dlrLibs Utility Libraries: dlr::utilities::OptionParser Class Reference

List of all members.


Public Member Functions
	OptionParser (bool allowExtraArguments=true, bool allowStackedShortOptions=true, bool allowOptionishArguments=false)
	Default constructor.
	OptionParser (int exitCode, bool handleMinusMinusHelp=true, bool printUsage=true, bool allowExtraArguments=true, bool allowStackedShortOptions=true, bool allowOptionishArguments=false)
	This constructor specifies that if a malformed commandline is parsed, the OptionParser should exit instead of throwing an exception, optionally printing a usage message first.
	~OptionParser ()
	Destructor.
void	addOption (const std::string &name, const std::string &shortVersion, const std::string &longVersion, const std::string &docString, bool allowPartialMatch=true)
	This member function adds an option to be recognized during command line parsing.
void	addOptionWithValue (const std::string &name, const std::string &shortVersion, const std::string &longVersion, const std::string &defaultValue, const std::string &docString, bool requireArgument=true, bool allowPartialMatch=true, bool allowOptionishValue=false)
	This member function adds an option which requires a value to the list which will be recognized during command line parsing.
void	addPositionalArgument (const std::string &name, const std::string &docString, bool isRequired=false, const std::string &defaultValue="")
	This member function adds a named positional argument.
template<class Type>
Type	convertValue (const std::string &name)
	This member function is like getValue(const std::string&), but attempts to convert the returned string to the specified type.
template<class Type>
Type	convertValue (const std::string &name, int valueIndex)
	This member function is like getValue(const std::string&, int), but attempts to convert the returned string to the specified type.
size_t	getCount (const std::string &name) const
	This member function indicates how many times the specified option or positional argument was specified in the most recently parsed command line.
std::vector< std::string >	getExtraPositionalArguments ()
	If constructor argument allowExtraArguments was set to true, and if number of positional arguments on the most recently parsed command line exceeds the number of named positional arguments specified using addPositionalArgument(), then this member function will return the extra positional arguments, in the order they were found on the command line, as a vector of strings.
std::string	getOptionsDescription ()
	This member function returns a formatted string describing the available command line options, as specified using addOption() and addOptionWithValue().
std::string	getUsage ()
	This member function returns a formatted string suitable for a usage message.
std::string	getValue (const std::string &name)
	Following a successful parse of a command line, this member function returns the requested option value or positional argument value as a string.
std::string	getValue (const std::string &name, int valueIndex)
	Following a successful parse of a command line, this member function returns the (valueIndex)th value of the requested option or positional argument.
template<class Type>
Type	getValue (const std::string &name, type_tag< Type >)
template<class Type>
Type	getValue (const std::string &name, int valueIndex, type_tag< Type >)
void	parseCommandLine (int argc, char *argv[])
	This member function should be called after all calls to addOption(), addOptionWithValue(), and addPositionalArgument() are completed in order to parse a command line and store the result for subsequent access using the getCount() and getValue() methods.

Detailed Description

   // Create an OptionParser which automatically generates
   // help messages, and which prints usage and calls exit(65)
   // if it encounters an inappropriate command line.
   OptionParser optionParser(65);

   // Specify options which do not take arguments.
   optionParser.addOption(
     "NOLINK", "-c", "--no_link",
     "Don't run the linker.  Instead, generate .o files.");
   optionParser.addOption(
     "DEBUG", "-g", "--debug",
     "Include debugging symbols in generated object code.");

   // Specify options which require values.
   optionParser.addOptionWithValue(
     "OPTIMIZATION_LEVEL", "-O", "--optimization_level", "0",
     "Set optimization level.");
   optionParser.addOptionWithValue(
     "INCLUDE_DIR", "-I", "--include_dir", "",
     "Add INCLUDE_DIR to include search path.");

   // Specify required positional arguments.
   optionParser.addPositionalArgument(
     "INPUT_FILE", "File to be compiled.", true);

   // Specify positional arguments which are not required.
   optionParser.addPositionalArgument(
     "SECOND_FILE", "Additional file to be compiled.", false);

   // Parse program arguments.
   optionParser.parseCommandLine(argc, argv);

   // Recover results of parse.
   bool debug = optionParser.getCount("DEBUG") != 0;
   int  optimizationLevel =
     optionParser.convertValue<int>("OPTIMIZATION_LEVEL", dlr::Int);
   std::string inputFile0 = optionParser.getValue("INPUT_FILE");
   std::string inputFile1 = optionParser.getValue("SECOND_FILE");
   std::vector<std::string> includeDirs;
   for(size_t includeIndex = 0;
       includeIndex < optionParser.getCount("INCLUDE_DIR");
       ++includeIndex) {
     includeDirs.push_back(
       optionParser.getValue("INCLUDE_DIR", includeIndex));
   }

