src/cfg/cfg+.h

   1 /*
   2  * libcfg+ - precise command line & config file parsing library
   3  *
   4  * cfg+.h - main implementation header file
   5  * ____________________________________________________________
   6  *
   7  * Developed by Ondrej Jombik <nepto@platon.sk>
   8  *          and Lubomir Host <rajo@platon.sk>
   9  * Copyright (c) 2001-2004 Platon SDG, http://platon.sk/
  10  * All rights reserved.
  11  *
  12  * See README file for more information about this software.
  13  * See COPYING file for license information.
  14  *
  15  * Download the latest version from
  16  * http://platon.sk/projects/libcfg+/
  17  */
  18
  19 /* $Platon: libcfg+/src/cfg+.h,v 1.60 2004/01/12 06:03:08 nepto Exp $ */
  20
  21 /**
  22  * @file        cfg+.h
  23  * @brief       main implementation header file
  24  * @author      Ondrej Jombik <nepto@platon.sk>
  25  * @author      Lubomir Host <rajo@platon.sk>
  26  * @version     \$Platon: libcfg+/src/cfg+.h,v 1.60 2004/01/12 06:03:08 nepto Exp $
  27  * @date        2001-2004
  28  */
  29
  30 #ifndef _PLATON_CFG_H
  31 #define _PLATON_CFG_H
  32
  33 #include <stdio.h>
  34
  35 /** End of options list marker */
  36 #define CFG_END_OPTION { NULL, '\0', NULL, CFG_END, NULL, 0 }
  37 #define CFG_END_OF_LIST CFG_END_OPTION /**< Alias for @ref CFG_END_OPTION */
  38
  39 /**
  40  * @name Error codes
  41  */
  42 /*@{*/
  43 /**
  44  * Possible return values returned by parsing functions.
  45  */
  46 enum cfg_error { /* {{{ */
  47
  48         /*@{*/
  49         /** OK, all is right. */
  50         CFG_ERR_OK = 0,
  51         CFG_ERROR_OK = 0,
  52         CFG_OK = 0,
  53         /*@}*/
  54
  55         /** An argument is missing for an option. */
  56         CFG_ERR_NOARG = -1,
  57         CFG_ERROR_NOARG = -1,
  58
  59         /** An argument is not allowed for an option. */
  60         CFG_ERR_NOTALLOWEDARG = -2,
  61         CFG_ERROR_NOTALLOWEDARG = -2,
  62
  63         /** An option's argument could not be parsed. */
  64         CFG_ERR_BADOPT = -3,
  65         CFG_ERROR_BADOPT = -3,
  66
  67         /** Error in quotations. */
  68         CFG_ERR_BADQUOTE = -4,
  69         CFG_ERROR_BADQUOTE = -4,
  70
  71         /** An option could not be converted to appropriate numeric type. */
  72         CFG_ERR_BADNUMBER = -5,
  73         CFG_ERROR_BADNUMBER = -5,
  74
  75         /** A given number was too big or too small. */
  76         CFG_ERR_OVERFLOW = -6,
  77         CFG_ERROR_OVERFLOW = -6,
  78
  79         /** Multiple arguments used for single option. */
  80         CFG_ERR_MULTI = -7,
  81         CFG_ERROR_MULTI = -7,
  82
  83         /** Not enough memory. */
  84         CFG_ERR_NOMEM = -8,
  85         CFG_ERROR_NOMEM = -8,
  86
  87         /** Stop string was found. */
  88         CFG_ERR_STOP_STR = -9,
  89         CFG_ERR_STOP_STR_FOUND = -9,
  90         CFG_ERROR_STOP_STR = -9,
  91         CFG_ERROR_STOP_STR_FOUND = -9,
  92
  93         /** No equal sign on the line. */
  94         CFG_ERR_NOEQUAL = -10,
  95         CFG_ERROR_NOEQUAL = -10,
  96
  97         /** An unknown option. */
  98         CFG_ERR_UNKNOWN = -11,
  99         CFG_ERROR_UNKNOWN = -11,
 100
 101         /** File not found error. */
 102         CFG_ERR_FILE_NOT_FOUND = -12,
 103         CFG_ERROR_FILE_NOT_FOUND = -12,
 104
 105         /** Seek error (fseek() failure). */
 106         CFG_ERR_SEEK_ERROR = -13,
 107         CFG_ERROR_SEEK_ERROR = -13,
 108
 109         /** Internal error. */
 110         CFG_ERR_INTERNAL = -20,
 111         CFG_ERROR_INTERNAL = -20
 112
 113 }; /* }}} */ /*@}*/
 114
 115 /**
 116  * @name Context flags
 117  */
 118 /*@{*/
 119 /**
 120  * By default are @ref CFG_PROCESS_FIRST, @ref CFG_POSIXLY_LEFTOVERS and
 121  * @ref CFG_NORMAL_LEFTOVERS initialized.
 122  * @todo CFG_APPEND, CFG_OVERWRITE, CFG_APPEND_MULTI_ONLY
 123  */
 124 enum cfg_flag { /* {{{ */
 125
 126         /** Ignore multiple arguments for single option. */
 127         CFG_IGNORE_MULTI = 1,
 128
 129         /** Ignore unknown options. */
 130         CFG_IGNORE_UNKNOWN = 2,
 131
 132         /** Process also the first argument on command line. */
 133         CFG_PROCESS_FIRST = 0,
 134
 135         /** Skip processing of the first argument on command line. */
 136         CFG_SKIP_FIRST = 4,
 137
 138         /** Posixly correct leftover arguments. */
 139         CFG_POSIXLY_LEFTOVERS = 0,
 140
 141         /** Advanced leftover arguments. */
 142         CFG_ADVANCED_LEFTOVERS = 8,
 143
 144         /** Normal leftover arguments initialization in file.
 145           This flag is not used and it is kept from historical reasons. */
 146         CFG_NORMAL_LEFTOVERS = 0,
 147
 148         /** Strict leftover arguments initialization in file.
 149           This flag is not used and it is kept from historical reasons. */
 150         CFG_STRICT_LEFTOVERS = 16,
 151
 152         /** Byte type position usage in file. */
 153         CFG_FILE_BYTE_POS_USAGE = 0,
 154
 155         /** Line type position usage in file. */
 156         CFG_FILE_LINE_POS_USAGE = 32
 157
 158                 /* Ignore all quotations in options arguments. */
 159                 /*
 160                    CFG_USE_QUOTE = 0,
 161                    CFG_IGNORE_QUOTE = 16
 162                    */
 163                 /* Advanced quotations are things like  option = va"'l'"ue
 164                    which resolves to                                    va'l'ue.
 165
 166                    We really want this strange stuff? Any volunter?
 167
 168                    CFG_ADVANCED_QUOTE = 32 + 16
 169                    */
 170
 171 }; /* }}} */ /*@}*/
 172
 173 /**
 174  * @name Option types
 175  */
 176 /*@{*/
 177 /**
 178  * Possible types of options
 179  * @todo Thinking about case insensitivy of option
 180  * ("--input" is the same as "--INPUT")
 181  */
 182 enum cfg_option_type { /* {{{ */
 183
 184         /** Boolean */
 185         CFG_BOOL = 1,
 186         CFG_BOOLEAN = 1,
 187
 188         /** Integer */
 189         CFG_INT = 2,
 190         CFG_INTEGER = 2,
 191
 192         /** Unsigned int */
 193         CFG_UINT = 3,
 194         CFG_UNSIGNED = 3,
 195         CFG_UNSIGNED_INT = 3,
 196
 197         /** Long */
 198         CFG_LONG = 4,
 199
 200         /** Unsigned long */
 201         CFG_ULONG = 5,
 202         CFG_UNSIGNED_LONG = 5,
 203
 204         /** Float */
 205         CFG_FLOAT = 6,
 206
 207         /** Double */
 208         CFG_DOUBLE = 7,
 209
 210         /** String */
 211         CFG_STR = 8,
 212         CFG_STRING = 8,
 213
 214         /** End (to mark last item in list) */
 215         CFG_END = 0,
 216
 217         /** Data type mask (used internally) */
 218         CFG_DATA_TYPE_MASK = 31,
 219
 220         /**
 221          * Single, multi or multi separated. Single by default.
 222          * Tells if option can be repeated.
 223          * In multi case value is array of poiters to type ended with NULL.
 224          */
 225         CFG_SINGLE = 0,
 226         CFG_MULTI = 32,
 227         CFG_MULTI_ARRAY = 32,
 228         CFG_MULTI_SEPARATED = 32 + 64,
 229
 230         /**
 231          * Leftover arguments specification.
 232          * Mark option which will contain leftover arguments.
 233          */
 234         CFG_LAST_ARGS = 128,
 235         CFG_LAST_ARGUMENTS = 128,
 236         CFG_LEFTOVER_ARGS = 128,
 237         CFG_LEFTOVER_ARGUMENTS = 128
 238
 239 }; /* }}} */ /*@}*/
 240
 241 /**
 242  * @name Property types
 243  */
 244 /*@{*/
 245 enum cfg_property_type { /* {{{ */
 246
 247         /**
 248          * @name Property codes
 249          */
 250         /*@{*/
 251
 252         /** Array of strings which forces to stop command line parsing.
 253           By default it is empty. */
 254         CFG_LINE_STOP_STRING = 0,
 255
 256         /** Command line short option prefix.
 257           By default is "-" initialized. */
 258         CFG_LINE_SHORT_OPTION_PREFIX = 1,
 259
 260         /** Command line long option prefix.
 261           By default is "--" initialized. */
 262         CFG_LINE_LONG_OPTION_PREFIX = 2,
 263
 264         /** Command line option argument separator.
 265           By default is "=" initialized. */
 266         CFG_LINE_OPTION_ARG_SEPARATOR = 3,
 267
 268         /** Command line multi values separator.
 269           By default are "," and ";" initialized. */
 270         CFG_LINE_NORMAL_MULTI_VALS_SEPARATOR = 4,
 271
 272         /** Command line multi values leftover arguments separator.
 273           By default it is empty. */
 274         CFG_LINE_LEFTOVER_MULTI_VALS_SEPARATOR = 5,
 275
 276         /** Command line quote prefix & postfix.
 277           By default are apostrophes (') and quotations (") initlized for both.*/
 278         CFG_LINE_QUOTE_PREFIX  = 6,
 279         CFG_LINE_QUOTE_POSTFIX = 7,
 280
 281         /** Array of strings prefixes which forces to stop config file parsing.
 282           By default it is empty. */
 283         CFG_FILE_STOP_PREFIX = 8,
 284
 285         /** Array of string prefixes which mark comment line.
 286           By default are "#" and ";" initialized.  */
 287         CFG_FILE_COMMENT_PREFIX = 9,
 288
 289         /** Array of string postfixes to determine multi lines.
 290           By default is "\\" initialized. */
 291         CFG_FILE_MULTI_LINE_POSTFIX = 10,
 292
 293         /** Config file option argument separator.
 294           By default is "=" initialized. */
 295         CFG_FILE_OPTION_ARG_SEPARATOR = 11,
 296
 297         /** Config file multi values separator.
 298           By default are ",", ";" and " " initialized. */
 299         CFG_FILE_NORMAL_MULTI_VALS_SEPARATOR = 12,
 300
 301         /** Command line multi values leftover arguments separator.
 302           By default is " " initialized. */
 303         CFG_FILE_LEFTOVER_MULTI_VALS_SEPARATOR = 13,
 304
 305         /** Config file quote prefix & postfix.
 306           By default are apostrophes (') and quotations (\") initlized for both.*/
 307         CFG_FILE_QUOTE_PREFIX  = 14,
 308         CFG_FILE_QUOTE_POSTFIX = 15,
 309
 310         /*@}*/
 311
 312         /**
 313          * @name Count of normal properties
 314          */
 315         /*@{*/
 316         /** Special properties count */
 317         CFG_N_PROPS = 16,
 318         /*@}*/
 319
 320         /**
 321          * @name Virtual property codes
 322          */
 323         /*@{*/
 324
 325         /** File quote prefix & postfix */
 326         CFG_QUOTE         = 50,
 327         CFG_LINE_QUOTE    = 51,
 328         CFG_FILE_QUOTE    = 52,
 329         CFG_QUOTE_PREFIX  = 53,
 330         CFG_QUOTE_POSTFIX = 54,
 331
 332         /** Multi values separator */
 333         CFG_MULTI_VALS_SEPARATOR          = 55,
 334         CFG_FILE_MULTI_VALS_SEPARATOR     = 56,
 335         CFG_LINE_MULTI_VALS_SEPARATOR     = 57,
 336         CFG_NORMAL_MULTI_VALS_SEPARATOR   = 58,
 337         CFG_LEFTOVER_MULTI_VALS_SEPARATOR = 59,
 338
 339         /** Option argument separator */
 340         CFG_OPTION_ARG_SEPARATOR = 60
 341                 /*@}*/
 342 }; /* }}} */
 343
 344 /**
 345  * Terminators of variable number arguments in functions cfg_add_properties(),
 346  * cfg_set_properties(), cfg_get_properties() and similar.
 347  */
 348 #define CFG_EOT                 CFG_N_PROPS
 349 #define CFG_END_TYPE    CFG_N_PROPS
 350
 351 /*@}*/
 352
 353 /**
 354  * @name Internal enumerations
 355  */
 356 /*@{*/
 357 /**
 358  * Context type
 359  *
 360  * Possible types of context (used internally)
 361  */
 362 enum cfg_context_type { /* {{{ */
 363
 364         /** No context */
 365         CFG_NO_CONTEXT = 0,
 366
 367         /** Command line context type */
 368         CFG_CMDLINE = 1,
 369         CFG_LINE = 1,
 370
 371         /** Config file context type */
 372         CFG_CFGFILE = 2,
 373         CFG_FILE = 2
 374 }; /* }}} */
 375
 376 /**
 377  * Command line option type.
 378  *
 379  * Possible types of command line option (used internally)
 380  */
 381 enum cfg_line_option_type { /* {{{ */
 382
 383         /** Not long and not short option */
 384         CFG_NONE_OPTION = 0,
 385
 386         /** Short command line option */
 387         CFG_SHORT_OPTION = 1,
 388
 389         /** Long command line option */
 390         CFG_LONG_OPTION = 2,
 391
 392         /** Short command line options */
 393         CFG_SHORT_OPTIONS = 4,
 394
 395         /** Long command line option argument initialized with separator */
 396         CFG_LONG_SEPINIT = 8,
 397
 398         /** Long command line option argument initialized without separator (default) */
 399         CFG_LONG_NOSEPINIT = 0
 400 }; /* }}} */ /*@}*/
 401
 402 /**
 403  * @brief Structure for defining one config option
 404  */
 405 struct cfg_option { /* {{{ */
 406         /** Command line long name (may be NULL) */
 407         const char *cmdline_long_name;
 408         /** Command line short name (may be '\0') */
 409         const char  cmdline_short_name;
 410         /** Config file name (may be NULL) */
 411         const char *cfgfile_name;
 412
 413         /** Option type
 414           @see cfg_option_type */
 415         const enum cfg_option_type type;
 416
 417         /** Pointer where to store value of option */
 418         void *value;
 419
 420         /** Return value (set to 0 for not return) */
 421         int val;
 422 }; /* }}} */
 423
 424 /**
 425  * @brief Main structure for defining context
 426  */
 427 struct cfg_context { /* {{{ */
 428
 429         /**
 430          * @name Shared properties
 431          */
 432         /*@{*/
 433
 434         /** Context type (command line or config file) */
 435         enum cfg_context_type type;
 436
 437         /** Flags */
 438         int flags;
 439
 440         /** Options table */
 441         const struct cfg_option *options;
 442
 443         /** Starting parsing position */
 444         long begin_pos;
 445
 446         /** Number of elements (array arguments, bytes or lines) to parse
 447           (value of -1 means infinite) */
 448         long size;
 449
 450         /** Array of used options indexes */
 451         int *used_opt_idx;
 452
 453         /** Error code of last occured error. */
 454         enum cfg_error error_code;
 455
 456         /** Special properties */
 457         char **prop[CFG_N_PROPS];
 458
 459         /** Currents */
 460         long cur_idx;
 461         long cur_idx_tmp;
 462         int  cur_opt_type;
 463
 464         /** Current option string */
 465         char *cur_opt;
 466
 467         /** Current option argument*/
 468         char *cur_arg;
 469
 470         /*@}*/
 471
 472         /**
 473          * @name Command line specific properties
 474          */
 475         /*@{*/
 476
 477         /** Flag to detect if parsing already started */
 478         int parsing_started:1;
 479
 480         /** NULL terminated array of argument */
 481         char **argv;
 482
 483         /*@}*/
 484
 485         /**
 486          * @name Config file specific properties.
 487          */
 488         /*@{*/
 489
 490         /** Filename (name of file) */
 491         char *filename;
 492
 493         /** Pointer to FILE* structure of parsed file */
 494         FILE *fhandle;
 495
 496         /*@}*/
 497 }; /* }}} */
 498
 499 /**
 500  * @brief Context data type
 501  */
 502 typedef struct cfg_context * CFG_CONTEXT;
 503
 504 /*
 505  * Functions
 506  */
 507
 508 #ifdef __cplusplus
 509 extern "C" {
 510 #endif
 511
 512         /**
 513          * @name Functions and macros for creating and manipulating context
 514          */
 515         /*@{*/ /* {{{ */
 516
 517         /**
 518          * Initialize core context
 519          *
 520          * @param options       pointer to options table
 521          * @return                      initialized core context; further specification
 522          *                                      to command line or config file is required
 523          */
 524         CFG_CONTEXT cfg_get_context(struct cfg_option *options);
 525
 526         /**
 527          * Initialize command line context
 528          *
 529          * @param begin_pos     index of beginning argument of arguments array
 530          * @param size          maximal number of array elements to parse
 531          *                                      (set value of -1 for infinite)
 532          * @param argv          arguments array
 533          * @param options       pointer to options table
 534          * @return                      initialized command line context
 535          */
 536         CFG_CONTEXT cfg_get_cmdline_context(
 537                         long begin_pos,
 538                         long size,
 539                         char **argv,
 540                         struct cfg_option *options);
 541
 542 #define cfg_get_cmdline_context_pos(begin_pos, end_pos, argv, options) \
 543         cfg_get_cmdline_context( \
 544                         begin_pos, \
 545                         end_pos - begin_pos + 1, \
 546                         argv, \
 547                         options)
 548
 549                 /**
 550                  * Initialize command line context by argc and argv passed to main()
 551                  *
 552                  * @param argc          argumet count (argc) passed to function main()
 553                  * @param argv          arguments array (argv) passed to function main()
 554                  * @param options       pointer to options table
 555                  * @return                      initialized command line context
 556                  */
 557                 CFG_CONTEXT cfg_get_cmdline_context_argc(
 558                                 int argc,
 559                                 char **argv,
 560                                 struct cfg_option *options);
 561
 562         /**
 563          * Initialize configuration file context
 564          *
 565          * @param begin_pos     starting position in file to parse
 566          * @param size          maximal number of bytes/lines in file to parse
 567          *                                      (set value of -1 for infinite)
 568          * @param filename      parsed filename
 569          * @param options       pointer to options table
 570          * @return                      initialized command line context
 571          */
 572         CFG_CONTEXT cfg_get_cfgfile_context(
 573                         long begin_pos,
 574                         long size,
 575                         char *filename,
 576                         struct cfg_option *options);
 577
 578 #define cfg_get_cfgfile_context_pos(begin_pos, end_pos, argv, options) \
 579         cfg_get_cfgfile_context( \
 580                         begin_pos, \
 581                         end_pos - begin_pos + 1, \
 582                         argv, \
 583                         options)
 584
 585                 /**
 586                  * Set context to command line
 587                  *
 588                  * @param con           initialized context
 589                  * @param begin_pos     index of beginning argument of arguments array
 590                  * @param size          maximal number of array elements to parse
 591                  *                                      (set value of -1 for infinite)
 592                  * @param argv          arguments array
 593                  * @return                      void
 594                  */
 595                 void cfg_set_cmdline_context(
 596                                 const CFG_CONTEXT con,
 597                                 long begin_pos,
 598                                 long size,
 599                                 char **argv);
 600
 601 #define cfg_set_cmdline_context_pos(con, begin_pos, end_pos, argv) \
 602         cfg_get_cmdline_context( \
 603                         con \
 604                         begin_pos, \
 605                         end_pos - begin_pos + 1, \
 606                         argv)
 607
 608                 /**
 609                  * Set context to command line by argc and argv passed to main()
 610                  *
 611                  * @param con           initialized context
 612                  * @param argc          argumet count (argc) passed to function main()
 613                  * @param argv          arguments array (argv) passed to function main()
 614                  * @return                      initialized command line context
 615                  */
 616                 void cfg_set_cmdline_context_argc(
 617                                 const CFG_CONTEXT con,
 618                                 int argc,
 619                                 char **argv);
 620
 621         /**
 622          * Set context to configuration file
 623          *
 624          * @param con           initialized context
 625          * @param begin_pos     starting position in file to parse
 626          * @param size          maximal number of bytes/lines in file to parse
 627          *                                      (set value of -1 for infinite)
 628          * @param filename      parsed filename
 629          * @return                      void
 630          */
 631         void cfg_set_cfgfile_context(
 632                         const CFG_CONTEXT con,
 633                         long begin_pos,
 634                         long size,
 635                         char *filename);
 636
 637 #define cfg_set_cfgfile_context_pos(con, begin_pos, end_pos, argv) \
 638         cfg_get_cfgfile_context( \
 639                         con \
 640                         begin_pos, \
 641                         end_pos - begin_pos + 1, \
 642                         argv)
 643
 644                 /**
 645                  * Reinitialize popt context
 646                  *
 647                  * @param con           initialized context
 648                  * @return                      void
 649                  */
 650                 void cfg_reset_context(const CFG_CONTEXT con);
 651
 652         /**
 653          * Destroy context
 654          *
 655          * @param con           initialized context
 656          * @return                      void
 657          */
 658         void cfg_free_context(const CFG_CONTEXT con);
 659
 660         /* }}} */ /*@}*/
 661
 662         /**
 663          * @name Functions for setting and clearing context flags
 664          */
 665         /*@{*/ /* {{{ */
 666
 667         /**
 668          * Set context flag
 669          *
 670          * @param con   initialized context
 671          * @param flag  context flag
 672          * @return              void
 673          */
 674         void cfg_set_context_flag(const CFG_CONTEXT con, int flag);
 675
 676         /**
 677          * Clear context flag
 678          *
 679          * @param con   initialized context
 680          * @param flag  context flag
 681          * @return              void
 682          */
 683         void cfg_clear_context_flag(const CFG_CONTEXT con, int flag);
 684
 685         /**
 686          * Get context flag
 687          *
 688          * @param con   initialized context
 689          * @param flag  context flag
 690          * @return              0 on false, non-zero on true
 691          */
 692         int cfg_get_context_flag(const CFG_CONTEXT con, int flag);
 693
 694 #define cfg_is_context_flag(con, flag) cfg_get_context_flag(con, flag)
 695
 696         /**
 697          * Overwrite context flags
 698          *
 699          * @param con   initialized context
 700          * @param flags context flags
 701          * @return              void
 702          */
 703         void cfg_set_context_flags(const CFG_CONTEXT con, int flags);
 704
 705         /**
 706          * Get all context flags
 707          *
 708          * @param con   initialized context
 709          * @return              all context flags
 710          */
 711         int cfg_get_context_flags(const CFG_CONTEXT con);
 712
 713         /* }}} */ /*@}*/
 714
 715         /**
 716          * @name Functions and macros for properties manipulation
 717          */
 718         /*@{*/ /* {{{ */
 719
 720         /**
 721          * Clear all strings of property
 722          *
 723          * @param con   initialized context
 724          * @param type  property type
 725          * @return              1 on success, 0 on not enough memory error
 726          * @see                 cfg_property_type
 727          */
 728         int cfg_clear_property(
 729                         const CFG_CONTEXT con, enum cfg_property_type type);
 730
 731         /**
 732          * Clear all strings of property
 733          *
 734          * @param con   initialized context
 735          * @param type  property type
 736          * @return              1 on success, 0 on not enough memory error
 737          * @see                 cfg_property_type
 738          */
 739         int cfg_clear_properties(
 740                         const CFG_CONTEXT con, enum cfg_property_type type, ...);
 741
 742
 743         /**
 744          * Add string to property
 745          *
 746          * @param con   initialized context
 747          * @param type  property type
 748          * @param str   string for addition
 749          * @return              1 on success, 0 on not enough memory error
 750          * @see                 cfg_property_type
 751          */
 752         int cfg_add_property(
 753                         const CFG_CONTEXT con, enum cfg_property_type type, char *str);
 754
 755         /**
 756          * Add multiple strings to particular properties
 757          *
 758          * @param con   initialized context
 759          * @param type  property type(s)
 760          * @param str   string(s) for addition
 761          * @return              1 on success, 0 on not enough memory error
 762          * @see                 cfg_property_type
 763          *
 764          * Argument list must be terminated with typeN = CFG_EOT or strN = NULL.
 765          * Use constructions like this:<br>
 766          * cfg_add_properties(con, type1, str1, type2, str2, type3=CFG_EOT)
 767          */
 768         int cfg_add_properties(
 769                         const CFG_CONTEXT con, enum cfg_property_type type, char *str, ...);
 770
 771         /**
 772          * Add string to multiple properties
 773          *
 774          * @param con   initialized context
 775          * @param str   string for addition
 776          * @param type  property type(s)
 777          * @return              1 on success, 0 on not enough memory error
 778          * @see                 cfg_property_type
 779          *
 780          * Argument list must be terminated with typeN = CFG_EOT. Use constructions
 781          * like this:<br>
 782          * cfg_add_properties(con, str, type1, type2, type3=CFG_EOT)
 783          */
 784         int cfg_add_properties_str(
 785                         const CFG_CONTEXT con, char *str, enum cfg_property_type type, ...);
 786
 787         /**
 788          * Add multiple strings to one property
 789          *
 790          * @param con   initialized context
 791          * @param type  property type
 792          * @param str   string(s) for addition
 793          * @return              1 on success, 0 on not enough memory error
 794          * @see                 cfg_property_type
 795          *
 796          * Argument list must be terminated with strN = NULL. Use constructions
 797          * like this:<br>
 798          * cfg_add_properties(con, type, str1, str2, str3=NULL)
 799          */
 800         int cfg_add_properties_type(
 801                         const CFG_CONTEXT con, enum cfg_property_type type, char *str, ...);
 802
 803         /**
 804          * Remove string from property
 805          *
 806          * @param con   initialized context
 807          * @param type  property type
 808          * @param str   string for removal
 809          * @return              1 on success, 0 on not enough memory error
 810          * @see                 cfg_property_type
 811          */
 812         int cfg_remove_property(
 813                         const CFG_CONTEXT con, enum cfg_property_type type, char *str);
 814
 815         /**
 816          * Remove multiple strings from particular properties
 817          *
 818          * @param con   initialized context
 819          * @param type  property type(s)
 820          * @param str   string(s) for removal
 821          * @return              1 on success, 0 on not enough memory error
 822          * @see                 cfg_property_type
 823          *
 824          * Argument list must be terminated with typeN = CFG_EOT or strN = NULL.
 825          * Use constructions like this:<br>
 826          * cfg_remove_properties(con, type1, str1, type2, str2, type3=CFG_EOT)
 827          */
 828         int cfg_remove_properties(
 829                         const CFG_CONTEXT con, enum cfg_property_type type, char *str, ...);
 830
 831         /**
 832          * Remove string from multiple properties
 833          *
 834          * @param con   initialized context
 835          * @param str   string for removal
 836          * @param type  property type(s)
 837          * @return              1 on success, 0 on not enough memory error
 838          * @see                 cfg_property_type
 839          *
 840          * Argument list must be terminated with typeN = CFG_EOT. Use constructions
 841          * like this:<br>
 842          * cfg_remove_properties(con, str, type1, type2, type3=CFG_EOT)
 843          */
 844         int cfg_remove_properties_str(
 845                         const CFG_CONTEXT con, char *str, enum cfg_property_type type, ...);
 846
 847         /**
 848          * Remove multiple strings from one property
 849          *
 850          * @param con   initialized context
 851          * @param type  property type
 852          * @param str   string(s) for removal
 853          * @return              1 on success, 0 on not enough memory error
 854          * @see                 cfg_property_type
 855          *
 856          * Argument list must be terminated with strN = NULL. Use constructions
 857          * like this:<br>
 858          * cfg_add_properties(con, type, str1, str2, str3=NULL)
 859          */
 860         int cfg_remove_properties_type(
 861                         const CFG_CONTEXT con, enum cfg_property_type type, char *str, ...);
 862
 863         /* }}} */ /*@}*/
 864
 865         /**
 866          * @name Functions for processing context options
 867          */
 868         /*@{*/ /* {{{ */
 869
 870         /**
 871          * Parse context
 872          *
 873          * @param con   initialized context
 874          * @return              code of error (CFG_ERROR_*)
 875          *                              or CFG_OK if parsing was sucessfull
 876          * @see                 cfg_error
 877          */
 878         int cfg_parse(const CFG_CONTEXT con);
 879
 880         /**
 881          * Parse next option(s) and return its value (if non-zero) or error code.
 882          *
 883          * @param con   initialized context
 884          * @return              next option val, code of error (CFG_ERROR_*)
 885          *                              or CFG_OK on end
 886          * @see                 cfg_error
 887          * @see                 cfg_context
 888          */
 889         int cfg_get_next_opt(const CFG_CONTEXT con);
 890
 891         /**
 892          * Return currently processed option name
 893          *
 894          * @param con   initialized context
 895          * @return              pointer to current option name
 896          */
 897         char *cfg_get_cur_opt(const CFG_CONTEXT con);
 898
 899         /**
 900          * Return currently processed option argument
 901          *
 902          * @param con   initialized context
 903          * @return              pointer to current option argument
 904          */
 905         char *cfg_get_cur_arg(const CFG_CONTEXT con);
 906
 907         /**
 908          * Return currently processed option index (argv index in command line
 909          * context, file byte position or line position in config file context)
 910          *
 911          * @param con   initialized context @return             index of current option
 912          */
 913         int cfg_get_cur_idx(const CFG_CONTEXT con);
 914
 915         /* }}} */ /*@}*/
 916
 917         /**
 918          * @name Error handling functions
 919          */
 920         /*@{*/ /* {{{ */
 921
 922         /**
 923          * Print error string to stderr
 924          *
 925          * @param con           initialized context
 926          * @return                      void
 927          */
 928         void cfg_print_error(const CFG_CONTEXT con);
 929
 930         /**
 931          * Print error string to stream
 932          *
 933          * @param con           initialized context
 934          * @param fh            stream opened for writting
 935          * @return                      void
 936          */
 937         void cfg_fprint_error(const CFG_CONTEXT con, FILE *fh);
 938
 939         /**
 940          * Get error string; error string is dynamically allocated, it needs to be
 941          * freed after use.
 942          *
 943          * @param con           initialized context
 944          * @return                      dynamically allocated error string
 945          */
 946         char *cfg_get_error_str(const CFG_CONTEXT con);
 947
 948         /**
 949          * Get static error string
 950          *
 951          * @param errorcode     code of libcfg error
 952          * @return                      static error string
 953          */
 954         char *cfg_get_static_error_str(const int errorcode);
 955
 956         /* }}} */ /*@}*/
 957
 958 #ifdef __cplusplus
 959 }
 960 #endif
 961
 962 #endif /* _PLATON_CFG_H */
 963
 964 /* Modeline for ViM {{{
 965  * vim:set ts=4:
 966  * vim600:fdm=marker fdl=0 fdc=0:
 967  * }}} */
 968