---
name: "mlpack_CLI"
section: "3"
platform: "linux"
package: "mlpack-doc"
version: "1.0.10-1"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/mlpack_CLI"
---

# mlpack\_CLI(3)

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

## NAME

mlpack::CLI -

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

## SYNOPSIS

### Public Member Functions

**~CLI** ()\
 *Destructor.*

### 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.*  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.*  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.*  static void **DefaultMessages** ()\
 *Parses the parameters for 'help' and 'info'.*  static void **Destroy** ()\
 *Destroy the* **CLI** *object.*  static std::string **GetDescription** (const std::string &identifier)\
 *Get the description of the specified node.*  template\<typename T \> static T & **GetParam** (const std::string &identifier)\
 *Grab the value of type T found while parsing.*  static **CLI** & **GetSingleton** ()\
 *Retrieve the singleton.*  static bool **HasParam** (const std::string &identifier)\
 *See if the specified flag was found while parsing.*  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.*  static void **ParseCommandLine** (int argc, char \*\*argv)\
 *Parses the commandline for arguments.*  static void **ParseStream** (std::istream &stream)\
 *Parses a stream for arguments.*  static void **Print** ()\
 *Print out the current hierarchy.*  static void **PrintHelp** (const std::string &param='')\
 *Print out the help info of the hierarchy.*  static void **RegisterProgramDoc** (**util::ProgramDoc** \***doc**)\
 *Registers a ProgramDoc object, which contains documentation about the program.*  static void **RemoveDuplicateFlags** (po::basic\_parsed\_options\< char \> &bpo)\
 *Removes duplicate flags.*

### Public Attributes

**util::ProgramDoc** \* **doc**\
 *Pointer to the ProgramDoc object.*

### Private Types

typedef std::map\< std::string, \
 std::string \> **amap\_t**"\
 *Map for aliases, from alias to actual name.*  typedef std::map\< std::string, \
 **ParamData** \> **gmap\_t**"\
 *Map of global values.*

### Private Member Functions

**CLI** ()\
 *Make the constructor private, to preclude unauthorized instances.*  **CLI** (const std::string &optionsName)\
 *Initialize desc with a particular name.*  **CLI** (const **CLI** &other)\
 *Private copy constructor; we don't want copies floating around.*

### Static Private Member Functions

static void **AddAlias** (const std::string &alias, const std::string &original)\
 *Maps a given alias to a given parameter.*  static std::string **AliasReverseLookup** (const std::string &value)\
 *Returns an alias, if given the name of the original.*  static void **RequiredOptions** ()\
 *Checks that all required parameters have been specified on the command line.*  static std::string **SanitizeString** (const std::string &str)\
 *Cleans up input pathnames, rendering strings such as /foo/bar and foo/bar/ equivalent inputs.*  static void **UpdateGmap** ()\
 *Parses the values given on the command line, overriding any default values.*

### Private Attributes

**amap\_t** **aliasValues**\
 po::options\_description **desc**\
 *The documentation and names of options.*  bool **didParse**\
 *True, if* **CLI** *was used to parse command line options.*  **gmap\_t** **globalValues**\
 std::string **programName**\
 *Hold the name of the program for --version.*  std::list\< std::string \> **requiredOptions**\
 *Pathnames of required options.*  **Timers** **timer**\
 *Holds the timer objects.*  po::variables\_map **vmap**\
 *Values of the options given by user.*

### Static Private Attributes

static **CLI** \* **singleton**\
 *The singleton itself.*

### Friends

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

## 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):

- •

  **PARAM\_FLAG(ID, DESC, ALIAS)**

- •

  **PARAM\_DOUBLE(ID, DESC, ALIAS, DEF)**

- •

  **PARAM\_INT(ID, DESC, ALIAS, DEF)**

- •

  **PARAM\_STRING(ID, DESC, ALIAS, DEF)**

**Parameters:**

*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 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 531 of file cli.hpp.

## Member Typedef Documentation

### typedef std::map\<std::string, std::string\> mlpack::CLI::amap\_t` [private]`

Map for aliases, from alias to actual name.

Definition at line 699 of file cli.hpp.

### typedef std::map\<std::string, ParamData\> mlpack::CLI::gmap\_t` [private]`

Map of global values.

Definition at line 695 of file cli.hpp.

## Constructor & Destructor Documentation

### mlpack::CLI::~CLI ()

Destructor.

### mlpack::CLI::CLI ()` [private]`

Make the constructor private, to preclude unauthorized instances.

### mlpack::CLI::CLI (const std::string &optionsName)` [private]`

Initialize desc with a particular name.

**Parameters:**

*optionsName* Name of the module, as far as boost is concerned.

### mlpack::CLI::CLI (const CLI &other)` [private]`

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

## Member Function Documentation

