From: <enl...@li...> - 2003-03-17 21:28:46
|
Enlightenment CVS committal Author : mej Project : eterm Module : libast Dir : eterm/libast/src Modified Files: conf.c debug.c Log Message: Mon Mar 17 16:27:53 2003 Michael Jennings (mej) More work on docs. =================================================================== RCS file: /cvsroot/enlightenment/eterm/libast/src/conf.c,v retrieving revision 1.9 retrieving revision 1.10 diff -u -3 -r1.9 -r1.10 --- conf.c 8 Mar 2003 04:52:56 -0000 1.9 +++ conf.c 17 Mar 2003 21:28:13 -0000 1.10 @@ -31,7 +31,7 @@ * @author Michael Jennings <me...@et...> */ -static const char cvs_ident[] = "$Id: conf.c,v 1.9 2003/03/08 04:52:56 mej Exp $"; +static const char cvs_ident[] = "$Id: conf.c,v 1.10 2003/03/17 21:28:13 mej Exp $"; #ifdef HAVE_CONFIG_H # include <config.h> @@ -974,7 +974,7 @@ /** * @example conf_example.c - * Example code for using the string routines. + * Example code for using the config file parser. * */ @@ -992,13 +992,105 @@ * LibAST's config file parser supports the inclusion of sub-files via * its %include directive, it must keep track of multiple instances of * this information, one for each file. LibAST uses a structure array - * called the File State Stack. + * called the file state stack. + * + * When config file parsing is initiated by a call to conf_parse(), + * the information for that file is pushed onto the empty stack. For + * monolithic config files, the stack retains its height throughout + * the parsing cycle. However, if an @c %include directive is + * encountered (and the file is successfully opened), a new set of + * data is placed atop the stack via file_push(). The new file is + * then parsed in its entirety, including any sub-files that it may + * itself include, before its information is popped off the stack and + * parsing of the original file can continue. + * + * Client programs should not need to modify the stack in any way. + * However, use of the file_peek_path() and file_peek_line() macros + * are encouraged, specifically for printing error/warning messages. + * Many of the file state stack manipulation routines should probably + * never be called by client programs (and are therefore marked as + * internal); they are, however, made available on the off chance that + * someone may get super-creative and do something neat with them. + * Just don't blame LibAST if your (ab)use of internal functions + * breaks the parser! */ /** * @defgroup DOXGRP_CONF_CTX Context Handling * @ingroup DOXGRP_CONF * + * LibAST-style configuration files are organized into logical units + * called "contexts." A begin/end pair is used to surround groups of + * directives which should be evaluated in a given context. The begin + * keyword is followed by the name of the context that will follow. + * The end keyword may stand alone; anything after it is ignored. + * + * The parser starts out in a pseudo-context called @c null for which + * LibAST employs a built-in handler that rejects any unexpected + * directives with an error message. Any other context must be dealt + * with by a client-specified context handler. + * + * Context handlers defined by the client program must conform to the + * following specification: + * - Accept two parameters as follows: + * -# A char * containing the line of text to be parsed + * -# A void * containing optional state information, or NULL + * - Return a void * containing optional state information, or NULL + * + * Although nothing else is strictly @em required by LibAST, if you + * want your parser to actually work, it needs to handle the LibAST + * context handler calling conventions. The following is a + * step-by-step walk-through of how LibAST calls parser functions: + * + * -# When LibAST encounters a @c begin keyword followed by a one or + * more additional words (words are separated by whitespace + * according to shell conventions), the word immediately following + * the @c begin keyword is interpreted as the context name. + * -# LibAST checks its list of registered context handlers for one + * that matches the given context name. If none is found, an error + * is printed, and the parser skips the entire context (until the + * next @c end keyword). Otherwise, go to the next step. + * -# The registered context handler function is called. The value + * #CONF_BEGIN_STRING is passed as the first parameter (which I'll + * call @a buff ), and NULL is passed as the second parameter + * (which I'll call @a state ). + * -# The context handler should handle this using a statement similar + * to the following: + * @code + * if (*buff == CONF_BEGIN_CHAR) { + * @endcode + * (The value of #CONF_BEGIN_CHAR is such that it should never + * occur in normal config file text.) + * If the handler does not require any persistent state information + * to be kept between calls, it may simply return NULL here. + * Otherwise, this portion of the handler should perform any + * initialization required for the state information and return a + * pointer to that information. + * -# The value returned by the context handler is stored by LibAST + * for later use, and parsing of the config file continues with the + * next line. + * -# Each subsequent line encountered in the config file which does + * not start with the keyword @c end is passed to the context + * handler function as the first parameter. The second parameter + * will contain the handler's previous return value, the persistent + * state information pointer. The handler, of course, should + * continue returning the state information pointer. + * -# Once the @c end keyword is encountered, the context handler is + * called with #CONF_END_STRING as the first parameter and the + * state information pointer as the second parameter. This + * situation should be caught by some code like this: + * @code + * if (*buff == CONF_END_CHAR) { + * @endcode + * Again, the handler should simply return NULL if no state + * information is being kept. Otherwise, any post-processing or + * cleanup needed should be done, possibly including the freeing of + * the state pointer, etc. The handler should then return NULL. + * -# LibAST reverts to the aforementioned @c null context and + * continues parsing as above. * + * A sample implementation of context handlers which demonstrate use + * of this mechanism can be found in the @link conf_example.c config + * file parser example @endlink. */ =================================================================== RCS file: /cvsroot/enlightenment/eterm/libast/src/debug.c,v retrieving revision 1.4 retrieving revision 1.5 diff -u -3 -r1.4 -r1.5 --- debug.c 24 Feb 2003 03:03:20 -0000 1.4 +++ debug.c 17 Mar 2003 21:28:15 -0000 1.5 @@ -30,7 +30,7 @@ * @author Michael Jennings <me...@et...> */ -static const char cvs_ident[] = "$Id: debug.c,v 1.4 2003/02/24 03:03:20 mej Exp $"; +static const char cvs_ident[] = "$Id: debug.c,v 1.5 2003/03/17 21:28:15 mej Exp $"; #ifdef HAVE_CONFIG_H # include <config.h> @@ -143,13 +143,20 @@ * the following pages of goop, hopefully you'll learn about the * miscellaneous mounds of spiffitude which await you in LibAST! * - * Use the document tree to your left, or the quick links above, to - * navigate. Or if you prefer, select from the list of topics below. + * Choose a section from the list below, or pick one of the quick + * links at the top of the page. If you prefer tree-style navigation, + * there is a hidden frame on the left-hand side of your browser + * window. You can expand this frame to find the document tree + * (requires JavaScript!). * * @section topiclist Topic List * * -# @link DOXGRP_DEBUG Debugging Subsystem @endlink * -# @link DOXGRP_MEM Memory Management Subsystem @endlink * -# @link DOXGRP_STRINGS String Utility Routines @endlink + * -# @link DOXGRP_CONF Configuration File Parser @endlink + * -# @link DOXGRP_CONF_FSS File State Stack @endlink + * -# @link DOXGRP_CONF_CTX Context Handling @endlink + * -# @link DOXGRP_OPT Command Line Option Parser @endlink * */ |