.\" 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_ADD_PROPERTY" "3" "17 February 2004" "libcfg+ 0.6.2" "libcfg+ 0.6.2"
.SH NAME
cfg_clear_property, cfg_add_property, cfg_remove_property \- libcfg+ properties
.SH "SYNOPSIS | SINGLE PROPERTY MANIPULATION"
.PP
In this chapter are functions for manipulating with libcfg+ properties described.
We are starting with functions manipulating with one property. These functions
work also with virtual properties as well.
.PP
.sp
\fB#include <cfg+.h>
.sp
int cfg_clear_property (CFG_CONTEXT \fIcon\fB, enum cfg_property_type \fItype\fB);
.sp
int cfg_add_property (CFG_CONTEXT \fIcon\fB, enum cfg_property_type \fItype\fB, char *\fIstr\fB);
.sp
int cfg_remove_property (CFG_CONTEXT \fIcon\fB, enum cfg_property_type \fItype\fB, char *\fIstr\fB);
\fR
.SH "DESCRIPTION"
.PP
Given the context \fIcon\fR, the functions perform the following tasks:
.TP 0.2i
\(bu
Function \fBcfg_clear_property()\fR clears the
property \fItype\fR of any values it might have
accumulated.
.TP 0.2i
\(bu
Function \fBcfg_add_property()\fR adds a new value
\fIstr\fR to the property
\fItype\fR.
.TP 0.2i
\(bu
Function \fBcfg_remove_property()\fR removes a
value \fIstr\fR from the property
\fItype\fR.
.PP
Note that, when you set some string of multi vals separator property, any
whitespace you will use in that string will match any non-zero amount of
whitespaces during parsing. For example if separator is one space, also tab will
match, two or more spaces too, tab with space and so forth. It is similar
behaviour like when option name contains one or more white characters.
.PP
Types of properties, which are passed to mentioned functions as parameter
\fItype\fR, are described in following tables. They are divided
into three types. The first one are Command line related properties that affects only command
line. Than there are Configuration file related properties that affect only
configuration file. The last type of properties are Virtual properties (also known as \fIShared
properties\fR). In example, they can affect both, comand line and
configuration file, or set up quotation prefix and postfix in one call. They
exist for simplyfication of real properties manipulation.
.PP
Here are properties for command line.
.PP
"COMMAND LINE RELATED PROPERTIES"
.TP
\fBCFG_LINE_QUOTE_PREFIX \~ -- \~ command line quotation prefix\fR
For changing command line quotation prefix use this type. Note, that you
probably want also set quotation postfix equivalent to this prefix.  By default
are no strings initialized, due to simple reason. Most from often used shells
such as \fBsh\fR, \fBbash\fR,
\fBtcsh\fR and \fBzsh\fR already
contains quotation marks implementation so there is no need to do that thing also
in libcfg+ library. Although this, you can set command line quotation characters
by appropriate \fBcfg_add_property()\fR function call.
.TP
\fBCFG_LINE_QUOTE_POSTFIX \~ -- \~ command line quotation postfix\fR
For changing command line quotation postfix use this type. Note, that you
probably want also set quotation prefix equivalent to this postfix. By default
is of course also nothing initialized due to same reasons as it is in
CFG_LINE_QUOTE_POSTFIX case.
.TP
\fBCFG_LINE_STOP_STRING \~ -- \~ command line stop string\fR
For changing command line stop string use this type. Set this property if
you want to stop parsing on specified string which occurs on command line. Error
code CFG_ERROR_STOP_STR_FOUND is returned from parsing
function to determine this event. By default is nothing initialized.
.TP
\fBCFG_LINE_SHORT_OPTION_PREFIX \~ -- \~ command line short option prefix\fR
For changing command line short option prefix use this type. Default value
is of course single dash (-), because it is most offten
used in applications. You will probably don't need to redefine this property.
.TP
\fBCFG_LINE_LONG_OPTION_PREFIX \~ -- \~ command line short option prefix\fR
For changing command line long option prefix use this type. Default value
is of course double dash (--), because it is most offten
used in applications. You will probably don't need to redefine this property.
.TP
\fBCFG_LINE_NORMAL_MULTI_VALS_SEPARATOR \~ -- \~ normal command line multi values separator\fR
For changing normal command line multi values separators use this type. Multi values
separators are strings used for separation option values initialized with one
argument. For example if separator is comma, one command line argument will be
similar to this: \fB--multi=val1,val2,val3\fR. Option must have
CFG_MULTI_SEPARATED flag set. By default are
comma (,) and semicolon (;) initialized.
.TP
\fBCFG_LINE_LEFTOVER_MULTI_VALS_SEPARATOR \~ -- \~ leftover command line multi values separator\fR
For changing leftover command line multi values separators use this type.
Explanation is the same as for previous type with difference, that this property
affects only leftover arguments (arguments left on the command line without any
option that are stored into option with CFG_LEFTOVER_ARGS
type). By default is nothing initialized.
.TP
\fBCFG_LINE_OPTION_ARG_SEPARATOR \~ -- \~ command line option argument separator\fR
For changing command line option argument separator use this type. Option
argument separators are strings used to separate option and its argument. By
default is equal sign (=) character used. For example
\fB--option=argument\fR. Note that on command line argument can be
initialized also as following string with no need of separator usage (like this:
\fB--option argument\fR).
.PP
Here are properties for configuration file.
.PP
"CONFIGURATION FILE RELATED PROPERTIES"
.TP
\fBCFG_FILE_QUOTE_PREFIX \~ -- \~ configuration file quotation prefix\fR
For changing configuration file quotation prefix use this type. Note, that you
probably want also set quotation postfix equivalent to this prefix. By default
are standart quotation characters, apostrophes (') and
inverted commans ("), initialized (also for postfixes).
.TP
\fBCFG_FILE_QUOTE_POSTFIX \~ -- \~ configuration file quotation postfix\fR
For changing configuration file quotation postfix use this type. Note, that you
probably want also set quotation prefix equivalent to this postfix. By default
are standart quotation characters, apostrophes (') and
inverted commans ("), initialized (also for prefixes).
.TP
\fBCFG_FILE_STOP_PREFIX \~ -- \~ config file stop prefix\fR
For changing configuration file stop string use this type. Set this property if
you want to stop parsing on specified string which occurs on configration file
line. Error code CFG_ERROR_STOP_STR_FOUND is returned from
parsing function to determine this event. By default is nothing initialized. We
recommend you set this property to [ character, if you want
to determine configuration section beginning (to stop parsing on section
header).
.TP
\fBCFG_FILE_COMMENT_PREFIX \~ -- \~ config file comment prefix\fR
For changing configuration comment prefix use this type. Lines started with one
of these prefixes are skipped. By default are hash sign (#)
and semicolon (;) initialized.
.TP
\fBCFG_FILE_MULTI_LINE_POSTFIX \~ -- \~ config file multi line postfix\fR
For changing configuration file multi line postfix use this type. Multi
line postfixes are strings used to determine situation, that line continues on
next line. Multi lines are are concatenated to one and that is parsed. Multui
line postfixes are removed from concatenated line. By deault is backslash
(\\) initialized.
.TP
\fBCFG_FILE_NORMAL_MULTI_VALS_SEPARATOR \~ -- \~ normal config file multi values separator\fR
For changing normal configuration file multi values separators use this type.
Multi values separators are strings used for separation option values
initialized with one argument. For example if separator is comma one line in
configuration fill will be similar to this: \fBmulti =
val1,val2,val2\fR. Option must have
CFG_MULTI_SEPARATED flag set. By default are space, comma
(,) and semicolon (;) initialized.
.TP
\fBCFG_FILE_LEFTOVER_MULTI_VALS_SEPARATOR \~ -- \~ leftover config file multi values separator\fR
For changing leftover config file multi values separators use this type.
Explanation is the same as for previous type with difference, that this property
affects only leftover arguments (arguments left on the command line without any
option that are stored into option with CFG_LEFTOVER_ARGS
type). By default is space initialized. The goal is to get the similar
functionality as it is in command line case, where leftover arguments are placed
on command line and separated with spaces.
.TP
\fBCFG_FILE_OPTION_ARG_SEPARATOR \~ -- \~ config file option argument separator\fR
For changing configuration file option argument separator use this type.
Option argument separators are strings used to separate option and its argument.
By default is equal sign (=) character used. For example \fBoption
= argument\fR.
.PP
Here are virtual (shared) properties. In description of every virtual will be
only written which real properties are set. Please refer to Configuration file related properties table and Configuration file related properties table above for description
of real properties.
.PP
"VIRTUAL PROPERTIES"
.TP
\fBCFG_QUOTE\fR
CFG_LINE_QUOTE_PREFIX,
CFG_LINE_QUOTE_POSTFIX,
CFG_FILE_QUOTE_PREFIX,
CFG_FILE_QUOTE_POSTFIX
.TP
\fBCFG_LINE_QUOTE\fR
CFG_LINE_QUOTE_PREFIX,
CFG_LINE_QUOTE_POSTFIX
.TP
\fBCFG_FILE_QUOTE\fR
CFG_FILE_QUOTE_PREFIX,
CFG_FILE_QUOTE_POSTFIX
.TP
\fBCFG_QUOTE_PREFIX\fR
CFG_LINE_QUOTE_PREFIX,
CFG_FILE_QUOTE_PREFIX
.TP
\fBCFG_QUOTE_POSTFIX\fR
CFG_LINE_QUOTE_POSTFIX,
CFG_FILE_QUOTE_POSTFIX
.TP
\fBCFG_MULTI_VALS_SEPARATOR\fR
CFG_LINE_NORMAL_MULTI_VALS_SEPARATOR,
CFG_LINE_LEFTOVER_MULTI_VALS_SEPARATOR,
CFG_FILE_NORMAL_MULTI_VALS_SEPARATOR,
CFG_FILE_LEFTOVER_MULTI_VALS_SEPARATOR
.TP
\fBCFG_LINE_MULTI_VALS_SEPARATOR\fR
CFG_LINE_NORMAL_MULTI_VALS_SEPARATOR,
CFG_LINE_LEFTOVER_MULTI_VALS_SEPARATOR
.TP
\fBCFG_FILE_MULTI_VALS_SEPARATOR\fR
CFG_FILE_NORMAL_MULTI_VALS_SEPARATOR,
CFG_FILE_LEFTOVER_MULTI_VALS_SEPARATOR
.TP
\fBCFG_NORMAL_MULTI_VALS_SEPARATOR\fR
CFG_LINE_NORMAL_MULTI_VALS_SEPARATOR,
CFG_FILE_NORMAL_MULTI_VALS_SEPARATOR
.TP
\fBCFG_LEFTOVER_MULTI_VALS_SEPARATOR\fR
CFG_LINE_LEFTOVER_MULTI_VALS_SEPARATOR,
CFG_FILE_LEFTOVER_MULTI_VALS_SEPARATOR
.TP
\fBCFG_OPTION_ARG_SEPARATOR\fR
CFG_LINE_OPTION_ARG_SEPARATOR,
CFG_FILE_OPTION_ARG_SEPARATOR
.SH "SYNOPSIS | MULTIPLE PROPERTIES MANIPULATION"
.PP
Following functions allows you to set up multiple properties and/or its multiple
values in one call. They work just like Virtual properties, but they are more flexible -
you can specify arbitrary properties. All these functions use variable number of
arguments.
.PP
.sp
\fB#include <cfg+.h>
.sp
int cfg_clear_properties (CFG_CONTEXT \fIcon\fB, enum cfg_property_type \fItype\fB, \fI...\fB);
.sp
int cfg_add_properties (CFG_CONTEXT \fIcon\fB, enum cfg_property_type \fItype\fB, char *\fIstr\fB, \fI...\fB, \fI...\fB);
.sp
int cfg_remove_properties (CFG_CONTEXT \fIcon\fB, enum cfg_property_type \fItype\fB, char *\fIstr\fB, \fI...\fB, \fI...\fB);
.sp
int cfg_add_properties_type (CFG_CONTEXT \fIcon\fB, enum cfg_property_type \fItype\fB, char *\fIstr\fB, \fI...\fB);
.sp
int cfg_remove_properties_type (CFG_CONTEXT \fIcon\fB, enum cfg_property_type \fItype\fB, char *\fIstr\fB, \fI...\fB);
.sp
int cfg_add_properties_str (CFG_CONTEXT \fIcon\fB, char *\fIstr\fB, enum cfg_property_type \fItype\fB, \fI...\fB);
.sp
int cfg_remove_properties_str (CFG_CONTEXT \fIcon\fB, char *\fIstr\fB, enum cfg_property_type \fItype\fB, \fI...\fB);
\fR
.SH "DESCRIPTION"
.PP
Given the context \fIcon\fR the functions provide the
following functionality:
.TP 0.2i
\(bu
Function \fBcfg_clear_properties()\fR removes all values from the list
of properties specified by the variable length parameter
\fItype\fR. The property list must be terminated by the
CFG_EOT constant. 
.TP 0.2i
\(bu
Functions \fBcfg_add_properties()\fR and
\fBcfg_remove_properties()\fR give you the ability to add and
remove multiple property/value pairs. The property/value pairs are designated
by the variable length parameters \fItype\fR and
\fIstr\fR correspondingly. The property list must be
terminated with CFG_EOT and the value list must be
terminated with NULL. 
.TP 0.2i
\(bu
Functions \fBcfg_add_properties_type()\fR and
\fBcfg_remove_properties_type()\fR add and remove multiple
values specified by the variable parameter \fIstr\fR to and
from a single property denoted by \fItype\fR. The value list
should be terminated with NULL.
.TP 0.2i
\(bu
Functions \fBcfg_add_properties_str()\fR and
\fBcfg_remove_properties_str()\fR add and remove the value
denoted by \fIstr\fR to and from the list of properties
specified by the variable length parameter \fItype\fR. The
property list must be terminated with CFG_EOT.
.PP
As with the single-property functions, all of these functions return
1 on success or 0 on not enough
memory error.
.\" 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.