DisplayOptions.h

Classes

DisplayOptions -- Class to provide option parsing routines for display classes. (full description)

class DisplayOptions

Interface

Public Members

DisplayOptions()

virtual ~DisplayOptions()

template <class T> Bool readOptionRecord(T<T> &target, Bool &error, const Vector &rec, const Record &fieldname) const

template <class T> Bool readOptionRecord(T &target, Bool &error, const T &rec, const Record &fieldname) const

virtual Bool readOptionRecord(String &target, Bool &unsetTarget, Bool &error, const Record &rec, const String &fieldname) const

Record unset() const

Bool isUnset(const Record &rec) const

Protected Members

DisplayOptions(const DisplayOptions &other)

void operator=(const DisplayOptions &other)

Private Members

Bool compatible(const DataType &compareme, const DataType &tome) const

Description

Review Status

Reviewed By:

Peter Barnes

Date Reviewed:

1999/10/27

Programs:

Tests:

tDisplayOptions

Prerequisite

Record

Etymology

DisplayOptions contains methods for parsing "Options" for various "Display" classes.

Synopsis

DisplayOptions is a simple class which provides methods for parsing Records containing fields which conform to "options" as used in the Display Library classes. Consider a record having the following structure:

    rec.minimum.value = 4.0
    rec.minimum.otherfield = "some text"
    rec.maximum = 8.0

The DisplayOptions methods can be used to extract the values of the minimum and maximum fields of the Record rec, regardless of whether the value itself is stored in a value sub-field, or at the next higher level. The DisplayOptions methods also offer the capability to detect "unset" Record values.

This class can be used as-is, or inherited from by higher-level classes.

Example

The following example shows the use of DisplayOptions as a stand-alone class.

    /* assume some Record "rec" is to be parsed */
    DisplayOptions dopt;
    Bool error;
    
    Float min = 0.0;
    if (dopt.readOptionRecord(min, error, rec, "minimum") && !error) {
      cerr << "minimum found and changed, new value is " << min << endl;
    }
    
    String color;
    Bool colorIsUnset = False;
    if (dopt.readOptionRecord(color, colorIsUnset, error,
                              rec, "color") && !error) {
      if (colorIsUnset) {
        cerr << "color found and unset" << endl;
      } else {
        cerr << "color found and changed, new value is " << color << endl;
      }
    }

Motivation

Options are used prolifically throughout the display classes, so some unified processing of options is desirable.

Thrown Exceptions

None.

To Do

add unset support for Bool, Float and Int types

Member Description

DisplayOptions()

Constructor.

virtual ~DisplayOptions()

Destructor.

template <class T> Bool readOptionRecord(T<T> &target, Bool &error, const Vector &rec, const Record &fieldname) const
template <class T> Bool readOptionRecord(T &target, Bool &error, const T &rec, const Record &fieldname) const

Find the field fieldname in Record rec, containing the requested type (Bool, String, Float, Int) in itself or its "value" sub-field, and return the value in target. If the field doesn't exist, or does not contain the requested type, or a "value" sub-field containing the requested type, then error is set True. When error is False, the return value indicates whether target was modified. The Float version will also read records containing Ints or Doubles, and cast their value to Float.

virtual Bool readOptionRecord(String &target, Bool &unsetTarget, Bool &error, const Record &rec, const String &fieldname) const

Find the field fieldname in Record rec, containing the requested type (String) in itself or its "value" sub-field, and return the value in target. If the field (or "value" sub-field) instead contains an "unset" Record, then unsetTarget is set True. If the field doesn't exist, or does not contain the requested type (String) or an "unset" Record, or a "value" sub-field containing either of these, then error is set True. When error is False, the return value indicates whether target (or unsetTarget) was modified.

Record unset() const

Return a Record which is an "unset" Record, ie. has a field with name String("i_am_unset") whose value is String("i_am_unset").

Bool isUnset(const Record &rec) const

Return True or False indicating if the provided Record is equal to an "unset" Record.

DisplayOptions(const DisplayOptions &other)

(Required) copy constructor.

void operator=(const DisplayOptions &other)

(Required) copy assignment.

Bool compatible(const DataType &compareme, const DataType &tome) const

A utility to check if two types are compatible. (I.e. double is "compatible" with int. Used by readOptionRecord.