Parse command-line arguments. More...

#include <command-line.h>

Collaboration diagram for ns3::CommandLine:

Classes
class	CallbackItem
	An argument Item using a Callback to parse the input. More...

class	Item
	The argument base class. More...

class	UserItem
	An argument Item assigning to POD. More...

Public Member Functions
	CommandLine ()
	Constructor. More...

	CommandLine (const CommandLine &cmd)
	Copy constructor. More...

	~CommandLine ()
	Destructor. More...

template<typename T >
void	AddValue (const std::string &name, const std::string &help, T &value)
	Add a program argument, assigning to POD. More...

void	AddValue (const std::string &name, const std::string &help, Callback< bool, std::string > callback)
	Add a program argument, using a Callback to parse the value. More...

std::string	GetName () const
	Get the program name. More...

CommandLine &	operator= (const CommandLine &cmd)
	Assignment. More...

void	Parse (int argc, char *argv[])
	Parse the program arguments. More...

void	PrintHelp (std::ostream &os) const
	Print program usage to the desired output stream. More...

void	Usage (const std::string usage)
	Supply the program usage and documentation. More...

Private Types
typedef std::list< Item * >	Items
	Argument list container. More...

Private Member Functions
void	Clear (void)
	Remove all arguments, Usage(), name. More...

void	Copy (const CommandLine &cmd)
	Copy constructor. More...

void	HandleArgument (const std::string &name, const std::string &value) const
	Match name against the program or general arguments, and dispatch to the appropriate handler. More...

void	PrintAttributes (std::ostream &os, const std::string &type) const
	Handler for `--PrintAttributes`: print the attributes for a given type. More...

void	PrintGlobals (std::ostream &os) const
	Handler for `--PrintGlobals`: print all global variables and values. More...

void	PrintGroup (std::ostream &os, const std::string &group) const
	Handler for `--PrintGroup`: print all types belonging to a given group. More...

void	PrintGroups (std::ostream &os) const
	Handler for `--PrintGroups`: print all TypeId group names. More...

void	PrintTypeIds (std::ostream &os) const
	Handler for `--PrintTypeIds`: print all TypeId names. More...

Private Attributes
Items	m_items
	The list of arguments. More...

std::string	m_name
	The program name. More...

std::string	m_usage
	The Usage string. More...

Detailed Description

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. POD argument variables will be set directly; more general arguments can be processed via 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.
--PrintHelp:                 Print this help message.

The more common –help is a synonym for –PrintHelp; an example is given below.

Finally, CommandLine processes Attribute and GlobalValue arguments.

In use, arguments are given in the form

--arg=value --toggle

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.

CommandLine can set the initial value of every attribute in the system with the –TypeIdName::AttributeName=value syntax, for example

--Application::StartTime=3s

CommandLine can also set the value of every GlobalValue in the system with the –GlobalValueName=value syntax, for example

--SchedulerType=HeapScheduler

A simple example is in src/core/example/ command-line-example.cc The heart of that example is this code:

  int         intArg  = 1;
  bool        boolArg = false;
  std::string strArg  = "strArg default";
CommandLine cmd;
cmd.Usage ("CommandLine example program.\n"
           "\n"
           "This little program demonstrates how to use CommandLine.");
  cmd.AddValue ("intArg",  "an int argument",       intArg);
  cmd.AddValue ("boolArg", "a bool argument",       boolArg);
  cmd.AddValue ("strArg",  "a string argument",     strArg);
  cmd.AddValue ("cbArg",   "a string via callback", MakeCallback (SetCbArg));
cmd.Parse (argc, argv);

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:

$ ./waf --run="command-line-example"
intArg:   1
boolArg:  false
strArg:   "strArg default"
cbArg:    "cbArg default"
$ ./waf --run="command-line-example --intArg=2 --boolArg --strArg=Hello --cbArg=World"
intArg:   2
boolArg:  true
strArg:   "Hello"
cbArg:    "World"
$ ./waf --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]
    --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.
    --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,

int value1;
int value2;
CommandLine cmd;
cmd.Usage ("...");
cmd.AddValue ("value1", "first value", value1);
cmd.AddValue ("value2", "second value", value1);
cmd.Parse (argc, argv);
if (value1 * value2 < 0)
  {
    std::cerr << "value1 and value2 must have the same sign!" << std::endl;
    std::cerr << cmd;
    exit (-1);
  }

Definition at line 177 of file command-line.h.

Member Typedef Documentation

typedef std::list<Item *> ns3::CommandLine::Items

