CmdLine::Parser Class Reference

Parses command line arguments. More...

#include <Parser.h>

Classes
class	DuplicateOption
	An exception thrown for adding a duplicate Option. More...
class	DuplicatePosParam
	An exception thrown for adding duplicate PosParam. More...
class	EmptyArguments
	An exception thrown for a Parser with empty arguments. More...
class	NullParameter
	An exception thrown for adding null Parameter. More...

Public Types
enum class	Status { Success , Failure }
	Determines the status of the Parser. More...

Public Member Functions
	Parser (ProgParam *p, std::vector< std::string > args)
	Constructs a new Parser.
Status	Parse ()
	Parses the command line arguments.
std::string	GenerateUsage () const
	Generates program usage info.
std::string	GenerateHelp () const
	Generates program help info.
bool	BuiltInHelpOptionIsSpecified () const
	Determines if the built-in help Option has been specified.
void	Add (Option *o)
	Adds an Option to the Parser.
void	Add (PosParam *p)
	Adds a PosParam to the Parser.
void	Set (MultiPosParam *p)
	Sets a MultiPosParam on the Parser.
void	Set (Option::Style s)
	Sets the Option::Style on all options added to the Parser.
bool	AllMandatoryParamsSpecified ()
	Checks that all mandatory Param were specified.

Detailed Description

Parses command line arguments.

The command line Parser populates command line parameters (Param) from command line arguments. A Parser is created from a ProgParam and a vector containing a list of command line arguments. Prior to parsing the arguments, the program must add command line parameters (Param) to the Parser so it can populate them. Such parameters include Options (both Option and ValueOption) and positional parameters (PosParam). The parser also allows zero or one multi-positional parameters (MultiPosParam) to be set (positional parameters that accept multiple positional arguments). Finally, the Parser can generate command line usage and help information for the program based on each Param added to the Parser.

Member Enumeration Documentation

Status

enum class CmdLine::Parser::Status

strong

Determines the status of the Parser.

Enumerator
Success	Indicates parsing was successful. When parsing is successful, the program is free to examine the values that were stored in each command line Param as a result of parsing the command line arguments. Such values serve as input to the program from the command line.
Failure	Indicates parsing failed. When parsing failes, it is usually as a result of invalid command line arguments being passed to the program (i.e. a mandatory Param was not specified, etc.). In such cases, the program should output usage information.

Constructor & Destructor Documentation

Parser()

CmdLine::Parser::Parser	(	ProgParam *	p,
		std::vector< std::string >	args )

Constructs a new Parser.

Parameters

p	The ProgParam to populate with the program name.
args	The command line arguments to parse.

Invariant

There is at least one argument (program name).

Option, PosParam, and ProgParam are not null.

Cannot add a duplicate Option or PosParam.

There can only be zero or one MultiPosParam.

There must be exactly one ProgParam.

Exceptions

NullParamter	The parameter is null.
EmptyArguments	The arguments were empty.

Member Function Documentation

Add() [1/2]

void CmdLine::Parser::Add

(

Option *

o

)

Adds an Option to the Parser.

Adds an Option pointer to the Parser so that the Parser can populate the Option if the user specifies it at the command line. This method will also accept pointers of the derived class ValueOption.

Parameters

o	The Option pointer to add to the Parser.

Precondition

The Option pointer must not be null.

The Option must not be a duplicate.

Postcondition

The Option is added to the Parser.

Exceptions

DuplicateOption

Tried to add a duplicate Option.

Add() [2/2]

void CmdLine::Parser::Add

(

PosParam *

p

)

Adds a PosParam to the Parser.

Adds a PosParam pointer to the Parser so that the Parser can populate the PosParam if the user specifies it at the command line.

Parameters

p	The PosParam pointer to add to the Parser.

Precondition

The PosParam pointer must not be null.

The PosParam must not be a duplicate.

Postcondition

The PosParam is added to the Parser.

Exceptions

DuplicatePosParam

Tried to add duplicate PosParam.

AllMandatoryParamsSpecified()

bool CmdLine::Parser::AllMandatoryParamsSpecified

(

)

Checks that all mandatory Param were specified.

Returns

True if all are specified, otherwise false.

BuiltInHelpOptionIsSpecified()

bool CmdLine::Parser::BuiltInHelpOptionIsSpecified ( ) const

inline

Determines if the built-in help Option has been specified.

Since the built-in help Option is not defined outside of the parser, use this method to determine if it has been specified.

Returns

True if it has been specified, otherwise false.

GenerateHelp()

std::string CmdLine::Parser::GenerateHelp

(

)

const

Generates program help info.

Generates program help info from each command line Param (ProgParam, Option, ValueOption, PosParam, and MultiPosParam) that has been added or set on the Parser. Help info is the detailed help information that programs typically show when a help option (-h, –help, -?, /h, /help, etc.) is specified.

Returns

The program help information.

GenerateUsage()

std::string CmdLine::Parser::GenerateUsage

(

)

const

Generates program usage info.

Generates program usage info from each command line Param (ProgParam, Option, ValueOption, PosParam, and MultiPosParam) that has been added or set on the Parser. Usage information is typically shown when the user supplies invalid command line arguments, or no arguments, to the program.

Returns

The program usage information.

Parse()

Status CmdLine::Parser::Parse

(

)

Parses the command line arguments.

Parsing the command line arguments will populate any command line Param (ProgParam, Option, ValueOption, PosParam, and MultiPosParam) that have been added or set on the Parser and that could be populated by one of the arguments.

Returns

Success upon successful parsing, otherwise failure.

Set() [1/2]

void CmdLine::Parser::Set ( MultiPosParam * p )

inline

Sets a MultiPosParam on the Parser.

A Parser can only have zero or one MultiPosParam at a time. By default, the Parser has no MultiPosParams unless a pointer to one is set. If the pointer is null, the Parser does not process the MultiPosParam.

Parameters

p	The pointer to the MultiPosParam to set on the Parser.

Postcondition

Parser MultiPosParam is either set or cleared (nulltpr).

Set() [2/2]

void CmdLine::Parser::Set

(

Option::Style

s

)

Sets the Option::Style on all options added to the Parser.

An Option usually has its Style set during creation in its Option::Definition. However, it may be more convenient / less error prone to set the Option::Style for all options after they have been added to the Parser for the sake of consistency. That is the purpose of this method.

Parameters

s	The Option::Style to set on each Option.

Precondition

All Options must already be added to the Parser

Postcondition

All Options have their Option::Style changed.

---

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

• LibCppCmdLine/Parser.h