plCommandLineOption Class Reference

plCommandLineOption (and derived types) are used to define options that the application supports. More...

#include <CommandLineOptions.h>

Inheritance diagram for plCommandLineOption:

Public Types
enum class	LogAvailableModes { Always , IfHelpRequested }
enum class	LogMode {   Never , FirstTime , FirstTimeIfSpecified , Always ,   AlwaysIfSpecified }
	Describes whether the value of an option (and whether something went wrong), should be printed to plLog. More...

Public Member Functions
	plCommandLineOption (plStringView sSortingGroup)
virtual void	GetSortingGroup (plStringBuilder &ref_sOut) const
	Writes the sorting group name to 'out'.
virtual void	GetOptions (plStringBuilder &ref_sOut) const =0
	Writes all the supported options (e.g. '-arg') to 'out'. If more than one option is allowed, they should be separated with semicolons or pipes.
void	GetSplitOptions (plStringBuilder &out_sAll, plDynamicArray< plStringView > &ref_splitOptions) const
	Returns the supported option names (e.g. '-arg') as split strings.
virtual void	GetParamShortDesc (plStringBuilder &ref_sOut) const =0
	Returns a very short description of the option (type). For example "<int>" or "<enum>".
virtual void	GetParamDefaultValueDesc (plStringBuilder &ref_sOut) const =0
	Returns a very short string for the options default value. For example "0" or "auto".
virtual void	GetLongDesc (plStringBuilder &ref_sOut) const =0
	Returns a proper description of the option.
virtual plStringView	GetType ()=0
	Returns a string indicating the exact implementation type.

Static Public Member Functions
static bool	IsHelpRequested (const plCommandLineUtils *pUtils=plCommandLineUtils::GetGlobalInstance())
	Checks whether a command line was passed that requests help output.
static plResult	RequireOptions (plStringView sRequiredOptions, plString *pMissingOption=nullptr, const plCommandLineUtils *pUtils=plCommandLineUtils::GetGlobalInstance())
	Checks whether all required options are passed to the command line.
static bool	LogAvailableOptions (LogAvailableModes mode, plStringView sGroupFilter={}, const plCommandLineUtils *pUtils=plCommandLineUtils::GetGlobalInstance())
	Prints all available options to the plLog.
static bool	LogAvailableOptionsToBuffer (plStringBuilder &out_sBuffer, LogAvailableModes mode, plStringView sGroupFilter={}, const plCommandLineUtils *pUtils=plCommandLineUtils::GetGlobalInstance())
	Same as LogAvailableOptions() but captures the output from plLog and returns it in an plStringBuilder.
Static Public Member Functions inherited from plNoBase
static const plRTTI *	GetStaticRTTI ()

Protected Attributes
plStringView	m_sSortingGroup
Protected Attributes inherited from plEnumerable< plCommandLineOption >
plEnumerable *	m_pNextInstance

Detailed Description

plCommandLineOption (and derived types) are used to define options that the application supports.

Command line options are created as global variables anywhere throughout the code, wherever they are needed. The point of using them over going through plCommandLineUtils directly, is that the options can be listed automatically and thus an application can print all available options, when the user requests help.

Consequently, their main purpose is to make options discoverable and to document them in a consistent manner.

Additionally, classes like plCommandLineOptionEnum add functionality that makes some options easier to setup.

Member Enumeration Documentation

LogAvailableModes

enum class plCommandLineOption::LogAvailableModes

strong

Enumerator
Always	Logs the available modes no matter what.
IfHelpRequested	Only logs the modes, if '-h', '-help', '-?' or something similar was specified.

LogMode

enum class plCommandLineOption::LogMode

strong

Describes whether the value of an option (and whether something went wrong), should be printed to plLog.

Enumerator
Never	Don't log anything.
FirstTime	Only print the information the first time a value is accessed.
FirstTimeIfSpecified	Only on first access and only if the user specified the value on the command line.
Always	Always log the options value on access.
AlwaysIfSpecified	Always log values, if the user specified non-default ones.

Constructor & Destructor Documentation

plCommandLineOption()

plCommandLineOption::plCommandLineOption ( plStringView sSortingGroup )

inline

Parameters

szSortingGroup

This string is used to sort options. Application options should start with an underscore, such that they appear first in the output.

Member Function Documentation

GetLongDesc()

virtual void plCommandLineOption::GetLongDesc ( plStringBuilder & ref_sOut ) const

pure virtual

Returns a proper description of the option.

The long description is allowed to contain newlines (
) and the output will be formatted accordingly.

Implemented in plCommandLineOptionDoc.

GetOptions()

virtual void plCommandLineOption::GetOptions ( plStringBuilder & ref_sOut ) const

pure virtual

Writes all the supported options (e.g. '-arg') to 'out'. If more than one option is allowed, they should be separated with semicolons or pipes.

Implemented in plCommandLineOptionDoc.

GetParamDefaultValueDesc()

virtual void plCommandLineOption::GetParamDefaultValueDesc ( plStringBuilder & ref_sOut ) const

pure virtual

Returns a very short string for the options default value. For example "0" or "auto".

Implemented in plCommandLineOptionDoc, plCommandLineOptionEnum, plCommandLineOptionFloat, and plCommandLineOptionInt.

GetParamShortDesc()

virtual void plCommandLineOption::GetParamShortDesc ( plStringBuilder & ref_sOut ) const

pure virtual

Returns a very short description of the option (type). For example "<int>" or "<enum>".

Implemented in plCommandLineOptionDoc, plCommandLineOptionEnum, plCommandLineOptionFloat, and plCommandLineOptionInt.

GetType()

virtual plStringView plCommandLineOption::GetType ( )

pure virtual

Returns a string indicating the exact implementation type.

Implemented in plCommandLineOptionBool, plCommandLineOptionDoc, plCommandLineOptionEnum, plCommandLineOptionFloat, plCommandLineOptionInt, plCommandLineOptionPath, and plCommandLineOptionString.

LogAvailableOptions()

bool plCommandLineOption::LogAvailableOptions ( LogAvailableModes mode, plStringView sGroupFilter = {}, const plCommandLineUtils * pUtils = plCommandLineUtils::GetGlobalInstance() )

static

Prints all available options to the plLog.

Parameters

szGroupFilter

If this is empty, all options from all 'sorting groups' are logged. If non-empty, only options from sorting groups that appear in this string will be logged.

RequireOptions()

plResult plCommandLineOption::RequireOptions ( plStringView sRequiredOptions, plString * pMissingOption = nullptr, const plCommandLineUtils * pUtils = plCommandLineUtils::GetGlobalInstance() )

static

Checks whether all required options are passed to the command line.

The options are passed as a semicolon-separated list (spare spaces are stripped away), for instance "-opt1; -opt2"

---

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

• Code/Engine/Foundation/Utilities/CommandLineOptions.h
• Code/Engine/Foundation/Utilities/Implementation/CommandLineOptions.cpp