private

Argument list container.

Definition at line 380 of file command-line.h.

Constructor & Destructor Documentation

ns3::CommandLine::CommandLine ( )

Constructor.

Definition at line 39 of file command-line.cc.

References NS_LOG_FUNCTION.

ns3::CommandLine::CommandLine ( const CommandLine & cmd )

Copy constructor.

Parameters

cmd	the CommandLine to copy from

Definition at line 43 of file command-line.cc.

References Copy().

Here is the call graph for this function:

ns3::CommandLine::~CommandLine ( )

Destructor.

Definition at line 54 of file command-line.cc.

References Clear(), and NS_LOG_FUNCTION.

Here is the call graph for this function:

Member Function Documentation

template<typename T >

void ns3::CommandLine::AddValue	(	const std::string &	name,
		const std::string &	help,
		T &	value
	)

Add a program argument, assigning to POD.

Parameters

name	the name of the program-supplied argument
help	the help text used by `--PrintHelp`
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 435 of file command-line.h.

References ns3::CommandLine::UserItem< T >::m_default, ns3::CommandLine::Item::m_help, m_items, ns3::CommandLine::Item::m_name, and ns3::CommandLine::UserItem< T >::m_valuePtr.

Referenced by Experiment::CommandSetup(), RoutingExperiment::CommandSetup(), AodvExample::Configure(), MeshTest::Configure(), CommandLineBooleanTestCase::DoRun(), CommandLineIntTestCase::DoRun(), CommandLineUnsignedIntTestCase::DoRun(), CommandLineStringTestCase::DoRun(), main(), PrintPsr(), PrintPsrVsCollisionInterval(), PrintPsrVsDistance(), and PrintSizeVsRange().

Here is the caller graph for this function:

void ns3::CommandLine::AddValue	(	const std::string &	name,
		const std::string &	help,
		Callback< bool, std::string >	callback
	)

Add a program argument, using a Callback to parse the value.

Parameters

name	the name of the program-supplied argument
help	the help text used by `–help`
callback	a Callback function that will be invoked to parse and store the value.

The callback should have the signature bool callback (const std::string value)

Definition at line 395 of file command-line.cc.

References ns3::CommandLine::CallbackItem::m_callback, ns3::CommandLine::Item::m_help, m_items, ns3::CommandLine::Item::m_name, and NS_LOG_FUNCTION.

void ns3::CommandLine::Clear ( void )

private

Remove all arguments, Usage(), name.

Definition at line 73 of file command-line.cc.

References m_items, m_name, m_usage, and NS_LOG_FUNCTION.

Referenced by operator=(), and ~CommandLine().

Here is the caller graph for this function:

void ns3::CommandLine::Copy ( const CommandLine & cmd )

private

Copy constructor.

Parameters

cmd	CommandLine to copy

Definition at line 60 of file command-line.cc.

References m_items, m_name, m_usage, and NS_LOG_FUNCTION.

Referenced by CommandLine(), and operator=().

Here is the caller graph for this function:

std::string ns3::CommandLine::GetName ( void ) const

Get the program name.

Returns: the program name. Only valid after calling Parse()

Definition at line 93 of file command-line.cc.

References m_name.

Referenced by main().

Here is the caller graph for this function:

void ns3::CommandLine::HandleArgument	(	const std::string &	name,
		const std::string &	value
	)		const

private

Match name against the program or general arguments, and dispatch to the appropriate handler.

Parameters

name	the argument name
value	the command line value

Definition at line 316 of file command-line.cc.

References m_items, NS_LOG_DEBUG, NS_LOG_FUNCTION, PrintAttributes(), PrintGlobals(), PrintGroup(), PrintGroups(), PrintHelp(), PrintTypeIds(), ns3::Config::SetDefaultFailSafe(), and ns3::Config::SetGlobalFailSafe().

Referenced by Parse().

Here is the call graph for this function:

Here is the caller graph for this function:

CommandLine & ns3::CommandLine::operator= ( const CommandLine & cmd )

Assignment.

Parameters

cmd	the CommandLine to assign from

Returns: the CommandLine

Definition at line 48 of file command-line.cc.

References Clear(), and Copy().

Here is the call graph for this function:

void ns3::CommandLine::Parse	(	int	argc,
		char *	argv[]
	)

Parse the program arguments.

Parameters

argc	the 'argc' variable: number of arguments (including the main program name as first element).
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 104 of file command-line.cc.

