Aria  2.7.5.2
ArConfig Class Reference

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

#include <ArConfig.h>

Inherited by ArRobotParams.

Classes

class  ProcessFileCBType
 

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. More...
 
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. More...
 
void addProcessFileCB (ArRetFunctor< bool > *functor, int priority=0)
 
void addProcessFileCB (ArRetFunctor2< bool, char *, size_t > *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 More...
 
 ArConfig (const char *baseDirectory=NULL, bool noBlanksBetweenParams=false, bool ignoreBounds=false, bool failOnBadSection=false, bool saveUnknown=true)
 Constructor. More...
 
 ArConfig (const ArConfig &config)
 Copy 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.
 
ArConfigSectionfindSection (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)
 
ArConfigoperator= (const ArConfig &config)
 
bool parseArgument (ArArgumentBuilder *arg, char *errorBuffer=NULL, size_t errorBufferLen=0)
 This parses the argument given (for parser or other use) More...
 
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. More...
 
bool parseSection (ArArgumentBuilder *arg, char *errorBuffer=NULL, size_t errorBufferLen=0)
 This parses the section change (for parser or other use) More...
 
bool parseUnknown (ArArgumentBuilder *arg, char *errorBuffer=NULL, size_t errorBufferLen=0)
 This parses an unknown argument (so we can save it) More...
 
virtual bool processFile (void)
 for inheritors this is called after the file is processed More...
 
void removeAllUnsetValues (void)
 Removes all unset values from the config (internal for default configs)
 
void remProcessFileCB (ArRetFunctor< bool > *functor)
 Removes a processedFile callback. More...
 
void remProcessFileCB (ArRetFunctor2< bool, char *, size_t > *functor)
 Removes a processedFile callback. More...
 
bool remSectionFlag (const char *sectionName, const char *flag)
 Removes a flag from a section. More...
 
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. More...
 
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. More...
 
void useArgumentParser (ArArgumentParser *parser)
 Uses this argument parser after it parses a file before it processes. More...
 
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. More...
 
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. More...
 

Protected Attributes

ArArgumentParsermyArgumentParser
 
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
 

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.

Constructor & Destructor Documentation

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

Constructor.

Parameters
baseDirectorya directory to search for files in
noBlanksBetweenParamsif there should not be blank lines between params in output
ignoreBoundsif this is true bounds checking will be ignored when the file is read in. this should ONLY be used by developers debugging
failOnBadSectionif this is true and there is a bad section, then parseFile will fail
saveUnknownif 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
commentText of the comment.
sectionNameName of the section to add the comment to. If the section does not exist, it will be created.
priorityPriority 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
argObject containing key, description and value type of this parameter. This object will be copied.
sectionNameName of the section to put this parameter in.
priorityPriority or importance of this parameter to a user.
displayHintSuggest 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 ( ArRetFunctor< bool > *  functor,
int  priority = 0 
)

Adds a callback to be invoked when the configuration is loaded or reloaded.

After a file has been read all the way these processFileCBs are called in the priority (higher numbers first)... these are only called if there were no errors parsing the file or continueOnError was set to false when parseFile was called

The functor should return true if the config parsed was good (parseFile will return true) false if the config parsed wasn't (parseFile will return false)

Parameters
functorthe functor to call
prioritythe functors are called in descending order, if two things have the same number the first one added is the first one called
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

After a file has been read all the way these processFileCBs are called in the priority (higher numbers first)... these are only called if there were no errors parsing the file or continueOnError was set to false when parseFile was called

The functor should return true if the config parsed was good (parseFile will return true) false if the config parsed wasn't (parseFile will return false)

Parameters
functorthe functor to call
prioritythe functors are called in descending order, if two things have the same number the first one added is the first one called
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

This function has a different name than addProcessFileCB just so that if you mean to get this function but have the wrong functor you'll get an error. The rem's are the same though since that shouldn't matter.

After a file has been read all the way these processFileCBs are called in the priority (higher numbers first)... these are only called if there were no errors parsing the file or continueOnError was set to false when parseFile was called

The functor should return true if the config parsed was good (parseFile will return true) false if the config parsed wasn't (parseFile will return false)

Parameters
functorthe functor to call (the char * and unsigned int should be used by the functor to put an error message into that buffer)
prioritythe functors are called in descending order, if two things have the same number the first one added is the first one called
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
argObtain parameter name from this object's "extra string" and value(s) from its argument(s).
errorBufferIf 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
errorBufferLenthe 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
fileNamethe file to load
continueOnErrorswhether to continue parsing if we get errors (or just bail)
noFileNotFoundMessageif the file isn't found and this param is true it won't complain, otherwise it will
errorBufferIf an error occurs and this is not NULL, copy a description of the error into this buffer
errorBufferLenthe length of errorBuffer
sectionsToParseif 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
argShould contain the 'Section' keyword as its "extra" string, and section name as argument(s).
errorBufferif 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
errorBufferLenthe 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
argObtain parameter name from this argument builder's "exra" string and value(s) from its argument(s).
errorBufferif 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
errorBufferLenthe length of the error buffer
virtual bool ArConfig::processFile ( void  )
inlinevirtual

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 ( ArRetFunctor< bool > *  functor)

Removes a processedFile callback.

Removes a processFileCB, see addProcessFileCB for details

void ArConfig::remProcessFileCB ( ArRetFunctor2< bool, char *, size_t > *  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
configNamea char * descriptive name of the ArConfig instance (e.g. Server or Default)
robotNamean 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
fileNamethe name of the file to write out
appendif true then text will be appended to the file if it exists, otherwise any existing file will be overwritten.
alreadyWrittenif 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
writePrioritiesif this is true then priorities will be written, if it is false they will not be
sectionsToWriteif 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: