doc/config-semantics

   1 $Id: config-semantics 4792 2001-06-21 08:59:39Z rra $
   2
   3 Groups in a configuration file have a well-defined order, namely the order
   4 in which the groups would be encountered in a depth-first traversal of the
   5 parse tree.
   6
   7 The supported operations on a configuration file parse tree for reading
   8 are:
   9
  10  * Search.  Find the first group of a given type in a given tree.  This is
  11    done via depth-first search.
  12
  13  * Next.  Find the next group of a given type, starting from some group.
  14    This is done via depth-first search.
  15
  16  * Query.  Look up the value of a given parameter in a given group (with
  17    inheritance).  Note that the expected type of the parameter value must
  18    be provided by the caller; the parsing library doesn't know the types
  19    of parameters.
  20
  21  * Prune.  Limit one's view of the configuration file to only a given set
  22    of group types and everything underneath them; any other group types
  23    encountered won't be parsed (and therefore everything under them, even
  24    groups of the wanted type, won't be seen).
  25
  26 Therefore, the *only* significance of nested group structure is parameter
  27 inheritence and pruning.  In the absence of pruning, it would always be
  28 possible, by duplicating parameter settings that were inherited and laying
  29 out the groups in depth-first traversal order, to transform any
  30 configuration file into an entirely equivalent one that contains no nested
  31 groups.  This isn't true in the presence of pruning, but pruning is
  32 intended to be used primarily for performance (ignoring the parts of the
  33 configuration that don't apply to a given parsing library client).
  34
  35 The expected way for clients to use the parsing library is to follow one
  36 of these two access patterns:
  37
  38  * Search for a particular configuration group and then query it for a set
  39    of parameters (either one by one as they're used, or all at once to
  40    collapse the parameters into a struct for faster access later).  This
  41    is expected to be the common pattern for finding and looking up
  42    settings for a particular program.  There will generally only be a
  43    single group per group type for groups of this sort; it doesn't make
  44    sense to have multiple groups setting general configuration options for
  45    a program and have to iterate through them and merge them in some
  46    fashion.
  47
  48  * Iterate through all groups of a given type, building a list of them (or
  49    of the data they contain).  This is the model used by, for example,
  50    storage classes; each storage class has a set of parameters, and the
  51    storage subsystem needs to know about the full list of classes.
  52
  53 Note that neither of these operations directly reveal the tree structure;
  54 the tree structure is intended for the convenience of the user in setting
  55 defaults for various parameters so that they don't have to be repeated in
  56 each group, and to allow some top-level pruning.  It's not intended to be
  57 semantically significant other than that.
  58
  59 Here are some suggested general conventions:
  60
  61  * General options for a particular program should be separated out into a
  62    their own group.  For example, a group innwatch in inn.conf to set the
  63    various options only used by innwatch.  Note that pruning is inclusive
  64    rather than exclusive, so programs should ideally only need to care
  65    about a short list of groups.
  66
  67  * Groups used only for grouping and setting default parameters, ones that
  68    won't be searched for explicitly by any program, should use the type
  69    "group".  This can be used uniformly in all configuration files so that
  70    whenever a user sees a group of type "group", they know that it's just
  71    syntactic convenience to avoid having to repeat a bunch of parameter
  72    settings and isn't otherwise significant.
  73
  74  * Groups that are searched for or iterated through shouldn't be nested;
  75    for example, if a configuration file defines a list of access groups,
  76    nesting one access group inside another is discouraged (in favor of
  77    putting both groups inside an enclosing group of type "group" that sets
  78    the parameters they have in common).  This is to cut down on user
  79    confusion, since otherwise the nesting appears to be significant.