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

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

Diff for libcfg+/doc/sgml/usage.options-set.sgml between version 1.13 and 1.14

version 1.13, 2003/03/13 19:11:05

version 1.14, 2003/08/16 01:43:42

Line 1

<!-- MAN:

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

Line 24

<para>

The basic element of &name; usage is one <firstterm>option</firstterm>. Option

The basic unit of &name; is an <firstterm>option</firstterm>. An option is

is defined like <structname>cfg_option</structname> structure. Definition

defined by the <structname>cfg_option</structname> structure, whose definition

follows:

is presented below:

</para>

<para>

Line 46 struct <structname>cfg_option</structnam

<para>

First two members of <structname>cfg_option</structname> structure,

The first two members of the <structname>cfg_option</structname> structure,

<structfield>cmdline_long_name</structfield> and

<structfield>cmdline_short_name</structfield> concern to command line. They

<structfield>cmdline_short_name</structfield>, specify the long and short name

specify command line long name and short name. Configuration file option name is

of the option when parsing the command line. The third member,

specified by third structure member <structfield>cfgfile_name</structfield>.

<structfield>cfgfile_name</structfield>, specifies the name of the option in a

Fields <structfield>cmdline_long_name</structfield> and

configuration file. Setting the first two fields to <constant>NULL</constant>

<structfield>cfgfile_name</structfield> are strings (pointers to char) and may

and <constant>'\0'</constant> respectively will effectively eliminate the

be <constant>NULL</constant>, what means undefined. Field

option from taking part in command line parsing. Setting

<structfield>cmdline_short_name</structfield> is single character and may be

<structfield>cfgfile_name</structfield> to <constant>NULL</constant> will

<constant>'\0'</constant>, what means also undefined.

eliminate this option from taking part in configuration file parsing.

</para>

<para>

Note that, any whitespace you will use in

Note also that if <structfield>cmdline_long_name</structfield> or

<structfield>cmdline_long_name</structfield> or

<structfield>cfgfile_name</structfield> point to a string containing at least

<structfield>cfgfile_name</structfield> will match any non-zero amount of

one whitespace character, any non-zero number of whitespace characters will be

whitespace during parsing. For example if separator is one space, also tab will

matched during parsing. For example, if the separator is a space, a tab

match, two or more spaces too, etc. This feature is to simplify configuration of

character will also match, as will two spaces and a tab, two tabs and a space,

your application for your user, as she doesn't have to pay attention to number

and so on. This simplifies the configuration for the user because one does not

of spaces used in configurarion option. For example "debug level", "debug\tlevel"

have to pay attention to the number of spaces used in a configuration option.

and "debug \tlevel" will match the same configuration option.

For example, <userinput>debug level</userinput>,

<userinput>debug\tlevel</userinput> and

<userinput>debug \tlevel</userinput> will match the same option.

</para>

<para>

Next structure member, <structfield>type</structfield>, defines an option type

The variable <structfield>type</structfield> is an enumeration defining the

with option type flags. They are summarized in tables <xref

type of an option with each member of the enumeration being either a type or a

linkend="usage.option-types.table" endterm="usage.option-types.table.title"> and

flag. The possible values of <structfield>type</structfield> are summarized in

<xref linkend="usage.option-type-flags.table"

tables <xref linkend="usage.option-types.table"

endterm="usage.option-type-flags.table.title">.

endterm="usage.option-types.table.title"> and <xref

linkend="usage.option-type-flags.table"

endterm="usage.option-type-flags.table.title">

</para>

<para>

The <structfield>value</structfield> member tells the address where option

The variable <structfield>value</structfield> is a pointer to the argument(s)

argument or arguments will be stored. It should be address of appropriate

of an option. The argument(s) must be of the type stored in the

datatype defined in <structfield>type</structfield> field. Note that

<structfield>type</structfield> member of the

<constant>NULL</constant> can be also used, but then option argument will not

<structname>cfg_option</structname> structure. Note that

be stored. Last field of <structname>cfg_option</structname> structure is

<structfield>value</structfield> could also contain a

<structfield>val</structfield>, which defines exit code from parsing functions

