"SfR Fresh" - the SfR Freeware/Shareware Archive

Member "inn-2.4.5/doc/config-design" of archive inn-2.4.5.tar.gz:

    1 $Id: config-design 4805 2001-06-21 10:52:27Z rra $
    2 
    3 This file is documentation of the design principles that went into INN's
    4 configuration file syntax, and some rationale for why those principles
    5 were chosen.
    6 
    7  1.  All configuration files used by INN should have the same syntax.
    8      This was the root reason why the project was taken on in the first
    9      place; INN developed a proliferation of configuration files, all of
   10      which had a slightly (or greatly) different syntax, forcing the
   11      administrator to learn several different syntaxes and resulting in a
   12      proliferation of parsers, all with their own little quirks.
   13 
   14  2.  Adding a new configuration file or a new set of configuration options
   15      should not require writing a single line of code for syntax parsing.
   16      Code that analyzes the semantics of the configuration will of course
   17      be necessary, but absolutely no additional code to read files, parse
   18      files, build configuration trees, or the like should be required.
   19      Ideally, INN should have a single configuration parser that
   20      everything uses.
   21 
   22  3.  The syntax should look basically like the syntax of readers.conf,
   23      incoming.conf, and innfeed.conf in INN 2.3.  After extensive
   24      discussion on the inn-workers mailing list, this seemed to be the
   25      most generally popular syntax of the ones already used in INN, and
   26      inventing a completely new syntax didn't appear likely to have gains
   27      outweighing the effort involved.  This syntax seemed sufficiently
   28      general to represent all of the configuration information that INN
   29      needed.
   30 
   31  4.  The parsing layer should *not* attempt to do semantic analysis of the
   32      configuration; it should concern itself solely with syntax (or very
   33      low-level semantics that are standard across all conceivable INN
   34      configuration files).  In particular, the parsing layer should not
   35      know what parameters are valid, what groups are permitted, what types
   36      the values for parameters should have, or what default values
   37      parameters have.
   38 
   39      This principle requires some additional explanation, since it is very
   40      tempting to not do things this way.  However, the more semantic
   41      information the parser is aware of, the less general the parser is,
   42      and it's very easy to paint oneself into a corner.  In particular,
   43      it's *not* a valid assumption that all clients of the parsing code
   44      will want to reduce the configuration to a bunch of structs; this
   45      happens to be true for most clients of inn.conf, for example, but
   46      inndstart doesn't want the code needed to reduce everything to a
   47      struct and set default values to necessarily be executed in a
   48      security-critical context.
   49 
   50      Additionally, making the parser know more semantic information either
   51      complicates (significantly) the parser interface or means that the
   52      parser has to be modified when the semantics change.  The latter is
   53      not acceptable, and the parser interface should be as straightforward
   54      as possible (to encourage all parts of INN to use it).
   55 
   56  5.  The result of a parse of the configuration file may be represented as
   57      a tree of dictionaries, where each dictionary corresponds to a group
   58      and each key corresponds to a parameter setting.  (Note that this does
   59      not assume that the underlying data structure is a hash table, just
   60      that it has dictionary semantics, namely a collection of key/value
   61      pairs with the keys presumed unique.)
   62 
   63  6.  Parameter values inherit via group nesting.  In other words, if a
   64      group is nested inside another group, all parameters defined in the
   65      enclosing group are inherited by the nested group unless they're
   66      explicitly overriden within the nested group.  (This point and point
   67      5 are to some degree just corollaries of point 3.)
   68 
   69  7.  The parsing library must permit writing as well as reading.  It must
   70      be possible for a program to read in a configuration file, modify
   71      parameters, add and delete groups, and otherwise change the
   72      configuration, and then write back out to disk a configuration file
   73      that preserves those changes and still remains as faithful to the
   74      original (possibly human-written) configuration file as possible.
   75      (Ideally, this would extend to preserving comments, but that may be
   76      too difficult to do and therefore isn't required.)
   77 
   78  8.  The parser must not limit the configuration arbitrarily.  In
   79      particular, unlimited length strings (within available memory) must
   80      be supported for string values, and if allowable line length is
   81      limited, line continuation must be supported everywhere that there's
   82      any reasonable expectation that it might be necessary.  One common
   83      configuration parameter is a list of hosts or host wildmats that can
   84      be almost arbitrarily long, and the syntax and parser must support
   85      that.
   86 
   87  9.  The parser should be reasonably efficient, enough so as to not cause
   88      an annoying wait for command-line tools like sm and grephistory to
   89      start.  In general, though, efficiency in either time or memory is
   90      not as high of a priority as readable, straightforward code; it's
   91      safe to assume that configuration parsing is only done on startup and
   92      at rare intervals and is not on any critical speed paths.
   93 
   94 10.  Error reporting is a must.  It must be possible to clearly report
   95      errors in the configuration files, including at minimum the file name
   96      and line number where the error occurred.
   97 
   98 11.  The configuration parser should not trust its input, syntax-wise.  It
   99      must not segfault, infinitely loop, or otherwise explode on malformed
  100      or broken input.  And, as a related point, it's better to be
  101      aggressively picky about syntax than to be lax and attempt to accept
  102      minor violations.  The intended configuration syntax is simple and
  103      unambiguous, so it should be unnecessary to accept violations.
  104 
  105 12.  It must be possible to do comprehensive semantic checks of a
  106      configuration file, including verifying that all provided parameters
  107      are known ones, all parameter values have the correct type, group
  108      types that are not expected to be repeated are not, and only expected
  109      group types are used.  This must *not* be done by the parser, but the
  110      parser must provide sufficient hooks that the client program can do
  111      this if it chooses.
  112 
  113 13.  The parser must be re-entrant and thread-safe.
  114 
  115 14.  The grammar shouldn't require any lookahead to parse.  This is in
  116      order to keep the parser extremely simple and therefore maintainable.
  117      (It's worth noting that this design principle leads to the
  118      requirement that parameter keys end in a colon; the presence of the
  119      colon allows parameter keys to be distinguished from other syntactic
  120      elements allowed in the same scope, like the beginning of a nested
  121      group.)