] grad:gradient [y-int] -tit <title> your title grad:gradient line gradient y-int y-intercept \endverbatim We will create a single argument table in our program that defines the argument properties, and pass that table along with \b argc and \b argv[] to the arg_scanargv() function to do the parsing. \section Argtable Defining the argument table. An argument table is just an array of \b arg_rec structs, with each array element pertaining to a single command line argument. The arg_rec struct is defined in argtable.h as: \code typedef enum {arg_int=0,arg_dbl,arg_str,arg_bool,arg_lit} arg_type; typedef struct { const char *tagstr; // argument tag string const char *argname; // argument name string arg_type argtype; // argument data type void *valueptr; // ptr to user storage location const char *defaultstr; // default value, as a string const char *argdescrip; // argument description string } arg_rec; \endcode Thus we may define our argument table statically in the code as follows: \code int main(int argc, char **argv) { static char str[50]; static double grad; static int c; arg_rec argtable[] = { {"-tit ", "<title>", arg_str, str, "noname", "\t\t your title"}, {"grad:", "gradient", arg_dbl, &grad, NULL, "\t line gradient"}, {NULL, "y-int", arg_int, &c, "0", "\t\t y-intercept"} }; const size_t narg = sizeof(argtable)/sizeof(arg_rec); ... } \endcode Defining the tables statically is a programming convenience but not a requirement; the table could equally well have been dynamically allocated and initialized at runtime. Notice that I also chose to define the argument table within the main() block because that's the only place where it is used so there is no need to promote it to a higher namespace. However you may define it in the global namespace if you prefer. Our argument table has three rows, one for each command line argument -tit \<title\>, grad:gradient, and y-int. The behaviour of the argument parsing is governed entirely by the contents of the various fields (columns) of the argument table. Lets step through each field one by one. \par The tag string: The first field is the argument's tag string. It defines the prefix literal that identifies a tagged argument and should contain at least one non-whitespace character unless the argument is untagged whereupon the field should be NULL. In our example, -tit \<title\> and grad:gradient are tagged arguments but y-int is untagged so it has a NULL tag string. \par The name string: The second field is the argument's name string. It is not actually used to process the command line arguments, rather it defines the name of the argument as it appears in the description strings generated by the \b arg_syntax and \b arg_glossary functions. Those functions automatically substitute any NULL names with the argument's data type enclosed in angled brackets, as in "\<int\>" or "\<string\>". \par The data type: The third field is an enumerated type that defines the data type of the command line argument. Possible values are \b arg_int, \b arg_dbl, \b arg_str, \b arg_bool, and \b arg_lit. They represent integer, double, string, boolean, and literal arguments respectively. In our example -tit \<title\> expects \em \<title\> to be substituted by a string value, grad:gradient expects \em gradient to be a double, and y-int is expected to be an integer. \par The data pointer: The fourth field is a pointer-to-void that gives the address of the user-defined program variable used to store the argument's value. A NULL pointer here causes the value to be discarded once is has been scanned. Take care that the data type of of the target memory location matches that specified in the previous column. Arguments of type \b arg_int, \b arg_bool, and \b arg_lit must each point to an \em integer variable. Those of type \b arg_dbl must point to a \em double and those of \b arg_str must point to a \em char \em array. In our example, the string value associated with -tit \<title\> is written into the \em char \em str[50] buffer, the double value associated with \b grad:gradient is written into \em double \em grad, and the integer value associated with y-int is written into \em int \em c. \par The default value: The fifth field is a string which contains an optional default value for the argument. It is defined as a string and automatically cast to the appropriate data type at run time. A NULL value indicates no default. In our example, -tit \<title\> and y-int have default values of "noname" and zero respectively, whereas grad:gradient has no default and is thus regarded as a mandatory argument. \par The description string: The sixth and final field allows the programmer to enter a brief description of the argument. It is these descriptions that are output by the arg_glossary() function. A NULL value causes that entry to be omitted from the glossary output. \section Parsing Parsing the command line. Having defined the argument table, we can now use it to parse the command line arguments in argv[]. There are several ways to do this, but the simplest is to use the \b arg_scanargv function. \code int arg_scanargv(int argc, char** argv, arg_rec *argtable, int n, char* CmdLine, char* ErrMsg, char* ErrMark); \endcode It takes as input the command line arguments in \b argv[] (there are \b argc of them) and a pointer to the argument table in \b argtable (which has \b n rows). It proceeds to scan the argv[] arguments (skipping argv[0]) and tries to resolve them with the entries given in the argument table. If this can be done successfully then all argument values are written into the program variables as designated by the argument table and the function returns 1. If not, the function returns 0 to indicate failure. The three string pointers \b CmdLine, \b ErrMsg, and \b ErrMark refer to user defined string buffers in which \b arg_scanargv returns information about the parsing. They are optional parameters in the sense that they may be given as NULL if you do not wish to use them. \b CmdLine is always assigned a copy of the orginal command line, concatenated into a single space-separated string. \b ErrMsg and \b ErrMark are only used when \b arg_scanargv detects a parse error in the command line. In those cases, \b ErrMsg is assigned an explantory error message string, and \b ErrMark is assigned a string of tilde characters which have been formatted in such a way as to highlight the exact location of the error in \b CmdLine when printed one atop the other. The code fragment below demonstrates the use of \b arg_scanargv. It presumes that \em argc, \em argv, \em argtable, and \em narg are as defined in the example above. \code { char cmdline[200], errmsg[200], errmark[200]; if (!arg_scanargv(argc,argv,argtable,narg,cmdline,errmsg,errmark)) { // arg error occurred, print error message and exit printf("ERROR: %s\n", cmdline); printf(" %s %s\n", errmark, errmsg); return 1; } // only get here if the arguments were scanned successfully } \endcode And here are some examples of the console output that this code produces when \b arg_scanargv detects a parse error. \code $ myprog grad:oops ERROR: myprog grad:oops ^ invalid grad:gradient argument $ myprog grad:13 nope ERROR: myprog grad:13 nope ^^^^ unexpected argument $ myprog grad:13 99 uh oh ERROR: myprog grad:13 99 uh oh ^^ unexpected argument \endcode \section OnlineHelp Generating online help. The arg_syntax() and arg_glossary() functions take an argument table and generate plain text descriptions of its command line syntax as well as descriptions of the individual arguments. These are useful for displaying help text to the user. \code const char* arg_syntax(const arg_rec* argtable, int n); const char* arg_glossary(const arg_rec* argtable, int n, const char* prefix); \endcode The \b arg_syntax function returns a pointer to an internal string buffer that contains a plain text description of the usage syntax of the argument table it was passed. The string comprises a space separated list of the tag and name strings of each argument table entries concatenated into a single line string. Optional command line arguments are automatically enclosed in square brackets. Calling \b arg_syntax on our example argument table would return the string: \verbatim [-tit <title>] grad:gradient [y-int] \endverbatim The calling program would ordinarily prepend the program name from argv[0] to this to get the full command line usage syntax. The \b arg_glossary function is similar, except it generates a multi-line text string with one argument per line. Each line includes the argument's tag, its name string, and its description string as given in the argument table. Arguments that have a NULL description string are omitted. Each line of the glossary string is prefixed with the string given in the prefix parameter; it useful for indenting each line of the string. Calling \b arg_glossary with our example argument table results in the following multi-line string: \verbatim -tit \<title\> your title grad:gradient line gradient y-int y-intercept \endverbatim \section Altogether Putting it all together. Lets return to our example program and put it all together in its entirety. Our program, when executed without any arguments (argc==1), will print the argument usage syntax and a glossary on stdout, then exit. When given a valid set of arguments, it will display the resulting argument values as they are stored in the local program variables. Otherwise, it echoes the erroneous command line together with an appropriate error message and terminates with error code 1. \code #include "argtable.h" int main(int argc, char **argv) { static char str[50]; static double grad; static int c; arg_rec argtable[] = { {"-tit ", "<title>", arg_str, str, "noname", "\t\t your title"}, {"grad:", "gradient", arg_dbl, &grad, NULL, "\t line gradient"}, {NULL, "y-int", arg_int, &c, "0", "\t\t y-intercept"} }; const size_t narg = sizeof(argtable)/sizeof(arg_rec); // process the command line args if (argc==1) { // display program usage and exit. printf("Usage: %s %s\n", argv[0], arg_syntax(argtable,narg)); printf("%s\n",arg_glossary(argtable,narg," ")); return 0; } else { // scan command line arguments from argv[] char cmdline[200], errmsg[200], errmark[200]; if (!arg_scanargv(argc, argv, argtable, narg, cmdline, errmsg, errmark)) { // arg error occurred, print error message and exit printf("ERROR: %s\n", cmdline); printf(" %s %s\n", errmark, errmsg); return 1; } } // get here only if command line args ok printf("title: \"%s\"\n",str); printf("gradient: %f\n",grad); printf("y-intercept: %d\n",c); return 0; } \endcode Here are some results of running myprog with various command line arguments. \verbatim $ myprog Usage: myprog [-tit <title>] grad:gradient [y-int] -tit <title> your title grad:gradient line gradient y-int y-intercept $ myprog grad:10 title: "noname" gradient: 10.000000 y-intercept: 0 $ myprog 7 grad:1.234 title: "noname" gradient: 1.234000 y-intercept: 7 $ myprog -tit "hello world" grad:3.33 11 title: "hello world" gradient: 3.330000 y-intercept: 11 \endverbatim */ /** \page Release Release Notes. \par Argtable-2.0 coming eventually. Argtable-2.0 will be a major overhaul of the code. The changes are required to address the most common complaint about argtable; the potential for buffer overruns as argtable writes into fixed size string buffers. The redesign will bring some inevitable changes to the library interface, but the basic look and feel of the argument tables will stay the same. I been promising to finish Argtable-2.0 for a very long time. Well, one of the days.... \par Argtable-1.3 released December 20, 2001. Moved argtable to a new home on the \b sourceforge site and revamped the documentation. Documentation is now created with \b Doxygen instead of \b c2man. Also fixed some minor bugs in the Makefiles. The source code itself is unaltered. \par Argtable-1.2 released August 5, 1999. The original makefiles have been replaced by autoconf makefiles. The char pointers in the argument table have been redefined as pointers to const char. Some of argtable's internal string buffers have been made larger to accommodate long command lines, and a bug that occurred when program names contained whitespace has been fixed. The documentation has also been revised. \par Argtable-1.1 released January 20, 1999. This version fixes some cross-platform compilation errors, and saw the introduction of the multi-platform configuration. It also saw the addition of the arg_record() function and a change to the arg_scanargv() function so that it no longer requires argv[0] to be the first entry of the argument table. To maintain backwards compatibility, programs written for version 1.0 should now define the macro #define ARGTABLE_COMPATIBILITY_10 prior to including the argtable.h header file. \par Argtable-1.0 released November 13, 1998. Argtable's debut! */ #endif

/********************************************************************* This file is part of the argtable library. It contains the declarations of the argtable library functions. Copyright (C) 1998,1999,2001 Stewart Heitmann (sheitmann@users.sourceforge.net) The argtable library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *********************************************************************/ #ifndef ARGTABLE #define ARGTABLE #include #define ARGTABLE_VERSION 1.3 #ifdef ARGTABLE_COMPATIBILITY_10 #define arg_scanargv(a,b,c,d,e,f,g) arg_scanargv_10(a,b,c,d,e,f,g) #endif #ifdef __cplusplus extern "C" { #endif /** * arg_type enums are used in the argument table to define * the data type of a command line argument. */ typedef enum { arg_int=0, /**< Integer value. */ arg_dbl, /**< Double value. */ arg_str, /**< Ascii string; may be quoted or un-quoted.*/ arg_bool, /**< Boolean; accepts the keywords \em yes, \em no, \em true, \em false, \em on , or \em off and converts them into an integer value of 0 (negative) or 1 (affirmative) accordingly. */ arg_lit /**< Literal; returns 1 if a given literal string was present on the command line otherwise returns the default value. */ } arg_type; /** * A fixed array of strings that are used when arguments are * given NULL names. * The array is indexed by arg_type, with each name describing * the corresponding data type. * \code * arg_str[arg_int] = ""; * arg_str[arg_dbl] = ""; * arg_str[arg_str] = ""; * arg_str[arg_bool] = ""; * arg_str[arg_lit] = ""; * \endcode */ extern const char* arg_typestr[]; /** * An argument table is defined an array of arg_rec structs * having one entry for each command line argument that is expected. * It is most conveniently defined and initialised as a * static array (but need not be so). * * \code * //command line arguments will be written into these variables * int x,y,z,verbose,debug; * double radius; * char infname[100]; * char outfname[100];i * * //The argument table. * arg_rec argtable[] = * // TAG NAME TYPE STORAGE DEFAULT DESCRIPTION * { * { NULL, "x", arg_int, &x, NULL, "x coord" }, * { NULL, "y", arg_int, &y, NULL, "y coord" }, * { NULL, "z", arg_int, &z, "0", "z coord" }, * { "-r ", NULL, arg_dbl, &radius, "1.0", "radius" }, * { "-o ", "", arg_str, outfname, "-", "output file" }, * { "-verbose", NULL, arg_lit, &verbose, "0", "verbose output" }, * { NULL, "", arg_str, infname, NULL, "input file" }, * { "debug=", "", arg_bool, &debug, "off", NULL }, * }; * const size_t narg = sizeof(argtable)/sizeof(arg_rec); * \endcode */ typedef struct { /** * The argument tag string defines the tag that identifies the argument on the command line. * Tags may be any string you choose provided they have no whitespace. * Examples of common tag string styles are "mytag:", "-mytag", "mytag=". * An argument can be specified without a tag by setting the tag string to NULL. * Untagged argument are taken from the command line from left to right after * all the tagged arguments (if any) have first been extracted. */ const char *tagstr; /** * The argument name has no effect on the argument processing. * It is simply a descriptive name used to represent the argument in the * output of the arg_syntax() and arg_glossary() functions. * The argument name can be whatever you want, and is a convenient place * to communicate the default value to the user if you so wish, * for example "\=1024". * If a NULL name string is given, it is automatically replaced by the * argument's data type enclosed in angled brackets, as in "\". * If you dislike such behaviour, you can effectively suppress the name by * defining it as an empty string. */ const char *argname; /** * This defines the data type associated with a command line argument. * It supports integer, double, string and boolean data types as well * as literal argument strings. * * Strings may appear on the command line either quoted or unquoted. * * Booleans expect one of the keywords "true", "false", "yes", "no", * "on", or "off" to appear on the command line. These are converted to 0 * (false,no,off) or 1 (true,yes,on) and stored as an integer. * * Literals are command line arguments with no associated data value, * they are used to define keyword strings that can be used as command line switches. * The string literal can be defined in either the tag string or the name string * fields. If you use the tag string then the literal, like other tagged * arguments, may appear anywhere on the command line. On the other hand, * if you use the name string, then the literal must appear in that * argument's position just as for normal untagged arguments. * When a string literal is succesfully scanned, an integer value of 1 is * written into its user-suplied program variable, otherwise it is assigned * the default value (if it has one). If there is no default value, then the * literal is regarded as a mandatory argument the same as for any other * argument. * */ arg_type argtype; /** * Points to a user-defined variable into which the command line value will * be written. * It is imperative that the data type of the user-defined variable matches * the argtype field, otherwise you can expect very spurious behaviour. * \li \em arg_int arguments require \em int storage. * \li \em arg_double arguments require \em double storage. * \li \em arg_str arguments require a \em char buffer big enough to store * the expected result (you'll have to guess what big enough is!). * \li \em arg_bool arguments require \em int storage. * \li \em arg_lit arguments require \em int storage. * * Lastly, a NULL placed in this field will cause the argument value to be scanned * in the normal way, but the resulting value will be discarded. */ void *valueptr; /** * The default string contains an optional default value to be used * should the argument be missing from teh command line. All defaults are * defined as strings (as they would appear on teh command line) and converted * to the appropriate data type during processing. * * If a default is specified as NULL then that argument is regarded as * mandatory, meaning that a parse error will result if the argument * was not given on the command line. */ const char *defaultstr; /** * The argument description string, like the name string, does not * affect argument processing. The arg_glossary() function * uses it to display additional descriptions of command line arguments. * Arguments with NULL description strings are omitted from the glossary * altogether. */ const char *argdescrip; } arg_rec; /** * \brief Parse the command line as per a given argument table. * * Attempts to resolve the argv[] command line arguments * (ignoring argv[0]) with the specifications given in the argument table. * The values scanned from the command line are written directly into * the program variables nominated by each argument table entry. * * During the process, a copy of the command line is written * (as a single line of space separated arguments) into the * user-supplied string at *CmdLine in case it is needed in future * for error reporting. * * Should there be any conflict between the command line arguments * and the argument table specifications, an error message and * corresponding error marker are written into the user-supplied * strings at *ErrMsg and *ErrMark respectively, after which the * function returns zero. The error marker string is used to store * a string of tilde characters formated in such a way that the tildes * underscore the exact location of the error in *CmdLine when the * strings are aligned one above the other. This can be useful for * including in on-line error messages to help the user quickly * pinpoint the cause of the error. * * If, on the other hand, all arguments were resolved successfully * then *ErrMsg and *ErrMark are set to empty strings and the * function returns 1. * Either way, CmdLine, ErrMsg, or ErrMark can be safely ignored * by passing them as NULL. * * \returns 1 upon success, 0 upon failure. */ int arg_scanargv(int argc, /**< number of entries in argv[]. */ char **argv, /**< command line arguments. */ arg_rec *argtable, /**< pointer to the argument table. */ int n, /**< number of entries in argtable[]. */ char* CmdLine, /**< pointer to storage for command line (may be NULL). */ char* ErrMsg, /**< pointer to storage for error message (may be NULL). */ char* ErrMark /**< pointer to storage for error marker (may be NULL). */ ); /** * \brief Parse a string as per a given argument table. * * This function is much like arg_scanargv() except that is scans * the arguments from the string at *str rather than from argv[]. * The string is expected to contain a single line, space separated * list of arguments, like that generated by arg_catargs(). * * In a departure from \b arg_scanargv, this function erases the scanned * arguments from \em *str by overwriting them with spaces once they have been * successfully scanned. * Furthermore, this function does not throw an error if there are still * arguments remaining in *str after the argtable has been fully processed. * Thus, complicated argument usages can be achieved by invoking this * function multiple times on the same command line string, * each time applying a different argument table until the arguments * have been exhausted, or an error has been detected. * * \returns 1 upon success, 0 upon failure. */ int arg_scanstr(char* str, /**< pointer to command line string. */ arg_rec *argtable, /**< pointer to the argument table. */ int n, /**< number of array elements in argtable[]. */ char* ErrMsg, /**< pointer to storage for error message (may be NULL). */ char* ErrMark /**< pointer to storage for error marker (may be NULL). */ ); /** * \brief Generates a 'usage' syntax string from an argument table * * Builds a syntactical description of the allowable command line arguments * specified by the 'argtable' array. * The resulting string is stored in static data within the local scope of * this function. Its contents are overwritten by subsequent calls. * * The syntactical description is generated as a single line of space * separated argument descriptors, each comprising of the argument's tag * string and name string concatenated together. For example, * * "myprog x y [z] [-r ] [-o ] [-verbose] [debug=]" * * If an argument is optional (has a non-NULL default value) then its * descriptor is enclosed in square brackets. * NULL name strings are substituted with the argument's data type enclosed * in angled brackets, as in , , or . * If both the tag and the name are empty strings ("") then the argument is * omitted from the description altogether. This allows the suppression of * individual arguments that you do not want to appear. * * \returns a pointer to the internal string. */ const char* arg_syntax(const arg_rec* argtable, /**< pointer to the argument table */ int n /**< number of array elements in argtable[] */ ); /** * \brief Generate a glossary string from an argument table. * * Returns a pointer to an internal 'glossary' string which * contains a multi-line description of each of the argument table * entres that have a non-NULL \ field. * The contents of the glossary string remain unaltered up until the * next invocation of this function. * Each line of the glossary string is formatted as * * "\\\\" * * The 'prefix' string is useful for adding indenting spaces * before each line in the description to improve the look of * the glossary string, or it can be given as NULL in which * case it is ignored. * * Any NULL \ fields in the argument table will appear in the * glosssary as empty strings. * * Any NULL \ fields will be substituted by a description of * that argument's data type, enclosed in angled brackets, as in * \ and \. * A name can effectively be suppressed from the glossary by defining * it as an empty string in the argument table. * * \returns a pointer to the internal string. */ const char* arg_glossary(const arg_rec* argtable, /**< pointer to the argument table */ int n, /**< number of array elements in argtable[] */ const char* prefix /**< a string to be prefixed to each line of the output */ ); /** * \brief Concatenate all argv[] arguments into a single string. * * Concatenates all of the arguments in the argv[] array and writes the * result into *str as a single line, space separated string. * * Any argv[] entries that contain whitespace are automatically * encapsulated by single quotes prior to the concatenation to preserve * their word grouping. * A trailing space is always appended to the resulting string as a * safety precaution in lieu of scanning for string literals that expect * trailing space. * It is assumed that *str is big enough to store the result. */ extern void arg_catargs(int argc, /**< number of arguments in argv[] */ char **argv, /**< command line arguments */ char *str /**< pointer to destination string */ ); /** * \brief Builds and returns an argument table record. * * Returns an arg_rec structure containing the values passed to * the function. It is useful for building argument tables dynamically. */ arg_rec arg_record(char *tagstr, /**< argument tag string */ char *argname, /**< argument name string */ arg_type argtype, /**< argument data type */ void *valueptr, /**< pointer to user-supplied storage location */ char *defaultstr, /**< default argument value, as a string */ char *argdescrip /**< argument description string */ ); /** * \brief Print the contents of an argument table. * * The contents of the argument table, and the user-supplied * variables it references, are printed to the stream 'fp'. * This can be useful for debugging argument tables. */ void arg_dump(FILE* fp, /**< output stream */ const arg_rec* argtable, /**< pointer to the argument table */ int n /**< number of array elements in argtable[] */ ); #ifdef __cplusplus } #endif /** \mainpage Introduction to Argtable \section LegalNotice Legal notice. The argtable library and accompanying documentation is copyright 1998, 1999, 2001 Stewart Heitmann (sheitmann@users.sourceforge.net). Argtable is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. \section Overview Overview. Argtable (http://argtable.sourceforge.net) is a freely available programmer's library for parsing the command line arguments of any C/C++ program. It allows the programmer to specify the desired format of the command line arguments in one or more statically defined arrays known as argument tables. Each row of an argument table specifies the data type of an expected argument and nominates a user-defined program variable as storage for the incoming argument value. If arguments require default values, then these too are specified in the argument table. Once an argument table has been established, parsing the command line is simply a matter of calling the library's arg_scanargv() function which attempts to resolve the contents of \b argv[] with the entries of the argument table. If successful, the command line arguments are now known to be valid and their values are ready and available for use in their nominated program variables. If the arguments could not be successfully resolved then \b arg_scanargv returns an error message string describing the reason for the failure and showing the location of the error in the command line. The program can simply print the error message to stdout or stderr and exit. \code ERROR: myprog grad:13 99 uh oh ^^ unexpected argument \endcode Alternatively, if the program has multiple command line usages then it may choose to call \b arg_scanargv several times each with a different argument table until a successful match is found or all argument tables are exhausted. Auxilliary functions arg_glossary() and arg_syntax() generate plain text descriptions of the arguments defined in an argument table and their command line syntax. These make it easy to generate on-line help facilities that are always current. \section ArgStyles Styles of command line arguments. Argtable supports both \em tagged and \em untagged command line arguments. Tagged arguments are identified by a prefix tag, as in -o file or title:mystuff. The tag enables these arguments to appear anywhere on the command line, and in any order. The programmer may implement any style of argument tag desired, including such common styles as -title mystuff, title:mystuff, --title mystuff, or title=mystuff. Untagged arguments on the other hand have no prefix; they are identified strictly by their ordering on the command line. The two styles of arguments may be freely mixed, whereupon the tagged arguments are always processed first, leaving any remaining (untagged) arguments to be scanned from left to right. A command line argument may be of type \b integer, \b double, \b string, or \b boolean. Doubles are accepted in in either floating point or scientific notation, and strings may be either quoted or unquoted. Booleans will accept any of the keywords \b on, \b off, \b yes, \b no, \b true, or \b false and yield an integer value of 0 (negative) or 1 (affirmative) accordingly. A special argument type called \b literal is also provided; it yields an integer value according to the presence or absence of a given string literal on the command line. It is useful for specifying unparameterised command line switches such as \b -verbose and \b -help. \section OptionalArgs Optional arguments and default values. Arguments may be assigned default values that take effect when no matching command line argument could be found. When a default value is specified for an argument you are, in effect, declaring that argument as being optional. Arguments without defaults are, by definition, regarded as mandatory arguments. \section Platforms Supported platforms. Argtable conforms to ansi C requirements and should compile on any standard ansi C compiler. To date, it has been successfully compiled on: \li MIPSpro C/C++ on IRIX 6.2, 6.3 and IRIX64 6.2 \li DEC C/C++ on Digital Unix V4.0 (OSF/1) \li GNU gcc/g++ on DEC Digital Unix V4.0 (OSF/1); IRIX 6.2, 6.3; IRIX64 6.2; Linux 2.0.30; and SunOS 5.5.1. Please let me know if you have successfully used argtable on other platforms. \section InstallSection Installing Argtable The fastest and easiest way to use argtable is simply to copy the \b argtable.h and \b argtable.c files into your project and compile them with the rest of your code. If you are a system administrator, you may wish to install argtable on your system as a programmer's library, complete with man pages and html documentation. This is easy to do as the makefiles follow the usual \b autoconf procedure. -# \b cd to the argtable package directory and type \b ./configure to configure it for your system. -# Type \b make to compile the package. -# Optionally, type \b make \b check to run the self-tests. -# \b su as root user. -# Type \b make \b install to install the programs and documentation. By default the package installs into \b /usr/local/ but a different location may be specified when configuring the package. Type \b ./configure \b --help for the full list of configuration options. -# logout from root user. -# Type \b make \b clean to remove the temporary binaries created during compilation. \section GetStarted Getting started. \ref Tutorial is the best place to get started. Then look at the example code supplied with the distribution. \section Others Similar packages. Here are some other command line parsing tools that I am aware of. Apologies for any I may have omitted. \li \b clig: The Command Line Interpreter Generator: http://wsd.iitb.fhg.de/~kir/clighome/ \li \b opt: The Options and Parameter parsing Toolkit: ftp://ftp.lanl.gov/pub/users/jt/Software/opt/opt_toc.html \li \b getopt: The GNU-style options parser. This comes as standard on most unix systems. */ /** \page Tutorial The Argtable Tutorial Imagine we have written a program called \b myprog and we wish to implement the following command line usage syntax for it: \verbatim myprog [-tit ] grad:gradient [y-int] -tit <title> your title grad:gradient line gradient y-int y-intercept \endverbatim We will create a single argument table in our program that defines the argument properties, and pass that table along with \b argc and \b argv[] to the arg_scanargv() function to do the parsing. \section Argtable Defining the argument table. An argument table is just an array of \b arg_rec structs, with each array element pertaining to a single command line argument. The arg_rec struct is defined in argtable.h as: \code typedef enum {arg_int=0,arg_dbl,arg_str,arg_bool,arg_lit} arg_type; typedef struct { const char *tagstr; // argument tag string const char *argname; // argument name string arg_type argtype; // argument data type void *valueptr; // ptr to user storage location const char *defaultstr; // default value, as a string const char *argdescrip; // argument description string } arg_rec; \endcode Thus we may define our argument table statically in the code as follows: \code int main(int argc, char **argv) { static char str[50]; static double grad; static int c; arg_rec argtable[] = { {"-tit ", "<title>", arg_str, str, "noname", "\t\t your title"}, {"grad:", "gradient", arg_dbl, &grad, NULL, "\t line gradient"}, {NULL, "y-int", arg_int, &c, "0", "\t\t y-intercept"} }; const size_t narg = sizeof(argtable)/sizeof(arg_rec); ... } \endcode Defining the tables statically is a programming convenience but not a requirement; the table could equally well have been dynamically allocated and initialized at runtime. Notice that I also chose to define the argument table within the main() block because that's the only place where it is used so there is no need to promote it to a higher namespace. However you may define it in the global namespace if you prefer. Our argument table has three rows, one for each command line argument -tit \<title\>, grad:gradient, and y-int. The behaviour of the argument parsing is governed entirely by the contents of the various fields (columns) of the argument table. Lets step through each field one by one. \par The tag string: The first field is the argument's tag string. It defines the prefix literal that identifies a tagged argument and should contain at least one non-whitespace character unless the argument is untagged whereupon the field should be NULL. In our example, -tit \<title\> and grad:gradient are tagged arguments but y-int is untagged so it has a NULL tag string. \par The name string: The second field is the argument's name string. It is not actually used to process the command line arguments, rather it defines the name of the argument as it appears in the description strings generated by the \b arg_syntax and \b arg_glossary functions. Those functions automatically substitute any NULL names with the argument's data type enclosed in angled brackets, as in "\<int\>" or "\<string\>". \par The data type: The third field is an enumerated type that defines the data type of the command line argument. Possible values are \b arg_int, \b arg_dbl, \b arg_str, \b arg_bool, and \b arg_lit. They represent integer, double, string, boolean, and literal arguments respectively. In our example -tit \<title\> expects \em \<title\> to be substituted by a string value, grad:gradient expects \em gradient to be a double, and y-int is expected to be an integer. \par The data pointer: The fourth field is a pointer-to-void that gives the address of the user-defined program variable used to store the argument's value. A NULL pointer here causes the value to be discarded once is has been scanned. Take care that the data type of of the target memory location matches that specified in the previous column. Arguments of type \b arg_int, \b arg_bool, and \b arg_lit must each point to an \em integer variable. Those of type \b arg_dbl must point to a \em double and those of \b arg_str must point to a \em char \em array. In our example, the string value associated with -tit \<title\> is written into the \em char \em str[50] buffer, the double value associated with \b grad:gradient is written into \em double \em grad, and the integer value associated with y-int is written into \em int \em c. \par The default value: The fifth field is a string which contains an optional default value for the argument. It is defined as a string and automatically cast to the appropriate data type at run time. A NULL value indicates no default. In our example, -tit \<title\> and y-int have default values of "noname" and zero respectively, whereas grad:gradient has no default and is thus regarded as a mandatory argument. \par The description string: The sixth and final field allows the programmer to enter a brief description of the argument. It is these descriptions that are output by the arg_glossary() function. A NULL value causes that entry to be omitted from the glossary output. \section Parsing Parsing the command line. Having defined the argument table, we can now use it to parse the command line arguments in argv[]. There are several ways to do this, but the simplest is to use the \b arg_scanargv function. \code int arg_scanargv(int argc, char** argv, arg_rec *argtable, int n, char* CmdLine, char* ErrMsg, char* ErrMark); \endcode It takes as input the command line arguments in \b argv[] (there are \b argc of them) and a pointer to the argument table in \b argtable (which has \b n rows). It proceeds to scan the argv[] arguments (skipping argv[0]) and tries to resolve them with the entries given in the argument table. If this can be done successfully then all argument values are written into the program variables as designated by the argument table and the function returns 1. If not, the function returns 0 to indicate failure. The three string pointers \b CmdLine, \b ErrMsg, and \b ErrMark refer to user defined string buffers in which \b arg_scanargv returns information about the parsing. They are optional parameters in the sense that they may be given as NULL if you do not wish to use them. \b CmdLine is always assigned a copy of the orginal command line, concatenated into a single space-separated string. \b ErrMsg and \b ErrMark are only used when \b arg_scanargv detects a parse error in the command line. In those cases, \b ErrMsg is assigned an explantory error message string, and \b ErrMark is assigned a string of tilde characters which have been formatted in such a way as to highlight the exact location of the error in \b CmdLine when printed one atop the other. The code fragment below demonstrates the use of \b arg_scanargv. It presumes that \em argc, \em argv, \em argtable, and \em narg are as defined in the example above. \code { char cmdline[200], errmsg[200], errmark[200]; if (!arg_scanargv(argc,argv,argtable,narg,cmdline,errmsg,errmark)) { // arg error occurred, print error message and exit printf("ERROR: %s\n", cmdline); printf(" %s %s\n", errmark, errmsg); return 1; } // only get here if the arguments were scanned successfully } \endcode And here are some examples of the console output that this code produces when \b arg_scanargv detects a parse error. \code $ myprog grad:oops ERROR: myprog grad:oops ^ invalid grad:gradient argument $ myprog grad:13 nope ERROR: myprog grad:13 nope ^^^^ unexpected argument $ myprog grad:13 99 uh oh ERROR: myprog grad:13 99 uh oh ^^ unexpected argument \endcode \section OnlineHelp Generating online help. The arg_syntax() and arg_glossary() functions take an argument table and generate plain text descriptions of its command line syntax as well as descriptions of the individual arguments. These are useful for displaying help text to the user. \code const char* arg_syntax(const arg_rec* argtable, int n); const char* arg_glossary(const arg_rec* argtable, int n, const char* prefix); \endcode The \b arg_syntax function returns a pointer to an internal string buffer that contains a plain text description of the usage syntax of the argument table it was passed. The string comprises a space separated list of the tag and name strings of each argument table entries concatenated into a single line string. Optional command line arguments are automatically enclosed in square brackets. Calling \b arg_syntax on our example argument table would return the string: \verbatim [-tit <title>] grad:gradient [y-int] \endverbatim The calling program would ordinarily prepend the program name from argv[0] to this to get the full command line usage syntax. The \b arg_glossary function is similar, except it generates a multi-line text string with one argument per line. Each line includes the argument's tag, its name string, and its description string as given in the argument table. Arguments that have a NULL description string are omitted. Each line of the glossary string is prefixed with the string given in the prefix parameter; it useful for indenting each line of the string. Calling \b arg_glossary with our example argument table results in the following multi-line string: \verbatim -tit \<title\> your title grad:gradient line gradient y-int y-intercept \endverbatim \section Altogether Putting it all together. Lets return to our example program and put it all together in its entirety. Our program, when executed without any arguments (argc==1), will print the argument usage syntax and a glossary on stdout, then exit. When given a valid set of arguments, it will display the resulting argument values as they are stored in the local program variables. Otherwise, it echoes the erroneous command line together with an appropriate error message and terminates with error code 1. \code #include "argtable.h" int main(int argc, char **argv) { static char str[50]; static double grad; static int c; arg_rec argtable[] = { {"-tit ", "<title>", arg_str, str, "noname", "\t\t your title"}, {"grad:", "gradient", arg_dbl, &grad, NULL, "\t line gradient"}, {NULL, "y-int", arg_int, &c, "0", "\t\t y-intercept"} }; const size_t narg = sizeof(argtable)/sizeof(arg_rec); // process the command line args if (argc==1) { // display program usage and exit. printf("Usage: %s %s\n", argv[0], arg_syntax(argtable,narg)); printf("%s\n",arg_glossary(argtable,narg," ")); return 0; } else { // scan command line arguments from argv[] char cmdline[200], errmsg[200], errmark[200]; if (!arg_scanargv(argc, argv, argtable, narg, cmdline, errmsg, errmark)) { // arg error occurred, print error message and exit printf("ERROR: %s\n", cmdline); printf(" %s %s\n", errmark, errmsg); return 1; } } // get here only if command line args ok printf("title: \"%s\"\n",str); printf("gradient: %f\n",grad); printf("y-intercept: %d\n",c); return 0; } \endcode Here are some results of running myprog with various command line arguments. \verbatim $ myprog Usage: myprog [-tit <title>] grad:gradient [y-int] -tit <title> your title grad:gradient line gradient y-int y-intercept $ myprog grad:10 title: "noname" gradient: 10.000000 y-intercept: 0 $ myprog 7 grad:1.234 title: "noname" gradient: 1.234000 y-intercept: 7 $ myprog -tit "hello world" grad:3.33 11 title: "hello world" gradient: 3.330000 y-intercept: 11 \endverbatim */ /** \page Release Release Notes. \par Argtable-2.0 coming eventually. Argtable-2.0 will be a major overhaul of the code. The changes are required to address the most common complaint about argtable; the potential for buffer overruns as argtable writes into fixed size string buffers. The redesign will bring some inevitable changes to the library interface, but the basic look and feel of the argument tables will stay the same. I been promising to finish Argtable-2.0 for a very long time. Well, one of the days.... \par Argtable-1.3 released December 20, 2001. Moved argtable to a new home on the \b sourceforge site and revamped the documentation. Documentation is now created with \b Doxygen instead of \b c2man. Also fixed some minor bugs in the Makefiles. The source code itself is unaltered. \par Argtable-1.2 released August 5, 1999. The original makefiles have been replaced by autoconf makefiles. The char pointers in the argument table have been redefined as pointers to const char. Some of argtable's internal string buffers have been made larger to accommodate long command lines, and a bug that occurred when program names contained whitespace has been fixed. The documentation has also been revised. \par Argtable-1.1 released January 20, 1999. This version fixes some cross-platform compilation errors, and saw the introduction of the multi-platform configuration. It also saw the addition of the arg_record() function and a change to the arg_scanargv() function so that it no longer requires argv[0] to be the first entry of the argument table. To maintain backwards compatibility, programs written for version 1.0 should now define the macro #define ARGTABLE_COMPATIBILITY_10 prior to including the argtable.h header file. \par Argtable-1.0 released November 13, 1998. Argtable's debut! */ #endif