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 the 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 environment variables
  • Either one variable with a list of arguments as you would write on your command line (i.e. MYAPP="--debug-level INFO")
  • Or one variable per argument (in which case the argument name is not included in the variable value (i.e. MYAPP_DEBUG_LEVEL="INFO") -- this is very similar to what systems such as Kubernetes/Docker use
• 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 of 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 (for shell scripts, you can use the "edit-config" tool)
  • 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>/<project>.conf
• Automatically output the usage screen (for the --help command
  • Handles formatting for current console width
  • Use less when the output is more than one page in height
• 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
  • --compiler-version -- the version of the compiler used to compile the advgetopt which is likely the same as your tool (if you are on the same system and use the stock version of the compiler)
  • --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)
  • --long-help -- prints out all the commands with all the 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
  • --print-option <name> -- print the value of the named option once all the parsing of the command line, environment variables, configuration files
  • --show-option-sources -- parse all the options and then print out the source of each since the order matters and you may have been trying to update the value and another configuration file or a variable overrides that value; with this option you can debug your configuration setup and find the culprit quickly
  • --system-help -- print out system specific help options
  • --version | -V -- print out the software version (the -V is defined only if not in conflict with one of your command line options)
• Automatically validate the parameters following the arguments with validators:
  • Double
  • Duration (i.e. 3m, 1h, 2d)
  • Email (uses libtld)
  • Integer
  • Keywords (i.e. red,green,blue for a --channel option)
  • Length (i.e. make sure the parameter value is long enough and not too long)
  • List -- supports a list of validators so either type of value is accepted
  • Network Address (defined in libaddr since that other project depends on this one)
  • Regex
  • Size (i.e. 2mb, 2Mb, 3Kb)
  • Your own—you can extend the validator base class with your own validation functions
• Many compile time verifications of your options
• The value of a parameter can include references to variables (${blah}), which can be particularly useful in configuration files where you can defined a [variables] section (name of which can be set to anything you like)
• 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 automatically (you have to make one call) adds its own command line options to the list of commands and automatically handles those options without you having to do so in each one of your programs.

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 (several already do so in our Snap! C++ environment).

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++23 or better
• 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.

Origin

This library was originally developed for wpkg.

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/.