argpar

argpar, an EfficiOS project, is yet another open-source command-line argument parser for C/C++ programs.

Table of Contents

• Features
• Known limitations
• Build argpar
• Build the C99 API documentation
• Run the tests
• Community

Features

The most important features of argpar are:

• A single MIT-licensed, independent C99 source file and its header that you can copy as is into your own project.

  You may also copy argpar/argpar.hpp which is a C++11 API wrapping the C99 API.

• Declarative description of expected options:

  enum my_opt_id {
      MY_OPT_ID_DATA,
      MY_OPT_ID_SQUEEZE,
      MY_OPT_ID_MEOW,
  };
  
  static const struct argpar_opt_descr descrs[] = {
      { MY_OPT_ID_DATA,    'd',  NULL,      false },
      { MY_OPT_ID_SQUEEZE, '\0', "squeeze", true },
      { MY_OPT_ID_MEOW,    'm',  "meow",    true },
      ARGPAR_OPT_DESCR_SENTINEL,
  };

• Supports short (-k) and long (--kernel) options.

  Multiple short options may be concatenated, and the argument of the last one may be “attached” (-xvfmyfile).

  The argument of a long option may follow a space (--meow mix) or an = sign (--meow=mix).

• Supports repeated options:

  --meow=mix salut -f4 /path/to/file --meow blend -cqc

• Fully documented, const-correct C99 API based on an argument iterator.

  The argpar_iter_next() function produces items in the same order that it parses original arguments, including non-option items. This means, for example, that for:

  --hello --count=23 /path/to/file -ab --type file -- magie

  argpar_iter_next() produces the following items, in this order:

  • Option item: --hello.

  • Option item: --count with argument 23.

  • Non-option item: /path/to/file.

  • Option item: -a.

  • Option item: -b.

  • Option item: --type with argument file.

  • Non-option item: --.

  • Non-option item: magie.

• On parsing error, provides a detailed error object including the index of the argument (in argv) that caused the error as well as the name, if available, of the unknown option.

Known limitations

Compared with other similar open-source command-line argument parsers, argpar has the following known limitations:

• Doesn’t support abbreviated long options.

  For example, if your option descriptor describes --fraction, then argpar_iter_next() won’t parse --frac=23: it will return an unknown option error instead.

• Doesn’t explicitly support “end of option” (--).

  This is valid:

  --hello=world --meow -- mix --hut=23

  argpar_iter_next() provides the -- argument as a non-option item.

• Doesn’t support a non-option argument having the form of an option, for example if you need to pass the exact relative path --calorie.

  In that case, you would need to pass ./--calorie. There’s no generic way to escape - as of this version. This is in part because argpar doesn’t support “end of option” (--).

  As a workaround, because argpar offers an iterator API, you may:

  1. Stop using argpar_iter_next() from the first -- non-option item ITEM.

  2. Use argpar_item_non_opt_orig_index() with ITEM to get the original index I of the first -- within argv (as passed to argpar_iter_create()).

  3. Read the remaining non-option arguments from argv, starting at I + 1.

• Doesn’t handle the -h/--help option in a special way (doesn’t show some automatic usage message).

• Doesn’t provide direct access to the value of an option.

  This is because argpar offers an iterator API to support positional and repeated options.

Build argpar

To use argpar in your own project, simply copy the argpar/argpar.c and argpar/argpar.h files and you’re ready to go.

You may also copy argpar/argpar.hpp which is a C++11 API wrapping the C99 API.

To build this project, make sure you have GLib 2 (required by the tests), and then:

1. If you build from a Git clone, run:

   $ ./bootstrap

   This generates the configure script and other important files.

2. Configure the project:

   $ ./configure

   See ./configure --help for more options.

3. Build the project:

   $ make

Build the C99 API documentation

To build the C99 API documentation, make sure you have Doxygen, and then:

• From the root of the project, run:

  $ doxygen

Open api-doc/html/index.html with Netscape Navigator.

Run the tests

To run the argpar tests:

1. Build the project.

2. Run the tests:

   $ make check

Community

argpar uses Gerrit for code review.

To report a bug, create a GitHub issue.