slang::CommandLine class
#include <slang/util/CommandLine.h>

Command line argument parser.

Arguments are parsed in the general style of GNU longopts. Each option name can be any combination of short and long form, where short forms start with a single dash and are a single letter, and long forms start with a double dash and can be multiple letters.

All options (besides boolean flags) require a value to be passed as well. Values can be passed as whitespace separated strings. For example: -f 1 --long 2

For long form names, values can be passed with an '=' sign followed by the value instead: --long=2

For short form names, values can be passed directly adjacent in the string, no whitespace required: -f1

Groups of short form names can be combined together. The final short form name in such a group can have an adjacent value: -abcf1

Options can alternatively begin with a '+', in which case they are always long form, and expect their value(s) to come separated by additional '+' signs. For example: +opt+val1+val2

A standalone double dash, "--", indicates that all further elements of the command line are to be considered positional and not parsed as options. A single dash, "-", is always considered to be a positional argument.

If a provided option on the command line does not match any registered name, an error is reported. If the name is "close" to one of the registered names, the error will provide a helpful "did you mean" hint.

Public types

struct ParseOptions
Contains various options to control parsing of command flags.

is a comma separated list of long form and short form names

Register an option with name that will be parsed as a string and forwarded to the given cb callback function for handling. If the option is not provided on a command line, the callback will never be invoked.

(including the dashes) that are accepted for this option. desc is a human-friendly description for printing help text. valueName is an example name for the value when printing help text. isFileName indicates whether the parsed string is a filename that might be relative to the current directory.

std::map<std::string, std::string> cmdRename
void setPositional(std::vector<std::string>& values, std::string_view valueName, bool isFileName = false)
void setPositional(OptionCallback cb, std::string_view valueName, bool isFileName = false)
auto addIgnoreCommand(std::string_view value) -> std::string
auto addRenameCommand(std::string_view value) -> std::string
auto parse(int argc, const char*const argv[]) -> bool
auto parse(std::string_view argList, ParseOptions options = {}) -> bool
auto parse(std::span<const std::string_view> args, ParseOptions options = {}) -> bool
auto getProgramName() const -> std::string_view
Gets the name of the program, parsed out of the first item on the command line.
void setProgramName(std::string_view name)
Manually set the program name for later use in help text.
auto getErrors() const -> std::span<const std::string>
Gets the set of errors that were encountered when parsing command line options.
auto getHelpText(std::string_view overview) const -> std::string

Function documentation

void slang::CommandLine::setPositional(std::vector<std::string>& values, std::string_view valueName, bool isFileName = false)

Set a variable that will receive any positional arguments provided on the command line. They will be returned as a list of strings. valueName is for including in the help text. isFileName indicates whether the parsed string is a filename that might be relative to the current directory.

void slang::CommandLine::setPositional(OptionCallback cb, std::string_view valueName, bool isFileName = false)

Set a callback that will receive any positional arguments provided on the command line. valueName is for including in the help text. isFileName indicates whether the parsed string is a filename that might be relative to the current directory.

std::string slang::CommandLine::addIgnoreCommand(std::string_view value)

Parameters
value a string containing a single comma-separated "name,value" pair, where the name is the argument to ignore (including any leading '+' and '-' characters) and the value is an integer indicating the (possibly zero) number of arguments to ignore following it in the argument list.
Returns a string containing an error message if the value is malformed.

Adds a command that will be ignored if encountered during argument parsing.

std::string slang::CommandLine::addRenameCommand(std::string_view value)

Parameters
value a string containing a single comma-separated "from,to" pair, where the "from" is the command that should be renamed whenever encountered in the argument list (including any leading '+' and '-' characters), and "to" is the new name it should have.
Returns a string containing an error message if the value is malformed.

Adds a command that will be renamed to one of the existing commands already registered.

bool slang::CommandLine::parse(int argc, const char*const argv[])

Returns true on success, false if an errors occurs.

Parse the provided command line (C-style).

bool slang::CommandLine::parse(std::string_view argList, ParseOptions options = {})

Returns true on success, false if an errors occurs.

Parse the provided command line (space delimited, with handling of quoted arguments).

bool slang::CommandLine::parse(std::span<const std::string_view> args, ParseOptions options = {})

Returns true on success, false if an errors occurs.

Parse the provided command line (as a pre-separated list of strings).

std::string slang::CommandLine::getHelpText(std::string_view overview) const

Gets a string representing program help text, based on registered flags. overview text is a human friendly description of what the program does.

Variable documentation

std::map<std::string, std::string> slang::CommandLine::cmdRename

A map of commands to be renamed, pointing to new name key is the vendor command name (including any leading +/- symbols) value is the command name to be used instead