NAME
arg_scanargv - Scan the command line as per the given argument table.
SYNOPSIS
#include <argtable.h>
int (arg_scanargv)(int argc, char **argv, arg_rec *argtable, int n, char *CmdLine, char *ErrMsg, char *ErrMark);
PARAMETERS
-
int argc
-
Number of entries in 'argv'.
-
char **argv
-
Ptr to command line arguments.
-
arg_rec *argtable
-
Ptr to argument table.
-
int n
-
Number of entries in argtable[].
-
char *CmdLine
-
Ptr to storage for command line (may be NULL).
-
char *ErrMsg
-
Ptr to storage for error message (may be NULL).
-
char *ErrMark
-
Ptr to storage for error marker (may be NULL).
DESCRIPTION
Attempts to resolve the command line arguments given in argv[]
with the specifications given in the argument table.
The values scanned from the command line are written directly into
the chosen memory locations as specified by each argument table
entry. Notice that the program name, in argv[0], is not treated as
an argument and does not require an entry in the argument table.
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.
RETURN VALUE
Returns 1 upon success, 0 upon failure.
THE ARGUMENT TABLE
The argument table is an array of arg_rec structs, and has one entry
for each command line argument that is expected.
It is most conveniently defined and initialised as a
static array within the main block, but need not be so.
We know that the first argument in argv[0] is always going to be the
name of the executable so arg_scanargv() skips it during the scanning
phase, starting instead with argv[1]. Thus the first entry of an
argument table refers to argv[1] and not argv[0] (This was not the
case in argtable version 1.0).
ANATOMY OF AN ARGUMENT TABLE ENTRY
The arg_rec structure has six members; a tag string, an argument name,
an argument type, a pointer to a user-supplied data location, a default
value (as a string), and a description string.
A typical table entry might look like,
{ "--Bs", "<size>", arg_int, &blcksize, "1024", "\\ttape block size" }
Here, we have a tagged integer argument whose value is to be stored
in the program variable called "blcksize". It would be used on the
command line as --bs 2048 for example.
In our case, the argument has a default value of 1024 that is
converted from a string to an integer and written into blcksize
whenever a corresponding argument cannot be found on the command line.
If the default value was instead given as NULL then the argument would
be regarded as mandatory.
Because our argument has a tag it may, unlike untagged arguments, be used
anywhere on the command line.
Furthermore, there need not be any space between the tag and the
subsequent argument value, so --bs 2048 and --bs2048 would both be
accepted. You can force the presence of whitespace between the
tag and the value by putting a trailing space in the tag string, as in
"--bs ". The choice is yours.
The argument name "<size>" has no effect on the argument processing.
It is just a descriptive name used to represent the argument in the
output of the arg_syntax() and arg_glossary() functions, which in our
case would appear as "--bs<size>".
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 instead you specify a NULL name string,
it is automatically replaced by the arguments 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.
Like the name string, the description string "\\ttape block size" does not
affect the processing. It is only used by the arg_glossary function, which
in our case would produce a glossary entry of
"--bs<size> tape block size".
Arguments with NULL description strings are omitted from the glossary
altogether.
See arg_syntax() and arg_glossary() for more details on the name and
description fields.
An argument may also be untagged, as in the following string
argument,
{ NULL, "<infile>", arg_str, infilename, NULL, " input file" }
This argument has no tag and no default value and stores its result in the
user-defined string called "infilename".
Untagged arguments are expected to appear on the command line in the
same order as they are defined in the argument table.
When tagged and untagged arguments are mixed, the argument table is
processed in two passes. The first pass extracts all the tagged
arguments from the command line, the second pass extracts the
remaining untagged arguments from left to right.
As a final note, argtable entries may be given a NULL in place of the
pointer-to-void entry that specifies the location of the user-defined
program variable. Such arguments are still scanned from the command line in
the normal way, but the resulting value is discarded.
ARGUMENT DATA TYPES
It is imperative that the data type of program variable used to store
the argument's value matches the enum arg_type given in the third
column of the argument table. If you get this wrong you can you can
expect very spurious behaviour from the argtable functions.
The enum arg_type is defined as
Typedef enum {arg_int, arg_dbl, arg_str, arg_bool, arg_lit} arg_type;
Its values correspond to integer, double, string and boolean data types
followed by a special string literal type. The boolean type stores its
value as an integer that is either 0 or 1. The arg_lit type is a special
case which is discussed in detail later, for now it is suffice to say that
it too stores an integer value.
The arg_bool type does not read an integer value from the command line,
rather it expects one of the keywords "true", "false", "yes", "no", "on",
or "off" which it then converts to 0 (false,no,off) or 1 (true,yes,on).
For example, the argument
{ "Debug:", NULL, arg_bool, &dbg, "false", "\\tdebugging option" }
Defines an optional tagged boolean argument whose default value is 0 (false).
It may appear on the command line as any of debug:true, debug:yes,
debug:on, debug:false, debug:off, or debug:no.
The value 0 or 1 is written into the integer program variable "dbg".
The arg_lit type represents a special argument type. Unlike the other
arguments, it does not scan a parameterised value from the command line.
Instead, it just expects a given string literal to be
present on the command line, as in --verbose or --help.
The string literal can be defined in either the tag or the name string
fields. If you use the tag then the string literal, like other tagged
arguments, may appear anywhere on the command line. On the other hand,
if you use the name string, then the string 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.
The following arg_lit argument shows how to implement a --verbose command
line switch,
{ "--Verbose ", NULL, arg_lit, &verbosity, "0", "\\tverbosity switch" }
Should --verbose be given on the command line, the value 1 is written
into the integer program variable named "verbosity", otherwise the default
value of 0 is used instead.
Another use of the arg_lit type is to enforce the presence of a given
keyword on the command line. This is useful to help distinguish individual
command line usages when multiple candidate argument tables can be
be applied. For example, the argtable entry
{ NULL, "geometric", arg_lit, NULL, NULL, NULL }
Has no tag, no default, no storage location, and no description. It
simply defines the string literal "geometric" which must be present at
a specific location on the command line for the argument table to be
succesfully resolved. A sister argument table might have the entry
{ NULL, "linear", arg_lit, NULL, NULL, NULL }
In the same argument position. Thus, the keywords "geometric"
and "linear" are used to distinguish the two possible usages.
SEE ALSO
arg_catargs
,
arg_dump
,
arg_glossary
,
arg_record
,
arg_scanstr
,
arg_syntax
,
arg_typestr