.TH "mlpack::CLI" 3 "Tue Sep 9 2014" "Version 1.0.10" "MLPACK" \" -*- nroff -*-
.ad l
.nh
.SH NAME
mlpack::CLI \- 
.PP
Parses the command line for parameters and holds user-specified parameters\&.  

.SH SYNOPSIS
.br
.PP
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "\fB~CLI\fP ()"
.br
.RI "\fIDestructor\&. \fP"
.in -1c
.SS "Static Public Member Functions"

.in +1c
.ti -1c
.RI "static void \fBAdd\fP (const std::string &path, const std::string &description, const std::string &alias='', bool required=false)"
.br
.RI "\fIAdds a parameter to the hierarchy; use the PARAM_*() macros instead of this (i\&.e\&. \fP"
.ti -1c
.RI "template<class T > static void \fBAdd\fP (const std::string &identifier, const std::string &description, const std::string &alias='', bool required=false)"
.br
.RI "\fIAdds a parameter to the hierarchy; use the PARAM_*() macros instead of this (i\&.e\&. \fP"
.ti -1c
.RI "static void \fBAddFlag\fP (const std::string &identifier, const std::string &description, const std::string &alias='')"
.br
.RI "\fIAdds a flag parameter to the hierarchy; use \fBPARAM_FLAG()\fP instead of this\&. \fP"
.ti -1c
.RI "static void \fBDefaultMessages\fP ()"
.br
.RI "\fIParses the parameters for 'help' and 'info'\&. \fP"
.ti -1c
.RI "static void \fBDestroy\fP ()"
.br
.RI "\fIDestroy the \fBCLI\fP object\&. \fP"
.ti -1c
.RI "static std::string \fBGetDescription\fP (const std::string &identifier)"
.br
.RI "\fIGet the description of the specified node\&. \fP"
.ti -1c
.RI "template<typename T > static T & \fBGetParam\fP (const std::string &identifier)"
.br
.RI "\fIGrab the value of type T found while parsing\&. \fP"
.ti -1c
.RI "static \fBCLI\fP & \fBGetSingleton\fP ()"
.br
.RI "\fIRetrieve the singleton\&. \fP"
.ti -1c
.RI "static bool \fBHasParam\fP (const std::string &identifier)"
.br
.RI "\fISee if the specified flag was found while parsing\&. \fP"
.ti -1c
.RI "static std::string \fBHyphenateString\fP (const std::string &str, int padding)"
.br
.RI "\fIHyphenate a string or split it onto multiple 80-character lines, with some amount of padding on each line\&. \fP"
.ti -1c
.RI "static void \fBParseCommandLine\fP (int argc, char **argv)"
.br
.RI "\fIParses the commandline for arguments\&. \fP"
.ti -1c
.RI "static void \fBParseStream\fP (std::istream &stream)"
.br
.RI "\fIParses a stream for arguments\&. \fP"
.ti -1c
.RI "static void \fBPrint\fP ()"
.br
.RI "\fIPrint out the current hierarchy\&. \fP"
.ti -1c
.RI "static void \fBPrintHelp\fP (const std::string &param='')"
.br
.RI "\fIPrint out the help info of the hierarchy\&. \fP"
.ti -1c
.RI "static void \fBRegisterProgramDoc\fP (\fButil::ProgramDoc\fP *\fBdoc\fP)"
.br
.RI "\fIRegisters a ProgramDoc object, which contains documentation about the program\&. \fP"
.ti -1c
.RI "static void \fBRemoveDuplicateFlags\fP (po::basic_parsed_options< char > &bpo)"
.br
.RI "\fIRemoves duplicate flags\&. \fP"
.in -1c
.SS "Public Attributes"

.in +1c
.ti -1c
.RI "\fButil::ProgramDoc\fP * \fBdoc\fP"
.br
.RI "\fIPointer to the ProgramDoc object\&. \fP"
.in -1c
.SS "Private Types"

.in +1c
.ti -1c
.RI "typedef std::map< std::string, 
.br
std::string > \fBamap_t\fP"
.br
.RI "\fIMap for aliases, from alias to actual name\&. \fP"
.ti -1c
.RI "typedef std::map< std::string, 
.br
\fBParamData\fP > \fBgmap_t\fP"
.br
.RI "\fIMap of global values\&. \fP"
.in -1c
.SS "Private Member Functions"

