ConfigFile Class Reference
#include <configfile.h>

Detailed Description
Class for loading configuration file information.This class is used to load and configure drivers from a configuration text file. This file is divided into sections, with section having a set of key/value fields.
Example file format is as follows:
# This is a comment # The keyword 'driver' begins a section driver ( # This line is used to identify which driver to # instantiate name "mydriver" # This line lists the interfaces that the driver # will support provides ["position2d:0" "laser:0"] # This line lists the devices to which the driver # will subscribe requires ["ptz:0"] # An integer key1 0 # A string key2 "foo" # A tuple of strings key3 ["foo" "bar"] # A tuple of multiple types key4 ["foo" 3.14 42] )
The most common use of this class is for a driver to extract configuration file options. All drivers are passed a ConfigFile pointer cf and an integer section in their contructor (see Driver::Driver). The driver code can use this information to retrieve key/value information that was given inside the appropriate driver() section in the configuration file. For example:
int maximum_speed = cf->ReadInt(section, "max_speed", -1); if(maximum_speed == -1) { // Since the default value of -1 was assigned, // no "max_speed" key/value was given in the configuration // file. }
For each type Foo, there is a method ReadFoo() that looks for a key/value pair in the indicated section and with the type Foo. The last argument specifies a default value to return if the given key is not found. The default should either be a reasonable value or a recognizably invalid value (so that you can determine when the user did not specify a value).
Always use ReadLength for linear dimensions, positions, and time derivatives (velocities, accelerations, etc.) ; this method will return values in meters, regardless of what local units are being used in the configuration file. Similarly, always use ReadAngle for angular quanities; this method will always return values in radians.
Always use ReadFilename for filenames; this method will return absolute paths, appropriately converting any relative paths that are given in the configuration file. Non-absolute paths in the configuration file are assumed to be relative to the directory in which the configuration file itself resides.
Always use ReadColor for packed 24-bit color values.
Drivers that support multiple interfaces must use ReadDeviceAddr to find out which interfaces they have been asked to support (single-interface drivers specify their one interface in the Driver constructor). For example, to check whether the driver has been asked to support a position2d interface, and if so, to add that interface:
player_devaddr_t position_addr; if(cf->ReadDeviceAddr(&position_addr, section, "provides", PLAYER_POSITION2D_CODE, -1, NULL) == 0) { if(this->AddInterface(position_addr) != 0) { this->SetError(-1); return; } }
driver ( name "mydriver" provides ["odometry:::position2d:0" "gyro:::position2d:1"] )
player_devaddr_t odom_addr, gyro_addr; // Do we create an odometry position interface? if(cf->ReadDeviceAddr(&odom_addr, section, "provides", PLAYER_POSITION2D_CODE, -1, "odometry") == 0) { if(this->AddInterface(odom_addr) != 0) { this->SetError(-1); return; } } // Do we create a gyro position interface? if(cf->ReadDeviceAddr(&gyro_addr, section, "provides", PLAYER_POSITION2D_CODE, -1, "gyro") == 0) { if(this->AddInterface(gyro_addr) != 0) { this->SetError(-1); return; } }
Drivers that subscribe to other devices use ReadDeviceAddr in the same way to retrieve information from the "requires" line of the configuration file.
Public Member Functions | |
ConfigFile (uint32_t _default_host, uint32_t _default_robot) | |
Standard constructor. | |
ConfigFile (const char *_default_host, uint32_t _default_robot) | |
Alternate constructor, to specify the host as a string. | |
ConfigFile () | |
Alternate constructor, used when not loading from a file. | |
~ConfigFile () | |
Standard destructor. | |
bool | Load (const char *filename) |
Load config from file. | |
void | InsertFieldValue (int index, const char *name, const char *value) |
Add a (name,value) pair directly into the database, without reading from a file. | |
bool | WarnUnused () |
Check for unused fields and print warnings. | |
bool | ReadBool (int section, const char *name, bool value) |
Read a boolean value (one of: yes, no, true, false, 1, 0). | |
const char * | ReadString (int section, const char *name, const char *value) |
Read a string value. | |
int | ReadInt (int section, const char *name, int value) |
Read an integer value. | |
double | ReadFloat (int section, const char *name, double value) |
Read a floating point (double) value. | |
double | ReadLength (int section, const char *name, double value) |
Read a length (includes unit conversion, if any). | |
double | ReadAngle (int section, const char *name, double value) |
Read an angle (includes unit conversion). | |
uint32_t | ReadColor (int section, const char *name, uint32_t value) |
Read a color (includes text to RGB conversion). | |
const char * | ReadFilename (int section, const char *name, const char *value) |
Read a filename. | |
int | GetTupleCount (int section, const char *name) |
Get the number of values in a tuple. | |
const char * | ReadTupleString (int section, const char *name, int index, const char *value) |
Read a string from a tuple field. | |
int | ReadTupleInt (int section, const char *name, int index, int value) |
Read an integer from a tuple field. | |
double | ReadTupleFloat (int section, const char *name, int index, double value) |
Read a float (double) from a tuple field. | |
double | ReadTupleLength (int section, const char *name, int index, double value) |
Read a length from a tuple (includes units conversion). | |
double | ReadTupleAngle (int section, const char *name, int index, double value) |
Read an angle form a tuple (includes units conversion). | |
uint32_t | ReadTupleColor (int section, const char *name, int index, uint32_t value) |
Read a color (includes text to RGB conversion). | |
int | ReadDeviceAddr (player_devaddr_t *addr, int section, const char *name, int code, int index, const char *key) |
Read a device id. | |
bool | ParseDriver (int section) |
bool | ParseInterface (int section) |
bool | ParseAllDrivers () |
bool | ParseAllInterfaces () |
int | GetSectionCount () |
Get the number of sections. | |
const char * | GetSectionType (int section) |
Get a section type name. | |
int | LookupSection (const char *type) |
Lookup a section number by section type name. | |
int | GetSectionParent (int section) |
Get a section's parent section. | |
void | DumpTokens () |
Dump the token list (for debugging). | |
void | DumpSections () |
Dump the section list for debugging. | |
void | DumpFields () |
Dump the field list for debugging. | |
Public Attributes | |
char * | filename |
Name of the file we loaded. | |
Private Types | |
enum | { TokenComment, TokenWord, TokenNum, TokenString, TokenBool, TokenOpenSection, TokenCloseSection, TokenOpenTuple, TokenCloseTuple, TokenSpace, TokenEOL } |
Private Member Functions | |
void | InitFields () |
bool | Save (const char *filename) |
void | WriteBool (int section, const char *name, bool value) |
void | WriteBool_Compat (int section, const char *name, bool value) |
void | WriteString (int section, const char *name, const char *value) |
void | WriteInt (int section, const char *name, int value) |
void | WriteFloat (int section, const char *name, double value) |
void | WriteLength (int section, const char *name, double value) |
void | WriteTupleString (int section, const char *name, int index, const char *value) |
void | WriteTupleInt (int section, const char *name, int index, int value) |
void | WriteTupleFloat (int section, const char *name, int index, double value) |
void | WriteTupleLength (int section, const char *name, int index, double value) |
void | WriteTupleAngle (int section, const char *name, int index, double value) |
bool | LoadTokens (FILE *file, int include) |
bool | LoadTokenComment (FILE *file, int *line, int include) |
bool | LoadTokenWord (FILE *file, int *line, int include) |
bool | LoadTokenInclude (FILE *file, int *line, int include) |
bool | LoadTokenNum (FILE *file, int *line, int include) |
bool | LoadTokenString (FILE *file, int *line, int include) |
bool | LoadTokenSpace (FILE *file, int *line, int include) |
bool | SaveTokens (FILE *file) |
void | ClearTokens () |
bool | AddToken (int type, const char *value, int include) |
bool | SetTokenValue (int index, const char *value) |
const char * | GetTokenValue (int index) |
bool | ParseTokens () |
bool | ParseTokenInclude (int *index, int *line) |
bool | ParseTokenDefine (int *index, int *line) |
bool | ParseTokenPlugin (int *index, int *line) |
bool | ParseTokenWord (int section, int *index, int *line) |
bool | ParseTokenSection (int section, int *index, int *line) |
bool | ParseTokenField (int section, int *index, int *line) |
bool | ParseTokenTuple (int section, int field, int *index, int *line) |
void | ClearMacros () |
int | AddMacro (const char *macroname, const char *sectionname, int line, int starttoken, int endtoken) |
int | LookupMacro (const char *macroname) |
void | DumpMacros () |
void | ClearSections () |
int | AddSection (int parent, const char *type) |
void | ClearFields () |
int | AddField (int section, const char *name, int line) |
void | AddFieldValue (int field, int index, int value_token) |
int | GetField (int section, const char *name) |
int | GetFieldValueCount (int field) |
const char * | GetFieldValue (int field, int index, bool flag_used=true) |
void | SetFieldValue (int field, int index, const char *value) |
uint32_t | LookupColor (const char *name) |
Private Attributes | |
int | token_size |
int | token_count |
Token * | tokens |
int | macro_size |
int | macro_count |
CMacro * | macros |
int | section_size |
int | section_count |
Section * | sections |
int | field_size |
int | field_count |
Field * | fields |
uint32_t | default_host |
uint32_t | default_robot |
double | unit_length |
double | unit_angle |
Classes | |
struct | CMacro |
struct | Field |
struct | Section |
struct | Token |
Member Function Documentation
void ConfigFile::InitFields | ( | ) | [private] |
For internal use only.
Intitialization helper
bool ConfigFile::Load | ( | const char * | filename | ) |
Load config from file.
- Parameters:
-
filename Name of file; can be relative or fully qualified path.
- Returns:
- Returns true on success.
void ConfigFile::InsertFieldValue | ( | int | index, | |
const char * | name, | |||
const char * | value | |||
) |
Add a (name,value) pair directly into the database, without reading from a file.
The (name,value) goes into the "global" section. Can be called multiple times with different index to create a tuple field.
- Parameters:
-
index Index of the value within the field (0 unless the field is a tuple) name Name of the field value Value to be assigned
bool ConfigFile::WarnUnused | ( | ) |
Check for unused fields and print warnings.
- Returns:
- Returns true if there are unused fields.
bool ConfigFile::ReadBool | ( | int | section, | |
const char * | name, | |||
bool | value | |||
) |
Read a boolean value (one of: yes, no, true, false, 1, 0).
- Parameters:
-
section Section to read. name Field name value Default value if this field is not present in the file
- Returns:
- Returns the field value
const char* ConfigFile::ReadString | ( | int | section, | |
const char * | name, | |||
const char * | value | |||
) |
Read a string value.
- Parameters:
-
section Section to read. name Field name value Default value if the field is not present in the file.
- Returns:
- Returns the field value.
int ConfigFile::ReadInt | ( | int | section, | |
const char * | name, | |||
int | value | |||
) |
Read an integer value.
- Parameters:
-
section Section to read. name Field name value Default value if the field is not present in the file.
- Returns:
- Returns the field value.
double ConfigFile::ReadFloat | ( | int | section, | |
const char * | name, | |||
double | value | |||
) |
Read a floating point (double) value.
- Parameters:
-
section Section to read. name Field name value Default value if the field is not present in the file.
- Returns:
- Returns the field value.
double ConfigFile::ReadLength | ( | int | section, | |
const char * | name, | |||
double | value | |||
) |
Read a length (includes unit conversion, if any).
- Parameters:
-
section Section to read. name Field name value Default value if the field is not present in the file.
- Returns:
- Returns the field value.
double ConfigFile::ReadAngle | ( | int | section, | |
const char * | name, | |||
double | value | |||
) |
Read an angle (includes unit conversion).
In the configuration file, angles are specified in degrees; this method will convert them to radians.
- Parameters:
-
section Section to read. name Field name value Default value if the field is not present in the file (radians).
- Returns:
- Returns the field value.
uint32_t ConfigFile::ReadColor | ( | int | section, | |
const char * | name, | |||
uint32_t | value | |||
) |
Read a color (includes text to RGB conversion).
In the configuration file colors may be specified with sybolic names; e.g., "blue" and "red". This function will convert them to an RGB value using the X11 rgb.txt file.
- Parameters:
-
section Section to read. name Field name value Default value if the field is not present in the file (RGB).
- Returns:
- Returns the field value.
const char* ConfigFile::ReadFilename | ( | int | section, | |
const char * | name, | |||
const char * | value | |||
) |
Read a filename.
Always returns an absolute path. If the filename is entered as a relative path, we prepend the config file's path to it.
- Parameters:
-
section Section to read. name Field name value Default value if the field is not present in the file.
- Returns:
- Returns the field value.
int ConfigFile::GetTupleCount | ( | int | section, | |
const char * | name | |||
) |
Get the number of values in a tuple.
- Parameters:
-
section Section to read. name Field name.
const char* ConfigFile::ReadTupleString | ( | int | section, | |
const char * | name, | |||
int | index, | |||
const char * | value | |||
) |
Read a string from a tuple field.
- Parameters:
-
section Section to read. name Field name index Tuple index (zero-based) value Default value if the field is not present in the file.
- Returns:
- Returns the tuple element value.
int ConfigFile::ReadTupleInt | ( | int | section, | |
const char * | name, | |||
int | index, | |||
int | value | |||
) |
Read an integer from a tuple field.
- Parameters:
-
section Section to read. name Field name index Tuple index (zero-based) value Default value if the field is not present in the file.
- Returns:
- Returns the tuple element value.
double ConfigFile::ReadTupleFloat | ( | int | section, | |
const char * | name, | |||
int | index, | |||
double | value | |||
) |
Read a float (double) from a tuple field.
- Parameters:
-
section Section to read. name Field name index Tuple index (zero-based) value Default value if the field is not present in the file.
- Returns:
- Returns the tuple element value.
double ConfigFile::ReadTupleLength | ( | int | section, | |
const char * | name, | |||
int | index, | |||
double | value | |||
) |
Read a length from a tuple (includes units conversion).
- Parameters:
-
section Section to read. name Field name index Tuple index (zero-based) value Default value if the field is not present in the file.
- Returns:
- Returns the tuple element value.
double ConfigFile::ReadTupleAngle | ( | int | section, | |
const char * | name, | |||
int | index, | |||
double | value | |||
) |
Read an angle form a tuple (includes units conversion).
In the configuration file, angles are specified in degrees; this method will convert them to radians.
- Parameters:
-
section Section to read. name Field name index Tuple index (zero-based) value Default value if the field is not present in the file.
- Returns:
- Returns the tuple element value.
uint32_t ConfigFile::ReadTupleColor | ( | int | section, | |
const char * | name, | |||
int | index, | |||
uint32_t | value | |||
) |
Read a color (includes text to RGB conversion).
In the configuration file colors may be specified with sybolic names; e.g., "blue" and "red". This function will convert them to an RGB value using the X11 rgb.txt file.
- Parameters:
-
section Section to read. name Field name index Tuple index (zero-based) value Default value if the field is not present in the file (RGB).
- Returns:
- Returns the field value.
int ConfigFile::ReadDeviceAddr | ( | player_devaddr_t * | addr, | |
int | section, | |||
const char * | name, | |||
int | code, | |||
int | index, | |||
const char * | key | |||
) |
Read a device id.
Reads a device id from the named field of the given section. The returned id will match the given code, index and key values.
- Parameters:
-
addr address field to be filled in. section File section. name Field name. code Interface type code (use 0 to match all interface types). index Tuple index (use -1 to match all indices). key Device key value (use NULL to match all key vales).
- Returns:
- Non-zero on error.
int ConfigFile::LookupSection | ( | const char * | type | ) |
Lookup a section number by section type name.
- Returns:
- Returns -1 if there is no section with this type.
int ConfigFile::GetSectionParent | ( | int | section | ) |
Get a section's parent section.
- Returns:
- Returns -1 if there is no parent.
The documentation for this class was generated from the following file: