CConfigurationParameter

NSCL DAQ Software Documentation
Prev		Next

Synopsis


            CConfigurationParameter
             CConfigurationParameter (const std::string&  keyword)          throws ;
               std::string  getSwitch()          throws ;
               const std::string  getValue()          throws ;
                bool  Match (const std::string& rSwitch)          throws ;
             virtual   int    ; operator() (CTCLInterpreter& rInterp, CTCLResult& rResult, const char* parameter)          throws ;
              const std::string  getOptionString ()          throws ;
             virtual     = 0 int  SetValue (CTCLInterpreter& rInterp, CTCLResult& rResult, const char* pvalue)          throws ;
             virtual  = 0 std::string  GetParameterFormat()          throws ;
           
           CBoolConfigParam : public CConfigurationParameter
             CBoolConfigParam(const std::string& rName, bool fDefault =  = false)          throws ;
               bool  getOptionValue()          throws ;
             virtual  int SetValue(CTCLInterpreter& rInterp, CTCLResult& rResult, const char* pFlag)          throws ;
              virtual   std::string  GetParameterFormat()          throws ;
           
           CEnumParameter : public CConfigurationParameter
             CEnumParameter(std::string keyword, std::vector<CEnumParameter::enumeratorValue> values, std::string defaultValue);
             virtual   int  SetValue(CTCLInterpreter& rInterp, CTCLResult& rResult, const char* pValue)          throws ;  
             virtual   std::string  GetParameterFormat();()          throws ;  
                int  GetEnumValue()          throws ;  
        
            CIntArrayParam : public CConfigurationParameter
              CIntArrayParam(const std::string& rName, unsigned int size, int nDefault = = 0);
              CIntArrayParam(const std::string& rName, unsigned int size, int nLow, int nHigh, int nDefault = = 0);
               const int  getSize();
              const  const  int*  getValues ();
               const  bool  getCheckRange ();
               const int   getLow ();
               const  int  getHigh ();
                 int&         operator[] ( int n);
              virtual    int  SetValue(  CTCLInterpreter&  rInterp,  CTCLResult&  rResult, const  char*  pValues);
              virtual   std::string   GetParameterFormat();
                 void  setRange( int   nLow,  int  nHigh);
            
            CIntConfigParam : public CConfigurationParameter
              CIntConfigParam(const  std::string&  rName,  int  nDefault = =0);
              CIntConfigParam(const   std::string& rName,  int  nLow,  int  nHigh,  int  nDefault = =0);
               const   bool  getCheckrange();
               const  int  getLow();
               const  int  getHigh();
                int  getOptionValue()          throws ;
              virtual  int  SetValue (CTCLInterpreter&  rInterp, CTCLResult&  rResult, const char* pValue)          throws ;  
              virtual   std::string  GetParameterFormat()          throws ;  
                void  setRange(int nLo, int nHi)          throws ;

DESCRIPTION

CDigitizerModule objects include a database of configuration items managed by their base class SConfigurableObject. The items in this database are derived from the CConfigurableObject. The derived classes provide a strongly typed system of parameters. Each type can also have associated with it type specific constraints.

The remaining sections of this manpage describe the predefined members of the class hierarchy that is derived from CConfigurableObject. Sophisticated programmers can extend this hierarchy if needed.

`CConfigurationParameter`

This is the abstract base class of the parameter item hierarchy. It defines the programmatic interfaces all configuration parameters must implement:

CConfigurationParameter (const std::string& keyword) throws ;

Constructor for the named parameter keyword. The keyword is the parameter name used in e.g. config subcommands.

std::string getSwitch() throws ;

Returns the nameof the configuration option this object represents. Normally, this is the keyword parameter passed into the constructor.

const std::string getValue() throws ;

Returns the string representation of the value of the configuration item. All configuration items have a string representation. Derived classes may define an alternative representation as well. Typically a derived class will enforce the convertability of the string value to the alternative representation by overriding the SetValue method below. Derived classes will usually also provide a mechanism to access the alternative representation's natural form.

See also the GetParameterFormat method below.

bool Match (const std::string& rSwitch) throws ;

