argtable.h(3) Argtable argtable.h(3)
21 Dec 2001
NAME
argtable.h -
SYNOPSIS
#include <stdio.h>
Data Structures
struct arg_rec
Defines
#define ARGTABLE_VERSION 1.3
Enumerations
enum arg_type { arg_int = 0, arg_dbl, arg_str, arg_bool, arg_lit }
Functions
int arg_scanargv (int argc, char **argv, arg_rec *argtable, int n, char
*CmdLine, char *ErrMsg, char *ErrMark)
Parse the command line as per a given argument table.
int arg_scanstr (char *str, arg_rec *argtable, int n, char *ErrMsg,
char *ErrMark)
Parse a string as per a given argument table.
const char* arg_syntax (const arg_rec *argtable, int n)
Generates a 'usage' syntax string from an argument table.
const char* arg_glossary (const arg_rec *argtable, int n, const char
*prefix)
Generate a glossary string from an argument table.
void arg_catargs (int argc, char **argv, char *str)
Concatenate all argv[] arguments into a single string.
arg_rec arg_record (char *tagstr, char *argname, arg_type argtype, void
*valueptr, char *defaultstr, char *argdescrip)
Builds and returns an argument table record.
void arg_dump (FILE *fp, const arg_rec *argtable, int n)
Print the contents of an argument table.
Variables
const char* arg_typestr []
DEFINE DOCUMENTATION
#define ARGTABLE_VERSION 1.3
ENUMERATION TYPE DOCUMENTATION
enum arg_type
arg_type enums are used in the argument table to define the data type
of a command line argument.
Enumeration values:
arg_int
Integer value.
- 1 - Formatted: November 14, 2024
argtable.h(3) Argtable argtable.h(3)
21 Dec 2001
arg_dbl
Double value.
arg_str
Ascii string; may be quoted or un-quoted.
arg_bool
Boolean; accepts the keywords yes, no, true, false, on , or 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.
FUNCTION DOCUMENTATION
int arg_scanargv (int argc, char **
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.
Parameters:
argc number of entries in argv[].
argv command line arguments.
- 2 - Formatted: November 14, 2024
argtable.h(3) Argtable argtable.h(3)
21 Dec 2001
argtable
pointer to the argument table.
n number of entries in argtable[].
CmdLine
pointer to storage for command line (may be NULL).
ErrMsg
pointer to storage for error message (may be NULL).
ErrMark
pointer to storage for error marker (may be NULL).
int arg_scanstr (char * str, arg_rec
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 arg_scanargv, this function erases the scanned
arguments from *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.
Parameters:
str pointer to command line string.
argtable
pointer to the argument table.
n number of array elements in argtable[].
ErrMsg
pointer to storage for error message (may be NULL).
ErrMark
pointer to storage for error marker (may be NULL).
const char * arg_syntax (const arg_rec
Builds a syntactical description of the allowable command line
arguments specified by the 'argtable' array. The resulting string is
- 3 - Formatted: November 14, 2024
argtable.h(3) Argtable argtable.h(3)
21 Dec 2001
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 <double>] [-o <outfile>] [-verbose] <infile>
[debug=<on/off>]"
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 <int>, <double>, or <string>. 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.
Parameters:
argtable
pointer to the argument table
n number of array elements in argtable[]
const char * arg_glossary (const arg_rec
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 <description> 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
"<prefix><tag><name><description>"
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 <tag> fields in the argument table will appear in the
glosssary as empty strings.
Any NULL <name> fields will be substituted by a description of that
argument's data type, enclosed in angled brackets, as in <int> and
<double>. 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.
- 4 - Formatted: November 14, 2024
argtable.h(3) Argtable argtable.h(3)
21 Dec 2001
Parameters:
argtable
pointer to the argument table
n number of array elements in argtable[]
prefix
a string to be prefixed to each line of the output
void arg_catargs (int argc, char **
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.
Parameters:
argc number of arguments in argv[]
argv command line arguments
str pointer to destination string
arg_rec arg_record (char * tagstr, char
Returns an arg_rec structure containing the values passed to the
function. It is useful for building argument tables dynamically.
Parameters:
tagstr
argument tag string
argname
argument name string
argtype
argument data type
valueptr
pointer to user-supplied storage location
defaultstr
default argument value, as a string
- 5 - Formatted: November 14, 2024
argtable.h(3) Argtable argtable.h(3)
21 Dec 2001
argdescrip
argument description string
void arg_dump (FILE * fp, const
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.
Parameters:
fp output stream
argtable
pointer to the argument table
n number of array elements in argtable[]
VARIABLE DOCUMENTATION
const char * arg_typestr
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.
arg_str[arg_int] = "<int>";
arg_str[arg_dbl] = "<double>";
arg_str[arg_str] = "<string>";
arg_str[arg_bool] = "<bool>";
arg_str[arg_lit] = "";
AUTHOR
Generated automatically by Doxygen for Argtable from the source
- 6 - Formatted: November 14, 2024