A command line argument is considered to match the short version of an option if it begins with the entire text of the short version. For example, each of "-p", "-pdf", and "-pp" would match an option with a short version of "-p". Arguments which match the short version of an option, but have additional text (such as "-pdf" in the example above) are interpreted in one of two ways. If constructor argument allowStackedShortOptions was set to true, and the short version of the matched option starts with the character '-', and the matched option does not take an value, then the remaining text will be prepended with a '-' character and re-parsed. In this case, the "-pdf" from the previous example would be parsed as if it were typed "-p -df". In all other cases, the remaining text will be interpreted as an argument to the matched option, that is "-pdf" would be parsed as "-p" with the argument "df".

A command line argument is considered to match the long version of an option if one of three things is true: first, the text of the argument matches the text of the long version of the option exactly; second the option was specified with "allowPartialMatch" set to true, and the entire text of the argument matches an initial substring of the long version of the option; or third, the argument begins with a string that matches under one of the other two cases, and then continues with a string that starts with an equals sign. For an option with long version "--optimization_level", these three cases are illustrated by the three argument strings "--optimization_level", "--opt", and "--opt=3". In the final case, the text following the equals sign is interpreted as a value being specified for the option.

Constructor & Destructor Documentation

dlr::utilities::OptionParser::OptionParser	(	bool	allowExtraArguments = `true`,
		bool	allowStackedShortOptions = `true`,
		bool	allowOptionishArguments = `false`
	)

Default constructor.

OptionParser instances constructed in this way will throw an IOException from parseCommandLine() if the command line doesn't match the specified options. You can catch the exception and the print usage, etc.

Parameters:

	allowExtraArguments	This argument specifies whether extra positional argument should be permitted. If allowExtraArguments is false, then member function parseCommandLine() will throw an IOException whenever the number of positional arguments on the command line exceeds the number specified using member function addPositionalArgument(). If allowExtraArguments is true, then any extra positional arguments will be recorded without throwing an exception. These arguments can then be recovered using member function getExtraPositionalArguments().
	allowStackedShortOptions	This argument specifies whether it is permissible to decompose arguments such as "-plr" into "-p -l -r". If allowStackedShortOptions is true, then this type of decomposition will be carried out for short options which do not accept values. If option "-p" does accept a value, then "-plr" will (as always) be interpreted as "-p" with the argument "lr". Note that this type of decomposition may lead to ambiguity. For example, if you have an option "-p" and an option "-pl", then it's hard to know how "-plr" should parse. If any of your short options are longer than a dash plus a single character, then you may wish disable stacked short options by setting allowStackedShortOptions to false.
	allowOptionishArguments	This argument specifies how to handle command line arguments which start with "-", but which don't correspond to any of the specified options. If allowOptionishArguments is true, then such arguments will be simply recorded as positional arguments. If allowOptionishArguments is false, then such arguments will cause an IOException to be thrown for "unrecognized option."

Definition at line 26 of file optionParser.cpp.

dlr::utilities::OptionParser::OptionParser	(	int	exitCode,
		bool	handleMinusMinusHelp = `true`,
		bool	printUsage = `true`,
		bool	allowExtraArguments = `true`,
		bool	allowStackedShortOptions = `true`,
		bool	allowOptionishArguments = `false`
	)			`[explicit]`

