chiark / gitweb /
wip filepoll poll interval variable
[innduct.git] / 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.