.in +1c
.ti -1c
.RI "\fBCLI\fP ()"
.br
.RI "\fIMake the constructor private, to preclude unauthorized instances\&. \fP"
.ti -1c
.RI "\fBCLI\fP (const std::string &optionsName)"
.br
.RI "\fIInitialize desc with a particular name\&. \fP"
.ti -1c
.RI "\fBCLI\fP (const \fBCLI\fP &other)"
.br
.RI "\fIPrivate copy constructor; we don't want copies floating around\&. \fP"
.in -1c
.SS "Static Private Member Functions"

.in +1c
.ti -1c
.RI "static void \fBAddAlias\fP (const std::string &alias, const std::string &original)"
.br
.RI "\fIMaps a given alias to a given parameter\&. \fP"
.ti -1c
.RI "static std::string \fBAliasReverseLookup\fP (const std::string &value)"
.br
.RI "\fIReturns an alias, if given the name of the original\&. \fP"
.ti -1c
.RI "static void \fBRequiredOptions\fP ()"
.br
.RI "\fIChecks that all required parameters have been specified on the command line\&. \fP"
.ti -1c
.RI "static std::string \fBSanitizeString\fP (const std::string &str)"
.br
.RI "\fICleans up input pathnames, rendering strings such as /foo/bar and foo/bar/ equivalent inputs\&. \fP"
.ti -1c
.RI "static void \fBUpdateGmap\fP ()"
.br
.RI "\fIParses the values given on the command line, overriding any default values\&. \fP"
.in -1c
.SS "Private Attributes"

.in +1c
.ti -1c
.RI "\fBamap_t\fP \fBaliasValues\fP"
.br
.ti -1c
.RI "po::options_description \fBdesc\fP"
.br
.RI "\fIThe documentation and names of options\&. \fP"
.ti -1c
.RI "bool \fBdidParse\fP"
.br
.RI "\fITrue, if \fBCLI\fP was used to parse command line options\&. \fP"
.ti -1c
.RI "\fBgmap_t\fP \fBglobalValues\fP"
.br
.ti -1c
.RI "std::string \fBprogramName\fP"
.br
.RI "\fIHold the name of the program for --version\&. \fP"
.ti -1c
.RI "std::list< std::string > \fBrequiredOptions\fP"
.br
.RI "\fIPathnames of required options\&. \fP"
.ti -1c
.RI "\fBTimers\fP \fBtimer\fP"
.br
.RI "\fIHolds the timer objects\&. \fP"
.ti -1c
.RI "po::variables_map \fBvmap\fP"
.br
.RI "\fIValues of the options given by user\&. \fP"
.in -1c
.SS "Static Private Attributes"

.in +1c
.ti -1c
.RI "static \fBCLI\fP * \fBsingleton\fP"
.br
.RI "\fIThe singleton itself\&. \fP"
.in -1c
.SS "Friends"

.in +1c
.ti -1c
.RI "class \fBTimer\fP"
.br
.RI "\fISo that \fBTimer::Start()\fP and \fBTimer::Stop()\fP can access the timer variable\&. \fP"
.in -1c
.SH "Detailed Description"
.PP 
Parses the command line for parameters and holds user-specified parameters\&. 

