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
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
22 /* clp.h - Public interface to CLP.
23 * This file is part of CLP, the command line parser package.
25 * Copyright (c) 1997-2014 Eddie Kohler, ekohler@gmail.com
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.
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. */
45 typedef struct Clp_Option Clp_Option;
46 typedef struct Clp_Parser Clp_Parser;
47 typedef struct Clp_ParserState Clp_ParserState;
50 /** @brief Option description.
52 * CLP users declare arrays of Clp_Option structures to specify what options
54 * @sa Clp_NewParser, Clp_SetOptions */
56 const char *long_name; /**< Name of long option, or NULL if the option
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
64 int flags; /**< Option parsing flags. */
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. */
72 #define Clp_NoVal 0 /**< @brief Option takes no value. */
73 #define Clp_ValString 1 /**< @brief Option value is an
75 #define Clp_ValStringNotOption 2 /**< @brief Option value is a
78 See Clp_DisallowOptions. */
79 #define Clp_ValBool 3 /**< @brief Option value is a
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
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
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
100 #define Clp_ValUnsignedLong 7 /**< @brief Option value is an
102 #define Clp_ValDouble 8 /**< @brief Option value is a
104 Accepts a real number as defined by strtod(). */
105 #define Clp_ValFirstUser 10 /**< @brief Value types >=
106 Clp_ValFirstUser are available
110 /** @name Option flags
111 * These flags are used in the Clp_Option flags field. */
113 #define Clp_Mandatory (1<<0) /**< @brief Option flag: value
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
121 #define Clp_Negate (1<<2) /**< @brief Option flag: option
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.
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.
134 Prefixes of --[long_name] should map to this option, even if
135 other options begin with --[long_name]. */
138 /** @name Option character types
139 * These flags are used in to define character types in Clp_SetOptionChar(). */
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
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
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
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. */
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
177 typedef int (*Clp_ValParseFunc)(Clp_Parser *clp, const char *vstr,
178 int complain, void *user_data);
180 /** @brief A function for reporting option errors.
181 * @param clp the parser
182 * @param message error message
184 typedef void (*Clp_ErrorHandler)(Clp_Parser *clp, const char *message);
187 /** @brief Command line parser.
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 */
193 const Clp_Option *option; /**< The last option. */
195 int negated; /**< Whether the last option was negated. */
197 int have_val; /**< Whether the last option had a value. */
198 const char *vstr; /**< The string value provided with the last
209 #ifdef HAVE_INT64_TYPES
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
220 void *user_data; /**< Uninterpreted by CLP; users can set
223 struct Clp_Internal *internal;
228 # define CLP_SENTINEL __attribute__((sentinel))
230 # define CLP_SENTINEL /* nothing */
232 /** @endcond never */
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);
239 /** @brief Destroy a Clp_Parser object. */
240 void Clp_DeleteParser(Clp_Parser *clp);
243 /** @brief Return @a clp's program name. */
244 const char *Clp_ProgramName(Clp_Parser *clp);
246 /** @brief Set @a clp's program name. */
247 const char *Clp_SetProgramName(Clp_Parser *clp, const char *name);
250 /** @brief Set @a clp's error handler function. */
251 Clp_ErrorHandler Clp_SetErrorHandler(Clp_Parser *clp, Clp_ErrorHandler errh);
253 /** @brief Set @a clp's UTF-8 mode. */
254 int Clp_SetUTF8(Clp_Parser *clp, int utf8);
256 /** @brief Return @a clp's treatment of character @a c. */
257 int Clp_OptionChar(Clp_Parser *clp, int c);
259 /** @brief Set @a clp's treatment of character @a c. */
260 int Clp_SetOptionChar(Clp_Parser *clp, int c, int type);
262 /** @brief Set @a clp's option definitions. */
263 int Clp_SetOptions(Clp_Parser *clp, int nopt, const Clp_Option *opt);
265 /** @brief Set @a clp's arguments. */
266 void Clp_SetArguments(Clp_Parser *clp, int argc, const char * const *argv);
268 /** @brief Set whether @a clp is searching for options. */
269 int Clp_SetOptionProcessing(Clp_Parser *clp, int on);
272 #define Clp_DisallowOptions (1<<0) /**< @brief Value type flag: value
273 can't be an option string.
275 See Clp_AddType(). */
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);
282 #define Clp_AllowNumbers (1<<0) /**< @brief String list flag: allow
285 See Clp_AddStringListType() and Clp_AddStringListTypeVec(). */
286 #define Clp_StringListLong (1<<1) /**< @brief String list flag: values
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,
294 /** @brief Define a new string list value type for @a clp. */
295 int Clp_AddStringListType(Clp_Parser *clp, int val_type, int flags, ...)
299 /** @brief Parse and return the next argument from @a clp. */
300 int Clp_Next(Clp_Parser *clp);
302 /** @brief Return the next argument from @a clp without option parsing. */
303 const char *Clp_Shift(Clp_Parser *clp, int allow_options);
306 /** @brief Create a new Clp_ParserState. */
307 Clp_ParserState *Clp_NewParserState(void);
309 /** @brief Destroy a Clp_ParserState object. */
310 void Clp_DeleteParserState(Clp_ParserState *state);
312 /** @brief Save @a clp's current state in @a state. */
313 void Clp_SaveParser(const Clp_Parser *clp, Clp_ParserState *state);
315 /** @brief Restore parser state from @a state into @a clp. */
316 void Clp_RestoreParser(Clp_Parser *clp, const Clp_ParserState *state);
319 /** @brief Report a parser error. */
320 int Clp_OptionError(Clp_Parser *clp, const char *format, ...);
322 /** @brief Format a message. */
323 int Clp_vsnprintf(Clp_Parser* clp, char* str, size_t size,
324 const char* format, va_list val);
326 /** @brief Print a message. */
327 int Clp_fprintf(Clp_Parser* clp, FILE* f, const char* format, ...);
329 /** @brief Print a message. */
330 int Clp_vfprintf(Clp_Parser* clp, FILE* f, const char* format, va_list val);
332 /** @brief Extract the current option as a string. */
333 int Clp_CurOptionNameBuf(Clp_Parser *clp, char *buf, int len);
335 /** @brief Extract the current option as a string. */
336 const char *Clp_CurOptionName(Clp_Parser *clp);
338 /** @brief Test if the current option had long name @a name. */
339 int Clp_IsLong(Clp_Parser *clp, const char *long_name);
341 /** @brief Test if the current option had short name @a name. */
342 int Clp_IsShort(Clp_Parser *clp, int short_name);