This constructor specifies that if a malformed commandline is parsed, the OptionParser should exit instead of throwing an exception, optionally printing a usage message first.

Parameters:

	exitCode	This argument specifies the exit code which should be used to report a bad command line.
	handleMinusMinusHelp	This argument specifies whether the parser should automatically watch of "--help" arguments. If handleMinusMinusHelp is true, the parser will print a usage message and then exit(0) when a "--help" option is encountered.
	printUsage	This argument specifies whether, when a malformed commandline is parsed, a usage message should be printed before exiting with the specified exit code.
	allowExtraArguments	Please refer to the documentation for the default constructor to find a description of this argument.
	allowStackedShortOptions	Please refer to the documentation for the default constructor to find a description of this argument.
	allowOptionishArguments	Please refer to the documentation for the default constructor to find a description of this argument.

Definition at line 52 of file optionParser.cpp.

dlr::utilities::OptionParser::~OptionParser ( )

Destructor.

Definition at line 81 of file optionParser.cpp.

Member Function Documentation

void dlr::utilities::OptionParser::addOption	(	const std::string &	name,
		const std::string &	shortVersion,
		const std::string &	longVersion,
		const std::string &	docString,
		bool	allowPartialMatch = `true`
	)

This member function adds an option to be recognized during command line parsing.

Parameters:

	name	This argument specifies a unique name for the option. It will be used later to refer to this option when checking parsing results.
	shortVersion	This argument specifies a short version of the option, such as "-p" or "-rgb". Setting this argument to "" indicates that this option does not have a short version.
	longVersion	This argument specifies a long version of the option, such as "--do_calibration". Setting this argument to "" indicates that this option does not have a long version.
	docString	This argument specifies a breif description for the option. If the automatic documentation features of the optionParser are not being used, then this argument can be safely set to "".
	allowPartialMatch	This argument specifies whether to allow partial matches for the long version of this option. For more information, please see the class comment for OptionParser.

Definition at line 89 of file optionParser.cpp.

References DLR_THROW.

void dlr::utilities::OptionParser::addOptionWithValue	(	const std::string &	name,
		const std::string &	shortVersion,
		const std::string &	longVersion,
		const std::string &	defaultValue,
		const std::string &	docString,
		bool	requireArgument = `true`,
		bool	allowPartialMatch = `true`,
		bool	allowOptionishValue = `false`
	)

This member function adds an option which requires a value to the list which will be recognized during command line parsing.

Parameters:

	name	This argument specifies a unique name for the option. It will be used later to refer to this option when checking parsing results.
	shortVersion	This argument specifies a short version of the option, such as "-p" or "-rgb". Setting this argument to "" indicates that this option does not have a short version.
	longVersion	This argument specifies a long version of the option, such as "--do_calibration". Setting this argument to "" indicates that this option does not have a long version.
	defaultValue	This argument specifies the default value for the option. If the option is not found on the command line, then the default value will be used.
	docString	This argument specifies a breif description for the option. If the automatic documentation features of the optionParser are not being used, then this argument can be safely set to "".
	requireArgument	This argument is currently not supported.
	allowPartialMatch	This argument specifies whether to allow partial matches for the long version of this option. For more information, please see the class comment for OptionParser.
	allowOptionishValue	This argument specifies whether or not the supplied value (on the command line) is permitted to begin with the character '-'.

Definition at line 110 of file optionParser.cpp.

References DLR_THROW.

void dlr::utilities::OptionParser::addPositionalArgument	(	const std::string &	name,
		const std::string &	docString,
		bool	isRequired = `false`,
		const std::string &	defaultValue = `""`
	)

This member function adds a named positional argument.

