Argument class for ArConfig. More...

#include <ArConfigArg.h>

Public Types
enum	{ DEFAULT_DOUBLE_PRECISION = 5, TYPE_COUNT = LAST_TYPE + 1, RESTART_LEVEL_COUNT = LAST_RESTART_LEVEL + 1 }

enum	{ MAX_RESOURCE_ARG_TEXT_LENGTH = 1024 }

enum	ResourceIndices { RESOURCE_INDEX_OF_SECTION_NAME = 0, RESOURCE_INDEX_OF_ARG_NAME = 1, RESOURCE_INDEX_OF_TYPE = 2, RESOURCE_INDEX_OF_PRIORITY = 3, RESOURCE_INDEX_OF_RESTART_LEVEL = 4, RESOURCE_INDEX_OF_PARENT_PATH = 5, RESOURCE_INDEX_OF_DESCRIPTION = 6, RESOURCE_INDEX_OF_EXTRA = 7, RESOURCE_INDEX_OF_DISPLAY = 8, RESOURCE_INDEX_OF_NEW = 9 }

enum	RestartLevel { NO_RESTART, RESTART_CLIENT, RESTART_IO, RESTART_SOFTWARE, RESTART_HARDWARE, LAST_RESTART_LEVEL = RESTART_HARDWARE }
	Indicates the components that must be restarted if the parameter is changed.

enum	Type { INVALID, INT, DOUBLE, STRING, BOOL, FUNCTOR, DESCRIPTION_HOLDER, STRING_HOLDER, SEPARATOR, CPPSTRING, LIST, LIST_HOLDER, LAST_TYPE = LIST_HOLDER }

Public Member Functions
bool	addArg (const ArConfigArg &arg)
	Adds a child arg to this arg. Valid only for LIST type; otherwise returns false. More...

bool	addToFileParser (ArFileParser parser, ArRetFunctor3C< bool, ArConfig, ArArgumentBuilder , char , size_t > parserCB, const char *logPrefix="", bool isQuiet=false) const
	Adds given parserCB handler for the appropriate keyword(s) to the given file parser. More...

	ArConfigArg ()
	Default empty contructor.

	ArConfigArg (const char name, int pointer, const char *description="", int minInt=INT_MIN, int maxInt=INT_MAX)
	Constructor for making an integer argument by pointer (4 bytes) More...

	ArConfigArg (const char name, short pointer, const char *description="", int minInt=SHRT_MIN, int maxInt=SHRT_MAX)
	Constructor for making an int argument thats a short (2 bytes) More...

	ArConfigArg (const char name, unsigned short pointer, const char *description="", int minInt=0, int maxInt=USHRT_MAX)
	Constructor for making an int argument thats a ushort (2 bytes) More...

	ArConfigArg (const char name, unsigned char pointer, const char *description="", int minInt=0, int maxInt=255)
	Constructor for making an char (1 byte) argument by pointer (treated as int) More...

	ArConfigArg (const char name, double pointer, const char *description="", double minDouble=-HUGE_VAL, double maxDouble=HUGE_VAL, int precision=DEFAULT_DOUBLE_PRECISION)
	Constructor for making a double argument by pointer. More...

	ArConfigArg (const char name, bool pointer, const char *description="")
	Constructor for making a boolean argument by pointer. More...

	ArConfigArg (const char name, char str, const char *description, size_t maxStrLen)
	Constructor for making an argument of a string by pointer (see details) More...

	ArConfigArg (const char name, const char str, const char *description)
	Constructor for making an argument of a string by pointer (see details) More...

	ArConfigArg (const char name, std::string str, const char *description)
	Constructor for making an argument of a C++ std::string. More...

	ArConfigArg (const char name, int val, const char description="", int minInt=INT_MIN, int maxInt=INT_MAX)
	Constructor for making an integer argument. More...

	ArConfigArg (const char name, double val, const char description="", double minDouble=-HUGE_VAL, double maxDouble=HUGE_VAL, int precision=DEFAULT_DOUBLE_PRECISION)
	Constructor for making a double argument. More...

	ArConfigArg (const char name, bool val, const char description="")
	Constructor for making a boolean argument. More...

	ArConfigArg (const char name, ArRetFunctor1< bool, ArArgumentBuilder > setFunctor, ArRetFunctor< const std::list< ArArgumentBuilder > > getFunctor, const char *description)
	Constructor for making an argument that has functors to handle things. More...

	ArConfigArg (const char *str, Type type=DESCRIPTION_HOLDER)
	Constructor for just holding a description (for ArConfig)

	ArConfigArg (const char name, const char str)
	Constructor for holding an unknown argument (STRING_HOLDER) More...

	ArConfigArg (Type type, const char name, const char description)
	Constructs a new named argument of the specified type. More...

	ArConfigArg (Type type)
	Constructs a new argument of the specified type. More...

	ArConfigArg (const char *argName, const ArConfigArg &arg)
	Copy constructor that allows a new name to be assigned.

	ArConfigArg (const ArConfigArg &arg)
	Copy constructor.

void	clearValueSet (void)
	Tells the configArg that the value hasn't been set.

void	copyAndDetach (const ArConfigArg &arg)
	Copies the given arg to this one, detaching any pointers so they are not shared.

