mlpack  master

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...

 
static void Destroy ()
 Destroy the CLI object. 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 CLIGetSingleton ()
 Retrieve the singleton. More...

 
static bool HasParam (const std::string &identifier)
 See if the specified flag was found while parsing. 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 StopTimers ()
 Stop all of the timers. 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::ProgramDocdoc
 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...

 

Detailed Description

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).

Adding parameters to a program

$ ./executable --bar=5
Note
The = is optional; a space can also be used.

A parameter is specified by using one of the following macros (this is not a complete list; see core/io/cli.hpp):

Parameters
IDName of the parameter.
DESCShort description of the parameter (one/two sentences).
ALIASAn alias for the parameter.
DEFDefault 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):

PARAM_STRING_REQ("reference_file", "File containing the reference dataset.",
"r");
PARAM_STRING_REQ("distances_file", "File to output distances into.", "d");
PARAM_STRING_REQ("neighbors_file", "File to output neighbors into.", "n");
PARAM_INT_REQ("k", "Number of furthest neighbors to find.", "k");
PARAM_STRING("query_file", "File containing query points (optional).", "q",
"");
PARAM_INT("leaf_size", "Leaf size for tree building.", "l", 20);
PARAM_FLAG("naive", "If true, O(n^2) naive mode is used for computation.",
"N");
PARAM_FLAG("single_mode", "If true, single-tree search is used (as opposed "
"to dual-tree search.", "s");

More documentation is available on the PARAM_*() macros in the documentation for core/io/cli.hpp.

Documenting the program itself

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:

PROGRAM_INFO("Maximum Variance Unfolding", "This program performs maximum "
"variance unfolding on the given dataset, writing a lower-dimensional "
"unfolded dataset to the given output file.");

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.

Parsing the command line with CLI

To have CLI parse the command line at the beginning of code execution, only a call to ParseCommandLine() is necessary:

int main(int argc, char** argv)
{
CLI::ParseCommandLine(argc, argv);
...
}

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.

Getting parameters with CLI

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":

if (CLI::HasParam("naive"))
{
Log::Info << "Naive has been passed!" << std::endl;
}

To get the value of a parameter, such as a string, use GetParam:

const std::string filename = CLI::GetParam<std::string>("filename");
Note
Options should only be defined in files which define 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.
Bug:
The COUNTER variable is used in most cases to guarantee a unique global identifier for options declared using the PARAM_*() macros. However, not all compilers have this support–most notably, gcc < 4.3. In that case, the LINE macro is used as an attempt to get a unique global identifier, but collisions are still possible, and they produce bizarre error messages. See https://github.com/mlpack/mlpack/issues/100 for more information.

Definition at line 167 of file cli.hpp.

Member Typedef Documentation

◆ FunctionMapType

typedef std::map<std::string, std::map<std::string, void (*)(const util::ParamData&, const void*, void*)> > FunctionMapType

Map for functions and types.

Use as functionMap["typename"]["functionName"].

Definition at line 302 of file cli.hpp.

Member Function Documentation

◆ Add()

static void Add ( util::ParamData &&  d)
static

Adds a parameter to the hierarchy; use the PARAM_*() macros instead of this (i.e.

PARAM_INT()).

Parameters
dUtility structure holding parameter data.

Referenced by CLIOption< N >::CLIOption(), PyOption< T >::PyOption(), and TestOption< N >::TestOption().

◆ Aliases()

static std::map<char, std::string>& Aliases ( )
static

Return a modifiable list of aliases that CLI knows about.

◆ ClearSettings()

static void ClearSettings ( )
static

Clear all of the settings, removing all parameters and function mappings.

Referenced by PyOption< T >::PyOption(), and TestOption< N >::TestOption().

◆ Destroy()

static void Destroy ( )
static

Destroy the CLI object.

This resets the pointer to the singleton, so in case someone tries to access it after destruction, a new one will be made (the program will not fail).

◆ GetParam()

static T& GetParam ( const std::string identifier)
static

Get the value of type T found while parsing.

You can set the value using this reference safely.

Parameters
identifierThe name of the parameter in question.

◆ GetPrintableParam()

static std::string GetPrintableParam ( const std::string identifier)
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.

Parameters
identifierThe name of the parameter in question.

◆ GetRawParam()

static T& GetRawParam ( const std::string identifier)
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.

Parameters
identifierThe name of the parameter in question.

◆ GetSingleton()

static CLI& GetSingleton ( )
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.

Returns
The singleton instance for use in the static methods.

Referenced by CLIOption< N >::CLIOption(), mlpack::bindings::cli::EndProgram(), mlpack::bindings::cli::ParseCommandLine(), PyOption< T >::PyOption(), mlpack::util::ResetTimers(), and TestOption< N >::TestOption().

◆ HasParam()

static bool HasParam ( const std::string identifier)
static

See if the specified flag was found while parsing.

Parameters
identifierThe name of the parameter in question.

Referenced by mlpack::bindings::cli::EndProgram(), and mlpack::bindings::cli::ParseCommandLine().

◆ Parameters()

static std::map<std::string, util::ParamData>& Parameters ( )
static

Return a modifiable list of parameters that CLI knows about.

Referenced by CLIOption< N >::CLIOption(), mlpack::bindings::cli::EndProgram(), and mlpack::bindings::cli::ParseCommandLine().

◆ ProgramName()

static std::string ProgramName ( )
static

Get the program name as set by the PROGRAM_INFO() macro.

Referenced by mlpack::bindings::cli::ParseCommandLine().

◆ RegisterProgramDoc()

static void RegisterProgramDoc ( util::ProgramDoc doc)
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.

Parameters
docPointer to the ProgramDoc object.

◆ RestoreSettings()

static void RestoreSettings ( const std::string name,
const bool  fatal = true 
)
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()).

Parameters
nameName of settings to restore.
fatalWhether to throw an exception on an unknown name.

Referenced by PyOption< T >::PyOption(), and TestOption< N >::TestOption().

◆ SetPassed()

static void SetPassed ( const std::string name)
static

Mark a particular parameter as passed.

Parameters
nameName of the parameter.

Referenced by TestOption< N >::TestOption().

◆ StopTimers()

static void StopTimers ( )
static

Stop all of the timers.

Referenced by mlpack::bindings::cli::EndProgram().

◆ StoreSettings()

static void StoreSettings ( const std::string name)
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.

Parameters
nameName of settings to save.

Referenced by PyOption< T >::PyOption(), and TestOption< N >::TestOption().

Member Data Documentation

◆ didParse

bool didParse

True, if CLI was used to parse command line options.

Definition at line 316 of file cli.hpp.

Referenced by mlpack::bindings::cli::ParseCommandLine().

◆ doc

Pointer to the ProgramDoc object.

Definition at line 331 of file cli.hpp.

◆ functionMap

◆ programName

std::string programName

Holds the name of the program for –version.

This is the true program name (argv[0]) not what is given in ProgramDoc.

Definition at line 321 of file cli.hpp.

◆ timer

Timers timer

Holds the timer objects.

Definition at line 324 of file cli.hpp.

Referenced by mlpack::bindings::cli::EndProgram(), and mlpack::util::ResetTimers().


The documentation for this class was generated from the following file: