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 & save 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 (#, ;, //)
  • Search for configuration files under:
    • /usr/share/<project>.conf
    • /etc/<project>.conf
    • /etc/<project>.d/??-<project>.conf
    • ~/.config/<project>.conf
• Automatically output the --help screen with proper formatting for current console width
• Support many internally defined command line options:
  • --build-date -- print out the date when that binary was built
  • --<group>-help -- for each group you define, list those specific options
  • --config-dir -- if allowed, you can use this command line option to change the directory where the configuration files will be searched
  • --configuration-filenames -- list the names of the configuration files that the library attempts to read; all these files are optional
  • --copyright | -C -- print out the copyright notice (the -C is defined only if not in conflict with one of your command line options)
  • --environment-variable-name -- print the name of the variable read by the advgetopt library to parse additional parameters from it
  • --help | -h -- print out the help screen automatically formatted (the -h is defined only if not in conflict with one of your command line options)
  • --license | -L -- print out your software license (the -L is defined only if not in conflict with one of your command line options)
  • --path-to-option-definitions -- print the path to a directory where you can define default options
  • --version | -V -- print out the software version
• 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.

Logger Support

The Snap! Logger project is directly integrated with the advgetopt library.

Especially, the logger will automatically (you have to make one call) add its own command line options to the list of commands and automatically handle those options without you having to do so in each one of your program.

This is also a good example on how to do such a thing in case you are creating a library and wanted to offer the end user to enter command line options specific to your library.

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.