cdlcore.hxx

eCos1.31版

// ----------------------------------------------------------------------------
// Update support.
//
// When there is a change to a node and there are references to that node,
// the referencing properties will want to be informed about this. There
// are various different kinds of changes, not all of which are always
// relevant. For example, if a CDL entity gets destroyed or unloaded then
// all referencing entities are likely to want to know about this, but
// if a container's value changes then this has no effect on a reference
// in e.g. a "parent" property. In some cases it is also useful to apply
// updates to nodes rather than properties, e.g. when a node becomes
// active or inactive.
//
// The generic update code is also used for initialization and finalization,
// i.e. when the source object itself has just been loaded or is
// being unloaded.
//
// For any particular update at most one bit set, but it is often
// appropriate to treat several different kinds of update with
// common code. Hence the enum values can be or'ed and and'ed.

enum CdlUpdate {
    CdlUpdate_Loaded            = 0x0001,       // The source has just been loaded
    CdlUpdate_Init              = 0x0002,       // Second-phase of a load operation
    CdlUpdate_Unloading         = 0x0004,       // The source is being unloaded
    CdlUpdate_Created           = 0x0008,       // The destination has just been created
    CdlUpdate_Destroyed         = 0x0010,       // The destination is being destroyed
    CdlUpdate_ValueChange       = 0x0020,       // The destination's value has changed.
                                                // This gets applied to nodes as well                   
    CdlUpdate_ActiveChange      = 0x0040        // The node has become active or inactive
};

// ----------------------------------------------------------------------------
// Inference engine callback.
//
// During a transaction there may be one or more invocations of the inference
// engine, followed by a callback which should display the current transaction
// status to the user and allow one or more recommended fixes to be accepted.
// The callback's return code indicates what should happen next. "Cancel"
// is pretty obvious. "Continue" may result in a commit, or it may result in
// another iteration.

enum CdlInferenceCallbackResult {
    CdlInferenceCallbackResult_Continue = 0x01,
    CdlInferenceCallbackResult_Cancel   = 0x02
};

// ----------------------------------------------------------------------------
// Widget hints.
//
// The library can provide a hint to the GUI code as to a sensible
// widget to use for displaying a particular valuable. There are separate
// hints for the bool and data parts.

enum CdlBoolWidget {
    CdlBoolWidget_None                  = 0,    // The boolean part is not applicable
    CdlBoolWidget_CustomDialog          = 1,    // There is a valid custom dialog property
    CdlBoolWidget_CheckButton           = 2,    // For simple booleans
    CdlBoolWidget_Radio                 = 3,    // For several mutual exclusive options,
                                                // the data structure will provide a string identifier
};

enum CdlValueWidget {
    CdlValueWidget_None                 = 0,    // The value part is not applicable
    CdlValueWidget_CustomDialog         = 1,    // There is a valid custom dialog property
    CdlValueWidget_Loadable             = 2,    // Use package/version dialog
    CdlValueWidget_EntryBox             = 3,    // Fallback
    CdlValueWidget_MultilineString      = 4,    // For complicated strings
    CdlValueWidget_DecimalRange         = 5,    // e.g. 1 to 16
                                                // Could be implemented as scale, radio buttons, entry, pull-down menu,
                                                // combo box, ... depending on GUI conventions and number of entries
    CdlValueWidget_HexRange             = 6,    // e.g. 0x01 to 0x10
    CdlValueWidget_OctalRange           = 7,    // e.g. 01 to 020
    CdlValueWidget_DoubleRange          = 8,    // e.g. 0.1 to 0.2
    CdlValueWidget_NumericSet           = 9,    // e.g. 1 2 4 8 16
                                                // The exact nature of the numbers is irrelevant, they will only
                                                // get displayed, not edited
                                                // Could be implemented as radio buttons, entry widget, pull-down menu,
                                                // combo box, ... depending on GUI conventions and number of entries
                                                // Each entry can have its own representation
    CdlValueWidget_StringSet            = 10    // e.g. "ram", "rom"

    // More to be added, e.g. for compiler flag handling
};

// ----------------------------------------------------------------------------
// Value formats.
//
// The CDL input data can accept numbers in a variety of formats,
// for example hexadecimal as well as decimal. It is desirable to try
// to keep track of this formatting information where possible, so
// that what the user sees and what ends up in header files corresponds
// more closely to what is in the raw CDL data. For example, it is
// much easier to understand 0x7fffffff than its decimal equivalent.
//
// The information kept here is very imprecise, it provides only
// minimal formatting information. It is not clear yet whether this
// will suffice or whether something more exact is going to be needed.
enum CdlValueFormat
{
    CdlValueFormat_Default              = 0,
    CdlValueFormat_Hex                  = 1,
    CdlValueFormat_Octal                = 2
};

//}}}
//{{{  Exception classes                                

// ----------------------------------------------------------------------------
// Some parts of the library make use of C++ exception handling. A number
// of exception classes related to this library are useful. In addition
// just about every part of the library can throw std::bad_alloc, but this
// is not checked for explicitly anywhere.

// This class is used for all exceptions where an error message should
// be displayed to the user. There is a single string message associated
// with the exception.

class CdlStringException {
    friend class CdlTest;

  public:
    CdlStringException(std::string message_arg) {
        message = message_arg;
    }
    CdlStringException(const CdlStringException& original) {
        message = original.message;
    }
    CdlStringException& operator=(const CdlStringException& original) {
        message = original.message;
        return *this;
    }
    ~CdlStringException() {
        message = "";
    }
    const std::string& get_message() const {
        return message;
    }
  private:
    std::string message;
    CdlStringException();
};