The order in which positional arguments are specified is important. This is most clearly illustrated with an example:

   int argc = 4;
   char* argv = {"progname", "arg0", "arg1", "arg2"};
   OptionParser optionParser;
   optionParser.addPositionalArgument("FOO", "");
   optionParser.addPositionalArgument("BAR", "");
   optionParser.addPositionalArgument("BAZ", "");
   optionParser.parseCommandLine(argc, argv);
   // The next line returns "arg0".
   std::string firstArgument = optionParser.getValue("FOO");
   // The next line returns "arg1".
   std::string secondArgument = optionParser.getValue("BAR");
   // The next line returns "arg2".
   std::string thirdArgument = optionParser.getValue("BAZ");

Parameters:

	name	This argument specifies a unique name for the positional argument. It will be used later to refer to this argument when checking parsing results.
	docString	This argument specifies a breif description for the argument. If the automatic documentation features of the optionParser are not being used, then this argument can be safely set to "".
	isRequired	This argument specifies whether the absence of this positional argument should cause the parsing of a command line to fail. If isRequired is set to false, and this positional argument is missing from the command line, then the default value specified by argument defaultValue will be used.

Definition at line 141 of file optionParser.cpp.

template<class Type>

Type dlr::utilities::OptionParser::convertValue ( const std::string & name ) [inline]

This member function is like getValue(const std::string&), but attempts to convert the returned string to the specified type.

It works for all built-in types, and for user-defined types which define a stream input operator. If the conversion fails, and you used the OptionParser constructor which specifies an exit code, then the OptionParser will behave as if the command line parsing failed, printing usage and calling exit() as appropriate. If the conversion fails and the non-exit code constructor was used, then getValue() will throw a ConversionException.

Parameters:

name

This argument specifies the option or positional argument whose value is to be queried. If name does not match the name argument of a previous call to addOption(), addOptionWithValue(), or addPositionalArgument(), then the returned value will be the empty string.

Returns:: The return value is the value for the requested option or positional argument.

Definition at line 635 of file optionParser.h.

References getValue().

template<class Type>

Type dlr::utilities::OptionParser::convertValue	(	const std::string &	name,
		int	valueIndex
	)			`[inline]`

This member function is like getValue(const std::string&, int), but attempts to convert the returned string to the specified type.

Parameters:

	name	This argument is as described in the documentation for getValue(const std::string&, int).
	valueIndex	This argument is as described in the documentation for getValue(const std::string&, int).

Returns:: The return value is the value for the requested option or positional argument.

Definition at line 644 of file optionParser.h.

References getValue().

size_t dlr::utilities::OptionParser::getCount ( const std::string & name ) const

This member function indicates how many times the specified option or positional argument was specified in the most recently parsed command line.

For positional arguments, the return value is always 0 or 1. For options, the return value may be higher, since options may be specified more than once.

Parameters:

name

This argument is as described in the documentation for getValue(const std::string&, int).

Returns:: The return value is the value specified on the commandline for the indicated option or positional argument. If the command line did not provide that option or argument, a default value will be returned.

Definition at line 157 of file optionParser.cpp.

References DLR_THROW.

std::vector< std::string > dlr::utilities::OptionParser::getExtraPositionalArguments ( )

If constructor argument allowExtraArguments was set to true, and if number of positional arguments on the most recently parsed command line exceeds the number of named positional arguments specified using addPositionalArgument(), then this member function will return the extra positional arguments, in the order they were found on the command line, as a vector of strings.

Returns:: The return value is a vector of extra positional arguments.

Definition at line 173 of file optionParser.cpp.

std::string dlr::utilities::OptionParser::getOptionsDescription ( )

This member function returns a formatted string describing the available command line options, as specified using addOption() and addOptionWithValue().

It is useful for building your own usage messages if you used the default constructor. If you used the constructor which specifies an exit code, you probably have no use for getOptionsDescription(). The string returned by getOptionsDescription() will be much more informative if the docString arguments of the addOption() and addOptionWithValue() calls were not empty.

Returns:: The return value is a formatted string describing the configured options.

Definition at line 181 of file optionParser.cpp.

std::string dlr::utilities::OptionParser::getUsage ( )

This member function returns a formatted string suitable for a usage message.