References HandleArgument(), m_name, NS_LOG_FUNCTION, and ns3::SystemPath::Split().

Referenced by Experiment::CommandSetup(), RoutingExperiment::CommandSetup(), AodvExample::Configure(), MeshTest::Configure(), main(), and CommandLineTestCaseBase::Parse().

Here is the call graph for this function:

Here is the caller graph for this function:

void ns3::CommandLine::PrintAttributes	(	std::ostream &	os,
		const std::string &	type
	)		const

private

Handler for --PrintAttributes: print the attributes for a given type.

Parameters

os	the output stream.
type	the TypeId whose Attributes should be displayed

Definition at line 222 of file command-line.cc.

References ns3::TypeId::AttributeInformation::checker, ns3::TypeId::GetAttribute(), ns3::TypeId::GetAttributeFullName(), ns3::TypeId::GetAttributeN(), ns3::TypeId::GetName(), ns3::TypeId::AttributeInformation::help, ns3::TypeId::AttributeInformation::initialValue, ns3::TypeId::LookupByNameFailSafe(), NS_FATAL_ERROR, and NS_LOG_FUNCTION.

Referenced by HandleArgument().

Here is the call graph for this function:

Here is the caller graph for this function:

void ns3::CommandLine::PrintGlobals ( std::ostream & os ) const

private

Handler for --PrintGlobals: print all global variables and values.

Definition at line 202 of file command-line.cc.

References ns3::GlobalValue::Begin(), ns3::GlobalValue::End(), ns3::StringValue::Get(), and NS_LOG_FUNCTION.

Referenced by HandleArgument().

Here is the call graph for this function:

Here is the caller graph for this function:

void ns3::CommandLine::PrintGroup	(	std::ostream &	os,
		const std::string &	group
	)		const

private

Handler for --PrintGroup: print all types belonging to a given group.

Parameters

os	the output stream.
group	the name of the TypeId group to display

Definition at line 246 of file command-line.cc.

References ns3::TypeId::GetGroupName(), ns3::TypeId::GetName(), ns3::TypeId::GetRegistered(), ns3::TypeId::GetRegisteredN(), visualizer.higcontainer::group, and NS_LOG_FUNCTION.

Referenced by HandleArgument().

Here is the call graph for this function:

Here is the caller graph for this function:

void ns3::CommandLine::PrintGroups ( std::ostream & os ) const

private

Handler for --PrintGroups: print all TypeId group names.

Definition at line 275 of file command-line.cc.

References ns3::TypeId::GetGroupName(), ns3::TypeId::GetRegistered(), ns3::TypeId::GetRegisteredN(), visualizer.higcontainer::group, and NS_LOG_FUNCTION.

Referenced by HandleArgument().

Here is the call graph for this function:

Here is the caller graph for this function:

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:

  CommandLine cmd;
  cmd.Parse (argc, argv);
...
  std::cerr << cmd;

Definition at line 150 of file command-line.cc.

References m_items, m_name, m_usage, and NS_LOG_FUNCTION.

Referenced by HandleArgument(), and ns3::operator<<().

Here is the caller graph for this function:

void ns3::CommandLine::PrintTypeIds ( std::ostream & os ) const

private

Handler for --PrintTypeIds: print all TypeId names.

Definition at line 263 of file command-line.cc.

References ns3::TypeId::GetName(), ns3::TypeId::GetRegistered(), ns3::TypeId::GetRegisteredN(), and NS_LOG_FUNCTION.

Referenced by HandleArgument().

Here is the call graph for this function:

Here is the caller graph for this function:

void ns3::CommandLine::Usage ( const std::string usage )

Supply the program usage and documentation.

Parameters

usage Program usage message to write with –help.

Definition at line 87 of file command-line.cc.

References m_usage.

Referenced by main().

Here is the caller graph for this function:

Member Data Documentation

Items ns3::CommandLine::m_items

private

The list of arguments.

Definition at line 381 of file command-line.h.

Referenced by AddValue(), Clear(), Copy(), HandleArgument(), and PrintHelp().

std::string ns3::CommandLine::m_name

private

The program name.

Definition at line 383 of file command-line.h.

Referenced by Clear(), Copy(), GetName(), Parse(), and PrintHelp().

std::string ns3::CommandLine::m_usage

private

The Usage string.

Definition at line 382 of file command-line.h.

Referenced by Clear(), Copy(), PrintHelp(), and Usage().

The documentation for this class was generated from the following files:

src/core/model/command-line.h
src/core/model/command-line.cc

Classes

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation