Home   Intro   Tutorial   argtable.h   arg_rec   Globals   Release Notes  

arg_rec Struct Reference

#include <argtable.h>


Data Fields

const char* tagstr
const char* argname
arg_type argtype
void* valueptr
const char* defaultstr
const char* argdescrip


Detailed Description

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).

 //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 ",      "<outfile>", arg_str,  outfname, "-",   "output file" },
   { "-verbose", NULL,        arg_lit,  &verbose, "0",   "verbose output" },
   { NULL,       "<infile>",  arg_str,  infname,  NULL,  "input file" },
   { "debug=",   "<on/off>",  arg_bool, &debug,   "off", NULL },
   };
 const size_t narg = sizeof(argtable)/sizeof(arg_rec);


Field Documentation

const char * arg_rec::tagstr
 

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 * arg_rec::argname
 

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 "<size>=1024". If a NULL name string is given, it is automatically replaced by the argument's data type enclosed in angled brackets, as in "<integer>". If you dislike such behaviour, you can effectively suppress the name by defining it as an empty string.

arg_type arg_rec::argtype
 

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.

void * arg_rec::valueptr
 

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.

  • arg_int arguments require int storage.
  • arg_double arguments require double storage.
  • arg_str arguments require a char buffer big enough to store the expected result (you'll have to guess what big enough is!).
  • arg_bool arguments require int storage.
  • arg_lit arguments require 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.

const char * arg_rec::defaultstr
 

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 * arg_rec::argdescrip
 

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.


Argtable (http://argtable.sourceforge.net)