The \fBCLI\fP 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 \fBCLI\fP that a user should need: \fBCLI::ParseCommandLine()\fP, \fBCLI::GetParam()\fP, and \fBCLI::HasParam()\fP (in addition to the PARAM_*() macros)\&.
.SH "Adding parameters to a program"
.PP
.PP
.nf
$ \&./executable --bar=5
.fi
.PP
.PP
\fBNote:\fP
.RS 4
The = is optional; a space can also be used\&.
.RE
.PP
A parameter is specified by using one of the following macros (this is not a complete list; see core/io/cli\&.hpp):
.PP
.IP "\(bu" 2
\fBPARAM_FLAG(ID, DESC, ALIAS)\fP
.IP "\(bu" 2
\fBPARAM_DOUBLE(ID, DESC, ALIAS, DEF)\fP
.IP "\(bu" 2
\fBPARAM_INT(ID, DESC, ALIAS, DEF)\fP
.IP "\(bu" 2
\fBPARAM_STRING(ID, DESC, ALIAS, DEF)\fP
.PP
.PP
\fBParameters:\fP
.RS 4
\fIID\fP Name of the parameter\&. 
.br
\fIDESC\fP Short description of the parameter (one/two sentences)\&. 
.br
\fIALIAS\fP An alias for the parameter\&. 
.br
\fIDEF\fP Default value of the parameter\&.
.RE
.PP
The flag (boolean) type automatically defaults to false; it is specified merely as a flag on the command line (no '=true' is required)\&.
.PP
Here is an example of a few parameters being defined; this is for the AllkNN executable (methods/neighbor_search/allknn_main\&.cpp):
.PP
.PP
.nf
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");
.fi
.PP
.PP
More documentation is available on the PARAM_*() macros in the documentation for core/io/cli\&.hpp\&.
.SH "Documenting the program itself"
.PP
In addition to allowing documentation for each individual parameter and module, the \fBPROGRAM_INFO()\fP macro provides support for documenting the program itself\&. There should only be one instance of the \fBPROGRAM_INFO()\fP macro\&. Below is an example:
.PP
.PP
.nf
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\&.");
.fi
.PP
.PP
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\&.
.SH "Parsing the command line with CLI"
.PP
To have \fBCLI\fP parse the command line at the beginning of code execution, only a call to \fBParseCommandLine()\fP is necessary:
.PP
.PP
.nf
int main(int argc, char** argv)
{
  CLI::ParseCommandLine(argc, argv);

  \&.\&.\&.
}
.fi
.PP
.PP
\fBCLI\fP 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\&.
.SH "Getting parameters with CLI"
.PP
When the parameters have been defined, the next important thing is how to access them\&. For this, the \fBHasParam()\fP and \fBGetParam()\fP methods are used\&. For instance, to see if the user passed the flag (boolean) 'naive':
.PP
.PP
.nf
if (CLI::HasParam("naive"))
{
  Log::Info << "Naive has been passed!" << std::endl;
}
.fi
.PP
.PP
To get the value of a parameter, such as a string, use GetParam:
.PP
.PP
.nf
const std::string filename = CLI::GetParam<std::string>("filename");
.fi
.PP
.PP
\fBNote:\fP
.RS 4
Options should only be defined in files which define \fCmain()\fP (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\&.
.RE
.PP
\fBBug\fP
.RS 4
The \fBCOUNTER\fP 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 \fBLINE\fP 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\&. 
.RE
.PP

.PP
Definition at line 531 of file cli\&.hpp\&.
.SH "Member Typedef Documentation"
.PP 
.SS "typedef std::map<std::string, std::string> \fBmlpack::CLI::amap_t\fP\fC [private]\fP"

.PP
Map for aliases, from alias to actual name\&. 
.PP
Definition at line 699 of file cli\&.hpp\&.
.SS "typedef std::map<std::string, \fBParamData\fP> \fBmlpack::CLI::gmap_t\fP\fC [private]\fP"

.PP
Map of global values\&. 
.PP
Definition at line 695 of file cli\&.hpp\&.
.SH "Constructor & Destructor Documentation"
.PP 
.SS "mlpack::CLI::~CLI ()"

.PP
Destructor\&. 
.SS "mlpack::CLI::CLI ()\fC [private]\fP"

.PP
Make the constructor private, to preclude unauthorized instances\&. 
.SS "mlpack::CLI::CLI (const std::string &optionsName)\fC [private]\fP"

.PP
Initialize desc with a particular name\&. 
.PP
\fBParameters:\fP
.RS 4
\fIoptionsName\fP Name of the module, as far as boost is concerned\&. 
.RE
.PP

.SS "mlpack::CLI::CLI (const \fBCLI\fP &other)\fC [private]\fP"

.PP
Private copy constructor; we don't want copies floating around\&. 
.SH "Member Function Documentation"
.PP 
.SS "static void mlpack::CLI::Add (const std::string &path, const std::string &description, const std::string &alias = \fC''\fP, boolrequired = \fCfalse\fP)\fC [static]\fP"

.PP
Adds a parameter to the hierarchy; use the PARAM_*() macros instead of this (i\&.e\&. \fBPARAM_INT()\fP)\&. Uses char* and not std::string since the vast majority of use cases will be literal strings\&.
.PP
\fBParameters:\fP
.RS 4
\fIidentifier\fP The name of the parameter\&. 
.br
\fIdescription\fP Short string description of the parameter\&. 
.br
\fIalias\fP An alias for the parameter, defaults to '' which is no alias\&. ('')\&. 
.br
\fIrequired\fP Indicates if parameter must be set on command line\&. 
.RE
.PP

.SS "template<class T > static void mlpack::CLI::Add (const std::string &identifier, const std::string &description, const std::string &alias = \fC''\fP, boolrequired = \fCfalse\fP)\fC [static]\fP"

.PP
Adds a parameter to the hierarchy; use the PARAM_*() macros instead of this (i\&.e\&. \fBPARAM_INT()\fP)\&. 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\&.
.PP
\fBParameters:\fP
.RS 4
\fIidentifier\fP The name of the parameter\&. 
.br
\fIdescription\fP Short string description of the parameter\&. 
.br
\fIalias\fP An alias for the parameter, defaults to '' which is no alias\&. 
.br
\fIrequired\fP Indicates if parameter must be set on command line\&. 
.RE
.PP

.SS "static void mlpack::CLI::AddAlias (const std::string &alias, const std::string &original)\fC [static]\fP, \fC [private]\fP"

.PP
Maps a given alias to a given parameter\&. 
.PP
\fBParameters:\fP
.RS 4
\fIalias\fP The name of the alias to be mapped\&. 
.br
\fIoriginal\fP The name of the parameter to be mapped\&. 
.RE
.PP

.SS "static void mlpack::CLI::AddFlag (const std::string &identifier, const std::string &description, const std::string &alias = \fC''\fP)\fC [static]\fP"

.PP
Adds a flag parameter to the hierarchy; use \fBPARAM_FLAG()\fP instead of this\&. 
.PP
\fBParameters:\fP
.RS 4
\fIidentifier\fP The name of the paramater\&. 
.br
\fIdescription\fP Short string description of the parameter\&. 
.br
\fIalias\fP An alias for the parameter, defaults to '' which is no alias\&. 
.RE
.PP

.SS "static std::string mlpack::CLI::AliasReverseLookup (const std::string &value)\fC [static]\fP, \fC [private]\fP"

.PP
Returns an alias, if given the name of the original\&. 
.PP
\fBParameters:\fP
.RS 4
\fIvalue\fP The value in a key:value pair where the key is an alias\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
The alias associated with value\&. 
.RE
.PP

.SS "static void mlpack::CLI::DefaultMessages ()\fC [static]\fP"

.PP
Parses the parameters for 'help' and 'info'\&. If found, will print out the appropriate information and kill the program\&. 
.SS "static void mlpack::CLI::Destroy ()\fC [static]\fP"

.PP
Destroy the \fBCLI\fP 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)\&. 
.SS "static std::string mlpack::CLI::GetDescription (const std::string &identifier)\fC [static]\fP"

