Parses the command line for parameters and holds user-specified parameters. More...
Public Types | |
typedef std::map< std::string, std::map< std::string, void(*)(const util::ParamData &, const void *, void *)> > | FunctionMapType |
Map for functions and types. More... | |
Static Public Member Functions | |
static void | Add (util::ParamData &&d) |
Adds a parameter to the hierarchy; use the PARAM_*() macros instead of this (i.e. More... | |
static std::map< char, std::string > & | Aliases () |
Return a modifiable list of aliases that CLI knows about. More... | |
static void | ClearSettings () |
Clear all of the settings, removing all parameters and function mappings. More... | |
template < typename T > | |
static T & | GetParam (const std::string &identifier) |
Get the value of type T found while parsing. More... | |
template < typename T > | |
static std::string | GetPrintableParam (const std::string &identifier) |
Cast the given parameter of the given type to a short, printable std::string, for use in status messages. More... | |
template < typename T > | |
static T & | GetRawParam (const std::string &identifier) |
Get the raw value of the parameter before any processing that GetParam() might normally do. More... | |
static CLI & | GetSingleton () |
Retrieve the singleton. More... | |
static bool | HasParam (const std::string &identifier) |
See if the specified flag was found while parsing. More... | |
static void | MakeInPlaceCopy (const std::string &outputParamName, const std::string &inputParamName) |
Given two (matrix) parameters, ensure that the first is an in-place copy of the second. More... | |
static std::map< std::string, util::ParamData > & | Parameters () |
Return a modifiable list of parameters that CLI knows about. More... | |
static std::string | ProgramName () |
Get the program name as set by the PROGRAM_INFO() macro. More... | |
static void | RegisterProgramDoc (util::ProgramDoc *doc) |
Registers a ProgramDoc object, which contains documentation about the program. More... | |
static void | RestoreSettings (const std::string &name, const bool fatal=true) |
Restore all of the parameters and function mappings of the given name, if they exist. More... | |
static void | SetPassed (const std::string &name) |
Mark a particular parameter as passed. More... | |
static void | StoreSettings (const std::string &name) |
Take all parameters and function mappings and store them, under the given name. More... | |
Public Attributes | |
bool | didParse |
True, if CLI was used to parse command line options. More... | |
util::ProgramDoc * | doc |
Pointer to the ProgramDoc object. More... | |
FunctionMapType | functionMap |
std::string | programName |
Holds the name of the program for –version. More... | |
Timers | timer |
Holds the timer objects. More... | |
Parses the command line for parameters and holds user-specified parameters.
The CLI class is a subsystem by which parameters for machine learning methods can be specified and accessed. In conjunction with the macros PARAM_DOUBLE, PARAM_INT, PARAM_STRING, PARAM_FLAG, and others, this class aims to make user configurability of mlpack methods very easy. There are only three methods in CLI that a user should need: CLI::ParseCommandLine(), CLI::GetParam(), and CLI::HasParam() (in addition to the PARAM_*() macros).
A parameter is specified by using one of the following macros (this is not a complete list; see core/io/cli.hpp):
ID | Name of the parameter. |
DESC | Short description of the parameter (one/two sentences). |
ALIAS | An alias for the parameter. |
DEF | Default value of the parameter. |
The flag (boolean) type automatically defaults to false; it is specified merely as a flag on the command line (no '=true' is required).
Here is an example of a few parameters being defined; this is for the KNN executable (methods/neighbor_search/knn_main.cpp):
More documentation is available on the PARAM_*() macros in the documentation for core/io/cli.hpp.
In addition to allowing documentation for each individual parameter and module, the PROGRAM_INFO() macro provides support for documenting the program itself. There should only be one instance of the PROGRAM_INFO() macro. Below is an example:
This description should be verbose, and explain to a non-expert user what the program does and how to use it. If relevant, paper citations should be included.
To have CLI parse the command line at the beginning of code execution, only a call to ParseCommandLine() is necessary:
CLI provides –help and –info options which give nicely formatted documentation of each option; the documentation is generated from the DESC arguments in the PARAM_*() macros.
When the parameters have been defined, the next important thing is how to access them. For this, the HasParam() and GetParam() methods are used. For instance, to see if the user passed the flag (boolean) "naive":
To get the value of a parameter, such as a string, use GetParam:
main()
(that is, main executables). If options are defined elsewhere, they may be spuriously included into other executables and confuse users. Similarly, if your executable has options which you did not define, it is probably because the option is defined somewhere else and included in your executable.typedef std::map<std::string, std::map<std::string, void (*)(const util::ParamData&, const void*, void*)> > FunctionMapType |
|
static |
Adds a parameter to the hierarchy; use the PARAM_*() macros instead of this (i.e.
PARAM_INT()).
d | Utility structure holding parameter data. |
Referenced by CLIOption< N >::CLIOption(), GoOption< T >::GoOption(), JuliaOption< T >::JuliaOption(), MDOption< T >::MDOption(), PyOption< T >::PyOption(), and TestOption< N >::TestOption().
|
static |
Return a modifiable list of aliases that CLI knows about.
|
static |
Clear all of the settings, removing all parameters and function mappings.
Referenced by GoOption< T >::GoOption(), JuliaOption< T >::JuliaOption(), MDOption< T >::MDOption(), PyOption< T >::PyOption(), and TestOption< N >::TestOption().
|
static |
Get the value of type T found while parsing.
You can set the value using this reference safely.
identifier | The name of the parameter in question. |
|
static |
Cast the given parameter of the given type to a short, printable std::string, for use in status messages.
Ideally the message returned here should be only a handful of characters, and certainly no longer than one line.
identifier | The name of the parameter in question. |
|
static |
Get the raw value of the parameter before any processing that GetParam() might normally do.
So, e.g., for command-line programs, this does not perform any data loading or manipulation like GetParam() does. So if you want to access a matrix or model (or similar) parameter before it is loaded, this is the method to use.
identifier | The name of the parameter in question. |
|
static |
Retrieve the singleton.
As an end user, if you are just using the CLI object, you should not need to use this function—the other static functions should be sufficient.
In this case, the singleton is used to store data for the static methods, as there is no point in defining static methods only to have users call private instance methods.
Referenced by CLIOption< N >::CLIOption(), mlpack::bindings::cli::EndProgram(), mlpack::util::GetParamWithInfo(), GoOption< T >::GoOption(), JuliaOption< T >::JuliaOption(), MDOption< T >::MDOption(), mlpack::bindings::cli::ParseCommandLine(), PyOption< T >::PyOption(), mlpack::util::ResetTimers(), and TestOption< N >::TestOption().
|
static |
See if the specified flag was found while parsing.
identifier | The name of the parameter in question. |
Referenced by mlpack::bindings::cli::EndProgram(), and mlpack::bindings::cli::ParseCommandLine().
|
static |
Given two (matrix) parameters, ensure that the first is an in-place copy of the second.
This will generally do nothing (as the bindings already do this automatically), except for command-line bindings, where we need to ensure that the output filename is the same as the input filename.
outputParamName | Name of output (matrix) parameter. |
inputParamName | Name of input (matrix) parameter. |
|
static |
Return a modifiable list of parameters that CLI knows about.
Referenced by CLIOption< N >::CLIOption(), mlpack::bindings::cli::EndProgram(), mlpack::bindings::cli::ParseCommandLine(), and mlpack::bindings::python::PrintOutputProcessing().
|
static |
Get the program name as set by the PROGRAM_INFO() macro.
Referenced by mlpack::bindings::cli::ParseCommandLine().
|
static |
Registers a ProgramDoc object, which contains documentation about the program.
If this method has been called before (that is, if two ProgramDocs are instantiated in the program), a fatal error will occur.
doc | Pointer to the ProgramDoc object. |
|
static |
Restore all of the parameters and function mappings of the given name, if they exist.
A std::invalid_argument exception will be thrown if fatal is true and no settings with the given name have been stored (with StoreSettings()).
name | Name of settings to restore. |
fatal | Whether to throw an exception on an unknown name. |
Referenced by GoOption< T >::GoOption(), JuliaOption< T >::JuliaOption(), MDOption< T >::MDOption(), PyOption< T >::PyOption(), and TestOption< N >::TestOption().
|
static |
Mark a particular parameter as passed.
name | Name of the parameter. |
Referenced by mlpack::util::SetInputParam(), and TestOption< N >::TestOption().
|
static |
Take all parameters and function mappings and store them, under the given name.
This can later be restored with RestoreSettings(). If settings have already been saved under the given name, they will be overwritten. This also clears the current parameters and function map.
name | Name of settings to save. |
Referenced by GoOption< T >::GoOption(), JuliaOption< T >::JuliaOption(), MDOption< T >::MDOption(), PyOption< T >::PyOption(), and TestOption< N >::TestOption().
bool didParse |
True, if CLI was used to parse command line options.
Definition at line 311 of file cli.hpp.
Referenced by mlpack::bindings::cli::ParseCommandLine().
util::ProgramDoc* doc |
FunctionMapType functionMap |
Definition at line 302 of file cli.hpp.
Referenced by CLIOption< N >::CLIOption(), mlpack::bindings::cli::EndProgram(), GoOption< T >::GoOption(), JuliaOption< T >::JuliaOption(), MDOption< T >::MDOption(), mlpack::bindings::cli::ParseCommandLine(), PyOption< T >::PyOption(), and TestOption< N >::TestOption().
std::string programName |
Timers timer |
Holds the timer objects.
Definition at line 318 of file cli.hpp.
Referenced by mlpack::bindings::cli::EndProgram(), mlpack::util::GetParamWithInfo(), and mlpack::util::ResetTimers().