### static void mlpack::CLI::Add (const std::string &path, const std::string &description, const std::string &alias = `''`, boolrequired = `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:**

*identifier* The name of the parameter. \
 *description* Short string description of the parameter. \
 *alias* An alias for the parameter, defaults to '' which is no alias. (''). \
 *required* Indicates if parameter must be set on command line.

### template\<class T \> static void mlpack::CLI::Add (const std::string &identifier, const std::string &description, const std::string &alias = `''`, boolrequired = `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:**

*identifier* The name of the parameter. \
 *description* Short string description of the parameter. \
 *alias* An alias for the parameter, defaults to '' which is no alias. \
 *required* Indicates if parameter must be set on command line.

### static void mlpack::CLI::AddAlias (const std::string &alias, const std::string &original)` [static]`, ` [private]`

Maps a given alias to a given parameter.

**Parameters:**

*alias* The name of the alias to be mapped. \
 *original* The name of the parameter to be mapped.

### 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:**

*identifier* The name of the paramater. \
 *description* Short string description of the parameter. \
 *alias* An alias for the parameter, defaults to '' which is no alias.

### static std::string mlpack::CLI::AliasReverseLookup (const std::string &value)` [static]`, ` [private]`

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

**Parameters:**

*value* The value in a key:value pair where the key is an alias.

**Returns:**

The alias associated with value.

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

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

### static std::string mlpack::CLI::GetDescription (const std::string &identifier)` [static]`

Get the description of the specified node.

**Parameters:**

*identifier* Name of the node in question.

**Returns:**

Description of the node in question.

### 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:**

*identifier* The name of the parameter in question.

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

### static bool mlpack::CLI::HasParam (const std::string &identifier)` [static]`

See if the specified flag was found while parsing.

**Parameters:**

*identifier* The name of the parameter in question.

### static std::string mlpack::CLI::HyphenateString (const std::string &str, intpadding)` [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:**

*str* String to hyphenate (splits are on ' '). \
 *padding* Amount of padding on the left for each new line.

### static void mlpack::CLI::ParseCommandLine (intargc, char \*\*argv)` [static]`

Parses the commandline for arguments.

**Parameters:**

*argc* The number of arguments on the commandline. \
 *argv* The array of arguments as strings.

### static void mlpack::CLI::ParseStream (std::istream &stream)` [static]`

Parses a stream for arguments.

**Parameters:**

*stream* The stream to be parsed.

### static void mlpack::CLI::Print ()` [static]`

Print out the current hierarchy.

### static void mlpack::CLI::PrintHelp (const std::string &param = `''`)` [static]`

Print out the help info of the hierarchy.

### 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:**

*doc* Pointer to the ProgramDoc object.

### static void mlpack::CLI::RemoveDuplicateFlags (po::basic\_parsed\_options\< char \> &bpo)` [static]`

Removes duplicate flags.

**Parameters:**

*bpo* The basic\_program\_options to remove duplicate flags from.

### static void mlpack::CLI::RequiredOptions ()` [static]`, ` [private]`

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.

### static std::string mlpack::CLI::SanitizeString (const std::string &str)` [static]`, ` [private]`

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

**Parameters:**

*str* Input string.

**Returns:**

Sanitized string.

### static void mlpack::CLI::UpdateGmap ()` [static]`, ` [private]`

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

## Friends And Related Function Documentation

### friend class Timer` [friend]`

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

Definition at line 715 of file cli.hpp.

## Member Data Documentation

### amap\_t mlpack::CLI::aliasValues` [private]`

Definition at line 700 of file cli.hpp.

### po::options\_description mlpack::CLI::desc` [private]`

The documentation and names of options.

Definition at line 686 of file cli.hpp.

### bool mlpack::CLI::didParse` [private]`

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

Definition at line 706 of file cli.hpp.

### util::ProgramDoc\* mlpack::CLI::doc

Pointer to the ProgramDoc object.

Definition at line 719 of file cli.hpp.

### gmap\_t mlpack::CLI::globalValues` [private]`

Definition at line 696 of file cli.hpp.

### std::string mlpack::CLI::programName` [private]`

Hold the name of the program for --version.

Definition at line 709 of file cli.hpp.

### std::list\<std::string\> mlpack::CLI::requiredOptions` [private]`

Pathnames of required options.

Definition at line 692 of file cli.hpp.

### CLI\* mlpack::CLI::singleton` [static]`, ` [private]`

The singleton itself.

Definition at line 703 of file cli.hpp.

### Timers mlpack::CLI::timer` [private]`

Holds the timer objects.

Definition at line 712 of file cli.hpp.

### po::variables\_map mlpack::CLI::vmap` [private]`

Values of the options given by user.

Definition at line 689 of file cli.hpp.

## Author

Generated automatically by Doxygen for MLPACK from the source code.