ArConfig Class Reference

#include <ArConfig.h>

Inheritance diagram for ArConfig:

Detailed Description

Stores configuration information which may be read to and from files or other sources.

The configuration is a set of parameters (or config arguments), organized into sections. Parameters contain a key or name (a short string), a value (which may be one of several types), a priority (important, normal, or trivial to most users), a longer description, and a display hint which suggests what kind of UI control might be most appropriate for the parameter. After adding a parameter to the configuration, its value may be changed when the configuration is loaded or reloaded from a file. Various program modules may register callbacks to be notified when a shared global configuration (such as the static ArConfig object kept by the Aria class) is loaded or otherwise changed.

Classes dealing with more specialized kinds of config files inherit from this one.

Important methods in this class are: addParam(), addProcessFileCB(), remProcessFileCB(), parseFile(), writeFile().

Examples:: configExample.cpp.

Definition at line 55 of file ArConfig.h.

Public Member Functions

bool addComment (const char *comment, const char *sectionName="", ArPriority::Priority priority=ArPriority::NORMAL)

Command to add a new comment to the given section with given priority.

bool addParam (const ArConfigArg &arg, const char *sectionName="", ArPriority::Priority priority=ArPriority::NORMAL, const char *displayHint=NULL)

Command to add a parameter to the given section with given priority.

void addProcessFileCB (ArRetFunctor< bool > *functor, int priority=0)

void addProcessFileWithErrorCB (ArRetFunctor2< bool, char *, size_t > *functor, int priority=0)

bool addSectionFlags (const char *sectionName, const char *flags)

adds a flag to a section

ArConfig (const ArConfig &config)

Copy constructor.

ArConfig (const char *baseDirectory=NULL, bool noBlanksBetweenParams=false, bool ignoreBounds=false, bool failOnBadSection=false, bool saveUnknown=true)

Constructor.

bool callProcessFileCallBacks (bool continueOnError, char *errorBuffer=NULL, size_t errorBufferLen=0)

Call the processFileCBs.

void clearAll (void)

Clears out all the section information and the processFileCBs.

void clearAllValueSet (void)

calls clearValueSet on the whole config (internal for default configs)

void clearSections (void)

Clears out all the section information.

ArConfigSection * findSection (const char *sectionName) const

const char * getBaseDirectory (void) const

Get the base directory.

const char * getFileName (void) const

Get the file name we loaded.

bool getNoBlanksBetweenParams (void)

Get whether we have blanks between the params or not.

ArLog::LogLevel getProcessFileCallbacksLogLevel (void)

Get the log level used when loading or reloading the configuration.

bool getSaveUnknown (void)

Gets whether we save unknowns (if we don't save 'em we ignore 'em).

std::list< ArConfigSection * > * getSections (void)

Get the sections themselves (use only if you know what to do).

void log (bool isSummary=true)

ArConfig & operator= (const ArConfig &config)

bool parseArgument (ArArgumentBuilder *arg, char *errorBuffer=NULL, size_t errorBufferLen=0)

This parses the argument given (for parser or other use).

bool parseArgumentParser (ArArgumentParser *parser, bool continueOnError=false, char *errorBuffer=NULL, size_t errorBufferLen=0)

Use an argument parser to change the config.

bool parseFile (const char *fileName, bool continueOnError=false, bool noFileNotFoundMessage=false, char *errorBuffer=NULL, size_t errorBufferLen=0, std::list< std::string > *sectionsToParse=NULL)

Parse a config file.

bool parseSection (ArArgumentBuilder *arg, char *errorBuffer=NULL, size_t errorBufferLen=0)

This parses the section change (for parser or other use).

bool parseUnknown (ArArgumentBuilder *arg, char *errorBuffer=NULL, size_t errorBufferLen=0)

This parses an unknown argument (so we can save it).

virtual bool processFile (void)

for inheritors this is called after the file is processed

void removeAllUnsetValues (void)

Removes all unset values from the config (internal for default configs).

void remProcessFileCB (ArRetFunctor2< bool, char *, size_t > *functor)

Removes a processedFile callback.

void remProcessFileCB (ArRetFunctor< bool > *functor)

Removes a processedFile callback.

bool remSectionFlag (const char *sectionName, const char *flag)

Removes a flag from a section.

void setBaseDirectory (const char *baseDirectory)

Set the base directory.

virtual void setConfigName (const char *configName, const char *robotName=NULL)

Stores an optional config and robot name to be used in log messages.

void setNoBlanksBetweenParams (bool noBlanksBetweenParams)

Set whether we have blanks between the params or not.

void setProcessFileCallbacksLogLevel (ArLog::LogLevel level)

Set the log level used when loading or reloading the configuration.

void setSaveUnknown (bool saveUnknown)

Sets whether we save unknown items (if we don't save 'em we ignore 'em).

void setSectionComment (const char *sectionName, const char *comment)

Sets the comment for a section.

void useArgumentParser (ArArgumentParser *parser)

Uses this argument parser after it parses a file before it processes.

bool writeFile (const char *fileName, bool append=false, std::set< std::string > *alreadyWritten=NULL, bool writePriorities=false, std::list< std::string > *sectionsToWrite=NULL)

Write out a config file.

virtual ~ArConfig ()

Destructor.

Protected Member Functions

void addParserHandlers (void)

void copySectionsToParse (std::list< std::string > *from)

void writeSection (ArConfigSection *section, FILE *file, std::set< std::string > *alreadyWritten, bool writePriorities)

Write out a section.

Protected Attributes

ArArgumentParser * myArgumentParser

std::string myBaseDirectory

std::string myConfigName

Optional name of the config instance.

bool myDuplicateParams

bool myFailOnBadSection

std::string myFileName

bool myIgnoreBounds

std::string myLogPrefix

Prefix to be inserted in log messages (contains the robot and config names).

bool myNoBlanksBetweenParams

ArFileParser myParser

ArRetFunctor3C< bool, ArConfig,
ArArgumentBuilder *, char *,
size_t > myParserCB

ArLog::LogLevel myProcessFileCallbacksLogLevel

std::multimap< int, ProcessFileCBType * > myProcessFileCBList

std::string myRobotName

Optional name of the robot with which the config is associated.

bool mySaveUnknown

std::string mySection

bool mySectionBroken

ArRetFunctor3C< bool, ArConfig,
ArArgumentBuilder *, char *,
size_t > mySectionCB

bool mySectionIgnored

std::list< ArConfigSection * > mySections

std::list< std::string > * mySectionsToParse

ArRetFunctor3C< bool, ArConfig,
ArArgumentBuilder *, char *,
size_t > myUnknownCB

bool myUsingSections

Classes

class ProcessFileCBType

Constructor & Destructor Documentation

ArConfig::ArConfig ( const char * baseDirectory = NULL,

bool noBlanksBetweenParams = false,

bool ignoreBounds = false,

bool failOnBadSection = false,

bool saveUnknown = true

)

Constructor.

Parameters:

baseDirectory a directory to search for files in

noBlanksBetweenParams if there should not be blank lines between params in output

ignoreBounds if this is true bounds checking will be ignored when the file is read in. this should ONLY be used by developers debugging

failOnBadSection if this is true and there is a bad section, then parseFile will fail

saveUnknown if this is true and there are unknown parameters or sections then they will be saved, if false then they will be ignored (can also be set with setSaveUnknown())

Definition at line 60 of file ArConfig.cpp.

Member Function Documentation

bool ArConfig::addComment ( const char * comment,

const char * sectionName = "",

ArPriority::Priority priority = ArPriority::NORMAL

)

Command to add a new comment to the given section with given priority.
Add a comment to a section.
Parameters:

comment Text of the comment.

sectionName Name of the section to add the comment to. If the section does not exist, it will be created.

priority Priority or importance.

Definition at line 495 of file ArConfig.cpp.

bool ArConfig::addParam ( const ArConfigArg & arg,

const char * sectionName = "",

ArPriority::Priority priority = ArPriority::NORMAL,

const char * displayHint = NULL

)

Command to add a parameter to the given section with given priority.
Add a parameter.
Parameters:

arg Object containing key, description and value type of this parameter. This object will be copied.

sectionName Name of the section to put this parameter in.

priority Priority or importance of this parameter to a user.

displayHint Suggest an appropriate UI control for editing this parameter's value. See ArConfigArg::setDisplayHint() for description of display hint format.

Examples:
configExample.cpp.

Definition at line 410 of file ArConfig.cpp.

void ArConfig::addProcessFileCB ( ArRetFunctor< bool > * functor,

int priority = 0

)

Adds a callback to be invoked when the configuration is loaded or reloaded.
Examples:
configExample.cpp.

Definition at line 1392 of file ArConfig.cpp.

void ArConfig::addProcessFileWithErrorCB ( ArRetFunctor2< bool, char *, size_t > * functor,

int priority = 0

)

Adds a callback to be invoked when the configuration is loaded or reloaded, which my also receive error messages
Definition at line 1444 of file ArConfig.cpp.

bool ArConfig::addSectionFlags ( const char * sectionName,

const char * flags

)

adds a flag to a section
Add a flag to a section. If the section doesn't exist then it is created.
Definition at line 369 of file ArConfig.cpp.

ArConfigSection * ArConfig::findSection ( const char * sectionName ) const

Find the section with the given name.
Returns:
section object, or NULL if not found.

Examples:
configExample.cpp.

Definition at line 1681 of file ArConfig.cpp.

bool ArConfig::parseArgument ( ArArgumentBuilder * arg,

char * errorBuffer = NULL,

size_t errorBufferLen = 0

)

This parses the argument given (for parser or other use).
The extra string of the parser should be set to the command wanted, while the rest of the arg should be the arguments to the command. Its case insensitive.

Parameters:

arg Obtain parameter name from this object's "extra string" and value(s) from its argument(s).

errorBuffer If this is NULL it is ignored, otherwise the string for the error is put into the buffer, the first word should be the parameter that has trouble

errorBufferLen the length of errorBuffer

Definition at line 635 of file ArConfig.cpp.

bool ArConfig::parseFile ( const char * fileName,

bool continueOnErrors = false,

bool noFileNotFoundMessage = false,

char * errorBuffer = NULL,

size_t errorBufferLen = 0,

std::list< std::string > * sectionsToParse = NULL

)

Parse a config file.

Parameters:

fileName the file to load

continueOnErrors whether to continue parsing if we get errors (or just bail)

noFileNotFoundMessage if the file isn't found and this param is true it won't complain, otherwise it will

errorBuffer If an error occurs and this is not NULL, copy a description of the error into this buffer

errorBufferLen the length of errorBuffer

sectionsToParse if NULL, then parse all sections; otherwise, a list of the section names that should be parsed (sections not in the list are ignored)

Examples:
configExample.cpp.

Definition at line 932 of file ArConfig.cpp.

bool ArConfig::parseSection ( ArArgumentBuilder * arg,

char * errorBuffer = NULL,

size_t errorBufferLen = 0

)

This parses the section change (for parser or other use).
The extra string of the parser should be set to the 'Section' command while the rest of the arg should be the arguments to the section command. Its case insensitive.

Parameters:

arg Should contain the 'Section' keyword as its "extra" string, and section name as argument(s).

errorBuffer if this is NULL it is ignored, otherwise the string for the error is put into the buffer, the first word should be the parameter that has trouble

errorBufferLen the length of the error buffer

Definition at line 516 of file ArConfig.cpp.

bool ArConfig::parseUnknown ( ArArgumentBuilder * arg,

char * errorBuffer = NULL,

size_t errorBufferLen = 0

)

This parses an unknown argument (so we can save it).
The extra string of the parser should be set to the command wanted, while the rest of the arg should be the arguments to the command. Its case insensitive.

Parameters:

arg Obtain parameter name from this argument builder's "exra" string and value(s) from its argument(s).

errorBuffer if this is NULL it is ignored, otherwise the string for the error is put into the buffer, the first word should be the parameter that has trouble

errorBufferLen the length of the error buffer

Definition at line 881 of file ArConfig.cpp.

virtual bool ArConfig::processFile ( void ) [inline, virtual]

for inheritors this is called after the file is processed
For classes that inherit from ArConfig this function is called after parseFile and all of the processFileCBs are called... If you want to call something before the processFileCBs then just add a processFileCB... this is only called if there were no errors parsing the file or continueOnError was set to false when parseFile was called

Returns:
true if the config parsed was good (parseFile will return true) false if the config parsed wasn't (parseFile will return false)

Definition at line 118 of file ArConfig.h.

void ArConfig::remProcessFileCB ( ArRetFunctor2< bool, char *, size_t > * functor )

Removes a processedFile callback.
Removes a processFileCB, see addProcessFileCB for details
Definition at line 1456 of file ArConfig.cpp.

void ArConfig::remProcessFileCB ( ArRetFunctor< bool > * functor )

Removes a processedFile callback.
Removes a processFileCB, see addProcessFileCB for details
Definition at line 1403 of file ArConfig.cpp.

bool ArConfig::remSectionFlag ( const char * sectionName,

const char * flag

)

Removes a flag from a section.
Add a flag to a section. If the section doesn't exist then it is created.
Definition at line 392 of file ArConfig.cpp.

void ArConfig::setConfigName ( const char * configName,

const char * robotName = NULL

) [virtual]

Stores an optional config and robot name to be used in log messages.
These names are used solely for log messages.

Parameters:

configName a char * descriptive name of the ArConfig instance (e.g. Server or Default)

robotName an optional char * identifier of the robot that has the config

Definition at line 216 of file ArConfig.cpp.

void ArConfig::setSectionComment ( const char * sectionName,

const char * comment

)

Sets the comment for a section.
Set the comment string associated with a section. If the section doesn't exist then it is created.
Examples:
configExample.cpp.

Definition at line 347 of file ArConfig.cpp.

void ArConfig::useArgumentParser ( ArArgumentParser * parser )

Uses this argument parser after it parses a file before it processes.
This argument parser the arguments in to check for parameters of this name, note that ONLY the first parameter of this name will be used, so if you have duplicates only the first one will be set.
Definition at line 1573 of file ArConfig.cpp.

bool ArConfig::writeFile ( const char * fileName,

bool append = false,

std::set< std::string > * alreadyWritten = NULL,

bool writePriorities = false,

std::list< std::string > * sectionsToWrite = NULL

)

Write out a config file.

Parameters:

fileName the name of the file to write out

append if true then text will be appended to the file if it exists, otherwise any existing file will be overwritten.

alreadyWritten if non-NULL, a list of strings that have already been written out, don't write it again if it's in this list; when something is written by this function, then it is put it into this list

writePriorities if this is true then priorities will be written, if it is false they will not be

sectionsToWrite if NULL, then write all sections; otherwise, a list of the section names that should be written

Examples:
configExample.cpp.

Definition at line 1015 of file ArConfig.cpp.

void ArConfig::writeSection ( ArConfigSection * section,

FILE * file,

std::set< std::string > * alreadyWritten,

bool writePriorities

) [protected]

Write out a section.
clear out our written ones between sections
Definition at line 1109 of file ArConfig.cpp.

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

Generated on Tue Feb 20 10:51:43 2007 for Aria by

1.4.0


Public Member Functions
bool	addComment (const char comment, const char sectionName="", ArPriority::Priority priority=ArPriority::NORMAL)
	Command to add a new comment to the given section with given priority.
bool	addParam (const ArConfigArg &arg, const char sectionName="", ArPriority::Priority priority=ArPriority::NORMAL, const char displayHint=NULL)
	Command to add a parameter to the given section with given priority.
void	addProcessFileCB (ArRetFunctor< bool > *functor, int priority=0)
void	addProcessFileWithErrorCB (ArRetFunctor2< bool, char , size_t > functor, int priority=0)
bool	addSectionFlags (const char sectionName, const char flags)
	adds a flag to a section
	ArConfig (const ArConfig &config)
	Copy constructor.
	ArConfig (const char *baseDirectory=NULL, bool noBlanksBetweenParams=false, bool ignoreBounds=false, bool failOnBadSection=false, bool saveUnknown=true)
	Constructor.
bool	callProcessFileCallBacks (bool continueOnError, char *errorBuffer=NULL, size_t errorBufferLen=0)
	Call the processFileCBs.
void	clearAll (void)
	Clears out all the section information and the processFileCBs.
void	clearAllValueSet (void)
	calls clearValueSet on the whole config (internal for default configs)
void	clearSections (void)
	Clears out all the section information.
ArConfigSection *	findSection (const char *sectionName) const
const char *	getBaseDirectory (void) const
	Get the base directory.
const char *	getFileName (void) const
	Get the file name we loaded.
bool	getNoBlanksBetweenParams (void)
	Get whether we have blanks between the params or not.
ArLog::LogLevel	getProcessFileCallbacksLogLevel (void)
	Get the log level used when loading or reloading the configuration.
bool	getSaveUnknown (void)
	Gets whether we save unknowns (if we don't save 'em we ignore 'em).
std::list< ArConfigSection * > *	getSections (void)
	Get the sections themselves (use only if you know what to do).
void	log (bool isSummary=true)
ArConfig &	operator= (const ArConfig &config)
bool	parseArgument (ArArgumentBuilder arg, char errorBuffer=NULL, size_t errorBufferLen=0)
	This parses the argument given (for parser or other use).
bool	parseArgumentParser (ArArgumentParser parser, bool continueOnError=false, char errorBuffer=NULL, size_t errorBufferLen=0)
	Use an argument parser to change the config.
bool	parseFile (const char fileName, bool continueOnError=false, bool noFileNotFoundMessage=false, char errorBuffer=NULL, size_t errorBufferLen=0, std::list< std::string > *sectionsToParse=NULL)
	Parse a config file.
bool	parseSection (ArArgumentBuilder arg, char errorBuffer=NULL, size_t errorBufferLen=0)
	This parses the section change (for parser or other use).
bool	parseUnknown (ArArgumentBuilder arg, char errorBuffer=NULL, size_t errorBufferLen=0)
	This parses an unknown argument (so we can save it).
virtual bool	processFile (void)
	for inheritors this is called after the file is processed
void	removeAllUnsetValues (void)
	Removes all unset values from the config (internal for default configs).
void	remProcessFileCB (ArRetFunctor2< bool, char , size_t > functor)
	Removes a processedFile callback.
void	remProcessFileCB (ArRetFunctor< bool > *functor)
	Removes a processedFile callback.
bool	remSectionFlag (const char sectionName, const char flag)
	Removes a flag from a section.
void	setBaseDirectory (const char *baseDirectory)
	Set the base directory.
virtual void	setConfigName (const char configName, const char robotName=NULL)
	Stores an optional config and robot name to be used in log messages.
void	setNoBlanksBetweenParams (bool noBlanksBetweenParams)
	Set whether we have blanks between the params or not.
void	setProcessFileCallbacksLogLevel (ArLog::LogLevel level)
	Set the log level used when loading or reloading the configuration.
void	setSaveUnknown (bool saveUnknown)
	Sets whether we save unknown items (if we don't save 'em we ignore 'em).
void	setSectionComment (const char sectionName, const char comment)
	Sets the comment for a section.
void	useArgumentParser (ArArgumentParser *parser)
	Uses this argument parser after it parses a file before it processes.
bool	writeFile (const char fileName, bool append=false, std::set< std::string > alreadyWritten=NULL, bool writePriorities=false, std::list< std::string > *sectionsToWrite=NULL)
	Write out a config file.
virtual	~ArConfig ()
	Destructor.
Protected Member Functions
void	addParserHandlers (void)
void	copySectionsToParse (std::list< std::string > *from)
void	writeSection (ArConfigSection section, FILE file, std::set< std::string > *alreadyWritten, bool writePriorities)
	Write out a section.
Protected Attributes
ArArgumentParser *	myArgumentParser
std::string	myBaseDirectory
std::string	myConfigName
	Optional name of the config instance.
bool	myDuplicateParams
bool	myFailOnBadSection
std::string	myFileName
bool	myIgnoreBounds
std::string	myLogPrefix
	Prefix to be inserted in log messages (contains the robot and config names).
bool	myNoBlanksBetweenParams
ArFileParser	myParser
ArRetFunctor3C< bool, ArConfig, ArArgumentBuilder , char , size_t >	myParserCB
ArLog::LogLevel	myProcessFileCallbacksLogLevel
std::multimap< int, ProcessFileCBType * >	myProcessFileCBList
std::string	myRobotName
	Optional name of the robot with which the config is associated.
bool	mySaveUnknown
std::string	mySection
bool	mySectionBroken
ArRetFunctor3C< bool, ArConfig, ArArgumentBuilder , char , size_t >	mySectionCB
bool	mySectionIgnored
std::list< ArConfigSection * >	mySections
std::list< std::string > *	mySectionsToParse
ArRetFunctor3C< bool, ArConfig, ArArgumentBuilder , char , size_t >	myUnknownCB
bool	myUsingSections
Classes
class	ProcessFileCBType