client/cliparser/argtable3.h

   1 /*******************************************************************************
   2  * argtable3: Declares the main interfaces of the library
   3  *
   4  * This file is part of the argtable3 library.
   5  *
   6  * Copyright (C) 1998-2001,2003-2011,2013 Stewart Heitmann
   7  * <sheitmann@users.sourceforge.net>
   8  * All rights reserved.
   9  *
  10  * Redistribution and use in source and binary forms, with or without
  11  * modification, are permitted provided that the following conditions are met:
  12  *     * Redistributions of source code must retain the above copyright
  13  *       notice, this list of conditions and the following disclaimer.
  14  *     * Redistributions in binary form must reproduce the above copyright
  15  *       notice, this list of conditions and the following disclaimer in the
  16  *       documentation and/or other materials provided with the distribution.
  17  *     * Neither the name of STEWART HEITMANN nor the  names of its contributors
  18  *       may be used to endorse or promote products derived from this software
  19  *       without specific prior written permission.
  20  *
  21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  22  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24  * ARE DISCLAIMED. IN NO EVENT SHALL STEWART HEITMANN BE LIABLE FOR ANY DIRECT,
  25  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  26  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  27  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  28  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  30  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  ******************************************************************************/
  32
  33 #ifndef ARGTABLE3
  34 #define ARGTABLE3
  35
  36 #include <stdio.h> /* FILE */
  37 #include <time.h>  /* struct tm */
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 #define ARG_REX_ICASE 1
  44 #define ARG_DSTR_SIZE 200
  45 #define ARG_CMD_NAME_LEN 100
  46 #define ARG_CMD_DESCRIPTION_LEN 256
  47
  48 #ifndef ARG_REPLACE_GETOPT
  49 #define ARG_REPLACE_GETOPT 1 /* use the embedded getopt as the system getopt(3) */
  50 #endif /* ARG_REPLACE_GETOPT */
  51
  52 /* bit masks for arg_hdr.flag */
  53 enum { ARG_TERMINATOR = 0x1, ARG_HASVALUE = 0x2, ARG_HASOPTVALUE = 0x4 };
  54
  55 #if defined(_WIN32)
  56   #if defined(argtable3_EXPORTS)
  57     #define ARG_EXTERN __declspec(dllexport)
  58   #elif defined(argtable3_IMPORTS)
  59     #define ARG_EXTERN __declspec(dllimport)
  60   #else
  61     #define ARG_EXTERN
  62   #endif
  63 #else
  64   #define ARG_EXTERN
  65 #endif
  66
  67 typedef struct _internal_arg_dstr* arg_dstr_t;
  68 typedef void* arg_cmd_itr_t;
  69
  70 typedef void(arg_resetfn)(void* parent);
  71 typedef int(arg_scanfn)(void* parent, const char* argval);
  72 typedef int(arg_checkfn)(void* parent);
  73 typedef void(arg_errorfn)(void* parent, arg_dstr_t ds, int error, const char* argval, const char* progname);
  74 typedef void(arg_dstr_freefn)(char* buf);
  75 typedef int(arg_cmdfn)(int argc, char* argv[], arg_dstr_t res);
  76 typedef int(arg_comparefn)(const void* k1, const void* k2);
  77
  78 /*
  79  * The arg_hdr struct defines properties that are common to all arg_xxx structs.
  80  * The argtable library requires each arg_xxx struct to have an arg_hdr
  81  * struct as its first data member.
  82  * The argtable library functions then use this data to identify the
  83  * properties of the command line option, such as its option tags,
  84  * datatype string, and glossary strings, and so on.
  85  * Moreover, the arg_hdr struct contains pointers to custom functions that
  86  * are provided by each arg_xxx struct which perform the tasks of parsing
  87  * that particular arg_xxx arguments, performing post-parse checks, and
  88  * reporting errors.
  89  * These functions are private to the individual arg_xxx source code
  90  * and are the pointer to them are initiliased by that arg_xxx struct's
  91  * constructor function. The user could alter them after construction
  92  * if desired, but the original intention is for them to be set by the
  93  * constructor and left unaltered.
  94  */
  95 typedef struct arg_hdr {
  96     char flag;             /* Modifier flags: ARG_TERMINATOR, ARG_HASVALUE. */
  97     const char* shortopts; /* String defining the short options */
  98     const char* longopts;  /* String defiing the long options */
  99     const char* datatype;  /* Description of the argument data type */
 100     const char* glossary;  /* Description of the option as shown by arg_print_glossary function */
 101     int mincount;          /* Minimum number of occurences of this option accepted */
 102     int maxcount;          /* Maximum number of occurences if this option accepted */
 103     void* parent;          /* Pointer to parent arg_xxx struct */
 104     arg_resetfn* resetfn;  /* Pointer to parent arg_xxx reset function */
 105     arg_scanfn* scanfn;    /* Pointer to parent arg_xxx scan function */
 106     arg_checkfn* checkfn;  /* Pointer to parent arg_xxx check function */
 107     arg_errorfn* errorfn;  /* Pointer to parent arg_xxx error function */
 108     void* priv;            /* Pointer to private header data for use by arg_xxx functions */
 109 } arg_hdr_t;
 110
 111 typedef struct arg_rem {
 112     struct arg_hdr hdr; /* The mandatory argtable header struct */
 113 } arg_rem_t;
 114
 115 typedef struct arg_lit {
 116     struct arg_hdr hdr; /* The mandatory argtable header struct */
 117     int count;          /* Number of matching command line args */
 118 } arg_lit_t;
 119
 120 typedef struct arg_int {
 121     struct arg_hdr hdr; /* The mandatory argtable header struct */
 122     int count;          /* Number of matching command line args */
 123     int* ival;          /* Array of parsed argument values */
 124 } arg_int_t;
 125
 126 typedef struct arg_dbl {
 127     struct arg_hdr hdr; /* The mandatory argtable header struct */
 128     int count;          /* Number of matching command line args */
 129     double* dval;       /* Array of parsed argument values */
 130 } arg_dbl_t;
 131
 132 typedef struct arg_str {
 133     struct arg_hdr hdr; /* The mandatory argtable header struct */
 134     int count;          /* Number of matching command line args */
 135     const char** sval;  /* Array of parsed argument values */
 136 } arg_str_t;
 137
 138 typedef struct arg_rex {
 139     struct arg_hdr hdr; /* The mandatory argtable header struct */
 140     int count;          /* Number of matching command line args */
 141     const char** sval;  /* Array of parsed argument values */
 142 } arg_rex_t;
 143
 144 typedef struct arg_file {
 145     struct arg_hdr hdr;     /* The mandatory argtable header struct */
 146     int count;              /* Number of matching command line args*/
 147     const char** filename;  /* Array of parsed filenames  (eg: /home/foo.bar) */
 148     const char** basename;  /* Array of parsed basenames  (eg: foo.bar) */
 149     const char** extension; /* Array of parsed extensions (eg: .bar) */
 150 } arg_file_t;
 151
 152 typedef struct arg_date {
 153     struct arg_hdr hdr; /* The mandatory argtable header struct */
 154     const char* format; /* strptime format string used to parse the date */
 155     int count;          /* Number of matching command line args */
 156     struct tm* tmval;   /* Array of parsed time values */
 157 } arg_date_t;
 158
 159 enum { ARG_ELIMIT = 1, ARG_EMALLOC, ARG_ENOMATCH, ARG_ELONGOPT, ARG_EMISSARG };
 160 typedef struct arg_end {
 161     struct arg_hdr hdr;  /* The mandatory argtable header struct */
 162     int count;           /* Number of errors encountered */
 163     int* error;          /* Array of error codes */
 164     void** parent;       /* Array of pointers to offending arg_xxx struct */
 165     const char** argval; /* Array of pointers to offending argv[] string */
 166 } arg_end_t;
 167
 168 typedef struct arg_cmd_info {
 169     char name[ARG_CMD_NAME_LEN];
 170     char description[ARG_CMD_DESCRIPTION_LEN];
 171     arg_cmdfn* proc;
 172 } arg_cmd_info_t;
 173
 174 /**** arg_xxx constructor functions *********************************/
 175
 176 ARG_EXTERN struct arg_rem* arg_rem(const char* datatype, const char* glossary);
 177
 178 ARG_EXTERN struct arg_lit* arg_lit0(const char* shortopts, const char* longopts, const char* glossary);
 179 ARG_EXTERN struct arg_lit* arg_lit1(const char* shortopts, const char* longopts, const char* glossary);
 180 ARG_EXTERN struct arg_lit* arg_litn(const char* shortopts, const char* longopts, int mincount, int maxcount, const char* glossary);
 181
 182 ARG_EXTERN struct arg_int* arg_int0(const char* shortopts, const char* longopts, const char* datatype, const char* glossary);
 183 ARG_EXTERN struct arg_int* arg_int1(const char* shortopts, const char* longopts, const char* datatype, const char* glossary);
 184 ARG_EXTERN struct arg_int* arg_intn(const char* shortopts, const char* longopts, const char* datatype, int mincount, int maxcount, const char* glossary);
 185
 186 ARG_EXTERN struct arg_dbl* arg_dbl0(const char* shortopts, const char* longopts, const char* datatype, const char* glossary);
 187 ARG_EXTERN struct arg_dbl* arg_dbl1(const char* shortopts, const char* longopts, const char* datatype, const char* glossary);
 188 ARG_EXTERN struct arg_dbl* arg_dbln(const char* shortopts, const char* longopts, const char* datatype, int mincount, int maxcount, const char* glossary);
 189
 190 ARG_EXTERN struct arg_str* arg_str0(const char* shortopts, const char* longopts, const char* datatype, const char* glossary);
 191 ARG_EXTERN struct arg_str* arg_str1(const char* shortopts, const char* longopts, const char* datatype, const char* glossary);
 192 ARG_EXTERN struct arg_str* arg_strn(const char* shortopts, const char* longopts, const char* datatype, int mincount, int maxcount, const char* glossary);
 193
 194 ARG_EXTERN struct arg_rex* arg_rex0(const char* shortopts, const char* longopts, const char* pattern, const char* datatype, int flags, const char* glossary);
 195 ARG_EXTERN struct arg_rex* arg_rex1(const char* shortopts, const char* longopts, const char* pattern, const char* datatype, int flags, const char* glossary);
 196 ARG_EXTERN struct arg_rex* arg_rexn(const char* shortopts,
 197                          const char* longopts,
 198                          const char* pattern,
 199                          const char* datatype,
 200                          int mincount,
 201                          int maxcount,
 202                          int flags,
 203                          const char* glossary);
 204
 205 ARG_EXTERN struct arg_file* arg_file0(const char* shortopts, const char* longopts, const char* datatype, const char* glossary);
 206 ARG_EXTERN struct arg_file* arg_file1(const char* shortopts, const char* longopts, const char* datatype, const char* glossary);
 207 ARG_EXTERN struct arg_file* arg_filen(const char* shortopts, const char* longopts, const char* datatype, int mincount, int maxcount, const char* glossary);
 208
 209 ARG_EXTERN struct arg_date* arg_date0(const char* shortopts, const char* longopts, const char* format, const char* datatype, const char* glossary);
 210 ARG_EXTERN struct arg_date* arg_date1(const char* shortopts, const char* longopts, const char* format, const char* datatype, const char* glossary);
 211 ARG_EXTERN struct arg_date* arg_daten(const char* shortopts, const char* longopts, const char* format, const char* datatype, int mincount, int maxcount, const char* glossary);
 212
 213 ARG_EXTERN struct arg_end* arg_end(int maxerrors);
 214
 215 #define ARG_DSTR_STATIC ((arg_dstr_freefn*)0)
 216 #define ARG_DSTR_VOLATILE ((arg_dstr_freefn*)1)
 217 #define ARG_DSTR_DYNAMIC ((arg_dstr_freefn*)3)
 218
 219 /**** other functions *******************************************/
 220 ARG_EXTERN int arg_nullcheck(void** argtable);
 221 ARG_EXTERN int arg_parse(int argc, char** argv, void** argtable);
 222 ARG_EXTERN void arg_print_option(FILE* fp, const char* shortopts, const char* longopts, const char* datatype, const char* suffix);
 223 ARG_EXTERN void arg_print_syntax(FILE* fp, void** argtable, const char* suffix);
 224 ARG_EXTERN void arg_print_syntaxv(FILE* fp, void** argtable, const char* suffix);
 225 ARG_EXTERN void arg_print_glossary(FILE* fp, void** argtable, const char* format);
 226 ARG_EXTERN void arg_print_glossary_gnu(FILE* fp, void** argtable);
 227 ARG_EXTERN void arg_print_errors(FILE* fp, struct arg_end* end, const char* progname);
 228 ARG_EXTERN void arg_print_option_ds(arg_dstr_t ds, const char* shortopts, const char* longopts, const char* datatype, const char* suffix);
 229 ARG_EXTERN void arg_print_syntax_ds(arg_dstr_t ds, void** argtable, const char* suffix);
 230 ARG_EXTERN void arg_print_syntaxv_ds(arg_dstr_t ds, void** argtable, const char* suffix);
 231 ARG_EXTERN void arg_print_glossary_ds(arg_dstr_t ds, void** argtable, const char* format);
 232 ARG_EXTERN void arg_print_glossary_gnu_ds(arg_dstr_t ds, void** argtable);
 233 ARG_EXTERN void arg_print_errors_ds(arg_dstr_t ds, struct arg_end* end, const char* progname);
 234 ARG_EXTERN void arg_freetable(void** argtable, size_t n);
 235
 236 ARG_EXTERN arg_dstr_t arg_dstr_create(void);
 237 ARG_EXTERN void arg_dstr_destroy(arg_dstr_t ds);
 238 ARG_EXTERN void arg_dstr_reset(arg_dstr_t ds);
 239 ARG_EXTERN void arg_dstr_free(arg_dstr_t ds);
 240 ARG_EXTERN void arg_dstr_set(arg_dstr_t ds, char* str, arg_dstr_freefn* free_proc);
 241 ARG_EXTERN void arg_dstr_cat(arg_dstr_t ds, const char* str);
 242 ARG_EXTERN void arg_dstr_catc(arg_dstr_t ds, char c);
 243 ARG_EXTERN void arg_dstr_catf(arg_dstr_t ds, const char* fmt, ...);
 244 ARG_EXTERN char* arg_dstr_cstr(arg_dstr_t ds);
 245
 246 ARG_EXTERN void arg_cmd_init(void);
 247 ARG_EXTERN void arg_cmd_uninit(void);
 248 ARG_EXTERN void arg_cmd_register(const char* name, arg_cmdfn* proc, const char* description);
 249 ARG_EXTERN void arg_cmd_unregister(const char* name);
 250 ARG_EXTERN int arg_cmd_dispatch(const char* name, int argc, char* argv[], arg_dstr_t res);
 251 ARG_EXTERN unsigned int arg_cmd_count(void);
 252 ARG_EXTERN arg_cmd_info_t* arg_cmd_info(const char* name);
 253 ARG_EXTERN arg_cmd_itr_t arg_cmd_itr_create(void);
 254 ARG_EXTERN void arg_cmd_itr_destroy(arg_cmd_itr_t itr);
 255 ARG_EXTERN int arg_cmd_itr_advance(arg_cmd_itr_t itr);
 256 ARG_EXTERN char* arg_cmd_itr_key(arg_cmd_itr_t itr);
 257 ARG_EXTERN arg_cmd_info_t* arg_cmd_itr_value(arg_cmd_itr_t itr);
 258 ARG_EXTERN int arg_cmd_itr_search(arg_cmd_itr_t itr, void* k);
 259 ARG_EXTERN void arg_mgsort(void* data, int size, int esize, int i, int k, arg_comparefn* comparefn);
 260 ARG_EXTERN void arg_make_get_help_msg(arg_dstr_t res);
 261 ARG_EXTERN void arg_make_help_msg(arg_dstr_t ds, char* cmd_name, void** argtable);
 262 ARG_EXTERN void arg_make_syntax_err_msg(arg_dstr_t ds, void** argtable, struct arg_end* end);
 263 ARG_EXTERN int arg_make_syntax_err_help_msg(arg_dstr_t ds, char* name, int help, int nerrors, void** argtable, struct arg_end* end, int* exitcode);
 264 ARG_EXTERN void arg_set_module_name(const char* name);
 265 ARG_EXTERN void arg_set_module_version(int major, int minor, int patch, const char* tag);
 266
 267 /**** deprecated functions, for back-compatibility only ********/
 268 ARG_EXTERN void arg_free(void** argtable);
 269
 270 #ifdef __cplusplus
 271 }
 272 #endif
 273 #endif