DEVEL/code_features.txt

   1 $NHDT-Date: 1432473678 2015/05/24 13:21:18 $  $NHDT-Branch: master $:$NHDT-Revision: 1.2 $
   2 code_features.txt
   3
   4 Developer-useful info about code features, assumptions, purpose,
   5 rationale, etc.
   6
   7 ==============================================
   8 FEATURE_NOTICE Alerts for a Release
   9
  10 There is a code mechanism for alerting players to a change in behavior
  11 over prior versions of the game.
  12
  13 Here's how to do it:
  14    o Where the change in behavior needs to alert the player,
  15      - Add an 'if statement' to invoke the alert behavior
  16        if the condition is met, for example
  17           if (flags.suppress_alert < FEATURE_NOTICE_VER(3.6.0))
  18              pline("Note: and explain the change here.");
  19      - The example above will alert the users for a new feature
  20        added in 3.6.0 via a one-liner via pline(), but you
  21        could get more elaborate (just make sure it is all done
  22        in the 'if' code block..
  23
  24 Once the user finds the alert no longer useful, or becoming
  25 annoying, they can set the "suppress_alert" option.
  26       - The user can only set the suppress_alert to the current
  27         version, not future versions. That restriction is done
  28         so that the feature can be used for new things in new
  29         releases.
  30       - The suppression can be done interactively mid game with
  31         the 'O' command, or via
  32            OPTIONS=suppress_alert:3.6.0
  33         in the user's config file.
  34
  35 ==============================================
  36 PREFIXES_IN_USE and NOCWD_ASSUMPTIONS
  37
  38 Those provide a storage mechanism for holding the paths to various different
  39 types of files. Those paths are stored in the fqn_prefix[] array. They are a
  40 mechanism for enabling separation of the different files that NetHack needs.
  41
  42 The prefixes are added to the beginning of file names  by various routines in
  43 files.c immediately prior to opening one of the types of files that the game
  44 uses.
  45
  46 They aren't about config file options (although config file options would be
  47 one way to set non-default values for some of the paths in the fqn_prefix[]
  48 array). Obviously the very first path needed (now sysconfdir, previously
  49 configdir) isn't viable for setting via config file options, but the game
  50 still needs to hunt it down "someplace."  When the "someplace" is figured
  51 out, that place (path) would be stored in fqn_prefix[SYSCONPREFIX].  How it
  52 gets stored in fqn_prefix[SYSCONPREFIX] is up to us as developers.
  53
  54 Any of the fqn_prefix[] entries can be set somehow. It could be done in port
  55 startup code; in options processing; in config file processing; by
  56 translating a system environment variable such as USERPROFILE; whatever
  57 you/we want.  The point is that NOCWD_ASSUMPTIONS and PREFIXES_IN_USE are
  58 there to ensure that there is a place to store that path information.  The
  59 code to *utilize* the information is already in files.c (see fqname()).
  60
  61 There is a fqn_prefix[] entry for holding the path to each of the following:
  62     PREFIX        NAME
  63 0 HACKPREFIX     hackdir
  64 1 LEVELPREFIX    leveldir    location to create level files
  65 2 SAVEPREFIX     savedir location to create/read saved games
  66 3 BONESPREFIX    bonesir location to create/read bones
  67 4 DATAPREFIX     datadir location to read data.base etc.
  68 5 SCOREPREFIX    scoredir    location to read/write scorefile
  69 6 LOCKPREFIX     lockdir     location to create/read lock files
  70 7 SYSCONFPREFIX  sysconfdir  location to read SYSCF_FILE
  71 8 CONFIGPREFIX   configdir   location to read user configuration file
  72 9 TROUBLEPREFIX  troubledir  location to place panic files etc.
  73
  74 To recap, they are about enabling "different paths for different things", and
  75 separation of:
  76 - read-only stuff from read-write stuff.
  77 - sysadmin stuff from user-writeable stuff.
  78 etc.
  79
  80 ==============================================
  81 REGULAR EXPRESSIONS
  82
  83 There are multiple regular expression libraries supported. Currently, one (and
  84 only one) of the following files should be linked into a built:
  85   sys/share/cppregex.cpp
  86   sys/share/posixregex.c
  87   sys/share/pmatchregex.c
  88
  89 This provides a way to access different system regular expression libraries,
  90 or fall back onto pmatch() if none is available. cppregex.cpp uses the regular
  91 expression library in the C++11 standard, and is the default on Windows.
  92 posixregex.c uses the POSIX regular expression library, and is the default on
  93 POSIX. pmatchregex.c is the fallback.
  94
  95 Configuration files written using either of the two true regex engines are
  96 compatible with one another, as the regular expressions are both POSIX
  97 extended regular expressions. Configuration files written using the fallback
  98 engine are incompatible.
  99
 100 Additional regular expression implementations can be written. The full
 101 interface documentation is in sys/share/posixregex.c
 102
 103 =================== NEXT FEATURE ==========================
 104
 105
 106