CItemConfiguration Class Reference

#include <CItemConfiguration.h>

Classes
struct	_isListParameter
struct	_ListSizeConstraint
struct	flimit
struct	limit

Public Types
typedef std::pair< typeChecker, void * >	TypeCheckInfo
typedef std::vector< std::pair< std::string, std::string > >	ConfigurationArray
typedef std::pair< limit, limit >	Limits
typedef std::set< std::string >	isEnumParameter
typedef struct CItemConfiguration::_ListSizeConstraint	ListSizeConstraint
typedef struct CItemConfiguration::_isListParameter	isListParameter
typedef std::pair< flimit, flimit >	FloatingLimits

Public Member Functions
	CItemConfiguration (std::string name)
	CItemConfiguration (const CItemConfiguration &rhs)
virtual	~CItemConfiguration ()
CItemConfiguration &	operator= (const CItemConfiguration &rhs)
int	operator== (const CItemConfiguration &rhs) const
int	operator!= (const CItemConfiguration &rhs) const
std::string	getName () const
std::string	cget (std::string name)
ConfigurationArray	cget ()
int	getIntegerParameter (std::string name)
unsigned int	getUnsignedParameter (std::string name)
bool	getBoolParameter (std::string name)
double	getFloatParameter (std::string name)
std::vector< int >	getIntegerList (std::string name)
void	addParameter (std::string name, typeChecker checker, void *arg, std::string defaultValue=std::string(""))
void	clearConfiguration ()
bool	isValid (std::string name, std::string value)
void	configure (std::string name, std::string value)

Static Public Member Functions
static bool	isInteger (std::string name, std::string value, void *arg)
static bool	isBool (std::string name, std::string value, void *arg)
static bool	isEnum (std::string name, std::string value, void *arg)
static bool	isFloat (std::string name, std::string value, void *arg)
static bool	isList (std::string name, std::string value, void *arg)
static bool	isBoolList (std::string name, std::string value, void *arg)
static bool	isIntList (std::string name, std::string value, void *arg)
static bool	isStringList (std::string name, std::string value, void *arg)

Detailed Description

An Item configuration is a set of name value pairs. Each name value pair can have an associated validity checker who is responsible for ensuring that for any configuration value a candidate new value is legal. Type checkers are just unbound functions, or static member functions. See the typedef for typeChecker above.

For convenience, some of the static functions of this class provide commonly used type checkers.

How to use this:

In general, one would create an object that contains a CItemConfiguration object. That object would provide mechanisms to set/get the configuration. The object itself, would register the configuration names it needs. It would, in appropriate methods, get the values of the configuration names.

See e.g. CConfigurableObject for a base class that can be used and that has those properties.

The configuration subsystem would at some point call configure to set up the configuration (note subclassed objects can also call this to set up their default configuration).

The data taking system would then call subclass functions to inform it that configuration is complete. The subclass then would call cget to get and react to its configuration.

This class does not implement any policy about how the configuration is gotten. This can be done by manual parsing of data files, by internal data structures, by a Tcl interpreter reading scripts or any other practical means.

Constructor & Destructor Documentation

CItemConfiguration()

CItemConfiguration::CItemConfiguration

(

const CItemConfiguration &

rhs

)

Copy construction. We can just copy the name and map. Copy construction should be rare as normally names are unique.

~CItemConfiguration()

CItemConfiguration::~CItemConfiguration ( )

virtual

Destruction probably will result in some memory leaks since it is possible that the typeChecker's will have parameters that are dynamically allocated. In a future life we can provide cleanup functions.. for now we just assume that destruction will be infrequent, and leaks will be small enough to be tolerated.

I think that destruction is not necessary since all the pairs will copyconstruct/assign into the map. This is a place holder for later code that can handle deletion of the typechecker args.

Member Function Documentation

addParameter()

void CItemConfiguration::addParameter	(	std::string	name,
		typeChecker	checker,
		void *	arg,
		std::string	defaultValue = std::string("")
	)

Adds a configuration parameter to the configuration. If there is already a configuration parameter by this name, it is silently ovewritten.

Parameters

name	: std::string Name of the parameter to add.
checker	: typeChecker A type checker to validate the values proposed for the parameter, if NULL, no validation is performed.
arg	: void Parameter passed without interpretation to the typechecker at validation time.
defaultValue	: string (default = "") Initial value for the parameter.

cget()

CItemConfiguration::ConfigurationArray CItemConfiguration::cget

(

)

Get the values of all the configuration parameters.

Returns

CCOnfigurableObject::ConfigurationArray

Return values

A	vector of parameter name/value pairs. Given an element, ele of the vector, ele.first is the parameter name, ele.second the value.

Note

While at present, the parameters come out sorted alphabetically, you should not count on that fact.

clearConfiguration()

void CItemConfiguration::clearConfiguration

(

)

clear the current configuration. The configuration map m_parameters map is emptied.

configure()

void CItemConfiguration::configure	(	std::string	name,
		std::string	value
	)

Configure the value of a parameter.

Parameters

name	: std::string Name of the parameter to configure.
value	: std::string New value of the parameter

Exceptions

std::string("No

such parameter") if the parameter 'name' is not defined. \throw std::string("Validation failed for 'name' <- 'value'") if the value does not pass the validator for the parameter.

getBoolParameter()

bool CItemConfiguration::getBoolParameter

(

std::string

name

)

Return the value of a bool parameter. This uses the same set of true values as the checker.. however any other value is assumed to be false.

Parameters

name	: std::string Name of the value.

Returns

bool

Return values

the	boolean equivalent of the config param

getFloatParameter()

double CItemConfiguration::getFloatParameter

(

std::string

name

)

Return a parameter decoded as a double.

Parameters

name	: std::string Name of the parameter

Returns

double

getIntegerList()

vector< int > CItemConfiguration::getIntegerList

(

std::string

name

)

Return a parameter that is a list of integers.

Parameters

name	- name of the parameter.

Returns

vector<int>

Return values

Vector

containing the integers in the list.

getIntegerParameter()

int CItemConfiguration::getIntegerParameter

(

std::string

name

)

Return the value of an integer parameter.

Parameters

name	: std::string Name of the value.

Returns

int

Return values

the	integer equivalent of the config paramter.

getName()

string CItemConfiguration::getName

(

)

const

Returns

string

Return values

The	name of the object.

getUnsignedParameter()

unsigned int CItemConfiguration::getUnsignedParameter

(

std::string

name

)

Same as above but for an integer. Needed because strtol for something bigger than MAXINT returns MAXINT.

isBool()

bool CItemConfiguration::isBool ( std::string  name, std::string  value, void *  arg  )

static

Validate a bool parameter. Bool parameters have any of the values:

• true: true, yes, 1, on, enabled
• false: false, no, 0, off, disabled We'll just delegate this off to isEnum.

  Parameters

  name	: std::string Name of the parameter
  value	: std:: string proposed new value.
  ignored	: void* Ignored value parameter.

  Returns

  bool

  Return values

  true	If valid.
  false	If invalid.

isBoolList()

bool CItemConfiguration::isBoolList ( std::string  name, std::string  value, void *  arg  )

static

Check that a list is a valid bool list. This is done by constructing the listValidity object with a list element checker set to the bool element checker.

Parameters

name	: std::string Name of the parameter.
value	: std:: string Proposed new value.
sizes	: void* Actually a pointer to ListSizeConstraint if non null: If NULL elements are checked for validity but any list size is ok. If non NULL elements are checked for validity and Limits set the limits on size.

Returns

bool

Return values

true	List validates.
false	List is not valid.

isEnum()

bool CItemConfiguration::isEnum ( std::string  name, std::string  value, void *  arg  )

static

Validate an enum parameter. An enumerated parameter is one that can be a string drawn from a limited set of keywords. Validation fails of the string is not one of the valid keywords.

Parameters

name	: std::string Name of the parameter.
value	: std::string Proposed parameter value.
values	: void* Actually an std::set<string>* where the set elements are the valid keywords.

Returns

bool

Return values

true	If valid.
false	If invalid.

isFloat()

bool CItemConfiguration::isFloat ( std::string  name, std::string  value, void *  arg  )

static

Validate a floating point parameter. Floating parameters allow the implementor of a device to let the user specify values in 'real units' which are then converted transparently to device register values. Floating point values are actually handled as doubles, since C/C++ likes to upconvert floats to doubles in any event. The conversion fails if the string does not convert to a floating point value or the etire string is not used in the conversion. NAN's are also considered invali, and isnan is used to determine if the conversion resulted in an NAN.

The application can place limits on the floating point value as well. See the parameters below:

Parameters

name	: std::string Parameter name (ignored).
value	: std::string The value of the paramter.
values	: void* Actually a ppointer to a FloatingLimits type which sets the limits on the parameter. If the FloatingLimits type is NULL, all floating values are allowed...except for NAN's... which are never allowed.

Returns

bool

Return values

true	- if Valid.
false	- if not Valid.

isInteger()

bool CItemConfiguration::isInteger ( std::string  name, std::string  value, void *  arg  )

static

Validate an integer parameter with optional limits.

Parameters

name	: std::string Name of the parameter being checked (ignored).
value	: std::string Proposed new value.
arg	: void* This is actually a pointer to an Limits structure or NULL. If NULL, no range checking is done. If not null, range checking is done. Each limit contains a checkme flag which allows validation to occur when one or both limits are needed. limits are inclusively valid.

Returns

bool

Return values

true	- Validation passed.
false	- Validation failed.

isIntList()

bool CItemConfiguration::isIntList ( std::string  name, std::string  value, void *  arg  )

static

Check that this is a valid list of integers. For string lists in this implementation we are not able to do range checking on the values of the list elements. We do, however enforce the integer-ness of each element of the list.

Parameters

name	: std::string Name of the parameter.
value	: std::string Proposed value of the parameter.
sizes	: void* Actually a pointer to a ListSizeConstraint which, if non null places constraints on the number of elements in the list.

Returns

bool

Return values

true	- List validated.
false	- List not validated

Todo:

Extend the parameter to us to supply optional limit information.

isList()

bool CItemConfiguration::isList ( std::string  name, std::string  value, void *  arg  )

static

Validate a list parameter. To simplify; a list parameter is a Tcl formatted list. List validation can fail for the following reasons:

• The value is not a properly formatted list.
• The value has too many list elements.
• The value has too few list elements.
• One or more of the list elements fails validation.

  Parameters

  name	: std::string Name of the parameter being modified.
  value	: std::string Value proposed for the parameter.
  validity	: void* Actually an optional pointer to an isListParameter: If validity is NULL, no size or element validity checking is done. If validity is non-null, it's s_allowedSize element is used to validate the list size, and if the s_checker.first is not null, it is used to validate the list elementss.

  Returns

  bool

  Return values

  true	List is valid.
  fals	List is invalid.

isStringList()

bool CItemConfiguration::isStringList ( std::string  name, std::string  value, void *  arg  )

static

Check for a string list. String lists are allowed to have just about anything as element values...therefore, if the validSizes parameter is present, we'll do list size checking only, otherwise on list syntax checking.

Parameters

name	: std::string Name of the parameter being modified.
value	; std::string proposed new value for the parameter.
validSizes	: void* Actually a pointer to a ListSizeConstraint structure that, if non-null defines the list size checking that will take place. If NULL, any sized list (including empty) is allowed.

Returns

bool

Return values

true	- List validated.
false	- List not validated

isValid()

bool CItemConfiguration::isValid	(	std::string	name,
		std::string	value
	)

Returns true if a proposed configuration is valid. This will still throw if the name is not defined... but will

Returns

bool

Return values

true	- The proposed configuration is acceptable.
false	- The proposed configuration is not acceptable.

Parameters

name	- of the parameter to validate.
value	- Proposed new value.

operator!=()

int CItemConfiguration::operator!=

(

const CItemConfiguration &

rhs

)

const

Inequality is the logical inverse of equality:

operator=()

CItemConfiguration & CItemConfiguration::operator=

(

const CItemConfiguration &

rhs

)

Assignement is similar to copy construction:

operator==()

int CItemConfiguration::operator==

(

const CItemConfiguration &

rhs

)

const

Equality is via item comparison.

---

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

• libtclplus/include/tclplus/CItemConfiguration.h
• libtclplus/tclplus/CItemConfiguration.cpp