Subversion Repositories openrisc_2011-10-31

#ifndef __CDLCORE_HXX

# define __CDLCORE_HXX

//{{{  Banner

//==========================================================================

//

//      cdlcore.hxx

//

//      The core parts of the library. This header defines aspects of

//      CDL that are shared between software cdl, hcdl, scdl, and any

//      future languages based on the same core technology.

//

//==========================================================================

//####COPYRIGHTBEGIN####

//

// ----------------------------------------------------------------------------

// Copyright (C) 2002 Bart Veer

// Copyright (C) 1999, 2000, 2001 Red Hat, Inc.

//

// This file is part of the eCos host tools.

//

// This program is free software; you can redistribute it and/or modify it

// under the terms of the GNU General Public License as published by the Free

// Software Foundation; either version 2 of the License, or (at your option)

// any later version.

//

// This program is distributed in the hope that it will be useful, but WITHOUT

// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

// FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for

// more details.

//

// You should have received a copy of the GNU General Public License along with

// this program; if not, write to the Free Software Foundation, Inc.,

// 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

//

// ----------------------------------------------------------------------------

//

//####COPYRIGHTEND####

//==========================================================================

//#####DESCRIPTIONBEGIN####

//

// Author(s):           bartv

// Contributors:        bartv

// Date:                1999-04-15

//

//####DESCRIPTIONEND####

//==========================================================================

//}}}

//{{{  Platform dependencies

// ----------------------------------------------------------------------------

// Visual C++ has the delightful feature that the source browser will generate

// warnings if there are any identifiers of length >= 256 characters, while at

// the same time use of templates in the standard C++ library can easily

// generate functions that long. It appears that the only way to disable the

// warnings is by use of a %$#@(%*&%! #pragma.

//

// Similarly, VC++ gives spurious warnings when it comes to multiple virtual

// inheritance.

#ifdef _MSC_VER

# pragma warning( disable: 4786 )

# pragma warning( disable: 4250 )

#endif

//}}}

//{{{  nested #include's

// ----------------------------------------------------------------------------

// The libcdl API is defined using parts of the standard C++ library,

// including strings and various bits of STL. Therefore these headers must

// be #include'd here for the header file to work.

#include 

#include 

#include 

#include 

#include 

#include 

#include 

#include 

//  is needed in various places in the implementation.

// This #include should be moved to an implementation-specific

// header.

#include 

// Now for some eCos host-side infrastructure headers.

//

// Get the cyg_int64 data type and CYG_UNUSED_PARAM() macro.

#include 

// Some of the classes need to reference the cyg_assert_class_zeal enum.

// Also inline functions may perform assertions.

#include 

// This header file also depends on having a suitable Tcl installation

// Unfortunately  does some ugly things in the interests of

// portability, including defining symbols such as EXTERN when

// necessary, and this has to be patched up here as cleanly as possible.

#ifndef CONST

# define __CDL_CONST_UNDEFINED

#endif

#ifndef EXTERN

# define __CDL_EXTERN_UNDEFINED

#endif

#ifndef VOID

# define __CDL_VOID_UNDEFINED

#endif

#ifndef CHAR

# define __CDL_CHAR_UNDEFINED

#endif

#ifndef SHORT

# define __CDL_SHORT_UNDEFINED

#endif

#ifndef LONG

# define __CDL_LONG_UNDEFINED

#endif

extern "C" {

#include 

}

#ifdef __CDL_CONST_UNDEFINED

# undef CONST

# undef __CDL_CONST_UNDEFINED

#endif

#ifdef __CDL_EXTERN_UNDEFINED

# undef EXTERN

# undef __CDL_EXTERN_UNDEFINED

#endif

#ifdef __CDL_VOID_UNDEFINED

# undef VOID

# undef __CDL_VOID_UNDEFINED

#endif

#ifdef __CDL_CHAR_UNDEFINED

# undef CHAR

# undef __CDL_CHAR_UNDEFINED

#endif

#ifdef __CDL_SHORT_UNDEFINED

# undef SHORT

# undef __CDL_SHORT_UNDEFINED

