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

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

Diff for libcfg+/doc/sgml/usage.parsing.sgml between version 1.7 and 1.8

version 1.7, 2002/10/07 10:54:40

version 1.8, 2003/08/16 14:06:06

Line 1

<!-- MAN:

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [

Line 28

<para>

After &name; context is created and context flags are set, we can start with

After a &name; context is created and its flags are set (optional), one can

configuration parsing. This chapter contains information about particular

initiate the parsing. This chapter provides information about the available

parsing methods.

Line 51 parsing methods.

<para>

These functions get created context as its single argument. Depending on context

These functions take a context as their only argument. Depending on the type

type they parse next configuration file line or command line argument. If found

of the context, either a file or a command line option will be processed. If

option is in specified options set (see <xref linkend="usage.options-set"

the option just parsed matches one of the options in the option set

endterm="usage.options-set.title"> chapter) and if

(see <xref linkend="usage.options-set"

<structfield>value</structfield> field in <structname>cfg_option</structname> of

endterm="usage.options-set.title"> section) and the arguments of the

appropriate option is not <constant>NULL</constant>, that field is filled with

parsed option are stored in memory and <structfield>value</structfield> is set

parsed argument or arguments.

to point to them. However, if the <structfield>value</structfield> of the

relevant option in the option is set to <constant>NULL</constant>, the

arguments will not be stored.

</para>

<para>

The main and only one difference between these two parsing functions is, that

The main and only difference between the two functions is in the way they

after option is found on command line or in config file and

interpret the <structfield>val</structfield> field of the relevant option

<structfield>val</structfield> structure field is not <constant>0</constant>,

after a matching token was found in the token stream. The function

<function>cfg_get_next_opt()</function> returns that value. Otherwise function

<function>cfg_get_next_opt()</function> respects the value of this field and

continues on next config file line or on next command line argument. This

if it is not <constant>0</constant>, returns the value upon a match. If the

feature is especially usuable for applications with need of more sophisticated

field is set to <constant>0</constant>, the function proceeds to the next token

command line or config file parsing. Function <function>cfg_parse()</function>

without returning a value. In the case of <function>cfg_parse()</function>,

allways ignores <structfield>val</structfield> value.

<structfield>val</structfield> is ignored.

</para>

<para>

These functions also returns error code if error has occured. Note, that all

If an error occurs during parsing, the functions return a negative integer.

error codes are lower than <constant>0</constant>. That is the reason why it is

This is why it is a good idea to set the <structfield>val</structfield> member

good to keep value of <structfield>val</structfield> structure member equal or

of the <structname>cfg_option</structname> to a value equal or greater than

greater than <constant>0</constant>. More information with error codes description

<constant>0</constant>. Detailed information about error codes as well as

are in <xref linkend="usage.error-codes" endterm="usage.error-codes.title">

their descriptions can be found in the <xref linkend="usage.error-codes"

chapter.

endterm="usage.error-codes.title"> section.

</para>

<para>

Line 90 At the end of parsing <constant>0</const

Line 92 At the end of parsing <constant>0</const

<para>

Following functions provide such additional information when returned options

The following functions provide additional information about a matched option.

are handled.

Line 117 are handled.

Line 118 are handled.

<para>

Functions have following behaviour: <function>cfg_get_cur_opt()</function>

Use <function>cfg_get_cur_opt()</function> to get the name of the option being

returns currently processed option name, <function>cfg_get_cur_arg()</function>

processed. Use <function>cfg_get_cur_arg()</function>to get the current

returns currently processed option argument. Return value of

argument. Finally, use <function>cfg_get_cur_idx()</function> to get the

<function>cfg_get_cur_idx()</function> function depends on current type of

current offset in the parsing stream. If the context is associated with the

context. It returns <parameter>argv</parameter> index of processed option in

command line, the value is the current offset in the

command line context and file byte or line position of processed option in

<parameter>argv</parameter> array. If the context is associated with a

config file context.

configuration file, then depending on the value of

<constant>CFG_FILE_LINE_POS_USAGE</constant>, it is either the current byte

offset or line number in the file.

</para>

</sect1>

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


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