bool	copyTranslation (const ArConfigArg &arg)
	Copies the translation data from given arg to this one. More...

const ArConfigArg *	findArg (const char *childParamName) const
	Finds the specified child arg. Valid only for LIST type; otherwise returns NULL. More...

ArConfigArg *	findArg (const char *childParamName)
	Finds the specified child arg. Valid only for LIST type; otherwise returns NULL. More...

const ArConfigArg *	getArg (size_t index) const
	Returns the child arg at the specified index (between 0 and getArgCount()). More...

ArConfigArg *	getArg (size_t index)
	Returns the child arg at the specified index (between 0 and getArgCount()).

size_t	getArgCount () const
	Returns the number of child args. Valid only for LIST type; otherwise returns 0. More...

std::list< ArConfigArg >	getArgs (bool *ok=NULL) const
	Returns a list of all child args in this arg. Valid only for LIST type; otherwise returns an empty list. More...

const std::list< ArArgumentBuilder * > *	getArgsWithFunctor (bool *ok=NULL) const
	Gets the argument value, which is a list of argumentbuilders here.

bool	getBool (bool *ok=NULL) const
	Gets the argument value, for bool arguments.

ArPriority::Priority	getConfigPriority (void) const
	Gets the priority (only used by ArConfig) More...

std::string	getCppString (bool *ok=NULL) const
	Get a copy of the value of the target std::string. More...

const std::string *	getCppStringPtr (bool *ok=NULL) const
	Get the internal pointer to the target std::string. More...

const char *	getDescription (void) const
	Gets the brief description of the argument. More...

const char *	getDisplayHint () const
	Returns the display hint for this arg, or NULL if none is defined.

double	getDouble (bool *ok=NULL) const
	Gets the argument value, for double arguments.

int	getDoublePrecision (bool *ok=NULL) const
	Gets the decimal precision of the double.

const char *	getExtraExplanation () const
	Returns the extra explanation, if any, for this argument.

int	getInt (bool *ok=NULL) const
	Gets the argument value, for int arguments.

double	getMaxDouble (bool *ok=NULL) const
	Gets the maximum double value. More...

int	getMaxInt (bool *ok=NULL) const
	Gets the maximum int value. More...

double	getMinDouble (bool *ok=NULL) const
	Gets the minimum double value. More...

int	getMinInt (bool *ok=NULL) const
	Gets the minimum int value. More...

const char *	getName (void) const
	Gets the name of the argument. More...

ArConfigArg *	getParentArg () const
	Returns a pointer to the immediate parent arg. If this is not a child ArConfigArg, then returns NULL. More...

std::string	getParentPathName (char separator='\|') const
	If getParentArg() is not null, then returns the path to the top level, as a single string.

RestartLevel	getRestartLevel () const
	Gets the restart level of this parameter (only used by ArConfig)

const char *	getString (bool *ok=NULL) const
	Gets the argument value, for string (and string holder) arguments.

bool	getSupressChanges (void) const
	Gets if notifications of changes are supressed (for the central server config)

ArConfigArg::Type	getType (void) const
	Gets the type of the argument. More...

bool	hasArgs () const
	Returns whether the list contains child args. Valid only for LIST type; otherwise returns false. More...

bool	hasExternalDataReference () const
	Returns true if this arg points to a member of another object, false if arg is self-contained.

bool	hasMaxBound () const
	Returns whether the arg has a maximum value, currently applicable to INTs and DOUBLEs.

bool	hasMinBound () const
	Returns whether the arg has a minimum value, currently applicable to INTs and DOUBLEs.

bool	isTranslated () const
	Returns whether the arg has been translated by a resource file.

bool	isValueEqual (const ArConfigArg &other) const
	Checks only the name, type, and value attributes and returns whether they are equal.

bool	isValueSet (void)
	Gets whether this value has been set since it was last cleared or not.

void	log (bool verbose=false, int indentCount=1, const char *logPrefix="") const
	Logs the type, name, and value of this argument.

ArConfigArg &	operator= (const ArConfigArg &arg)
	Assignment operator.

bool	parseArgument (ArArgumentBuilder arg, char errorBuffer, size_t errorBufferLen, const char logPrefix="", bool isQuiet=false, bool changed=NULL)
	Sets the value of this arg to the data described in the given ArArgumentBuilder.

bool	parseResource (ArArgumentBuilder arg, char errorBuffer, size_t errorBufferLen, const char *logPrefix="", bool isQuiet=false)
	Sets the value of this arg to the resource data described in the given ArArgumentBuilder.

void	replaceSpacesInName (void)
	Replaces spaces in the name with underscores.

bool	setArgWithFunctor (ArArgumentBuilder argument, char errorBuffer=NULL, size_t errorBufferLen=0, bool doNotSet=false)
	Sets the argument by calling the setFunctor callback.

bool	setBool (bool val, char *errorBuffer=NULL, size_t errorBufferLen=0, bool doNotSet=false)
	Sets the argument value, for bool arguments.

void	setConfigPriority (ArPriority::Priority priority)
	Sets the priority (only used by ArConfig) More...

bool	setCppString (const std::string &str, char *errorBuffer=NULL, size_t errorBufferLen=0, bool doNotSet=false)

