NSCL DAQ Software Documentation
PrevNext

CItemConfiguration

Name

CItemConfiguration -- Hold a configuration

Synopsis


#include <CItemConfiguration.h>
         
 class CItemConfiguration {

  CItemConfiguration(std::string name);
  CItemConfiguration(const CItemConfiguration& rhs);

  virtual ~CItemConfiguration();

  CItemConfiguration& operator=(const CItemConfiguration& rhs);
  const int operator==(const CItemConfiguration& rhs);
  const int operator!=(const CItemConfiguration& rhs);
  const std::string getName();
  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();
  void configure(std::string name, std::string value);
  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);
}

Description

CItemConfiguration captures the configuration of an item. A configuration is a set of name-value pairs.

While the values are all stored as strings, validators and type safe 'getters' allow you to store strictly typed data as well. A validator is a function that is called to ensure a proposed new value for a parameter is suitable for the parameter. Validators are described in "Types and public data" below. A rich set of pre-defined validators should meet most needs, however it is possible to write and use custom validators should the built in ones be insufficient for your application.

Public member functions

CItemConfiguration(std::string name);

Constructs the configuration. name is just any string you'd like to associate with the configuration. getName can be used to fetch the value of this string. Names are used with collections of configurations when they may be inserted in an STL Map with the item name as the lookup key.

CItemConfiguration(const CItemConfiguration& rhs);

Copy construction. Note that if your application causes copy construction several configurations with the same name can be be created. If you want to ensure that copy construction can't exist, us a class derived from this in which the copy constructor is declared private but never implemented.

virtual ~CItemConfiguration();

Destructor.

CItemConfiguration& operator=(const CItemConfiguration& rhs);

Assignment operator. Note that in the presence of named configuration items, this can result in objects with duplicate names. To avoid this derive from this class and set the = operator to be private...without ever Implementing it.

const int operator==(const CItemConfiguration& rhs);

Compares two objects for equality. Equality is defined as having the same name, same set of configuration items with matching values.

const int operator!=(const CItemConfiguration& rhs);

Inequality test operator is the logical inverse of equality.

const std::string getName();

Returns the name string used to construct the object.

std::string cget(std::string name);

Returns the string value of the configuration parameter name. If the name is not a defined configuration parameter, this will throw an explanatory string exception. See addParameter for information about how to define configuration parameters.

ConfigurationArray cget();

Returns a container ConfigurationArray that provides the entire configuration. See "Types and public data" for more information about the ConfigurationArray data type.

int getIntegerParameter(std::string name);

Returns the value of a parameter name converted to an integer. This can throw an explanatory string exception either if name is not a defined parameter or if its current value does not translate to an integer (using strtoul). Typically name should have been defined with a validator that will make sure the value will always be a legal integer.

unsigned int getUnsignedParameter(std::string name);

Same as getIntegerParameter however strtoul is used to convert the string ot an unsigned value. Once more the configuration parameter name should have a validator attached to it to ensure that the value always represents a legal unsigned integer.

bool getBoolParameter(std::string name);

Returns the value of name as a boolean. This will throw a descriptive string exception if name is not a define configuration parameter or if the value is not one of true, yes, 1, on, or enabled for true and false, no, 0, off or disabled for false.

double getFloatParameter(std::string name);

Returns the value of a parameter name as a floating point double value. If the parameter cannot be decoded as a floating point number a string exception is thrown that describes this.

std::vector<int> getIntegerList(std::string name);

Returns a parameter name that is supposed to be a list of integers. The list is returned as a std::vector<int>. A string exception is thrown describing the error in the event that either the parameter value is not a valid Tcl list or any of the values does not decode as an integer.

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

Defines a new configuration parameter. The value of this configuration parameter is modified by calling configure below. name is the name of the new parameter. This parameter definition is ovewritten if it already exists.

checker is a validation function that will be called to approve or disapprove of changes to the configuration value. Passing a NULL for checker disables value checking. arg is a parameter passed to the type checker. See "Types and public data " below for a definition of the typeChecker function prototype.

default is the initial value of the parameter. This defaults to the empty string. Note that default is not passed through the checker, so it is up to the definer to ensure this value is a legal value for the functions used to fetch it from the parameter.

void clearConfiguration();

Destroys all parameter definitions. After this is called, no configuration parameters are defined.

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

Modifies the value of the configuration parameter name to value. If either the parameter name has not been defined, or value fails checking, a string exception is thrown to describe in human terms the problem.

Types and public data

This class exports several public data types. For the sake of brevity only the final typename is give, therefore, when you use a type like ConfigurationArray remember that it must be qualified with the CItemConfiguration class name (e.g. referred to in your source code as CItemConfiguration::ConfigurationArray)

One type is exported in the global (unqualified) namespace, this is typeChecker which defines the function prototype for a configuration parameter validity checker. The prototype of this function is:

bool (*typeChecker)(std::string name, std::string value, void* arg);

Type checkers are registered when a configuration parameter is created via addParameter. When configure is called and the parameter has a type checker it is called. name is the name of the configuration parameter being configured, value is the proposed new value for the parameter.

arg is the arg parameter specified in the call to addParameter that created the configuration parameter in the first place. Usually this is some additional information required to validate the proposed value.

