Rev

Rev 2230 | Details | Compare with Previous | Last modification | View Log | SVN | Bug Tracker

Rev Author Line No. Line
2398 filatov 1
/*********************************************************************
2
######################################################################
3
##
4
##  Created by: Denis Filatov
5
##  Date      : 10.11.2005
6
##
7
##      C command line arguments and simple config file parser
8
##
9
##  Copyleft (c) 2003 - 2007
10
##  This code is provided under the CeCill-C license agreement.
11
######################################################################
12
*********************************************************************/
13
#ifndef copts_h
14
#define copts_h
15
#include <stdio.h>
16
 
17
#ifdef __cplusplus
18
extern "C" {
19
#endif
20
 
21
/** @defgroup COPTS copts - Programm line option processing.
22
 * @{ */
23
 
24
#ifndef DOXYGEN
25
    typedef struct copt_t   copt_t;
26
    typedef enum coptflag_t coptflag_t;
27
    typedef enum coptype_t  coptype_t;
28
    typedef enum copterr_t  copterr_t;
29
#endif
30
    /** @enum coptype_t
31
     * Option types definitions.
32
     */
33
    enum coptype_t{
34
        COPT_BOOL ,   /**< Boolean option. Doesn't require arguments.*/
35
        COPT_BOOLI,   /**< Inverted Boolean option. Doesn't require arguments. */
36
        COPT_LONG ,   /**< Requires for long argument */
37
        COPT_ULONG,   /**< Requires for unsigned long argument */
38
        COPT_SHORT,   /**< Requires for short (16 bit) argument */
39
        COPT_USHORT,  /**< Requires for unsigned short argument */
40
        COPT_CHAR ,   /**< Requires for char or unsigned char argument */
41
        COPT_STR  ,   /**< Requires for string (const char *) arguments */
42
        COPT_HOST,    /**< Requires for string (const char *) arguments. Checks url syntax. */
43
        COPT_PATH,    /**< Requires for string (const pchar_t *) arguments. */
44
        COPT_STRLIST, /**< Requires for string list argument (const char *[])
45
                       *   Every time when this opion will be occuren in argv
46
                       *   the value will be assigned to given pointer and
47
                       *   this pointer will be incremented. */
48
        COPT_STRENUM, /**< Requires for one of the string in the array given by vptr)
49
                       *   Array of strings must be terminated by NULL pointer.
50
                       *   After option found the vptr pointer will point
51
                       *   to the element corresponding to the argument */
52
        COPT_CFGFILE, /**< Requires for string (const pchar_t *) arguments.
53
                       *    Treat it as config file name and load if found.
54
                       *    If one or more config file options are exists in copt_t list
55
                       *    this options will be executed before any other options parsing */
56
        COPT_HELP,    /**< Does't require argument.
57
                       *    If this option is occured in command line parsing will be
58
                       *    terminated imediate and COPT_EHELP will be returned */
59
 
60
 
61
        COPT_TYPE_MASK = 0x00FF, /**< Option type mask. For internal usage. */
62
        COPT_CALLBACK  = 0x4000, /**< Mask. Can be or-ed with any other option.
63
                                  *    That's mean treat vptr as a callback addres to call
64
                                  *    when option is occured */
65
        COPT_CONFIG    = 0x8000, /**< Mask. Can be or-ed with any other option.
66
                                  *    That's mean this option can be reached from config file
67
                                  *    and have to be writen to.*/
68
 
69
        COPT_END       = 0xFFFF, /**< End of options.
70
                                  *   If vptr is not NULL, treat it as callback to call for unknown
71
                                  *   options and non-option values */
72
    };
73
 
74
#define COPT_INT      COPT_LONG
75
#define COPT_UINT     COPT_ULONG
76
#define COPT_IBOOL    COPT_BOOLI
77
 
78
    /** Main options item.
79
     *   Have to be used to define options items.
80
     *   Short and long options can be defined.
81
     *   Possible options notations:
82
     *     - Boolean options:
83
     *       - -o
84
     *       - --option
85
     *     - Other types except of boolean:
86
     *       - -o value
87
     *       - -o=value
88
     *       - --option=value
89
     */
90
    struct copt_t
91
    {
92
        const    char*  sopts;   /**< Short options. */
93
        const    char*  lopt;    /**< Long option.   */
94
        const coptype_t type;    /**< Option type ( see @ref coptype_t ). */
95
                 void*  vptr;    /**< Option variable pointer. */
96
        const    char*  helpstr; /**< Option help string. */
97
    };
98
 
99
    /**
100
     * Execute option parser.
101
     * @param argc  Command line parameters count (from arguments of main() for example).
102
     * @param argv  Array of command line parameters.
103
     * @param flags Configuration flags ( @ref coptflag_t ).
104
     * @param opts  Array of possible options. Must be finished by item with COPT_END type.
105
     * @return      <ul><li>On success returns the index of the first option argument in the arguments array.<li>On error returns negative index of the invalid option in the arguments array.</ul>
106
     */
107
    int  coptions(int argc, char* argv[], int flags, copt_t* opts);
108
 
109
    /** Get enum index from the option variable.
110
      * @param opts @ref copt_t array.
111
      * @param idx  Index of the enum option in the array.
112
      * @param ptr  The initial value of the @a vptr field of the opion array item.
113
      * @return the integer enum value of the selected item.
114
     */
115
#define copts_enum_value(opts,idx,ptr) \
116
    ((const char **)((opts)[idx]).vptr) - ((const char **)(ptr))
117
 
118
    /**
119
     * Load options config file.
120
     * @param filename  File path to load.
121
     * @param section   If not NULL then try to find the last occurance of the
122
     *                  given section or load the file complet.
123
     * @param flags     Configuration flags ( see @ref coptflag_t ).
124
     * @param opts      The Array of possible option records. Must be finished
125
     *                  by the item with COPT_END type.
126
     * @return
127
                      <ul><li>On success returns 0.<li>On error returns negative line number of the invalid expression.</ul>
128
     */
129
    int  coptions_load(const char* filename, const char * section, int flags, copt_t* const opts);
130
 
131
    /**
132
     * Save current options to the file
133
     */
134
    int  coptions_save(const char* filename, const copt_t* const opts);
135
 
136
    /**
137
     * Save current options to already opened file
138
     */
139
    int  coptions_fsave(FILE * fd,  const copt_t* const opts);
140
 
141
    /**
142
     * Generate and print the help page.
143
     * @param fd       File descriptor to print the resulting help page.
144
     * @param prgname  Application name. Can be taken from argv[0].
145
     * @param opt      Options array.
146
     * @param usagestr The string to print before option list.
147
     * @param header   Help page header.
148
     * @param footer   Help page footer.
149
 
150
     */
151
    void coptions_help_ex(FILE * fd, const char * prgname, int flags, copt_t* opt, const char* usagestr,
152
                          const char* header, const char* footer);
153
    /** The lite version of the @ref coptions_help_ex.
154
     * @param fd       File descriptor to print the resulting help page.
155
     * @param prgname  Application name. Can be taken from argv[0].
156
     * @param opt      Options array.
157
     * @param usagestr The string to print before option list.
158
     */
159
#define coptions_help(fd,prgname,flags,opt,usagestr) \
160
    coptions_help_ex(fd,prgname,flags,opt,usagestr,NULL,NULL)
161
 
162
    /** Wild value definition */
163
    typedef union{
164
        int            v_boolean;
165
        signed   short v_short;
166
        unsigned short v_ushort;
167
        signed   long  v_long;
168
        unsigned long  v_ulong;
169
        char           v_char;
170
        char *         v_str;
171
    }copt_value_t;
172
 
173
    /** The type of callback function to be called for the option having
174
        @ref COPT_CALLBACK bit set in the @e type field of the @ref copt_t structure.
175
 
176
        These functions must return zero if option was successfully processed,
177
        @ref COPT_EHELP to generate option help string or negative value when
178
        some error was occured.
179
        @param opt The current item of the options array.
180
        @param option String option given.
181
        @param value Pointer to the option value.
182
     */
183
 
184
    typedef int copt_callback(const copt_t * opt, const char * option, const copt_value_t * value);
185
 
186
/** Inverted Boolean True. */
187
#define IBOOL_YES ((void*)-1)
188
 
189
/** @enum coptflag_t
190
    Option flag mask values.
191
*/
192
    enum coptflag_t
193
    {
194
        COPT_DEFAULT       = 0x0000, /**< No special flags given. */
195
        COPT_NOAUTOHELP    = 0x0001, /**< Does not provide automatic help messages. */
196
        COPT_NOCONFIG      = 0x0002, /**< Does not search for config files. */
197
        COPT_NOREORDER     = 0x0004, /**< Does not reorder command line array. */
198
        COPT_NOERR_MSG     = 0x0010, /**< Be silent. */
199
        COPT_NOERR_UNKNOWN = 0x0020, /**< Treat unknown options as non-option args.*/
200
        COPT_NOERR_ARG     = 0x0040, /**< Does not produce an error if the required
201
                                          option's argument is omited or have
202
                                          incompatible type. */
203
        COPT_NOERR         = 0x0070, /**< Does not produce any errors. */
204
        COPT_ERR_CONFIG    = 0x0080, /**< Does not produce config errors. */
205
                COPT_NOHELP_MSG    = 0x0100, /**< Does not print help messages. */
206
                COPT_HELP_NOVALUES = 0x0200, /**< Does not print default values. */
207
        };
208
 
209
    /** @{
210
        @ref coptions return codes.
211
     */
212
    /** Help option (-h or --help) vaw invoked. Need to print help page.*/
213
#define COPT_EHELP   ((int)(0x80000001))
214
    /** Some error was occured.*/
215
#define COPT_ERROR   ((int)(0x80000002))
216
#define COPT_ERC(rc) (rc < 0 && 0==(rc & 0x8000000))
217
    /**@}*/
218
 
219
/** @} */
220
 
221
/**
222
 *   @example test_copts.c
223
 */
224
 
225
#ifdef __cplusplus
226
}
227
#endif
228
 
229
#endif