#endif

#ifdef __CDL_LONG_UNDEFINED

# undef LONG

# undef __CDL_LONG_UNDEFINED

#endif

//}}}

//{{{  Primitive types, constants:, enums, etc.

// ----------------------------------------------------------------------------

// The CDL languages are defined in terms of arbitrary precision

// arithmetic. This is necessary to allow e.g. pointers to be

// manipulated at the CDL level on 64 bit target processors.

//

// Temporarily it is not necessary to provide this precision, so it is

// convenient to stick to 64 bit integers as provided by the

// underlying infrastructure. However the API is defined in terms of

// the type cdl_int, so that it will be easier in future to make the

// change to the correct datatype. At that point cdl_int can be

// redefined to be a class which supports the appropriate operators.

typedef cyg_int64 cdl_int;

// ---------------------------------------------------------------------------

// A common concept in the CDL language is a small amount of TCL code.

// This is currently stored as a simple string. Conceivably it could

// be byte-compiled and stored accordingly.

typedef std::string  cdl_tcl_code;

// ----------------------------------------------------------------------------

// CDL values.

//

// CDL is a declarative programming language. It does involve the

// manipulation of values, but such values do not necessarily

// correspond to hardware-level entities such as integers or double

// precision numbers. Hence the term "type" is avoided, "flavor"

// is used instead. CDL understands four different flavors.

//

//    None  |  Bool

//  --------+--------

//    Data  |BoolData

//

//

// The flavor "none" is used for entities that serve only as

// placeholders in the hierarchy, allowing other entities to be

// grouped more easily.

//

// Boolean entities can be either enabled or disabled. This is the

// most common flavor for software configuration options, the user can

// either enable or disable some unit of functionality. For software

// packages implemented in C or C++ the implementation is obvious: iff

// the entity is enabled then there will be a #define, and code will

// check the setting using e.g. #ifdef.

//

// The flavor "data" implies some arbitrary data. Internally this will

// be held as a string. Other properties such as legal_values,

// check_proc and entry_proc can be used to constrain the

// actual values, for example to an integer value within a certain

// range.

//

// The flavor "booldata" combines the previous two: it means that

// the option can be either enabled or disabled, and if it is

// enabled then it must have a value as per legal_values etc.

// One example of this is a software package: this may be either

// enabled or disabled, and if it is enabled then it has a value

// corresponding to the version string. Another example is a hardware

// pin: this may or may not be connected, and if it is connected

// then its value identifies some other pin.

//

// An entity's flavor is not always sufficient by itself to specify

// how the user can manipulate it in a graphical tool. Obviously an

// entity of flavor "none" cannot be manipulated at all. Flavor "bool"

// normally implies a checkbutton, but occasionally a radiobutton will

// be more appropriate. "Data" says very little about the user

// interaction, it will be necessary to examine other properties such

// as legal_values to determine a sensible representation. The same

// goes for "BoolData", with the additional possibility that the

// entity may be disabled.

//

// It can be argued that three of the flavors are redundant: both Bool

// and BoolData could be implemented as cases of "Data" with a special

// legal value "disabled" (or false, or whatever); "None" could be

// implemented as constant "Data"; effectively CDL would manipulate

// all data as strings, just like e.g. all variables in Tcl, or just

// like all scalars in Perl. This approach is certainly tempting and

// might well make it easier to document the language, but in practice

// it would result in more verbose CDL: boolean entities really are a

// different beast from data entities.

//

// It can also be argued that there should be more flavors. For

// example there could be separate flavors for integer data, floating

// point data, string data, and so on. There are a number of good

// reasons for not doing so:

//

// 1) applying separate constraints such as legal_values allows much

//    finer control over the actual values, for example numbers within a

//    given range. As likely as not, a value will be constrained to

//    something smaller than the range MININT to MAXINT (whatever those

//    happen to be for the current target).

//

// 2) where do you stop? Do you provide separate flavors for signed

//    vs. unsigned? Char, wchar_t, short, int, long, long long? How about

//    the eCos data types cyg_ucount8, cyg_uint8, ... Is there support

