ConfigFile Class Reference
Class for loading configuration file information. More...
#include <configfile.h>
Classes | |
struct | CMacro |
struct | Field |
struct | Section |
struct | Token |
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 () | |
Standard destructor. | |
bool | Load (const char *filename) |
Load config from 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 | ParseAllDrivers () |
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. |
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.
Member Function Documentation
int ConfigFile::GetSectionParent | ( | int | section | ) |
Get a section's parent section.
- Returns:
- Returns -1 if there is no parent.
int ConfigFile::GetTupleCount | ( | int | section, | |
const char * | name | |||
) |
Get the number of values in a tuple.
- Parameters:
-
section Section to read. name Field name.
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.
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.
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.
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
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.
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.
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.
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.
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::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.
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.
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.
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.
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::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.
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.
bool ConfigFile::WarnUnused | ( | ) |
Check for unused fields and print warnings.
- Returns:
- Returns true if there are unused fields.
The documentation for this class was generated from the following file: