329 lines
13 KiB
Text
329 lines
13 KiB
Text
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename arg_parser.info
|
|
@documentencoding ISO-8859-15
|
|
@settitle Arg_parser Manual
|
|
@finalout
|
|
@c %**end of header
|
|
|
|
@set UPDATED 5 February 2022
|
|
@set VERSION 1.17
|
|
|
|
@dircategory Libraries
|
|
@direntry
|
|
* Arg_parser: (arg_parser). A POSIX/GNU command line argument parser
|
|
@end direntry
|
|
|
|
|
|
@ifnothtml
|
|
@titlepage
|
|
@title Arg_parser
|
|
@subtitle A POSIX/GNU command line argument parser
|
|
@subtitle for Arg_parser version @value{VERSION}, @value{UPDATED}
|
|
@author by Antonio Diaz Diaz
|
|
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
@end titlepage
|
|
|
|
@contents
|
|
@end ifnothtml
|
|
|
|
@ifnottex
|
|
@node Top
|
|
@top
|
|
|
|
This manual is for Arg_parser (version @value{VERSION}, @value{UPDATED}).
|
|
|
|
@menu
|
|
* Introduction:: Purpose and features of Arg_parser
|
|
* Argument syntax:: By convention, options start with a hyphen
|
|
* Initialization:: Parsing arguments and reporting errors
|
|
* Using Arg_parser:: Reading the options and arguments parsed
|
|
* C version:: Using the C version of Arg_parser
|
|
* Problems:: Reporting bugs
|
|
* Concept index:: Index of concepts
|
|
@end menu
|
|
|
|
@sp 1
|
|
Copyright @copyright{} 2006-2022 Antonio Diaz Diaz.
|
|
|
|
This manual is free documentation: you have unlimited permission to copy,
|
|
distribute, and modify it.
|
|
@end ifnottex
|
|
|
|
|
|
@node Introduction
|
|
@chapter Introduction
|
|
@cindex introduction
|
|
|
|
@uref{http://www.nongnu.org/arg-parser/arg_parser.html,,Arg_parser}
|
|
is an argument parser that follows POSIX and GNU conventions for
|
|
command line arguments. There exist C++ and C versions of Arg_parser. 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 than @samp{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.
|
|
|
|
Arg_parser was developed as the argument parser for
|
|
@uref{http://www.gnu.org/software/moe/moe.html,,GNU moe}, because moe's
|
|
argument parsing is rather complex. Then I used it in my other projects,
|
|
including
|
|
@uref{http://www.gnu.org/software/ddrescue/ddrescue.html,,GNU ddrescue},
|
|
@uref{http://www.gnu.org/software/ed/ed.html,,GNU ed},
|
|
@uref{http://www.nongnu.org/lzip/lzip.html,,lzip},
|
|
@uref{http://www.gnu.org/software/ocrad/ocrad.html,,GNU ocrad},
|
|
@uref{http://www.nongnu.org/lzip/tarlz.html,,tarlz}, and
|
|
@uref{http://www.nongnu.org/zutils/zutils.html,,zutils}, with
|
|
excellent results.
|
|
|
|
|
|
@node Argument syntax
|
|
@chapter Syntax of command line arguments
|
|
@cindex argument syntax
|
|
|
|
POSIX recommends these conventions for command line arguments.
|
|
Arg_parser makes it easy to implement them.
|
|
|
|
@itemize @bullet
|
|
@item A command line argument is an option if it begins with a hyphen
|
|
delimiter (@samp{-}).
|
|
|
|
@item Multiple options may follow a hyphen delimiter in a single token
|
|
if the options don't take arguments. Thus, @samp{-abc} is equivalent to
|
|
@w{@samp{-a -b -c}}.
|
|
|
|
@item Option names are single alphanumeric characters.
|
|
|
|
@item Certain options require an argument.
|
|
|
|
@item An option and its argument may or may not appear as separate
|
|
tokens. (In other words, the whitespace separating them is optional).
|
|
Thus, @w{@samp{-o foo}} and @samp{-ofoo} are equivalent.
|
|
|
|
@item Options typically precede other non-option arguments.
|
|
|
|
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
|
|
@samp{Arg_parser} with @w{@var{in_order} = true}.
|
|
|
|
@item The argument @samp{--} terminates all options; any following arguments
|
|
are treated as non-option arguments, even if they begin with a hyphen.
|
|
|
|
@item A token consisting of a single hyphen character is interpreted as
|
|
an ordinary non-option argument. By convention, it is used to specify
|
|
input from or output to the standard input and output streams.
|
|
|
|
@item Options may be supplied in any order, or appear multiple times.
|
|
The interpretation is left up to the particular application program.
|
|
|
|
@item GNU adds @dfn{long options} to these conventions. Long options
|
|
consist of @samp{--} 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.
|
|
|
|
@item A long option and its argument may or may not appear as separate
|
|
tokens. In the latter case they must be separated by an equal sign @samp{=}.
|
|
Thus, @w{@samp{--foo bar}} and @samp{--foo=bar} are equivalent.
|
|
|
|
@item The syntax for optional option arguments is
|
|
@samp{-<short_option><argument>} (without whitespace), or
|
|
@samp{--<long_option>=<argument>}.
|
|
@end itemize
|
|
|
|
|
|
@node Initialization
|
|
@chapter Parsing arguments and reporting errors
|
|
@cindex initialization
|
|
|
|
To use Arg_parser in your own programs first copy the files
|
|
@samp{arg_parser.h} and @samp{arg_parser.cc} in your source tree. See the
|
|
file @samp{main.cc} for an example of use.
|
|
|
|
The class @samp{Arg_parser} has two constructors; one to parse command line
|
|
arguments from @var{argv}, and the other to parse a single token from a
|
|
configuration file or other source.
|
|
|
|
@anchor{struct Option}
|
|
@deffn {Data Type} struct Option
|
|
This structure describes a single option for the sake of
|
|
@samp{Arg_parser}. The argument @var{options} must be an array of these
|
|
structures, one for each option. Terminate the array with an element
|
|
containing a code which is zero.
|
|
|
|
@samp{struct Option} has the following members:
|
|
|
|
@table @code
|
|
@item int code
|
|
This member 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.
|
|
|
|
@item const char * long_name
|
|
This member is the long option name. It is a zero-terminated string. A
|
|
null or empty long_name means a short-only option.
|
|
|
|
@item enum Has_arg has_arg
|
|
This member says whether the option takes an argument. It has three
|
|
valid values: @samp{no}, @samp{yes}, and @samp{maybe}.
|
|
@end table
|
|
@end deffn
|
|
|
|
@defun Arg_parser ( const int @var{argc}, const char * const @var{argv}[], const Option @var{options}[], const bool @var{in_order} = false )
|
|
Constructor. Reads the arguments in @var{argv} and parses all options,
|
|
option arguments, and non-option arguments contained in them. In case of
|
|
error, @samp{error().size()} will be non-zero.
|
|
@end defun
|
|
|
|
@defun Arg_parser ( const char * const @var{opt}, const char * const @var{arg}, const Option @var{options}[] )
|
|
Restricted constructor. Parses a single token (plus an optional second
|
|
token in case an argument is needed for an option parsed). Can be used to
|
|
parse options from a configuration file one at a time. Be warned that a
|
|
single token may produce an undefined number of short options. In case
|
|
of error, @samp{error().size()} will be non-zero.
|
|
@end defun
|
|
|
|
@deftypefun {const std::string &} error () const
|
|
Use this funtion to verify that the arguments have been correctly parsed
|
|
by the constructor. If there was an error parsing the arguments,
|
|
@samp{error} returns a non-empty error message explaining the cause.
|
|
@end deftypefun
|
|
|
|
|
|
@node Using Arg_parser
|
|
@chapter Using the class @samp{Arg_parser}
|
|
@cindex using Arg_parser
|
|
|
|
After a successful call to the constructor, which must be verified by
|
|
calling @samp{error}, the options and arguments parsed can be accessed
|
|
by means of the following functions:
|
|
|
|
@deftypefun int arguments () const
|
|
This function returns the number of options and non-option arguments parsed.
|
|
This number is usually different from argc.
|
|
@end deftypefun
|
|
|
|
@deftypefun int code ( const int @var{i} ) const
|
|
This function returns the code of the option at position @var{i}. Valid
|
|
values for @var{i} range from 0 to @w{@samp{arguments() - 1}}. If the
|
|
code returned is non-zero, @samp{argument(@var{i})} is the option's
|
|
argument (or is empty if the option does not have an argument). If the
|
|
code returned is zero, @samp{argument(@var{i})} is a non-option argument.
|
|
@end deftypefun
|
|
|
|
@deftypefun {const std::string &} parsed_name ( const int @var{i} ) const
|
|
This function returns the full name of the option parsed (short or long) at
|
|
position @var{i}. It may be useful to produce more accurate diagnostic
|
|
messages. For non-option arguments it returns the empty string.
|
|
@end deftypefun
|
|
|
|
@deftypefun {const std::string &} argument ( const int @var{i} ) const
|
|
This function returns the argument at position @var{i}. It may be the
|
|
argument of an option or a non-option argument, depending on the value
|
|
returned by @samp{code(@var{i})}. Valid values for @var{i} range from 0
|
|
to @w{@samp{arguments() - 1}}.
|
|
@end deftypefun
|
|
|
|
|
|
@node C version
|
|
@chapter Using the C version of Arg_parser
|
|
@cindex C version
|
|
|
|
To use the C version of Arg_parser in your own programs first copy the files
|
|
@samp{carg_parser.h} and @samp{carg_parser.c} in your source tree. See the
|
|
file @samp{cmain.c} for an example of use.
|
|
|
|
Then you need to declare a variable of type @samp{struct Arg_parser},
|
|
pass its address to @samp{ap_init} to initialize it, and verify that
|
|
@samp{ap_error} returns 0.
|
|
|
|
@samp{struct ap_Option} is identical to @samp{struct Option}, except
|
|
that @samp{Has_arg} becomes @samp{ap_Has_arg}, and the names of its
|
|
three values are also prefixed with @samp{ap_}. @xref{struct Option},
|
|
for details about the members.
|
|
|
|
@deftypefun char ap_init ( struct Arg_parser * const @var{ap}, const int @var{argc}, const char * const @var{argv}[], const struct ap_Option @var{options}[], const char @var{in_order} )
|
|
Reads the arguments in @var{argv} and parses all options, option
|
|
arguments, and non-option arguments contained in them. Returns 0 if there
|
|
is not enough memory, else 1. In case of error, @samp{ap_error} will
|
|
return a non-null pointer.
|
|
@end deftypefun
|
|
|
|
@deftypefun void ap_free ( struct Arg_parser * const @var{ap} )
|
|
Frees all dynamically allocated data structures.
|
|
@end deftypefun
|
|
|
|
@deftypefun {const char *} ap_error ( const struct Arg_parser * const @var{ap} )
|
|
Use this funtion to verify that the arguments have been correctly parsed
|
|
by @samp{ap_init}. If there was an error parsing the arguments,
|
|
@samp{ap_error} returns a pointer to an error message explaining the
|
|
cause, else it returns a null pointer.
|
|
@end deftypefun
|
|
|
|
After a successful call to @samp{ap_init}, which must be verified by
|
|
calling @samp{ap_error}, the options and arguments parsed can be accessed
|
|
by means of the following functions:
|
|
|
|
@deftypefun int ap_arguments ( const struct Arg_parser * const @var{ap} )
|
|
This function returns the number of options and non-option arguments parsed.
|
|
This number is usually different from argc.
|
|
@end deftypefun
|
|
|
|
@deftypefun int ap_code ( const struct Arg_parser * const @var{ap}, const int @var{i} )
|
|
This function returns the code of the option at position @var{i}. Valid
|
|
values for @var{i} range from 0 to @w{@samp{ap_arguments() - 1}}. If the
|
|
code returned is non-zero, @samp{ap_argument(@var{i})} is the option's
|
|
argument (or is empty if the option does not have an argument). If the
|
|
code returned is zero, @samp{ap_argument(@var{i})} is a non-option argument.
|
|
@end deftypefun
|
|
|
|
@deftypefun {const char *} ap_parsed_name ( const struct Arg_parser * const @var{ap}, const int @var{i} )
|
|
This function returns the full name of the option parsed (short or long) at
|
|
position @var{i}. It may be useful to produce more accurate diagnostic
|
|
messages. For non-option arguments it returns the empty string.
|
|
@end deftypefun
|
|
|
|
@deftypefun {const char *} ap_argument ( const struct Arg_parser * const @var{ap}, const int @var{i} )
|
|
This function returns the argument at position @var{i}. It may be the
|
|
argument of an option or a non-option argument, depending on the value
|
|
returned by @samp{ap_code(@var{i})}. Valid values for @var{i} range from 0
|
|
to @w{@samp{ap_arguments() - 1}}.
|
|
@end deftypefun
|
|
|
|
When you are finished, you should free all dynamically allocated data
|
|
structures by calling @samp{ap_free}.
|
|
|
|
|
|
@node Problems
|
|
@chapter Reporting bugs
|
|
@cindex bugs
|
|
@cindex getting help
|
|
|
|
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
|
|
@email{arg-parser-bug@@nongnu.org}. Include the version number, which
|
|
you can find by running @w{@samp{arg_parser --version}}.
|
|
|
|
|
|
@node Concept index
|
|
@unnumbered Concept index
|
|
|
|
@printindex cp
|
|
|
|
@bye
|