chiark - git - mdw - fwd/blob - conf.h

   1 /* -*-c-*-
   2  *
   3  * $Id: conf.h,v 1.5 1999/10/22 22:46:44 mdw Exp $
   4  *
   5  * Configuration parsing
   6  *
   7  * (c) 1999 Straylight/Edgeware
   8  */
   9
  10 /*----- Licensing notice --------------------------------------------------*
  11  *
  12  * This file is part of the `fw' port forwarder.
  13  *
  14  * `fw' is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU General Public License as published by
  16  * the Free Software Foundation; either version 2 of the License, or
  17  * (at your option) any later version.
  18  *
  19  * `fw' is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  * GNU General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU General Public License
  25  * along with `fw'; if not, write to the Free Software Foundation,
  26  * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  27  */
  28
  29 /*----- Revision history --------------------------------------------------*
  30  *
  31  * $Log: conf.h,v $
  32  * Revision 1.5  1999/10/22 22:46:44  mdw
  33  * Improve documentation for conf_enum.
  34  *
  35  * Revision 1.4  1999/08/19 18:32:48  mdw
  36  * Improve lexical analysis.  In particular, `chmod' patterns don't have to
  37  * be quoted any more.
  38  *
  39  * Revision 1.3  1999/07/27 18:30:14  mdw
  40  * Improve documentation and layout for @CONF_BEGIN@ and friends.  Remove
  41  * irritating warning about unused label by introducing a spurious `goto'.
  42  *
  43  * Revision 1.2  1999/07/26 23:28:39  mdw
  44  * Major reconstruction work for new design.
  45  *
  46  * Revision 1.1.1.1  1999/07/01 08:56:23  mdw
  47  * Initial revision.
  48  *
  49  */
  50
  51 #ifndef CONF_H
  52 #define CONF_H
  53
  54 #ifdef __cplusplus
  55   extern "C" {
  56 #endif
  57
  58 /*----- Header files ------------------------------------------------------*/
  59
  60 #include <mLib/dstr.h>
  61
  62 #ifndef SCAN_H
  63 #  include "scan.h"
  64 #endif
  65
  66 /*----- Magic numbers -----------------------------------------------------*/
  67
  68 #define CTOK_EOF (-1)
  69 #define CTOK_WORD 256
  70
  71 /*----- Functions provided ------------------------------------------------*/
  72
  73 /* --- @undelim@ --- *
  74  *
  75  * Arguments:   @const char *d, dd@ = pointer to characters to escape
  76  *
  77  * Returns:     ---
  78  *
  79  * Use:         Modifies the tokenizer.  Characters in the first list will
  80  *              always be considered to begin a word.  Characters in the
  81  *              second list will always be allowed to continue a word.
  82  */
  83
  84 extern void undelim(const char */*d*/, const char */*dd*/);
  85
  86 /* --- @token@ --- *
  87  *
  88  * Arguments:   @scanner *sc@ = pointer to scanner definition
  89  *
  90  * Returns:     Type of token scanned.
  91  *
  92  * Use:         Reads the next token from the character scanner.
  93  */
  94
  95 extern int token(scanner */*sc*/);
  96
  97 /* --- @error@ --- *
  98  *
  99  * Arguments:   @scanner *sc@ = pointer to scanner definition
 100  *              @const char *msg@ = message skeleton string
 101  *              @...@ = extra arguments for the skeleton
 102  *
 103  * Returns:     Doesn't
 104  *
 105  * Use:         Reports an error at the current scanner location.
 106  */
 107
 108 extern void error(scanner */*sc*/, const char */*msg*/, ...);
 109
 110 /* --- @conf_enum@ --- *
 111  *
 112  * Arguments:   @scanner *sc@ = pointer to a scanner object
 113  *              @const char *list@ = comma-separated things to allow
 114  *              @unsigned @f = flags for the search
 115  *              @const char *err@ = error message if not found
 116  *
 117  * Returns:     Index into list, zero-based, or @-1@.
 118  *
 119  * Use:         Checks whether the current token is a string which matches
 120  *              one of the comma-separated items given.  The return value is
 121  *              the index (zero-based) of the matched string in the list.
 122  *
 123  *              The flags control the behaviour if no exact match is found.
 124  *              If @ENUM_ABBREV@ is set, and the current token is a left
 125  *              substring of exactly one of the possibilities, then that one
 126  *              is chosen.  If @ENUM_NONE@ is set, the value @-1@ is
 127  *              returned; otherwise an error is reported and the program is
 128  *              terminated.
 129  */
 130
 131 #define ENUM_ABBREV 1u
 132 #define ENUM_NONE 2u
 133
 134 extern int conf_enum(scanner */*sc*/, const char */*list*/,
 135                      unsigned /*flags*/, const char */*err*/);
 136
 137 /* --- @conf_prefix@ --- *
 138  *
 139  * Arguments:   @scanner *sc@ = pointer to a scanner object
 140  *              @const char *p@ = pointer to prefix string to check
 141  *
 142  * Returns:     Nonzero if the prefix matches.
 143  *
 144  * Use:         If the current token is a word matching the given prefix
 145  *              string, then it and an optional `.' character are removed and
 146  *              a nonzero result is returned.  Otherwise the current token is
 147  *              left as it is, and zero is returned.
 148  *
 149  *              Typical options parsing code would remove an expected prefix,
 150  *              scan an option anyway (since qualifying prefixes are
 151  *              optional) and if a match is found, claim the option.  If no
 152  *              match is found, and a prefix was stripped, then an error
 153  *              should be reported.
 154  */
 155
 156 extern int conf_prefix(scanner */*sc*/, const char */*p*/);
 157
 158 /* --- @CONF_BEGIN@, @CONF_END@ --- *
 159  *
 160  * Arguments:   @sc@ = scanner to read from
 161  *              @prefix@ = prefix to scan for
 162  *              @desc@ = description of what we're parsing
 163  *
 164  * Use:         Bracket an options parsing routine.  The current token is
 165  *              checked to see whether it matches the prefix.  If so, it is
 166  *              removed and the following token examined.  If that's a `.'
 167  *              then it's removed.  If it's a `{' then the enclosed
 168  *              option-parsing code is executed in a loop until a matching
 169  *              '}' is found.  If the options parser doesn't accept an
 170  *              option, the behaviour is dependent on whether a prefix was
 171  *              seen: if so, an error is reported; otherwse a zero return is
 172  *              made.
 173  */
 174
 175 #define CS_PLAIN 0
 176 #define CS_PREFIX 1
 177 #define CS_BRACE 2
 178 #define CS_UNKNOWN 3
 179
 180 #define CONF_BEGIN(sc, prefix, desc) do {                               \
 181   scanner *_conf_sc = (sc);                                             \
 182   const char *_conf_desc = (desc);                                      \
 183   int _conf_state = CS_PLAIN;                                           \
 184                                                                         \
 185   /* --- Read the initial prefix --- */                                 \
 186                                                                         \
 187   if (_conf_sc->t == CTOK_WORD &&                                       \
 188       strcmp(_conf_sc->d.buf, (prefix)) == 0) {                         \
 189     token(_conf_sc);                                                    \
 190     _conf_state = CS_PREFIX;                                            \
 191     if (_conf_sc->t == '.')                                             \
 192       token(_conf_sc);                                                  \
 193     else if (_conf_sc->t == '{') {                                      \
 194       token(_conf_sc);                                                  \
 195       _conf_state = CS_BRACE;                                           \
 196     }                                                                   \
 197   }                                                                     \
 198                                                                         \
 199   /* --- Ensure the next token is a word --- */                         \
 200                                                                         \
 201   if (_conf_sc->t != CTOK_WORD)                                         \
 202     error(_conf_sc, "parse error, expected option keyword");            \
 203   do {
 204
 205 #define CONF_END                                                        \
 206                                                                         \
 207     /* --- Reject an option --- *                                       \
 208      *                                                                  \
 209      * We could get here as a result of an explicit @CONF_REJECT@ or    \
 210      * because the option wasn't accepted.                              \
 211      */                                                                 \
 212                                                                         \
 213      goto _conf_reject;                                                 \
 214   _conf_reject:                                                         \
 215     if (_conf_state == CS_PLAIN)                                        \
 216       _conf_state = CS_UNKNOWN;                                         \
 217     else {                                                              \
 218       error(_conf_sc, "unknown %s option `%s'",                         \
 219             _conf_desc, _conf_sc->d.buf);                               \
 220     }                                                                   \
 221                                                                         \
 222     /* --- Accept an option --- *                                       \
 223      *                                                                  \
 224      * It's safe to drop through from above.  Either an error will have \
 225      * been reported, or the state is not @CS_BRACE@.                   \
 226      */                                                                 \
 227                                                                         \
 228   _conf_accept:                                                         \
 229     if (_conf_state == CS_BRACE && _conf_sc->t == ';')                  \
 230       token(_conf_sc);                                                  \
 231   } while (_conf_state == CS_BRACE && _conf_sc->t == CTOK_WORD);        \
 232                                                                         \
 233   /* --- Check for a closing brace --- */                               \
 234                                                                         \
 235   if (_conf_state == CS_BRACE) {                                        \
 236     if (_conf_sc->t == '}')                                             \
 237       token(_conf_sc);                                                  \
 238     else                                                                \
 239       error(_conf_sc, "parse error, expected `}'");                     \
 240   }                                                                     \
 241                                                                         \
 242   /* --- Return an appropriate value --- */                             \
 243                                                                         \
 244   return (_conf_state != CS_UNKNOWN);                                   \
 245 } while (0)
 246
 247 /* --- @CONF_ACCEPT@, @CONF_REJECT@ --- *
 248  *
 249  * Arguments:   ---
 250  *
 251  * Use:         Within an options parser (between @CONF_BEGIN@ and
 252  *              @CONF_END@), accept or reject an option.
 253  */
 254
 255 #define CONF_ACCEPT goto _conf_accept
 256 #define CONF_REJECT goto _conf_reject
 257
 258 /* --- @CONF_QUAL@ --- *
 259  *
 260  * Arguments:   ---
 261  *
 262  * Use:         Evaluates to a nonzero value if the current option is
 263  *              qualified.  This can be used to decide whether abbreviations
 264  *              for options should be accepted.
 265  */
 266
 267 #define CONF_QUAL (_conf_state != CS_PLAIN)
 268
 269 /* --- @conf_name@ --- *
 270  *
 271  * Arguments:   @scanner *sc@ = pointer to scanner
 272  *              @char delim@ = delimiter character to look for
 273  *              @dstr *d@ = pointer to dynamic string for output
 274  *
 275  * Returns:     ---
 276  *
 277  * Use:         Reads in a compound name consisting of words separated by
 278  *              delimiters.  Leading and trailing delimiters are permitted,
 279  *              although they'll probably cause confusion if used.  The name
 280  *              may be enclosed in square brackets if that helps at all.
 281  *
 282  *              Examples of compound names are filenames (delimited by `/')
 283  *              and IP addresses (delimited by `.').
 284  */
 285
 286 extern void conf_name(scanner */*sc*/, char /*delim*/, dstr */*d*/);
 287
 288 /* --- @conf_parse@ --- *
 289  *
 290  * Arguments:   @scanner *sc@ = pointer to a scanner structure
 291  *
 292  * Returns:     ---
 293  *
 294  * Use:         Parses a configuration file fragment from the scanner
 295  */
 296
 297 extern void conf_parse(scanner *sc);
 298
 299 /*----- That's all, folks -------------------------------------------------*/
 300
 301 #ifdef __cplusplus
 302   }
 303 #endif
 304
 305 #endif