.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "CFG_OPTION" "3" "17 February 2004" "libcfg+ 0.6.2" "libcfg+ 0.6.2"
.SH NAME
cfg_option \- libcfg+ options set
.SH "SYNOPSIS"
.PP
The basic unit of libcfg+ is an \fIoption\fR. An option is
defined by the cfg_option structure, whose definition
is presented below:
.PP

.nf
struct cfg_option {
	const char *\fBcmdline_long_name\fR;
	const char  \fBcmdline_short_name\fR;
	const char *\fBcfgfile_name\fR;
	const enum cfg_option_type \fBtype\fR;
	void *\fBvalue\fR;
	int   \fBval\fR;
};
.fi
.SH "DESCRIPTION"
.PP
The first two members of the cfg_option structure,
\fBcmdline_long_name\fR and
\fBcmdline_short_name\fR, specify the long and short name
of the option when parsing the command line. The third member,
\fBcfgfile_name\fR, specifies the name of the option in a
configuration file. Setting the first two fields to NULL
and '\\0' respectively will effectively eliminate the
option from taking part in command line parsing.  Setting
\fBcfgfile_name\fR to NULL will
eliminate this option from taking part in configuration file parsing.
.PP
Note also that if \fBcmdline_long_name\fR or
\fBcfgfile_name\fR point to a string containing at least
one whitespace character, any non-zero number of whitespace characters will be
matched during parsing. For example, if the separator is a space, a tab
character will also match, as will two spaces and a tab, two tabs and a space,
and so on. This simplifies the configuration for the user because one does not
have to pay attention to the number of spaces used in a configuration option.
For example, \fBdebug\~level\fR,
\fBdebug\\tlevel\fR and
\fBdebug\~\\tlevel\fR will match the same option.
.PP
The variable \fBtype\fR is an enumeration defining the
type of an option with each member of the enumeration being either a type or a
flag. The possible values of \fBtype\fR are summarized in
tables Option type flags and Option type flags
.PP
The variable \fBvalue\fR is a pointer to the argument(s)
of an option. The argument(s) must be of the type stored in the
\fBtype\fR member of the
cfg_option structure. Note that
\fBvalue\fR could also contain a
NULL value, which would suggest that the option arguments
will not be stored. 
.PP
The last field of the structure is \fBval\fR. It defines
the exit code of parsing function when this option is found in the token
stream. Setting this field to 0 will cause
\fBcfg_get_next_opt()\fR to proceed to the next option instead
of returning.  Also, since \fBcfg_get_next_opt()\fR 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
Parsing section.
.PP
"OPTION TYPES"
.TP
\fBCFG_BOOL, CFG_BOOLEAN\fR
\fBvalue\fR type: int

No argument for an option is expected. Boolean datatype with two states.
.TP
\fBCFG_INT, CFG_INTEGER\fR
\fBvalue\fR type: int

Integer argument
.TP
\fBCFG_UINT, CFG_UNSIGNED, CFG_UNSIGNED_INT\fR
\fBvalue\fR type: unsigned int

Unsigned integer argument
.TP
\fBCFG_LONG\fR
\fBvalue\fR type: long int

Long integer argument
.TP
\fBCFG_ULONG, CFG_UNSIGNED_LONG\fR
\fBvalue\fR type: unsigned long int

Unsigned long integer argument
.TP
\fBCFG_FLOAT\fR
\fBvalue\fR type: float

Float argument
.TP
\fBCFG_DOUBLE\fR
\fBvalue\fR type: double

Double argument
.TP
\fBCFG_STR, CFG_STRING\fR
\fBvalue\fR type: char *

String argument
.PP
The next table describes the possible "type flags" of an option. The purpose
of the flags is to add more variety and thus flexibility to the basic data
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
CFG_MULTI flag in addition to the
CFG_STRING 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. 
.PP
"OPTION TYPE FLAGS"
.TP
\fBCFG_MULTI, CFG_MULTI_ARRAY\fR
<type> **

The Option can be specified more than once and the result is a
dynamic array of the defined type.
.TP
\fBCFG_MULTI_SEPARATED\fR
<type> **

Same as CFG_MULTI_ARRAY, but a dynamic array
is also created by splitting the option value according to the defined
separators.  See the Properties section for more information about the
separators that can be used and ways to change them.
.TP
\fB  CFG_LAST_ARGS, CFG_LAST_ARGUMENTS, CFG_LEFTOVER_ARGS, CFG_LEFTOVER_ARGUMENTS \fR
<type> **

Leftover arguments are stored here.
.PP
Of the basic data types, only strings are dynamically allocated and in that
case \fBvalue\fR points to a portion of memory allocated
with \fBmalloc()\fR function. Do not forget to free that memory
when you do not need it anymore using the \fBfree()\fR
function. If the CFG_MULTI_ARRAY or the
CFG_MULTI_SEPARATED flag was used,
\fBvalue\fR will point to a NULL
terminated array of a basic type. It can be freed using
\fBcfg_strdyn_free()\fR.
.PP
The constants CFG_END_OPTION and
CFG_END_OF_LIST are used to mark the end of an option
set. They set all pointer values to NULL and all numeric
values to 0.
.PP
.SS "EXAMPLE OF OPTIONS SET DEFINITION"

.nf
#include <cfg+.h>

/* Option variables */
int help, verbose, nice;
char *cfg_file;
char **command;

/* Option set */
struct cfg_option options[] = {
  {"help",    'h', NULL,      CFG_BOOL,          (void *) &help,     0},
  {"nice",    'n', "nice",    CFG_INT,           (void *) &nice,     0},
  {"verbose", 'v', "verbose", CFG_BOOL+CFG_MULTI,(void *) &verbose,  0},
  {NULL,      'f', NULL,      CFG_STR,           (void *) &cfg_file, 0},
  {NULL, '\\0', "command", CFG_STR+CFG_MULTI_SEPARATED+CFG_LEFTOVER_ARGS,
    (void *) &command, 0},
  CFG_END_OF_LIST
};
.fi
.\" This is common footer for libcfg+ manpages. 
.\" Written by Ondrej Jombik in 14th September 2002
.SH "SEE ALSO"
You can get library overview, table of contents and such additional information
info from main \fBlibcfg+\fR(3) manpage by typing "man libcfg+" on UNIX-based
systems. Also use this command to get information about authors, homepage and
license conditions.