<constant>NULL</constant> value, which would suggest that the option arguments

when option is found. <constant>0</constant> means no return. It is good

will not be stored.

idea to keep these values positive to prevent mismatch with

<structname>cfg_error</structname> exit codes.

</para>

<para>

The last field of the structure is <structfield>val</structfield>. It defines

the exit code of parsing function when this option is found in the token

stream. Setting this field to <constant>0</constant> will cause

<function>cfg_get_next_opt()</function> to proceed to the next option instead

of returning. Also, since <function>cfg_get_next_opt()</function> also

returns negative integers to signal an error, it is a good idea to keep the

value of this field in the positive range. You can read more about this in the

<xref linkend="usage.parsing" endterm="usage.parsing.title"> section.

</para>

<para>

Line 154 idea to keep these values positive to pr

Line 168 idea to keep these values positive to pr

</para>

<para>

Here follows option type flags. These flags can be used in addition to

The next table describes the possible "type flags" of an option. The purpose

particular options types in option set. They modify

of the flags is to add more variety and thus flexibility to the basic data

<structfield>value</structfield> datatype.

types presented in the previous table. By combining one of the flags with one

of the basic types, a completely new data type can be produced. For example,

to define an array of strings, one would use the

<constant>CFG_MULTI</constant> flag in addition to the

<constant>CFG_STRING</constant> data type. One of the obvious rules of this

data type combining is that the flags must always be used in conjunction with

the basic types since a flag is only a data type modifier and not a

self-contained data type.

</para>

<para>

Line 175 particular options types in option set.

Line 196 particular options types in option set.

<row>

<entry><constant>CFG_MULTI</constant>, <constant>CFG_MULTI_ARRAY</constant></entry>

<entry>Option can be specified more than once and result is dynamic array of

<entry>The Option can be specified more than once and the result is a

defined type.</entry>

dynamic array of the defined type.</entry>

</row>

<row>

<entry><constant>CFG_MULTI_SEPARATED</constant></entry>

<entry>Same as the <constant>CFG_MULTI_ARRAY</constant>, but dynamic array

<entry>Same as <constant>CFG_MULTI_ARRAY</constant>, but a dynamic array

is also created by spliting option value according to defined separators.

is also created by splitting the option value according to the defined

See <xref linkend="usage.properties" endterm="usage.properties.title">

separators. See the <xref linkend="usage.properties"

section for more information about used separators and how to change

endterm="usage.properties.title"> section for more information about the

them.</entry>

separators that can be used and ways to change them.</entry>

</row>

<row>

<entry>

Line 204 defined type.</entry>

Line 225 defined type.</entry>

</para>

<para>

All simple datatypes are stored to defined address as they are. Strings are

Of the basic data types, only strings are dynamically allocated and in that

dynamically allocated using <function>malloc()</function> function and pointer

case <structfield>value</structfield> points to a portion of memory allocated

(address) to this string is stored. In this case, don't forget to free allocated

with <function>malloc()</function> function. Do not forget to free that memory

memory using <function>free()</function> function. When using

when you do not need it anymore using the <function>free()</function>

<constant>CFG_MULTI_ARRAY</constant> or <constant>CFG_MULTI_SEPARATED</constant>

function. If the <constant>CFG_MULTI_ARRAY</constant> or the

type flag, pointer to NULL terminated array of defined datatype is always

<constant>CFG_MULTI_SEPARATED</constant> flag was used,

stored. This array can be freed using <function>strdyn_free()</function>

<structfield>value</structfield> will point to a <constant>NULL</constant>

function.

terminated array of a basic type. It can be freed using

<function>cfg_strdyn_free()</function>.

</para>

<para>

One of the constants <constant>CFG_END_OPTION</constant> and

The constants <constant>CFG_END_OPTION</constant> and

<constant>CFG_END_OF_LIST</constant> is used to mark end of an options set.

<constant>CFG_END_OF_LIST</constant> are used to mark the end of an option

They have set all pointer values to <constant>NULL</constant> and all arithmetic

set. They set all pointer values to <constant>NULL</constant> and all numeric

values to <constant>0</constant>.

</para>

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


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