void	setDescription (const char *description)
	Sets the description (normally given in the constructor)

void	setDisplayHint (const char *hintText)
	Sets the display hint for this arg. More...

bool	setDouble (double val, char *errorBuffer=NULL, size_t errorBufferLen=0, bool doNotSet=false)
	Sets the argument value, for double arguments.

void	setExtraExplanation (const char *extraExplanation)
	For arguments that require more than a brief description, set the extra explanation.

void	setIgnoreBounds (bool ignoreBounds=false)
	Sets whether to ignore bounds or not (default is to not to) More...

bool	setInt (int val, char *errorBuffer=NULL, size_t errorBufferLen=0, bool doNotSet=false)
	Sets the argument value, for int arguments.

void	setRestartLevel (RestartLevel level)
	Sets the restart level of this parameter (only used by ArConfig)

bool	setString (const char str, char errorBuffer=NULL, size_t errorBufferLen=0, bool doNotSet=false)
	Sets the argument value for string arguments. More...

bool	setString (const std::string &str, char *errorBuffer=NULL, size_t errorBufferLen=0, bool doNotSet=false)
	Sets the argument value for string arguments. The value of str is copied to the target string.

void	setSupressChanges (bool supressChanges)
	Sets if notifications of changes are supressed (for the central server config)

void	setTranslated (bool b)
	Sets whether the arg has been translated by a resource file.

bool	setValue (const ArConfigArg &source, bool isVerifyArgNames=false)
	If the given source is of the same type, copies its value to this arg. More...

void	setValueSet (void)
	For special arg types (such as LIST), sets the flag to indicate the value was set.

bool	writeArguments (FILE file, char lineBuf, int lineBufSize, int startCommentColumn, bool isWriteExtra=false, const char *logPrefix="", int indentLevel=0) const
	Writes this arg to the given file, in a format suitable for reading by parseArgument. More...

bool	writeBounds (char line, size_t lineLen, const char logPrefix="") const
	Writes the min/max values of this arg to the given buffer, as applicable. More...

bool	writeName (char *lineBuf, int lineBufSize, int indentLevel) const
	Writes the name of this arg to the given buffer, indenting as specified. More...

bool	writeResource (FILE file, char lineBuf, int lineBufSize, char separatorChar, const char sectionName, const char logPrefix="") const
	Writes this arg to the given file, in a format suitable for reading by parseResource.

virtual	~ArConfigArg ()
	Destructor.

Static Public Member Functions
static bool	isResourceTopLevel (ArArgumentBuilder arg, const char logPrefix="")
	Returns true if the given resource arg is "top-level", i.e. not a list member.

static std::string	parseResourceArgName (ArArgumentBuilder arg, const char logPrefix="")
	Returns the param name contained in the given resource arg.

static bool	parseResourceArgText (const char argText, char bufOut, size_t bufLen)
	Parses the text obtained from the resource arg, strips surrounding quotes, blanks, and funny chars.

static std::string	parseResourceDescription (ArArgumentBuilder arg, const char logPrefix="")
	Returns the description contained in the given resource arg.

static std::string	parseResourceExtra (ArArgumentBuilder arg, const char logPrefix="")
	Returns the extra explanation contained in the given resource arg.

static std::list< std::string >	parseResourceParentPath (ArArgumentBuilder arg, char separator='\|', const char logPrefix="")
	Returns the parent path contained in the resource arg for list members.

static std::string	parseResourceSectionName (ArArgumentBuilder arg, const char logPrefix="")
	Returns the section name contained in the given resource arg.

static Type	parseResourceType (ArArgumentBuilder arg, const char logPrefix="")
	Returns the arg type contained in the given resource arg.

static RestartLevel	restartLevelFromString (const char *text)
	Given a text representation, returns the appropriate RestartLevel.

static std::list< std::string >	splitParentPathName (const char *parentPathName, char separator='\|')
	Given a parent path, as a single string, splits it in a format useable by ArConfigSection findParam.

static const char *	toString (Type t)
	Returns a text representation of the given type, suitable for logging.

static const char *	toString (RestartLevel r)
	Returns a text representation of the given RestartLevel, suitable for logging.

static Type	typeFromString (const char *text)
	Given a text representation, returns the appropriate Type.

static int	writeResourceHeader (FILE file, char lineBuf, int lineBufSize, char separatorChar, const char sectionTitle, const char logPrefix="")
	Writes column labels and edit info to the given resource file, returns number of lines written.

static int	writeResourceSectionHeader (FILE file, char lineBuf, int lineBufSize, char separatorChar, const char sectionName, const char sectionDesc, const char sectionExtra, const char sectionDisplayName, bool isTranslated, const char *logPrefix="")
	Writes the section description to the resource file.

Static Public Attributes
static const char *	LIST_BEGIN_TAG = "_beginList"
	Keyword that indicates the start of an ArConfigArg LIST object, for ArFileParser.

static const char *	LIST_END_TAG = "_endList"
	Keyword that indicates the end of an ArConfigArg LIST object, for ArFileParser.

static const char *	NEW_RESOURCE_TAG = "xltrNew"
	Resource file keyword that indicates a new entry.

