ConfigFile Class Reference

#include <configfile.h>

List of all members.


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;
    }
  }
A driver can support more than interface of the same type. For example, the p2os driver supports 3 position2d interfaces: one for wheelmotors/odometry, one for compass, and one for gyro. In this case, the last argument to ReadDeviceAddr is used to differentiate them, according to key that was given in the "provides" line. For example, if in the configuration file we have:
driver
(
  name "mydriver"
  provides ["odometry:::position2d:0" "gyro:::position2d:1"]
)
then in the driver code we can do something like this:
  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)
 ConfigFile (const char *_default_host, uint32_t _default_robot)
 ~ConfigFile ()
bool Load (const char *filename)
bool WarnUnused ()
bool ReadBool (int section, const char *name, bool value)
const char * ReadString (int section, const char *name, const char *value)
int ReadInt (int section, const char *name, int value)
double ReadFloat (int section, const char *name, double value)
double ReadLength (int section, const char *name, double value)
double ReadAngle (int section, const char *name, double value)
uint32_t ReadColor (int section, const char *name, uint32_t value)
const char * ReadFilename (int section, const char *name, const char *value)
int GetTupleCount (int section, const char *name)
const char * ReadTupleString (int section, const char *name, int index, const char *value)
int ReadTupleInt (int section, const char *name, int index, int value)
double ReadTupleFloat (int section, const char *name, int index, double value)
double ReadTupleLength (int section, const char *name, int index, double value)
double ReadTupleAngle (int section, const char *name, int index, double value)
uint32_t ReadTupleColor (int section, const char *name, int index, uint32_t value)
int ReadDeviceAddr (player_devaddr_t *addr, int section, const char *name, int code, int index, const char *key)
bool ParseDriver (int section)
bool ParseAllDrivers ()
int GetSectionCount ()
const char * GetSectionType (int section)
int LookupSection (const char *type)
int GetSectionParent (int section)
void DumpTokens ()
void DumpSections ()
void DumpFields ()

Public Attributes

char * filename
 Name of the file we loaded.

Classes

struct  CMacro
struct  Field
struct  Section
struct  Token

Constructor & Destructor Documentation

ConfigFile::ConfigFile ( uint32_t  _default_host,
uint32_t  _default_robot 
)

Standard constructor

ConfigFile::ConfigFile ( const char *  _default_host,
uint32_t  _default_robot 
)

Alternate constructor, to specify the host as a string

ConfigFile::~ConfigFile (  ) 

Standard destructor


Member Function Documentation

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.

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::GetSectionCount (  ) 

Get the number of sections.

const char* ConfigFile::GetSectionType ( int  section  ) 

Get a section type name.

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.

void ConfigFile::DumpTokens (  ) 

Dump the token list (for debugging).

void ConfigFile::DumpSections (  ) 

Dump the section list for debugging

void ConfigFile::DumpFields (  ) 

Dump the field list for debugging


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

Last updated 12 September 2005 21:38:45