//    for enums? Arrays? Bitfields? Structures? Unions? C++ classes?

//    How about other programming languages such as Ada or Java?

//

//    Any attempt to implement a grand union of all data types in CDL

//    is doomed to failure and should not be attempted. Treating

//    everything as a string instead has proven successful in a number

//    of languages, including Tcl and Perl.

//

// 3) for some variants of CDL, for example hardware CDL, it may not

//    make much sense to display a value directly and allow it to be

//    manipulated directly. The value associated with a pin entity

//    identifies the pin to which it is connected, and typically

//    this value will be manipulated by drag and drop rather than by

//    typing some characters. Such a value certainly does not correspond

//    to any machine data type.

//

// Another reason for extending the number of flavors is to provide

// more information. For example there could be a specialized version

// of the boolean flavor called "radio". This would imply a specific

// representation in the user interface, and it would also impose

// a constraint that it implicitly precludes any other radio entities

// within the same group. However the same information can be specified

// by other more general means such as requires statements.

enum CdlValueFlavor {

    CdlValueFlavor_Invalid      =  0,

    CdlValueFlavor_None         =  1,

    CdlValueFlavor_Bool         =  2,

    CdlValueFlavor_BoolData     =  3,

    CdlValueFlavor_Data         =  4

};

// Another important aspect of a value is where it came from. There

// are a number of possible sources: the default value, calculated

// from a default_value property; a value inferred by the inference

// engine; a value set by a wizard; and a value set explicitly by

// the user. These sources have different priorities, so for example

// the inference engine can safely replace a calculated default

// value without prompting the user, but changing a user-set value

// automatically is undesirable.

//

// Wizard-generated values are considered more valuable than default

// or inferred values (there is some user input involved), but less

// valuable than values set explicitly by the user: the idea is that

// a wizard asks fairly generic questions and makes a best guess at

// the correct values, which may not be precise enough for the

// user's needs.

//

// Arguably dialogs provide a level between wizards and users, in that

// a dialog can theoretically manipulate several entities in one go so

// it is a less precise way of setting values. At this stage it does

// not seem worthwhile to add this distinction.

//

// The library actually maintains separate values for each source,

// as well as the current source which is what actually gets used.

// In theory it is possible for the user interface code to let

// the user switch between these. It is not yet clear whether this

// makes sense from an end user's perspective.

enum CdlValueSource {

    CdlValueSource_Invalid              = -1, // 0 is needed for array indexing

    CdlValueSource_Default              =  0,

    CdlValueSource_Inferred             =  1,

    CdlValueSource_Wizard               =  2,

    CdlValueSource_User                 =  3,

    CdlValueSource_Current              =  4

};

// ----------------------------------------------------------------------------

// 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;

// A definable object is a valuable object whose value can result

// in #define statements in a header file

class CdlDefinableBody;

// A loadable which can contain definables

class CdlDefineLoadableBody;

// TODO: add instantiation support

// Custom dialogs and wizards are provided by the core.

class CdlDialogBody;

class CdlWizardBody;

class CdlInterfaceBody;

// Support for Tcl interpreters is also in the core, since it is

// difficult to do anything CDL-related without at least one Tcl

// interpreter lying around.

class CdlInterpreterBody;

// The basic conflict class is part of the core library, as are a

// number of common derived classes for specific types of conflict.

class CdlConflictBody;

class CdlConflict_UnresolvedBody;

class CdlConflict_IllegalValueBody;

class CdlConflict_EvalExceptionBody;

class CdlConflict_RequiresBody;

class CdlConflict_DataBody;

// Many operations happen (or may happen) in the context of a

// transaction. This is necessary to keep track of the various

// changes that can happen: for example, changing a component's

// value may require other entities' default values to be

// recalculated; it may change some legal_values list expressions,

// causing current values to become invalid; it may affect

// "requires" properties, causing goals to become satisfied or

// not-satisfied; it may change the "active" state of everything

// below the component, not to mention any entity with an

// "active_if" properties, and when an entity becomes active or

// inactive that may in turn affect other entities.

