ConfigFile Class Reference

#include <configfile.h>

Collaboration diagram for ConfigFile:

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.

Definition at line 184 of file configfile.h.

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)

Parameters:

addr

address field to be filled in.

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

For internal use only.

Intitialization helper

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

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

Referenced by Alsa::Alsa().

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.

Referenced by Alsa::Alsa(), CameraUvc::CameraUvc(), ClodBuster::ClodBuster(), ER::ER(), Erratic::Erratic(), Khepera::Khepera(), P2OS::P2OS(), REB::REB(), RFLEX::RFLEX(), SegwayRMP::SegwayRMP(), SphereDriver::SphereDriver(), and wbr914::wbr914().

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.

Referenced by AdaptiveMCL::AdaptiveMCL(), Alsa::Alsa(), ER::ER(), Erratic::Erratic(), GarciaDriver::GarciaDriver(), Khepera::Khepera(), AMCLLaser::Load(), AMCLImu::Load(), AMCLGps::Load(), P2OS::P2OS(), RFLEX::RFLEX(), SphereDriver::SphereDriver(), StatGrabDriver::StatGrabDriver(), and wbr914::wbr914().

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.

Referenced by ER::ER(), Erratic::Erratic(), GarciaDriver::GarciaDriver(), Khepera::Khepera(), AMCLLaser::Load(), P2OS::P2OS(), and RFLEX::RFLEX().

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.

Referenced by Erratic::Erratic(), AMCLLaser::Load(), P2OS::P2OS(), and SegwayRMP::SegwayRMP().

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.

Referenced by Erratic::Erratic(), AMCLImu::Load(), P2OS::P2OS(), and SegwayRMP::SegwayRMP().

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.

Referenced by GarciaDriver::GarciaDriver().

int ConfigFile::GetTupleCount	(	int	section,
		const char *	name
	)

Get the number of values in a tuple.

Parameters:

	section	Section to read.
	name	Field name.

Referenced by Alsa::Alsa().

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.

Referenced by Alsa::Alsa().

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.

Referenced by CameraUvc::CameraUvc(), and SphereDriver::SphereDriver().

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.

Referenced by Khepera::Khepera(), AMCLOdom::Load(), AMCLGps::Load(), P2OS::P2OS(), and RFLEX::RFLEX().

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
	)

Parameters:

addr

address field to be filled in.

Parameters:

	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.

Referenced by AdaptiveMCL::AdaptiveMCL(), ER::ER(), Erratic::Erratic(), GarciaDriver::GarciaDriver(), ImageBase::ImageBase(), Khepera::Khepera(), LaserTransform::LaserTransform(), AMCLLaser::Load(), MapTransform::MapTransform(), P2OS::P2OS(), RFLEX::RFLEX(), SegwayRMP::SegwayRMP(), SphereDriver::SphereDriver(), StatGrabDriver::StatGrabDriver(), and wbr914::wbr914().

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:

configfile.h

Last updated 12 September 2005 21:38:45