Cascadeable command line argument parser. More...

Data Structures
struct	caps_arg_parameter

struct	caps_arg_parser

struct	caps_arg_parser_list

Enumerations
enum	caps_arg_parameter_flag { CAPS_PARAM_UNKNOWN = 0 , CAPS_PARAM_OPTIONAL = 1 , CAPS_VALUE_OPTIONAL = 2 }

Functions
int	caps_arg_parser_process (const struct caps_arg_parser_list plist, int argc, char argv[argc])

int	caps_arg_parser_help (const struct caps_arg_parser_list *plist)

Detailed Description

This command line argument parser is intended for library based command line processing.

With this library you can define your application's command line argument parser and cascade it with the command line argument parsers of external sources (libraries for example).

Features

NLS domain on a per parser base
the full help text and - even in the parser callbacks - parser based national language translations are possible
a parser based dedicated local private data pointer to avoid global variables
no surprising termination in the library for --version, --help and --usage. It returns with a -EAGAIN error code instead
library's output can be forwarded into dedicated streams (generic messages versus error messages)

Something like the output of --help is generated at one single location based on the different parser definitions.

Background

Parameters to understood are defined in caps_arg_parameter as a simple array. The difference between a mandatory parameter and an optional one is the flag CAPS_PARAM_OPTIONAL. Whenever a parameter is found in the command line arguments, its corresponding callback is called. It receives its own parser definition and the (possible) value of the command line argument. The parser definition contains an object, which can point to private data to be accessed when a parameter of this parser definition was found. The struct also contains the help texts for the parameter and its value. They are used, when the --help output is created.

Note: The object member is important to avoid the use of global variables to store the values of parameters; The domain member is important to be able to output more local language specific messages in the callback function (regarding your own layer in the cascade of parsers).

The parameter array

A command line argument parser in caps_arg_parser defines an object pointer used by the parameter callbacks and a header and footer help text, used as the heading text of the parameters and the trailing text. It defines the NLS domain for all help texts of this parser as well. And it refers the array of parameters.

A single parser with its parameter array

A command line argument parser list in caps_arg_parser_list defines the whole parser. It is intended to be used by the main program, so it defines the program version, bug reporting email address and the name of the program. These texts are used when creating the --help output. And it defines the streams for error output and regular output for special requirements. As the last, it refers an array of command line argument parsers.

A parser list with some parsers and their parameter arrays

Single Parser Programming Example

The following example is a very simple one, with a single command line argument parser and a single command line argument (here --verbose).

#include <stdio.h>
#include <libcapscmdparser.h>
 
static int verbosity = 0;
 
static int cb_verbose(const struct caps_arg_parser *parser, const char *value)
{
   int p = (int*)parser->object;
   *p++;
   return 0;
}
 
static const struct caps_arg_parameter some_param_list = {
  .flags = CAPS_PARAM_OPTIONAL,
  .keyword = "verbose", .key = 'v',
  .cb = cb_verbose,
  .doc = NLS_("Increase verbosity"),
};
 
static const struct caps_arg_parser some_parser = {
  .parameter_cnt = 1, .parameter_list = &some_param_list,
  .header = NLS_("Some header text"), .footer = NLS_("Some footer text"),
  .object = &verbosity, .domain = PACKAGE,
};
 
static struct caps_arg_parser_list prog_parser_list = {
  .cnt = 1, .list = &some_parser,
  .version = "some_prog (CAPS universe) " PACKAGE_VERSION,
  .bugreport = PACKAGE_BUGREPORT,
  .progname = "some_prog",
  .feature = NLS_("Does something famous in the 'CAPS universe'"),
  .domain = PACKAGE,
  .errorout = stderr, .out = stdout,
};

Attention: Don't forget to init the caps_arg_parser_list::errorout and caps_arg_parser_list::out members correctly.

At run-time this results into:

The --help output:

 $ some_prog --help
 Does something famous in the 'CAPS universe'. Usage:
 some_prog [arguments]

 Some header text:
  -v, --verbose    Increase verbosity
  Some footer text

 Usual options:
  -V, --version  Print program's version
      --usage    Print short usage help
  -?, --help     Print this help

 Report bugs to projects@caps-universe.org

the --version parameter is listed, if the caps_arg_parser_list::version member is defined.
the hint where to report bugs to is listed, if the caps_arg_parser_list::bugreport member is defined.

The --usage output:

 $ some_prog --usage
 Usage: some_prog [--verbose] [--version] [--usage] [--help]

The --version output:

 $ some_prog --version
 some_prog (caps universe) 1.0.1

Multiple Parser Programming Example

The previous example can be cascaded with command line argument parsers from external sources. Thus, in the next example it uses three different command line argument parsers:

one in the main program (here some_prog)
one from libcapsdriver
one from libcapsprovider

