Parse command-line arguments. More...
#include "command-line.h"
Classes | |
class | CallbackItem |
An argument Item using a Callback to parse the input. More... | |
class | CharStarItem |
Extension of Item for char* . More... | |
class | Item |
The argument abstract base class. More... | |
class | StringItem |
Extension of Item for extra non-options, stored as strings. More... | |
class | UserItem |
An argument Item assigning to POD. More... | |
Public Types | |
typedef bool(* | Callback) (const std::string &value) |
Callback function signature for AddValue(const std::string&,const std::string&,Callback<bool,const std::string>). | |
Public Member Functions | |
CommandLine () | |
Constructor. | |
CommandLine (const CommandLine &cmd) | |
Copy constructor. | |
CommandLine (const std::string &filename) | |
Construct and register the source file name. | |
~CommandLine () | |
Destructor. | |
template<typename T > | |
void | AddNonOption (const std::string &name, const std::string &help, T &value) |
Add a non-option argument, assigning to POD. | |
void | AddValue (const std::string &name, const std::string &attributePath) |
Add a program argument as a shorthand for an Attribute. | |
void | AddValue (const std::string &name, const std::string &help, char *value, std::size_t num) |
Retrieve the char* in char* and add it as a program argument. | |
void | AddValue (const std::string &name, const std::string &help, ns3::Callback< bool, const std::string & > callback, const std::string &defaultValue="") |
Add a program argument, using a Callback to parse the value. | |
template<typename T > | |
void | AddValue (const std::string &name, const std::string &help, T &value) |
Add a program argument, assigning to POD. | |
std::string | GetExtraNonOption (std::size_t i) const |
Get extra non-option arguments by index. | |
std::string | GetName () const |
Get the program name. | |
std::size_t | GetNExtraNonOptions () const |
Get the total number of non-option arguments found, including those configured with AddNonOption() and extra non-option arguments. | |
std::string | GetVersion () const |
Get the program version. | |
CommandLine & | operator= (const CommandLine &cmd) |
Assignment. | |
void | Parse (int argc, char *argv[]) |
Parse the program arguments. | |
void | Parse (std::vector< std::string > args) |
Parse the program arguments. | |
void | PrintHelp (std::ostream &os) const |
Print program usage to the desired output stream. | |
void | PrintVersion (std::ostream &os) const |
Print ns-3 version to the desired output stream. | |
void | Usage (const std::string &usage) |
Supply the program usage and documentation. | |
Private Types | |
using | HasOptionName = std::tuple< bool, std::string, std::string > |
Tuple type returned by GetOptionName(). | |
using | Items = std::vector< std::shared_ptr< Item > > |
Argument list container. | |
Private Member Functions | |
void | Clear () |
Remove all arguments, Usage(), name. | |
void | Copy (const CommandLine &cmd) |
Copy constructor implementation. | |
HasOptionName | GetOptionName (const std::string ¶m) const |
Strip leading -- or - from options. | |
bool | HandleArgument (const std::string &name, const std::string &value) const |
Match name against the program or general arguments, and dispatch to the appropriate handler. | |
void | HandleHardOptions (const std::vector< std::string > &args) const |
Handle hard-coded options. | |
bool | HandleNonOption (const std::string &value) |
Handle a non-option. | |
bool | HandleOption (const std::string ¶m) const |
Handle an option in the form param=value . | |
void | PrintAttributeList (std::ostream &os, const TypeId tid, std::stringstream &header) const |
Print the Attributes for a single type. | |
void | PrintAttributes (std::ostream &os, const std::string &type) const |
Handler for --PrintAttributes: print the attributes for a given type as well as its parents. | |
void | PrintDoxygenUsage () const |
Append usage message in Doxygen format to the file indicated by the NS_COMMANDLINE_INTROSPECTION environment variable. | |
void | PrintGlobals (std::ostream &os) const |
Handler for --PrintGlobals: print all global variables and values. | |
void | PrintGroup (std::ostream &os, const std::string &group) const |
Handler for --PrintGroup: print all types belonging to a given group. | |
void | PrintGroups (std::ostream &os) const |
Handler for --PrintGroups: print all TypeId group names. | |
void | PrintTypeIds (std::ostream &os) const |
Handler for --PrintTypeIds: print all TypeId names. | |
Static Private Member Functions | |
static bool | HandleAttribute (const std::string &name, const std::string &value) |
Callback function to handle attributes. | |
Private Attributes | |
std::size_t | m_NNonOptions |
The expected number of non-option arguments. | |
std::size_t | m_nonOptionCount |
The number of actual non-option arguments seen so far. | |
Items | m_nonOptions |
The list of non-option arguments. | |
Items | m_options |
The list of option arguments. | |
std::string | m_shortName |
The source file name (without .cc ), as would be given to ns3 run | |
std::string | m_usage |
The Usage string. | |
Parse command-line arguments.
Instances of this class can be used to parse command-line arguments. Programs can register a general usage message with CommandLine::Usage, and arguments with CommandLine::AddValue. Argument variable types with input streamers (operator>>
) can be set directly; more complex argument parsing can be accomplished by providing a Callback.
CommandLine also provides handlers for these standard arguments:
--PrintGlobals: Print the list of globals. --PrintGroups: Print the list of groups. --PrintGroup=[group]: Print all TypeIds of group. --PrintTypeIds: Print all TypeIds. --PrintAttributes=[typeid]: Print all attributes of typeid. --PrintVersion: Print the ns-3 version. --PrintHelp: Print this help message.
The more common --version
is a synonym for --PrintVersion
.
The more common --help
is a synonym for --PrintHelp
; an example is given below.
CommandLine can also handle non-option arguments (often called simply "positional" parameters: arguments which don't begin with "-" or "--"). These can be parsed directly in to variables, by registering arguments with AddNonOption in the order expected. Additional non-option arguments encountered will be captured as strings.
Finally, CommandLine processes Attribute and GlobalValue arguments. Default values for specific attributes can be set using a shorthand argument name.
In use, arguments are given in the form
--arg=value --toggle first-non-option
Most arguments expect a value, as in the first form, --arg=value
. Toggles, corresponding to boolean arguments, can be given in any of the forms
--toggle1 --toggle2=1 --toggle3=t --toggle4=true
The first form changes the state of toggle1 from its default; all the rest set the corresponding boolean variable to true. 0
, f
and false
are accepted to set the variable to false. Option arguments can appear in any order on the command line, even intermixed with non-option arguments. The order of non-option arguments is preserved.
Option arguments can be repeated on the command line; the last value given will be the final value used. For example,
--arg=one --toggle=f --arg=another --toggle
The variable set by --arg
will end up with the value "another"
; the boolean set by --toggle
will end up as true
.
Because arguments can be repeated it can be hard to decipher what value each variable ended up with, especially when using boolean toggles. Suggested best practice is for scripts to report the values of all items settable through CommandLine, as done by the example below.
CommandLine can set the initial value of every attribute in the system with the --TypeIdName::AttributeName=value
syntax, for example
--Application::StartTime=3s
In some cases you may want to highlight the use of a particular attribute for a simulation script. For example, you might want to make it easy to set the Application::StartTime
using the argument --start
, and have its help string show as part of the help message. This can be done using the AddValue (name, attributePath) method.
CommandLine can also set the value of every GlobalValue in the system with the --GlobalValueName=value
syntax, for example
--SchedulerType=HeapScheduler
A simple example of CommandLine is in src/core/example/
command-line-example.cc
See that file for an example of handling non-option arguments.
The heart of that example is this code:
after which it prints the values of each variable. (The SetCbArg
function is not shown here; see src/core/example/
command-line-example.cc
)
Here is the output from a few runs of that program:
$ ./ns3 run "command-line-example" intArg: 1 boolArg: false strArg: "strArg default" cbArg: "cbArg default" $ ./ns3 run "command-line-example --intArg=2 --boolArg --strArg=Hello --cbArg=World" intArg: 2 boolArg: true strArg: "Hello" cbArg: "World" $ ./ns3 run "command-line-example --help" ns3-dev-command-line-example-debug [Program Arguments] [General Arguments] CommandLine example program. This little program demonstrates how to use CommandLine. Program Arguments: --intArg: an int argument [1] --boolArg: a bool argument [false] --strArg: a string argument [strArg default] --anti: Set this RNG stream to generate antithetic values (ns3::RandomVariableStream::Antithetic) [false] --cbArg: a string via callback General Arguments: --PrintGlobals: Print the list of globals. --PrintGroups: Print the list of groups. --PrintGroup=[group]: Print all TypeIds of group. --PrintTypeIds: Print all TypeIds. --PrintAttributes=[typeid]: Print all attributes of typeid. --PrintVersion: Print the ns-3 version. --PrintHelp: Print this help message.
Having parsed the arguments, some programs will need to perform some additional validation of the received values. A common issue at this point is to discover that the supplied arguments are incomplete or incompatible. Suggested best practice is to supply an error message and the complete usage message. For example,
Finally, note that for examples which will be run by test.py
the preferred declaration of a CommandLine instance is
This will ensure that the program usage and arguments can be added to the Doxygen documentation automatically.
Definition at line 231 of file command-line.h.
typedef bool(* ns3::CommandLine::Callback) (const std::string &value) |
Callback function signature for AddValue(const std::string&,const std::string&,Callback<bool,const std::string>).
[in] | value | The argument value. |
Definition at line 309 of file command-line.h.
|
private |
Tuple type returned by GetOptionName().
Field | Meaning |
---|---|
get<0> | Is this an option (beginning with - )? |
get<1> | The option name (after any - , before = ) |
get<2> | The value (after any = ) |
Definition at line 549 of file command-line.h.
|
private |
Argument list container.
Definition at line 657 of file command-line.h.
ns3::CommandLine::CommandLine | ( | ) |
ns3::CommandLine::CommandLine | ( | const std::string & | filename | ) |
Construct and register the source file name.
This would typically be called by CommandLine cmd (FILE);
This form is required to generate Doxygen documentation of the arguments and options.
[in] | filename | The source file name. |
Definition at line 120 of file command-line.cc.
References m_shortName, NS_LOG_FUNCTION, and ns3::SystemPath::Split().
ns3::CommandLine::CommandLine | ( | const CommandLine & | cmd | ) |
Copy constructor.
[in] | cmd | The CommandLine to copy from |
Definition at line 131 of file command-line.cc.
References Copy().
ns3::CommandLine::~CommandLine | ( | ) |
Destructor.
Definition at line 144 of file command-line.cc.
References Clear(), and NS_LOG_FUNCTION.
void ns3::CommandLine::AddNonOption | ( | const std::string & | name, |
const std::string & | help, | ||
T & | value | ||
) |
Add a non-option argument, assigning to POD.
[in] | name | The name of the program-supplied argument |
[in] | help | The help text used by --PrintHelp |
[out] | value | A reference to the variable where the value parsed will be stored (if no value is parsed, this variable is not modified). |
Definition at line 762 of file command-line.h.
References m_NNonOptions, and m_nonOptions.
void ns3::CommandLine::AddValue | ( | const std::string & | name, |
const std::string & | attributePath | ||
) |
Add a program argument as a shorthand for an Attribute.
[in] | name | The name of the program-supplied argument. |
[out] | attributePath | The fully-qualified name of the Attribute |
Definition at line 778 of file command-line.cc.
References AddValue(), ns3::TypeId::AttributeInformation::checker, HandleAttribute(), ns3::TypeId::AttributeInformation::help, ns3::TypeId::AttributeInformation::initialValue, ns3::TypeId::LookupAttributeByName(), ns3::TypeId::LookupByNameFailSafe(), ns3::MakeBoundCallback(), NS_FATAL_ERROR, NS_LOG_DEBUG, and NS_LOG_FUNCTION.
void ns3::CommandLine::AddValue | ( | const std::string & | name, |
const std::string & | help, | ||
char * | value, | ||
std::size_t | num | ||
) |
Retrieve the char*
in char*
and add it as a program argument.
This variant it used to receive C string pointers from the python bindings.
The C string result stored in value
will be null-terminated, and have a maximum length of (num - 1). The result will be truncated to fit, if necessary.
[in] | name | The name of the program-supplied argument |
[in] | help | The help text used by --PrintHelp |
[out] | value | A pointer pointing to the beginning of a null-terminated C string buffer provided by the caller. The parsed value will be stored in that buffer (if no value is parsed, this variable is not modified). |
num | The size of the buffer pointed to by value , including any terminating null. |
Definition at line 746 of file command-line.cc.
References m_options, and NS_LOG_FUNCTION.
void ns3::CommandLine::AddValue | ( | const std::string & | name, |
const std::string & | help, | ||
ns3::Callback< bool, const std::string & > | callback, | ||
const std::string & | defaultValue = "" |
||
) |
Add a program argument, using a Callback to parse the value.
[in] | name | The name of the program-supplied argument |
[in] | help | The help text used by --help |
[in] | callback | A Callback function that will be invoked to parse and store the value. |
[in] | defaultValue | Optional default value for argument. |
The callback should have the signature CommandLine::Callback
Definition at line 762 of file command-line.cc.
References m_options, and NS_LOG_FUNCTION.
void ns3::CommandLine::AddValue | ( | const std::string & | name, |
const std::string & | help, | ||
T & | value | ||
) |
Add a program argument, assigning to POD.
[in] | name | The name of the program-supplied argument |
[in] | help | The help text used by --PrintHelp |
[out] | value | A reference to the variable where the value parsed will be stored (if no value is parsed, this variable is not modified). |
Definition at line 746 of file command-line.h.
References m_options.
Referenced by AddValue().
|
private |
Remove all arguments, Usage(), name.
Definition at line 165 of file command-line.cc.
References m_NNonOptions, m_nonOptions, m_options, m_shortName, m_usage, and NS_LOG_FUNCTION.
Referenced by ~CommandLine(), and operator=().
|
private |
Copy constructor implementation.
[in] | cmd | CommandLine to copy |
Definition at line 151 of file command-line.cc.
References m_NNonOptions, m_nonOptionCount, m_nonOptions, m_options, m_shortName, m_usage, and NS_LOG_FUNCTION.
Referenced by CommandLine(), and operator=().
std::string ns3::CommandLine::GetExtraNonOption | ( | std::size_t | i | ) | const |
Get extra non-option arguments by index.
This allows CommandLine to accept more non-option arguments than have been configured explicitly with AddNonOption().
This is only valid after calling Parse().
[in] | i | The index of the non-option argument to return. |
Definition at line 807 of file command-line.cc.
References m_NNonOptions, and m_nonOptions.
std::string ns3::CommandLine::GetName | ( | ) | const |
Get the program name.
Definition at line 183 of file command-line.cc.
References m_shortName.
std::size_t ns3::CommandLine::GetNExtraNonOptions | ( | ) | const |
Get the total number of non-option arguments found, including those configured with AddNonOption() and extra non-option arguments.
This is only valid after calling Parse().
Definition at line 823 of file command-line.cc.
References m_NNonOptions, and m_nonOptions.
|
private |
Strip leading --
or -
from options.
[in] | param | Option name to search |
false
if none found, indicating this is a non-option. Definition at line 231 of file command-line.cc.
Referenced by HandleHardOptions(), and HandleOption().
std::string ns3::CommandLine::GetVersion | ( | ) | const |
Get the program version.
Definition at line 445 of file command-line.cc.
References ns3::Version::LongVersion().
Referenced by PrintVersion().
|
private |
Match name against the program or general arguments, and dispatch to the appropriate handler.
[in] | name | The argument name |
[in] | value | The command line value |
true
if the argument was handled successfully Definition at line 688 of file command-line.cc.
References HandleAttribute(), m_options, NS_LOG_DEBUG, NS_LOG_FUNCTION, and PrintHelp().
Referenced by HandleOption().
|
staticprivate |
Callback function to handle attributes.
[in] | name | The full name of the Attribute. |
[in] | value | The value to assign to name. |
true
if the value was set successfully, false otherwise. Definition at line 837 of file command-line.cc.
References ns3::Config::SetDefaultFailSafe(), and ns3::Config::SetGlobalFailSafe().
Referenced by AddValue(), and HandleArgument().
|
private |
Handle hard-coded options.
[in] | args | Vector of hard-coded options to handle. |
Definition at line 273 of file command-line.cc.
References GetOptionName(), NS_LOG_FUNCTION, PrintAttributes(), PrintGlobals(), PrintGroup(), PrintGroups(), PrintHelp(), PrintTypeIds(), and PrintVersion().
Referenced by Parse().
|
private |
Handle a non-option.
[in] | value | The command line non-option value. |
true
if value
could be parsed correctly. Definition at line 346 of file command-line.cc.
References m_nonOptionCount, m_nonOptions, NS_LOG_FUNCTION, NS_LOG_LOGIC, and PrintHelp().
Referenced by Parse().
|
private |
Handle an option in the form param=value
.
[in] | param | The option string. |
true
if this was really an option. Definition at line 332 of file command-line.cc.
References GetOptionName(), and HandleArgument().
Referenced by Parse().
CommandLine & ns3::CommandLine::operator= | ( | const CommandLine & | cmd | ) |
Assignment.
[in] | cmd | The CommandLine to assign from |
Definition at line 137 of file command-line.cc.
References Clear(), and Copy().
void ns3::CommandLine::Parse | ( | int | argc, |
char * | argv[] | ||
) |
Parse the program arguments.
[in] | argc | The 'argc' variable: number of arguments (including the main program name as first element). |
[in] | argv | The 'argv' variable: a null-terminated array of strings, each of which identifies a command-line argument. |
Obviously, this method will parse the input command-line arguments and will attempt to handle them all.
As a side effect, this method saves the program basename, which can be retrieved by GetName().
Definition at line 375 of file command-line.cc.
References NS_LOG_FUNCTION, and Parse().
Referenced by Parse().
void ns3::CommandLine::Parse | ( | std::vector< std::string > | args | ) |
Parse the program arguments.
This version may be convenient when synthesizing arguments programmatically. Other than the type of argument this behaves identically to Parse(int, char *)
[in] | args | The vector of arguments. |
Definition at line 194 of file command-line.cc.
References ns3::Singleton< DesMetrics >::Get(), HandleHardOptions(), HandleNonOption(), HandleOption(), ns3::DesMetrics::Initialize(), m_nonOptionCount, NS_ASSERT_MSG, NS_LOG_FUNCTION, and PrintDoxygenUsage().
|
private |
Print the Attributes for a single type.
[in,out] | os | the output stream. |
[in] | tid | The TypeId whose Attributes should be displayed, |
[in] | header | A header line to print if tid has Attributes |
Definition at line 559 of file command-line.cc.
References ns3::TypeId::AttributeInformation::checker, ns3::TypeId::GetAttribute(), ns3::TypeId::GetAttributeFullName(), ns3::TypeId::GetAttributeN(), ns3::TypeId::AttributeInformation::help, ns3::TypeId::AttributeInformation::initialValue, and NS_LOG_FUNCTION.
Referenced by PrintAttributes().
|
private |
Handler for --PrintAttributes:
print the attributes for a given type as well as its parents.
[in,out] | os | the output stream. |
[in] | type | The type name whose Attributes should be displayed, |
Definition at line 588 of file command-line.cc.
References ns3::TypeId::GetName(), ns3::TypeId::GetParent(), ns3::TypeId::LookupByNameFailSafe(), NS_FATAL_ERROR, NS_LOG_FUNCTION, and PrintAttributeList().
Referenced by HandleHardOptions().
|
private |
Append usage message in Doxygen format to the file indicated by the NS_COMMANDLINE_INTROSPECTION environment variable.
This is typically only called once, by Parse().
Definition at line 462 of file command-line.cc.
References ns3::SystemPath::Append(), ns3::EnvironmentVariable::Get(), m_NNonOptions, m_nonOptions, m_options, m_shortName, m_usage, NS_FATAL_ERROR, NS_LOG_FUNCTION, and NS_LOG_INFO.
Referenced by Parse().
|
private |
Handler for --PrintGlobals:
print all global variables and values.
[in,out] | os | The output stream to print on. |
Definition at line 531 of file command-line.cc.
References ns3::GlobalValue::Begin(), ns3::GlobalValue::End(), ns3::StringValue::Get(), and NS_LOG_FUNCTION.
Referenced by HandleHardOptions().
|
private |
Handler for --PrintGroup:
print all types belonging to a given group.
[in,out] | os | The output stream. |
[in] | group | The name of the TypeId group to display |
Definition at line 618 of file command-line.cc.
References ns3::TypeId::GetGroupName(), ns3::TypeId::GetName(), ns3::TypeId::GetRegistered(), ns3::TypeId::GetRegisteredN(), and NS_LOG_FUNCTION.
Referenced by HandleHardOptions().
|
private |
Handler for --PrintGroups:
print all TypeId group names.
[in,out] | os | The output stream. |
Definition at line 668 of file command-line.cc.
References ns3::TypeId::GetGroupName(), ns3::TypeId::GetRegistered(), ns3::TypeId::GetRegisteredN(), and NS_LOG_FUNCTION.
Referenced by HandleHardOptions().
void ns3::CommandLine::PrintHelp | ( | std::ostream & | os | ) | const |
Print program usage to the desired output stream.
Handler for --PrintHelp
and --help:
print Usage(), argument names, and help strings
Alternatively, an overloaded operator << can be used:
[in,out] | os | The output stream to print on. |
Definition at line 383 of file command-line.cc.
References m_NNonOptions, m_nonOptions, m_options, m_shortName, m_usage, and NS_LOG_FUNCTION.
Referenced by HandleArgument(), HandleHardOptions(), and HandleNonOption().
|
private |
Handler for --PrintTypeIds:
print all TypeId names.
[in,out] | os | The output stream. |
Definition at line 645 of file command-line.cc.
References ns3::TypeId::GetName(), ns3::TypeId::GetRegistered(), ns3::TypeId::GetRegisteredN(), and NS_LOG_FUNCTION.
Referenced by HandleHardOptions().
void ns3::CommandLine::PrintVersion | ( | std::ostream & | os | ) | const |
Print ns-3 version to the desired output stream.
Handler for --PrintVersion
and --version
.
[in,out] | os | The output stream to print on. |
Definition at line 456 of file command-line.cc.
References GetVersion().
Referenced by HandleHardOptions().
void ns3::CommandLine::Usage | ( | const std::string & | usage | ) |
Supply the program usage and documentation.
[in] | usage | Program usage message to write with --help . |
Definition at line 177 of file command-line.cc.
References m_usage.
|
private |
The expected number of non-option arguments.
Definition at line 665 of file command-line.h.
Referenced by AddNonOption(), Clear(), Copy(), GetExtraNonOption(), GetNExtraNonOptions(), PrintDoxygenUsage(), and PrintHelp().
|
private |
The number of actual non-option arguments seen so far.
Definition at line 667 of file command-line.h.
Referenced by Copy(), HandleNonOption(), and Parse().
|
private |
The list of non-option arguments.
Definition at line 662 of file command-line.h.
Referenced by AddNonOption(), Clear(), Copy(), GetExtraNonOption(), GetNExtraNonOptions(), HandleNonOption(), PrintDoxygenUsage(), and PrintHelp().
|
private |
The list of option arguments.
Definition at line 660 of file command-line.h.
Referenced by AddValue(), Clear(), Copy(), HandleArgument(), PrintDoxygenUsage(), and PrintHelp().
|
private |
The source file name (without .cc
), as would be given to ns3 run
Definition at line 671 of file command-line.h.
Referenced by CommandLine(), Clear(), Copy(), GetName(), PrintDoxygenUsage(), and PrintHelp().
|
private |
The Usage string.
Definition at line 669 of file command-line.h.
Referenced by Clear(), Copy(), PrintDoxygenUsage(), PrintHelp(), and Usage().