The configuration management pieces of SConfigurableObject determine which configuration item is being referred to by asking each item if it responds to a specific name. The Match method compares the parameter keyword passed in to the constructor to its rSwitch parameter and returns true if they are the same.

Presently this comparison is case sensitive.

virtual int ; operator() (CTCLInterpreter& rInterp, CTCLResult& rResult, const char* parameter) throws ;

Thie method is invoked when Match returns true as a result of a config subcommand. It invokes SetValue which is assumed to at least ensure the value can be translated to any internal representation and then stores the string representation of the value if successful.

On success TCL_OK is returned otherwise, TCL_ERROR is returned.

While derived classes can override this method normally they don't need to, and should not.

const std::string getOptionString () throws ;

This is synonymous with getValue

virtual = 0 int SetValue (CTCLInterpreter& rInterp, CTCLResult& rResult, const char* pvalue) throws ;

This is a pure virtual method that must be supplied by concrete derivations of this abstract base class. Normally, this method ensures that the string pointed to by pvalue is a legal value for the configuration parameter (both in type and any constraints that might be applied). Often this method actually converts and caches pvalue in the format appropriate to the type of the parameter (e.g. CIntConfigParam converts pvalue to an int).

rInterp is a reference to the interpreter that is executing the configuration command that invoked this. rResult is the intepreter result object which can be set to a value that, in the case of a normal return, will be the interpreter result and, in the case of a failure will be an error message.

A normal return is indicated by a return value of TCL_OK. A failed return is indicated by a return value of TCL_ERROR.

virtual = 0 std::string GetParameterFormat() throws ;

Derived classes should supply this method. It is expected to return a string that hints at the format of the parameter value. For example for an CIntArrayParam insstance with an array size of 16, the return value is int[16]

`CBoolConfigParam`

This is a concrete class derived from the CConfigurationParameter. The class constrains its values to be compatibile with boolean values. Acceptable true values are true, on and enable. Acceptable false values are false off and disable.

CBoolConfigParam(const std::string& rName, bool fDefault = = false) throws ;: The constructor for this class. rName is the name of the configuration parameter. fDefault is the initial value given to the parameter (in the event the configuration script never configures this parameter).
bool getOptionValue() throws ;: Returns the bool representation of the current parameter value.
virtual int SetValue(CTCLInterpreter& rInterp, CTCLResult& rResult, const char* pFlag) throws ;: Determines if the string pointed to by pFlag is a valid boolean value. If so the string and boolean representation are updated and TCL_OK is returned. If not, rResult is filled in with an error message and TCL_ERROR is returned.
virtual std::string GetParameterFormat() throws ;: Returns the string: on | off. Note that other representations are legal (see above).

`CEnumParameter`

This concrete subclass of CConfigurationParameer is represents a parameter that can hold one of a distinct set of strings. The class supports mapping each allowed string to an integer value. This supports direct conversion of a string to the contents of a register bit field.

CEnumParameter(std::string keyword, std::vector<CEnumParameter::enumeratorValues> values, std::string defaultValue);

Constructor. The keyword is the name of the parameter. values defines the legal values of the parameter and their mappings to integers. defaultValue is the default value and shoulid be one of the strings defined as legal by values

values is a vector containing CEnumParameter::enumeratorValues structs. This struct has the fields: std::string s_name which contains the string value of a legal parameter value and int s_value which is the integer value to which s_name should map.

CEnumParameter::enumeratorValue provides a constructor for convenience that has in order the requested values for s_name and s_value as parameters.

virtual int SetValue(CTCLInterpreter& rInterp, CTCLResult& rResult, const char* pValue) throws ;

Determines if the string pointed to by pValue is one of the legal s_name values for the enumerator. If so, the string value is saved and TCL_OK is returned. If not, TCL_ERROR is returned and rResult the interpreter result value is set to an informative error message.

virtual std::string GetParameterFormat();() throws ;

Returns a string that lists the legal value strings separated by the | character.

int GetEnumValue() throws ;

Returns the s_value field corresponding to the current string value of the parameter. Note that the base class getOptionString method can retrieve the raw string value.

CIntArrayParam

This is a concrete derived class whose instances hold arrays of integer values. The array values are passed in to the option as Tcl lists whose elements are then set in consecutive elements of the array. The list must always contain all values in the array.

CIntArrayParam(const std::string& rName, unsigned int size, int nDefault = = 0);

Constructs a parameter named rName. The parameter is an array of exactly size elements. The elements of the array are all initialized to nDefault.

CIntArrayParam(const std::string& rName, unsigned int size, int nLow, int nHigh, int nDefault = = 0);

This constructor has additional parameters that constrain the values of the array elements to be at least nLow and ad most nHigh. If any element is out of range no elements get modified.

Clearly nDefault should also satisfy this constraint.

const int getSize();

Returns the number of elements the array has. this is the value of the size parameter to the constructor.

const const int* getValues ();

Returns a pointer to an array of int values that are the contents of the array. Note that this is readonly and storage is managed by the object not by the caller.

const bool getCheckRange ();

If this returns true the parameter has a value range constraint defined. If false the contents of the array are not constrained.

const int getLow ();

Returns the low limit set at construction time. if getCheckRange returns false the value retured is undefined.

const int getHigh ();

Returns the high limit set at construction time. if getCheckRange returns false the value retured is undefined.

int& operator[] ( int n);

Provides indexing into the array of values. Note that this method supports indexing both for lvalues and rvalues (that is on the left or right side of an assignment).

virtual int SetValue( CTCLInterpreter& rInterp, CTCLResult& rResult, const char* pValues);

If pValues points to a valid Tcl list whose elements are integers and, if range checking, all elements satisfy the range constraints, the array elements are replaced with the elements of that list. Note that the list must also have the correct number of elements.

On success, the method returns TCL_OK if any of the restrictions described above are not satisfied, the method returns TCL_ERROR and rResult is set with a human meaningful error message. The rInterp interpreter is used to parse the list.

virtual std::string GetParameterFormat();

Returns a string of the form: int[n] where n is the array size.

void setRange( int nLow, int nHigh);

Sets a new range constraint on the values of the array. Note that this does not check the value of the array against the new constraint. If you call this method after the array may have been assigned values you may want to reset the array to a legal default value, or set of values.

`CIntConfigParam`

This class is a concrete class that represents a single integer valued parameter. The parameter can optionally have range constraints applied to its value.

CIntConfigParam(const std::string& rName, int nDefault = =0);: Constructs an integer configuration parameter with no range constraint. rName is the name of the parameter and its initial value is nDefault.
CIntConfigParam(const std::string& rName, int nLow, int nHigh, int nDefault = =0);: Creates an integer parameter whose value is constrained to be at least nLow and at most nHigh.
const bool getCheckrange();: This method returns true if the parameter has a range constraint defined. Range constraints can be defined either at construction time or by invoking the setRange method after the object is constructed. If no range constraint is in place this method returnes false.
const int getLow();: Returns the low limit of the range constraint on the parameter. If no range constraint has been set (getCheckRange returns false), the value returned from this method has no meaning.
const int getHigh();: Returns the upper limit of the range constraint set on the parameter. If no range constraint has been set, the return value from this method is meaningless.
int getOptionValue() throws ;: Returns the current value of the configuration parameter as an integer.
virtual int SetValue (CTCLInterpreter& rInterp, CTCLResult& rResult, const char* pValue) throws ;: Called by the configuration manager to attempt to provide a new value for the parameter. If pValue points to a string that converts to an integer and, if the parameter has a range constraint, satisfies the range constraint, the parameter value is modified and TCL_OK is returned. If not TCL_ERROR is returned and a human readable error message is set in rResult.
virtual std::string GetParameterFormat() throws ;: Returns the string int indicating that parameters of this type expect integer values.
void setRange(int nLo, int nHi) throws ;: Sets a new range constraint from nLo as the lower limit and nHi as the upper limit.

Prev	Home	Next
CDigitizerModule	Up	SConfigurableObject

CConfigurationParameter

Name

Synopsis

DESCRIPTION

CConfigurationParameter

CBoolConfigParam

CEnumParameter

CIntArrayParam

CIntConfigParam

SEE ALSO

`CConfigurationParameter`

`CBoolConfigParam`

`CEnumParameter`

`CIntConfigParam`