libcfg+  0.7.0
cfg+.h
Go to the documentation of this file.
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-2015 Platon Group, 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://opensource.platon.sk/projects/libcfg+/
17  */
18 
19 /* $Platon: libcfg+/src/cfg+.h,v 1.61 2015/09/12 04:04:49 nepto Exp $ */
20 
30 #ifndef _PLATON_CFG_H
31 #define _PLATON_CFG_H
32 
33 #include <stdio.h>
34 
36 #define CFG_END_OPTION { NULL, '\0', NULL, CFG_END, NULL, 0 }
37 #define CFG_END_OF_LIST CFG_END_OPTION
46 enum cfg_error { /* {{{ */
47 
52  CFG_OK = 0,
57  CFG_ERROR_NOARG = -1,
58 
61  CFG_ERROR_NOTALLOWEDARG = -2,
62 
65  CFG_ERROR_BADOPT = -3,
66 
69  CFG_ERROR_BADQUOTE = -4,
70 
73  CFG_ERROR_BADNUMBER = -5,
74 
77  CFG_ERROR_OVERFLOW = -6,
78 
81  CFG_ERROR_MULTI = -7,
82 
85  CFG_ERROR_NOMEM = -8,
86 
89  CFG_ERR_STOP_STR_FOUND = -9,
90  CFG_ERROR_STOP_STR = -9,
91  CFG_ERROR_STOP_STR_FOUND = -9,
92 
95  CFG_ERROR_NOEQUAL = -10,
96 
99  CFG_ERROR_UNKNOWN = -11,
100 
103  CFG_ERROR_FILE_NOT_FOUND = -12,
104 
107  CFG_ERROR_SEEK_ERROR = -13,
108 
111  CFG_ERROR_INTERNAL = -20
112 
113 }; /* }}} */ /*@}*/
114 
124 enum cfg_flag { /* {{{ */
125 
128 
131 
134 
137 
140 
143 
147 
151 
154 
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 
182 enum cfg_option_type { /* {{{ */
183 
185  CFG_BOOL = 1,
186  CFG_BOOLEAN = 1,
187 
189  CFG_INT = 2,
190  CFG_INTEGER = 2,
191 
193  CFG_UINT = 3,
194  CFG_UNSIGNED = 3,
195  CFG_UNSIGNED_INT = 3,
196 
198  CFG_LONG = 4,
199 
202  CFG_UNSIGNED_LONG = 5,
203 
206 
209 
211  CFG_STR = 8,
212  CFG_STRING = 8,
213 
215  CFG_END = 0,
216 
219 
226  CFG_MULTI = 32,
227  CFG_MULTI_ARRAY = 32,
228  CFG_MULTI_SEPARATED = 32 + 64,
229 
235  CFG_LAST_ARGUMENTS = 128,
236  CFG_LEFTOVER_ARGS = 128,
237  CFG_LEFTOVER_ARGUMENTS = 128
238 
239 }; /* }}} */ /*@}*/
240 
245 enum cfg_property_type { /* {{{ */
246 
251 
255 
259 
263 
267 
271 
275 
280 
284 
288 
292 
296 
300 
304 
309 
324 
326  CFG_QUOTE = 50,
331 
338 
342 }; /* }}} */
343 
348 #define CFG_EOT CFG_N_PROPS
349 #define CFG_END_TYPE CFG_N_PROPS
350 
362 enum cfg_context_type { /* {{{ */
363 
366 
369  CFG_LINE = 1,
370 
373  CFG_FILE = 2
374 }; /* }}} */
375 
381 enum cfg_line_option_type { /* {{{ */
382 
385 
388 
391 
394 
397 
400 }; /* }}} */ /*@}*/
401 
405 struct cfg_option { /* {{{ */
407  const char *cmdline_long_name;
409  const char cmdline_short_name;
411  const char *cfgfile_name;
412 
415  const enum cfg_option_type type;
416 
418  void *value;
419 
421  int val;
422 }; /* }}} */
423 
427 struct cfg_context { /* {{{ */
428 
433 
436 
438  int flags;
439 
441  const struct cfg_option *options;
442 
444  long begin_pos;
445 
448  long size;
449 
452 
455 
457  char **prop[CFG_N_PROPS];
458 
460  long cur_idx;
463 
465  char *cur_opt;
466 
468  char *cur_arg;
469 
476 
479 
481  char **argv;
482 
489 
491  char *filename;
492 
494  FILE *fhandle;
495 
497 }; /* }}} */
498 
502 typedef struct cfg_context * CFG_CONTEXT;
503 
504 /*
505  * Functions
506  */
507 
508 #ifdef __cplusplus
509 extern "C" {
510 #endif
511 
515  /* {{{ */
516 
524  CFG_CONTEXT cfg_get_context(struct cfg_option *options);
525 
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 
557  CFG_CONTEXT cfg_get_cmdline_context_argc(
558  int argc,
559  char **argv,
560  struct cfg_option *options);
561 
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 
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 
617  const CFG_CONTEXT con,
618  int argc,
619  char **argv);
620 
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 
650  void cfg_reset_context(const CFG_CONTEXT con);
651 
658  void cfg_free_context(const CFG_CONTEXT con);
659 
660  /* }}} */ /*@}*/
661 
665  /* {{{ */
666 
674  void cfg_set_context_flag(const CFG_CONTEXT con, int flag);
675 
683  void cfg_clear_context_flag(const CFG_CONTEXT con, int flag);
684 
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 
703  void cfg_set_context_flags(const CFG_CONTEXT con, int flags);
704 
711  int cfg_get_context_flags(const CFG_CONTEXT con);
712 
713  /* }}} */ /*@}*/
714 
718  /* {{{ */
719 
728  int cfg_clear_property(
729  const CFG_CONTEXT con, enum cfg_property_type type);
730 
740  const CFG_CONTEXT con, enum cfg_property_type type, ...);
741 
742 
752  int cfg_add_property(
753  const CFG_CONTEXT con, enum cfg_property_type type, char *str);
754 
768  int cfg_add_properties(
769  const CFG_CONTEXT con, enum cfg_property_type type, char *str, ...);
770 
785  const CFG_CONTEXT con, char *str, enum cfg_property_type type, ...);
786 
801  const CFG_CONTEXT con, enum cfg_property_type type, char *str, ...);
802 
813  const CFG_CONTEXT con, enum cfg_property_type type, char *str);
814 
829  const CFG_CONTEXT con, enum cfg_property_type type, char *str, ...);
830 
845  const CFG_CONTEXT con, char *str, enum cfg_property_type type, ...);
846 
861  const CFG_CONTEXT con, enum cfg_property_type type, char *str, ...);
862 
863  /* }}} */ /*@}*/
864 
868  /* {{{ */
869 
878  int cfg_parse(const CFG_CONTEXT con);
879 
889  int cfg_get_next_opt(const CFG_CONTEXT con);
890 
897  char *cfg_get_cur_opt(const CFG_CONTEXT con);
898 
905  char *cfg_get_cur_arg(const CFG_CONTEXT con);
906 
913  int cfg_get_cur_idx(const CFG_CONTEXT con);
914 
915  /* }}} */ /*@}*/
916 
920  /* {{{ */
921 
928  void cfg_print_error(const CFG_CONTEXT con);
929 
937  void cfg_fprint_error(const CFG_CONTEXT con, FILE *fh);
938 
946  char *cfg_get_error_str(const CFG_CONTEXT con);
947 
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 
int parsing_started
Flag to detect if parsing already started.
Definition: cfg+.h:478
Config file quote prefix & postfix.
Definition: cfg+.h:307
cfg_context_type
Context type.
Definition: cfg+.h:362
Line type position usage in file.
Definition: cfg+.h:156
Float.
Definition: cfg+.h:205
void cfg_set_cfgfile_context(const CFG_CONTEXT con, long begin_pos, long size, char *filename)
Set context to configuration file.
enum cfg_option_type type
Option type.
Definition: cfg+.h:415
Data type mask (used internally)
Definition: cfg+.h:218
long size
Number of elements (array arguments, bytes or lines) to parse (value of -1 means infinite) ...
Definition: cfg+.h:448
Array of strings which forces to stop command line parsing.
Definition: cfg+.h:308
File not found error.
Definition: cfg+.h:102
Config file context type.
Definition: cfg+.h:372
Strict leftover arguments initialization in file.
Definition: cfg+.h:150
Config file multi values separator.
Definition: cfg+.h:299
Array of strings prefixes which forces to stop config file parsing.
Definition: cfg+.h:283
Unsigned int.
Definition: cfg+.h:193
Integer.
Definition: cfg+.h:189
const struct cfg_option * options
Options table.
Definition: cfg+.h:441
Error in quotations.
Definition: cfg+.h:68
Command line quote prefix & postfix.
Definition: cfg+.h:278
int cfg_get_context_flags(const CFG_CONTEXT con)
Get all context flags.
An unknown option.
Definition: cfg+.h:98
Normal leftover arguments initialization in file.
Definition: cfg+.h:146
int cfg_add_properties_type(const CFG_CONTEXT con, enum cfg_property_type type, char *str,...)
Add multiple strings to one property.
void cfg_set_cmdline_context_argc(const CFG_CONTEXT con, int argc, char **argv)
Set context to command line by argc and argv passed to main()
int cfg_parse(const CFG_CONTEXT con)
Parse context.
FILE * fhandle
Pointer to FILE* structure of parsed file.
Definition: cfg+.h:494
Seek error (fseek() failure).
Definition: cfg+.h:106
const char * cfgfile_name
Config file name (may be NULL)
Definition: cfg+.h:411
CFG_CONTEXT cfg_get_cmdline_context_argc(int argc, char **argv, struct cfg_option *options)
Initialize command line context by argc and argv passed to main()
long cur_idx
Currents.
Definition: cfg+.h:460
File quote prefix & postfix.
Definition: cfg+.h:329
int * used_opt_idx
Array of used options indexes.
Definition: cfg+.h:451
An argument is missing for an option.
Definition: cfg+.h:56
Multiple arguments used for single option.
Definition: cfg+.h:80
int cfg_remove_property(const CFG_CONTEXT con, enum cfg_property_type type, char *str)
Remove string from property.
int cfg_remove_properties_str(const CFG_CONTEXT con, char *str, enum cfg_property_type type,...)
Remove string from multiple properties.
char ** argv
NULL terminated array of argument.
Definition: cfg+.h:481
int cfg_add_properties_str(const CFG_CONTEXT con, char *str, enum cfg_property_type type,...)
Add string to multiple properties.
Command line multi values leftover arguments separator.
Definition: cfg+.h:274
Structure for defining one config option.
Definition: cfg+.h:405
char ** prop[CFG_N_PROPS]
Special properties.
Definition: cfg+.h:457
Single, multi or multi separated.
Definition: cfg+.h:225
String.
Definition: cfg+.h:211
int cfg_clear_properties(const CFG_CONTEXT con, enum cfg_property_type type,...)
Clear all strings of property.
const char * cmdline_long_name
Command line long name (may be NULL)
Definition: cfg+.h:407
cfg_line_option_type
Command line option type.
Definition: cfg+.h:381
OK, all is right.
Definition: cfg+.h:50
int val
Return value (set to 0 for not return)
Definition: cfg+.h:421
File quote prefix & postfix.
Definition: cfg+.h:328
Special properties count.
Definition: cfg+.h:317
Array of strings which forces to stop command line parsing.
Definition: cfg+.h:254
Array of string prefixes which mark comment line.
Definition: cfg+.h:287
File quote prefix & postfix.
Definition: cfg+.h:334
Posixly correct leftover arguments.
Definition: cfg+.h:139
Ignore multiple arguments for single option.
Definition: cfg+.h:127
Command line context type.
Definition: cfg+.h:368
File quote prefix & postfix.
Definition: cfg+.h:326
char * cfg_get_error_str(const CFG_CONTEXT con)
Get error string; error string is dynamically allocated, it needs to be freed after use...
Array of strings which forces to stop command line parsing.
Definition: cfg+.h:279
Command line long option prefix.
Definition: cfg+.h:262
enum cfg_context_type type
Context type (command line or config file)
Definition: cfg+.h:435
Double.
Definition: cfg+.h:208
CFG_CONTEXT cfg_get_cfgfile_context(long begin_pos, long size, char *filename, struct cfg_option *options)
Initialize configuration file context.
Command line option argument separator.
Definition: cfg+.h:266
int cfg_get_next_opt(const CFG_CONTEXT con)
Parse next option(s) and return its value (if non-zero) or error code.
File quote prefix & postfix.
Definition: cfg+.h:337
Byte type position usage in file.
Definition: cfg+.h:153
CFG_CONTEXT cfg_get_context(struct cfg_option *options)
Initialize core context.
long cur_idx_tmp
Context type (command line or config file)
Definition: cfg+.h:461
Short command line options.
Definition: cfg+.h:393
Command line multi values leftover arguments separator.
Definition: cfg+.h:303
int cfg_add_properties(const CFG_CONTEXT con, enum cfg_property_type type, char *str,...)
Add multiple strings to particular properties.
int cfg_get_cur_idx(const CFG_CONTEXT con)
Return currently processed option index (argv index in command line context, file byte position or li...
Long.
Definition: cfg+.h:198
Short command line option.
Definition: cfg+.h:387
Not enough memory.
Definition: cfg+.h:84
An argument is not allowed for an option.
Definition: cfg+.h:60
OK, all is right.
Definition: cfg+.h:51
Option argument separator.
Definition: cfg+.h:340
void * value
Pointer where to store value of option.
Definition: cfg+.h:418
struct cfg_context * CFG_CONTEXT
Context data type.
Definition: cfg+.h:502
File quote prefix & postfix.
Definition: cfg+.h:327
char * cfg_get_cur_opt(const CFG_CONTEXT con)
Return currently processed option name.
Unsigned long.
Definition: cfg+.h:201
Long command line option argument initialized without separator (default)
Definition: cfg+.h:399
void cfg_reset_context(const CFG_CONTEXT con)
Reinitialize popt context.
File quote prefix & postfix.
Definition: cfg+.h:335
Internal error.
Definition: cfg+.h:110
int cfg_remove_properties(const CFG_CONTEXT con, enum cfg_property_type type, char *str,...)
Remove multiple strings from particular properties.
long begin_pos
Starting parsing position.
Definition: cfg+.h:444
int cfg_remove_properties_type(const CFG_CONTEXT con, enum cfg_property_type type, char *str,...)
Remove multiple strings from one property.
File quote prefix & postfix.
Definition: cfg+.h:336
Not long and not short option.
Definition: cfg+.h:384
cfg_property_type
Terminators of variable number arguments in functions cfg_add_properties(), cfg_set_properties(), cfg_get_properties() and similar.
Definition: cfg+.h:245
void cfg_clear_context_flag(const CFG_CONTEXT con, int flag)
Clear context flag.
File quote prefix & postfix.
Definition: cfg+.h:330
Boolean.
Definition: cfg+.h:185
char * cur_arg
Current option argument.
Definition: cfg+.h:468
Ignore unknown options.
Definition: cfg+.h:130
Stop string was found.
Definition: cfg+.h:88
int cfg_clear_property(const CFG_CONTEXT con, enum cfg_property_type type)
Clear all strings of property.
An option's argument could not be parsed.
Definition: cfg+.h:64
Config file option argument separator.
Definition: cfg+.h:295
void cfg_set_context_flag(const CFG_CONTEXT con, int flag)
Set context flag.
Skip processing of the first argument on command line.
Definition: cfg+.h:136
cfg_flag
By default are CFG_PROCESS_FIRST, CFG_POSIXLY_LEFTOVERS and CFG_NORMAL_LEFTOVERS initialized.
Definition: cfg+.h:124
cfg_option_type
Possible types of options.
Definition: cfg+.h:182
A given number was too big or too small.
Definition: cfg+.h:76
char * cur_opt
Current option string.
Definition: cfg+.h:465
void cfg_print_error(const CFG_CONTEXT con)
Print error string to stderr.
CFG_CONTEXT cfg_get_cmdline_context(long begin_pos, long size, char **argv, struct cfg_option *options)
Initialize command line context.
int cfg_get_context_flag(const CFG_CONTEXT con, int flag)
Get context flag.
Advanced leftover arguments.
Definition: cfg+.h:142
enum cfg_error error_code
Error code of last occured error.
Definition: cfg+.h:454
char * filename
Filename (name of file)
Definition: cfg+.h:491
An option could not be converted to appropriate numeric type.
Definition: cfg+.h:72
Leftover arguments specification.
Definition: cfg+.h:234
No equal sign on the line.
Definition: cfg+.h:94
Main structure for defining context.
Definition: cfg+.h:427
Long command line option.
Definition: cfg+.h:390
Array of string postfixes to determine multi lines.
Definition: cfg+.h:291
Multi values separator.
Definition: cfg+.h:333
Command line multi values separator.
Definition: cfg+.h:270
void cfg_set_cmdline_context(const CFG_CONTEXT con, long begin_pos, long size, char **argv)
Set context to command line.
void cfg_set_context_flags(const CFG_CONTEXT con, int flags)
Overwrite context flags.
int flags
Flags.
Definition: cfg+.h:438
const char cmdline_short_name
Command line short name (may be '\0')
Definition: cfg+.h:409
Process also the first argument on command line.
Definition: cfg+.h:133
char * cfg_get_static_error_str(const int errorcode)
Get static error string.
OK, all is right.
Definition: cfg+.h:52
int cur_opt_type
Context type (command line or config file)
Definition: cfg+.h:462
char * cfg_get_cur_arg(const CFG_CONTEXT con)
Return currently processed option argument.
int cfg_add_property(const CFG_CONTEXT con, enum cfg_property_type type, char *str)
Add string to property.
cfg_error
Possible return values returned by parsing functions.
Definition: cfg+.h:46
void cfg_fprint_error(const CFG_CONTEXT con, FILE *fh)
Print error string to stream.
End (to mark last item in list)
Definition: cfg+.h:215
void cfg_free_context(const CFG_CONTEXT con)
Destroy context.
Command line short option prefix.
Definition: cfg+.h:258
Long command line option argument initialized with separator.
Definition: cfg+.h:396
No context.
Definition: cfg+.h:365

libcfg+ developer documentation generated by Doxygen