1 /* -*- c-basic-offset: 4; indent-tabs-mode: nil -*- */
2 /* ====================================================================
3 * Copyright (c) 1999-2004 Carnegie Mellon University. All rights
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
10 * 1. Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
13 * 2. Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in
15 * the documentation and/or other materials provided with the
18 * This work was supported in part by funding from the Defense Advanced
19 * Research Projects Agency and the National Science Foundation of the
20 * United States of America, and the CMU Sphinx Speech Consortium.
22 * THIS SOFTWARE IS PROVIDED BY CARNEGIE MELLON UNIVERSITY ``AS IS'' AND
23 * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
24 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
25 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY
26 * NOR ITS EMPLOYEES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
27 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
28 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
29 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
30 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
32 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34 * ====================================================================
38 * cmd_ln.h -- Command line argument parsing.
40 * **********************************************
41 * CMU ARPA Speech Project
43 * Copyright (c) 1999 Carnegie Mellon University.
44 * ALL RIGHTS RESERVED.
45 * **********************************************
49 * 15-Jul-1997 M K Ravishankar (rkm@cs.cmu.edu) at Carnegie Mellon University
50 * Added required arguments types.
52 * 07-Dec-96 M K Ravishankar (rkm@cs.cmu.edu) at Carnegie Mellon University
53 * Created, based on Eric's implementation. Basically, combined several
54 * functions into one, eliminated validation, and simplified the interface.
58 #ifndef _LIBUTIL_CMD_LN_H_
59 #define _LIBUTIL_CMD_LN_H_
64 /* Win32/WinCE DLL gunk */
65 #include <sphinxbase/sphinxbase_export.h>
66 #include <sphinxbase/prim_type.h>
70 * @brief Command-line and other configurationparsing and handling.
72 * Configuration parameters, optionally parsed from the command line.
86 * Argument definition structure.
88 typedef struct arg_s {
89 char const *name; /**< Name of the command line switch */
90 int type; /**< Type of the argument in question */
91 char const *deflt; /**< Default value (as a character string), or NULL if none */
92 char const *doc; /**< Documentation/description string */
96 * @name Values for arg_t::type
100 * Bit indicating a required argument.
102 #define ARG_REQUIRED (1<<0)
104 * Integer argument (optional).
106 #define ARG_INTEGER (1<<1)
108 * Floating point argument (optional).
110 #define ARG_FLOATING (1<<2)
112 * String argument (optional).
114 #define ARG_STRING (1<<3)
116 * Boolean (true/false) argument (optional).
118 #define ARG_BOOLEAN (1<<4)
120 * Boolean (true/false) argument (optional).
122 #define ARG_STRING_LIST (1<<5)
125 * Required integer argument.
127 #define REQARG_INTEGER (ARG_INTEGER | ARG_REQUIRED)
129 * Required floating point argument.
131 #define REQARG_FLOATING (ARG_FLOATING | ARG_REQUIRED)
133 * Required string argument.
135 #define REQARG_STRING (ARG_STRING | ARG_REQUIRED)
137 * Required boolean argument.
139 #define REQARG_BOOLEAN (ARG_BOOLEAN | ARG_REQUIRED)
142 * @deprecated Use ARG_INTEGER instead.
144 #define ARG_INT32 ARG_INTEGER
146 * @deprecated Use ARG_FLOATING instead.
148 #define ARG_FLOAT32 ARG_FLOATING
150 * @deprecated Use ARG_FLOATING instead.
152 #define ARG_FLOAT64 ARG_FLOATING
154 * @deprecated Use REQARG_INTEGER instead.
156 #define REQARG_INT32 (ARG_INT32 | ARG_REQUIRED)
158 * @deprecated Use REQARG_FLOATING instead.
160 #define REQARG_FLOAT32 (ARG_FLOAT32 | ARG_REQUIRED)
162 * @deprecated Use REQARG_FLOATING instead.
164 #define REQARG_FLOAT64 (ARG_FLOAT64 | ARG_REQUIRED)
169 * Helper macro to stringify enums and other non-string values for
172 #define ARG_STRINGIFY(s) ARG_STRINGIFY1(s)
173 #define ARG_STRINGIFY1(s) #s
177 * Opaque structure used to hold the results of command-line parsing.
179 typedef struct cmd_ln_s cmd_ln_t;
182 * Create a cmd_ln_t from NULL-terminated list of arguments.
184 * This function creates a cmd_ln_t from a NULL-terminated list of
185 * argument strings. For example, to create the equivalent of passing
186 * "-hmm foodir -dsratio 2 -lm bar.lm" on the command-line:
188 * config = cmd_ln_init(NULL, defs, TRUE, "-hmm", "foodir", "-dsratio", "2",
189 * "-lm", "bar.lm", NULL);
191 * Note that for simplicity, <strong>all</strong> arguments are passed
192 * as strings, regardless of the actual underlying type.
194 * @param inout_cmdln Previous command-line to update, or NULL to create a new one.
195 * @param defn Array of argument name definitions, or NULL to allow any arguments.
196 * @param strict Whether to fail on duplicate or unknown arguments.
197 * @return A cmd_ln_t* containing the results of command line parsing, or NULL on failure.
200 cmd_ln_t *cmd_ln_init(cmd_ln_t *inout_cmdln, arg_t const *defn, int32 strict, ...);
203 * Retain ownership of a command-line argument set.
205 * @return pointer to retained command-line argument set.
208 cmd_ln_t *cmd_ln_retain(cmd_ln_t *cmdln);
211 * Release a command-line argument set and all associated strings.
213 * @return new reference count (0 if freed completely)
216 int cmd_ln_free_r(cmd_ln_t *cmdln);
219 * Parse a list of strings into argumetns.
221 * Parse the given list of arguments (name-value pairs) according to
222 * the given definitions. Argument values can be retrieved in future
223 * using cmd_ln_access(). argv[0] is assumed to be the program name
224 * and skipped. Any unknown argument name causes a fatal error. The
225 * routine also prints the prevailing argument values (to stderr)
228 * @note It is currently assumed that the strings in argv are
229 * allocated statically, or at least that they will be valid as
230 * long as the cmd_ln_t returned from this function.
231 * Unpredictable behaviour will result if they are freed or
232 * otherwise become invalidated.
234 * @return A cmd_ln_t containing the results of command line parsing,
235 * or NULL on failure.
238 cmd_ln_t *cmd_ln_parse_r(cmd_ln_t *inout_cmdln, /**< In/Out: Previous command-line to update,
239 or NULL to create a new one. */
240 arg_t const *defn, /**< In: Array of argument name definitions */
241 int32 argc, /**< In: Number of actual arguments */
242 char *argv[], /**< In: Actual arguments */
243 int32 strict /**< In: Fail on duplicate or unknown
244 arguments, or no arguments? */
248 * Parse an arguments file by deliminating on " \r\t\n" and putting each tokens
249 * into an argv[] for cmd_ln_parse().
251 * @return A cmd_ln_t containing the results of command line parsing, or NULL on failure.
254 cmd_ln_t *cmd_ln_parse_file_r(cmd_ln_t *inout_cmdln, /**< In/Out: Previous command-line to update,
255 or NULL to create a new one. */
256 arg_t const *defn, /**< In: Array of argument name definitions*/
257 char const *filename,/**< In: A file that contains all
259 int32 strict /**< In: Fail on duplicate or unknown
260 arguments, or no arguments? */
264 * Access the generic type union for a command line argument.
267 anytype_t *cmd_ln_access_r(cmd_ln_t *cmdln, char const *name);
270 * Retrieve a string from a command-line object.
272 * The command-line object retains ownership of this string, so you
273 * should not attempt to free it manually.
275 * @param cmdln Command-line object.
276 * @param name the command-line flag to retrieve.
277 * @return the string value associated with <tt>name</tt>, or NULL if
278 * <tt>name</tt> does not exist. You must use
279 * cmd_ln_exists_r() to distinguish between cases where a
280 * value is legitimately NULL and where the corresponding flag
284 char const *cmd_ln_str_r(cmd_ln_t *cmdln, char const *name);
287 * Retrieve an array of strings from a command-line object.
289 * The command-line object retains ownership of this array, so you
290 * should not attempt to free it manually.
292 * @param cmdln Command-line object.
293 * @param name the command-line flag to retrieve.
294 * @return the array of strings associated with <tt>name</tt>, or NULL if
295 * <tt>name</tt> does not exist. You must use
296 * cmd_ln_exists_r() to distinguish between cases where a
297 * value is legitimately NULL and where the corresponding flag
301 char const **cmd_ln_str_list_r(cmd_ln_t *cmdln, char const *name);
304 * Retrieve an integer from a command-line object.
306 * @param cmdln Command-line object.
307 * @param name the command-line flag to retrieve.
308 * @return the integer value associated with <tt>name</tt>, or 0 if
309 * <tt>name</tt> does not exist. You must use
310 * cmd_ln_exists_r() to distinguish between cases where a
311 * value is legitimately zero and where the corresponding flag
315 long cmd_ln_int_r(cmd_ln_t *cmdln, char const *name);
318 * Retrieve a floating-point number from a command-line object.
320 * @param cmdln Command-line object.
321 * @param name the command-line flag to retrieve.
322 * @return the float value associated with <tt>name</tt>, or 0.0 if
323 * <tt>name</tt> does not exist. You must use
324 * cmd_ln_exists_r() to distinguish between cases where a
325 * value is legitimately zero and where the corresponding flag
329 double cmd_ln_float_r(cmd_ln_t *cmdln, char const *name);
332 * Retrieve a boolean value from a command-line object.
334 #define cmd_ln_boolean_r(c,n) (cmd_ln_int_r(c,n) != 0)
337 * Set a string in a command-line object.
339 * @param cmdln Command-line object.
340 * @param name The command-line flag to set.
341 * @param str String value to set. The command-line object does not
342 * retain ownership of this pointer.
345 void cmd_ln_set_str_r(cmd_ln_t *cmdln, char const *name, char const *str);
348 * Set an integer in a command-line object.
350 * @param cmdln Command-line object.
351 * @param name The command-line flag to set.
352 * @param iv Integer value to set.
355 void cmd_ln_set_int_r(cmd_ln_t *cmdln, char const *name, long iv);
358 * Set a floating-point number in a command-line object.
360 * @param cmdln Command-line object.
361 * @param name The command-line flag to set.
362 * @param fv Integer value to set.
365 void cmd_ln_set_float_r(cmd_ln_t *cmdln, char const *name, double fv);
368 * Set a boolean value in a command-line object.
370 #define cmd_ln_set_boolean_r(c,n,b) (cmd_ln_set_int_r(c,n,(b)!=0))
373 * Compatibility macros
375 #define cmd_ln_int32_r(c,n) cmd_ln_int_r(c,n)
376 #define cmd_ln_float32_r(c,n) (float32)cmd_ln_float_r(c,n)
377 #define cmd_ln_float64_r(c,n) (float64)cmd_ln_float_r(c,n)
378 #define cmd_ln_set_int32_r(c,n,i) cmd_ln_set_int_r(c,n,i)
379 #define cmd_ln_set_float32_r(c,n,f) cmd_ln_set_float_r(c,n,(double)f)
380 #define cmd_ln_set_float64_r(c,n,f) cmd_ln_set_float_r(c,n,(double)f)
383 * Re-entrant version of cmd_ln_exists().
385 * @return True if the command line argument exists (i.e. it
386 * was one of the arguments defined in the call to cmd_ln_parse_r().
389 int cmd_ln_exists_r(cmd_ln_t *cmdln, char const *name);
392 * Print a help message listing the valid argument names, and the associated
393 * attributes as given in defn.
396 void cmd_ln_print_help_r (cmd_ln_t *cmdln,
397 FILE *fp, /**< In: File to which to print */
398 const arg_t *defn /**< In: Array of argument name definitions */
402 * Non-reentrant version of cmd_ln_parse().
404 * @deprecated This is deprecated in favor of the re-entrant API
405 * function cmd_ln_parse_r().
406 * @return 0 if successful, <0 if error.
409 int32 cmd_ln_parse(const arg_t *defn, /**< In: Array of argument name definitions */
410 int32 argc, /**< In: Number of actual arguments */
411 char *argv[], /**< In: Actual arguments */
412 int32 strict /**< In: Fail on duplicate or unknown
413 arguments, or no arguments? */
417 * Parse an arguments file by deliminating on " \r\t\n" and putting each tokens
418 * into an argv[] for cmd_ln_parse().
420 * @deprecated This is deprecated in favor of the re-entrant API
421 * function cmd_ln_parse_file_r().
423 * @return 0 if successful, <0 on error.
426 int32 cmd_ln_parse_file(const arg_t *defn, /**< In: Array of argument name definitions*/
427 char const *filename,/**< In: A file that contains all the arguments */
428 int32 strict /**< In: Fail on duplicate or unknown
429 arguments, or no arguments? */
433 * Old application initialization routine for Sphinx3 code.
435 * @deprecated This is deprecated in favor of the re-entrant API.
438 void cmd_ln_appl_enter(int argc, /**< In: Number of actual arguments */
439 char *argv[], /**< In: Number of actual arguments */
440 char const* default_argfn, /**< In: default argument file name*/
441 const arg_t *defn /**< Command-line argument definition */
446 * Finalization routine corresponding to cmd_ln_appl_enter().
448 * @deprecated This is deprecated in favor of the re-entrant API.
452 void cmd_ln_appl_exit(void);
455 * Retrieve the global cmd_ln_t object used by non-re-entrant functions.
457 * @deprecated This is deprecated in favor of the re-entrant API.
458 * @return global cmd_ln_t object.
461 cmd_ln_t *cmd_ln_get(void);
464 * Test the existence of a command-line argument in the global set of
467 * @deprecated This is deprecated in favor of the re-entrant API
468 * function cmd_ln_exists_r().
470 * @return True if the command line argument exists (i.e. it
471 * was one of the arguments defined in the call to cmd_ln_parse().
473 #define cmd_ln_exists(name) cmd_ln_exists_r(cmd_ln_get(), name)
476 * Return a pointer to the previously parsed value for the given argument name.
478 * @deprecated This is deprecated in favor of the re-entrant API
479 * function cmd_ln_access_r().
481 #define cmd_ln_access(name) cmd_ln_access_r(cmd_ln_get(), name)
484 * Retrieve a string from the global command line.
486 * @deprecated This is deprecated in favor of the re-entrant API
487 * function cmd_ln_str_r().
489 #define cmd_ln_str(name) cmd_ln_str_r(cmd_ln_get(), name)
492 * Retrieve an array of strings in the global command line.
494 * @deprecated This is deprecated in favor of the re-entrant API
495 * function cmd_ln_str_list_r().
497 #define cmd_ln_str_list(name) cmd_ln_str_list_r(cmd_ln_get(), name)
500 * Retrieve a 32-bit integer from the global command line.
502 * @deprecated This is deprecated in favor of the re-entrant API
503 * function cmd_ln_int_r().
505 #define cmd_ln_int32(name) (int32)cmd_ln_int_r(cmd_ln_get(), name)
507 * Retrieve a 32-bit float from the global command line.
509 * @deprecated This is deprecated in favor of the re-entrant API
510 * function cmd_ln_float_r().
512 #define cmd_ln_float32(name) (float32)cmd_ln_float_r(cmd_ln_get(), name)
514 * Retrieve a 64-bit float from the global command line.
516 * @deprecated This is deprecated in favor of the re-entrant API
517 * function cmd_ln_float_r().
519 #define cmd_ln_float64(name) (float64)cmd_ln_float_r(cmd_ln_get(), name)
521 * Retrieve a boolean from the global command line.
523 * @deprecated This is deprecated in favor of the re-entrant API
524 * function cmd_ln_boolean_r().
526 #define cmd_ln_boolean(name) cmd_ln_boolean_r(cmd_ln_get(), name)
529 * Set a string in the global command line.
531 * @deprecated This is deprecated in favor of the re-entrant API
532 * function cmd_ln_set_str_r().
534 #define cmd_ln_set_str(n,s) cmd_ln_set_str_r(cmd_ln_get(),n,s)
536 * Set a 32-bit integer value in the global command line.
538 * @deprecated This is deprecated in favor of the re-entrant API
539 * function cmd_ln_set_int_r().
541 #define cmd_ln_set_int32(n,i) cmd_ln_set_int_r(cmd_ln_get(),n,i)
543 * Set a 32-bit float in the global command line.
545 * @deprecated This is deprecated in favor of the re-entrant API
546 * function cmd_ln_set_float_r().
548 #define cmd_ln_set_float32(n,f) cmd_ln_set_float_r(cmd_ln_get(),n,f)
550 * Set a 64-bit float in the global command line.
552 * @deprecated This is deprecated in favor of the re-entrant API
553 * function cmd_ln_set_float_r().
555 #define cmd_ln_set_float64(n,f) cmd_ln_set_float_r(cmd_ln_get(),n,f)
557 * Set a boolean value in the global command line.
559 * @deprecated This is deprecated in favor of the re-entrant API
560 * function cmd_ln_set_boolean_r().
562 #define cmd_ln_set_boolean(n,b) cmd_ln_set_boolean_r(cmd_ln_get(),n,b)
565 * Print a help message listing the valid argument names, and the associated
566 * attributes as given in defn.
568 * @deprecated This is deprecated in favor of the re-entrant API
569 * function cmd_ln_print_help_r().
571 #define cmd_ln_print_help(f,d) cmd_ln_print_help_r(cmd_ln_get(),f,d)
574 * Free the global command line, if any exists.
575 * @deprecated Use the re-entrant API instead.
578 void cmd_ln_free (void);