Command line argument parser. More...

#include <cmtkCommandLine.h>

Inheritance diagram for cmtk::CommandLine:

Collaboration diagram for cmtk::CommandLine:

Classes
class	Callback
	Command line callback. More...
class	EnumGroup
	Key-to-action list for enumeration parameter groups. More...
class	EnumGroupBase
	Base class for templated EnumGroup class. More...
class	Exception
	Exception for parser error reporting. More...
class	Item
	Virtual base class for command line item. More...
class	Key
	Command line key: short and long option. More...
class	KeyActionGroupType
	Type for action groups, which map a group name to the group's key-action list. More...
class	KeyToAction
	Local class that connects command line options with their evaluators. More...
class	KeyToActionEnum
	Local class that connects command line options with enum group evaluators. More...
class	KeyToActionSingle
	Local class that connects command line options with single action evaluators. More...
class	List
	Command line option with list argument: repeated calls will add to list. More...
class	NonOptionParameter
	Non-option parameter. More...
class	NonOptionParameterVector
	Non-option parameter. More...
class	Option
	Command line option with argument. More...
class	Switch
	Command line switch. More...
class	Vector
	Command line option with vector argument. More...
Public Types
enum	ProgramProperties { PRG_TITLE = 0, PRG_DESCR = 1, PRG_CATEG = 2, PRG_ACKNL = 3, PRG_LCNSE = 4, PRG_CNTRB = 5, PRG_DOCUM = 6, PRG_VERSN = 7, PRG_SYNTX = 100 }
	Enum for program properties. More...
enum	ItemProperties { PROPS_XML = 0, PROPS_ADVANCED = 1, PROPS_MULTIPLE = 2, PROPS_NOXML = 4, PROPS_DIRNAME = 8, PROPS_FILENAME = 16, PROPS_IMAGE = 32, PROPS_LABELS = 64, PROPS_XFORM = 128, PROPS_OUTPUT = 256, PROPS_OPTIONAL = 512 }
	Enum for command line item properties. More...
typedef CommandLine	Self
	This class.
typedef void(*	CallbackFunc )()
	Callback function.
typedef void(*	CallbackFuncArg )(const char *)
	Callback function with an argument.
typedef void(*	CallbackFuncIntArg )(const long int)
	Callback function with an integer argument.
typedef void(*	CallbackFuncDblArg )(const double)
	Callback function with a double-precision floating point argument.
typedef void(*	CallbackFuncMultiArg )(const char **, int &argsUsed)
	Callback function with multiple arguments.
typedef std::vector < KeyToAction::SmartPtr >	KeyActionListType
	Type for key/action lists.
Public Member Functions
void	SetProgramInfo (const ProgramProperties key, const std::string &value)
	Set program title, description, an category.
	CommandLine (const int properties=PROPS_NOXML)
	Constructor using const inputs.
	~CommandLine ()
	Destructor: spit out a warning if there are unused extra arguments on the command line.
template<class TDataType >
EnumGroup< TDataType >::SmartPtr	AddEnum (const std::string &name, TDataType *const variable, const std::string &comment)
	Add an enum group.
template<class T >
Item::SmartPtr	AddSwitch (const Key &key, T const var, const T value, const char comment)
	Add switch.
template<class T >
Item::SmartPtr	AddOption (const Key &key, T const var, const char comment, bool *const flag=NULL)
	Add option.
template<class T >
Item::SmartPtr	AddList (const Key &key, std::list< T > &list, const char *comment)
	Add list option (put arguments from repeated uses into a FIFO list).
template<class T >
Item::SmartPtr	AddVector (const Key &key, std::vector< T > &vector, const char *comment)
	Add vector option (breaks argument into elements of a vector).
Item::SmartPtr	AddCallback (const Key &key, CallbackFunc func, const char *comment)
	Add callback.
template<class TArg >
Item::SmartPtr	AddCallback (const Key &key, void(funcArg)(const TArg), const char comment)
	Add callback with a single argument.
Item::SmartPtr	AddCallback (const Key &key, CallbackFuncMultiArg funcMultiArg, const char *comment)
	Add callback with multiple arguments.
Item::SmartPtr	AddParameter (const char *const var, const char name, const char comment, bool const flag=NULL)
	Add single non-option parameter.