.PP
Get the description of the specified node\&. 
.PP
\fBParameters:\fP
.RS 4
\fIidentifier\fP Name of the node in question\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Description of the node in question\&. 
.RE
.PP

.SS "template<typename T > static T& mlpack::CLI::GetParam (const std::string &identifier)\fC [static]\fP"

.PP
Grab the value of type T found while parsing\&. You can set the value using this reference safely\&.
.PP
\fBParameters:\fP
.RS 4
\fIidentifier\fP The name of the parameter in question\&. 
.RE
.PP

.SS "static \fBCLI\fP& mlpack::CLI::GetSingleton ()\fC [static]\fP"

.PP
Retrieve the singleton\&. Not exposed to the outside, so as to spare users some ungainly x\&.GetSingleton()\&.foo() syntax\&.
.PP
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\&.
.PP
\fBReturns:\fP
.RS 4
The singleton instance for use in the static methods\&. 
.RE
.PP

.SS "static bool mlpack::CLI::HasParam (const std::string &identifier)\fC [static]\fP"

.PP
See if the specified flag was found while parsing\&. 
.PP
\fBParameters:\fP
.RS 4
\fIidentifier\fP The name of the parameter in question\&. 
.RE
.PP

.SS "static std::string mlpack::CLI::HyphenateString (const std::string &str, intpadding)\fC [static]\fP"

.PP
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\&.
.PP
\fBParameters:\fP
.RS 4
\fIstr\fP String to hyphenate (splits are on ' ')\&. 
.br
\fIpadding\fP Amount of padding on the left for each new line\&. 
.RE
.PP

.SS "static void mlpack::CLI::ParseCommandLine (intargc, char **argv)\fC [static]\fP"

.PP
Parses the commandline for arguments\&. 
.PP
\fBParameters:\fP
.RS 4
\fIargc\fP The number of arguments on the commandline\&. 
.br
\fIargv\fP The array of arguments as strings\&. 
.RE
.PP

