mlpack: a scalable c++ machine learning library
mlpack  1.0.6

Parses the command line for parameters and holds user-specified parameters. More...

Collaboration diagram for mlpack::CLI:

Public Member Functions

 ~CLI ()
 Destructor. More...

 

Static Public Member Functions

static void Add (const std::string &path, const std::string &description, const std::string &alias="", bool required=false)
 Adds a parameter to the hierarchy; use the PARAM_*() macros instead of this (i.e. More...

 
template
<
class
T
>
static void Add (const std::string &identifier, const std::string &description, const std::string &alias="", bool required=false)
 Adds a parameter to the hierarchy; use the PARAM_*() macros instead of this (i.e. More...

 
static void AddFlag (const std::string &identifier, const std::string &description, const std::string &alias="")
 Adds a flag parameter to the hierarchy; use PARAM_FLAG() instead of this. More...

 
static void DefaultMessages ()
 Parses the parameters for 'help' and 'info'. More...

 
static void Destroy ()
 Destroy the CLI object. More...

 
static std::string GetDescription (const std::string &identifier)
 Get the description of the specified node. More...

 
template
<
typename
T
>
static T & GetParam (const std::string &identifier)
 Grab the value of type T found while parsing. 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::string HyphenateString (const std::string &str, int padding)
 Hyphenate a string or split it onto multiple 80-character lines, with some amount of padding on each line. More...

 
static void ParseCommandLine (int argc, char **argv)
 Parses the commandline for arguments. More...

 
static void ParseStream (std::istream &stream)
 Parses a stream for arguments. More...

 
static void Print ()
 Print out the current hierarchy. More...

 
static void PrintHelp (const std::string &param="")
 Print out the help info of the hierarchy. More...

 
static void RegisterProgramDoc (util::ProgramDoc *doc)
 Registers a ProgramDoc object, which contains documentation about the program. More...

 
static void RemoveDuplicateFlags (po::basic_parsed_options< char > &bpo)
 Removes duplicate flags. More...

 

Public Attributes

util::ProgramDocdoc
 Pointer to the ProgramDoc object. More...

 

Private Types

typedef std::map< std::string, std::string > amap_t
 Map for aliases, from alias to actual name. More...

 
typedef std::map< std::string, ParamDatagmap_t
 Map of global values. More...

 

Private Member Functions

 CLI ()
 Make the constructor private, to preclude unauthorized instances. More...

 
 CLI (const std::string &optionsName)
 Initialize desc with a particular name. More...

 
 CLI (const CLI &other)
 Private copy constructor; we don't want copies floating around. More...

 

Static Private Member Functions

static void AddAlias (const std::string &alias, const std::string &original)
 Maps a given alias to a given parameter. More...

 
static std::string AliasReverseLookup (const std::string &value)
 Returns an alias, if given the name of the original. More...

 
static void RequiredOptions ()
 Checks that all required parameters have been specified on the command line. More...

 
static std::string SanitizeString (const std::string &str)
 Cleans up input pathnames, rendering strings such as /foo/bar and foo/bar/ equivalent inputs. More...

 
static void UpdateGmap ()
 Parses the values given on the command line, overriding any default values. More...

 

Private Attributes

amap_t aliasValues
 
po::options_description desc
 The documentation and names of options. More...

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

 
gmap_t globalValues
 
std::list< std::string > requiredOptions
 Pathnames of required options. More...

 
Timers timer
 Holds the timer objects. More...

 
po::variables_map vmap
 Values of the options given by user. More...

 

Static Private Attributes

static CLIsingleton
 The singleton itself. More...

 

Friends

class Timer
 So that Timer::Start() and Timer::Stop() can access the timer variable. 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 AllkNN executable (methods/neighbor_search/allknn_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 http://mlpack.org/trac/ticket/74 for more information.

Definition at line 530 of file cli.hpp.

Member Typedef Documentation

◆ amap_t

typedef std::map<std::string, std::string> mlpack::CLI::amap_t
private

Map for aliases, from alias to actual name.

Definition at line 698 of file cli.hpp.

◆ gmap_t

typedef std::map<std::string, ParamData> mlpack::CLI::gmap_t
private

Map of global values.

Definition at line 694 of file cli.hpp.

Constructor & Destructor Documentation

◆ ~CLI()

mlpack::CLI::~CLI ( )

Destructor.

◆ CLI() [1/3]

mlpack::CLI::CLI ( )
private

Make the constructor private, to preclude unauthorized instances.

◆ CLI() [2/3]

mlpack::CLI::CLI ( const std::string &  optionsName)
private

Initialize desc with a particular name.

Parameters
optionsNameName of the module, as far as boost is concerned.

◆ CLI() [3/3]

mlpack::CLI::CLI ( const CLI other)
private

Private copy constructor; we don't want copies floating around.

Member Function Documentation

◆ Add() [1/2]

static void mlpack::CLI::Add ( const std::string &  path,
const std::string &  description,
const std::string &  alias = "",
bool  required = false 
)
static

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

PARAM_INT()). Uses char* and not std::string since the vast majority of use cases will be literal strings.

Parameters
identifierThe name of the parameter.
descriptionShort string description of the parameter.
aliasAn alias for the parameter, defaults to "" which is no alias. ("").
requiredIndicates if parameter must be set on command line.

◆ Add() [2/2]

template
<
class
T
>
static void mlpack::CLI::Add ( const std::string &  identifier,
const std::string &  description,
const std::string &  alias = "",
bool  required = false 
)
static

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

PARAM_INT()). Uses char* and not std::string since the vast majority of use cases will be literal strings. If the argument requires a parameter, you must specify a type.

Parameters
identifierThe name of the parameter.
descriptionShort string description of the parameter.
aliasAn alias for the parameter, defaults to "" which is no alias.
requiredIndicates if parameter must be set on command line.

◆ AddAlias()

static void mlpack::CLI::AddAlias ( const std::string &  alias,
const std::string &  original 
)
staticprivate

Maps a given alias to a given parameter.

Parameters
aliasThe name of the alias to be mapped.
originalThe name of the parameter to be mapped.

◆ AddFlag()

static void mlpack::CLI::AddFlag ( const std::string &  identifier,
const std::string &  description,
const std::string &  alias = "" 
)
static

Adds a flag parameter to the hierarchy; use PARAM_FLAG() instead of this.

Parameters
identifierThe name of the paramater.
descriptionShort string description of the parameter.
aliasAn alias for the parameter, defaults to "" which is no alias.

◆ AliasReverseLookup()

static std::string mlpack::CLI::AliasReverseLookup ( const std::string &  value)
staticprivate

Returns an alias, if given the name of the original.

Parameters
valueThe value in a key:value pair where the key is an alias.
Returns
The alias associated with value.

◆ DefaultMessages()

static void mlpack::CLI::DefaultMessages ( )
static

Parses the parameters for 'help' and 'info'.

If found, will print out the appropriate information and kill the program.

◆ Destroy()

static void mlpack::CLI::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).

