2.2. Context manipulation

Parsing capabilities of libcfg+ library are accessed via context. It allows you to parse multiple configuration sets. For particular command lines and/or configuration files you can have different contexes. They are implemented like CFG_CONTEXT data type.

Here are functions used for creating context. Functions used for freeing (destroying) context are described at the end of this page.

#include <cfg+.h>

First function cfg_get_context() initializes context. Although it is initialized, it also needs to be set to one from the command line or configuration file type. Parameter options defines options set. Options set was described in previous chapter.

For full context initialization there are two functions cfg_get_cmdline_context() and cfg_get_cfgfile_context(). There are also functions cfg_set_cmdline_context() and cfg_set_cfgfile_context() for setting up already existing context. They have parameters with the same meanings as their equivalents with one difference that they are modifying already existing context and nothing returning. With these functions you can change type already existing context. So for example if you have finished parsing of command line and wanted to continue with configuration file parsing relating the same option set, just change your context type and parse.

Function cfg_get_cmdline_function() initializes context and sets it to command line. Parameter begin_pos tells starting position in dynamic array of command line arguments. Than parameter size defines number of arguments (array elements) to parse. If negative value is passed, it means infinite, so the parsing of command line will finish only if ending NULL is reached. Next parameter argv contain NULL terminated array of strings with these arguments. They can be passed just as they are passed to the main() function.

Function cfg_get_cfgfile_function() initializes context and sets it to configuration file. Parameter begin_pos tells starting position in file for parsing. Type of position, byte or line, depends on fact, if context flag CFG_FILE_LINE_POS_USAGE is set. By default they are expected as byte possition, but they can be changed to line position by this context flag. See Context flags section for more informations about this issue. But anyway, all position types are counted from 0. Next parameter size defines number of bytes or lines to parse. If negative value is passed, it means infinite, so the parsing of confing file will finish only if end of file is reached. Filename to parse is passed as the third filename parameter.

Please note, that these context creating and setting function are mentioned to be similar for both context types. That is the reason, why also command line context has parameter begin_pos, when is also possible to change beginning of array parsing by passing different pointer for the parameter argv. Also note, that all positions are counted from 0. For example third line of file is at position 2. Although this, standart libcfg+ error handling functions will already print human readable position, so for the first position on command line it will print something like "on position 1", for second line in config file it will print "on line 2" and so on.

From version 0.5.2 there is also cfg_get_cmdline_context_argc() function. It is used for context initialization by passing argc and argv parameters directly from main() function. It has similar parameters as cfg_get_cmdline_context(), but instead of begin_pos and size long parameters is only one argc integer parameter present. Of course, you can also use cfg_set_cmdline_context_argc() equivalent.

Another macros used for initialization are cfg_get_cmdline_context_pos() and cfg_get_cfgfile_context_pos(). They differ from their standart equivalent functions in parameter size, which is replaced by parameter end_pos. It defines the last element (array member, byte or line in file) which will be parsed. Also here you can use analogicaly cfg_set_cmdline_context_pos() and cfg_set_cfgfile_context_pos() macros.

Here are further functions. They are used for reseting and freeing context:

#include <cfg+.h>

There are often situations, that reseting of context is neccessary. In command line context type current position is returned to the beginning of command line arguments specified by parameter begin_pos. Similary in config file context type, position in file is set to begin_pos position. Context flags and context properties remains unchanged. For this purpose is cfg_reset_context() function provided.

After parsing of configuration options is complete, context should be freed. The last function cfg_free_context() frees passed CFG_CONTEXT structure. It will not frees allocated arguments or argument arrays set in any value member of your options set. But it will free all internal context structures including context flags and context properties, also with context itself.