Config parsing (4/4): Proposed starting interface

[Aidan Cully]

On Thu, May 10, 2001 at 09:46:21AM, Russ Allbery said:
> 
> (Note that this doesn't yet deal with writing configuration files, only
> reading them.  Writing hasn't been forgotten, though.)

How does one verify syntax using this API?  E.g., make sure that the
user didn't stick some garbage parameter name into the file?

--aidan

> /*  $Id$
> **
> **  Configuration file parsing interface.
> */
> 
> #ifndef INN_CONFPARSE_H
> #define INN_CONFPARSE_H 1
> 
> #include <inn/defines.h>
> 
> /* Avoid including <inn/vector.h> unless the client needs it. */
> struct vector;
> 
> /* The opaque data type representing a configuration tree. */
> struct config_group_s;
> typedef struct config_group_s *config_group;
> 
> BEGIN_DECLS
> 
> /* Parse the given file and build a configuration tree.  This does purely
>    syntactic parsing; no semantic checking is done.  After the file name, a
>    NULL-terminated list of const char * pointers should be given, naming the
>    top-level group types that the caller is interested in.  If none are given
>    (if the second argument is NULL), the entire file is parsed.  (This is
>    purely for efficiency reasons; if one doesn't care about speed, everything
>    will work the same if no types are given.)
> 
>    Returns a config_group for the top-level group representing the entire
>    file.  Generally one never wants to query parameters in this group;
>    instead, the client should then call config_find_group for the group type
>    of interest.  Returns NULL on failure to read the file or on a parse
>    failure; errors are reported via warn. */
> config_group config_parse_file(const char *file, /* types */ ...);
> 
> /* config_find_group returns the first group of the given type found in the
>    tree rooted at its argument.  config_next_group returns the next group in
>    the tree of the same type as the given group (or NULL if none is found).
>    This can be used to do such things as enumerate all "peer" groups in a
>    configuration file. */
> config_group config_find_group(config_group, const char *type);
> config_group config_next_group(config_group);
> 
> /* Accessor functions for group information. */
> const char *config_group_type(config_group);
> const char *config_group_tag(config_group);
> 
> /* Look up a parameter in a given config tree.  The second argument is the
>    name of the parameter, and the result will be stored in the third argument
>    if the function returns true.  If it returns false, the third argument is
>    unchanged and that parameter wasn't set (or was set to an invalid value for
>    the expected type). */
> bool config_param_boolean(config_group, const char *, bool *);
> bool config_param_integer(config_group, const char *, long *);
> bool config_param_real(config_group, const char *, double *);
> bool config_param_string(config_group, const char *, const char **);
> bool config_param_list(config_group, const char *, struct vector *);
> 
> /* Free all space allocated by the tree rooted at config_group.  One normally
>    never wants to do this.  WARNING: This includes the storage allocated for
>    all strings returned by config_param_string and config_param_list for any
>    configuration groups in this tree. */
> void config_free(config_group);
> 
> END_DECLS
> 
> #endif /* INN_CONFPARSE_H */
> 
> -- 
> Russ Allbery (rra at stanford.edu)             <http://www.eyrie.org/~eagle/>

-- 
Aidan Cully       "Hooray!!!"
Not Panix Staff      -- Pokey the Penguin
aidan at panix.com