We can keep the most code from the previous example, just enlarge the some_parser structure into an array of some_parsers, and add the program's command line argument parser as its first one.

Note: Not shown here is the call to caps_drv_init() to fill the two remaining array elements of some_parsers, e.g. some_parsers[1] and some_parsers[2].

[…]
 
static const struct caps_arg_parser some_parsers[3] = {
  [0] = {
    .parameter_cnt = 1, .parameter_list = &some_param_list,
    .header = NLS_("Some header text"), .footer = NLS_("Some footer text"),
    .object = &verbosity, .domain = PACKAGE,
  },
};
 
static struct caps_arg_parser_list prog_parser_list = {
  .cnt = ARRAY_SIZE(some_parsers), .list = some_parsers,
  .version = "some_prog (CAPS universe) " PACKAGE_VERSION,
  .bugreport = PACKAGE_BUGREPORT,
  .progname = "some_prog",
  .feature = NLS_("Does something famous in the 'CAPS universe'"),
  .domain = PACKAGE,
  .errorout = stderr, .out = stdout,
};

Attention: Don't forget to init the caps_arg_parser_list::errorout and caps_arg_parser_list::out members correctly.

With this setup the output will now look different:

The --help output:

 $ some_prog --help
 Does something famous in the 'CAPS universe'. Usage:
 some_prog [arguments] arguments

 Some header text:
  -v, --verbose    Increase verbosity
  Some footer text

 libcapsdriver arguments:
  --test-doc=FILE        Direct file to print
  --test-param=PARAMS    IPP style printing parameters
  --test-printer=FILE    File/device node to print to
  --test-exit            Exit after print
  These arguments are optional and for test and development only

 Provider generic arguments:
  -f FILE, --driver-ini=FILE     Device Description INI file name
  -d DIR, --parameter-dir=DIR    Printers's dynamic parameter directory
  These arguments are mandatory

 Usual options:
  -V, --version  Print program's version
      --usage    Print short usage help
  -?, --help     Print this help

 Report bugs to projects@caps-universe.org

The usage output --usage will differ as well:

 $ testprog --usage
 Usage: testprog [--verbose] [--test-doc=FILE] [--test-param=PARAMS]
        [--test-printer=FILE] [--test-exit] --driver-ini=FILE --parameter-dir=DIR
        [--version] [--usage] [--help]

But the --version output stays the same:

 $ some_prog --version
 some_prog (caps universe) 1.0.1

Note

The caps_arg_parser_process() call returns with a -EINVAL error code

if at least one mandatory argument is required (e.g. not marked as optional), but it was called without any arguments (or with argv[0] only).
if an argument has a mandatory value, but on the command line there was none. And the other way round if an argument hasn't a value, but one was defined.

In addition in these cases, caps_arg_parser_process() will create a corresponding error message.

Command Line Argument Callback

A command line argument callback is defined to:

int cb(const struct caps_arg_parser *parser, const char *value);

The return value must be 0 if the callback function was successful.

Return a negative errno instead, -EINVAL for example, if the callback function wasn't able to process the command line argument successfully. A negative return value will terminate the command line argument processing and the call to caps_arg_parser_process() returns with this negative return value.

Since: libcapsbase-1.1.0

Enumeration Type Documentation

◆ caps_arg_parameter_flag

enum caps_arg_parameter_flag

Parameter and value description flags for caps_arg_parameter::flags

Enumerator
CAPS_PARAM_UNKNOWN
CAPS_PARAM_OPTIONAL	The marked parameter is optional
CAPS_VALUE_OPTIONAL	The marked option/parameter has an optional value, requires caps_arg_parameter::arg to be set

Function Documentation

◆ caps_arg_parser_process()

int caps_arg_parser_process	(	const struct caps_arg_parser_list *	plist,
		int	argc,
		char *	argv[argc]
	)

Process command line arguments with the given parser list

Parameters

[in]	plist	The full parser list
[in]	argc	Argument count, from main()
[in]	argv	Argument array, from main()

Return values

0	On success
value	A negative return value from a command line argument callback function
-EINVAL	bad or missing command line argument(s) or bad or missing argument values
-EAGAIN	Terminate the program by intention (e.g. `--version`, `--help` or `--usage` detected)

A return value of -EAGAIN should terminate the program without an error code, since this is the user's expectation if one of the parameters --version, --help or --usage are given.

A return value of -EINVAL creates a corresponding error message and send it to caps_arg_parser_list::errorout. The program should terminate with an error code in this case.

Note: The command line argument callback functions can return various negative values to signal a failure. Be prepared!

Precondition: caps_arg_parser_list::out and caps_arg_parser_list::errorout from plist must not be NULL

Since: libcapsbase-1.1.0

◆ caps_arg_parser_help()

int caps_arg_parser_help ( const struct caps_arg_parser_list * plist )

Output a long help about possible arguments (same as --help)

Parameters

[in] plist The full parser list