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