CFG_ADD_PROPERTY(3) libcfg+ 0.6.2 CFG_ADD_PROPERTY(3)NAME
cfg_clear_property, cfg_add_property, cfg_remove_property - libcfg+
properties
SYNOPSIS | SINGLE PROPERTY MANIPULATION
In this chapter are functions for manipulating with libcfg+ properties
described. We are starting with functions manipulating with one prop‐
erty. These functions work also with virtual properties as well.
#include <cfg+.h>
int cfg_clear_property (CFG_CONTEXT con, enum cfg_property_type type);
int cfg_add_property (CFG_CONTEXT con, enum cfg_property_type type,
char *str);
int cfg_remove_property (CFG_CONTEXT con, enum cfg_property_type type,
char *str);
DESCRIPTION
Given the context con, the functions perform the following tasks:
· Function cfg_clear_property() clears the property type of any values
it might have accumulated.
· Function cfg_add_property() adds a new value str to the property
type.
· Function cfg_remove_property() removes a value str from the property
type.
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.
Types of properties, which are passed to mentioned functions as parame‐
ter type, 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 prop‐
erties are Virtual properties (also known as Shared properties). In
example, they can affect both, comand line and configuration file, or
set up quotation prefix and postfix in one call. They exist for simply‐
fication of real properties manipulation.
Here are properties for command line.
"COMMAND LINE RELATED PROPERTIES"
CFG_LINE_QUOTE_PREFIX -- command line quotation prefix
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 sim‐
ple reason. Most from often used shells such as sh, bash, tcsh
and zsh 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 appropri‐
ate cfg_add_property() function call.
CFG_LINE_QUOTE_POSTFIX -- command line quotation postfix
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.
CFG_LINE_STOP_STRING -- command line stop string
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.
CFG_LINE_SHORT_OPTION_PREFIX -- command line short option prefix
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.
CFG_LINE_LONG_OPTION_PREFIX -- command line short option prefix
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.
CFG_LINE_NORMAL_MULTI_VALS_SEPARATOR -- normal command line multi
values separator
For changing normal command line multi values separators use
this type. Multi values separators are strings used for separa‐
tion option values initialized with one argument. For example if
separator is comma, one command line argument will be similar to
this: --multi=val1,val2,val3. Option must have CFG_MULTI_SEPA‐
RATED flag set. By default are comma (,) and semicolon (;) ini‐
tialized.
CFG_LINE_LEFTOVER_MULTI_VALS_SEPARATOR -- leftover command line
multi values separator
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.
CFG_LINE_OPTION_ARG_SEPARATOR -- command line option argument sepa‐
rator
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 --option=argument. Note that on command line
argument can be initialized also as following string with no
need of separator usage (like this: --option argument).
Here are properties for configuration file.
"CONFIGURATION FILE RELATED PROPERTIES"
CFG_FILE_QUOTE_PREFIX -- configuration file quotation prefix
For changing configuration file quotation prefix use this type.
Note, that you probably want also set quotation postfix equiva‐
lent to this prefix. By default are standart quotation charac‐
ters, apostrophes (') and inverted commans ("), initialized
(also for postfixes).
CFG_FILE_QUOTE_POSTFIX -- configuration file quotation postfix
For changing configuration file quotation postfix use this type.
Note, that you probably want also set quotation prefix equiva‐
lent to this postfix. By default are standart quotation charac‐
ters, apostrophes (') and inverted commans ("), initialized
(also for prefixes).
CFG_FILE_STOP_PREFIX -- config file stop prefix
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 rec‐
ommend you set this property to [ character, if you want to
determine configuration section beginning (to stop parsing on
section header).
CFG_FILE_COMMENT_PREFIX -- config file comment prefix
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.
CFG_FILE_MULTI_LINE_POSTFIX -- config file multi line postfix
For changing configuration file multi line postfix use this
type. Multi line postfixes are strings used to determine situa‐
tion, that line continues on next line. Multi lines are are con‐
catenated to one and that is parsed. Multui line postfixes are
removed from concatenated line. By deault is backslash (\) ini‐
tialized.
CFG_FILE_NORMAL_MULTI_VALS_SEPARATOR -- normal config file multi
values separator
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: multi = val1,val2,val2. Option must
have CFG_MULTI_SEPARATED flag set. By default are space, comma
(,) and semicolon (;) initialized.
CFG_FILE_LEFTOVER_MULTI_VALS_SEPARATOR -- leftover config file
multi values separator
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.
CFG_FILE_OPTION_ARG_SEPARATOR -- config file option argument sepa‐
rator
For changing configuration file option argument separator use
this type. Option argument separators are strings used to sepa‐
rate option and its argument. By default is equal sign (=)
character used. For example option = argument.
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.
"VIRTUAL PROPERTIES"
CFG_QUOTE
CFG_LINE_QUOTE_PREFIX, CFG_LINE_QUOTE_POSTFIX,
CFG_FILE_QUOTE_PREFIX, CFG_FILE_QUOTE_POSTFIX
CFG_LINE_QUOTE
CFG_LINE_QUOTE_PREFIX, CFG_LINE_QUOTE_POSTFIX
CFG_FILE_QUOTE
CFG_FILE_QUOTE_PREFIX, CFG_FILE_QUOTE_POSTFIX
CFG_QUOTE_PREFIX
CFG_LINE_QUOTE_PREFIX, CFG_FILE_QUOTE_PREFIX
CFG_QUOTE_POSTFIX
CFG_LINE_QUOTE_POSTFIX, CFG_FILE_QUOTE_POSTFIX
CFG_MULTI_VALS_SEPARATOR
CFG_LINE_NORMAL_MULTI_VALS_SEPARATOR, CFG_LINE_LEFT‐
OVER_MULTI_VALS_SEPARATOR, CFG_FILE_NORMAL_MULTI_VALS_SEPARATOR,
CFG_FILE_LEFTOVER_MULTI_VALS_SEPARATOR
CFG_LINE_MULTI_VALS_SEPARATOR
CFG_LINE_NORMAL_MULTI_VALS_SEPARATOR, CFG_LINE_LEFT‐
OVER_MULTI_VALS_SEPARATOR
CFG_FILE_MULTI_VALS_SEPARATOR
CFG_FILE_NORMAL_MULTI_VALS_SEPARATOR, CFG_FILE_LEFT‐
OVER_MULTI_VALS_SEPARATOR
CFG_NORMAL_MULTI_VALS_SEPARATOR
CFG_LINE_NORMAL_MULTI_VALS_SEPARATOR, CFG_FILE_NOR‐
MAL_MULTI_VALS_SEPARATOR
CFG_LEFTOVER_MULTI_VALS_SEPARATOR
CFG_LINE_LEFTOVER_MULTI_VALS_SEPARATOR, CFG_FILE_LEFT‐
OVER_MULTI_VALS_SEPARATOR
CFG_OPTION_ARG_SEPARATOR
CFG_LINE_OPTION_ARG_SEPARATOR, CFG_FILE_OPTION_ARG_SEPARATOR
SYNOPSIS | MULTIPLE PROPERTIES MANIPULATION
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.
#include <cfg+.h>
int cfg_clear_properties (CFG_CONTEXT con, enum cfg_property_type type,
...);
int cfg_add_properties (CFG_CONTEXT con, enum cfg_property_type type,
char *str, ..., ...);
int cfg_remove_properties (CFG_CONTEXT con, enum cfg_property_type
type, char *str, ..., ...);
int cfg_add_properties_type (CFG_CONTEXT con, enum cfg_property_type
type, char *str, ...);
int cfg_remove_properties_type (CFG_CONTEXT con, enum cfg_property_type
type, char *str, ...);
int cfg_add_properties_str (CFG_CONTEXT con, char *str, enum cfg_prop‐
erty_type type, ...);
int cfg_remove_properties_str (CFG_CONTEXT con, char *str, enum
cfg_property_type type, ...);
DESCRIPTION
Given the context con the functions provide the following functional‐
ity:
· Function cfg_clear_properties() removes all values from the list of
properties specified by the variable length parameter type. The prop‐
erty list must be terminated by the CFG_EOT constant.
· Functions cfg_add_properties() and cfg_remove_properties() give you
the ability to add and remove multiple property/value pairs. The
property/value pairs are designated by the variable length parameters
type and str correspondingly. The property list must be terminated
with CFG_EOT and the value list must be terminated with NULL.
· Functions cfg_add_properties_type() and cfg_remove_properties_type()
add and remove multiple values specified by the variable parameter
str to and from a single property denoted by type. The value list
should be terminated with NULL.
· Functions cfg_add_properties_str() and cfg_remove_properties_str()
add and remove the value denoted by str to and from the list of prop‐
erties specified by the variable length parameter type. The property
list must be terminated with CFG_EOT.
As with the single-property functions, all of these functions return 1
on success or 0 on not enough memory error.
SEE ALSO
You can get library overview, table of contents and such additional
information info from main libcfg+(3) manpage by typing "man libcfg+"
on UNIX-based systems. Also use this command to get information about
authors, homepage and license conditions.
libcfg+ 0.6.2 17 February 2004 CFG_ADD_PROPERTY(3)