Basic facility for processing command line flags. More...

#include <Flags.h>

Public Types
enum class	ParseStatus : uint8_t { Unknown = 0 , OK = 1 , EndOfFlags = 2 , NotRegistered = 3 , NotEnoughArgs = 4 }

Public Member Functions
	Flags (std::string fName)

	Flags (std::string fName, std::string fDescription)

	~Flags ()

bool	Register (std::string fName, FlagType fType, std::string fDescription)

bool	Register (std::string fName, bool defaultValue, std::string fDescription)

bool	Register (std::string fName, int defaultValue, std::string fDescription)

bool	Register (std::string fName, unsigned int defaultValue, std::string fDescription)

bool	Register (std::string fName, size_t defaultValue, std::string fDescription)

bool	Register (std::string fName, std::string defaultValue, std::string fDescription)

bool	Register (std::string fName, const char *defaultValue, std::string fDescription)

size_t	Size ()
	Return the number of registered flags.

Flag *	Lookup (std::string fName)

bool	ValueOf (std::string fName, FlagValue &value)
	ValueOf returns the value of the flag in the.

ParseStatus	Parse (int argc, char **argv, bool skipFirst=true)

void	Usage (std::ostream &os, int exitCode)
	Print a usage message to the output stream.

size_t	NumArgs ()

std::vector< std::string >	Args ()
	Return the arguments as a vector.

std::string	Arg (size_t index)

bool	GetBool (std::string fName, bool &flagValue)

bool	GetUnsignedInteger (std::string fName, unsigned int &flagValue)

bool	GetInteger (std::string fName, int &flagValue)

bool	GetString (std::string fName, std::string &flagValue)

bool	GetSizeT (std::string fName, std::size_t &flagValue)

Static Public Member Functions
static std::string	ParseStatusToString (ParseStatus status)

Detailed Description

Basic facility for processing command line flags.

Any remaining arguments after the args are added to the parser as arguments that can be accessed with NumArgs, Args, and Arg.

Note: The parser automatically handles the -h and –help flags by calling Usage(std::cout, 0). The user can override this flag and handle providing help on their own.

Arguments are named with their leading dash, e.g. "-f". For example,

++

flags.Register("-f", FlagType::String, "Path to a configuration file.");

scsl::FlagType::String

@ String

std::string

Usage

A short example program is below:

 ++
int
main(int argc, char *argv[])
{
    std::string  server = "service.example.com";
    unsigned int port   = 1234;
 
    auto flags = new scsl::Flags("example-client",
                     "This interacts with the example.com service.");
    flags->Register("-p", port, "server port");
    flags->Register("-s", server, "hostname to connect to");
 
    auto status = flags->Parse(argc, argv);
    if (status != ParseStatus::OK) {
        std::cerr << "failed to parse flags: "
              << scsl::Flags::ParseStatusToString(status)
              << "\n";
        exit(1);
    }
 
    auto wasSet = flags->GetString("-s", server);
    if (wasSet) {
        std::cout << "hostname override: " << server << "\n";
    }
 
    wasSet = flags->GetUnsignedInteger("-p", port);
    if (wasSet) {
        std::cout << "port override: " << port << "\n";
    }
 
    std::cout << "connecting to " << server << ":" << port << "\n";
    for (size_t i = 0; i < flags.NumArgs(); i++) {
        std::cout << "\tExecuting command " << flags.Arg(i) << "\n";
    }
    return 0;
}

Member Enumeration Documentation

◆ ParseStatus

enum class scsl::Flags::ParseStatus : uint8_t

strong

ParseStatus describes the result of parsing command-line arguments.

Enumerator
Unknown	An unknown parsing error occurred. This is a bug, and users should never see this.
OK	Parsing succeeded.
EndOfFlags	This is an internal status marking the end of command line flags.
NotRegistered	The command line flag provided isn't registered.
NotEnoughArgs	Not enough arguments were provided to a flag that takes an argument. For example, if "-p" expects a number, and the program was called with just `./program -p`, this error will be reported.