◆ GetDescription()

static std::string mlpack::CLI::GetDescription ( const std::string &  identifier)
static

Get the description of the specified node.

Parameters
identifierName of the node in question.
Returns
Description of the node in question.

◆ GetParam()

template
<
typename
T
>
static T& mlpack::CLI::GetParam ( const std::string &  identifier)
static

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

◆ GetSingleton()

static CLI& mlpack::CLI::GetSingleton ( )
static

Retrieve the singleton.

Not exposed to the outside, so as to spare users some ungainly x.GetSingleton().foo() syntax.

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.

◆ HasParam()

static bool mlpack::CLI::HasParam ( const std::string &  identifier)
static

See if the specified flag was found while parsing.

Parameters
identifierThe name of the parameter in question.

◆ HyphenateString()

static std::string mlpack::CLI::HyphenateString ( const std::string &  str,
int  padding 
)
static

Hyphenate a string or split it onto multiple 80-character lines, with some amount of padding on each line.

This is ued for option output.

Parameters
strString to hyphenate (splits are on ' ').
paddingAmount of padding on the left for each new line.

◆ ParseCommandLine()

static void mlpack::CLI::ParseCommandLine ( int  argc,
char **  argv 
)
static

Parses the commandline for arguments.

Parameters
argcThe number of arguments on the commandline.
argvThe array of arguments as strings.

◆ ParseStream()

static void mlpack::CLI::ParseStream ( std::istream &  stream)
static

Parses a stream for arguments.

Parameters
streamThe stream to be parsed.

◆ Print()

static void mlpack::CLI::Print ( )
static

Print out the current hierarchy.

◆ PrintHelp()

static void mlpack::CLI::PrintHelp ( const std::string &  param = "")
static

Print out the help info of the hierarchy.

◆ RegisterProgramDoc()

static void mlpack::CLI::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.

◆ RemoveDuplicateFlags()

static void mlpack::CLI::RemoveDuplicateFlags ( po::basic_parsed_options< char > &  bpo)
static

Removes duplicate flags.

Parameters
bpoThe basic_program_options to remove duplicate flags from.

◆ RequiredOptions()

static void mlpack::CLI::RequiredOptions ( )
staticprivate

Checks that all required parameters have been specified on the command line.

If any have not been specified, an error message is printed and the program is terminated.

◆ SanitizeString()

static std::string mlpack::CLI::SanitizeString ( const std::string &  str)
staticprivate

Cleans up input pathnames, rendering strings such as /foo/bar and foo/bar/ equivalent inputs.

Parameters
strInput string.
Returns
Sanitized string.

◆ UpdateGmap()

static void mlpack::CLI::UpdateGmap ( )
staticprivate

Parses the values given on the command line, overriding any default values.

Friends And Related Function Documentation

◆ Timer

friend class Timer
friend

So that Timer::Start() and Timer::Stop() can access the timer variable.

Definition at line 711 of file cli.hpp.

Member Data Documentation

◆ aliasValues

amap_t mlpack::CLI::aliasValues
private

Definition at line 699 of file cli.hpp.

◆ desc

po::options_description mlpack::CLI::desc
private

The documentation and names of options.

Definition at line 685 of file cli.hpp.

◆ didParse

bool mlpack::CLI::didParse
private

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

Definition at line 705 of file cli.hpp.

◆ doc

util::ProgramDoc* mlpack::CLI::doc

Pointer to the ProgramDoc object.

Definition at line 715 of file cli.hpp.

◆ globalValues

gmap_t mlpack::CLI::globalValues
private

Definition at line 695 of file cli.hpp.

◆ requiredOptions

std::list<std::string> mlpack::CLI::requiredOptions
private

Pathnames of required options.

Definition at line 691 of file cli.hpp.

◆ singleton

CLI* mlpack::CLI::singleton
staticprivate

The singleton itself.

Definition at line 702 of file cli.hpp.

◆ timer

Timers mlpack::CLI::timer
private

Holds the timer objects.

Definition at line 708 of file cli.hpp.

◆ vmap

po::variables_map mlpack::CLI::vmap
private

Values of the options given by user.

Definition at line 688 of file cli.hpp.


The documentation for this class was generated from the following file:
  • /var/www/www.mlpack.org/mlpack-1.0.6/src/mlpack/core/util/cli.hpp