Class cli (o2scl)

O2scl : Class List

class cli

Configurable command-line interface.

This class is experimental.

Default commands: help, get, set, quit, exit, license, no-intro, commands, warranty, alias, run, shell, and ‘!’.

Note that if the shell command is allowed (as it is by default) there are some potential security issues which are not solved here.

Interactive commands which begin with a ‘#’ character are ignored.

Todo

• Future: Warn in run_interactive() when extra parameters are given.

• Future: A replace command function, there’s already some code in cli.cpp for this.

• Future: There’s some code duplication between comm_option_run() and run_interactive().

• Future: Disallow direct access to ref o2scl::cli::par_list in order to ensure parameter names do not contain whitespace.

Concepts

As a matter of definition, the command-line arguments are simply called arguments. They are separated in commands (which begin with either one dash or two) and parameters to these commands. The word “parameter” is also used to refer to quantities which are modifiable by get and set.

Note

In interactive mode, commands are limited to 300 characters, but this limit does not apply when readline is used.

Subclassed by o2scl::cli_readline

Parameter storage and associated iterator type

typedef std::map<std::string, parameter*, std::greater<std::string>>::iterator par_t

List iterator.

std::map<std::string, parameter*, std::less<std::string>> par_list

Parameter list.

int verbose

Control screen output.

char buf[300]

Storage for getline.

comm_option_funct *user_set_func

Storage for the function to call after setting a parameter.

std::vector<comm_option_s> clist

List of commands.

int print_option_list()

Print out all of the command-line options.

int output_param_list()

Output the parameter list.

Todo: there is a fixme entry for 64 columns which should probably be fixed using the screen columns

Aliases

typedef std::map<std::string, std::string, std::greater<std::string>>::iterator al_it

std::map<std::string, std::string, std::greater<std::string>> als

cli()

virtual ~cli()

Colors

std::string command_color

Color for commands.

std::string type_color

Color for types.

std::string param_color

Color for parameters.

std::string help_color

Color for help topics.

std::string exec_color

Color for executable strings.

std::string url_color

Color for URLSs.

std::string default_color

Default color.

std::string colors

Color string.

The hard-coded command functions

std::string doc_o2_file

The file containing the O2scl documentation to be used.

std::vector<std::string> xml_subs

XML substitutions.

bool gnu_intro

If true, output the usual GNU intro when run_interactive() is called (default true).

In order to conform to GNU standards, this ought not be set to false by default.

int comm_option_alias(std::vector<std::string> &sv, bool itive_com)

int comm_option_commands(std::vector<std::string> &sv, bool itive_com)

int comm_option_get(std::vector<std::string> &sv, bool itive_com)

int comm_option_help(std::vector<std::string> &sv, bool itive_com)

int comm_option_license(std::vector<std::string> &sv, bool itive_com)

int comm_option_no_intro(std::vector<std::string> &sv, bool itive_com)

int comm_option_run(std::vector<std::string> &sv, bool itive_com)

int comm_option_shell(std::vector<std::string> &sv, bool itive_com)

int comm_option_set(std::vector<std::string> &sv, bool itive_com)

int comm_option_warranty(std::vector<std::string> &sv, bool itive_com)

int comm_option_xml_to_o2(std::vector<std::string> &sv, bool itive_com)

bool string_equal_dash(std::string s1, std::string s2)

Compare two strings, treating dashes and underscores as equivalent.

int apply_aliases(std::vector<std::string> &sv, size_t istart, bool debug = false)

Proceed through sv, applying all previously defined aliases.

inline int set_function(comm_option_funct &usf)

Function to call when a set command is issued.

The default command objects

comm_option_s c_alias

comm_option_s c_commands

comm_option_s c_exit

comm_option_s c_get

comm_option_s c_help

comm_option_s c_license

comm_option_s c_no_intro

comm_option_s c_quit

comm_option_s c_run

comm_option_s c_set

comm_option_s c_shell

comm_option_s c_warranty

comm_option_s c_xml_to_o2

bool sync_verbose

If true, then sync cli::verbose, with a parameter of the same name (default true)

bool shell_cmd_allowed

If true, allow the user to execute shell commands (default true)

std::string prompt

The prompt (default "> ")

std::string desc

A one- or two-line description (default is empty string)

std::string cmd_name

The name of the command.

std::string addl_help_cmd

Additional help text for interactive mode (default is empty string)

std::string addl_help_cli

Additional help text for command-line (default is empty string)

void set_colors(std::string c, int verbose = 0)

Set the colors to the values from string c.

Help for parameters

std::vector<std::string> ph_name

std::vector<std::string> ph_desc

Value to indicate whether commands are also command-line options

static const int comm_option_command = 0

static const int comm_option_cl_param = 1

static const int comm_option_both = 2

Basic operation

int set_comm_option(comm_option_s &ic)

Add a new command.

Each command/option must have either a short form in comm_option_s::shrt or a long from in comm_option_s::lng, which is unique from the other commands/options already present. You cannot add two commands/options with the same short form, even if they have different long forms, and vice versa.

void remove_comm_option(std::string cmd)

Remove a command with long name cmd.

template<class vec_t>
inline int set_comm_option_vec(size_t list_size, vec_t &option_list)

Add new commands specified in a list.

int set_param_help(std::string param, std::string help)

Set one-line help text for a parameter named param.

int run_auto(int argc, char *argv[], int debug = 0)

Automatically parse arguments to main and call interactive mode if required.

virtual char *cli_gets(const char *c)

The function which obtains input from the user.

Future: Think about whether or not this should be protected?

(Possibly not, as it’s extensively used by acolm.cpp)

int call_args(std::vector<cmd_line_arg> &ca, int debug = 0)

Call functions corresponding to command-line args.

int process_args_c(int argc, char *argv[], std::vector<cmd_line_arg> &ca, int debug = 0, bool also_call_args = false)

Process command-line arguments from a const char array.

This doesn’t actually execute the functions for the corresponding options, but simply processes the parameters argv and argv and packs the information into ca.

This function assumes that argc[0] just contains the name of the command, and should thus be ignored.

int parse_for_aliases(std::vector<std::string> &svsv, bool allow_undashed, bool debug = false)

Go through the argument list in sv and add any alias definitions which appear.

Note, if verbose is greater than 1, then new alias definitions will be output to the screen.

int process_args(std::vector<std::string> &sv, std::vector<cmd_line_arg> &ca, int debug, bool also_call_args = false)

Process command-line arguments from a vector of strings.

This doesn’t actually execute the functions for the corresponding options, but simply processes the arguments in sv and packs the information into ca.

int process_args_str(std::string s, std::vector<cmd_line_arg> &ca, int debug = 0, bool also_call_args = false)

Process command-line arguments from a string.

Future: There’s a typecast in this function to (char *)

from (const char *) which needs reworking.

int set_verbose(int v)

Set verbosity.

Most errors are output to the screen even if verbose is zero.

int run_interactive()

Run the interactive mode.

int set_alias(std::string alias, std::string str)

Set an alias alias for the string str.

Aliases can also be set using the command 'alias', but that version allows only one-word aliases.

std::string get_alias(std::string alias)

Set an alias alias for the string str.

Aliases can also be set using the command 'alias', but that version allows only one-word aliases.

bool is_valid_option(std::string str)

Return true if str is a valid option or command.

bool is_parameter(std::string name)

Return true if name is a valid parameter name.

std::vector<std::string> get_parameter_list()

Get the list of parameters.

std::vector<std::string> get_option_list()

Get the list of options/commands.

std::string parameter_desc(std::string name)

Get the description of parameter named name.

std::string option_short_desc(std::string name)

Get the short description of option named name.

int read_docs()

Read the command and parameter documentation from doc_o2_file.

void xml_replacements(std::string &s)

Make standard replacements of the Doxygen XML output.

comm_option_s *get_option_pointer(std::string name)

Get a pointer to the option of name name.

class parameter

Parameter for o2scl::cli.

Subclassed by o2scl::cli::parameter_bool, o2scl::cli::parameter_double, o2scl::cli::parameter_int, o2scl::cli::parameter_size_t, o2scl::cli::parameter_string

Public Functions

inline virtual ~parameter()

virtual int set(std::string s) = 0

Set from string.

virtual std::string get() = 0

Convert to string.

Public Members

std::string help

Help description.

int doc_type

(currently unused)

std::string doc_ns

The name of the namespace.

std::string doc_class

The name of the class (if applicable)

std::string doc_name

The function or object name.

std::string doc_xml_file

The file containing the XML documentation to be used.

class parameter_bool : public o2scl::cli::parameter

String parameter for o2scl::cli.

Public Functions

inline virtual ~parameter_bool()

inline virtual int set(std::string s)

Set from string.

inline virtual std::string get()

Convert to string.

Public Members

bool *b

Parameter.

class parameter_double : public o2scl::cli::parameter

Double parameter for o2scl::cli.

Public Functions

inline parameter_double()

inline virtual ~parameter_double()

virtual int set(std::string s)

Set from string.

inline virtual std::string get()

Convert to string.

Public Members

double *d

Parameter.

bool parse_strings

If true, use value_spec() to convert strings to doubles.

class parameter_int : public o2scl::cli::parameter

Integer parameter for o2scl::cli.

Public Functions

inline parameter_int()

inline virtual ~parameter_int()

virtual int set(std::string s)

Set from string.

inline virtual std::string get()

Convert to string.

Public Members

bool parse_strings

If true, use value_spec() to convert strings to integers.

int *i

Parameter.

class parameter_size_t : public o2scl::cli::parameter

Integer parameter for o2scl::cli.

Public Functions

inline parameter_size_t()

inline virtual ~parameter_size_t()

virtual int set(std::string st)

Set from string.

inline virtual std::string get()

Convert to string.

Public Members

bool parse_strings

If true, use value_spec() to convert strings to integers.

size_t *s

Parameter.

class parameter_string : public o2scl::cli::parameter

String parameter for o2scl::cli.

Public Functions

inline virtual ~parameter_string()

inline virtual int set(std::string s)

Set from string.

inline virtual std::string get()

Convert to string.

Public Members

std::string *str

Parameter.