<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
<TITLE>Advanced argtable topics</TITLE>
<META NAME="GENERATOR" CONTENT="OpenOffice.org 1.9.129 (Linux)">
<META NAME="CREATED" CONTENT="20030925;11311700">
<META NAME="CHANGED" CONTENT="20051216;11435800">
<META NAME="CLASSIFICATION" CONTENT="ANSI C command line parser">
<META NAME="KEYWORDS" CONTENT="command line parser">
<STYLE>
<!--
@page { size: 21.01cm 29.69cm }
H1 { margin-top: 2.01cm }
PRE { margin-left: 0.76cm }
PRE.western { font-size: 9pt }
-->
</STYLE>
</HEAD>
<BODY LANG="en-GB" DIR="LTR">
<H1 ALIGN=CENTER>Advanced argtable-2.x topics<BR><FONT SIZE=3>An ANSI
C library for parsing GNU style command line arguments</FONT></H1>
<P ALIGN=CENTER STYLE="margin-bottom: 0.99cm">Stewart
Heitmann<BR><I>sheitmann@users.sourceforge.net</I></P>
<H2>1. Parsing optional argument values</H2>
<P STYLE="margin-bottom: 0cm"><I><B>example code:</B>
<FONT FACE="Bitstream Vera Serif"><installdir>/share/doc/argtable2/example/hasoptvalue.c</FONT></I></P>
<P STYLE="margin-top: 0.51cm; margin-bottom: 0.51cm">This topic shows
how to use define command line arguments that take optional argument
values as in --foo=[<int>]. Consider the following syntax:</P>
<PRE CLASS="western">Usage: foobar -f <int> -b [<int>]
This program demonstrates the use of the argtable2 library
-f, --foo=<int> takes an integer value (defaults to 9)
-b, --bar=[<int>] takes an optional integer value (defaults to 5)</PRE><P ALIGN=LEFT STYLE="margin-bottom: 0cm">
Notice that the -f argument takes a mandatory argument value (eg:
-f4) , whereas the -b argument may or may not be given a value (eg:
-b5 or -b are both legal) even though both are defined in the
argument table in the same way.</P>
<PRE CLASS="western"><B>struct</B> arg_int *foo = arg_int1("f","foo", NULL,"takes an integer value (defaults to 9)");
<B>struct</B> arg_int *bar = arg_int1("b","bar", NULL,"takes an optional integer value (defaults to 5)");
<B>struct</B> arg_end *end = arg_end(20);
void* argtable[] = {foo,bar,end};
int nerrors;</PRE><P ALIGN=LEFT STYLE="margin-bottom: 0cm">
<BR>
</P>
<P ALIGN=LEFT STYLE="margin-bottom: 0cm">To have the -b argument
accept optional values we must set the following flag in its argtable
hdr structure.</P>
<P ALIGN=LEFT STYLE="margin-bottom: 0cm"><BR>
</P>
<PRE CLASS="western" STYLE="margin-bottom: 0.5cm; font-weight: medium">bar->hdr.flag |= ARG_HASOPTVALUE;</PRE><P>
Whenever an optional argument value is omitted from the command line
the argument is counted as a valid one, though the argument value
itself is left unaltered. Hence, any desired default values should be
manually assigned prior to parsing.</P>
<PRE CLASS="western">/* set foo default values to 9 */
for (i=0; i<foo->hdr.maxcount; i++)
foo->ival[i]=9;
/* set bar default values to 5 */
for (i=0; i<bar->hdr.maxcount; i++)
bar->ival[i]=5;
/* Parse the command line as defined by argtable[] */
nerrors = arg_parse(argc,argv,argtable);</PRE><H2>
2. Parsing multiple command line syntaxes</H2>
<P STYLE="margin-bottom: 0cm"><I><B>example code:</B>
<FONT FACE="Bitstream Vera Serif"><installdir>/share/doc/argtable2/example/multisyntax.c</FONT></I></P>
<P STYLE="margin-top: 0.51cm; margin-bottom: 0.51cm">This topic shows
how to use argtable to implement a program having multiple
alternative command line syntaxes. In this case our example program
has four alternate syntaxes as follows:</P>
<PRE CLASS="western">Usage: multisyntax [-nvR] insert <file> [<file>]... [-o <output>]
multisyntax [-nv] remove <file>
multisyntax [-v] search <pattern> [-o <output>]
multisyntax [--help] [--version]
This program demonstrates the use of the argtable2 library for parsing multiple command line syntaxes.
-n take no action
-v, --verbose verbose messages
-R recurse through subdirectories
<file> input file(s)
-o <output> output file (default is "-")
<pattern> search string
--help print this help and exit</PRE><P STYLE="margin-bottom: 0cm">
A separate argument table is defined for each alternate syntax and
each is parsed against the command line in turn. That syntax which
returns no errors is taken to be the winner. Should no syntax match
the command line then the appropriate error messages are displayed
and the program exits. Obviously, you must design your alternate
syntaxes to be mutually exclusive, otherwise your program syntax will
be ambiguous. Mutual exclusion is achieved in this case by the use of
keywords (insert, remove, search) in the command line which uniquely
identify each syntax.</P>
<P STYLE="margin-top: 0.25cm; margin-bottom: 0.51cm">Looking at the
code, we see that each syntax is defined by its own argument table as
follows:</P>
<PRE CLASS="western">/* SYNTAX 1: insert [-nvR] <file> [file]... -o <file> */
<B>struct</B> arg_rex *cmd1 = arg_rex1(NULL, NULL, "insert", NULL, REG_ICASE, NULL);
<B>struct</B> arg_lit *noact1 = arg_lit0("n", NULL, "take no action");
<B>struct</B> arg_lit *verbose1 = arg_lit0("v", "verbose", "verbose messages");
<B>struct</B> arg_lit *recurse1 = arg_lit0("R", NULL, "recurse through subdirectories");
<B>struct</B> arg_file *infiles1 = arg_filen(NULL,NULL, NULL, 1,argc+2, "input files)");
<B>struct</B> arg_file *outfile1 = arg_file0("o", NULL, "<output>", "output file (default is \"-\")");
<B>struct</B> arg_end *end1 = arg_end(20);
<B>void</B>* argtable1[] = {cmd1,noact1,verbose1,recurse1,infiles1,outfile1,end1};
<B>int</B> nerrors1;
/* SYNTAX 2: remove [-nv] <file> */
<B>struct</B> arg_rex *cmd2 = arg_rex1(NULL, NULL, "remove", NULL, REG_ICASE, NULL);
<B>struct</B> arg_lit *noact2 = arg_lit0("n", NULL, NULL);
<B>struct</B> arg_lit *verbose2 = arg_lit0("v", "verbose", NULL);
<B>struct</B> arg_file *infiles2 = arg_file1(NULL, NULL, NULL, NULL);
<B>struct</B> arg_end *end2 = arg_end(20);
<B>void</B>* argtable2[] = {cmd2,noact2,verbose2,infiles2,end2};
<B>int</B> nerrors2;
/* SYNTAX 3: search [-v] <pattern> [-o <file>] [--help] [--version] */
<B>struct</B> arg_rex *cmd3 = arg_rex1(NULL, NULL, "search", NULL, REG_ICASE, NULL);
<B>struct</B> arg_lit *verbose3 = arg_lit0("v", "verbose", NULL);
<B>struct</B> arg_str *pattern3 = arg_str1(NULL, NULL, "<pattern>", "search string");
<B>struct</B> arg_file *outfile3 = arg_file0("o", NULL, "<output>", NULL);
<B>struct</B> arg_end *end3 = arg_end(20);
<B>void</B>* argtable3[] = {cmd3,verbose3,pattern3,outfile3,end3};
<B>int</B> nerrors3;
/* SYNTAX 4: [-help] [-version] */
<B>struct</B> arg_lit *help4 = arg_lit0(NULL,"help", "print this help and exit");
<B>struct</B> arg_lit *version4 = arg_lit0(NULL,"version", "print version information and exit");
<B>struct</B> arg_end *end4 = arg_end(20);
<B>void</B>* argtable4[] = {help4,version4,end4};
<B>int</B> nerrors4;</PRE><P STYLE="margin-bottom: 0cm">
Notice that the argument tables keep their contents separate from
each other. While it may be tempting to share an <I><FONT FACE="Bitstream Vera Serif">arg_xxx</FONT></I>
structure between multiple argument tables, that will not work in
this example code since the contents of any shared <I><FONT FACE="Bitstream Vera Serif">arg_xxx</FONT></I>
structure will be repeatedly overwritten when each successive
argument table is parsed.</P>
<P STYLE="margin-bottom: 0cm">The insert/remove/search keywords are
implemented using <I><FONT FACE="Bitstream Vera Serif">arg_rex</FONT></I>
arguments. These are parsed as untagged string arguments that must
match a given regular expression: "insert", "remove",
and "search" respectively. The REG_ICASE regex flag is also
given to allow case insensitive regular expression matching as a
nicety. See the argtable programmer's manual for more information of
the <I><FONT FACE="Bitstream Vera Serif">arg_rex</FONT></I> argument
type.</P>
<P STYLE="margin-bottom: 0.51cm">Since we have multiple argument
tables, you'll need to pre-set any default argument values in every
argument table in which the value appears. Here we set the default
value of the output filename argument which appears in both the first
and third argument tables as <I><FONT FACE="Bitstream Vera Serif">struct
arg_file *outfile1</FONT></I> and <I><FONT FACE="Bitstream Vera Serif">struct
arg_file *outfile2</FONT></I> respectively.</P>
<PRE CLASS="western">/* set any command line default values prior to parsing */
outfile1->filename[0]="-";
outfile3->filename[0]="-";</PRE><P STYLE="margin-bottom: 0.51cm">
Having completed the argument tables, the command line is parsed
against each argument table in turn and we record the number of
errors reported by each.</P>
<PRE CLASS="western">nerrors1 = arg_parse(argc,argv,argtable1);
nerrors2 = arg_parse(argc,argv,argtable2);
nerrors3 = arg_parse(argc,argv,argtable3);
nerrors4 = arg_parse(argc,argv,argtable4);</PRE><P STYLE="margin-bottom: 0.51cm">
If any of these return zero errors then we have detected a successful
matching command line and we can pass the argument data from the
matching argument table to our program's main processing routine.
</P>
<PRE CLASS="western"><B>if</B> (nerrors1==0)
exitcode = mymain1(noact1->count, verbose1->count, recurse1->count,
outfile1->filename[0], infiles1->filename, infiles1->count);
<B>else</B> <B>if</B> (nerrors2==0)
exitcode = mymain2(noact2->count, verbose2->count, infiles2->filename[0]);
<B>else</B> <B>if</B> (nerrors3==0)
exitcode = mymain3(verbose3->count, pattern3->sval[0], outfile3->filename[0]);
<B>else</B> <B>if</B> (nerrors4==0)
exitcode = mymain4(help4->count, version4->count, progname,
argtable1, argtable2, argtable3, argtable4);</PRE><P STYLE="margin-bottom: 0cm">
Should they all return errors then we must display the appropriate
syntax error messages. The trick is knowing which error messages to
display. Simply displaying the error messages for each and every
syntax will work, but is overkill as it generates a lot of irrelevant
messages. A better strategy is to display only those errors related
to the syntax that gave the fewest errors on the presumption that the
user got it mostly correct. The strategy used in this example however
is to utilise the presence of any keywords ("insert",
"remove", "search") as markers to indicate which
syntax the user intended and only display the errors for that syntax.
Remember that the keywords were implemented using <I><FONT FACE="Bitstream Vera Serif">arg_rex</FONT></I>
argument structures (<FONT FACE="Bitstream Vera Serif"><I>cmd1</I>,
<I>cmd2</I>, <I>cmd3</I></FONT>) and these will return a count of 0
if the keyword was missing from the command line and 1 otherwise.
Thus we can test the presence of each keyword by checking the count
value stored in the <I>cmd1</I>, <I>cmd2</I>, and <I>cmd3</I>
structures.
</P>
<P STYLE="margin-bottom: 0.51cm">So if the "insert" keyword
was given on the command line then we display only those errors
associated with the first argument table, namely, the errors stored
in <I><FONT FACE="Bitstream Vera Serif">struct arg_end *end1</FONT></I>.</P>
<PRE CLASS="western"><B>if</B> (cmd1->count > 0)
{
<I>/* here the cmd1 argument was correct, so presume syntax 1 was intended target */</I>
arg_print_errors(stdout,end1,progname);
printf("usage: %s ", progname);
arg_print_syntax(stdout,argtable1,"\n");
}</PRE><P STYLE="margin-bottom: 0.51cm">
Likewise for the "remove" and "search" keywords
of the second and third argument tables</P>
<PRE CLASS="western"><B>else</B> <B>if</B> (cmd2->count > 0)
{
<I>/* here the cmd2 argument was correct, so presume syntax 2 was intended target */</I>
arg_print_errors(stdout,end2,progname);
printf("usage: %s ", progname);
arg_print_syntax(stdout,argtable2,"\n");
}
<B>else</B> <B>if</B> (cmd3->count > 0)
{
<I>/* here the cmd3 argument was correct, so presume syntax 3 was intended target */</I>
arg_print_errors(stdout,end3,progname);
printf("usage: %s ", progname);
arg_print_syntax(stdout,argtable3,"\n");
}</PRE><P STYLE="margin-bottom: 0.51cm">
If none of the keywords were detected we display a message to that
effect followed by the full usage description.</P>
<PRE CLASS="western">else
{
<I>/* no correct cmd literals were given, so we cant presume which syntax was intended */</I>
printf("%s: missing <insert|remove|search> command.\n",progname);
printf("usage 1: %s ", progname); arg_print_syntax(stdout,argtable1,"\n");
printf("usage 2: %s ", progname); arg_print_syntax(stdout,argtable2,"\n");
printf("usage 3: %s ", progname); arg_print_syntax(stdout,argtable3,"\n");
printf("usage 4: %s", progname); arg_print_syntax(stdout,argtable4,"\n");
}</PRE><P STYLE="margin-bottom: 0.51cm">
Lastly, remember to clean up all the argument tables at program's
end.</P>
<PRE CLASS="western">arg_freetable(argtable1,sizeof(argtable1)/sizeof(argtable1[0]));
arg_freetable(argtable2,sizeof(argtable2)/sizeof(argtable2[0]));
arg_freetable(argtable3,sizeof(argtable3)/sizeof(argtable3[0]));
arg_freetable(argtable4,sizeof(argtable4)/sizeof(argtable4[0]));</PRE><H2>
3. Writing custom callbacks</H2>
<P STYLE="margin-bottom: 0cm"><I><B>example code:</B>
<FONT FACE="Bitstream Vera Serif"><installdir>/share/doc/argtable2/example/callbacks.c</FONT></I></P>
<P STYLE="margin-top: 0.51cm; margin-bottom: 0.51cm">This topic shows
how to write your own argtable callback functions for controlling the
parsing, validation, and error reporting aspects of the command line
parsing. Each <I>arg_xxx</I> struct has four callback routines that
get called by the argtable parser. These are buried within the
<I>arg_hdr</I> structure that each <I>arg_xxx</I> structure has.
Among other things, you can see the relevant function pointers below.
They are called <I>resetfn</I>, <I>scanfn</I>, <I>checkfn</I>, and
<I>errorfn</I>.</P>
<PRE CLASS="western">typedef void (arg_resetfn)(void *parent);
typedef int (arg_scanfn)(void *parent, const char *argval);
typedef int (arg_checkfn)(void *parent);
typedef void (arg_errorfn)(void *parent, FILE *fp, int error, const char *argval, const char *progname);
struct arg_hdr
{
<FONT COLOR="#000000">char flag;</FONT>
const char *shortopts;
const char *longopts;
const char *datatype;
const char *glossary;
int mincount;
int maxcount;
void *parent;
<B>arg_resetfn *resetfn;</B>
<B>arg_scanfn *scanfn; </B>
<B>arg_checkfn *checkfn;</B>
<B>arg_errorfn *errorfn;</B>
<FONT COLOR="#000000">void *priv;</FONT><FONT COLOR="#666666"> </FONT>
};</PRE><P STYLE="margin-bottom: 0cm">
These function pointers are always pre-set by the <I>arg_xxx</I>
constructor functions to the default routines for that argument type
and ordinarily there is no need to change them. However, you may
replace them with your own custom routines if you wish. Thus when
argtable parses the command line for these particular argument types,
it will call your custom callbacks rather than the default routines.
However responsibility comes with control, and all callbacks must
implement certain features that argtable expects. These are each
discussed in turn.</P>
<H4>void resetfn(void *parent)</H4>
<P STYLE="margin-bottom: 0.51cm">The <I>resetfn</I> of each <I>arg_xxx</I>
within an argument table is called once by the parser prior to
parsing the command line. This provides the opportunity to initialise
the <I>arg_xxx</I> structure prior to parsing and nominally requires
resetting the argument count to zero. The <I>parent</I> parameter is
actually a pointer to the pertinent <I>arg_xxx</I> structure, and
should be cast appropriately. The casting may be done in the function
definition as shown in this example for an <I>arg_int</I> struct.
</P>
<PRE CLASS="western">void myresetfn(struct arg_int *parent)
{
parent->count=0;
}</PRE><P STYLE="margin-bottom: 0cm">
The storage space for the parsed argument values should <U>not</U> be
initialised since the user may have deliberately set default values
that should be retained.</P>
<H4>int scanfn(void *parent, const char *argval)</H4>
<P STYLE="margin-bottom: 0.51cm">The parser calls an <I>arg_xxx</I>'s
scanfn routine once for each matching command line argument that
needs to be parsed. Its purpose is to extract the argument's data
value from the argument string in <I>argval</I>, convert it to the
appropriate data type, and store the result in the <I>arg_xxx</I>'s
data array. It must handle NULL argval as will occur when an argument
with optional value is invoked. The function must return zero to
indicate success and a non-zero error code otherwise. The error codes
may be of your own choosing as they will latter be handled by your
own <I>errorfn</I> callback.</P>
<PRE CLASS="western">enum {EMINCOUNT=1, EMAXCOUNT, EBADINT};
int myscanfn(struct arg_int *parent, const char *argval)
{
int val;
char *end;
<I>/* return EMAXCOUNT if we have exceeded the maximum argument count */</I>
if (parent->count == parent->hdr.maxcount )
return EMAXCOUNT;
/* if argval is NULL then no argument value was given */
/* this will only happen for arguments that allow optional values */
/* in which case we leave the parent data value unaltered and */
/* count this as a valid argument (which it is) */
if (!argval)
{
parent->count++;
return 0;
}
/* extract base10 integer from argval string into val */
/* return EBADINT if conversion failed */
val = (int)strtol(argval,&end,10);
if (*end!=0)
return EBADINT;
<I>/* <perform custom checks here> */</I>
/* store the value in parent's ival[] array and increment the argument count */
parent->ival[parent->count++] = val;
/* return zero to indicate success */
return 0;
}</PRE><P STYLE="margin-bottom: 0cm">
Do <U>not</U> print error messages from within <I>scanfn</I> as the
user may wish to delay the error messages until alternative argument
tables have been tried. In the meantime the parser will save each
returned error code in the argument table's <I>arg_end</I> structure.
Latter, the <I>arg_print_errors</I> function will be called to
retrieve those error codes from <I>arg_end</I> and pass them onto the
<I>errorfn</I> callbacks whose job is to print the appropriate
messages.</P>
<H4>int checkfn(void *parent)</H4>
<P STYLE="margin-bottom: 0.51cm">The <I>checkfn</I> of each <I>arg_xxx</I>
within an the argument table is called by the parser once upon
completion of command line parsing. It provides the opportunity to
perform any post-parse error checks and nominally requires checking
the minimum argument count for the <I>arg_xxx</I> structure has been
satisfied.
</P>
<PRE CLASS="western">int mycheckfn(struct arg_int *parent)
{
<I>/* return EMINCOUNT if the minimum number of arguments is not present. */</I>
if (parent->count < parent->hdr.mincount)
return EMINCOUNT;
<I>/* <perform custom checks here> */</I>
<I>/* all checks passed */</I>
return 0;
}</PRE><P STYLE="margin-bottom: 0cm">
Like scanfn, it should return zero for success and a user-defined
non-zero error code otherwise. These error codes are likewise
destined to be passed onto errorfn.</P>
<H4>int errorfn(void *parent, FILE *fp, int errorcode, const char
*argval, const char *progname)</H4>
<P STYLE="margin-bottom: 0.51cm">When the users wishes to print the
syntax error messages he or she calls the <I>arg_print_errors</I>
function which in turn calls the <I>errorfn</I> routine of each
<I>arg_xxx</I> for each error that was previously reported. This is
where the error messages for the corresponding error codes are
printed. The <I>parent</I> pointer refers to the pertinent <I>arg_xxx</I>
structure, and <I>FILE* fp</I> designates the output stream onto
which the error messages should be printed. The <I>errorcode</I>
parameter contains the same value returned by the <I>scanfn</I> or
<I>checkfn</I> routine that reported the error, and <I>argval</I>
points to the offending command line argument string. The <I>progname</I>
parameter is the same one passed to the <I>arg_print_errors</I>
function, and is expected to contain the name of the program which is
usually prefixed onto the error message by convention. Notice that
each <I>arg_xxx</I> need only handle the error codes generated by its
own <I>scanfn</I> and <I>checkfn</I> routines.</P>
<PRE CLASS="western">void myerrorfn(struct arg_int *parent, FILE *fp, int errorcode, const char *argval, const char *progname)
{
<I>/* for convenience */</I>
const char *shortopts = parent->hdr.shortopts;
const char *longopts = parent->hdr.longopts;
const char *datatype = parent->hdr.datatype;
/* make argval NULL safe */
<I>argval = argval ? argval : "";</I>
<I>/* prefix all error messages with the program name */</I>
fprintf(fp,"%s: ",progname);
switch(errorcode)
{
case EMINCOUNT:
fputs("missing option ",fp);
arg_print_option(fp,shortopts,longopts,datatype,"\n");
break;
case EMAXCOUNT:
fputs("excess option ",fp);
arg_print_option(fp,shortopts,longopts,argval,"\n");
break;
case EBADINT:
arg_print_option(fp,shortopts,longopts,argval," is not a valid <int>\n");
break;
<I>/* <add custom error messages here> */</I>
}
}</PRE><H4>
Hooking the callbacks into the arg_xxx structure</H4>
<P STYLE="margin-bottom: 0.51cm">There are no functions for
registering callbacks with arg_xxx structures, you simply write the
function pointers directly into the arg_xxx structure after it has
been constructed.</P>
<PRE CLASS="western">struct arg_int *val = arg_intn(NULL,NULL,NULL,2,100,"blah blah");
/* replace the default arg_int parser routines with custom routines */
val->hdr.resetfn = (arg_resetfn*)myresetfn;
val->hdr.scanfn = (arg_scanfn*)myscanfn;
val->hdr.checkfn = (arg_checkfn*)mycheckfn;
val->hdr.errorfn = (arg_errorfn*)myerrorfn;</PRE><H4>
Words of restraint</H4>
<P STYLE="margin-bottom: 0cm">Callbacks are part of the argtable
design to make it possible to add new argument data types in future
without changing the base argtable source code. Since they exist,
they may be exploited by the programmer for finer control of the
parsing and error validation but that was never their intended role.
It is the authors view that the majority of custom argument checking
tasks are better done as a second stage in your program after
argtable has done its job. It is usually much simpler to implement
additional post-parse checks in your own code than creating custom
argtable callbacks that do it all. Custom callbacks are really only
required if you are scanning data types that argtable does not
support natively. In such cases you may also need to create a custom
arg_xxx structure in which to store the results, as is described in
the next topic.</P>
<H2>4. Creating custom argument types</H2>
<P STYLE="margin-bottom: 0cm"><I><B>example code:</B>
<FONT FACE="Bitstream Vera Serif"><installdir>/share/doc/argtable2/example/argcustom.c,
argxxx.c, argxxx.h</FONT></I></P>
<P STYLE="margin-top: 0.51cm; margin-bottom: 0cm">This topic shows
how to write new argument types for use with the argtable parser.
These need not be compiled into the library base code, so you can
create custom argument types for specific programs at will. A custom
argument type is required if you need to handle a data type that is
not supported natively by the argtable library. It involves defining
a new <I>arg_xxx</I> structure and writing the callback and
constructor functions that go with it. If you merely wish to alter
the parsing and validation rules applied to an existing <I>arg_xxx</I>
data type then hooking your own custom callbacks into the existing
structure as described in the previous topic is more appropriate.</P>
<H4>Defining an arg_xxx structure</H4>
<P STYLE="margin-bottom: 0.51cm">Every <I>arg_xxx</I> struct must
have an <I>arg_hdr</I> struct as its first data member. Internally,
argtable casts all <I>arg_xxx</I> structures to <I>arg_hdr</I>
structures, so it is imperative that <I>arg_hdr</I> be the first data
member. Argtable uses the information within it to cast the command
line option into the format required by GNU getopt which actually
does the parsing.</P>
<PRE CLASS="western">struct arg_xxx
{
struct arg_hdr hdr; /* The mandatory argtable header struct */
int count; /* Number of matching arguments parsed */
<xxx> *data; /* Array for storing the argument values */
... /* Other custom fields go here */
};</PRE><P STYLE="margin-bottom: 0.51cm">
Custom data members follow the <I>arg_hdr</I> struct. Since argtable
supports multiple instances of any given command line argument, it is
usual that your structure provides an array for storing multiple
argument values (<I>arg_xxx.data)</I> and a count of them
(<I>arg_xxx.count)</I>. Add any other fields you need for your custom
parsing routines as required. Any internal data you would prefer to
hide from the end-user can be stored in a user-defined private data
structure that is encapsulated by the <I>arg_hdr</I> structure as you
will see next.</P>
<PRE CLASS="western">struct arg_xxx_priv
{
/* Private custom data goes here */
...
};</PRE><H4>
Defining the argx_xxx constructors</H4>
<P STYLE="margin-bottom: 0.51cm">Each arg_xxx structure should have a
constructor function that is responsible for allocating memory for it
and populating the data within it. By convention, there are
ordinarily three forms of constructor function for each arg_xxx
struct</P>
<PRE CLASS="western">struct arg_xxx* arg_xxx0(const char* shortopts, const char* longopts,
const char *datatype, const char *glossary);
struct arg_xxx* arg_xxx1(const char* shortopts, const char* longopts,
const char *datatype, const char *glossary);
struct arg_xxx* arg_xxxn(const char* shortopts, const char* longopts,
const char *datatype,
int mincount, int maxcount,
const char *glossary);</PRE><P STYLE="margin-bottom: 0cm">
The different forms provide a convenient means for specifying command
line arguments that accept either zero-or-one, exactly-one, or many
instances on the command line. The first two forms are typically
implemented as wrapper functions of the third. You may customise the
actual parameters to fit your purposes, the declarations above are
merely examples of common forms.</P>
<P STYLE="margin-bottom: 0cm"><IMG SRC="argxxx.gif" NAME="Graphic1" ALIGN=LEFT WIDTH=671 HEIGHT=623 BORDER=0><BR CLEAR=LEFT><BR>
</P>
<P STYLE="margin-bottom: 0.51cm">The diagram shows the general layout
of the data structure that should be returned by the <I>arg_xxx</I>
constructor function(s). It comprises of a single contiguous block of
heap allocated memory, with the <I>arg_xxx</I> struct at its head,
followed by the storage space for <I>maxcount</I> argument values as
well as an optional private data structure that may be used to hide
internal data from the end-user. If the allocation failed then the
constructor should return NULL.</P>
<PRE CLASS="western">size_t nbytes;
struct arg_xxx *result;
nbytes = sizeof(struct arg_xxx) + sizeof(struct arg_xxx_priv) + maxcount*sizeof(<xxx>) ;
result = (struct arg_xxx*)malloc(nbytes);</PRE><P STYLE="margin-bottom: 0.51cm">
The entire <I>arg_hdr</I> structure must be populated by the
constructor, including the pointers to the appropriate callback
functions, the enclosing <I>arg_xxx</I> structure (<I>void *parent</I>),
and the private data structure (<I>void *priv</I>).
</P>
<PRE CLASS="western">result->hdr.flag = ARG_HASVALUE; /* argument accepts a value */
result->hdr.shortopts = shortopts; /* short options */
result->hdr.longopts = longopts; /* long options */
result->hdr.datatype = datatype ? datatype : "<xxx>"; /* datatype description */
result->hdr.glossary = glossary; /* glossary description */
result->hdr.mincount = mincount; /* minimum number of arguments */
result->hdr.maxcount = maxcount; /* maximum number of arguments */
result->hdr.parent = result; /* ptr to parent arg_xxx struct */
result->hdr.resetfn = (arg_resetfn*)resetfn; /* ptr to resetfn callback */
result->hdr.scanfn = (arg_scanfn*)scanfn; /* ptr to scanfn callback */
result->hdr.checkfn = (arg_checkfn*)checkfn; /* ptr to checkfn callback */
result->hdr.errorfn = (arg_errorfn*)errorfn; /* ptr to errorfn callback */
result->hdr.priv = result + 1; /* ptr to private data */ </PRE><P STYLE="margin-bottom: 0.51cm">
The custom <I>arg_xxx</I> fields should also be populated,
particularly the pointer to the argument storage array. The values
within the array may or may not be initialised at your discretion.</P>
<PRE CLASS="western"><I>/* locate the data[maxcount] array immediately after the private data structure */</I>
result->data = (<xxx>*)((struct arg_xxx_priv*)(result->hdr.priv) + 1);
/* init the remaining of the arg_xxx struct variables */
result->count = 0;
...</PRE><P STYLE="margin-bottom: 0cm">
Lastly, we return a pointer to the completed data structure</P>
<PRE CLASS="western" STYLE="margin-top: 0.51cm; margin-bottom: 0.51cm">return result;</PRE><P STYLE="margin-bottom: 0cm">
<BR>
</P>
</BODY>
</HTML>
