doc/options.txt

   1 The definitition for each OPTIONS= option resides in include/optlist.h as of
   2 February 2020 in 3.7 WIP.
   3
   4 Boolean and compound options are combined into a single allopt[] array.
   5
   6 To add an entirely new option macro type:
   7
   8     The current list of option macros:
   9     NHOPTB (for boolean options)
  10     NHOPTC (for complex options that take values beyond off/on)
  11     NHOPTP (for handling a suite that all begin with a common prefix)
  12     NHOPTO (for other options not easily handled as one of the above)
  13
  14      1. You need to add three different expansions of your macro, one for
  15         the NHOPT_PROTO phase where function prototypes are generated,
  16         one for the NHOPT_ENUM phase where enums are generated, and
  17         NHOPT_PARSE phase.
  18
  19      2. If you are adding a new macro type to the current NHOPTB,
  20         NHOPTC, NHOPTP, NHOPTO macros, don't forget to add the #undef near
  21         the bottom of optlist.h, so that the macro is available for re-use
  22         during the next usage phase.
  23
  24  To add an option:
  25
  26      1. Add an entry to include/optlist.h, using the NHOPTB macro for a
  27        boolean on/off option, or NHOPTC macro for a complex option,
  28        or NHOPTP macro if it handles an entire prefix, or NHOPTO macro for
  29        other types.
  30
  31        The list of options is always kept in optlist.h in alphabetical order.
  32
  33        When the list of options is processed during the compile of options.c,
  34        the following will be automatically generated and included in
  35        options.c:
  36
  37             i) an optfn_xxxx function prototype (xxxx is the option name).
  38            ii) an opt_xxxx enum value for referencing that option index by
  39                name throughout options.c (xxxx is the option name).
  40           iii) an initialization of an element in the allopt[] array, at
  41                index opt_xxxx from step ii (xxxx is the option name).
  42
  43     2. Create the optfn_xxxx() function in options.c. Failure to do that will
  44        result in a link error of "undefined function optfn_xxxx." The functions are
  45        in options.c in alphabetical sequence by function name.
  46
  47        The skeletal template for an optn_xxxx() function is:
  48
  49             int
  50             optfn_xxxx(optidx, req, negated, opts, op)
  51             int optidx              /* the index of this option opt_xxxx */
  52             int req;                /* the request ID from core functions */
  53             boolean negated;        /* will be true if opt was negated */
  54             char *opts;             /* points to the complete opt string */
  55             char *op;               /* points to value portion of opt string */
  56             {
  57                 if (req == do_init) {
  58                     return optn_ok;
  59                 }
  60                 if (req == do_set) {
  61                     /* do option set processing for the option */
  62                     /* if successful, return optn_ok;    */
  63                     /* if unsuccessful, return optn_err; */
  64                 }
  65                 if (req == get_val) {
  66                     /* return the current val of option in supplied opts buf */
  67                     if (!opts)
  68                         return optn_err;
  69                     Sprintf(opts, "%s", fakefunction_to_get_xxxx_value_goes_here);
  70                     return optn_ok;
  71                 }
  72                 if (req == do_handler) {
  73
  74                     /* this is optional. If the option needs its own
  75                        special handling after the doset menu, do it here
  76                        or call a function to do it. The naming convention
  77                        for such a function in options.c has been
  78                        handler_xxxx(), but the function does not need to
  79                        reside in options.c */
  80
  81                     return optn_ok;
  82                 }
  83                 return optn_ok;
  84             }
  85
  86     3. NOTE:  If you add (or delete) an option, please update the short
  87        options help (option_help()), the long options help (dat/opthelp)
  88        and also the Guidebooks.
  89
  90 Here's some information about the req ID's passed to optfn_xxxx() functions.
  91 Each optfn_xxxx() function can be called with a req id of: do_init, do_set,
  92 do_handler or get_val.
  93
  94 req do_init is called from options_init, and if initialization or memory
  95 allocation or other initialization for that particular option is needed,
  96 it can be done in response to the init req
  97
  98 req do_set is called from parseoptions() for each option it encounters
  99 and the optfn_xxxx() function is expected to react and set the option
 100 based on the string values that parseoptions() passes to it.
 101
 102 req get_val is passed a buffer from its caller that the optfn_xxxx() is
 103 expected to fill with the current value of the option.
 104
 105 req do_handler is called during doset() operations processing in response
 106 to player selections, most likely from the 'O' option-setting menu. The
 107 do_handler req is only called for options that were marked as supporting
 108 do_handler in the option definition in include/optlist.h