// CdlInputOutputException: this gets thrown when something goes wrong during
// file I/O operations, e.g. a file exists but cannot be opened. The
// exception contains a simple string explaining the error. This string
// may contain multiple lines, it is intended to be written to stderr
// or displayed in either a text widget or a dialog box.
//
// A separate class rather than a typedef is used to avoid any possible
// error message confusion. Everything gets inlined so there should be
// no performance issues.

class CdlInputOutputException : public CdlStringException {
    friend class CdlTest;
  public:
    CdlInputOutputException(std::string message_arg) :
        CdlStringException(message_arg) {
    }
    CdlInputOutputException(const CdlInputOutputException& original) :
        CdlStringException(original) {
    }
    CdlInputOutputException& operator=(const CdlInputOutputException& original) {
        (void) CdlStringException::operator=(original);
        return *this;
    }
};

// This class is used when any parsing happens at the C++ level rather
// than at the Tcl level. The exception should be caught before it
// propagates through the Tcl interpreter, or the latter will end up
// in an inconsistent state.

class CdlParseException : public CdlStringException {
    friend class CdlTest;
  public:
    CdlParseException(std::string message_arg) :
        CdlStringException(message_arg) {
    }
    CdlParseException(const CdlParseException& original) :
        CdlStringException(original) {
    }
    CdlParseException& operator=(const CdlParseException& original) {
        (void) CdlStringException::operator=(original);
        return *this;
    }
};

// Evaluating an expression may fail for a variety of reasons, e.g. because
// some referenced entity has not been loaded into the configuration.
// This exception can be thrown in such cases.

class CdlEvalException : public CdlStringException {
    friend class CdlTest;
  public:
    CdlEvalException(std::string message_arg) :
        CdlStringException(message_arg) {
    }
    CdlEvalException(const CdlEvalException& original) :
        CdlStringException(original) {
    }
    CdlEvalException& operator=(const CdlEvalException& original) {
        (void) CdlStringException::operator=(original);
        return *this;
    }
};

//}}}
//{{{  Forward declarations of the body classes         

// ----------------------------------------------------------------------------
// This section provides forward declarations of the main classes in
// the core of the library. Each variant of CDL will define additional
// classes, e.g. cdl_option, but these will usually be derived from
// the core ones.

// There are three types of expression in CDL:
// 1) ordinary expressions evaluate to a single value. The most common
//    use is for the legal_values property.
// 2) list expressions evaluate to a range of values, e.g. 1 to 10,
//    and the most common use is for the legal_values property.
// 3) goal expressions evaluate to either true or false and are used
//    for e.g. requires and active_if properties.
class CdlExpressionBody;
class CdlListExpressionBody;
class CdlGoalExpressionBody;

// There are also objects for simple values, values and list values.
// These are expanded classes, there are no associated pointer
// types. It is quite likely that values need to be copied around
// on the stack.
class CdlSimpleValue;
class CdlValue;
class CdlListValue;

// Properties. The base class is CdlProperty, and there are a number
// of derived classes provided as standard. Additional derived classes
// may be added in future.
class CdlPropertyBody;
class CdlProperty_MinimalBody;
class CdlProperty_StringBody;
class CdlProperty_TclCodeBody;
class CdlProperty_ReferenceBody;
class CdlProperty_StringVectorBody;
class CdlProperty_ExpressionBody;
class CdlProperty_ListExpressionBody;
class CdlProperty_GoalExpressionBody;

// Base classes. CDL entities such as options and components derive
// from one or more of these, using virtual inheritance.
// 
// The lowest-level class is CdlNodeBody.
//
// 1) a node usually lives in a hierarchy, below a toplevel
//    and with a container object as the parent. However nodes
//    can live outside a container on a temporary basis,
//    and toplevel objects have no parent.
//
// 2) a node has a name that is unique within the hierarchy.
//
// 3) a node has a vector of properties. Actually some entities
//    will have an empty vector, e.g. the orphans container
//    that is internal to the library. However it is too
//    inconvenient to have separate base classes for these.
//
// 4) nodes can be referred to by properties in other nodes.
class CdlNodeBody;

// A container is a node that can contain other nodes.
class CdlContainerBody;

// A loadable object is a container whose data has come out of a CDL
// script of some sort. It also stores details about all entities that
// were loaded via this script (even if some of them were reparented)
// thus supporting unload operations.
class CdlLoadableBody;

// A toplevel object is a container that acts as the toplevel of
// a hierarchy, in other words its parent is always 0. In addition
// a toplevel keeps track of all the names used in the hierarchy,
// thus facilitating navigation.
class CdlToplevelBody;

// The remaining classes all add functionality to CdlNode, directly or
// indirectly.
//
// A user-visible object is likely to appear in the user interface.
// This means it may have an alias string, a description, a
// documentation URL, and a gui_hint field.
class CdlUserVisibleBody;

// A valuable object has a value that can be retrieved but not
// necessarily modified by the user. For example the value of an
// interface is always calculated and users can never change it.
// Valuable objects have a whole bunch of associated properties
// including dependencies.
class CdlValuableBody;

// A parentable object has the parent property, i.e. it can
// be reparented to anywhere in the hierarchy
class CdlParentableBody;

// A buildable object is a valuable object that may result in
// something being built, typically a library in the case of
// software packages.
class CdlBuildableBody;

// A loadable that contains buildables
class CdlBuildLoadableBody;