|
| template<class T > |
| static void | Add (const T &defaultValue, const std::string &identifier, const std::string &description, const char alias= '\0', const bool required=false, const bool input=true, const bool noTranspose=false) |
| | Adds a parameter to the hierarchy; use the PARAM_*() macros instead of this (i.e. More...
|
| |
| static void | Destroy () |
| | Destroy the CLI object. More...
|
| |
| template<typename T > |
| static T & | GetParam (const std::string &identifier) |
| | Grab the value of type T found while parsing. More...
|
| |
| template<typename T > |
| static T & | GetRawParam (const std::string &identifier) |
| | Get the raw value of the parameter before the processing that GetParam() would normally do. More...
|
| |
| static CLI & | GetSingleton () |
| | Retrieve the singleton. More...
|
| |
| template<typename T > |
| static util::ParameterType< T >::type & | GetUnmappedParam (const std::string &identifier) |
| | Get the unmapped (i.e. 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 | PrintHelp (const std::string ¶m="") |
| | Print out the help info for the given parameter (or all parameters if no argument is specified). More...
|
| |
| static void | RegisterProgramDoc (util::ProgramDoc *doc) |
| | Registers a ProgramDoc object, which contains documentation about the program. 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).
Adding parameters to a program
- 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 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 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":
{
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 174 of file cli.hpp.
1.8.11