libcfg+/man/cfg_add_property.3.html

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:

       o Function cfg_clear_property() clears the property type of any  values
         it might have accumulated.

       o Function  cfg_add_property()  adds  a  new  value str to the property
         type.

       o 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
              equivalent to this postfix. By default  are  standart  quotation
              characters,  apostrophes  (') and inverted commans ("), initial-
              ized (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:

       o Function  cfg_clear_properties()  removes all values from the list of
         properties specified by  the  variable  length  parameter  type.  The
         property list must be terminated by the CFG_EOT constant.

       o 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.

       o 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.

       o 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)