ArgParser¶
Synopsis¶
#include <ts/ArgParser.h>
Description¶
ArgParser
is a powerful and easy-to-use command line Parsing library for ATS.
The program defines what it requires by adding commands and options.
Then ArgParser
will figure out the related information from the command line.
All parsed arguments and function will be put in a key-value pairs structure
Arguments
available for users to use.
Usage¶
The usage of the ArgParser is straightforward. The user is expected to create an
ArgParser for the program. Commands and options can be added to the parser with details
including ENV variable, arguments expected, etc. After a single method parse(argv)
is called,
An object containing all information and parsed arguments available to use will be returned.
Create a parser¶
The first step to use ArgParser is to create a parser. The parser can be created simply by calling:
ts::ArgParser parser;
or initialize with the following arguments: name, help description, environment variable, argument number expected, function
ts::ArgParser parser("name", "description", "ENV_VAR", 0, &function);
To add the usage for the help message of this program:
parser.add_global_usage("traffic_blabla [--SWITCH]");
Add commands and options¶
We can perform all kinds of operations on the parser which is the ArgParser
or command which is a Command
.
To add commands to the program or current command:
ts::ArgParser &command1 = parser.add_command("command1", "description");
command1.add_command("command2", "description");
command1.add_command("command3", "description", "ENV_VAR", 0);
command1.add_command("command4", "description", "ENV_VAR", 0, &function, "lookup_key");
This function call returns the new Command
instance added.
Note
The 0 here is the number of arguments we expected. It can be also set to MORE_THAN_ZERO_ARG_N or MORE_THAN_ONE_ARG_N to specify that this command expects all the arguments come later (more than zero or more than one).
To add options to the parser or current command:
parser.add_option("--switch", "-s", "switch description");
command1.add_option("--switch", "-s", "switch description", "", 0);
command1.add_option("--switch", "-s", "switch description", "ENV_VAR", 1, "default", "lookup_key");
This function call returns the new Option
instance. (0 is also number of arguments expected)
We can also use the following chained way to add subcommand or option:
command.add_command("init", "description").add_command("subinit", "description");
command.add_command("remove", "description").add_option("-i", "--initoption");
which is equivalent to
ts::ArgParser::Command &init_command = command.add_command("init", "description");
ts::ArgParser::Command &remove_command = command.add_command("remove", "description");
init_command.add_command("subinit", "description");
remove_command.add_option("-i", "--initoption");
In this case, subinit is the subcommand of init and –initoption is a switch of command remove.
Parsing Arguments¶
ArgParser
parses arguments through the parse(argv)
method. This will inspect the command line
and walk through it. A Arguments
object will be built up from attributes
parsed out of the command line holding key-value pairs all the parsed data and the function.
Arguments args = parser.parse(argv);
Invoke functions¶
To invoke the function associated with certain commands, we can perform this by simply calling invoke()
from the Arguments
object returned from the parsing. The function can be a lambda.
args.invoke();
Help message¶
Help message will be outputted when a wrong usage of the program is detected or –help option found.
Classes¶
-
class
ArgParser
¶ -
Option &
add_option
(std::string const &long_option, std::string const &short_option, std::string const &description, std::string const &envvar = "", unsigned arg_num = 0, std::string const &default_value = "", std::string const &key = "")¶ Add an option to current command with long name, short name, help description, environment variable, arguments expected, default value and lookup key. Return The Option object itself.
-
Command &
add_command
(std::string const &cmd_name, std::string const &cmd_description, std::function<void()> const &f = nullptrstd::string const &key = "", )¶ Add a command with only name and description, function to invoke and lookup key. Return the new
Command
object.
-
Command &
add_command
(std::string const &cmd_name, std::string const &cmd_description, std::string const &cmd_envvar, unsigned cmd_arg_num, std::function<void()> const &f = nullptrstd::string const &key = "", )¶ Add a command with name, description, environment variable, number of arguments expected, function to invoke and lookup key. The function can be passed by reference or be a lambda. It returns the new
Command
object.
-
void
parse
(const char **argv)¶ Parse the command line by calling
parser.parse(argv)
. Return the newArguments
instance.
-
void
help_message
() const¶ Output usage to the console.
-
void
add_global_usage
(std::string const &usage)¶ Add a global_usage for
help_message()
. Example: traffic_blabla [–SWITCH [ARG]].
-
void
set_default_command
(std::string const &cmd);¶ Set a default command to the parser. This method should be called after the adding of the commands.
-
Command &
require_commands
()¶ Make the parser require commands. If no command is found, output help message. Return The
Command
instance for chained calls.
-
void
set_error
(std::string e)¶ Set the user customized error message for the parser.
-
std::string
get_error
() const¶ Return the error message of the parser.
-
Option &
struct Option {
std::string long_option; // long option: --arg
std::string short_option; // short option: -a
std::string description; // help description
std::string envvar; // stored ENV variable
unsigned arg_num; // number of argument expected
std::string default_value; // default value of option
std::string key; // look-up key
};
-
class
Command
¶ Command
is a nested structure of command forArgParser
. Theadd_option()
,add_command()
andrequire_command()
are the same with those inArgParser
. Whenadd_command()
is called under certain command, it will be added as a subcommand for the current command. For Example,command1.add_command("command2", "description")
will makecommand2
a subcommand ofcommand1
.require_commands()
is also available withinCommand
.-
void
add_example_usage
(std::string const &usage)¶ Add an example usage for the command to output in help_message. For Example:
command.add_example_usage("traffic_blabla init --path=/path/to/file")
.
-
void
-
class
Arguments
¶ Arguments
holds the parsed arguments and function to invoke. It basically contains a function to invoke and a private map holding key-value pairs. The key is the command or option name string and the value is the Parsed data object which contains the environment variable and arguments that belong to this certain command or option.-
std::string
get
(std::string const &name)¶ Return the
ArgumentData
object related to the name.
-
std::string
set_env
(std::string const &key, std::string const &value)¶ Set the environment variable given key.
-
void
append
(std::string const &key, ArgumentData const &value)¶ Append key-value pairs to the map in
Arguments
.
-
void
append_arg
(std::string const &key, std::string const &value)¶ Append value to the data of key.
-
void
show_all_configuration
() const¶ Show all the called commands, options, and associated arguments.
-
void
invoke
()¶ Invoke the function associated with the parsed command.
-
void
has_action
() const¶ return true if there is any function to invoke.
-
std::string
-
class
ArgumentData
¶ ArgumentData
is a struct containing the parsed Environment variable and command line arguments. There are methods to get the data out of it.Note: More methods can be added later to get specific types from the arguments.
-
operator bool
() const noexcept¶ bool for checking if certain command or option is called.
-
std::string const &
operator[]
(int x) const¶ Index accessing operator.
-
std::string const &
env
() const noexcept¶ Return the environment variable associated with the argument.
-
std::vector<std::string>::const_iterator
begin
() const noexcept¶ Begin iterator for iterating the arguments data.
-
std::vector<std::string>::const_iterator
end
() const noexcept¶ End iterator for iterating the arguments data.
-
std::string const &
at
(unsigned index) const¶ Index accessing method.
-
std::string const &
value
() const noexcept¶ Return the first element of the arguments data.
-
Example¶
ArgParser¶
Below is a short example of using the ArgParser. We add some options and some commands to it using different ways. This program will have such functionality:
--switch
,-s
as a global switch.Command
func
will callfunction()
and this command takes 2 argument.Command
func2
will callfunction2(int num)
.Command
init
has subcommandsubinit
and option--path
which take 1 argument.Command
remove
has option--path
which takes 1 argument and hasHOME
as the environment variable.
#include "ts/ArgParser.h"
void function() {
...
}
void function2(int num) {
...
}
int main (int, const char **argv) {
ts::ArgParser parser;
parser.add_global_usage("traffic_blabla [some stuff]");
parser.add_option("--switch", "-s", "top level switch");
parser.add_command("func", "some function", "ENV_VAR", 2, &function);
parser.add_command("func2", "some function2", [&]() { return function2(100); });
auto &init_command = parser.add_command("init", "initialize");
init_command.add_option("--path", "-p", "specify the path", "", 1);
init_command.add_command("subinit", "sub initialize");
parser.add_command("remove", "remove things").add_option("--path", "-p", "specify the path", "HOME", 1);
ts::Arguments parsed_data = parser.parse(argv);
parsed_data.invoke();
...
}
Arguments¶
To get the values from the arguments data, please refer to the methods in Arguments
and ArgumentData