This is arg_parser.info, produced by makeinfo version 4.13+ from arg_parser.texi. INFO-DIR-SECTION Libraries START-INFO-DIR-ENTRY * Arg_parser: (arg_parser). A POSIX/GNU command line argument parser END-INFO-DIR-ENTRY  File: arg_parser.info, Node: Top, Next: Introduction, Up: (dir) Arg_parser Manual ***************** This manual is for Arg_parser (version 1.17, 5 February 2022). * 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 Copyright (C) 2006-2022 Antonio Diaz Diaz. This manual is free documentation: you have unlimited permission to copy, distribute, and modify it.  File: arg_parser.info, Node: Introduction, Next: Argument syntax, Prev: Top, Up: Top 1 Introduction ************** 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 '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 GNU moe, because moe's argument parsing is rather complex. Then I used it in my other projects, including GNU ddrescue, GNU ed, lzip, GNU ocrad, tarlz, and zutils, with excellent results.  File: arg_parser.info, Node: Argument syntax, Next: Initialization, Prev: Introduction, Up: Top 2 Syntax of command line arguments ********************************** POSIX recommends these conventions for command line arguments. Arg_parser makes it easy to implement them. * A command line argument is an option if it begins with a hyphen delimiter ('-'). * Multiple options may follow a hyphen delimiter in a single token if the options don't take arguments. Thus, '-abc' is equivalent to '-a -b -c'. * Option names are single alphanumeric characters. * Certain options require an argument. * An option and its argument may or may not appear as separate tokens. (In other words, the whitespace separating them is optional). Thus, '-o foo' and '-ofoo' are equivalent. * 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 'Arg_parser' with IN_ORDER = true. * The argument '--' terminates all options; any following arguments are treated as non-option arguments, even if they begin with a hyphen. * 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. * Options may be supplied in any order, or appear multiple times. The interpretation is left up to the particular application program. * GNU adds "long options" to these conventions. Long options consist of '--' 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. * 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 '='. Thus, '--foo bar' and '--foo=bar' are equivalent. * The syntax for optional option arguments is '-' (without whitespace), or '--='.  File: arg_parser.info, Node: Initialization, Next: Using Arg_parser, Prev: Argument syntax, Up: Top 3 Parsing arguments and reporting errors **************************************** To use Arg_parser in your own programs first copy the files 'arg_parser.h' and 'arg_parser.cc' in your source tree. See the file 'main.cc' for an example of use. The class 'Arg_parser' has two constructors; one to parse command line arguments from ARGV, and the other to parse a single token from a configuration file or other source. -- Data Type: struct Option 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. 'struct Option' has the following members: '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. '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. 'enum Has_arg has_arg' This member says whether the option takes an argument. It has three valid values: 'no', 'yes', and 'maybe'. -- Function: Arg_parser ( const int ARGC, const char * const ARGV[], const Option OPTIONS[], const bool IN_ORDER = false ) Constructor. Reads the arguments in ARGV and parses all options, option arguments, and non-option arguments contained in them. In case of error, 'error().size()' will be non-zero. -- Function: Arg_parser ( const char * const OPT, const char * const ARG, const Option 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, 'error().size()' will be non-zero. -- Function: 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, 'error' returns a non-empty error message explaining the cause.  File: arg_parser.info, Node: Using Arg_parser, Next: C version, Prev: Initialization, Up: Top 4 Using the class 'Arg_parser' ****************************** After a successful call to the constructor, which must be verified by calling 'error', the options and arguments parsed can be accessed by means of the following functions: -- Function: int arguments () const This function returns the number of options and non-option arguments parsed. This number is usually different from argc. -- Function: int code ( const int I ) const This function returns the code of the option at position I. Valid values for I range from 0 to 'arguments() - 1'. If the code returned is non-zero, 'argument(I)' is the option's argument (or is empty if the option does not have an argument). If the code returned is zero, 'argument(I)' is a non-option argument. -- Function: const std::string & parsed_name ( const int I ) const This function returns the full name of the option parsed (short or long) at position I. It may be useful to produce more accurate diagnostic messages. For non-option arguments it returns the empty string. -- Function: const std::string & argument ( const int I ) const This function returns the argument at position I. It may be the argument of an option or a non-option argument, depending on the value returned by 'code(I)'. Valid values for I range from 0 to 'arguments() - 1'.  File: arg_parser.info, Node: C version, Next: Problems, Prev: Using Arg_parser, Up: Top 5 Using the C version of Arg_parser *********************************** To use the C version of Arg_parser in your own programs first copy the files 'carg_parser.h' and 'carg_parser.c' in your source tree. See the file 'cmain.c' for an example of use. Then you need to declare a variable of type 'struct Arg_parser', pass its address to 'ap_init' to initialize it, and verify that 'ap_error' returns 0. 'struct ap_Option' is identical to 'struct Option', except that 'Has_arg' becomes 'ap_Has_arg', and the names of its three values are also prefixed with 'ap_'. *Note struct Option::, for details about the members. -- Function: char ap_init ( struct Arg_parser * const AP, const int ARGC, const char * const ARGV[], const struct ap_Option OPTIONS[], const char IN_ORDER ) Reads the arguments in 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, 'ap_error' will return a non-null pointer. -- Function: void ap_free ( struct Arg_parser * const AP ) Frees all dynamically allocated data structures. -- Function: const char * ap_error ( const struct Arg_parser * const AP ) Use this funtion to verify that the arguments have been correctly parsed by 'ap_init'. If there was an error parsing the arguments, 'ap_error' returns a pointer to an error message explaining the cause, else it returns a null pointer. After a successful call to 'ap_init', which must be verified by calling 'ap_error', the options and arguments parsed can be accessed by means of the following functions: -- Function: int ap_arguments ( const struct Arg_parser * const AP ) This function returns the number of options and non-option arguments parsed. This number is usually different from argc. -- Function: int ap_code ( const struct Arg_parser * const AP, const int I ) This function returns the code of the option at position I. Valid values for I range from 0 to 'ap_arguments() - 1'. If the code returned is non-zero, 'ap_argument(I)' is the option's argument (or is empty if the option does not have an argument). If the code returned is zero, 'ap_argument(I)' is a non-option argument. -- Function: const char * ap_parsed_name ( const struct Arg_parser * const AP, const int I ) This function returns the full name of the option parsed (short or long) at position I. It may be useful to produce more accurate diagnostic messages. For non-option arguments it returns the empty string. -- Function: const char * ap_argument ( const struct Arg_parser * const AP, const int I ) This function returns the argument at position I. It may be the argument of an option or a non-option argument, depending on the value returned by 'ap_code(I)'. Valid values for I range from 0 to 'ap_arguments() - 1'. When you are finished, you should free all dynamically allocated data structures by calling 'ap_free'.  File: arg_parser.info, Node: Problems, Next: Concept index, Prev: C version, Up: Top 6 Reporting bugs **************** 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 . Include the version number, which you can find by running 'arg_parser --version'.  File: arg_parser.info, Node: Concept index, Prev: Problems, Up: Top Concept index ************* [index] * Menu: * argument syntax: Argument syntax. (line 6) * bugs: Problems. (line 6) * C version: C version. (line 6) * getting help: Problems. (line 6) * initialization: Initialization. (line 6) * introduction: Introduction. (line 6) * using Arg_parser: Using Arg_parser. (line 6)  Tag Table: Node: Top224 Node: Introduction951 Node: Argument syntax2085 Node: Initialization4504 Ref: struct Option5034 Node: Using Arg_parser6979 Node: C version8461 Node: Problems11640 Node: Concept index12193  End Tag Table  Local Variables: coding: iso-8859-15 End: