silo/masstree/clp.h

   1 /* Masstree
   2  * Eddie Kohler, Yandong Mao, Robert Morris
   3  * Copyright (c) 2012-2013 President and Fellows of Harvard College
   4  * Copyright (c) 2012-2013 Massachusetts Institute of Technology
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining a
   7  * copy of this software and associated documentation files (the "Software"),
   8  * to deal in the Software without restriction, subject to the conditions
   9  * listed in the Masstree LICENSE file. These conditions include: you must
  10  * preserve this copyright notice, and you cannot mention the copyright
  11  * holders in advertising related to the Software without their permission.
  12  * The Software is provided WITHOUT ANY WARRANTY, EXPRESS OR IMPLIED. This
  13  * notice is a summary of the Masstree LICENSE file; the license in that file
  14  * is legally binding.
  15  */
  16 #ifndef LCDF_CLP_H
  17 #define LCDF_CLP_H
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 /* clp.h - Public interface to CLP.
  23  * This file is part of CLP, the command line parser package.
  24  *
  25  * Copyright (c) 1997-2014 Eddie Kohler, ekohler@gmail.com
  26  *
  27  * CLP is free software. It is distributed under the GNU General Public
  28  * License, Version 2, or, alternatively and at your discretion, under the
  29  * more permissive (BSD-like) Click LICENSE file as described below.
  30  *
  31  * Permission is hereby granted, free of charge, to any person obtaining a
  32  * copy of this software and associated documentation files (the
  33  * "Software"), to deal in the Software without restriction, subject to the
  34  * conditions listed in the Click LICENSE file, which is available in full at
  35  * http://github.com/kohler/click/blob/master/LICENSE. The conditions
  36  * include: you must preserve this copyright notice, and you cannot mention
  37  * the copyright holders in advertising related to the Software without
  38  * their permission. The Software is provided WITHOUT ANY WARRANTY, EXPRESS
  39  * OR IMPLIED. This notice is a summary of the Click LICENSE file; the
  40  * license in that file is binding. */
  41
  42 #include <stdio.h>
  43 #include <stdarg.h>
  44
  45 typedef struct Clp_Option Clp_Option;
  46 typedef struct Clp_Parser Clp_Parser;
  47 typedef struct Clp_ParserState Clp_ParserState;
  48
  49
  50 /** @brief Option description.
  51  *
  52  * CLP users declare arrays of Clp_Option structures to specify what options
  53  * should be parsed.
  54  * @sa Clp_NewParser, Clp_SetOptions */
  55 struct Clp_Option {
  56     const char *long_name;      /**< Name of long option, or NULL if the option
  57                                      has no long name. */
  58     int short_name;             /**< Character defining short option, or 0 if
  59                                      the option has no short name. */
  60     int option_id;              /**< User-specified ID defining option,
  61                                      returned by Clp_Next. */
  62     int val_type;               /**< ID of option's value type, or 0 if option
  63                                      takes no value. */
  64     int flags;                  /**< Option parsing flags. */
  65 };
  66
  67 /** @name Value types
  68  * These values describe the type of an option's argument and are used in
  69  * the Clp_Option val_type field.  For example, if an option took integers, its
  70  * Clp_Option structure would have val_type set to Clp_ValInt. */
  71 /**@{*/
  72 #define Clp_NoVal               0       /**< @brief Option takes no value. */
  73 #define Clp_ValString           1       /**< @brief Option value is an
  74                                              arbitrary string. */
  75 #define Clp_ValStringNotOption  2       /**< @brief Option value is a
  76                                              non-option string.
  77
  78                 See Clp_DisallowOptions. */
  79 #define Clp_ValBool             3       /**< @brief Option value is a
  80                                              boolean.
  81
  82                 Accepts "true", "false", "yes", "no", "1", and "0", or any
  83                 prefixes thereof.  The match is case-insensitive. */
  84 #define Clp_ValInt              4       /**< @brief Option value is a
  85                                              signed int.
  86
  87                 Accepts an optional "+" or "-" sign, followed by one or more
  88                 digits.  The digits may be include a "0x" or "0X" prefix, for
  89                 a hexadecimal number, or a "0" prefix, for an octal number;
  90                 otherwise it is decimal. */
  91 #define Clp_ValUnsigned         5       /**< @brief Option value is an
  92                                              unsigned int.
  93
  94                 Accepts an optional "+" sign, followed by one or more
  95                 digits.  The digits may be include a "0x" or "0X" prefix, for
  96                 a hexadecimal number, or a "0" prefix, for an octal number;
  97                 otherwise it is decimal. */
  98 #define Clp_ValLong             6       /**< @brief Option value is a
  99                                              signed long. */
 100 #define Clp_ValUnsignedLong     7       /**< @brief Option value is an
 101                                              unsigned long. */
 102 #define Clp_ValDouble           8       /**< @brief Option value is a
 103                                              double.
 104                 Accepts a real number as defined by strtod(). */
 105 #define Clp_ValFirstUser        10      /**< @brief Value types >=
 106                                              Clp_ValFirstUser are available
 107                                              for user types. */
 108 /**@}*/
 109
 110 /** @name Option flags
 111  * These flags are used in the Clp_Option flags field. */
 112 /**@{*/
 113 #define Clp_Mandatory           (1<<0)  /**< @brief Option flag: value
 114                                              is mandatory.
 115
 116                 It is an error if the option has no value.  This is the
 117                 default if an option has arg_type != 0 and the Clp_Optional
 118                 flag is not provided. */
 119 #define Clp_Optional            (1<<1)  /**< @brief Option flag: value
 120                                              is optional. */
 121 #define Clp_Negate              (1<<2)  /**< @brief Option flag: option
 122                                              may be negated.
 123
 124                 --no-[long_name] will be accepted in argument lists. */
 125 #define Clp_OnlyNegated         (1<<3)  /**< @brief Option flag: option
 126                                              <em>must</em> be negated.
 127
 128                 --no-[long_name] will be accepted in argument lists, but
 129                 --[long_name] will not.  This is the default if long_name
 130                 begins with "no-". */
 131 #define Clp_PreferredMatch      (1<<4)  /**< @brief Option flag: prefer this
 132                                              option when matching.
 133
 134                 Prefixes of --[long_name] should map to this option, even if
 135                 other options begin with --[long_name]. */
 136 /**@}*/
 137
 138 /** @name Option character types
 139  * These flags are used in to define character types in Clp_SetOptionChar(). */
 140 /**@{*/
 141 /*      Clp_NotOption           0 */
 142 #define Clp_Short               (1<<0)  /**< @brief Option character begins
 143                                              a set of short options. */
 144 #define Clp_Long                (1<<1)  /**< @brief Option character begins
 145                                              a long option. */
 146 #define Clp_ShortNegated        (1<<2)  /**< @brief Option character begins
 147                                              a set of negated short options. */
 148 #define Clp_LongNegated         (1<<3)  /**< @brief Option character begins
 149                                              a negated long option. */
 150 #define Clp_LongImplicit        (1<<4)  /**< @brief Option character can begin
 151                                              a long option, and is part of that
 152                                              long option. */
 153 /**@}*/
 154
 155 #define Clp_NotOption           0       /**< @brief Clp_Next value: argument
 156                                              was not an option. */
 157 #define Clp_Done                -1      /**< @brief Clp_Next value: there are
 158                                              no more arguments. */
 159 #define Clp_BadOption           -2      /**< @brief Clp_Next value: argument
 160                                              was an erroneous option. */
 161 #define Clp_Error               -3      /**< @brief Clp_Next value: internal
 162                                              CLP error. */
 163
 164 #define Clp_ValSize             40      /**< @brief Minimum size of the
 165                                              Clp_Parser val.cs field. */
 166 #define Clp_ValIntSize          10      /**< @brief Minimum size of the
 167                                              Clp_Parser val.is field. */
 168
 169
 170 /** @brief A value parsing function.
 171  * @param clp the parser
 172  * @param vstr the value to be parsed
 173  * @param complain if nonzero, report error messages via Clp_OptionError
 174  * @param user_data user data passed to Clp_AddType()
 175  * @return 1 if parsing succeeded, 0 otherwise
 176  */
 177 typedef int (*Clp_ValParseFunc)(Clp_Parser *clp, const char *vstr,
 178                                 int complain, void *user_data);
 179
 180 /** @brief A function for reporting option errors.
 181  * @param clp the parser
 182  * @param message error message
 183  */
 184 typedef void (*Clp_ErrorHandler)(Clp_Parser *clp, const char *message);
 185
 186
 187 /** @brief Command line parser.
 188  *
 189  * A Clp_Parser object defines an instance of CLP, including allowed options,
 190  * value types, and current arguments.
 191  * @sa Clp_NewParser, Clp_SetOptions, Clp_SetArguments */
 192 struct Clp_Parser {
 193     const Clp_Option *option;   /**< The last option. */
 194
 195     int negated;                /**< Whether the last option was negated. */
 196
 197     int have_val;               /**< Whether the last option had a value. */
 198     const char *vstr;           /**< The string value provided with the last
 199                                      option. */
 200
 201     union {
 202         int i;
 203         unsigned u;
 204         long l;
 205         unsigned long ul;
 206         double d;
 207         const char *s;
 208         void *pv;
 209 #ifdef HAVE_INT64_TYPES
 210         int64_t i64;
 211         uint64_t u64;
 212 #endif
 213         char cs[Clp_ValSize];
 214         unsigned char ucs[Clp_ValSize];
 215         int is[Clp_ValIntSize];
 216         unsigned us[Clp_ValIntSize];
 217     } val;                      /**< The parsed value provided with the last
 218                                      option. */
 219
 220     void *user_data;            /**< Uninterpreted by CLP; users can set
 221                                      arbitrarily. */
 222
 223     struct Clp_Internal *internal;
 224 };
 225
 226 /** @cond never */
 227 #if __GNUC__ >= 4
 228 # define CLP_SENTINEL           __attribute__((sentinel))
 229 #else
 230 # define CLP_SENTINEL           /* nothing */
 231 #endif
 232 /** @endcond never */
 233
 234
 235 /** @brief Create a new Clp_Parser. */
 236 Clp_Parser *Clp_NewParser(int argc, const char * const *argv,
 237                           int nopt, const Clp_Option *opt);
 238
 239 /** @brief Destroy a Clp_Parser object. */
 240 void Clp_DeleteParser(Clp_Parser *clp);
 241
 242
 243 /** @brief Return @a clp's program name. */
 244 const char *Clp_ProgramName(Clp_Parser *clp);
 245
 246 /** @brief Set @a clp's program name. */
 247 const char *Clp_SetProgramName(Clp_Parser *clp, const char *name);
 248
 249
 250 /** @brief Set @a clp's error handler function. */
 251 Clp_ErrorHandler Clp_SetErrorHandler(Clp_Parser *clp, Clp_ErrorHandler errh);
 252
 253 /** @brief Set @a clp's UTF-8 mode. */
 254 int Clp_SetUTF8(Clp_Parser *clp, int utf8);
 255
 256 /** @brief Return @a clp's treatment of character @a c. */
 257 int Clp_OptionChar(Clp_Parser *clp, int c);
 258
 259 /** @brief Set @a clp's treatment of character @a c. */
 260 int Clp_SetOptionChar(Clp_Parser *clp, int c, int type);
 261
 262 /** @brief Set @a clp's option definitions. */
 263 int Clp_SetOptions(Clp_Parser *clp, int nopt, const Clp_Option *opt);
 264
 265 /** @brief Set @a clp's arguments. */
 266 void Clp_SetArguments(Clp_Parser *clp, int argc, const char * const *argv);
 267
 268 /** @brief Set whether @a clp is searching for options. */
 269 int Clp_SetOptionProcessing(Clp_Parser *clp, int on);
 270
 271
 272 #define Clp_DisallowOptions     (1<<0)  /**< @brief Value type flag: value
 273                                              can't be an option string.
 274
 275                 See Clp_AddType(). */
 276
 277 /** @brief Define a new value type for @a clp. */
 278 int Clp_AddType(Clp_Parser *clp, int val_type, int flags,
 279                 Clp_ValParseFunc parser, void *user_data);
 280
 281
 282 #define Clp_AllowNumbers        (1<<0)  /**< @brief String list flag: allow
 283                                              explicit numbers.
 284
 285                 See Clp_AddStringListType() and Clp_AddStringListTypeVec(). */
 286 #define Clp_StringListLong      (1<<1)  /**< @brief String list flag: values
 287                                              have long type. */
 288
 289 /** @brief Define a new string list value type for @a clp. */
 290 int Clp_AddStringListTypeVec(Clp_Parser *clp, int val_type, int flags,
 291                              int nstrs, const char * const *strs,
 292                              const int *vals);
 293
 294 /** @brief Define a new string list value type for @a clp. */
 295 int Clp_AddStringListType(Clp_Parser *clp, int val_type, int flags, ...)
 296                           CLP_SENTINEL;
 297
 298
 299 /** @brief Parse and return the next argument from @a clp. */
 300 int Clp_Next(Clp_Parser *clp);
 301
 302 /** @brief Return the next argument from @a clp without option parsing. */
 303 const char *Clp_Shift(Clp_Parser *clp, int allow_options);
 304
 305
 306 /** @brief Create a new Clp_ParserState. */
 307 Clp_ParserState *Clp_NewParserState(void);
 308
 309 /** @brief Destroy a Clp_ParserState object. */
 310 void Clp_DeleteParserState(Clp_ParserState *state);
 311
 312 /** @brief Save @a clp's current state in @a state. */
 313 void Clp_SaveParser(const Clp_Parser *clp, Clp_ParserState *state);
 314
 315 /** @brief Restore parser state from @a state into @a clp. */
 316 void Clp_RestoreParser(Clp_Parser *clp, const Clp_ParserState *state);
 317
 318
 319 /** @brief Report a parser error. */
 320 int Clp_OptionError(Clp_Parser *clp, const char *format, ...);
 321
 322 /** @brief Format a message. */
 323 int Clp_vsnprintf(Clp_Parser* clp, char* str, size_t size,
 324                   const char* format, va_list val);
 325
 326 /** @brief Print a message. */
 327 int Clp_fprintf(Clp_Parser* clp, FILE* f, const char* format, ...);
 328
 329 /** @brief Print a message. */
 330 int Clp_vfprintf(Clp_Parser* clp, FILE* f, const char* format, va_list val);
 331
 332 /** @brief Extract the current option as a string. */
 333 int Clp_CurOptionNameBuf(Clp_Parser *clp, char *buf, int len);
 334
 335 /** @brief Extract the current option as a string. */
 336 const char *Clp_CurOptionName(Clp_Parser *clp);
 337
 338 /** @brief Test if the current option had long name @a name. */
 339 int Clp_IsLong(Clp_Parser *clp, const char *long_name);
 340
 341 /** @brief Test if the current option had short name @a name. */
 342 int Clp_IsShort(Clp_Parser *clp, int short_name);
 343
 344 #undef CLP_SENTINEL
 345 #ifdef __cplusplus
 346 }
 347 #endif
 348 #endif