Introduction

This project is an advanced getopt() class to use with your C++ projects. It handles most everything that GNU-like tools offer as far as command line options go.

The main idea is for you to have as little to do as possible parsing your command line arguments and configuration files. The library expects a table of available options with a short and long version of the options, and whether they accept arguments (i.e. -f <filename>).

In your C++ program you can then just check whether a parameter is defined or not with the is_defined() function and get the value as a string, an integer, etc. as required by your tool. Data verification is done automatically using validators. Since you can create your own validators, pretty much any data type is supported.

Features

The library version 2.x has the following features:

• Parse command line arguments
• Parse an environment variable as a list of arguments
• Parse configuration files
  • Usual Unix like file (var=value)
  • INI file support ([section-name])
    • TOML first level array syntax
  • Supports multiple line definitions with line continuations (backslash or ampersand at the end o the line, & or spaces at the beginning of the following line)
  • Support sections like in an INI file or with named blocks similar to C++ namespaces
  • You can update parameters found in a configuration file and then save the new data back to the file
  • The Save feature also automatically creates a backup
  • Support several types of comments (#, ;, //)
• Automatically output the --help scren
• Support --version, --copyright, --license and some other internally defined command line options
• Automatically validate the parameters following the arguments with validators:
  • Integer
  • Regex
  • Email (TODO--using libtld)
  • Network Address (TODO--using libaddr)
  • Your own—you can extend the validator base class with your own validation function
• Many compile time verifications
• Make options visible/hidden using the SHOW flags, specifically, whether to show an option when an error occurred or because you used a specific help option
• Group options together, up to 7 different groups (plus the default group)
• Errors are sent to a logger, by default it goes to std::cerr, but you can setup a callback and have all the errors go to a log file instead

In the future we may add support for JSON, XML, and some other formats where configuration data could be saved. Such support may be limited but it would still be useful if you prefer to use such rather than the default Unix like syntax for your configuration files.

Download

The source is available on github in our project git.

On Ubuntu, you may want to install it from our Snap! C++ Launchpad PPA. In that case, add the repository this way:

sudo add-apt-repository ppa:snapcpp/ppa
sudo apt-get update

Then install one of the library packages with the install command:

sudo apt-get install libadvgetopt
sudo apt-get install libadvgetopt-dev
sudo apt-get install libadvgetopt-doc

List of currently available Snap! C++ packages.

Support

You got a problem with the library? An idea to improve it? Please post a ticket in the Support area of Github.

Requirements

Version 2.x requires the following to compile and use the library:

• C++14 or better (we will probably make it C++17 once we are on Ubuntu 18 or Ubuntu 20)
• cmake (compile only)
• snapcmakemodules (compile only)
• boost (compile only)
• snapcatch2 (compile only, for the unit tests)
• snapdev (compile only)
• libutf8
• libexcept

We use cmake to build everything. If you have Ubuntu, using the PPA (see Download above) will probably be much easier for you. We include a development package so you can directly compile and link against this library.

Documentation

The libadvgetopt-doc package includes all the documentation on how to use the library. You can also find a copy of the advgetopt reference on this website.

The different snapwebsites tools (under snapwebsites/<project-name>/src) will give you extensive examples on how the library gets used.

Coverage Tests

The library comes with a unit test which attempts to keep the coverage as close as possible to 100%. The test results can be found on lcov.snapwebsites.org/advgetopt.

Origin

This library was originally developed for wpkg.