This manual is for Arg_parser (version 1.3, 10 July 2009).
Copyright © 2006, 2007, 2008, 2009 Antonio Diaz Diaz.
This manual is free documentation: you have unlimited permission to copy, distribute and modify it.
Arg_parser is an argument parser that follows POSIX and GNU conventions for command line arguments. The C++ version is implemented as a C++ class, while the C version is implemented as a single struct plus associated functions. Both are simpler, easier to use, and safer that `getopt_long'.
For maximum stability, Arg_parser is self-contained. It extracts all the information it needs from its arguments to avoid refering to them later. This avoids index-out-of-bounds errors.
Arg_parser does not modify its arguments, nor uses any global variables. So you may create more than one parser in your program if you need or want to.
The C++ version of Arg_parser can also parse options from configuration files.
To use Arg_parser in your own programs simply copy the files `arg_parser.h' and `arg_parser.cc' (or `carg_parser.h' and `carg_parser.c' for the C version) in your source tree. See also the file `main.cc' (`cmain.c') for an example of use.
POSIX recommends these conventions for command line arguments.
Arg_parser makes it easy to implement them.
-).
-abc is equivalent to
-a -b -c.
-o foo and -ofoo are equivalent.
Arg_parser normally makes it appear as if all the option
arguments were specified before all the non-option arguments for the
purposes of parsing, even if the user of your program intermixed option
and non-option arguments. If you want the arguments in the exact order
the user typed them, call Arg_parser with in_order = true.
-- terminates all options; any following
arguments are treated as non-option arguments, even if they begin with a
hyphen.
-- followed by a name made of alphanumeric characters
and hyphens. Option names are typically one to three words long, with
hyphens to separate words. Users can abbreviate the option names as long
as the abbreviations are unique.
-<short_option><argument> (without whitespace), or
--<long_option>=<argument>.
The Arg_parser class has two constructors; one to parse command line arguments from argv, and the other to parse a single token (plus an optional second token in case an argument is needed for a parsed option) from a configuration file or other source. Be warned that a single token may produce an undefined number of short options.
For the C version, you need to declare a variable of type
Arg_parser and then pass its address to ap_init to
initialize it.
If there is an error parsing the arguments, error returns a
non-empty error message.
This structure describes a single option for the sake of `Arg_parser'. The argument options must be an array of these structures, one for each option. Terminate the array with an element containing a code which is zero.
The
struct optionstructure has these fields:
int code- This field is the code that identifies the option, normally the short-option character. Must be different from 0. A code value outside the unsigned char range means a long-only option.
const char * name- This field is the long option name. It is a zero-terminated string. A null or empty name means a short-only option.
Has_arg has_arg- This field says whether the option takes an argument. It has three legitimate values:
no,yesandmaybe.
Reads the arguments in argv and creates a number of option codes, option arguments and non-option arguments.
Restricted constructor. Parses a single token (plus an optional second token in case an argument is needed for a parsed option). Can be used to parse options from a configuration file one at a time.
Arg_parser class
After a succesful call to the constructor, the function arguments
will return the number of options and non-option arguments parsed. This
number is normally different from argc.
Call code(index), with 0 <= index < arguments, to get the code of every option. If the returned code
is nonzero, argument(index) is the option's argument (or is
empty if the option does not have an argument). If the returned code is
zero, argument(index) is a non-option argument.
There are probably bugs in Arg_parser. There are certainly errors and omissions in this manual. If you report them, they will get fixed. If you don't, no one will ever know about them and they will remain unfixed for all eternity, if not longer.
If you find a bug in Arg_parser, please send electronic mail to
bug-moe@gnu.org. Include the version number, which you can
find by running arg_parser --version.