Constructor & Destructor Documentation

◆ Flags() [1/2]

scsl::Flags::Flags ( std::string fName )

Create a new flags parser for the named program.

Parameters

fName The program name,

◆ Flags() [2/2]

scsl::Flags::Flags	(	std::string	fName,
		std::string	fDescription
	)

Create a new flags parser for the named program.

Parameters

fName	The program name.
fDescription	A short description of the program.

◆ ~Flags()

scsl::Flags::~Flags ( )

Member Function Documentation

◆ Arg()

std::string scsl::Flags::Arg ( size_t index )

Return a particular argument.

Parameters

index The argument number to extract.

Returns: The argument At index i. If the index is greater than the number of arguments present, an out_of_range exception is thrown.

◆ Args()

std::vector< std::string > scsl::Flags::Args ( )

Return the arguments as a vector.

◆ GetBool()

bool scsl::Flags::GetBool	(	std::string	fName,
		bool &	flagValue
	)

Retrieve the state of a boolean flag.

Parameters

fName	The flag to look up.
flagValue	The value to store.

Returns: True if the value was set, or false if the value isn't a boolean or if it wasn't set.

◆ GetInteger()

bool scsl::Flags::GetInteger	(	std::string	fName,
		int &	flagValue
	)

Retrieve the value of an integer flag.

Parameters

fName	The flag to look up.
flagValue	The value to store.

Returns: True if the value was set, or false if the value isn't an integer or if it wasn't set.

◆ GetSizeT()

bool scsl::Flags::GetSizeT	(	std::string	fName,
		std::size_t &	flagValue
	)

Retrieve the value of a size_t flag.

Parameters

fName	The flag to look up.
flagValue	The value to store.

Returns: True if the value was set, or false if the value isn't a size_t or if it wasn't set.

◆ GetString()

bool scsl::Flags::GetString	(	std::string	fName,
		std::string &	flagValue
	)

Retrieve the value of a string flag.

Parameters

fName	The flag to look up.
flagValue	The value to store.

Returns: True if the value was set, or false if the value isn't a string or if it wasn't set.

◆ GetUnsignedInteger()

bool scsl::Flags::GetUnsignedInteger	(	std::string	fName,
		unsigned int &	flagValue
	)

Retrieve the value of an unsigned integer flag.

Parameters

fName	The flag to look up.
flagValue	The value to store.

Returns: True if the value was set, or false if the value isn't an unsigned integer or if it wasn't set.

◆ Lookup()

Flag * scsl::Flags::Lookup ( std::string fName )

Lookup a flag.

Parameters

fName The flag name.

Returns: A pointer to flag if registered, or nullptr if the flag wasn't registered.

◆ NumArgs()

size_t scsl::Flags::NumArgs ( )

Return the number of arguments processed. These are any remaining elements in argv that are not flags.

◆ Parse()

ParseStatus scsl::Flags::Parse	(	int	argc,
		char **	argv,
		bool	skipFirst = `true`
	)

Process a list of arguments into flags.

Parameters

argc	The number of arguments.
argv	The arguments passed to the program.
skipFirst	Flags expects to receive arguments directly from those passed to `main`, and defaults to skipping the first argument. Set to false if this is not the case.

Returns

◆ ParseStatusToString()

static std::string scsl::Flags::ParseStatusToString ( ParseStatus status )

static

ParseStatusToString returns a string message describing the result of parsing command line args.

◆ Register() [1/7]

bool scsl::Flags::Register	(	std::string	fName,
		bool	defaultValue,
		std::string	fDescription
	)

Register a new boolean command line flag with a default value.

Note: For booleans, it only makes sense to pass a false default value, as there is no way to set a boolean flag to false. This form is provided for compatibility with the other variants on this method.

Parameters