//

// Keeping track of all of this via recursion is possible, but there

// are problems. If an entity is updated multiple times, no

// optimizations are possible. It becomes much more difficult to

// detect cycles. During an unload operation things can get very

// messy. There is no easy way to track all of the changes and report

// them to higher level code via a callback. There is no support

// for any kind of rollback. A transaction model potentially

// provides support for all of this, at the cost of a more

// complex API.

class CdlTransactionBody;

// This class is used to pass information back to the application

// about what has actually changed in a transaction.

class CdlTransactionCallback;

// Build info class. This is always an expanded object, but is

// needed here to break a circular dependency.

class CdlBuildInfo;

// ----------------------------------------------------------------------------

// Typedefs for the pointers. There are separate typedefs to cope with

// const vs. non-const objects. Otherwise you end up with the problem

// that "const CdlNode x" means that the pointer is const, not the

// object pointed at.

typedef CdlExpressionBody*              CdlExpression;

typedef CdlListExpressionBody*          CdlListExpression;

typedef CdlGoalExpressionBody*          CdlGoalExpression;

typedef CdlPropertyBody*                CdlProperty;

typedef CdlProperty_MinimalBody*        CdlProperty_Minimal;

typedef CdlProperty_StringBody*         CdlProperty_String;

typedef CdlProperty_TclCodeBody*        CdlProperty_TclCode;

typedef CdlProperty_ReferenceBody*      CdlProperty_Reference;

typedef CdlProperty_StringVectorBody*   CdlProperty_StringVector;

typedef CdlProperty_ExpressionBody*     CdlProperty_Expression;

typedef CdlProperty_ListExpressionBody* CdlProperty_ListExpression;

typedef CdlProperty_GoalExpressionBody* CdlProperty_GoalExpression;

typedef CdlNodeBody*                    CdlNode;

typedef CdlContainerBody*               CdlContainer;

typedef CdlLoadableBody*                CdlLoadable;

typedef CdlToplevelBody*                CdlToplevel;

typedef CdlUserVisibleBody*             CdlUserVisible;

typedef CdlValuableBody*                CdlValuable;

typedef CdlParentableBody*              CdlParentable;

typedef CdlBuildableBody*               CdlBuildable;

typedef CdlBuildLoadableBody*           CdlBuildLoadable;

typedef CdlDefinableBody*               CdlDefinable;

typedef CdlDefineLoadableBody*          CdlDefineLoadable;

typedef CdlDialogBody*                  CdlDialog;

typedef CdlWizardBody*                  CdlWizard;

typedef CdlInterfaceBody*               CdlInterface;

typedef CdlInterpreterBody*             CdlInterpreter;

typedef CdlConflictBody*                CdlConflict;

typedef CdlConflict_UnresolvedBody*     CdlConflict_Unresolved;

typedef CdlConflict_IllegalValueBody*   CdlConflict_IllegalValue;

typedef CdlConflict_EvalExceptionBody*  CdlConflict_EvalException;

typedef CdlConflict_RequiresBody*       CdlConflict_Requires;

typedef CdlConflict_DataBody*           CdlConflict_Data;

typedef CdlTransactionBody*             CdlTransaction;

// ----------------------------------------------------------------------------

typedef const CdlExpressionBody*              CdlConstExpression;

typedef const CdlListExpressionBody*          CdlConstListExpression;

typedef const CdlGoalExpressionBody*          CdlConstGoalExpression;

typedef const CdlPropertyBody*                CdlConstProperty;

typedef const CdlProperty_MinimalBody*        CdlConstProperty_Minimal;

typedef const CdlProperty_StringBody*         CdlConstProperty_String;

typedef const CdlProperty_TclCodeBody*        CdlConstProperty_TclCode;

typedef const CdlProperty_ReferenceBody*      CdlConstProperty_Reference;

typedef const CdlProperty_StringVectorBody*   CdlConstProperty_StringVector;

typedef const CdlProperty_ExpressionBody*     CdlConstProperty_Expression;

typedef const CdlProperty_ListExpressionBody* CdlConstProperty_ListExpression;