The function must return true in the event the proposed value is acceptable and false if not.

ConfigurationArray

This type is defined as std::vector<std::pair<std::string, std::string> >. This is a vector that contains pairs of strings. The first string of each pair is the name of a configuration parameter. The second string is the configuration parameter's current value. This type is returned from one of the overloaded cget methods.

You cannot make any assumption about the order of the parameters in this array.

Pre-defined type checkers and related data types

This section describes type checkers that are defined as static member functions of the CItemConfiguration class. Each type checker's arg is also described along with a description of the checker.

Prior to writing your own type checker you should ensure that a suitable one does not already exist.

For all of the type checkers the parameters have the same names an meanings:

std::string name

Name of the configuration parameter being checked.

std::string value

The proposed new value for the configuration parameter. This is the value to be checked by the validation function.

void* arg

This anonymous pointer points to data that is used to further qualify type checking. For exmaple. Integer type checkers can specify optional limits on the range of integers that are acceptable, for isInteger, therefore arg is actually a pointer to a data structure that specifies limit information.

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

Ensures that value is a legal integer value. The arg parameter is a pointer to a Limits type. This is a std::pair<limit, limit>. Each limit defines a limit on the range of acceptable values. The first one defines the lower end of the range, the second the high end of the range.

If arg is NULL no limit checking is performed.

The limit is, in turn a struct that has the following members: 


                bool s_checkMe;          // Check this limit if true
                long s_value             // Limit value

The limit structure also defines two construtors: limit()(); Defines a limit structure with s_checkMe initialized to false (that is a limit that will not be checked). limit(long value); defines a limit with s_checkMe set to true and s_value initialized to value.

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

This type checker ensures that the proposed value is a legal boolean value. isBool does not use its arg parameter. Legal boolean values are any text strings from the following set: {true, yes, 1, on, enabled, false, no, 0, off, disabled}. Any string not in this set results in a failed type check.

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

This is a type checker for enumerated parameters. An enumerated parameter is a parameter that is constrained to have specific discrete values (A boolean is a special case of an enumerated parameter). The arg value is required and must be a pointer to an std::set<string>. The elements you put in this set define the allowed values for value.

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

Checks that value decodes as a floating point number and optionally peforms limit checks on the value.

arg is a pointer to a FloatingLimits. FloatingLimits in turn is defined to be a std::pair<flimit, flimit>. The first flimit of the pair specifies the lower limit if any, while the second specifies the upper limit. If arg is NULL no limit checking is performed.

flimit is a struct that has the following members

Data members of flimit are: 


bool   s_checkMe;        // If true limit is checked.
float  s_value;          // Limit value.

If s_checkMe is true, then s_value is relevant and is the value of the limit.

flimit defines a pair of constructors:

flimit();

Initializes s_checkMe to false disabling the limit.

flimit(float value);

Initializes s_checkMe to true and sets s_value to value. This enables the limit and sets it's value to value.

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

This validation function ensures tht the proposed parameter is a properly formatted Tcl list. arg, if supplied, allows the list size to be constrained and optionally elements of the list to be validated. If NULL no constraints are enforced on the contents of the list.

arg if not NULL is a pointer to a isListParameter struct which contains the following fields: 


ListSizeConstraint  s_allowedSize;   // Constraints on list size.
TypeCheckInfo       s_checker;       // Element type checker.

s_allowedSize constrains the number of elements in a list. It is of type ListSizeConstraint which is a struct containing two limit element; s_atLeast which describes the minimum number of elements the list must contain and s_atMost which specifies the maximum numbger of elements the list must contain. See the isInteger function description above for more information about the limit type.

s_checker, of type TypeCheckInfo allows each element of the list to be validated (e.g. to require that a list contain integers that are all within some range). TypeCheckInfo is a std::pair<typeChecker, void*>. Where the typeChecker function is given each list value to validate and the void* element of the pair is the arg parameter passed to that validator. If TypeCheckInfo is NULL no per element validation is performed, however the list size can be constrained.

When elements are validated, the name parameter passed to the element validator is the name of the configuration parameter that contains the list. The value parameter is the proposed value of a list element.

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

This is a specialization of isList. arg shoule be either be a pointer to a ListSizeConstraint to constrain the number of elements in the list or NULL to keep the size unsconstrained. The method passes each list element through isBool to ensure that the list contains only boolean values.

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

This is a specialization of the isList function. arg should either be a pointer to a ListSizeConstraint or it should be a NULL. If arg is NULL, the size of the list is unconstrained. If not, the ListSizeConstraint is used to validate the size of the list.

The list items are checked via isInteger to be sure they are legal integers. No capability to set limits on the integer values is provdided for at this time.

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

This is a specialization of isList. Any string is allowed as a list item (if it has the necessary quoting to maintain legal Tcl list syntax). If not NULL, arg is a poitner to a ListSizeConstraint which can limit the number of elements in the list. If NULL no list size constraint is enforced.

Exceptions

In the event of error, the class thows exceptions of type std::string. The contents of the string are a human readable message that explains the problem and when it was detected.

SEE ALSO

CConfigurableObject(3tcl)

PrevHomeNext
CTCLPackagedObjectProcessorUpCConfigurableObject