fName	The name of the flag, including a leading dash.
defaultValue	The default value for the flag.
fDescription	A short description of the flag.

Returns: True if the flag was registered, false if the flag could not be registered (e.g. a duplicate flag was registered).

◆ Register() [2/7]

bool scsl::Flags::Register	(	std::string	fName,
		const char *	defaultValue,
		std::string	fDescription
	)

Register a new string command line flag with a default value.

Parameters

fName	The name of the flag, including a leading dash.
defaultValue	The default value for the flag.
fDescription	A short description of the flag.

Returns: True if the flag was registered, false if the flag could not be registered (e.g. a duplicate flag was registered).

◆ Register() [3/7]

bool scsl::Flags::Register	(	std::string	fName,
		FlagType	fType,
		std::string	fDescription
	)

Register a new command line flag.

Parameters

fName	The name of the flag, including a leading dash.
fType	The type of the argument to parse.
fDescription	A description of the flag.

Returns: True if the flag was registered, false if the flag could not be registered (e.g. a duplicate flag was registered).

◆ Register() [4/7]

bool scsl::Flags::Register	(	std::string	fName,
		int	defaultValue,
		std::string	fDescription
	)

Register a new integer command line flag with a default value.

Parameters

fName	The name of the flag, including a leading dash.
defaultValue	The default value for the flag.
fDescription	A short description of the flag.

Returns: True if the flag was registered, false if the flag could not be registered (e.g. a duplicate flag was registered).

◆ Register() [5/7]

bool scsl::Flags::Register	(	std::string	fName,
		size_t	defaultValue,
		std::string	fDescription
	)

Register a new size_t command line flag with a default value.

Parameters

fName	The name of the flag, including a leading dash.
defaultValue	The default value for the flag.
fDescription	A short description of the flag.

Returns: True if the flag was registered, false if the flag could not be registered (e.g. a duplicate flag was registered).

◆ Register() [6/7]

bool scsl::Flags::Register	(	std::string	fName,
		std::string	defaultValue,
		std::string	fDescription
	)

Register a new string command line flag with a default value.

Parameters

fName	The name of the flag, including a leading dash.
defaultValue	The default value for the flag.
fDescription	A short description of the flag.

Returns: True if the flag was registered, false if the flag could not be registered (e.g. a duplicate flag was registered).

◆ Register() [7/7]

bool scsl::Flags::Register	(	std::string	fName,
		unsigned int	defaultValue,
		std::string	fDescription
	)

Register a new unsigned integer command line flag with a default value.

Parameters

fName	The name of the flag, including a leading dash.
defaultValue	The default value for the flag.
fDescription	A short description of the flag.

Returns: True if the flag was registered, false if the flag could not be registered (e.g. a duplicate flag was registered).

◆ Size()

size_t scsl::Flags::Size ( )

Return the number of registered flags.

◆ Usage()

void scsl::Flags::Usage	(	std::ostream &	os,
		int	exitCode
	)

Print a usage message to the output stream.

◆ ValueOf()

bool scsl::Flags::ValueOf	(	std::string	fName,
		FlagValue &	value
	)

ValueOf returns the value of the flag in the.

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

include/scsl/Flags.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Usage

Member Enumeration Documentation

◆ ParseStatus

Constructor & Destructor Documentation

◆ Flags() [1/2]

◆ Flags() [2/2]

◆ ~Flags()

Member Function Documentation

◆ Arg()

◆ Args()

◆ GetBool()

◆ GetInteger()

◆ GetSizeT()

◆ GetString()

◆ GetUnsignedInteger()

◆ Lookup()

◆ NumArgs()

◆ Parse()

◆ ParseStatusToString()

◆ Register() [1/7]

◆ Register() [2/7]

◆ Register() [3/7]

◆ Register() [4/7]

◆ Register() [5/7]

◆ Register() [6/7]

◆ Register() [7/7]

◆ Size()

◆ Usage()

◆ ValueOf()