It includes the string returned by getOptionsDescription(), so if you call getUsage(), you probably don't need to call getOptionsDescription(). If you used the constructor which specifies an exit code, you probably have no use for getUsage(). The string returned by getOptionsDescription() will be much more informative if the docString arguments of addOption(), addOptionWithValue(), and addPositionalArgument() calls were not empty.

Returns:: The return value is a formatted usage message.

Definition at line 198 of file optionParser.cpp.

References dlr::utilities::wrapString().

Referenced by parseCommandLine().

std::string dlr::utilities::OptionParser::getValue ( const std::string & name )

Following a successful parse of a command line, this member function returns the requested option value or positional argument value as a string.

If an option was specified more than once, this member function returns the value specified latest on the command line. This member function is equivalent to calling getValue<Type>(const std::string, int) with the int argument set to -1. If name does not match any specified option or positional argument, then a ValueException will be thrown.

Parameters:

name

Returns:: The return value is the value for the requested option or positional argument, or the empty string if no such value was specified on the most recently parsed command line.

Definition at line 249 of file optionParser.cpp.

Referenced by convertValue().

std::string dlr::utilities::OptionParser::getValue	(	const std::string &	name,
		int	valueIndex
	)

Following a successful parse of a command line, this member function returns the (valueIndex)th value of the requested option or positional argument.

Parameters:

	name	This argument specifies the option or positional argument whose value is to be queried. If name does not match the name argument of a previous call to addOption(), addOptionWithValue(), or addPositionalArgument(), then the returned value will be the empty string.
	valueIndex	This argument specifies which occurrence of the option/argument is being queried. If valueIndex is set to -1, than the last occurrence of the option will be returned. ValueIndex must always be less than the number returned by getCount(name), and therefore must always be 0 or -1 for positional arguments.

Returns:: The return value is the value for the requested option or positional argument, or the empty string if no such value was specified on the most recently parsed command line.

Definition at line 257 of file optionParser.cpp.

References DLR_THROW.

template<class Type>

Type dlr::utilities::OptionParser::getValue	(	const std::string &	name,
		type_tag< Type >
	)			`[inline]`

Deprecated:: {Replaced by member function convertValue().}

This deprecated member function is equivalent to convertValue<Type>(const std::string&).

Parameters:

name

This argument is as described in the documentation for getValue(const std::string&).

Returns:: The return value is the recovered argument value.

Definition at line 653 of file optionParser.h.

template<class Type>

Type dlr::utilities::OptionParser::getValue	(	const std::string &	name,
		int	valueIndex,
		type_tag< Type >
	)			`[inline]`

Deprecated:: {Replaced by member function convertValue().}

This deprecated member function is equivalent to convertValue<Type>(const std::string&, int).

Parameters:

	name	This argument is as described in the documentation for getValue(const std::string&, int).
	valueIndex	This argument is as described in the documentation for getValue(const std::string&, int).

Returns:: The return value is the recovered argument value.

Definition at line 662 of file optionParser.h.

void dlr::utilities::OptionParser::parseCommandLine	(	int	argc,
		char *	argv[]
	)

This member function should be called after all calls to addOption(), addOptionWithValue(), and addPositionalArgument() are completed in order to parse a command line and store the result for subsequent access using the getCount() and getValue() methods.

If the command line doesn't match the expected options & positional arguments, one of several things will happen, depending on which constructor & constructor arguments were used to create the OptionParser. The default behavior is to throw an IOException, but the OptionParser can also be configured to exit with a specific error code, or to print a usage message before exiting with a specific error code. If the allowMinusMinusHelp constructor argument was specified, and a "--help" option is encountered, then the OptionParser instance will print a usage message and then call exit(0).

Parameters:

	argc	This argument can be taken directly from the argc argument to main().
	argv	This argument can be taken directly from the argv argument to main().

Definition at line 316 of file optionParser.cpp.

References DLR_THROW, dlr::utilities::OptionDescription::getName(), getUsage(), and dlr::utilities::OptionDescription::requiresValue().

dlr::utilities::OptionParser Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation