dot.conf API description ===================================================================== 1. dot.conf types --------------------------------------------------------------------- 1.0. typedefs 1.1. constants 1.2. macros 1.3. structures 1.3.1. configfile_t 1.3.2. configoption_t 1.3.3. command_t The API is built around the main data structures configfile_t configoption_t and command_t Two other types are context_t and info_t, but these are only typedefs from void! configfile_t is the dotconf 'session' structure building the glue between the various API parts. It stores things like the stream, current filename or the line currently read. When using dot.conf the first thing for the programmer to do is to receive a valid configfile_t structure with the ->dotconf_create API call. 1.0. dot.conf's typedefs ============================== typedef void context_t; typedef void info_t; typedef const char *(*dotconf_callback_t)(command_t *, context_t *); ^^^^^^^^^^^^^^^^^^ the type of function called for each encountered command typedef int (*dotconf_errorhandler_t)(configfile_t *, int, ^^^^^^^^^^^^^^^^^^^^^^ unsigned long, const char *); the type of the errorhandler callback typedef const char *(*dotconf_contextchecker_t)(command_t *, unsigned long); ^^^^^^^^^^^^^^^^^^^^^^^^ the type of the contextchecker 1.1. dot.conf's constants ============================== CFG_BUFSIZE 4096 max length of one line CFG_MAX_OPTION 32 max length of an option name CFG_MAX_VALUE 4064 max length of an options value CFG_MAX_FILENAME 256 max length of a filename (used when Include'ing) CFG_VALUES 16 max # of parameters an option can take. if an options gets more than CFG_VALUES parameters, the last one holds the complete remaining unparsed string is passed in list[CFG_VALUES-1]. CFG_INCLUDEPATH_ENV "DC_INCLUDEPATH" the name of the environment variable used to find the search path for Include'ed files. 1.2. dot.conf's macros ============================== DOTCONF_CB(__name) conveniently declare / define a callback function. FUNC_ERRORHANDLER(__name) conveniently declare / define the errorhandler callback 1.3.1. configfile_t ============================== FILE *stream the stream opened by dotconf_create. this field should only be used by dotconf_get_next_line for reading char eof eof is set to one as soon as the END OF FILE has been reached. size_t size this field is only used if there was a here-document to be handled. for here-documents dotconf allocates as much memory as the filesize. The result of the necessary stat() call is cached in this field. Do never rely on the value of this field!! context_t *context the application's pointer to the context memory block. this field is set by dotconf_create, and used to fill in the corresponding field of the command_t when calling a command's callback configoption_t const **config_options a list of configuration options dotconf's dotconf_handle_command can understand. Never write to this field yourself, use dotconf_register_command to handle this for you. int config_option_count the number of modules that registered their options including dotconf's internal options and the core options of the app as given to dotconf_create. char *filename the name of the configuration file unsigned long line the line pointer in the file currently parsed unsigned long flags the run-time flags as passed to dotconf_create. this value can be changed at run-time to have dot.conf act different at different stages of the configuration file (i.e. switch case (in)sensitive matching) char *includepath the include-path for dot.conf's internal 'Include' option. This field is set by dotconf_create to one of these possibilities in order: - If the variable named by CFG_INCLUDEPATH_ENV is set in the environment, includepath is set to the value of that variable. - If the name of the configuration file passed to dotconf_create contains a fully qualified path, includepath is set to that path without the file name. - If the name of the configuration file passed to dotconf_create contains a relative path, includepath is set to the fullly qualified path where the configuration file is stored without the configuration file name. - Otherwise, includepath is not set. dotconf_errorhandler_t errorhandler the errorhandler of the app; after creating your configfile_t set this field to your errorhandler function or leave it as NULL dotconf_contextchecker_t contextchecker the contextchecker is responsible for telling dot.conf whether a command is valid in the current context. this callback is useful if you create several container commands that behave different according to their nesting (see Apache's Files, Directory and VirtualHost). int (*cmp_func)(const char *, const char *, size_t) the function used to compare the first word of a buffer line with all commands registered in config_options. this will be set by the core to be strncmp or strncasecmp depending on the matching type you chose via the flags. again, changing this at any point during the parsing will have an immediate effect. 1.3.2. configoption_t ============================== const char *name the name of the configuration option dot.conf should understand int type the type of the data your app expects. possible values are: ARG_NONE - your app does not expect any args; dot.conf will not parse any args even if some were given. ARG_RAW - unparsed string with whatever was on the line line continuation has been handled, environment variable substitution not. ARG_STR - the first argument (i.e. anything up to the first unquoted, unescaped whitespace character ARG_INT - like ARG_STR, but atoi() is called on the value found ARG_TOGGLE - your app gets 0 for off, and 1 for on; recognized values are On/Off, 1/0, Yes/No ARG_LIST - the application expects several ARG_STRs in a char **list. ARG_NAME - fallback to catch unknown commands. This is for instance especially useful to parse files like Apache's mime.types. If an ARG_NAME is given as the last item of the command table, dot.conf handles the commands as known, and does everything it would have done for an ARG_LIST option. Note: Modules cannot install an ARG_NAME handler. That is the sole right of the core application code. dotconf_callback_t callback the function to be called if the given command name is encountered info_t *info additional info for the callback to operate with unsigned long context the context flag; this will be passed to the apps configchecker 1.3.3. command_t ============================== const char *name the name of the configuration option as in the app's command table. for ARG_NAME type options this is the name of the unmatched/unknown command. configoption_t *option a pointer to the full entry of the command table that corresponds to the current option struct { long value; char *str; char **list; double dvalue; } data the data found when parsing. data.value - this is used for ARG_INT and ARG_TOGGLE options data.str - is only used for ARG_STR type options data.list - list is filled for ARG_LIST and ARG_NAME options data.list is terminated by a NULL entry data.dvalue - this is used for ARG_DOUBLE options int arg_count only set for ARG_LIST items; this is set to the number of items in data.list. the last item of the list is data.list[arg_count-1]. configfile_t *configfile the dot.conf session currently active context_t *context the context pointer you passed to dotconf_create when generating your configfile_t *. 2. Function Reference --------------------------------------------------------------------- 2.1. dotconf_create 2.2. dotconf_cleanup 2.3. dotconf_register_options 2.4. dotconf_command_loop 2.5. dotconf_command_loop_until_error 2.6. dotconf_get_next_line 2.7. dotconf_handle_command 2.8. dotconf_warning 2.1. dotconf_create ============================== configfile_t *dotconf_create(char *filename, const configoption_t *options, context_t *context, unsigned long flags); description: dotconf_create returns a pointer to a configfile_t structure after initializing it. The values you pass are stored in it for future reference. parameters: char *filename the filename of the configuration file you want to parse in this session. The filename is only read by dot.conf. const configoption_t *options this parameter lets dot.conf know about the commands you want it to understand. The configoption_t's tell dot.conf which of your callbacks is responsible for a specific command. context_t *context in context you can pass a pointer to the structure holding anything necessary to keep a context when parsing. This pointer is passed to your command callbacks as a field in command_t, so you can access it at any time. unsigned long flags this parameters sets the runtime flags to consider when parsing. This controls important core functionality. Possible flags are : NONE : no flags (0) CASE_INSENSITIVE : match option names case insensitive DONT_SUBSTITUTE : do not call substitute_env after read_arg NO_INLINE_COMMENTS : do not stop parsing arguments after a #-sign on a line DUPLICATE_OPTION_NAMES : allow for duplicate option names in different contexts The first one without an error from the contextchecker is used. return value: configfile_t * the dot.conf session structure, which is to be used in every call to another dot.conf API function. NULL is returned in case of a failure sideeffects: the returned configfile_t* is malloc()ed, and the field 'stream' is fopen()ed. Do not clean this by hand, but use dotconf_cleanup instead. 2.2. dotconf_cleanup ============================== void dotconf_cleanup(configfile_t *configfile); description: dotconf_cleanup cleans up behind whatever dotconf_create and friends did to and with the configfile_t* that is given as the argument. parameters: configfile_t *configfile the dot.conf session structure as returned by dotconf_create. return value: void 2.3. dotconf_register_options ============================== int dotconf_register_options(configfile_t *configfile, const configoption_t *options); description: this function registers additional known configuration commands at runtime. the next time dot.conf needs to match an option, these newly registered options are taken into account. parameters: configfile_t *configfile the dot.conf session structure as returned by dotconf_create const configoption_t *options this parameter lets dot.conf know about the commands you want it to understand. The configoption_t's tell dot.conf which of your callbacks is responsible for a specific command. return value: int dotconf_register_options returns non-zero on success and zero on failure. The only possible failure condition is the failure to allocate memory. If the function fails, configfile is untouched. 2.4. dotconf_command_loop ============================== int dotconf_command_loop(configfile_t *configfile); description: this function iterates through all lines of the configuration file passing the buffer filled by dotconf_get_next_line to dotconf_handle_command. On error dotconf_command_loop calls dotconf_warning. parameters: configfile_t *configfile the dot.conf session structure as returned by dotconf_create return value: int dotconf_command_loop returns zero on failure and non-zero for success. success means, that the parsing is done now. 2.5. dotconf_command_loop_until_error ============================== const char *dotconf_command_loop_until_error(configfile_t *configfile); description: this function iterates through all lines of the configuration file passing the buffer filled by dotconf_get_next_line to dotconf_handle_command. On error this function exits returning the error. parameters: configfile_t *configfile the dot.conf session structure as returned by dotconf_create return value: const char * dotconf_command_loop_until error returns the first error it stumbles over or NULL if everything went fine 2.6. dotconf_get_next_line ============================== int dotconf_get_next_line(char *buffer, size_t bufsize, configfile_t *configfile); description: this function reads the next line from the configfile, increments line counter, and handles the line continuation. parameters: char *buffer the buffer where the line should be written to size_t bufsize the size of the buffer configfile_t *configfile the dot.conf session structure as returned by dotconf_create return value: int zero indicates success, and non-zero means that some error occurred 2.7. dotconf_handle_command ============================== const char *dotconf_handle_command(configfile_t *configfile, char *buffer); description: handles commands. This function further parses the line buffer and tries to match up the first word found as the command. If the command exists it parses all commands arguments and stuffs them into a command_t structure. Where appropriate here-documents or quotings are handled, and the environment variable substitution is tried on every ARG_STR / ARG_LIST command argument except here-documents. parameters: configfile_t *configfile the dot.conf session structure as returned by dotconf_create char *buffer the buffer as filled by dotconf_get_next_line return value: const char * the error message as returned by the command callbacks for instance; NULL if everything went ok. 2.8. dotconf_warning ============================== int dotconf_warning(configfile_t *configfile, int type, unsigned long errnum, const char *fmt, ...); description: dotconf_warning is responsible for dispatching any messages either through the internal handler (i.e. fprintf) or through the app's errorhandler. parameters: configfile_t *configfile the dot.conf session structure as returned by dotconf_create int type type of the message; analogous to syslog-style types: DCLOG_EMERG, DCLOG_ALERT, DCLOG_CRIT, DCLOG_ERR, DCLOG_WARNING, DCLOG_NOTICE, DCLOG_INFO, DCLOG_DEBUG unsigned long errnum the error number. this is up to the app what values to put here. I suggest using numbers above ERR_USER for own error numbers to not be conflicting with dotconf's internal error numbers. const char *fmt, ... a printf style message format. the message will be prepared via vsnprintf before passing it to your errorhandler. return value: int the value returned here affects how dotconf_command_loop reacts to errors. a value of zero, which is returned by the internal handler, will make the command loop to read on. non-zero tells the loop to immediately exit after printing the error.