static const char *	NULL_TAG = "NULL"
	Resource file keyword that indicates an empty string (cannot write empty for csv).

Static Protected Member Functions
static bool	writeMultiLineComment (const char comment, FILE file, char lineBuf, int lineBufSize, const char startComment)
	Writes the given comment to the specified file, spanning multiple lines as necessary. More...

Friends
class	ArConfig

Detailed Description

Argument class for ArConfig.

ArConfigArg stores information about a parameter (name, description, type), and a pointer to the variable that will actually store the value. This variable is normally stored and used by whatever class or module has added the parameter to ArConfig. (In addition, there are some special types of ArConfigArg that behave differently such as the "holder" types and separator, these are used internally or in special cases.)

Which constructor you use determines the value type of the ArConfigArg object.

A typical idiom for creating ArConfigArg objects and adding them to ArConfig is to create a temporary ArConfigArg in the call to ArConfig::addParam():

config->addParam(ArConfigArg("MyParameter", &myTarget, "Example Parameter"), "Example Section");

Where config is a pointer to an ArConfig object or subclass, and myTarget is a variable (e.g. int) that is a class member whose instance will not be destroyed before the end of the program, or which will remove the parameter from ArConfig before being destroyed (the pointer to myTarget that is stored in ArConfig must not become invalid.) The ArConfigArg object passed to addParam() will be copied and stored in ArConfig.

Java and Python Wrappers: Swig cannot determine the correct constructor to use based on most target langugages types, so you must use subclasses defined for various types. Or, use the constructor that accepts functors for dealing with arguments. Also, Swig cannot use pointers to change variables, so you must create ArConfigArg objects, passing in default values, and retain references to those objects, in addition to passing them to ArConfig, and read new values from those objects if ArConfig changes; or pass functors to ArConfigArg instead of the initial value.

Examples:: configExample.cpp.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Enumerator
DEFAULT_DOUBLE_PRECISION	Default double precision, originates from previous saving behavior.
TYPE_COUNT	Number of argument types.
RESTART_LEVEL_COUNT	Number of restart levels.

◆ Type

enum ArConfigArg::Type

