Opensource.Platon.SK CVS: libcfg+/doc/sgml/usage.context-manipulation.sgml - diff

Up to [Platon] / libcfg+ / doc / sgml

Diff for libcfg+/doc/sgml/usage.context-manipulation.sgml between version 1.2 and 1.3

version 1.2, 2002/05/20 16:10:24

version 1.3, 2002/07/16 22:31:15

Line 9 Parsing capabilities of &name; library a

<firstterm>context</firstterm>. 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

<structname>CFG_CONTEXT</structname> structure.

<structname>CFG_CONTEXT</structname> data type.

</para>

<para>

Line 26 Here are methods used for creating and m

<funcdef>CFG_CONTEXT <function>cfg_get_cmdline_context</function></funcdef>

<paramdef>long <parameter>begin_pos</parameter></paramdef>

<paramdef>struct cfg_option <parameter>options</parameter></paramdef>

</funcprototype>

Line 34 Here are methods used for creating and m

Line 35 Here are methods used for creating and m

<funcdef>CFG_CONTEXT <function>cfg_get_cfgfile_context</function></funcdef>

<paramdef>long <parameter>begin_pos</parameter></paramdef>

<paramdef>char <parameter>*filename</parameter></paramdef>

<paramdef>struct cfg_option <parameter>options</parameter></paramdef>

</funcprototype>

Line 42 Here are methods used for creating and m

Line 43 Here are methods used for creating and m

<funcdef>void <function>cfg_set_cmdline_context</function></funcdef>

<paramdef>CFG_CONTEXT <parameter>con</parameter></paramdef>

<paramdef>long <parameter>begin_pos</parameter></paramdef>

</funcprototype>

Line 50 Here are methods used for creating and m

Line 52 Here are methods used for creating and m

<funcdef>void <function>cfg_set_cfgfile_context</function></funcdef>

<paramdef>CFG_CONTEXT <parameter>con</parameter></paramdef>

<paramdef>long <parameter>begin_pos</parameter></paramdef>

<paramdef>char <parameter>*filename</parameter></paramdef>

</funcprototype>

Line 61 Here are methods used for creating and m

Line 63 Here are methods used for creating and m

First function <function>cfg_get_context()</function> initializes context.

Although it is initialized, it also needs to be set to one from the command line

or config file type. Parameter <parameter>options</parameter> defines options

or configuration file type. Parameter <parameter>options</parameter> defines

set we have mentioned in previous chapter.

options set. Options set was described in previous chapter.

</para>

<para>

For full context initialization there are functions

For full context initialization there are two functions

<function>cfg_get_cmdline_context()</function> and

<function>cfg_get_cfgfile_context()</function>. There are also functions

<function>cfg_set_cmdline_context()</function> and

<function>cfg_set_cfgfile_context()</function> for setting up already existing

context. They have parameters with the same meanings as their equivalents with

one difference thet they are modifying already existing context and nothing

one difference that they are modifying already existing context and nothing

returning.

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.

</para>

<para>

Function <function>cfg_get_cmdline_function()</function> initializes context and

sets it to command line. Parameter <parameter>begin_pos</parameter> tells

starting position in dynamic array of command line arguments. Than parameter

<parameter>size</parameter> 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

<parameter>argv</parameter> contain NULL terminated array of strings with these

arguments. They can be passed just as they are passed to the

<function>main()</function> function.

</para>

<para>

<function>cfg_get_cmdline_function()</function> function initializes context and

Function <function>cfg_get_cfgfile_function()</function> initializes context and

sets it to command line. Parameter <parameter>argc</parameter> tells number of

sets it to configuration file. Parameter <parameter>begin_pos</parameter> tells

command line arguments. Next parameter <parameter>argv</parameter> contain array

starting position in file for parsing. Type of position, byte or line, depends

of strings with these arguments. They can be passed just as they are passed to

on fact, if context flag <constant>CFG_FILE_LINE_POS_USAGE</constant> is set. By

the <function>main()</function> function.

default they are expected as byte possition, but they can be changes to line

position by this context flag. See <xref linkend="usage.context-flags"

endterm="usage.context-flags.title"> section for more informations about this

issue. But anyway, all position types are counted from <constant>0</constant>.

Next parameter <parameter>size</parameter> 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 <parameter>filename</parameter> parameter.

</para>

<para>

<function>cfg_get_cfgfile_function()</function> function initializes context and

Please note, that these context creating and setting function are mentioned to

sets it to configuration file. Parameters <parameter>begin_pos</parameter> and

be similar for both context types. That is the reason, why also command line

<parameter>end_pos</parameter> tells starting and ending possition in file for

context has parameter <parameter>begin_pos</parameter>, when is also possible to

parsing. By default they are expected as byte possition, but they can be changes

change beginning of array parsing by passing different pointer for the parameter

to line position by appropriate context flag. See (TODO) context flags section

<parameter>argv</parameter>. Also note, that all positions are counted from

for more informations. Filename to parse is passed as the

<constant>0</constant>. For example third line of file is at position

<parameter>filename</parameter> parameter.

<constant>2</constant>. Although this, standart &name; 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.

</para>

<para>

Here are methods used for reseting and freeing context:

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

Line 121 Here are methods used for reseting and f

Line 149 Here are methods used for reseting and f

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. Similary in config file context type, position in file is set to

arguments specified by parameter <parameter>begin_pos</parameter>. Similary in

<parameter>begin_pos</parameter> position. Context flags remains unchanged. For

config file context type, position in file is set to

this purpose is <function>cfg_reset_context()</function> function provided.

<parameter>begin_pos</parameter> position. Context flags and context properties

remains unchanged. For this purpose is <function>cfg_reset_context()</function>

function provided.

</para>

<para>

Line 132 After parsing of configuration options i

Line 162 After parsing of configuration options i

last function <function>cfg_free_context()</function> frees passed

<structname>CFG_CONTEXT</structname> structure. It will not frees allocated

arguments or argument arrays set in any <structfield>value</structfield> member

of your options set.

of your options set. But it will free all internal context structures including

context flags and context properties, also with context itself.

</para>

</sect1>

Platon Group <platon@platon.org> http://platon.org/


Copyright © 2002-2006 Platon Group Site powered by Metafox CMS	Go to Top