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 property. 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  be‐
       haviour like when option name contains one or more white characters.

       Types  of  properties, which are passed to mentioned functions as parameter type, are described in fol‐
       lowing 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  Shared  proper‐
       ties). 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.

       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  quota‐
              tion 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  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 pars‐
              ing 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  rede‐
              fine 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 rede‐
              fine 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 separation option values initialized with one argument. For example if sep‐
              arator  is  comma,  one  command  line argument will be similar to this: --multi=val1,val2,val3.
              Option must have CFG_MULTI_SEPARATED 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 separator
              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 equivalent 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  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 recommend you set this property to [ character, if you want to deter‐
              mine 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 pre‐
              fixes 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 situation, 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 (\) initialized.

       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 sep‐
              arators 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  func‐
              tionality 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 separator
              For changing configuration file option argument separator use this type.  Option argument  sepa‐
              rators are strings used to separate option and its argument.  By default is equal sign (=) char‐
              acter 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_LEFTOVER_MULTI_VALS_SEPARATOR,    CFG_FILE_NOR‐
              MAL_MULTI_VALS_SEPARATOR, CFG_FILE_LEFTOVER_MULTI_VALS_SEPARATOR

       CFG_LINE_MULTI_VALS_SEPARATOR
              CFG_LINE_NORMAL_MULTI_VALS_SEPARATOR, CFG_LINE_LEFTOVER_MULTI_VALS_SEPARATOR

       CFG_FILE_MULTI_VALS_SEPARATOR
              CFG_FILE_NORMAL_MULTI_VALS_SEPARATOR, CFG_FILE_LEFTOVER_MULTI_VALS_SEPARATOR

       CFG_NORMAL_MULTI_VALS_SEPARATOR
              CFG_LINE_NORMAL_MULTI_VALS_SEPARATOR, CFG_FILE_NORMAL_MULTI_VALS_SEPARATOR

       CFG_LEFTOVER_MULTI_VALS_SEPARATOR
              CFG_LINE_LEFTOVER_MULTI_VALS_SEPARATOR, CFG_FILE_LEFTOVER_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  proper‐
       ties. 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_property_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 functionality:

       · Function cfg_clear_properties() removes all values from the list of properties specified by the vari‐
         able length parameter type. The property 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 parame‐
         ters 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 properties specified by the variable length parameter type. The  prop‐
         erty 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 informa‐
       tion about authors, homepage and license conditions.

libcfg+ 0.6.2                                  17 February 2004                            CFG_ADD_PROPERTY(3)