Home   Intro   Tutorial   argtable.h   arg_rec   Globals   Release Notes  

Introduction to Argtable

version 1.3

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.

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

ERROR: myprog grad:13 99 uh oh
                         ^^ unexpected argument

Alternatively, if the program has multiple command line usages then it may choose to call 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.

Styles of command line arguments.

Argtable supports both tagged and 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 integer, double, string, or 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 on, off, yes, no, true, or false and yield an integer value of 0 (negative) or 1 (affirmative) accordingly.

A special argument type called 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 -verbose and -help.

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.

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: Please let me know if you have successfully used argtable on other platforms.

Installing Argtable

The fastest and easiest way to use argtable is simply to copy the argtable.h and 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 autoconf procedure.

  1. cd to the argtable package directory and type ./configure to configure it for your system.
  2. Type make to compile the package.
  3. Optionally, type make check to run the self-tests.
  4. su as root user.
  5. Type make install to install the programs and documentation. By default the package installs into /usr/local/ but a different location may be specified when configuring the package. Type ./configure --help for the full list of configuration options.
  6. logout from root user.
  7. Type make clean to remove the temporary binaries created during compilation.

Getting started.

 The Argtable Tutorial is the best place to get started. Then look at the example code supplied with the distribution.

Similar packages.

Here are some other command line parsing tools that I am aware of. Apologies for any I may have omitted.
Argtable (http://argtable.sourceforge.net)