Aria
2.7.5.2
|
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. | |
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) 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 | |
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 |
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().
ArConfig::ArConfig | ( | const char * | baseDirectory = NULL , |
bool | noBlanksBetweenParams = false , |
||
bool | ignoreBounds = false , |
||
bool | failOnBadSection = false , |
||
bool | saveUnknown = true |
||
) |
Constructor.
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()) |
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.
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. |
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.
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. |
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)
functor | the functor to call |
priority | the functors are called in descending order, if two things have the same number the first one added is the first one called |
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)
functor | the functor to call |
priority | the 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)
functor | the functor to call (the char * and unsigned int should be used by the functor to put an error message into that buffer) |
priority | the 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.
ArConfigSection * ArConfig::findSection | ( | const char * | sectionName) | const |
Find the section with the given name.
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.
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.
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) |
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.
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.
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 |
|
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
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.
|
virtual |
Stores an optional config and robot name to be used in log messages.
These names are used solely for log messages.
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.
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.
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 |
|
protected |
Write out a section.
clear out our written ones between sections