Next: , Up: (dir)

Arg_parser Manual

This manual is for Arg_parser (version 1.10, 27 June 2014).


Copyright © 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Antonio Diaz Diaz.

This manual is free documentation: you have unlimited permission to copy, distribute and modify it.


Next: , Previous: 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 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.


Next: , Previous: 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.


Next: , Previous: 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 also the file 'main.cc' for an example of use.

The Arg_parser class 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.

The struct option structure 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.
enum Has_arg has_arg
This field 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 )

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 a parsed option). 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 & Arg_parser::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.


Next: , Previous: Initialization, Up: Top

4 Using the Arg_parser class

After a successful call to the constructor, which must be verified by calling Arg_parser::error, the parsed options and arguments can be accessed by means of the following functions:

-- Function: int Arg_parser::arguments () const

This function returns the number of options and non-option arguments parsed. This number is normally different from argc.

-- Function: int Arg_parser::code ( const int index ) const

This function returns the code of the option at position index. Valid values for index range from 0 to Arg_parser::arguments() - 1. If the returned code is non-zero, Arg_parser::argument(index) is the option's argument (or is empty if the option does not have an argument). If the returned code is zero, Arg_parser::argument(index) is a non-option argument.

-- Function: const std::string & Arg_parser::argument ( const int index ) const

This function returns the argument at position index. It may be the argument of an option or a non-option argument, depending on the value returned by Arg_parser::code(index). Valid values for index range from 0 to Arg_parser::arguments() - 1.


Next: , Previous: 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 also 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. See Initialization, for details about function arguments.

To access the parsed options and arguments you can use the functions 'ap_arguments', 'ap_code' and 'ap_argument'. See Using Arg_parser, for details about function arguments and return values.

When you are finished, you should free all dynamically allocated data structures by calling 'ap_free'.


Next: , Previous: 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 arg-parser-bug@nongnu.org. Include the version number, which you can find by running arg_parser --version.


Previous: Problems, Up: Top

Concept index