.SS "static void mlpack::CLI::ParseStream (std::istream &stream)\fC [static]\fP"

.PP
Parses a stream for arguments\&. 
.PP
\fBParameters:\fP
.RS 4
\fIstream\fP The stream to be parsed\&. 
.RE
.PP

.SS "static void mlpack::CLI::Print ()\fC [static]\fP"

.PP
Print out the current hierarchy\&. 
.SS "static void mlpack::CLI::PrintHelp (const std::string &param = \fC''\fP)\fC [static]\fP"

.PP
Print out the help info of the hierarchy\&. 
.SS "static void mlpack::CLI::RegisterProgramDoc (\fButil::ProgramDoc\fP *doc)\fC [static]\fP"

.PP
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\&.
.PP
\fBParameters:\fP
.RS 4
\fIdoc\fP Pointer to the ProgramDoc object\&. 
.RE
.PP

.SS "static void mlpack::CLI::RemoveDuplicateFlags (po::basic_parsed_options< char > &bpo)\fC [static]\fP"

.PP
Removes duplicate flags\&. 
.PP
\fBParameters:\fP
.RS 4
\fIbpo\fP The basic_program_options to remove duplicate flags from\&. 
.RE
.PP

.SS "static void mlpack::CLI::RequiredOptions ()\fC [static]\fP, \fC [private]\fP"

.PP
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\&. 
.SS "static std::string mlpack::CLI::SanitizeString (const std::string &str)\fC [static]\fP, \fC [private]\fP"

.PP
Cleans up input pathnames, rendering strings such as /foo/bar and foo/bar/ equivalent inputs\&. 
.PP
\fBParameters:\fP
.RS 4
\fIstr\fP Input string\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
Sanitized string\&. 
.RE
.PP

.SS "static void mlpack::CLI::UpdateGmap ()\fC [static]\fP, \fC [private]\fP"

.PP
Parses the values given on the command line, overriding any default values\&. 
.SH "Friends And Related Function Documentation"
.PP 
.SS "friend class \fBTimer\fP\fC [friend]\fP"

.PP
So that \fBTimer::Start()\fP and \fBTimer::Stop()\fP can access the timer variable\&. 
.PP
Definition at line 715 of file cli\&.hpp\&.
.SH "Member Data Documentation"
.PP 
.SS "\fBamap_t\fP mlpack::CLI::aliasValues\fC [private]\fP"

.PP
Definition at line 700 of file cli\&.hpp\&.
.SS "po::options_description mlpack::CLI::desc\fC [private]\fP"

.PP
The documentation and names of options\&. 
.PP
Definition at line 686 of file cli\&.hpp\&.
.SS "bool mlpack::CLI::didParse\fC [private]\fP"

.PP
True, if \fBCLI\fP was used to parse command line options\&. 
.PP
Definition at line 706 of file cli\&.hpp\&.
.SS "\fButil::ProgramDoc\fP* mlpack::CLI::doc"

.PP
Pointer to the ProgramDoc object\&. 
.PP
Definition at line 719 of file cli\&.hpp\&.
.SS "\fBgmap_t\fP mlpack::CLI::globalValues\fC [private]\fP"

.PP
Definition at line 696 of file cli\&.hpp\&.
.SS "std::string mlpack::CLI::programName\fC [private]\fP"

.PP
Hold the name of the program for --version\&. 
.PP
Definition at line 709 of file cli\&.hpp\&.
.SS "std::list<std::string> mlpack::CLI::requiredOptions\fC [private]\fP"

.PP
Pathnames of required options\&. 
.PP
Definition at line 692 of file cli\&.hpp\&.
.SS "\fBCLI\fP* mlpack::CLI::singleton\fC [static]\fP, \fC [private]\fP"

.PP
The singleton itself\&. 
.PP
Definition at line 703 of file cli\&.hpp\&.
.SS "\fBTimers\fP mlpack::CLI::timer\fC [private]\fP"

.PP
Holds the timer objects\&. 
.PP
Definition at line 712 of file cli\&.hpp\&.
.SS "po::variables_map mlpack::CLI::vmap\fC [private]\fP"

.PP
Values of the options given by user\&. 
.PP
Definition at line 689 of file cli\&.hpp\&.

.SH "Author"
.PP 
Generated automatically by Doxygen for MLPACK from the source code\&.