Command¶

Method	Description
command	Default constructor.
validity_rules	Returns rules to check validity of command line arguments.
execute	Executes the command.
log	Returns logging data.
caption	Returns command short description.
add_flag	Adds a flag to the command.
add_flag	Adds a flag with variable binding to the command.
add_option	Adds an option to the command.
add_option	Adds an anonymous option to the command.
option_value	Returns the value for an anonymous option.
is_set	Checks whether an option was set when calling the command.
store	Returns a store.

class command¶

Command base class.

Public Types

using rule = std::pair<std::function<bool()>, std::string>¶

Rule.

A rule consists of a nullary predicate (validator) and a string (error message). The validator should return true in the correct case.

using rules = std::vector<rule>¶

Rules.

Vector of rules.

Public Functions

command(const environment::ptr &env, const std::string &caption)¶

Default constructor.

The shell environment that is passed as the first argument should be the one from the alice::cli instance. Typically, commands are constructed and added using the macro API, e.g., ALICE_COMMAND or ALICE_ADD_COMMAND.

Parameters

env: Shell environment
caption: Short (one-line) description of the command

const auto &caption() const¶: Returns command short description.

auto add_flag(const std::string &name, const std::string &description)¶

Adds a flag to the command.

This function should be called in the constructor when the program options are set up. See https://github.com/CLIUtils/CLI11#adding-options for more information.

This is a shortcut to opts.add_flag.

Return

Option instance

Parameters

name: Flag names (short flags are prefixed with a single dash, long flags with a double dash), multiple flag names are separated by a comma.
description: Description for the help text

auto add_flag(const std::string &name, bool &value, const std::string &description)¶

Adds a flag with variable binding to the command.

This function should be called in the constructor when the program options are set up. See https://github.com/CLIUtils/CLI11#adding-options for more information.

This is a shortcut to opts.add_flag.

Return

Option instance

Parameters

name: Flag names (short flags are prefixed with a single dash, long flags with a double dash), multiple flag names are separated by a comma.
value: Reference where flag value is stored
description: Description for the help text

template<typename T> auto add_option(const std::string &name, T &value, const std::string &description, bool defaulted = false)¶

Adds an option to the command.

This function should be called in the constructor when the program options are set up. See https://github.com/CLIUtils/CLI11#adding-options for more information.

This is a shortcut to opts.add_option.

Return

Option instance

Parameters

name: Option names (short options are prefixed with a single dash, long options with a double dash, positional options without any dash), multiple option names are separated by a comma.
value: Reference where option value is stored
description: Description for the help text
defaulted: Use initial value to value as default value

template<typename T = std::string> auto add_option(const std::string &name, const std::string &description)¶

Adds an anonymous option to the command.

Unlike the other method, this method adds an option, but takes the value reference from the command itself. This is especially helpful when using the store API, e.g., can_read together with read, where command line options are setup in one function but used in another.

Use a type as template argument to specify the type of the option value and use option_value to return the option value using any of the option names (incl. possible dashes).

Return

Option instance

Parameters

name: Option names (short options are prefixed with a single dash, long options with a double dash, positional options without any dash), multiple option names are separated by a comma.
description: Description for the help text

template<typename T = std::string> T option_value(const std::string &name, const T &default_value = T()) const¶

Returns the value for an anonymous option.

Use any of the option names to access a value. For example, if the option names were "--option,-o", then one can use both "--option" and "-o" as value for the name parameter. It is important that the same type is used to retrieve the option value that was used to add the anonymous option. If the option name does not point to an anonymous option, a default value is returned.

Return

Option value

Parameters

name: One of the option names that was used to create the option
default_value: Dafault value, if name does not point to anonymous option

bool is_set(const std::string &name) const¶

Checks whether an option was set when calling the command.

Any of the option names can be passed, with our without dashes.

Parameters

name: Option name

template<typename T> store_container<T> &store() const¶

Returns a store.

Short cut for env->store<T>().

Protected Functions

virtual rules validity_rules() const¶

Returns rules to check validity of command line arguments.

This returns a vector of rule objects (rules), which are pairs of a nullary predicate (Function with bool return value and no arguments) and an error message as string. For each pair, in order of their position in the vector, the predicate is evaluated. If any of the predicates evalutes to false, the command will not be executed and the error message will be printed.

By default, an empty vector is returned.

The following code checks that a store element is present for std::string and that not both flags -a and -b are set at the same time. For the first check, a predefined rule can be used. Note also that the CLI11 interface allows to put several checks on single options (see https://github.com/CLIUtils/CLI11#adding-options).

command::rules example_command::validity_rules() const
{
  return {
    has_store_element<std::string>( env ),
    {
      [this]() { return !( is_set( "a") && is_set( "b") ); },
      "not both -a and -b can be set"
    }
  };
}

virtual void execute() = 0¶

Executes the command.

This function must be implemented and contains the main routine that the command executes. At this point all options have been parsed and the corresponding variables are assigned values. Also all validity checks have been made.

virtual nlohmann::json log() const¶

Returns logging data.

Logging data is returned in terms of a JSON object using the JSON API from https://github.com/nlohmann/json. This object can be nested, i.e., some keys can map to other objects or arrays.

nlohmann::json example_command::log() const
{
  return nlohmann::json({
    {"number", 42},
    {"float", 9.81},
    {"string", "alice"}
  });
}