Item::SmartPtr	AddParameterVector (std::vector< std::string > pvec, const char name, const char comment, bool const flag=NULL)
	Add vector of non-option parameters.
KeyToActionSingle::SmartPtr	AddKeyAction (const KeyToActionSingle::SmartPtr &keyAction)
	Add an item to applicable key/action lists.
KeyToActionEnum::SmartPtr	AddKeyAction (const KeyToActionEnum::SmartPtr &keyAction)
	Add an item to applicable key/action lists.
KeyActionGroupType::SmartPtr &	BeginGroup (const char name, const char description)
	Begin parameter group.
void	EndGroup ()
	End last parameter group.
bool	Parse (const int argc, const char *argv[]) throw ( ExitException, Self::Exception )
	Parse command line.
void	PrintHelp () const
	Print help text.
void	PrintWiki () const
	Print help text.
size_t	GetNextIndex () const
	Get next parameter index.
const char *	GetNext ()
	Get next command line argument.
const char *	GetNextOptional ()
	Get next command line argument.
void	WriteXML () const
	Write XML self description according to Slice3 execution model.
Public Attributes
KeyActionListType *	m_KeyActionList
	Reference to current key/action list (current group).
KeyActionListType	m_KeyActionListComplete
	Reference to complete key/action list (all groups combined), which is used for key lookup.
Static Public Attributes
static const int	HelpTextIndent = 10
	Help text indentation.
Private Types
typedef std::vector < KeyActionGroupType::SmartPtr >	KeyActionGroupListType
	Type for group list.
typedef std::vector < NonOptionParameter::SmartPtr >	NonOptionParameterListType
	Type for no-option parameter list.
typedef std::vector < NonOptionParameterVector::SmartPtr >	NonOptionParameterVectorListType
	Type for no-option parameter vector list. These come after the scalar non-option parameters.
typedef std::map < ProgramProperties, std::string >	ProgramPropertiesMapType
	Map type for program meta information.
Private Member Functions
mxml_node_t *	AddProgramInfoXML (mxml_node_t const parent, const ProgramProperties key, const char name) const
	Add program info item to XML tree.
void	SetDefaultInfo ()
	Set default values for meta information.
Private Attributes
size_t	ArgC
	Total number of arguments.
const char **	ArgV
	Array of argument pointers.
long int	m_Properties
	Global properties of the command line.
size_t	Index
	Index of current argument.
KeyActionGroupListType	m_KeyActionGroupList
	List of command line keys with associated actions.
NonOptionParameterListType	m_NonOptionParameterList
	List of non-option parameters (i.e., "the rest of the command line").
NonOptionParameterVectorListType	m_NonOptionParameterVectorList
	List of non-option parameters (i.e., "the rest of the command line").
ProgramPropertiesMapType	m_ProgramInfo
	Program meta information.
Friends
class	Option
	Make options class friend.
class	Switch
	Make switch class friend.
class	Callback
	Make callback class friend.

Detailed Description

Command line argument parser.