Enumerator
INVALID	An invalid argument, the argument wasn't created correctly.
INT	Integer argument.
DOUBLE	Double argument.
STRING	String argument.
BOOL	Boolean argument.
FUNCTOR	Argument that handles things with functors.
DESCRIPTION_HOLDER	Argument that just holds a description.
STRING_HOLDER	this one is for holding strings and reading them in and writing them out but not really letting them get sent anywhere (its for unknown config parameters (so they don't get lost if a feature is turned off)
SEPARATOR	Empty argument that merely acts as a separator within a (large) section.
CPPSTRING	Pointer to std::string, use like STRING.
LIST	Composite argument that contains an ordered list of other args.
LIST_HOLDER	Placeholder for composite argument that are not currently active.
LAST_TYPE	Last value in the enumeration.

Constructor & Destructor Documentation

◆ ArConfigArg() [1/16]

ArConfigArg::ArConfigArg	(	const char *	name,
		int *	pointer,
		const char *	description = `""`,
		int	minInt = `INT_MIN`,
		int	maxInt = `INT_MAX`
	)

Constructor for making an integer argument by pointer (4 bytes)

Java and Python Wrappers: Not available in Java or Python wrapper libraries.

◆ ArConfigArg() [2/16]

ArConfigArg::ArConfigArg	(	const char *	name,
		short *	pointer,
		const char *	description = `""`,
		int	minInt = `SHRT_MIN`,
		int	maxInt = `SHRT_MAX`
	)

Constructor for making an int argument thats a short (2 bytes)

Java and Python Wrappers: Not available in Java or Python wrapper libraries.

◆ ArConfigArg() [3/16]

ArConfigArg::ArConfigArg	(	const char *	name,
		unsigned short *	pointer,
		const char *	description = `""`,
		int	minInt = `0`,
		int	maxInt = `USHRT_MAX`
	)

Constructor for making an int argument thats a ushort (2 bytes)

Java and Python Wrappers: Not available in Java or Python wrapper libraries.

◆ ArConfigArg() [4/16]

ArConfigArg::ArConfigArg	(	const char *	name,
		unsigned char *	pointer,
		const char *	description = `""`,
		int	minInt = `0`,
		int	maxInt = `255`
	)

Constructor for making an char (1 byte) argument by pointer (treated as int)

Java and Python Wrappers: Not available in Java or Python wrapper libraries.

◆ ArConfigArg() [5/16]

ArConfigArg::ArConfigArg	(	const char *	name,
		double *	pointer,
		const char *	description = `""`,
		double	minDouble = `-HUGE_VAL`,
		double	maxDouble = `HUGE_VAL`,
		int	precision = `DEFAULT_DOUBLE_PRECISION`
	)

Constructor for making a double argument by pointer.

Java and Python Wrappers: Not available in Java or Python wrapper libraries.

◆ ArConfigArg() [6/16]

ArConfigArg::ArConfigArg	(	const char *	name,
		bool *	pointer,
		const char *	description = `""`
	)

Constructor for making a boolean argument by pointer.

Java and Python Wrappers: Not available in Java or Python wrapper libraries.

◆ ArConfigArg() [7/16]

ArConfigArg::ArConfigArg	(	const char *	name,
		char *	str,
		const char *	description,
		size_t	maxStrLen
	)

Constructor for making an argument of a string by pointer (see details)

This constructor can accept both an already-allocated string, or ArConfigArg can to the memory managment itself (reallocation and finally deletion).

If maxStrLen is 0, then ArConfigArg will do its own memory management, with the contents of str copied as the initial value of the internally held string. Otherwise, str must point to an allocated string, with its size given by maxStrLen.

Warning: The parameter name and value must not contain any characters with special meaning when saved and loaded from a config file, such as '#', ';', tab, or newline.

Java and Python Wrappers: Not available in Java or Python wrapper libraries. Use ArConfigArg_String subclass instead (which has no maxStrLen parameter in its constructor)

◆ ArConfigArg() [8/16]

ArConfigArg::ArConfigArg	(	const char *	name,
		const char *	str,
		const char *	description
	)

Constructor for making an argument of a string by pointer (see details)

This constructor can accept a const char str, then it'll take care of the string itself...

Warning: The parameter name and value must not contain any characters with special meaning when saved and loaded from a config file, such as '#', ';', tab, or newline.

Java and Python Wrappers: Not available in Java or Python wrapper libraries. Use ArConfigArg_String subclass instead (which has no maxStrLen parameter in its constructor)

◆ ArConfigArg() [9/16]

ArConfigArg::ArConfigArg	(	const char *	name,
		std::string *	strptr,
		const char *	description
	)

Constructor for making an argument of a C++ std::string.

Java and Python Wrappers: Not available in Java or Python wrapper libraries.

◆ ArConfigArg() [10/16]

ArConfigArg::ArConfigArg	(	const char *	name,
		int	val,
		const char *	description = `""`,
		int	minInt = `INT_MIN`,
		int	maxInt = `INT_MAX`
	)

Constructor for making an integer argument.

Java and Python Wrappers: Not available in Java or Python wrapper libraries. Use ArConfigArg_Int subclass instead.

◆ ArConfigArg() [11/16]

ArConfigArg::ArConfigArg	(	const char *	name,
		double	val,
		const char *	description = `""`,
		double	minDouble = `-HUGE_VAL`,
		double	maxDouble = `HUGE_VAL`,
		int	precision = `DEFAULT_DOUBLE_PRECISION`
	)

Constructor for making a double argument.

Java and Python Wrappers: Not available in Java or Python wrapper libraries. Use ArConfigArg_Double subclass instead.

◆ ArConfigArg() [12/16]

ArConfigArg::ArConfigArg	(	const char *	name,
		bool	val,
		const char *	description = `""`
	)

Constructor for making a boolean argument.

Java and Python Wrappers: Not available in Java or Python wrapper libraries. Use ArConfigArg_Bool subclass instead.

◆ ArConfigArg() [13/16]

ArConfigArg::ArConfigArg	(	const char *	name,
		ArRetFunctor1< bool, ArArgumentBuilder >	setFunctor,
		ArRetFunctor< const std::list< ArArgumentBuilder > > *	getFunctor,
		const char *	description
	)

Constructor for making an argument that has functors to handle things.

This constructor is for the functor type of argument, this is for cases that need to be complicated and have more than one argument per name...

such as the sonar in a config file. Where this data needs to be used to construct internal data structures.

Parameters

name	Name of this argument
description	Description of the purpose of this argument
setFunctor	When an argument is read it is passed to this functor in an ArArgumentBuilder object. The functor should return false if there is an error or problem handling the argument, or true otherwise.
getFunctor	Since configuration needs to be serialized to save files on disk or send data over the network etc., this functor will be called to get a list of strings to represent this argument and its value as text in the file etc.

Warning: The parameter name and value must not contain any characters with special meaning when saved and loaded from a config file, such as '#', ';', tab, or newline.

◆ ArConfigArg() [14/16]

ArConfigArg::ArConfigArg	(	const char *	name,
		const char *	str
	)

Constructor for holding an unknown argument (STRING_HOLDER)

Warning: The parameter name and value must not contain any characters with special meaning when saved and loaded from a config file, such as '#', ';', tab, or newline.

◆ ArConfigArg() [15/16]

ArConfigArg::ArConfigArg	(	Type	type,
		const char *	name,
		const char *	description
	)

Constructs a new named argument of the specified type.

This constructor is used for creating composite (LIST or LIST_HOLDER type) parameters.

◆ ArConfigArg() [16/16]

ArConfigArg::ArConfigArg ( Type type )

Constructs a new argument of the specified type.

This constructor is useful for creating separators within a config section.

Member Function Documentation

◆ addArg()

bool ArConfigArg::addArg ( const ArConfigArg & arg )

Adds a child arg to this arg. Valid only for LIST type; otherwise returns false.

If the given child arg is not a separator, then it must have a unique, non-empty name.

Parameters

arg	the ArConfigArg to be added as a child of this composite arg

Returns: bool true if the child arg was successfully added; false if an error occurred

◆ addToFileParser()

bool ArConfigArg::addToFileParser	(	ArFileParser *	parser,
		ArRetFunctor3C< bool, ArConfig, ArArgumentBuilder , char , size_t > *	parserCB,
		const char *	logPrefix = `""`,
		bool	isQuiet = `false`
	)		const

Adds given parserCB handler for the appropriate keyword(s) to the given file parser.

For normal args, this method simply adds the parserCB handler for the keyword (i.e.

arg name). For list args, this method adds the parserCB handler for all child arg names. The list arg itself is handled by ArConfig using the special keywords (_beginList and _endList).

Parameters

parser	the ArFileParser * to which to add the handler
parserCB	the ArFunctor * that will parse the arg when the keyword is found
logPrefix	the char * prefix to use in debug log messages
isQuiet	a bool set to true if minimal log messages should be generated; false if verbosity is desired.

Returns: bool true if the hanlder was successfully added to the parser; false if an error occurred

◆ copyTranslation()

bool ArConfigArg::copyTranslation ( const ArConfigArg & arg )

Copies the translation data from given arg to this one.

The translation data currently consists of the description and the extra explanation.

◆ findArg() [1/2]

const ArConfigArg * ArConfigArg::findArg ( const char * childParamName ) const

Finds the specified child arg. Valid only for LIST type; otherwise returns NULL.

This method performs a case-insensitive search of the child arg names.

Parameters

childParamName the char * name of the child arg to be retrieved; must be non-empty

Returns: ArConfigArg * a pointer to the requested child arg; or NULL if not found.

◆ findArg() [2/2]

ArConfigArg * ArConfigArg::findArg ( const char * childParamName )

Finds the specified child arg. Valid only for LIST type; otherwise returns NULL.

This method performs a case-insensitive search of the child arg names.

Parameters

childParamName the char * name of the child arg to be retrieved; must be non-empty

Returns: ArConfigArg * a pointer to the requested child arg; or NULL if not found.

◆ getArg()

const ArConfigArg * ArConfigArg::getArg ( size_t index ) const

Returns the child arg at the specified index (between 0 and getArgCount()).

Returns: std::list<ArConfigArg> a list of all of the child arg (copies) in this arg.

◆ getArgCount()

size_t ArConfigArg::getArgCount ( ) const

Returns the number of child args. Valid only for LIST type; otherwise returns 0.

Returns: int the number of child args in this list arg; or 0 if none.

◆ getArgs()

std::list< ArConfigArg > ArConfigArg::getArgs ( bool * ok = NULL ) const

Returns a list of all child args in this arg. Valid only for LIST type; otherwise returns an empty list.

Returns: std::list<ArConfigArg> a list of all of the child arg (copies) in this arg.

◆ getConfigPriority()

ArPriority::Priority ArConfigArg::getConfigPriority ( void ) const

Gets the priority (only used by ArConfig)

The priority of this argument when used in ArConfig.

◆ getCppString()

std::string ArConfigArg::getCppString ( bool * ok = NULL ) const

Get a copy of the value of the target std::string.

(If there is a NULL target, return "" and set ok to false if ok is not NULL.)

◆ getCppStringPtr()

const std::string * ArConfigArg::getCppStringPtr ( bool * ok = NULL ) const

Get the internal pointer to the target std::string.

Do not modify. (If there is a NULL target, return NULL and set ok to false if ok is not NULL.)

◆ getDescription()

const char * ArConfigArg::getDescription ( void ) const

Gets the brief description of the argument.

Returns: char *, the description of this arg or "" if none

◆ getMaxDouble()

double ArConfigArg::getMaxDouble ( bool * ok = NULL ) const

Gets the maximum double value.

This method is applicable only when getType() returns DOUBLE.

Parameters

ok	an optional pointer to a bool that can be set by this method to indicate success (true) or failure (false)

Returns: double the maximum value of this arg, or HUGE_VAL if none

◆ getMaxInt()

int ArConfigArg::getMaxInt ( bool * ok = NULL ) const

Gets the maximum int value.

This method is applicable only when getType() returns INT.

Parameters

ok	an optional pointer to a bool that can be set by this method to indicate success (true) or failure (false)

Returns: int the maximum value of this arg, or INT_MAX if none

◆ getMinDouble()

double ArConfigArg::getMinDouble ( bool * ok = NULL ) const

Gets the minimum double value.

This method is applicable only when getType() returns DOUBLE.

Parameters

ok	an optional pointer to a bool that can be set by this method to indicate success (true) or failure (false)

Returns: double the maximum value of this arg, or -HUGE_VAL if none

◆ getMinInt()

int ArConfigArg::getMinInt ( bool * ok = NULL ) const

Gets the minimum int value.

This method is applicable only when getType() returns INT.

Parameters

ok	an optional pointer to a bool that can be set by this method to indicate success (true) or failure (false)

Returns: int the minimum value of this arg, or INT_MIN if none

◆ getName()

const char * ArConfigArg::getName ( void ) const

Gets the name of the argument.

Returns: char *, the name of this arg or "" if none

◆ getParentArg()

ArConfigArg * ArConfigArg::getParentArg ( ) const

Returns a pointer to the immediate parent arg. If this is not a child ArConfigArg, then returns NULL.

Returns: ArConfigArg * the parent arg, if this is a child in a list arg; otherwise, NULL

◆ getType()

ArConfigArg::Type ArConfigArg::getType ( void ) const

Gets the type of the argument.

Returns: Type the type of this arg, used to determine which other attributes are valid

◆ hasArgs()

bool ArConfigArg::hasArgs ( ) const

Returns whether the list contains child args. Valid only for LIST type; otherwise returns false.

Returns: bool set to true if this is a list arg that contains child args; false, otherwise

◆ setConfigPriority()

void ArConfigArg::setConfigPriority ( ArPriority::Priority priority )

Sets the priority (only used by ArConfig)

The priority of this argument when used in ArConfig.

◆ setDisplayHint()

void ArConfigArg::setDisplayHint ( const char * hintText )

Sets the display hint for this arg.

The "display hint" is a text string that may be used by the client to improve the display of the argument.

Multiple, non-confilicting display hints may be specified by using the "&&" separator. For example: "Choices:High;;Low&&Visible:PinEnabled=true"

The display hints that are currently supported by MobileEyes and MobilePlanner are described below.

For all ArConfigArg types:

Visible:OtherParamName=OtherParamValue
- The current ArConfigArg will be displayed in the configuration editor only when the other parameter equals the specified value. This is used to vary a set of displayed items based on list choices. The presentation will be similar to the current implementation of child objects in the map.
Visible:OtherParamName!=OtherParamValue
- The current ArConfigArg will be displayed in the configuration editor only when the other parameter does not equal the specified value. This is used to vary a set of displayed items based on list choices. The presentation will be similar to the current implementation of child objects in the map.
Visible:OtherParamName>OtherParamValue
- EXPLANATION
Visible:false
- The ArConfigArg is never displayed
Editable:OtherParamName=OtherParamValue
- The current ArConfigArg is read-only unless the other parameter equals the specified value. This allows fine-grained dependencies, primarily for small �enabled� flags.
Editable:OtherParamName!=OtherParamValue
- The current ArConfigArg is read-only unless the other parameter equals the specified value. This allows fine-grained dependencies, primarily for small �enabled� flags.
Editable:OtherParamName>OtherParamValue
- The current ArConfigArg is read-only unless the other parameter exceeds the specified value. This is provided primarily for consistency with the Visible case. Its usefulness is questionable.
Editable:false
- The current ArConfigArg is always read-only

For type STRING:

Choices:choice1(;;choice::i)*
- For example, "Choices:North;;South;;East;;West"
- To include an empty choice, start the choice list with ;;. For example, "Choices:;;FirstNonEmpty;;SecondNonEmpty"
MapItem:type|(Parent|SubType|SubTypeAndParent|SubTypeGlob)|(Optional|Required)
- For example, "MapItem:Dock|Parent|Optional"
- If SubTypeGlob is specified, then type may contain wildchar characters * and ?
ChildObject:type|(Parent|SubType|SubTypeAndParent|SubTypeGlob)|(Optional|Required)
- This value is only supported for parameters that are associated with a MapInfo. It allows the application to create a parent/child relationship amongst certain map items. Mapper3 automatically manages the creation of the child items.
- To specify a default value for the associated parameter, set the ArConfigArg's string value to: ParentTypeName_@_ParameterName_@_DefaultChildTypeName.
Macro:taskClass1(;;taskClass::i)*|(Optional|Required)
- For example, "Macro:Audio;;Camera;;Video|Optional"
Macro
- When used with no qualifiers, there are no task class restrictions and the macro is optional
Time:format
- The format must conform to Qt's QTime format definition. (Briefly: h = hour, m = minute, s = second, z = millisecond, and AP = AM/PM. Double characters indicate that a leading 0 should be used to pad.)
- For example, "Time:h:mm AP" or "Time:hh:mm:ss"
- Note that this is a time-of-day, not a duration. Seconds and minutes range from 0 to 59, and hour ranges from 0 to 23 (or 1 to 12 with AM/PM).
- AP (i.e. AM/PM) only affects the display of the time; the string that is stored in the ArConfigArg should always be converted to 24 hour format.
Time
- When there are no qualifiers, the default format "h:mm AP" is used
RobotFile:fileFilterNames|fileFilters
- where:
  - fileFilterNames is a string that contains the complete displayable names for all of the file filters (e.g. Map files (*.map);;World files (*.wld)), or, empty if no filter needs to be applied, and
  - fileFilters is a string that contains just file extensions for each of the file filters (e.g. *.map;;*.wld"). The number and order of these filters must match that of the fileFilterNames parameter.
- For example, "RobotFile:Map Files (*.map);;World Files (*.wld)|*.map;;*.wld"
- For further example, "All audio files (*.ogg *.wav);;Ogg Vorbis files (*.ogg);;WAV files (*.wav);;*.ogg *.wav;;*.ogg;;*.wav"

For type INT:

Color

For type BOOL:

Checkbox

◆ setIgnoreBounds()

void ArConfigArg::setIgnoreBounds ( bool ignoreBounds = false )

Sets whether to ignore bounds or not (default is to not to)

This is for debugging and will prevent the bounds checking from happening, you shouldn't normally use it.

◆ setString()

bool ArConfigArg::setString	(	const char *	str,
		char *	errorBuffer = `NULL`,
		size_t	errorBufferLen = `0`,
		bool	doNotSet = `false`
	)

Sets the argument value for string arguments.

Warning: The value must not contain any characters with special meaning when saved and loaded from a config file, such as '#', ';', tab, or newline.

◆ setValue()

bool ArConfigArg::setValue	(	const ArConfigArg &	source,
		bool	isVerifyArgNames = `false`
	)

If the given source is of the same type, copies its value to this arg.

Note that this method currently only works for the primitive arg types (i.e. int, bool, etc.). It doesn't copy functors or description holders.

Parameters

source	the ArConfigArg whose value is to be copied to this arg
isVerifyArgNames	a bool set to true if the argument value should be set only if the given source has the same name as this argument; the default value is false

Returns: bool true if the value was copied; false if the source was of a different (or non-copyable) type

ArLog::log(ArLog::Verbose, "ArConfigArg::setValue() unverified names, cannot set %s to %s", getName(), source.getName());

◆ writeArguments()

bool ArConfigArg::writeArguments	(	FILE *	file,
		char *	lineBuf,
		int	lineBufSize,
		int	startCommentColumn,
		bool	isWriteExtra = `false`,
		const char *	logPrefix = `""`,
		int	indentLevel = `0`
	)		const

Writes this arg to the given file, in a format suitable for reading by parseArgument.

Parameters

file	the FILE * to be written, must be non-NULL
lineBuf	a char array to be used as a temporary write buffer, must be non-NULL
lineBufSize	the int number of chars in lineBuf, must be positive
startCommentColumn	the int column index at which to indent the arg description / comment
isWriteExtra	a bool set to true if the arg priority, display hint, restart level and other later extras should also be written to the file
logPrefix	the char * prefix to use in debug log messages, must be non-NULL
indentLevel	the int level of indentation for the arg (children of lists are indented further); must be non-negative

Returns: bool true if the arguments were successfully written; false if an error occurred

◆ writeBounds()

bool ArConfigArg::writeBounds	(	char *	line,
		size_t	lineLen,
		const char *	logPrefix = `""`
	)		const

Writes the min/max values of this arg to the given buffer, as applicable.

Parameters

line	a char array to be used as a temporary write buffer, must be non-NULL
lineLen	the int number of chars in line, must be positive
logPrefix	the char * prefix to use in debug log messages, must be non-NULL

Returns: bool true if the values were successfully written; false if an error occurred

◆ writeMultiLineComment()

bool ArConfigArg::writeMultiLineComment	(	const char *	comment,
		FILE *	file,
		char *	lineBuf,
		int	lineBufSize,
		const char *	startComment
	)

staticprotected

Writes the given comment to the specified file, spanning multiple lines as necessary.

Parameters

comment	the char * string to be written to the file, must be non-NULL
file	the FILE * to be written, must be non-NULL
lineBuf	a char array to be used as a temporary write buffer, must be non-NULL
lineBufSize	the int number of chars in lineBuf, must be positive
startComment	the char * text that should prefix the comment on the first line

Returns: bool true if the comment was successfully written; false if an error occurred

◆ writeName()

bool ArConfigArg::writeName	(	char *	lineBuf,
		int	lineBufSize,
		int	indentLevel
	)		const

Writes the name of this arg to the given buffer, indenting as specified.

Parameters

lineBuf	a char array to which to write the name, must be non-NULL
lineBufSize	the int number of chars in lineBuf, must be positive
indentLevel	the int level of indentation for the arg (children of lists are indented further); must be non-negative

Returns: bool true if the name was successfully written; false if an error occurred

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

ArConfigArg.h
ArConfigArg.cpp

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Static Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

◆ Type

Constructor & Destructor Documentation

◆ ArConfigArg() [1/16]

◆ ArConfigArg() [2/16]

◆ ArConfigArg() [3/16]

◆ ArConfigArg() [4/16]

◆ ArConfigArg() [5/16]

◆ ArConfigArg() [6/16]

◆ ArConfigArg() [7/16]

◆ ArConfigArg() [8/16]

◆ ArConfigArg() [9/16]

◆ ArConfigArg() [10/16]

◆ ArConfigArg() [11/16]

◆ ArConfigArg() [12/16]

◆ ArConfigArg() [13/16]

◆ ArConfigArg() [14/16]

◆ ArConfigArg() [15/16]

◆ ArConfigArg() [16/16]

Member Function Documentation

◆ addArg()

◆ addToFileParser()

◆ copyTranslation()

◆ findArg() [1/2]

◆ findArg() [2/2]

◆ getArg()

◆ getArgCount()

◆ getArgs()

◆ getConfigPriority()

◆ getCppString()

◆ getCppStringPtr()

◆ getDescription()

◆ getMaxDouble()

◆ getMaxInt()

◆ getMinDouble()

◆ getMinInt()

◆ getName()

◆ getParentArg()

◆ getType()

◆ hasArgs()

◆ setConfigPriority()

◆ setDisplayHint()

◆ setIgnoreBounds()

◆ setString()

◆ setValue()

◆ writeArguments()

◆ writeBounds()

◆ writeMultiLineComment()

◆ writeName()