typedef const CdlProperty_GoalExpressionBody* CdlConstProperty_GoalExpression;

typedef const CdlNodeBody*                    CdlConstNode;

typedef const CdlContainerBody*               CdlConstContainer;

typedef const CdlLoadableBody*                CdlConstLoadable;

typedef const CdlToplevelBody*                CdlConstToplevel;

typedef const CdlUserVisibleBody*             CdlConstUserVisible;

typedef const CdlValuableBody*                CdlConstValuable;

typedef const CdlParentableBody*              CdlConstParentable;

typedef const CdlBuildableBody*               CdlConstBuildable;

typedef const CdlBuildLoadableBody*           CdlConstBuildLoadable;

typedef const CdlDefinableBody*               CdlConstDefinable;

typedef const CdlDefineLoadableBody*          CdlConstDefineLoadable;

typedef const CdlDialogBody*                  CdlConstDialog;

typedef const CdlWizardBody*                  CdlConstWizard;

typedef const CdlInterfaceBody*               CdlConstInterface;

typedef const CdlInterpreterBody*             CdlConstInterpreter;

typedef const CdlConflictBody*                CdlConstConflict;

typedef const CdlConflict_UnresolvedBody*     CdlConstConflict_Unresolved;

typedef const CdlConflict_IllegalValueBody*   CdlConstConflict_IllegalValue;

typedef const CdlConflict_EvalExceptionBody*  CdlConstConflict_EvalException;

typedef const CdlConflict_RequiresBody*       CdlConstConflict_Requires;

typedef const CdlConflict_DataBody*           CdlConstConflict_Data;

typedef const CdlTransactionBody*             CdlConstTransaction;

//}}}

//{{{  Miscellaneous types etc.

// ----------------------------------------------------------------------------

// This section is used for data types, function prototypes, etc. which could

// not be defined until after the main CDL classes and handles.

// This typedef is used for error and warning reporting functions.

// Typically such a function pointer will be passed when the library

// is asked to perform any non-trivial parsing operation, e.g. loading

// a package.

//

// If the error is fatal then this callback function should raise

// a CdlParseException.

typedef void (*CdlDiagnosticFnPtr)(std::string);

// ----------------------------------------------------------------------------

// This function is used for update handler. Whenever there is a change

// to CDL entity (it has just been loaded, or its value has changed, or

// whatever) this can affect other CDL entities that reference it.

// All such references occur via properties, and there should be

// update handlers associated with those properties.

//

// Update handlers are also invoked for initialization and finalization

// operations, i.e. when the source object itself has just been loaded

// or is in the process of being unloaded.

//

// The arguments to an update handler are:

// 1) the transaction in which the operation takes place

// 2) the source object containing the reference

// 3) the source property containing the reference

// 4) the destination object. This may be 0 for some update

//    operations.

// 5) an indication of the change that has happened. This should

//    be a CdlUpdate value.

typedef void (*CdlUpdateHandler)(CdlTransaction, CdlNode, CdlProperty, CdlNode, CdlUpdate);

// ----------------------------------------------------------------------------

// This function is also used for transactions. Typically during a

// transaction there will be one or more invocations of the inference engine,

// with callbacks in between to allow one or more of the recommended

// changes to be undone.

typedef CdlInferenceCallbackResult (*CdlInferenceCallback)(CdlTransaction);

// ----------------------------------------------------------------------------

// The TCL API and C++ do not always mesh cleanly, for example a lot

// happens in terms of ClientData which is a void* pointer. To avoid

// too many casts all over the place libcdl provides a CdlInterpreter

// class and the following alternative to Tcl_CmdProc*. A single

// function will be used for the TCL command: its ClientData will be

// the CdlInterpreterCommand, and the CdlInterpreter is accessible via

// AssocData. This does result in some overheads, but none of these

// should be in performance-critical code.

typedef int (*CdlInterpreterCommand)(CdlInterpreter, int, const char*[]);

// ----------------------------------------------------------------------------

// In the libcdl world it is often convenient to swap whole sets of