This class provides functionality for command line argument parsing, including automatic generation of help texts and XML self-description according to the specification of the Slicer3 execution model (http://www.slicer.org/slicerWiki/index.php/Slicer3:Execution_Model_Documentation)

The class handles the following types of command line arguments:

Switches

A command line switch does not have an argument itself but internally sets a variable to a pre-defined value.

Example:

 bool verbose;
 cl.AddSwitch( CommandLine::Key( "verbose" ), &verbose, true, "Verbose mode );

Effect: "--verbose" sets the "verbose" variable to "true".

Options

A command line option has an argument, which is evaluated and stored in a variable.

Example:

 int iterations = 0;
 cl.AddOption( CommandLine::Key( "iterations" ), &iterations, "Number of iterations" );

Effect: "--iterations 10" sets "iterations" to 10.

Callbacks

A callback is linked to a user-defined C function, which is called when the associated key appears on the command line.

Example:

 const char* callback( const char* arg )
 {
    std::cerr << "callback!" << std::endl;
 }
 cl.AddCallback( Key( "do-something" ), &callback, "Do something using a callback function" );

Enumerations

An enumeration is a group of options that modify the same variable by setting it to different values.

Examples:

  int InterleaveAxis = 1;
  cmtk::CommandLine::EnumGroup<int>::SmartPtr interleaveGroup = cl.AddEnum( "interleave-axis", &InterleaveAxis, "Define interleave axis." );
  interleaveGroup->AddSwitch( Key( "guess-from-input" ), -1, "Guess from input image" );
  interleaveGroup->AddSwitch( Key( 'a', "axial" ), 2, "Interleaved axial images" );
  interleaveGroup->AddSwitch( Key( 'c', "coronal" ), 1, "Interleaved coronal images" );
  interleaveGroup->AddSwitch( Key( 's', "sagittal" ), 0, "Interleaved sagittal images" );

  std::string channel( "spgr" );
  cmtk::CommandLine::EnumGroup<std::string>::SmartPtr channelGroup = cl.AddEnum( "RegistrationChannel", &channel, "MR channel." );
  channelGroup->AddSwitch( Key( "spgr" ), "spgr", "SPGR (T1-weighted) structural channel" );
  channelGroup->AddSwitch( Key( "early-fse" ), "erly", "Early-echo (PD-weighted) fast spin echo channel" );
  channelGroup->AddSwitch( Key( "late-fse" ), "late", "Late-echo (T2-weighted) fast spin echo channel" );

Definition at line 137 of file cmtkCommandLine.h.

Member Typedef Documentation

typedef void(* cmtk::CommandLine::CallbackFunc)()

Callback function.

Definition at line 223 of file cmtkCommandLine.h.

typedef void(* cmtk::CommandLine::CallbackFuncArg)(const char *)

Callback function with an argument.

Definition at line 226 of file cmtkCommandLine.h.

typedef void(* cmtk::CommandLine::CallbackFuncDblArg)(const double)

Callback function with a double-precision floating point argument.

Definition at line 232 of file cmtkCommandLine.h.

typedef void(* cmtk::CommandLine::CallbackFuncIntArg)(const long int)

Callback function with an integer argument.

Definition at line 229 of file cmtkCommandLine.h.

typedef void(* cmtk::CommandLine::CallbackFuncMultiArg)(const char **, int &argsUsed)

Callback function with multiple arguments.

Definition at line 235 of file cmtkCommandLine.h.

typedef std::vector<KeyActionGroupType::SmartPtr> cmtk::CommandLine::KeyActionGroupListType [private]

Type for group list.

Definition at line 1169 of file cmtkCommandLine.h.

typedef std::vector<KeyToAction::SmartPtr> cmtk::CommandLine::KeyActionListType

Type for key/action lists.

Definition at line 1050 of file cmtkCommandLine.h.

typedef std::vector<NonOptionParameter::SmartPtr> cmtk::CommandLine::NonOptionParameterListType [private]

Type for no-option parameter list.

Definition at line 1175 of file cmtkCommandLine.h.

typedef std::vector<NonOptionParameterVector::SmartPtr> cmtk::CommandLine::NonOptionParameterVectorListType [private]

Type for no-option parameter vector list. These come after the scalar non-option parameters.

Definition at line 1181 of file cmtkCommandLine.h.

typedef std::map<ProgramProperties,std::string> cmtk::CommandLine::ProgramPropertiesMapType [private]

Map type for program meta information.

Definition at line 1187 of file cmtkCommandLine.h.

typedef CommandLine cmtk::CommandLine::Self

This class.

Definition at line 143 of file cmtkCommandLine.h.

Member Enumeration Documentation

enum cmtk::CommandLine::ItemProperties

Enum for command line item properties.

Enumerator:

PROPS_XML	No properties, but supports XML (NOXML is off)..
PROPS_ADVANCED	Item is an advanced option.
PROPS_MULTIPLE	Item can appear repeatedly.
PROPS_NOXML	Item is not included in XML output.
PROPS_DIRNAME	Item is a generic file name.
PROPS_FILENAME	Item is a generic directory name.
PROPS_IMAGE	Item is an image file name.
PROPS_LABELS	When used with PROPS_IMAGE, this means the expected image is a label map.
PROPS_XFORM	Item is a transformation file name.
PROPS_OUTPUT	This parameter refers to an output, not an input.
PROPS_OPTIONAL	This parameter (non-option argument) is optional.

Definition at line 169 of file cmtkCommandLine.h.

enum cmtk::CommandLine::ProgramProperties

Enum for program properties.

Enumerator:

PRG_TITLE	Program title.
PRG_DESCR	Program description.
PRG_CATEG	Program category.
PRG_ACKNL	Program acknowledgement.
PRG_LCNSE	Program license (URL).
PRG_CNTRB	Program contributor.
PRG_DOCUM	Program documentation (URL).
PRG_VERSN	Program version (default: CMTK version).
PRG_SYNTX	Program syntax.

Definition at line 146 of file cmtkCommandLine.h.

Member Function Documentation

Item::SmartPtr cmtk::CommandLine::AddCallback	(	const Key &	key,
		CallbackFunc	func,
		const char *	comment
	)		`[inline]`

Add callback.

Definition at line 1011 of file cmtkCommandLine.h.

template<class TArg >

Item::SmartPtr cmtk::CommandLine::AddCallback	(	const Key &	key,
		void(*)(const TArg)	funcArg,
		const char *	comment
	)		`[inline]`

Add callback with a single argument.

Definition at line 1019 of file cmtkCommandLine.h.

Item::SmartPtr cmtk::CommandLine::AddCallback	(	const Key &	key,
		CallbackFuncMultiArg	funcMultiArg,
		const char *	comment
	)		`[inline]`

Add callback with multiple arguments.

Definition at line 1026 of file cmtkCommandLine.h.

template<class TDataType >

EnumGroup<TDataType>::SmartPtr cmtk::CommandLine::AddEnum	(	const std::string &	name,
		TDataType *const	variable,
		const std::string &	comment
	)		`[inline]`

Add an enum group.

Definition at line 966 of file cmtkCommandLine.h.

Referenced by cmtk::AffineRegistrationCommandLine::AffineRegistrationCommandLine(), cmtk::ElasticRegistrationCommandLine::ElasticRegistrationCommandLine(), cmtk::ImagePairAffineRegistrationCommandLine::ImagePairAffineRegistrationCommandLine(), cmtk::ImagePairNonrigidRegistrationCommandLine::ImagePairNonrigidRegistrationCommandLine(), and cmtk::ImageSymmetryPlaneCommandLineBase::ImageSymmetryPlaneCommandLineBase().

KeyToActionSingle::SmartPtr cmtk::CommandLine::AddKeyAction ( const KeyToActionSingle::SmartPtr & keyAction ) [inline]

Add an item to applicable key/action lists.

Definition at line 1059 of file cmtkCommandLine.h.

KeyToActionEnum::SmartPtr cmtk::CommandLine::AddKeyAction ( const KeyToActionEnum::SmartPtr & keyAction ) [inline]

Add an item to applicable key/action lists.

Definition at line 1067 of file cmtkCommandLine.h.

template<class T >

Item::SmartPtr cmtk::CommandLine::AddList	(	const Key &	key,
		std::list< T > &	list,
		const char *	comment
	)		`[inline]`

Add list option (put arguments from repeated uses into a FIFO list).

Definition at line 996 of file cmtkCommandLine.h.

template<class T >

Item::SmartPtr cmtk::CommandLine::AddOption	(	const Key &	key,
		T *const	var,
		const char *	comment,
		bool *const	flag = `NULL`
	)		`[inline]`

Add option.

Definition at line 988 of file cmtkCommandLine.h.

Item::SmartPtr cmtk::CommandLine::AddParameter	(	const char **const	var,
		const char *	name,
		const char *	comment,
		bool *const	flag = `NULL`
	)		`[inline]`

Add single non-option parameter.

Definition at line 1033 of file cmtkCommandLine.h.

Referenced by cmtk::AffineRegistrationCommandLine::AffineRegistrationCommandLine(), cmtk::ElasticRegistrationCommandLine::ElasticRegistrationCommandLine(), cmtk::ImagePairAffineRegistrationCommandLine::ImagePairAffineRegistrationCommandLine(), cmtk::ImagePairNonrigidRegistrationCommandLine::ImagePairNonrigidRegistrationCommandLine(), cmtk::ImageSymmetryPlaneCommandLineBase::ImageSymmetryPlaneCommandLineBase(), and cmtk::SimpleLevelsetCommandLineBase::SimpleLevelsetCommandLineBase().

Item::SmartPtr cmtk::CommandLine::AddParameterVector	(	std::vector< std::string > *	pvec,
		const char *	name,
		const char *	comment,
		bool *const	flag = `NULL`
	)		`[inline]`