ArConfig Class Reference

#include <ArConfig.h>

Inheritance diagram for ArConfig:

List of all members.

---

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().

Usually, configuration data are read from and written to a file using parseFile() and writeFile(), or are set by a remote client via ArNetworking. It is also possible to import configuration settings from an ArArgumentParser (which, for example, may contain a program's command line arguments) using useArgumentParser().

Warning:

ArConfig does not escape any special characters when writing or loading to/from a file. Therefore in general parameter names, values, section names, and comments must not contain characters which have special meaning in a config file, such as '#', ';', tab or newline. (see also ArFileParser) Parameter names may have spaces, though by convention they generally do not.

Examples:

configExample.cpp.

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 (ArRetFunctor2< bool, char *, size_t > *functor, int priority=0)
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.
virtual void	setQuiet (bool isQuiet)
	Turn on this flag to reduce the number of verbose log messages.
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
bool	myIsQuiet
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())

---

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. Warning: The section name must not contain any characters with special meaning when saved and loaded from a config file, such as '#', ';', tab, or newline. The comment must not contain tab or newline, but '#' and ';' are OK within a comment.

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. 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. Examples: configExample.cpp.

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

Adds a callback to be invoked when the configuration is loaded or reloaded.... if you really want errors you should use addProcessFileWithErrorCB, this is just to catch mistakes

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.

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 may also receive error messages

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. Warning: The section name and flags must not contain any characters with special meaning when saved and loaded from a config file, such as '#', ';', tab, or newline.

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.

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

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.

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

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

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)

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

Removes a processedFile callback. Removes a processFileCB, see addProcessFileCB for details

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

Removes a processedFile callback. Removes a processFileCB, see addProcessFileCB for details

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.

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

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. Warning: The section name must not contain any characters with special meaning when saved and loaded from a config file, such as '#', ';', tab, or newline. The comment must not contain tab or newline, but '#' and ';' are OK within a comment. Examples: configExample.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.

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.

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

---

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

• ArConfig.h
• ArConfig.cpp

---