// commands in and out. For example when executing the body of a

// cdl_component it is desirable to swap in commands for all the

// properties that make sense in a component and swap out all the

// commands that made sense in a higher level. It is assumed that none

// of the commands being swapped in or out are built-ins. Achieving

// this involves a vector of this simple utility structure.

class CdlInterpreterCommandEntry {

  public:

    std::string                 name;

    CdlInterpreterCommand       command;

    CdlInterpreterCommandEntry() : name(""), command(0) {}

    CdlInterpreterCommandEntry(const char *name_arg, CdlInterpreterCommand command_arg)

        : name(name_arg), command(command_arg)

    {

    }

    CdlInterpreterCommandEntry(std::string name_arg, CdlInterpreterCommand command_arg)

        : name(name_arg), command(command_arg)

    {

    }

    ~CdlInterpreterCommandEntry()

    {

        name = "";

        command = 0;

    }

};

// ----------------------------------------------------------------------------

// Persistence support.

// Some applications want to be able to store additional information

// in savefiles, and essentially this involves extra commands that

// get executed when the savefile is executed. It is possible that

// the application reading back the savefile does not understand

// the same set of commands as the application that wrote back the

// data, so the library tries hard not to lose data.

//

// The CdlSaveCallback function typedef is used when installing

// an application-specific savefile command. The first argument

// indicates the node for which the callback is being invoked:

// this may be the entire toplevel, or just an option, or whatever.

//

// The CdlSavefileCommand structure keeps track of the command,

// the save callback if any (non-zero only for application-specific

// data, zero implies that the command is handled by the lirary).

// The load command is invoked when reading in a savefile and the

// appropriate command is executed: unrecognised commands will be

// processed by CdlToplevelBody::savefile_handle_unknown().

typedef void (*CdlSaveCallback)(CdlNode, CdlInterpreter, Tcl_Channel, int);

struct CdlSavefileCommand {

    std::string           name;

    CdlSaveCallback       save_callback;

    CdlInterpreterCommand load_command;

};

// ----------------------------------------------------------------------------

// Widget hint.

// This structure provides widget hint information for a CdlValuable.

// There are separate hints for the bool and data parts, and possibly

// some additional data such as a string identifying the set of

// items in a radio button.

struct CdlWidgetHint {

    CdlBoolWidget       bool_widget;

    CdlValueWidget      value_widget;

    std::string         radio_button_interface;

};

//}}}

//{{{  Memory leak detection

// ----------------------------------------------------------------------------

// Provide some macros that are useful for detecting memory leaks. Basically

// there is a static counter for every class, which gets incremented by the

// constructor(s) and decremented by the destructor. Memory leak detection

// is currently enabled if tracing is enabled. It would be possible to use

// another configure-time option, but the overheads of tracing are likely

// to dwarf the overheads of memory leak detection.

//

// For now the memleak counters are always present, even in non-debug

// versions. The overhead is sufficiently small that it can be

// ignored.There is control over whether or not the counters get

// updated in the constructor or destructor. Otherwise there would be problems

// with whether or not there should be a semicolon at the end of the

// CYGDBG_DECLARE_MEMLEAK_COUNTER() macro definition.

#define CYGDBG_DECLARE_MEMLEAK_COUNTER()        static int memleak_counter

#define CYGDBG_DEFINE_MEMLEAK_COUNTER(class)    int class::memleak_counter = 0

#define CYGDBG_GET_MEMLEAK_COUNTER(class)       class::memleak_counter

#ifdef CYGDBG_USE_TRACING

#define CYGDBG_MEMLEAK_CONSTRUCTOR()            this->memleak_counter++;

#define CYGDBG_MEMLEAK_DESTRUCTOR()             this->memleak_counter--;

#define CYGDBG_MEMLEAK_CHECKTHIS()              if (this->memleak_counter < 0) { return false; }

#else

#define CYGDBG_MEMLEAK_CONSTRUCTOR()

#define CYGDBG_MEMLEAK_DESTRUCTOR()

#define CYGDBG_MEMLEAK_CHECKTHIS()

#endif