Subversion Repositories openrisc

#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.
//
//==========================================================================
// ####ECOSHOSTGPLCOPYRIGHTBEGIN####                                        
// -------------------------------------------                              
// This file is part of the eCos host tools.                                
// Copyright (C) 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
//
// 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 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., 51 Franklin Street,                      
// Fifth Floor, Boston, MA  02110-1301, USA.                                
// -------------------------------------------                              
// ####ECOSHOSTGPLCOPYRIGHTEND####                                          
//==========================================================================
//#####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 <vector>
#include <list>
#include <map>
#include <set>
#include <deque>
#include <string>
#include <functional>
#include <algorithm>

// <cctype> is needed in various places in the implementation.
// This #include should be moved to an implementation-specific
// header.
#include <cctype>

// Now for some eCos host-side infrastructure headers.
//
// Get the cyg_int64 data type and CYG_UNUSED_PARAM() macro.
#include <cyg/infra/cyg_type.h>

// Some of the classes need to reference the cyg_assert_class_zeal enum.
// Also inline functions may perform assertions.
#include <cyg/infra/cyg_ass.h>

// This header file also depends on having a suitable Tcl installation
// Unfortunately <tcl.h> 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 <tcl.h>
}

#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

//}}}

//{{{  Cdl class                                        

// ---------------------------------------------------------------------------
// The sole purpose of this class is to provide some utility functions with
// reasonable namespace protection, without requiring that the compiler
// implements namespaces.

class Cdl {
    
  public:

    static bool         is_valid_value_flavor(CdlValueFlavor);
    static bool         is_valid_value_source(CdlValueSource);
    
    static bool         is_valid_cdl_name(const std::string&);
    static bool         is_valid_c_preprocessor_symbol(const std::string&);
    
    static bool         string_to_integer(std::string, cdl_int&);
    static bool         string_to_double(std::string, double&);
    static bool         string_to_bool(std::string, bool&);
    static void         integer_to_string(cdl_int, std::string&, CdlValueFormat = CdlValueFormat_Default);
    static std::string  integer_to_string(cdl_int, CdlValueFormat = CdlValueFormat_Default);
    static void         double_to_string(double, std::string&, CdlValueFormat = CdlValueFormat_Default);
    static std::string  double_to_string(double, CdlValueFormat = CdlValueFormat_Default);
    static void         bool_to_string(bool, std::string&);
    static std::string  bool_to_string(bool);
    static void         integer_to_double(cdl_int, double&);
    static double       integer_to_double(cdl_int);
    static bool         double_to_integer(double, cdl_int&);
    
    static bool         string_to_flavor(std::string, CdlValueFlavor&);
    static bool         flavor_to_string(CdlValueFlavor, std::string&);
    static bool         string_to_source(std::string, CdlValueSource&);
    static bool         source_to_string(CdlValueSource, std::string&);
                                         
    static std::string  get_library_version();
    static void         set_interactive(bool = true);
    static bool         is_interactive();

    static bool         truth() { return true; }
    static bool         falsehood() { return false; }
    
    // return values are -1,0,1 just like strcmp(). The most recent
    // version is the smallest.
    static int          compare_versions(std::string, std::string);

    // Also provide an STL-friendly comparison class
    class version_cmp {
      public:
        bool operator()(const std::string& v1, const std::string& v2) const {
            return Cdl::compare_versions(v1,v2) < 0;
        }
    };

    // Split a version string into major, minor and release numbers.
    static void         split_version_string(const std::string&, std::string& /* major */,
                                             std::string& /* minor */, std::string& /* release */);
    
    // It is occasionally useful to take a full CDL name such as CYGPKG_KERNEL
    // and turn it into a short form, i.e. kernel.
    static std::string  get_short_form(const std::string&);
    
  private:
    static bool         interactive;
};

//}}}
//{{{  CdlInterpreter class                             

// ----------------------------------------------------------------------------
// libcdl requires access to a Tcl interpreter. For now the standard
// interpreter is used. In the long run it may be better to use a
// custom parser in places, if only to improve the diagnostics messages
// that users see.
//
// Consider the case of software CDL (other CDL variants will have
// similar requirements). A Tcl interpreter is needed to read in the
// data for a given package. It will also be needed at various stages
// when the data is being manipulated, e.g. to display a custom dialog
// or to execute e.g. a check_proc or a define_proc. Each package
// should run in its own safe interpreter with limited capabilities:
// file I/O is limited to read-only, but read-write in the build and
// install trees; network I/O is out of the question, at least until
// appropriate security support is added to the CDL language itself.
// However the interpreter should be extended with additional commands
// like cdl_get and cdl_set to access the configuration data.
//
// For security and robustness reasons it is desirable to have
// separate interpreters for the various packages. This leads to the
// concept of a master interpreter for the entire configuration, and a
// group of slave interpreters, one per package. In this model it
// is convenient to have the configuration and package entities
// associated directly with the interpreter. Note that a single
// application may have several configurations loaded in memory,
// so there may be several master interpreters.
//
// Some applications will want to support the graphical side of CDL,
// i.e. custom dialogs and wizards. This means linking in Tk, not to
// mention X11 (or the Windows equivalents), and making some/all of
// the Tk commands available to the safe interpreter. Arguably
// commands like toplevel should always be disabled. Not all clients
// of libcdl will want the overheads of linking with Tk and X, so this
// has to be made optional.
//
// The approach taken is as follows:
//
// 1) there is a class CdlInterpreter which provides access to Tcl
//    interpreters. Amongst other things it takes care of converting
//    between C and C++ strings.
//
// 2) every toplevel needs its own CdlInterpreter. The application
//    code should supply this interpreter itself when the toplevel
//    is instantiated, allowing it to decide whether or not Tk should
//    be available.
//
// 3) each loadable gets its own safe slave interpreter, derived from
//    the toplevel's interpreter.
//    NOTE: initially the slave interpreters are not actually safe. It
//    is not clear in the long term to what extent per-loadable
//    interpreters need to be sandboxes, there are issues such as
//    doing the equivalent of autoconf tests.

// Tcl 8.4 involved various incompatible API changes related to
// const vs. non-const data. #define'ing USE_NON_CONST or
// USE_COMPAT_CONST avoids some of the problems, but does not
// help much for C++.
#if (TCL_MAJOR_VERSION > 8) || ((TCL_MAJOR_VERSION == 8) && (TCL_MINOR_VERSION >= 4))
# define CDL_TCL_CONST_CAST(type,var) (var)
#else
# define CDL_TCL_CONST_CAST(type,var) const_cast<type>(var)
#endif

class CdlInterpreterBody
{
    friend class        CdlTest;

  public:

    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
    // This is how a top-level (i.e. per-toplevel) interpreter
    // should get created.
    static CdlInterpreter       make(Tcl_Interp* = 0);

    // Create a slave interpreter for reading in the data in e.g. a
    // cdl_package
    CdlInterpreter create_slave(CdlLoadable, bool /* safe */ = true);
    
    // Make the interpreter safe, a one-way operation.
    void                make_safe();
    
    // The destructor is public.
    virtual ~CdlInterpreterBody();

    // Add or remove commands from an interpreter. This provides
    // a more C++-friendly implementation of Tcl's
    // CreateCommand() and DeleteCommand().
    void add_command(std::string, CdlInterpreterCommand);
    void remove_command(std::string);

    // In the libcdl world it is also convenient to swap whole sets of
    // commands in and out. This is achieved by push and pop operations.
    // push returns the old set (0 at the toplevel). pop restores
    // the old set.
    std::vector<CdlInterpreterCommandEntry>* push_commands(std::vector<CdlInterpreterCommandEntry>&);
    void pop_commands(std::vector<CdlInterpreterCommandEntry>*);
    std::vector<CdlInterpreterCommandEntry>* get_pushed_commands() const;
    
    // Similarly, allow variables to be set, unset and queried
    void        set_variable(std::string, std::string);
    void        unset_variable(std::string);
    std::string get_variable(std::string);
    
    // FIXME: add support for variable traces. These are needed
    // for cdl_value and similar utilities.
    
    // Provide hooks into the AssocData() facilities associated with
    // Tcl interpreters. This makes it possible to store arbitrary
    // data with an interpreter, e.g. to keep track of current state.
    void       set_assoc_data(const char*, ClientData, Tcl_InterpDeleteProc* =0);
    void       delete_assoc_data(const char*);
    ClientData get_assoc_data(const char*);

    // Evaluate a string as Tcl code. The return value comes from Tcl, e.g.
    // TCL_OK or TCL_ERROR. There are variants depending on whether or not
    // the result string is of interest.
    int eval(std::string);
    int eval(std::string, std::string&);

    // Ditto for any Tcl code that comes from CDL files
    int eval_cdl_code(const cdl_tcl_code);
    int eval_cdl_code(const cdl_tcl_code, std::string&);

    // And support for evaluating an entire file
    int eval_file(std::string);
    int eval_file(std::string, std::string&);
    
    // For use by commands implemented in C++, a way of setting the result
    void set_result(std::string);

    // And a utility to get the result as well.
    std::string get_result();

    // Was the result set by the Tcl interpreter or by libcdl?
    bool result_set_by_cdl();
    
    // A utility to quote data that is going to end up in a TCL script.
    static std::string quote(std::string);

    // Turn some multiline data into a comment.
    static std::string multiline_comment(const std::string&, int, int = 0);

    // Add some data to a comment, allowing for newlines if necessary
    static std::string extend_comment(const std::string&, int, int = 0);
    
    // Write some data to a savefile, throwing an exception on error
    void write_data(Tcl_Channel, std::string);

    // File-related utilities.
    void locate_subdirs(std::string, std::vector<std::string>&);
    void locate_all_subdirs(std::string, std::vector<std::string>&);
    void locate_files(std::string, std::vector<std::string>&);
    void locate_all_files(std::string, std::vector<std::string>&);
    bool is_directory(std::string);
    bool is_file(std::string);

    // When parsing a CDL script it is convenient to keep track of
    // a number of items:
    //
    // 1) the toplevel, e.g. the entire configuration
    // 2) the loadable, e.g. the current package
    // 3) the parent of whatever is being processed at the moment
    // 4) the entity, i.e. the thingamajig that is being processed.
    // 5) the current file
    // 6) an error reporting function
    //
    // This gives the various commands embedded in the Tcl interpreter
    // enough information to do their job. Additional information can
    // be provided via assoc_data()
    //
    // There should be only one call to set_toplevel(), for the
    // master interpreter. All slaves inherit this, and the toplevel
    // cannot be changed again.
    //
    // The loadable field is filled in via make_slave()
    //
    // For some members push and pop functions are more appropriate
    // than set.
    CdlToplevel         get_toplevel() const;
    CdlLoadable         get_loadable() const;
    CdlContainer        get_container() const;
    CdlNode             get_node() const;
    std::string         get_context() const;
    CdlDiagnosticFnPtr  get_error_fn_ptr() const;
    CdlDiagnosticFnPtr  get_warning_fn_ptr() const;
    CdlTransaction      get_transaction() const;
    void                set_toplevel(CdlToplevel);
    void                set_transaction(CdlTransaction);
    CdlContainer        push_container(CdlContainer);
    void                pop_container(CdlContainer);
    CdlNode             push_node(CdlNode);
    void                pop_node(CdlNode);
    std::string         push_context(std::string);
    void                pop_context(std::string);
    CdlDiagnosticFnPtr  push_error_fn_ptr(CdlDiagnosticFnPtr);
    void                pop_error_fn_ptr(CdlDiagnosticFnPtr);
    CdlDiagnosticFnPtr  push_warning_fn_ptr(CdlDiagnosticFnPtr);
    void                pop_warning_fn_ptr(CdlDiagnosticFnPtr);

    // Provide utility classes for common push/pop combinations. The
    // push happens during the constructor, the pop during the
    // destructor. This can simplify some code, especially when
    // exceptions may get thrown.
    class DiagSupport {
      public:
        DiagSupport(CdlInterpreter interp_arg, CdlDiagnosticFnPtr error_fn_arg, CdlDiagnosticFnPtr warn_fn_arg) {
            interp         = interp_arg;
            saved_error_fn = interp->push_error_fn_ptr(error_fn_arg);
            saved_warn_fn  = interp->push_warning_fn_ptr(warn_fn_arg);
        }
        ~DiagSupport() {
            interp->pop_error_fn_ptr(saved_error_fn);
            interp->pop_warning_fn_ptr(saved_warn_fn);
        }
    private:
        DiagSupport();

        CdlInterpreter     interp;
        CdlDiagnosticFnPtr saved_error_fn;
        CdlDiagnosticFnPtr saved_warn_fn;
    };
    class ContextSupport {
      public:
        ContextSupport(CdlInterpreter interp_arg, std::string context) {
            interp = interp_arg;
            saved_context = interp->push_context(context);
        }
        ~ContextSupport() {
            interp->pop_context(saved_context);
        }
      private:
        ContextSupport();
        CdlInterpreter interp;
        std::string    saved_context;
    };
    class ContainerSupport {
      public:
        ContainerSupport(CdlInterpreter interp_arg, CdlContainer container) {
            interp = interp_arg;
            saved_container = interp->push_container(container);
        }
        ~ContainerSupport() {
            interp->pop_container(saved_container);
        }
      private:
        ContainerSupport();
        CdlInterpreter interp;
        CdlContainer   saved_container;
    };
    class NodeSupport {
      public:
        NodeSupport(CdlInterpreter interp_arg, CdlNode node) {
            interp = interp_arg;
            saved_node = interp->push_node(node);
        }
        ~NodeSupport() {
            interp->pop_node(saved_node);
        }
      private:
        NodeSupport();
        CdlInterpreter interp;
        CdlNode        saved_node;
    };
    class CommandSupport {
      public:
        CommandSupport(CdlInterpreter interp_arg, std::vector<CdlInterpreterCommandEntry>& commands) {
            interp = interp_arg;
            saved_commands = interp->push_commands(commands);
        }
        CommandSupport(CdlInterpreter interp_arg, CdlInterpreterCommandEntry* commands) {
            unsigned int i;
            for (i = 0; 0 != commands[i].command; i++) {
                new_commands.push_back(commands[i]);
            }
            interp = interp_arg;
            saved_commands = interp->push_commands(new_commands);
        }
        ~CommandSupport() {
            interp->pop_commands(saved_commands);
        }

      private:
        CommandSupport();
        CdlInterpreter interp;
        std::vector<CdlInterpreterCommandEntry>* saved_commands;
        std::vector<CdlInterpreterCommandEntry> new_commands;
    };

    // Similar utility classes for variables and assoc data.
    class VariableSupport {
      public:
        VariableSupport(CdlInterpreter interp_arg, std::string varname_arg, std::string data) {
            interp  = interp_arg;
            varname = varname_arg;
            interp->set_variable(varname, data);
        }
        ~VariableSupport() {
            interp->unset_variable(varname);
        }
      private:
        VariableSupport();
        CdlInterpreter interp;
        std::string    varname;
    };
    class AssocSupport {
      public:
        AssocSupport(CdlInterpreter interp_arg, const char* name_arg, ClientData data, Tcl_InterpDeleteProc* del_proc = 0) {
            interp = interp_arg;
            name   = name_arg;
            interp->set_assoc_data(name, data, del_proc);
        }
        ~AssocSupport() {
            interp->delete_assoc_data(name);
        }
      private:
        AssocSupport();
        CdlInterpreter interp;
        const char*    name;
    };
    
    // Some command implementations may want to access other Tcl library
    // routines such as Tcl_SplitList(). This requires convenient access
    // to the underlying Tcl interpreter.
    Tcl_Interp*         get_tcl_interpreter() const;
    
    // For use by the assertion macros.
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;

  private:
    // This is the Tcl command proc that gets registered for all
    // CdlInterpreterCommand instances.
    static int          tcl_command_proc(ClientData, Tcl_Interp*, int, const char*[]);

    // This key is used to access the CdlInterpreter assoc data.
    static const char*  cdlinterpreter_assoc_data_key;
    
    // Do not allow static instances of a Cdl interpreter. There are too
    // many possible failure conditions. Cdl interpreters can only be
    // created dynamically via make(), which will invoke this.
    CdlInterpreterBody(Tcl_Interp*);

    // Default constructor, copy constructor and assignment are illegal
    CdlInterpreterBody();
    CdlInterpreterBody(const CdlInterpreterBody&);
    CdlInterpreterBody& operator=(const CdlInterpreterBody&);

    
    Tcl_Interp*                 tcl_interp;     // The underlying Tcl interpreter
    bool                        owns_interp;    // Was the Tcl interpreter created by the library?
    std::vector<CdlInterpreter> slaves;         // All slave interpreters
    CdlInterpreter              parent;         // Or else the parent
    CdlToplevel                 toplevel;       // Data that gets used during the parsing process
    CdlTransaction              transaction;
    CdlLoadable                 loadable;
    CdlContainer                container;
    CdlNode                     node;
    std::string                 context;
    CdlDiagnosticFnPtr          error_fn_ptr;
    CdlDiagnosticFnPtr          warning_fn_ptr;
    bool                        cdl_result;
    
    std::vector<CdlInterpreterCommandEntry>* current_commands; // for push() and pop()
    
    enum {
        CdlInterpreterBody_Invalid = 0,
        CdlInterpreterBody_Magic   = 0x0be67689
    } cdlinterpreterbody_cookie;
};

//}}}
//{{{  CdlReference/Referrer classes                    

// ---------------------------------------------------------------------------
// CDL objects are organised primarily in a tree hierarchy. For
// example a package contains components, components contain options,
// and so on. The tree hierarchy tends to change rather infrequently,
// so it makes sense to have a quick way of navigating between
// entities without continuously having to do hash-table lookups. In
// addition it is very desirable to make the connectivity
// bidirectional: if a "requires" property in option A references
// option B then it would be useful to have a link back to A from B;
// that way, if the value of B changes it is a lot easier to keep
// things up to date.
//
// Terminology: the entity which contains the reference, e.g. a
// "requires" property, is the source. The relevant property is the
// "source property". The entity pointed at is the destination.
//
// Unfortunately there may be connections between CDL entities outside
// the tree hierarchy. In particular any property can contain one or
// more references to packages, components, options, wizards, or
// whatever. Often these references will be to options etc. within the
// same package, but some references will go to other packages. There
// may even be references to other configurations: for example a board
// may contain both an ordinary processor and a DSP; these two need
// their own configurations; however a package running on the DSP may
// need to interact with a package running on the processor, and vice
// versa.
//
// Also, a reference may occur inside an object that is not in the
// hierarchy. For example CDL expressions may get evaluated inside Tcl
// code rather than as part of a property. Such expressions may still
// contain references to entities in the current configuration.
//
// References may not be resolved. When reading in a CDL script there
// may be forward references. A reference may involve another package
// that has not yet been loaded, which is a conflict.
//
// Using simple pointers to store these connections is a bad idea. It
// makes it a lot harder to figure out what is connected to what, and
// it introduces horrible consistency problems when packages get
// loaded and unloaded. Instead libCDL provides a CdlReference class.
// Whenever a CdlProperty contains a reference to some other CDL
// entity there should be a CdlReference object corresponding to this.
// The reverse direction is handled via a CdlReferrer object.
//
// A CdlReference object can be either bound or unbound. By default it
// is unbound, containing only a string. It can then be bound via a
// member function, examined, and unbound again as required. Creating
// a binding automatically creates a CdlReferrer entry in the target
// object, thus avoiding any risk of inconsistencies.
//
// The CdlReference class should not be used outside the hierarchy,
// since every bound reference must have a referrer object pointing
// back, and this link back can only be valid within the hierarchy.
// Temporary CdlReference objects are useful during the construction
// of properties.
//
// It is possible that a given property (e.g. a complicated "requires"
// expression) has multiple references to another entity. Each of
// these involves a separate CdlReference/CdlReferrer pair.

// ----------------------------------------------------------------------------
// The actual CdlReference class.

class CdlReference {

    friend class        CdlTest;

    // CdlReferrer must be a friend so that when a package gets unloaded
    // it can clean up all references to it.
    friend class        CdlReferrer;
    
  public:

    // The default constructor should not normally be used, instead
    // a string should be supplied. However there are vectors of
    // reference objects...
    CdlReference();
    
    // The main constructor supplies the name of the referenced
    // entity. The resulting object will be unbound.
    CdlReference(const std::string);

    // The copy constructor is legal for unbound objects only.
    CdlReference(const CdlReference&);

    // The assignment operator is needed for STL operations.
    // Again it only makes sense of unbound objects.
    CdlReference& operator=(const CdlReference&);
    
    // The destructor is only valid for unbound objects. All references
    // should be unbound before an entity can be destroyed.
    ~CdlReference();
    
    // Access the various fields.
    void               set_destination_name(const std::string);
    const std::string& get_destination_name() const;
    CdlNode            get_destination() const;

    // Binding a reference. Obviously this can only be used when the
    // reference is still unbound. When doing the binding it is
    // necessary to know:
    //   (1) the object containing the reference.
    //   (2) the specific property that contains the reference.
    //   (3) the object being referred to.
    // Binding a reference results in a new referrer entry in the
    // destination.
    void bind(CdlNode, CdlProperty, CdlNode);

    // Unbinding a reference. Typically this only happens when the
    // destination is unloaded. The arguments provide the source and
    // the source property.
    void unbind(CdlNode, CdlProperty);

    // This is used by the ASSERT_CLASS() and ASSERT_THIS() macros.
    bool check_this(cyg_assert_class_zeal cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  protected:

  private:
    
    // The data fields. The name is usually filled in by the
    // constructor. The destination defaults to zero for an unbound
    // object and gets filled in by the bind() operation.
    std::string dest_name;
    CdlNode     dest;

    enum {
        CdlReference_Invalid = 0,
        CdlReference_Magic   = 0x3f908608
    } cdlreference_cookie;
};

// ----------------------------------------------------------------------------
// The CdlNode class (and hence just about everything) contains a
// vector of CdlReferrer objects. This keeps track of all entities
// that refer to this one, so if the value associated with this
// changes it is possible to work out the impact of this on all
// entities that rely on this value.
//
// Arguably this should work in terms of CdlValuable objects rather
// than CdlNode objects. However it is convenient to use references
// for the connection between e.g. an option and a dialog, where
// there is no value involved. The reverse connection is of little
// use in this circumstance.
//
// CdlReferrer objects are rarely accessed directly. Instead they will
// be filled in during a CdlReference::bind() operation and erased
// during a CdlReference::unbind() operation. The only operations that
// should be public allow access to the contained data.

class CdlReferrer {

    friend class        CdlTest;

    // CdlReference::bind() and unbind() have direct access to the
    // members, since these two functions are really responsible for
    // creating and destroying referrer objects.
    friend class        CdlReference;
    
  public:

    // The default constructor, copy constructor and assignment
    // operator are all public to avoid problems with having vectors
    // of referrer objects. Similarly the destructor is public.
    // In practice updates actually happen as a consequence of
    // CdlReference::bind() and CdlReference::unbind().
    CdlReferrer();
    CdlReferrer(const CdlReferrer&);
    CdlReferrer& operator=(const CdlReferrer&);
    ~CdlReferrer();

    CdlNode     get_source() const;
    CdlProperty get_source_property() const;
    void        update(CdlTransaction, CdlNode, CdlUpdate);
    bool        check_this(cyg_assert_class_zeal=cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  private:

    CdlNode     source;
    CdlProperty source_property;
    
    enum {
        CdlReferrer_Invalid = 0,
        CdlReferrer_Magic   = 0x70e1fc37
    } cdlreferrer_cookie;
};

//}}}
//{{{  Value and Expression  classes                    

//{{{  CdlEvalContext                   

// ----------------------------------------------------------------------------
// Expression evaluation always happens within a certain context.
// This may involve a transaction. Usually it involves a node and
// a property within that node, although it is possible to evaluate
// expressions from inside Tcl code.
//
// To avoid passing too many arguments around the various
// evaluation-related routines, a utility class is provided.

class CdlEvalContext {
    
    friend class CdlTest;
    
  public:

    CdlTransaction      transaction;
    CdlNode             node;
    CdlProperty         property;
    CdlToplevel         toplevel;

    CdlEvalContext(CdlTransaction, CdlNode = 0, CdlProperty = 0, CdlToplevel = 0);
    ~CdlEvalContext();

    // Given a reference inside an expression, try to resolve this to either
    // a node or, more specifically, a valuable.
    CdlNode             resolve_reference(CdlExpression, int);
    CdlValuable         resolve_valuable_reference(CdlExpression, int);
    
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  protected:

  private:
    // Illegal operation, the three fields must always be supplied,
    // although they may be zero.
    CdlEvalContext();

    enum {
        CdlEvalContext_Invalid  = 0,
        CdlEvalContext_Magic    = 0x03434be9
    } cdlevalcontext_cookie;
    
};

//}}}
//{{{  CdlSimpleValue                   

// ----------------------------------------------------------------------------
// Expression evaluation happens in terms of CdlSimpleValue objects.
// In CDL all values are strings, but for the purposes of arithmetic
// these strings sometimes have to be interpreted as integers or as
// double precision numbers. Sometimes there is a choice, for example
// the equality operator == can mean numerical or string comparison.
// The basic rules that get applied are:
//
//    1) if the current value has an integer representation then
//       use this by preference. This means that an expression
//       of the form (CYGNUM_XXX != 0x100) will do a integer
//       comparison if possible.
//
//    2) otherwise if the current value can be interpreted as a
//       double precision number, use that representation.
//       All integers can be interpreted as doubles (at the risk
//       of some loss of precision), so the representation as
//       a double should only be used if the integer representation
//       is inappropriate.
//
//    3) otherwise interpret the value as a string.
//
// The default value is 0.

class CdlSimpleValue {
    
    friend class CdlTest;

  public:

    CdlSimpleValue();
    CdlSimpleValue(std::string);
    CdlSimpleValue(cdl_int);
    CdlSimpleValue(double);
    CdlSimpleValue(const CdlSimpleValue&);
    CdlSimpleValue(bool);
    ~CdlSimpleValue();

    CdlSimpleValue&     operator=(const CdlSimpleValue&);
    CdlSimpleValue&     operator=(std::string);
    CdlSimpleValue&     operator=(cdl_int);
    CdlSimpleValue&     operator=(double);
    
    CdlSimpleValue&     operator=(bool);
    
    bool                operator==(const CdlSimpleValue&) const;
    bool                operator!=(const CdlSimpleValue&) const;
    bool                operator==(std::string arg) const
    {
        CdlSimpleValue val(arg);
        return *this == val;
    }
    bool                operator==(cdl_int arg) const
    {
        CdlSimpleValue val(arg);
        return *this == val;
    }
    bool                operator==(double arg) const
    {
        CdlSimpleValue val(arg);
        return *this == val;
    }
    bool                operator!=(std::string arg) const
    {
        CdlSimpleValue val(arg);
        return *this != val;
    }
    bool                operator!=(cdl_int arg) const
    {
        CdlSimpleValue val(arg);
        return *this != val;
    }
    bool                operator!=(double arg) const
    {
        CdlSimpleValue val(arg);
        return *this != val;
    }
    
    void                set_value(std::string, CdlValueFormat = CdlValueFormat_Default);
    std::string         get_value() const;
    
    bool                has_integer_value() const;
    void                set_integer_value(cdl_int, CdlValueFormat = CdlValueFormat_Default);
    cdl_int             get_integer_value() const;
    
    bool                has_double_value() const;
    void                set_double_value(double, CdlValueFormat = CdlValueFormat_Default);
    double              get_double_value() const;

    CdlValueFormat      get_value_format() const;
    void                set_value_format(CdlValueFormat);
    void                set_value_format(CdlSimpleValue&);
    void                set_value_format(CdlSimpleValue&, CdlSimpleValue&);

    static void         eval_valuable(CdlEvalContext&, CdlValuable, CdlSimpleValue&);
    
    // For expression evaluation, it is often convenient to get hold
    // of a boolean as well. This may indicate a non-empty string
    // or a non-zero value.
    bool                get_bool_value() const;
    
    // This class is too simple to warrant even a cookie validation.
    bool check_this(cyg_assert_class_zeal zeal = cyg_quick) const {
        return true;
    }
    
  protected:

  private:
    enum {
        int_valid       = 0x01,
        double_valid    = 0x02,
        string_valid    = 0x04,
        int_invalid     = 0x08,
        double_invalid  = 0x10
    };
    mutable int         valid_flags;
    mutable std::string value;
    mutable cdl_int     int_value;
    mutable double      double_value;
    CdlValueFormat      format;
};

//}}}
//{{{  CdlListValue                     

// ----------------------------------------------------------------------------
// Evaluating a list expression results in a set of possible values, but
// unlike the original list expression these values are now constant and
// can have no dependencies on CDL entities. As with list expressions the
// main operation on a list value is to detect membership, but using
// list values allows multiple potential members to be tested without
// repeated expression evaluation. The main use of list values is implicit
// in libcdl, each list expression contains a mutable cached list value.
//
// A list value contains five sets of data:
//
// 1) separate vectors of strings, integers, and floating point constants.
//    Having separate vectors of integers and floating points avoids
//    problems when numbers can be represented in different formats.
// 2) a vector of cdl_int pairs for ranges of integer data
// 3) a vector of double pairs for ranges of floating point data
//
// Any of these vectors may be empty, but at least one of the vectors should
// contain useful data. Possibly there should also be tables for cdl_int and
// double to avoid unnecessary string conversions.

class CdlListValue {
    
    friend class        CdlTest;

    // A list value will only be filled in when a list expression is evaluated.
    // The members cannot be updated by other means.
    friend class        CdlListExpressionBody;
    
  public:

    CdlListValue();
    ~CdlListValue();
    CdlListValue(const CdlListValue&);
    CdlListValue& operator=(const CdlListValue&);

    bool        is_member(CdlSimpleValue&) const;
    bool        is_member(std::string, bool = true) const;
    bool        is_member(cdl_int, bool = true) const;
    bool        is_member(double, bool = true) const;

    // These provide access to the raw data, for example if it is
    // necessary to suggest a legal value to the user.
    const std::vector<CdlSimpleValue>&                get_table() const;
    const std::vector<std::pair<cdl_int, cdl_int> >&  get_integer_ranges() const;
    const std::vector<std::pair<double, double> >&    get_double_ranges() const;

    bool check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  private:
    std::vector<CdlSimpleValue>                 table;
    std::vector<std::pair<cdl_int, cdl_int> >   integer_ranges;
    std::vector<std::pair<double, double> >     double_ranges;

    enum {
        CdlListValue_Invalid  = 0,
        CdlListValue_Magic    = 0x2183a943
    } cdllistvalue_cookie;
};

//}}}
//{{{  CdlValue                         

// ----------------------------------------------------------------------------
// Values in CDL are non-trivial compared with some other languages.
// Even though CDL is not a fully-typed language, it does still have
// four different flavors to consider. There is also the problem that
// an entity may have up to four different values which should be
// stored (default, inferred, wizard, user), with the ability to
// switch between them. The CdlValue class provides support for this.
//
// CdlValue objects are not normally updated explicitly. Instead
// higher level code deals with CdlValuable objects, which inherit
// privately from CdlValue. Modifications to CdlValuables happen in
// the context of a transaction.
//
// The first concept to take into account is the flavor. There
// are four flavors, None, Bool, BoolData and Data. The member
// function get_flavor() can be used to obtain the current flavor.
//
//     CdlValueFlavor CdlValue::get_flavor() const;
//
// Values may be enabled or disabled. Values of flavor None
// and Data are always enabled. Values of flavor Bool or BoolData
// may or may not be enabled, by default they are disabled.
//
//     bool CdlValue::is_enabled(...) const;
//
// (The optional argument to is_enabled() is discussed later).
//
// Values of flavor BoolData and Data also have a string value,
// which can be interpreted as an integer or a double under
// the right circumstances.
//
//     std::string CdlValue::get_value(...) const;
//     bool        CdlValue::has_integer_value(...) const;
//     bool        CdlValue::has_double_value(...) const;
//     cdl_int     CdlValue::get_integer_value(...) const;
//     double      CdlValue::get_double_value(...) const;
//
// This is equivalent to a CdlSimpleValue object, and in fact
// that is the internal representation. It is possible to
// get hold of the CdlSimpleValue object directly:
//
//     CdlSimpleValue CdlValue::get_simple_value(...) const;
//
// The get_integer_value() and get_double_value() members should
// only be used if you are confident that the current value has
// an integer or double representation. Otherwise the result is
// undefined.
//
// The optional argument to these member functions represents
// the source. A value can be set from four different sources:
// the default value (usually either 0 or the result of
// evaluating a default_value property); an inferred value,
// determined by the inference engine; a wizard value, i.e.
// what a CDL wizard believes the correct value to be based
// on user input; and a user value, something explicitly
// set by the end user. These have different priorities:
// the inference engine can override default values but not
// user values. A CdlValue object keeps track of the current
// source.
//
//    CdlValueSource CdlValue::get_source() const;
//
// If no argument is given to e.g. is_enabled() then the
// current source is used. Otherwise it is possible to find
// out whether or not the entity is enabled for each of the
// sources.
//
// The default source is always defined, the others may or
// may not be. It is possible to find out for each source
// whether or not a value has been set.
//
//   bool CdlValue::has_source(CdlValueSource) const;
//
//
// Updating values normally happens in the CdlValuable class,
// but the member functions are the same. There is a member
// function to change the flavor:
//
//   void CdlValue::set_flavor(CdlValueFlavor);
//
// However this member function is intended only for use by the
// library itself. An entity's flavor is normally defined by CDL data,
// and should not be updated explicitly by application code.
//
// There are two member functions to manipulate the value source:
//
//     void CdlValue::set_source(CdlValueSource);
//     void CdlValue::invalidate_source(CdlValueSource);
//
// The first function can be used if e.g. the user wants to
// change his or her mind and go back to the default value
// rather than a user value. The user value is not forgotten
// and can be reinstated. 
//
// invalidate_source() can be used to completely cancel a
// value source. If that source happens to be the current one
// then the current source will be adjusted appropriately.
// It is illegal to attempt to invalidate the default source.
//
// For values with flavor Bool and BoolData, there are three
// member functions that can be used to control the enabled
// status:
//
//   void CdlValue::set_enabled(bool, CdlValueSource);
//   void CdlValue::enable(CdlValueSource);
//   void CdlValue::disable(CdlValueSource);
//
// Note that when updating a CdlValue object the source should
// be known and must be specified. If the source has a higher
// priority than the current one then it will automatically
// become the new source. On the rare occasion that this is
// not desired, set_source() will have to be used afterwards
// to reset the current source.
//
// For values with flavor BoolData and Data the following
// member functions are available to change the value string:
//
//   void CdlValue::set_value(std::string, CdlValueSource);
//   void CdlValue::set_value(cdl_int, CdlValueSource);
//   void CdlValue::set_value(double, CdlvalueSource);
//   void CdlValue::set_value(CdlSimpleValue&, CdlValueSource);
//
// For values with flavor BoolData is is possible to
// combine updating the enabled flag and the string value:
//
//   void CdlValue::set_enabled_and_value(bool, std::string, CdlValueSource);
//   void CdlValue::set_enabled_and_value(bool, cdl_int, CdlValueSource);
//   void CdlValue::set_enabled_and_value(bool, double, CdlValueSource);
//   void CdlValue::set_enabled_and_value(bool, CdlSimpleValue&, CdlValueSource);
//   void CdlValue::enable_and_set_value(std::string, CdlValueSource);
//   void CdlValue::enable_and_set_value(cdl_int, CdlValueSource);
//   void CdlValue::enable_and_set_value(double, CdlValueSource);
//   void CdlValue::enable_and_set_value(CdlSimpleValue&, CdlValueSource);
//   void CdlValue::disable_and_set_value(std::string, CdlValueSource);
//   void CdlValue::disable_and_set_value(cdl_int, CdlValueSource);
//   void CdlValue::disable_and_set_value(double, CdlValueSource);
//   void CdlValue::disable_and_set_value(CdlSimpleValue&, CdlValueSource);
//
// Obviously many of these functions are just simple inlines.
//
// There is one final member function:
//
//   void CdlValue::set(CdlSimpleValue, CdlValueSource);
//
// This member function is defined to do the right thing,
// whatever the flavor happens to be.

class CdlValue {
    
    friend class CdlTest;

  public:

    CdlValue(CdlValueFlavor = CdlValueFlavor_Bool);
    virtual ~CdlValue();
    CdlValue(const CdlValue&);
    CdlValue&           operator=(const CdlValue&);

    CdlValueFlavor      get_flavor() const;
    CdlValueSource      get_source() const;
    bool                has_source(CdlValueSource) const;

    bool                is_enabled(CdlValueSource = CdlValueSource_Current) const;
    std::string         get_value(CdlValueSource = CdlValueSource_Current) const;
    bool                has_integer_value(CdlValueSource = CdlValueSource_Current) const;
    bool                has_double_value(CdlValueSource = CdlValueSource_Current) const;
    cdl_int             get_integer_value(CdlValueSource = CdlValueSource_Current) const;
    double              get_double_value(CdlValueSource = CdlValueSource_Current) const;
    CdlSimpleValue      get_simple_value(CdlValueSource = CdlValueSource_Current) const;
    
    void set_source(CdlValueSource);
    void invalidate_source(CdlValueSource);
    
    void set_enabled(bool, CdlValueSource);
    void enable(CdlValueSource source)
    {
        set_enabled(true, source);
    }
    void disable(CdlValueSource source)
    {
        set_enabled(false, source);
    }

    void set_value(CdlSimpleValue&, CdlValueSource);
    void set_value(std::string data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_value(val, source);
    }
    void set_integer_value(cdl_int data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_value(val, source);
    }
    void set_double_value(double data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_value(val, source);
    }
    void set_enabled_and_value(bool, CdlSimpleValue&, CdlValueSource);
    void set_enabled_and_value(bool enabled, std::string data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_enabled_and_value(enabled, val, source);
    }
    void set_enabled_and_value(bool enabled, cdl_int data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_enabled_and_value(enabled, val, source);
    }
    void set_enabled_and_value(bool enabled, double data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_enabled_and_value(enabled, val, source);
    }
    void enable_and_set_value(CdlSimpleValue& val, CdlValueSource source)
    {
        set_enabled_and_value(true, val, source);
    }
    void enable_and_set_value(std::string data, CdlValueSource source)
    {
        set_enabled_and_value(true, data, source);
    }
    void enable_and_set_value(cdl_int data, CdlValueSource source)
    {
        set_enabled_and_value(true, data, source);
    }
    void enable_and_set_value(double data, CdlValueSource source)
    {
        set_enabled_and_value(true, data, source);
    }
    void disable_and_set_value(CdlSimpleValue& val, CdlValueSource source)
    {
        set_enabled_and_value(false, val, source);
    }
    void disable_and_set_value(std::string data, CdlValueSource source)
    {
        set_enabled_and_value(false, data, source);
    }
    void disable_and_set_value(cdl_int data, CdlValueSource source)
    {
        set_enabled_and_value(false, data, source);
    }
    void disable_and_set_value(double data, CdlValueSource source)
    {
        set_enabled_and_value(false, data, source);
    }

    void set(CdlSimpleValue&, CdlValueSource);
    
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

    // This should only be used by the library itself.
    void                set_flavor(CdlValueFlavor);
    
  protected:
    
  private:
    
    CdlValueFlavor      flavor;
    CdlValueSource      current_source;

    // FIXME: a static const member should be used for the array
    // sizes, but VC++ does not support that part of the language.
    // FIXME: std::bitset should be used here. Using lots of separate
    // bools here is inefficient.
    bool                source_valid[4];
    bool                enabled[4];
    CdlSimpleValue      values[4];
    
    enum {
        CdlValue_Invalid = 0,
        CdlValue_Magic   = 0x41837960
    } cdlvalue_cookie;
};

//}}}
//{{{  CdlSubexpression                 

// ----------------------------------------------------------------------------
// Expressions come into existence primarily as the result of reading
// in certain properties like default_value in CDL data. It is also
// possible for expressions to be generated and evaluated on the fly
// inside Tcl code, but that is expected to be a comparatively rare
// events. Expression objects always live on the heap, usually only
// in derived classes.
//
// An ordinary expression evaluates to a single value. There are two
// other types of expression in the CDL language, goal expressions and
// list expression. A goal expression is essentially a set of ordinary
// expressions with implicit &&'s between them. A list expression
// is a set of expressions that can be evaluated to a constant vector,
// plus pairs of expressions that constitute ranges. Again goal and
// list expressions only live on the heap.
//
// Both parsing an evaluation involve tokens for the various
// operators. The inference engine, conflict reporting code, and
// other diagnostic code will also need to have ready access to
// this information. Hence it makes a bit more sense to have
// the enum outside the expression class.

enum CdlExprOp {
    CdlExprOp_Invalid           =  0,
    CdlExprOp_EOD               =  1,   // End of data reached
    CdlEXprOp_Command           =  2,   // [tcl code]
    CdlExprOp_Variable          =  3,   // $tcl_variable
    CdlExprOp_StringConstant    =  4,   // "hello"
    CdlExprOp_IntegerConstant   =  5,   // 123
    CdlExprOp_DoubleConstant    =  6,   // 3.1415
    CdlExprOp_Reference         =  7,   // CYGPKG_INFRA
    CdlExprOp_Range             =  8,   // x to y
    CdlExprOp_Negate            =  9,   // -x
    CdlExprOp_Plus              = 10,   // +x
    CdlExprOp_LogicalNot        = 11,   // !x
    CdlExprOp_BitNot            = 12,   // ~x
    CdlExprOp_Indirect          = 13,   // *x
    CdlExprOp_Active            = 14,   // ?x
    CdlExprOp_Function          = 15,   // sin(x)
    CdlExprOp_Multiply          = 16,   // x * y
    CdlExprOp_Divide            = 17,   // x / y
    CdlExprOp_Remainder         = 18,   // x % y
    CdlExprOp_Add               = 19,   // x + y
    CdlExprOp_Subtract          = 20,   // x - y
    CdlExprOp_LeftShift         = 21,   // x << y
    CdlExprOp_RightShift        = 22,   // x >> y
    CdlExprOp_LessThan          = 23,   // x < y
    CdlExprOp_LessEqual         = 24,   // x <= y
    CdlExprOp_GreaterThan       = 25,   // x > y
    CdlExprOp_GreaterEqual      = 26,   // x >= y
    CdlExprOp_Equal             = 27,   // x == y
    CdlExprOp_NotEqual          = 28,   // x != y
    CdlExprOp_BitAnd            = 29,   // x & y
    CdlExprOp_BitXor            = 30,   // x ^ y
    CdlExprOp_BitOr             = 31,   // x | y
    CdlExprOp_And               = 32,   // x && y
    CdlExprOp_Or                = 33,   // x || y
    CdlExprOp_Cond              = 34,   // x ? a : b
    CdlExprOp_StringConcat      = 35,   // x . y
    CdlExprOp_Implies           = 36,   // x implies y
    CdlExprOp_Xor               = 37,   // x xor y
    CdlExprOp_Eqv               = 38    // x eqv y
};

// ----------------------------------------------------------------------------
// A subexpression consists of an operation, possibly some constant
// data, and possibly indices into the subexpression vector.
// Normally some unions would be used, but unions and objects such
// as std::string do not mix, and the amount of memory involved is
// not big enough to really worry about.

#define CdlFunction_MaxArgs     3
struct CdlSubexpression {

    CdlExprOp           op;
    CdlSimpleValue      constants;              // String, integer or double constant
    int                 reference_index;        // iff CdlExprOp_Reference

    int                 lhs_index;              // for all non-constant operators
    int                 rhs_index;              // for binary and ternary operators only
    int                 rrhs_index;             // only for ternary operators.
    
    int                 func;                   // iff CdlExprOp_Function
    int                 args[CdlFunction_MaxArgs];
};

//}}}
//{{{  CdlFunction                      

// ----------------------------------------------------------------------------
// Generic support for function parsing, evaluation, and inference. The
// implementation is extensible so that functions can be added to the
// core via static constructors.

class CdlFunction {
    
    friend class CdlTest;
    
  public:
    CdlFunction(const char* /* name */, int /* no_args */,
                void (*)(CdlExpression, const CdlSubexpression&),
                void (*)(CdlEvalContext&, CdlExpression, const CdlSubexpression&, CdlSimpleValue&),
                bool (*)(CdlTransaction, CdlExpression, unsigned int, bool, int),
                bool (*)(CdlTransaction, CdlExpression, unsigned int, CdlSimpleValue&, int)
                );
    ~CdlFunction();
    
    static bool         is_function(std::string, int&);
    static std::string  get_name(int);
    static int          get_args_count(int);

    static void         check(CdlExpression, const CdlSubexpression&);
    static void         eval(CdlEvalContext&, CdlExpression, const CdlSubexpression&, CdlSimpleValue&);
    static bool         infer_bool(CdlTransaction, CdlExpression, unsigned int, bool, int);
    static bool         infer_value(CdlTransaction, CdlExpression, unsigned int, CdlSimpleValue&, int);

    static void         (*null_check)(CdlExpression, const CdlSubexpression&);
    static bool         (*null_infer_bool)(CdlTransaction, CdlExpression, unsigned int, bool, int);
    static bool         (*null_infer_value)(CdlTransaction, CdlExpression, unsigned int, CdlSimpleValue&, int);
    
  protected:

  private:
    // Keep track of all functions in the system
    static std::vector<CdlFunction*>    all_functions;

    // Each function object is given a unique id during initialization
    static int          next_id;
    int                 id;

    // Provided by the constructor
    const char*         name;
    int                 number_args;
    void                (*check_fn)(CdlExpression, const CdlSubexpression&);
    void                (*eval_fn)(CdlEvalContext&, CdlExpression, const CdlSubexpression&, CdlSimpleValue&);
    bool                (*infer_bool_fn)(CdlTransaction, CdlExpression, unsigned int, bool, int);
    bool                (*infer_value_fn)(CdlTransaction, CdlExpression, unsigned int, CdlSimpleValue&, int);
    
    // The default constructor is illegal
    CdlFunction();
};

//}}}
//{{{  CdlExpression                    

// ----------------------------------------------------------------------------
// And now for the expression class itself.

class CdlExpressionBody {

    friend class CdlTest;
    
  public:

    // The default constructor is basically a no-op, new expression
    // objects only get created as a consequence of parsing. However
    // it exists and is protected for the convenience of derived
    // classes. The copy constructor is protected, allowing parsing
    // code to first parse an expression and then copy the expression
    // into a higher level object. The assignment operator is illegal.
    // There is no reason to hide the destructor.
    virtual ~CdlExpressionBody();

    // An expression involves three pieces of data. There is a vector
    // of subexpressions. It is also necessary to know where
    // evaluation should being, in accordance with operator precedence
    // rules. And there is a vector of CdlReference objects - this
    // needs to be kept separate from the subexpression vector because
    // CdlReference objects are comparatively tricky.
    //
    // All of this data is public and can be readily inspected by the
    // inference engine, by conflict detection code, by diagnostic
    // code, etc.
    std::vector<CdlSubexpression>       sub_expressions;
    int                                 first_subexpression;
    std::vector<CdlReference>           references;
    bool                                update(CdlTransaction, CdlNode, CdlProperty, CdlNode, CdlUpdate);
    
    // There are a number of parsing functions. The first one is
    // used by higher-level code to parse a single expression. Its
    // argument is a single string (which may be the result of
    // concatenating several Tcl arguments), and at the end of the
    // parse operation there should be no further data. The result
    // will either be a new expression object or a parsing exception
    // to be caught by higher level code.
    static CdlExpression        parse(std::string);

    // This is used when parsing list expressions, which involve a
    // sequence of ordinary expressions and possibly range operators.
    // The whole list expression lives in a single string, and it is
    // necessary to provide an index indicating where in the string
    // parsing should begin. It is also useful to return details of
    // the token that caused parsing to terminate (EOD, Range, or
    // the start of something else).
    static CdlExpression        parse(std::string, int&, CdlExprOp&, int&);

    // A goal expression is derived from an ordinary expression but
    // has somewhat different rules for evaluating. Parsing a goal
    // expression involves parsing a number of ordinary expressions
    // with implicit && operators between them, and it requires
    // a parsing function that can be used to extend an existing
    // expression.
    //
    // NOTE: possibly this should should be a protected member, since
    // its main use is in parsing goal expressions. 
    static void continue_parse(CdlExpression, std::string, int&, CdlExprOp&, int&);

    // Evaluating expressions. Note that this may fail at run-time
    // because of errors that cannot be caught sensibly when the
    // expression is read in, for example arithmetic overflow or
    // division by zero. Because such failures are a possibility
    // anyway no special action is taken to prevent an expression
    // with e.g. an unresolved reference from being evaluated.
    //
    // eval() is the public interface, and manages
    // CdlConflict_EvalException objects. eval_internal() is for use
    // by list and goal expressions.
    void eval(CdlEvalContext&, CdlSimpleValue&);
    void eval_internal(CdlEvalContext&, CdlSimpleValue&);
    void eval_subexpression(CdlEvalContext&, int, CdlSimpleValue&);
    
    // The full original expression is useful for diagnostics purposes
    std::string get_original_string() const;
    
    bool        check_this(cyg_assert_class_zeal cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  protected:

    // The default constructor does very little, the main work
    // is done by the various parsing functions. However it is
    // available to derived classes, especially goal expressions.
    CdlExpressionBody();
    
    // The copy constructor has to be usable by derived classes,
    // e.g. CdlExpressionProperty
    CdlExpressionBody(const CdlExpressionBody&);
    
  private:

    
    // The assignment operator is illegal.
    CdlExpressionBody&  operator=(const CdlExpressionBody&);

    // The string that was parsed originally
    std::string                 expression_string;
    
    enum {
        CdlExpressionBody_Invalid       = 0,
        CdlExpressionBody_Magic         = 0x760293a3
    } cdlexpressionbody_cookie;
};

//}}}
//{{{  CdlListExpression                

// ----------------------------------------------------------------------------
// The main use of list expressions is for the legal_values
// properties. Essentially a list expression is just a vector of
// ordinary expressions and ranges of expressions. 

class CdlListExpressionBody {

    friend class CdlTest;

  public:

    // Availability of constructors etc. is as per the ordinary
    // expression class.
    virtual ~CdlListExpressionBody();
    
    // The data associated with a list expression is a vector of
    // expressions, plus a vector of expression pairs constituting
    // ranges. As with ordinary expressions the data is fully public
    // and can be readily examined by e.g. the inference engine.
    std::vector<CdlExpression>                                  data;
    std::vector<std::pair<CdlExpression,CdlExpression> >        ranges;

    // Parsing. This involves taking a single string, typically from
    // a CDL script, and parsing one or more ordinary expressions.
    static CdlListExpression parse(std::string);
    
    // Evaluation support. A list expression evaluates to a list value.
    void eval(CdlEvalContext&, CdlListValue&);

    // More commonly client code is going to be interested in whether
    // or not a particular value is a legal member. The result
    // cache ensures that it is possible to 
    bool is_member(CdlEvalContext&, CdlSimpleValue&);
    bool is_member(CdlEvalContext&, std::string);
    bool is_member(CdlEvalContext&, cdl_int);
    bool is_member(CdlEvalContext&, double);

    // The full original expression is useful for diagnostics purposes
    std::string get_original_string() const;
    
    bool check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  protected:
    CdlListExpressionBody(const CdlListExpressionBody&);
    bool        update(CdlTransaction, CdlNode, CdlProperty, CdlNode, CdlUpdate);

  private:

    CdlListExpressionBody();
    CdlListExpressionBody& operator=(const CdlListExpressionBody&);

    void eval_internal(CdlEvalContext&, CdlListValue&);
    std::string         expression_string;
    
    enum {
        CdlListExpressionBody_Invalid   = 0,
        CdlListExpressionBody_Magic     = 0x7da4bcc2
    } cdllistexpressionbody_cookie;
};

//}}}
//{{{  CdlGoalExpression                

// ----------------------------------------------------------------------------
// A goal expression inherits privately from ordinary expressions. Essentially
// a goal expression is simply a set of ordinary expressions separated by &&,
// but it can only be evaluated to a boolean. The parse() and eval() members
// of the base class should not be exposed. There is a member to get hold of
// the underlying ordinary expression, for use by e.g. the inference engine.

class CdlGoalExpressionBody : private CdlExpressionBody {

    friend class CdlTest;

    typedef CdlExpressionBody inherited;

  public:
    virtual ~CdlGoalExpressionBody();

    static CdlGoalExpression parse(std::string);

    // A few variants of the eval() member, with a choice of returning
    // by value or by reference. The latter provide consistency with the
    // other expression classes.
    bool eval(CdlEvalContext&);
    void eval(CdlEvalContext&, bool&);

    // Provide public access to the underlying expression object,
    // useful for the inference engine
    CdlExpression               get_expression();
    
    // The full original expression is useful for diagnostics purposes
    std::string get_original_string() const;
    
    bool check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  protected:
    CdlGoalExpressionBody(const CdlGoalExpressionBody&);


  private:

    CdlGoalExpressionBody();
    CdlGoalExpressionBody& operator=(const CdlGoalExpressionBody&);
    void eval_internal(CdlEvalContext&, bool&);
    
    std::string expression_string;
    
    enum {
        CdlGoalExpressionBody_Invalid = 0,
        CdlGoalExpressionBody_Magic   = 0x5a58bb24
    } cdlgoalexpressionbody_cookie;
};

//}}}
//{{{  CdlInfer                         

// ----------------------------------------------------------------------------
// A utility class related to inference. This exports the main functions
// needed, allowing e.g. per-function inference routines from func.cxx to
// interact with the main inference engine.

class CdlInfer {
  public:
    static bool make_active(CdlTransaction, CdlNode, int /* level */);
    static bool make_inactive(CdlTransaction, CdlNode, int /* level */);
    static bool set_valuable_value(CdlTransaction, CdlValuable, CdlSimpleValue&, int /* level */);
    static bool set_valuable_bool(CdlTransaction, CdlValuable, bool, int /* level */);
    static bool subexpr_value(CdlTransaction, CdlExpression, unsigned int /* index */, CdlSimpleValue& goal, int /* level */);
    static bool subexpr_bool(CdlTransaction, CdlExpression, unsigned int /* index */, bool, int /* level */);

  private:
    CdlInfer();
};

//}}}

//}}}
//{{{  CdlConflict classes                              

// ----------------------------------------------------------------------------
// As a configuration is created and modified there will be times when
// things are not completely consistent. There may be a reference to
// some option that is not in any package in the current
// configuration. An option may have an invalid value, possibly as a
// side effect of a change to some other option. There may be a
// dependency that is not satisfied. There may be other types of
// conflict.
//
// The library provides a base class CdlConflict, and a number of
// derived classes for common types of conflict such as unresolved
// references. All conflicts are associated with a CdlNode and a
// property within that. It is possible to use dynamic_cast<> to find
// out the exact type of a conflict, or alternatively to use the
// virtual member function get_explanation().
//
// Conflicts may be disabled by the user if they are not actually
// important as far as application code is concerned. In other words
// the end user is allowed to override the constraints specified in
// the CDL. This information is saved with the configuration data.
// Preferably the user should give an explanation for why the conflict
// is disabled, to serve as a reminder some months later when the
// configuration is reloaded.
//
//
// Conflicts have a fairly complicated life cycle. First it is
// necessary to distinguish between structural and normal conflicts. A
// structural conflict is typically caused by a reference to a
// non-existent valuable. These conflicts are generally created only
// when something is loaded, and only go away when something is
// unloaded. A normal conflict is typically related to a value, for
// example a value outside the legal range, or a "requires" property
// that is not satisfied.
//
// Conflicts are created and destroyed in the context of a
// transaction, which in turn operates in the context of a toplevel.
// If the transaction is committed then new conflicts get added to the
// appropriate toplevel list, and destroyed conflicts get removed from
// the toplevel list. The transaction field indicates whether the
// conflict is currently per-transaction or global.
//
// Transactions may get nested, i.e. a conflict may get created as
// part of a sub-transaction, and when that sub-transaction is committed
// the conflict is moved to the parent transaction.
//
// For each toplevel, libcdl keeps track of all conflicts. This only
// applies to committed conflicts, per-transaction conflicts are not
// accessible in this way.
//
// As part of a transaction, libcdl may attempt to find solutions for
// particular conflicts, and those solutions may get installed
// automatically. No attempt is made to keep track of solutions
// on a global basis, only on a per-transaction basis.

class CdlConflictBody {
    
    friend class CdlTest;

    // Transactions and conflicts are closely connected
    friend class CdlTransactionBody;
    
  public:

    // Creation happens only inside a derived class.
    // Clearing a conflict only happens inside transactions.
    // Destroying a conflict only happens from inside a
    // per-transaction clear(), or during a transaction commit.
    
    // Is this conflict part of a transaction, or has it been committed to the toplevel.
    CdlTransaction      get_transaction() const;

    // Is inference implemented for this type of conflict?
    virtual bool        resolution_implemented() const;

    // Try to resolve an existing global conflict. A new transaction
    // is created for this operation, the conflict is resolved within
    // that transaction, and then CdlTransaction::body() is used to
    // handle inference callbacks, commits, etc. See also
    // CdlToplevel::resolve_conflicts() and
    // CdlToplevel::resolve_all_conflicts(). The conflict may cease to
    // exist as a side-effect of this call.
    void                resolve();
  
    // Keep track of whether or not this conflict has a solution
    // 1) a conflict may have a current solution. This gets invalidated
    //    whenever there is a change to a value that was referenced
    //    while identifying the solution.
    //
    //    A current solution is indicated by a non-empty solution vector.
    //    
    // 2) a conflict may not have a current solution. Again this gets
    //    invalidated whenever a referred value changes. There is a boolean
    //    to keep track of this.
    //
    // 3) a conflict may not have a current solution, but another run of
    //    the inference engine may find one.
    bool                has_known_solution() const;
    bool                has_no_solution() const;
    const std::vector<std::pair<CdlValuable, CdlValue> >& get_solution() const;
    const std::set<CdlValuable>& get_solution_references() const;
    void                clear_solution();
    
    // Provide a text message "explaining" the conflict.
    // This only makes sense for derived classes.
    virtual std::string get_explanation() const = 0;

    // Basic information access.
    CdlNode             get_node() const;
    CdlProperty         get_property() const;
    bool                is_structural() const;

    // Enabling and disabling conflicts currently happens outside the
    // context of any transaction.
    // FIXME: these are not currently implemented. It would be necessary
    // to store the information in the savefile, which requires an
    // unambiguous way of identifying a conflict that is likely to
    // survice package version changes.
    void                disable(std::string);
    void                enable();
    bool                is_enabled() const;
    std::string         get_disabled_reason() const;
    
    bool check_this(cyg_assert_class_zeal zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  protected:
    CdlConflictBody(CdlTransaction, CdlNode, CdlProperty, bool /* structural */);
    
    // The destructor gets accessed from inside the friend transaction class,
    // either during a clear_conflict() or during a transaction commit.
    virtual ~CdlConflictBody();
    
    // All conflicts are associated with a node and a property.
    // This information will be useful to derived classes'
    // implementations of get_explanation()
    CdlNode             node;
    CdlProperty         property;
    
  private:

    // Attempt to resolve a conflict in a sub-transaction
    // This is invoked from inside the transaction resolve code.
    // There are additional exported interfaces inside and outside
    // the transaction class.
    virtual bool        inner_resolve(CdlTransaction, int);
    
    // Keep track of the transaction in which this conflict was created.
    // The field is cleared at the end of a transaction.
    CdlTransaction      transaction;

    // Usually the derived class will decide whether or not
    // this conflict is structural in nature, but the data
    // needs to be available at base constructor time so
    // a virtual function is not appropriate.
    bool                structural;
    
    // Solution support
    bool                                           no_solution;
    std::vector<std::pair<CdlValuable, CdlValue> > solution;
    std::set<CdlValuable>                          solution_references;
    void update_solution_validity(CdlValuable);
    
    // Users may disable a conflict. Usually they will have to
    // supply a reason for this.
    bool                enabled;
    std::string         reason;

    enum {
        CdlConflictBody_Invalid = 0,
        CdlConflictBody_Magic   = 0x073e8853
    } cdlconflictbody_cookie;

    // Illegal operations. Conflicts always live on the heap.
    CdlConflictBody();
    CdlConflictBody(const CdlConflictBody&);
    CdlConflictBody& operator=(const CdlConflictBody&);
};

// ----------------------------------------------------------------------------
// An unresolved conflict means that there is a reference in some
// property to an entity that is not yet in the current configuration.
// The class provides convenient access to the name of the unresolved
// entity. 

class CdlConflict_UnresolvedBody : public CdlConflictBody {
    
    friend class CdlTest;
  public:

    static void         make(CdlTransaction, CdlNode, CdlProperty, std::string);

    std::string         get_target_name() const;
    std::string         get_explanation() const;
    static bool         test(CdlConflict);
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  protected:

  private:
    virtual ~CdlConflict_UnresolvedBody();
    CdlConflict_UnresolvedBody(CdlTransaction, CdlNode, CdlProperty, std::string);
    std::string         target_name;
    enum {
        CdlConflict_UnresolvedBody_Invalid      = 0,
        CdlConflict_UnresolvedBody_Magic        = 0x1b24bb8a
    } cdlconflict_unresolvedbody_cookie;
    
    CdlConflict_UnresolvedBody();
    CdlConflict_UnresolvedBody(const CdlConflict_UnresolvedBody&);
    CdlConflict_UnresolvedBody& operator=(const CdlConflict_UnresolvedBody&);
};

// ----------------------------------------------------------------------------
// An illegal value can be caused because of a number of properties:
// legal_values, check_proc, entry_proc, ... In the case of the latter
// the Tcl code should provide text explaining why the value is
// illegal.

class CdlConflict_IllegalValueBody : public CdlConflictBody {

    friend class CdlTest;

  public:

    static void         make(CdlTransaction, CdlNode, CdlProperty);

    bool                resolution_implemented() const;
    
    std::string         get_explanation() const;
    void                set_explanation(std::string);
    static bool         test(CdlConflict);
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  protected:

  private:
    virtual ~CdlConflict_IllegalValueBody();
    bool    inner_resolve(CdlTransaction, int);
    CdlConflict_IllegalValueBody(CdlTransaction, CdlNode, CdlProperty);
    std::string explanation;
    enum {
        CdlConflict_IllegalValueBody_Invalid    = 0,
        CdlConflict_IllegalValueBody_Magic      = 0x4fb27ed1
    } cdlconflict_illegalvaluebody_cookie;

    CdlConflict_IllegalValueBody();
    CdlConflict_IllegalValueBody(const CdlConflict_IllegalValueBody&);
    CdlConflict_IllegalValueBody& operator=(const CdlConflict_IllegalValueBody&);
};

// ----------------------------------------------------------------------------
// There are times when expression evaluation will fail, e.g. because of
// a division by zero. The explanation is supplied by the evaluation code.

class CdlConflict_EvalExceptionBody : public CdlConflictBody {

    friend class CdlTest;

  public:

    static void         make(CdlTransaction, CdlNode, CdlProperty, std::string);

    std::string         get_explanation() const;
    void                set_explanation(std::string);   // mainly for internal use
    static bool         test(CdlConflict);
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  protected:

  private:
    virtual ~CdlConflict_EvalExceptionBody();
    CdlConflict_EvalExceptionBody(CdlTransaction, CdlNode, CdlProperty, std::string);
    std::string explanation;
    enum {
        CdlConflict_EvalExceptionBody_Invalid   = 0,
        CdlConflict_EvalExceptionBody_Magic     = 0x7e64bc41
    } cdlconflict_evalexceptionbody_cookie;
};

// ----------------------------------------------------------------------------
// A goal expression evaluates to false. Producing sensible diagnostics
// depends on a detailed understanding of goal expressions, which will 
// have to wait until the inference engine comes along.

class CdlConflict_RequiresBody : public CdlConflictBody {

    friend class CdlTest;

  public:

    static void         make(CdlTransaction, CdlNode, CdlProperty);
    bool                resolution_implemented() const;
    
    std::string         get_explanation() const;
    static bool         test(CdlConflict);
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  protected:

  private:
    virtual ~CdlConflict_RequiresBody();
    bool     inner_resolve(CdlTransaction, int);
    CdlConflict_RequiresBody(CdlTransaction, CdlNode, CdlProperty);
    enum {
        CdlConflict_RequiresBody_Invalid        = 0,
        CdlConflict_RequiresBody_Magic          = 0x78436331
    } cdlconflict_requiresbody_cookie;
};

// ----------------------------------------------------------------------------
// There is an unusual problem in the configuration data somewhere.
// For example, a parent property can be resolved but the target is
// not a container. There is not a lot that the user can do about
// problems like this, apart from complaining to the component vendor,
// but the problem should not be ignored either.

class CdlConflict_DataBody : public CdlConflictBody {

    friend class CdlTest;

  public:

    static void         make(CdlTransaction, CdlNode, CdlProperty, std::string);

    std::string         get_explanation() const;
    static bool         test(CdlConflict);
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  protected:

  private:
    virtual ~CdlConflict_DataBody();
    CdlConflict_DataBody(CdlTransaction, CdlNode, CdlProperty, std::string);
    std::string message;
    enum {
        CdlConflict_DataBody_Invalid    = 0,
        CdlConflict_DataBody_Magic      = 0x2cec7ad8
    } cdlconflict_databody_cookie;
};

//}}}
//{{{  CdlProperty class and derived classes            

//{{{  Description                              

// ---------------------------------------------------------------------------
// There are many different kinds of property. An alias property contains
// a simple string. A check_proc property contains a fragment of Tcl code
// which can be represented internally as a string, as bytecodes, or both.
// A requires property contains a goal expression. ...
//
// The implementation involves a base class CdlProperty and various
// derived classes such as CdlProperty_StringBody and
// CdlProperty_ExpressionBody.
//
// New CdlProperty objects get created only when reading in CDL scripts,
// while executing commands like alias and requires. These commands are
// implemented as C++ functions hooked into the TCL interpreter. The
// property arguments are available as an argc/argv pair. Each command
// will parse and validate the arguments and then invoke an appropriate
// constructor.

//}}}
//{{{  CdlPropertyId_xxx                        

// ----------------------------------------------------------------------------
// Properties are identified by strings rather than by an enum or anything
// like that. A string-based approach allows new properties to be added at
// any time without invalidating an existing enum, complicating switch()
// statements, etc. There are some performance issues but these are
// manageable.
//
// A disadvantage of using strings is that there is a problem with
// typos. Mistyping something like CdlPropertyId_Compile will generally
// result in a compile-time failure. Mistyping "Complie" will cause
// strange behaviour at run-time and is hard to track down.
//
// A compromise solution is to have #define'd string constants.

#define CdlPropertyId_ActiveIf          "ActiveIf"
#define CdlPropertyId_BuildProc         "BuildProc"
#define CdlPropertyId_Calculated        "Calculated"
#define CdlPropertyId_CancelProc        "CancelProc"
#define CdlPropertyId_CheckProc         "CheckProc"
#define CdlPropertyId_Compile           "Compile"
#define CdlPropertyId_ConfirmProc       "ConfirmProc"
#define CdlPropertyId_DecorationProc    "DecorationProc"
#define CdlPropertyId_DefaultValue      "DefaultValue"
#define CdlPropertyId_Define            "Define"
#define CdlPropertyId_DefineHeader      "DefineHeader"
#define CdlPropertyId_DefineProc        "DefineProc"
#define CdlPropertyId_Description       "Description"
#define CdlPropertyId_Dialog            "Dialog"
#define CdlPropertyId_Display           "Display"
#define CdlPropertyId_DisplayProc       "DisplayProc"
#define CdlPropertyId_Doc               "Doc"
#define CdlPropertyId_EntryProc         "EntryProc"
#define CdlPropertyId_Flavor            "Flavor"
#define CdlPropertyId_DefineFormat      "DefineFormat"
#define CdlPropertyId_Group             "Group"
#define CdlPropertyId_Hardware          "Hardware"
#define CdlPropertyId_IfDefine          "IfDefine"
#define CdlPropertyId_Implements        "Implements"
#define CdlPropertyId_IncludeDir        "IncludeDir"
#define CdlPropertyId_IncludeFiles      "IncludeFiles"
#define CdlPropertyId_InitProc          "InitProc"
#define CdlPropertyId_InstallProc       "InstallProc"
#define CdlPropertyId_LegalValues       "LegalValues"
#define CdlPropertyId_Library           "Library"
#define CdlPropertyId_LicenseProc       "LicenseProc"
#define CdlPropertyId_Make              "Make"
#define CdlPropertyId_Makefile          "Makefile"
#define CdlPropertyId_MakeObject        "MakeObject"
#define CdlPropertyId_NoDefine          "NoDefine"
#define CdlPropertyId_Object            "Object"
#define CdlPropertyId_Parent            "Parent"
#define CdlPropertyId_Requires          "Requires"
#define CdlPropertyId_Screen            "Screen"
#define CdlPropertyId_Script            "Script"
#define CdlPropertyId_UpdateProc        "UpdateProc"
#define CdlPropertyId_Wizard            "Wizard"

//}}}
//{{{  Base class                               

// ----------------------------------------------------------------------------
// The base class is never used directly. Instead the appropriate derived
// objects are instantiated and when appropriate it will be necessary to
// do a dynamic cast from a CdlProperty to e.g. a CdlProperty_String.

class CdlPropertyBody {

    friend class CdlTest;
    
  public:
    // The destructor is public, to avoid possible problems with STL.
    virtual ~CdlPropertyBody();
    
    // These routines provide access to the basic data.
    std::string get_property_name() const;

    // Get hold of the arguments that were present in the original data.
    int         get_argc() const;
    bool        has_option(std::string) const;
    std::string get_option(std::string) const;
    const std::vector<std::string>&     get_argv() const;
    const std::vector<std::pair<std::string,std::string> >&     get_options() const;
    
    // Resolve any references, or generate/update appropriate conflict
    // objects. The default implementation is a no-op because not all
    // properties involve references.
    virtual void update(CdlTransaction, CdlNode /* source */, CdlNode /* dest */, CdlUpdate);
    
    bool check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  protected:

    // The legal constructor can only get invoked from a derived class
    // constructor. The first argument identifies the property, e.g.
    // CdlPropertyId_Doc (which is just #define'd to the string
    // "doc").
    //
    // The argc and argv fields provide access to the original
    // data in the command that resulted in the property being
    // constructed. Often but not always argv[0] will be the same as
    // the property id. The argv information is stored mainly for
    // diagnostics purposes, it may be removed in future to avoid
    // wasting memory.
    //
    // The options field is the result of parsing options such
    // as -library=libextras.a. It consists of a vector of
    // <name/value> pairs, and is usually obtained via
    // CdlParse::parse_options().
    CdlPropertyBody(CdlNode, std::string, int argc, const char* argv[], std::vector<std::pair<std::string,std::string> >&);
    
  private:
    // This string indicates the command used to define this property,
    // e.g. "doc" or "define_proc". It is provided to the constructor.
    std::string                 name;

    // All property data comes out of a file and gets rid via a
    // Tcl interpreter. The raw file data is stored with the property,
    // mainly for diagnostics purposes.
    std::vector<std::string>    argv;

    std::vector<std::pair<std::string, std::string> >   options;

    // The usual set of illegal operations.
    CdlPropertyBody();
    CdlPropertyBody(const CdlPropertyBody&);
    CdlPropertyBody& operator=(const CdlPropertyBody&);
    
    enum {
        CdlPropertyBody_Invalid = 0,
        CdlPropertyBody_Magic   = 0x60dd58f4
    } cdlpropertybody_cookie;
};

//}}}
//{{{  CdlProperty_Minimal                      

// ----------------------------------------------------------------------------
// This class is used for properties that are simple flags, e.g. no_define.
// There should be no additional data associated with such properties.

class CdlProperty_MinimalBody : public CdlPropertyBody {

    friend class CdlTest;
    
  public:
    static CdlProperty_Minimal   make(CdlNode, std::string, int, const char*[], std::vector<std::pair<std::string,std::string> >&);
    virtual ~CdlProperty_MinimalBody( );
    bool                        check_this( cyg_assert_class_zeal = cyg_quick ) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  protected:
    
  private:
    typedef CdlPropertyBody     inherited;
    
    CdlProperty_MinimalBody(CdlNode, std::string, int, const char*[], std::vector<std::pair<std::string,std::string> >&);
    enum {
        CdlProperty_MinimalBody_Invalid = 0,
        CdlProperty_MinimalBody_Magic   = 0x25625b8c
    } cdlproperty_minimalbody_cookie;

    CdlProperty_MinimalBody();
    CdlProperty_MinimalBody(const CdlProperty_MinimalBody&);
    CdlProperty_MinimalBody& operator=(const CdlProperty_MinimalBody&);
};

//}}}
//{{{  CdlProperty_String                       

// ----------------------------------------------------------------------------
// A string property contains a single piece of additional data in the form
// of a string.

class CdlProperty_StringBody : public CdlPropertyBody {

    friend class CdlTest;
    
  public:
    static CdlProperty_String    make(CdlNode, std::string, std::string, int, const char*[],
                                      std::vector<std::pair<std::string,std::string> >&);
    virtual ~CdlProperty_StringBody();

    std::string                 get_string(void) const;
    bool                        check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  protected:
    
  private:
    typedef CdlPropertyBody     inherited;
    
    CdlProperty_StringBody(CdlNode, std::string /* id */, std::string /* data */, int, const char*[],
                           std::vector<std::pair<std::string,std::string> >&);
    std::string                 data;
    enum {
        CdlProperty_StringBody_Invalid = 0,
        CdlProperty_StringBody_Magic   = 0x78d1ca94
    } cdlproperty_stringbody_cookie;

    // The only legal constructor supplies all the data.
    CdlProperty_StringBody();
    CdlProperty_StringBody(const CdlProperty_StringBody&);
    CdlProperty_StringBody& operator=(const CdlProperty_StringBody&);
};

//}}}
//{{{  CdlProperty_TclCode                      

// ----------------------------------------------------------------------------
// A TclCode property is currently equivalent to a string property. In
// future this may change to allow the byte-compiled versions of the
// script to be stored.
//
// One of the properties, "screen" inside a cdl_wizard, also takes
// an integer. Rather than create yet another class, this is handled
// by a separate constructor.


class CdlProperty_TclCodeBody : public CdlPropertyBody {

    friend class CdlTest;

  public:
    static CdlProperty_TclCode   make(CdlNode, std::string, cdl_tcl_code, int, const char*[],
                                      std::vector<std::pair<std::string,std::string> >&);
    static CdlProperty_TclCode   make(CdlNode, std::string, cdl_int, cdl_tcl_code, int, const char*[],
                                      std::vector<std::pair<std::string,std::string> >&);
    virtual ~CdlProperty_TclCodeBody();
    
    cdl_int                     get_number(void) const;
    const cdl_tcl_code&         get_code(void)   const;
    bool                        check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  private:
    typedef CdlPropertyBody     inherited;
    
    CdlProperty_TclCodeBody(CdlNode, std::string, cdl_int, cdl_tcl_code, int, const char*[],
                            std::vector<std::pair<std::string,std::string> >&);

    cdl_int                     number;
    cdl_tcl_code                code;
    enum {
        CdlProperty_TclCodeBody_Invalid = 0,
        CdlProperty_TclCodeBody_Magic   = 0x7b14d4e5
    } cdlproperty_tclcodebody_cookie;

    CdlProperty_TclCodeBody();
    CdlProperty_TclCodeBody(const CdlProperty_TclCodeBody&);
    CdlProperty_TclCodeBody& operator=(const CdlProperty_TclCodeBody&);
    
};

//}}}
//{{{  CdlProperty_StringVector                 

// ----------------------------------------------------------------------------
// This is used for multiple constant strings, as opposed to a list
// expression which requires evaluation. One example is a list
// of aliases.

class CdlProperty_StringVectorBody : public CdlPropertyBody {

    friend class CdlTest;

  public:
    static CdlProperty_StringVector     make(CdlNode, std::string, const std::vector<std::string>&, int, const char*[],
                                             std::vector<std::pair<std::string,std::string> >&);
    virtual ~CdlProperty_StringVectorBody();
    
    const std::vector<std::string>&     get_strings() const;
    std::string                         get_first_string() const;
    unsigned int                        get_number_of_strings() const;
    std::string                         get_string(unsigned int) const;                  
    bool                                check_this(cyg_assert_class_zeal zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  private:
    typedef CdlPropertyBody            inherited;
    
    CdlProperty_StringVectorBody(CdlNode, std::string, const std::vector<std::string>&, int, const char*[],
                                 std::vector<std::pair<std::string,std::string> >&);

    std::vector<std::string>            data;
    enum {
        CdlProperty_StringVectorBody_Invalid = 0,
        CdlProperty_StringVectorBody_Magic   = 0x4ed039f3
    } cdlproperty_stringvectorbody_cookie;

    CdlProperty_StringVectorBody();
    CdlProperty_StringVectorBody(const CdlProperty_StringVectorBody&);
    CdlProperty_StringVectorBody& operator=(const CdlProperty_StringVectorBody&);
};

//}}}
//{{{  CdlProperty_Reference                    

// ----------------------------------------------------------------------------
// This is used for properties such as wizard and dialog, where the data
// identifies some other entity in the system. The class is both a property
// and a reference object. Most of the desired functionality is provided by
// inheritance from CdlReference.

class CdlProperty_ReferenceBody : public CdlPropertyBody, public CdlReference {

    friend class CdlTest;

  public:
    static CdlProperty_Reference make(CdlNode, std::string /* id */, std::string /* destination */,
                                      CdlUpdateHandler, int, const char*[],
                                      std::vector<std::pair<std::string,std::string> >&);
    virtual ~CdlProperty_ReferenceBody();
    
    void update(CdlTransaction, CdlNode, CdlNode, CdlUpdate);
    
    bool check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  private:
    typedef CdlPropertyBody     inherited_property;
    typedef CdlReference        inherited_reference;

    CdlUpdateHandler            update_handler;
    
    CdlProperty_ReferenceBody(CdlNode, std::string /* id */, std::string /* destination */, CdlUpdateHandler, int, const char*[],
                              std::vector<std::pair<std::string,std::string> >&);
    enum {
        CdlProperty_ReferenceBody_Invalid = 0,
        CdlProperty_ReferenceBody_Magic   = 0x78100339
    } cdlproperty_referencebody_cookie;

    CdlProperty_ReferenceBody();
    CdlProperty_ReferenceBody(const CdlProperty_ReferenceBody&);
    CdlProperty_ReferenceBody& operator=(const CdlProperty_Reference&);
};

//}}}
//{{{  CdlProperty_Expression                   

// ----------------------------------------------------------------------------
// An expression property simply inherits its functionality from the basic
// property class and from the expression class.

class CdlProperty_ExpressionBody : public CdlPropertyBody, public CdlExpressionBody {

    friend class CdlTest;
    
  public:
    static CdlProperty_Expression       make(CdlNode, std::string, CdlExpression, CdlUpdateHandler, int, const char*[],
                                             std::vector<std::pair<std::string,std::string> >&);
    virtual ~CdlProperty_ExpressionBody();
    void update(CdlTransaction, CdlNode, CdlNode, CdlUpdate);
    bool check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  private:
    typedef CdlPropertyBody     inherited_property;
    typedef CdlExpressionBody   inherited_expression;

    CdlProperty_ExpressionBody(CdlNode, std::string, CdlExpression, CdlUpdateHandler, int, const char*[],
                               std::vector<std::pair<std::string,std::string> >&);
    
    CdlUpdateHandler update_handler;
    enum {
        CdlProperty_ExpressionBody_Invalid = 0,
        CdlProperty_ExpressionBody_Magic   = 0x05fb4056
    } cdlproperty_expressionbody_cookie;

    CdlProperty_ExpressionBody();
    CdlProperty_ExpressionBody(const CdlProperty_ExpressionBody&);
    CdlProperty_ExpressionBody& operator=(const CdlProperty_ExpressionBody&);
};

//}}}
//{{{  CdlProperty_ListExpression               

// ----------------------------------------------------------------------------
// Similarly a list property simply inherits from property and from
// list expressions.

class CdlProperty_ListExpressionBody : public CdlPropertyBody, public CdlListExpressionBody {

    friend class CdlTest;
    
  public:
    static CdlProperty_ListExpression   make(CdlNode, std::string, CdlListExpression, CdlUpdateHandler, int, const char*[],
                                             std::vector<std::pair<std::string,std::string> >&);
    virtual ~CdlProperty_ListExpressionBody();
    void update(CdlTransaction, CdlNode, CdlNode, CdlUpdate);
    bool check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  private:
    typedef CdlPropertyBody         inherited_property;
    typedef CdlListExpressionBody   inherited_expression;

    CdlProperty_ListExpressionBody(CdlNode, std::string, CdlListExpression, CdlUpdateHandler, int, const char*[],
                                   std::vector<std::pair<std::string,std::string> >&);

    CdlUpdateHandler update_handler;
    enum {
        CdlProperty_ListExpressionBody_Invalid = 0,
        CdlProperty_ListExpressionBody_Magic   = 0x6b0136f5
    } cdlproperty_listexpressionbody_cookie;

    CdlProperty_ListExpressionBody();
    CdlProperty_ListExpressionBody(const CdlProperty_ListExpressionBody&);
    CdlProperty_ListExpressionBody& operator=(const CdlProperty_ListExpressionBody&);
};

//}}}
//{{{  CdlProperty_GoalExpression               

// ----------------------------------------------------------------------------
// And a goal property inherits from property and from goal expressions.

class CdlProperty_GoalExpressionBody : public CdlPropertyBody, public CdlGoalExpressionBody {

    friend class CdlTest;
    
  public:
    static CdlProperty_GoalExpression   make(CdlNode, std::string, CdlGoalExpression, CdlUpdateHandler, int, const char*[],
                                             std::vector<std::pair<std::string,std::string> >&);
    virtual ~CdlProperty_GoalExpressionBody();
    void update(CdlTransaction, CdlNode, CdlNode, CdlUpdate);
    bool check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  private:
    typedef CdlPropertyBody         inherited_property;
    typedef CdlGoalExpressionBody   inherited_expression;

    CdlProperty_GoalExpressionBody(CdlNode, std::string, CdlGoalExpression, CdlUpdateHandler, int, const char*[],
                                   std::vector<std::pair<std::string,std::string> >&);
    
    CdlUpdateHandler update_handler;
    enum {
        CdlProperty_GoalExpressionBody_Invalid = 0,
        CdlProperty_GoalExpressionBody_Magic   = 0x08b2b31e
    } cdlproperty_goalexpressionbody_cookie;

    CdlProperty_GoalExpressionBody();
    CdlProperty_GoalExpressionBody(const CdlProperty_GoalExpressionBody&);
    CdlProperty_GoalExpressionBody& operator=(const CdlProperty_GoalExpressionBody&);
};

//}}}

//}}}
//{{{  CdlParse class                                   

// ----------------------------------------------------------------------------
// This is another utility class for collecting together parsing-related
// functions.
//
// Note that this is only a utility class. When libcdl is used for parsing
// things not related to software configuration the new functionality
// does not have to reside inside the CdlParse class, but it may be
// possible to re-use some of the functionality in that class.

class CdlParse {
    
  public:
    // Utility routines.
    static std::string  get_tcl_cmd_name(std::string);
    static std::string  concatenate_argv(int, const char*[], int);
    static int          parse_options(CdlInterpreter, std::string /* diag_prefix */, const char** /* options */,
                                               int /* argc */, const char*[] /* argv */, int /* start_index */,
                                               std::vector<std::pair<std::string,std::string> >& /* result */);
    static std::string  construct_diagnostic(CdlInterpreter, std::string /* classification */,
                                             std::string /* sub-identifier */, std::string /* message */);
                                       
    static void         report_error(CdlInterpreter, std::string /* sub-identifier */, std::string /* message */);
    static void         report_warning(CdlInterpreter, std::string /* sub-identifier */, std::string /* message */);
    static void         clear_error_count(CdlInterpreter);
    static int          get_error_count(CdlInterpreter);
    static void         incr_error_count(CdlInterpreter, int=1);

    static std::string  get_expression_error_location(void);
    
    // Support for Tcl's "unknown" command
    static int          unknown_command(CdlInterpreter, int, const char*[]);
    
    // Property-related utilities
    static void         report_property_parse_error(CdlInterpreter, std::string, std::string);
    static void         report_property_parse_error(CdlInterpreter, CdlProperty, std::string);
    static void         report_property_parse_warning(CdlInterpreter, std::string, std::string);
    static void         report_property_parse_warning(CdlInterpreter, CdlProperty, std::string);
    
    // Utility parsing routines
    static int  parse_minimal_property(CdlInterpreter, int, const char*[], std::string,
                                       const char**, void (*)(CdlInterpreter, CdlProperty_Minimal));
    static int  parse_string_property(CdlInterpreter, int, const char*[], std::string,
                                      const char**, void (*)(CdlInterpreter, CdlProperty_String));
    static int  parse_tclcode_property(CdlInterpreter, int, const char*[], std::string,
                                       const char**, void (*)(CdlInterpreter, CdlProperty_TclCode));
    static int  parse_stringvector_property(CdlInterpreter, int, const char*[], std::string,
                                            const char**, void (*)(CdlInterpreter, CdlProperty_StringVector),
                                            bool /* allow_empty */ = false);
    static int  parse_reference_property(CdlInterpreter, int, const char*[], std::string,
                                         const char**, void (*)(CdlInterpreter, CdlProperty_Reference),
                                         bool /* allow_empty */,
                                         CdlUpdateHandler);
    static int  parse_expression_property(CdlInterpreter, int, const char*[], std::string, 
                                          const char **, void (*)(CdlInterpreter, CdlProperty_Expression),
                                          CdlUpdateHandler);
    static int  parse_listexpression_property(CdlInterpreter, int, const char*[], std::string,
                                              const char **, void (*)(CdlInterpreter, CdlProperty_ListExpression),
                                              CdlUpdateHandler);
    static int  parse_goalexpression_property(CdlInterpreter, int, const char*[], std::string,
                                              const char **, void (*)(CdlInterpreter, CdlProperty_GoalExpression),
                                              CdlUpdateHandler);
};

//}}}
//{{{  CdlNode                                          

// ----------------------------------------------------------------------------
// A node object has a name and lives in a hierarchy. Each node keeps
// track of the toplevel and owner. The memory overheads are
// relatively small compared with the performance gains when such
// information is needed.
//
// A node object also has a vector of properties, and can be referred to
// by properties in other nodes. Some of the properties may result in
// conflicts.

class CdlNodeBody {

    friend class CdlTest;

    // Adding and removing nodes from the hierarchy is done
    // by CdlToplevel members.
    friend class CdlToplevelBody;

    // CdlLoadable must be able to access the destructor
    friend class CdlLoadableBody;
    
    // It is intended that CdlProperties will also add and remove themselves
    friend class CdlPropertyBody;

    // CdlReference bind and unbind operations need access to
    // the referrers vector. So does CdlTransaction::commit()
    friend class CdlReference;
    friend class CdlTransactionBody;
    
  public:

    // Basic information.
    std::string         get_name() const;
    CdlContainer        get_parent() const;
    CdlLoadable         get_owner() const;
    CdlToplevel         get_toplevel() const;

    // Propagation support. Some updates such as active/inactive changes
    // get applied to nodes as well as to properties. Note that because
    // of multiple inheritance this virtual call can get confusing.
    virtual void        update(CdlTransaction, CdlUpdate);
    
    // Is this node active or not? The is_active() call refers
    // to the global state, things may be different inside a
    // transaction.
    bool                is_active() const;
    bool                is_active(CdlTransaction transaction);

    // Generally nodes become active when the parent becomes
    // active and enabled. Some derived classes may impose
    // additional restrictions, for example because of
    // active_if constraints. This routine can be used
    // to check whether or not a node should become active.
    virtual bool        test_active(CdlTransaction);
    
    // Provide access to the various properties. Currently all this
    // information is publicly available.
    const std::vector<CdlProperty>&     get_properties() const;
    CdlProperty                         get_property(std::string) const;
    void                                get_properties(std::string, std::vector<CdlProperty>&) const;
    std::vector<CdlProperty>            get_properties(std::string) const;
    bool                                has_property(std::string) const;
    int                                 count_properties(std::string) const;

    // Provide access to the various global conflicts. More
    // commonly conflicts are accessed on a per-transaction basis.
    void get_conflicts(std::vector<CdlConflict>&) const;
    void get_conflicts(bool (*)(CdlConflict), std::vector<CdlConflict>&) const;
    void get_structural_conflicts(std::vector<CdlConflict>&) const;
    void get_structural_conflicts(bool (*)(CdlConflict), std::vector<CdlConflict>&) const;
    
    // Provide access to all the referrers. This may not get used very
    // much outside the library itself.
    const std::vector<CdlReferrer>&     get_referrers() const;

    // Add property parsers and validation code appropriate for a
    // node. Currently this is a no-op, there are no properties
    // associated with every node, but this may change in future e.g.
    // for diagnostics purposes.
    static void add_property_parsers(std::vector<CdlInterpreterCommandEntry>& parsers);
    void        check_properties(CdlInterpreter);

    // Persistence support. The final classes such as cdl_option
    // should provide implementations of these functions. The
    // base function takes care of data that was present in an
    // original save file but which was not recognised.
    //
    // Configuration save files are Tcl scripts, so it seems
    // appropriate to handle the I/O via the Tcl library and
    // to have a TCL interpreter available.
    virtual void save(CdlInterpreter, Tcl_Channel, int, bool);
    bool has_additional_savefile_information() const;
    
    // Mainly for diagnostics code, what is the actual name for this
    // type of CDL object? This should be in terms of CDL data, e.g.
    // "package" or "component", rather than in implementation terms
    // such as "CdlPackageBody". 
    virtual std::string get_class_name() const;

    bool check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  protected:
    
    // CdlNodeBodies are only instantiated by derived classes.
    // They must always have a name. They need not be placed
    // in the hierarchy immediately, that can wait until
    // later.
    CdlNodeBody(std::string);
    // A dummy constructor is needed because of the virtual
    // inheritance. 
    CdlNodeBody();

    // Nodes cannot be destroyed directly by application code,
    // only by higher-level library functions such as unload_package()
    virtual ~CdlNodeBody();

    // Updating the name is rarely required, but is useful for savefiles.
    void                set_name(std::string);
    
    // Is the node currently active? This applies to the global state
    // only, not per-transaction state. Some derived classes may want
    // to override the default value
    bool                active;
    
  private:
    
    // The basic data. The name is known during construction.
    // The other three fields get updated by e.g. CdlToplevel::add_node();
    std::string         name;
    CdlContainer        parent;
    CdlLoadable         owner;
    CdlToplevel         toplevel;

    // This is used by remove_node_from_toplevel()/add_node_to_toplevel()
    // to allow the latter to exactly reverse the former
    int                 remove_node_container_position;
    
    // Properties normally only get added during the parsing process,
    // and only get removed when the object itself is destroyed.
    // A vector is the obvious implementation.
    std::vector<CdlProperty> properties;

    // Currently a vector of referrers is used. This vector is subject
    // to change when packages get loaded and unloaded, possibly a
    // list would be better.
    std::vector<CdlReferrer> referrers;

    // Savefiles may contain information that is not recognised by the
    // current library, especially because of savefile hooks which
    // allow e.g. the configuration tool to store its own information
    // in save files. This information must not be lost, even if you are
    // e.g. mixing command line and GUI tools. This vector holds
    // the savefile information so that it can be put in the next
    // savefile.
    std::vector<std::string> unsupported_savefile_strings;
    
    enum {
        CdlNodeBody_Invalid     = 0,
        CdlNodeBody_Magic       = 0x309595b5
    } cdlnodebody_cookie;
    
    // Illegal operations
    CdlNodeBody(const CdlNodeBody&);
    CdlNodeBody& operator=(const CdlNodeBody&);
};

//}}}
//{{{  CdlContainer                                     

// ----------------------------------------------------------------------------
// A container is a node that can contain other nodes.

class CdlContainerBody : virtual public CdlNodeBody {

    friend class Cdltest;

    // Allow CdlNode::check_this() access to the internals
    friend class CdlNodeBody;
    
    // Adding a node to the hierarchy is done by a CdlToplevel member.
    // Ditto for removing.
    friend class CdlToplevelBody;

    // Deleting a container can happen inside CdlToplevel and CdlLoadable
    friend class CdlLoadableBody;
    
  public:

    const std::vector<CdlNode>& get_contents() const;
    bool                        contains(CdlConstNode, bool /* recurse */ = false) const;
    bool                        contains(const std::string, bool /* recurse */ = false) const;
    CdlNode                     find_node(const std::string, bool /* recurse */ = false) const;

    // Propagation support. Some updates such as active/inactive changes
    // get applied to nodes as well as to properties.
    virtual void update(CdlTransaction, CdlUpdate);
    
    // Persistence support.
    virtual void save(CdlInterpreter, Tcl_Channel, int, bool);
    
    virtual std::string get_class_name() const;
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  protected:

    // Containers cannot be destroyed explicitly, only via higher-level
    // code such as unload_package();
    virtual ~CdlContainerBody();

    CdlContainerBody();
    // Special constructor needed for internal use.
    CdlContainerBody(std::string);

    // The CdlToplevel class needs access to its own contents.
    std::vector<CdlNode>                contents;
    
  private:
    enum {
        CdlContainerBody_Invalid        = 0,
        CdlContainerBody_Magic          = 0x543c5f1d
    } cdlcontainerbody_cookie;

    // Illegal operations
    CdlContainerBody(const CdlContainerBody&);
    CdlContainerBody& operator=(const CdlContainerBody&);
};

//}}}
//{{{  CdlLoadable                                      

// ----------------------------------------------------------------------------
// A loadable object is a container that gets loaded or unloaded
// atomically from a toplevel. The key difference is that a loadable
// keeps track of all nodes that were loaded as part of this
// operation, thus allowing unload operations to happen safely even if
// nodes get re-parented all over the hierarchy. In addition, there is
// a slave interpreter associated with every loadable.

class CdlLoadableBody : virtual public CdlContainerBody {

    friend class CdlTest;

    // Allow CdlNode::check_this() access to the internals
    friend class CdlNodeBody;
    
    // Adding nodes to the hierarchy is done by a toplevel member
    friend class CdlToplevelBody;

  public:
    virtual ~CdlLoadableBody();

    
    const std::vector<CdlNode>&         get_owned() const;
    bool                                owns(CdlConstNode) const;
    CdlInterpreter                      get_interpreter() const;
    std::string                         get_repository() const;
    std::string                         get_directory() const;

    // Some properties such as doc and compile reference filenames.
    // A search facility is useful.
    virtual std::string find_relative_file(std::string /* filename */, std::string /* directory */ = "") const;
    virtual std::string find_absolute_file(std::string, std::string, bool /* allow_urls */ = false) const;
    virtual bool        has_subdirectory(std::string) const;

    // These support load/unload operations inside transactions
    // They are static members because some of them will want
    // to delete the loadable.
    static void         transaction_commit_load(CdlTransaction, CdlLoadable);
    static void         transaction_cancel_load(CdlTransaction, CdlLoadable);
    static void         transaction_commit_unload(CdlTransaction, CdlLoadable);
    static void         transaction_cancel_unload(CdlTransaction, CdlLoadable);

    // Binding and unbinding of properties. This involves processing
    // the various properties, calculating default values, etc.
    void                bind(CdlTransaction);
    void                unbind(CdlTransaction);
    
    virtual std::string get_class_name() const;
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  protected:

    CdlLoadableBody(CdlToplevel, std::string /* repository */, std::string /* directory */);

    // Needed by derived classes, but not actually used.
    CdlLoadableBody();
    
  private:
    
    std::vector<CdlNode> owned;
    CdlInterpreter       interp;
    std::string          repository;
    std::string          directory;

    // Used by add/remove_node_from_toplevel()
    int                  remove_node_loadables_position;
    
    enum {
        CdlLoadableBody_Invalid = 0,
        CdlLoadableBody_Magic   = 0x488d6127
    } cdlloadablebody_cookie;

    // Invalid operations
    CdlLoadableBody(const CdlLoadableBody&);
    CdlLoadableBody& operator=(const CdlLoadableBody&);
};

//}}}
//{{{  CdlToplevel                                      

// ----------------------------------------------------------------------------
// Toplevels are containers that live at the top of a hierarchy
// (surprise surprise). This means that they do not have a parent.
// In addition a toplevel object keeps track of all the names
// used, guaranteeing uniqueness and providing a quick lookup
// facility.
//
// Every container is also a node, so every toplevel is a node.
// Inheritance from CdlNode may seem wrong. However it achieves
// consistency, everything in the hierarchy including the toplevel
// is a node. The main disadvantage is that every toplevel now
// needs a name.

class CdlToplevelBody : virtual public CdlContainerBody {

    friend class CdlTest;

    // Allow CdlNode::check_this() access to the internals
    friend class CdlNodeBody;
    
    // The CdlTransaction class needs direct access to the lists
    // of conflicts.
    friend class CdlTransactionBody;

  public:
    virtual ~CdlToplevelBody();

    // Updating the hierarchy. This happens a node at a time. Adding a
    // node involves updating the name->node map in the toplevel,
    // setting the node's parent/owner/toplevel fields, and updating
    // the parent and owner containers. The owner may be 0 for special
    // nodes such as the orphans container. The parent must be known,
    // although it may change later on during a change_parent() call.
    //
    // Removing a node is more complicated, and involves a two-stage
    // process. First the node is removed from the toplevel, thus
    // eliminating the name->node mapping. The owner and parent fields
    // are preserved at this stage (except for the loadable itself),
    // and the operation may be undone if the relevant transaction
    // gets cancelled. If the transaction gets committed then the
    // second remove operation handles the owner and parent fields,
    // just prior to the node being deleted. For convenience there
    // are also per-loadable variants for some of these.
    //
    // change_parent() is used to support parent-properties.
    // A container of 0 indicates an orphan, i.e. a parent
    // property that did not or does not correspond to a
    // current container.
    //
    // There is also a clean-up call. This gets used for interfaces
    // which may alternate between belonging to a loadable and
    // being auto-created.
    void add_node(CdlLoadable, CdlContainer, CdlNode);
    void add_node_to_toplevel(CdlNode);
    void remove_node_from_toplevel(CdlNode);
    static void remove_node(CdlLoadable, CdlContainer, CdlNode);
    void add_loadable_to_toplevel(CdlLoadable);
    void remove_loadable_from_toplevel(CdlLoadable);
    void change_parent(CdlLoadable, CdlContainer /* current */, CdlContainer /* new */, CdlNode, int /* pos */ = -1);
    void cleanup_orphans();

    // Toplevels keep track of all the loadables, in addition to
    // inheriting tree behaviour from CdlContainer. This is convenient
    // for some operations like determining build information
    // which must operate on a per-loadable basis.
    const std::vector<CdlLoadable>& get_loadables() const;
    
    // Name uniqueness is guaranteed. It is convenient to have an STL
    // map as a lookup service.
    CdlNode lookup(const std::string) const;

    // There are two conflict lists associated with each toplevel. One
    // is for "structural" conflicts, ones that can only be resolved
    // by a fairly major change such as loading another package: a
    // typical example is an unresolved parent reference. The other is
    // for conflicts that can probably be resolved simply by changing
    // some values. Both sets of conflicts are held as a simple list.
    //
    // The active vs. inactive state of a CDL entity affects the
    // location of structural vs. non-structural conflicts. If an
    // entity becomes inactive then structural conflicts are not
    // affected, but non-structural conflicts are removed from the
    // global list. If an entity's "requires" expression is not
    // satisfied but the entity is inactive anyway then this is
    // harmless.
    const std::list<CdlConflict>& get_all_conflicts() const;
    const std::list<CdlConflict>& get_all_structural_conflicts() const;

    // Try to resolve some or all conflicts. Typically a new transaction
    // will be created for this.
    void        resolve_conflicts(const std::vector<CdlConflict>&);
    void        resolve_all_conflicts();
    
    // Toplevels can have descriptions provided by the user. This is
    // particularly important for pre-defined templates, target
    // board descriptions, etc. where the user would like some
    // extra information about the template before loading it in.
    // The default value is an empty string.
    std::string         get_description() const;
    void                set_description(std::string);
    
    // Each toplevel must have an associated master Tcl interpreter.
    CdlInterpreter      get_interpreter() const;

    // Each toplevel may have a single active main transaction.
    // For now there is no support for concurrent transactions
    // operating on a single toplevel (although nested transactions
    // are allowed)
    CdlTransaction      get_active_transaction() const;
    
    // Build and define operations are available for all toplevels,
    // even if they are not always applicable
    void                get_build_info(CdlBuildInfo&);
    void                get_all_build_info(CdlBuildInfo&);
    void                generate_config_headers(std::string);
    void                get_config_headers(std::vector<std::string>&);
    void                generate_build_tree(std::string, std::string = "");
    
    // Values can be stored in limbo. This is useful when unloading 
    // and reloading packages, e.g. when changing a version the
    // current settings can be preserved as much as possible.
    void                set_limbo_value(CdlValuable);
    bool                has_limbo_value(std::string) const;
    CdlValue            get_limbo_value(std::string) const;
    CdlValue            get_and_remove_limbo_value(std::string);
    void                clear_limbo();
    
    // Persistence support. These are commented in the source code.
           void         initialize_savefile_support();
    static bool         savefile_support_initialized();
           void         add_savefile_command(std::string, CdlSaveCallback, CdlInterpreterCommand);
           void         add_savefile_subcommand(std::string, std::string, CdlSaveCallback, CdlInterpreterCommand);
           void         get_savefile_commands(std::vector<CdlInterpreterCommandEntry>&);
           void         get_savefile_subcommands(std::string, std::vector<CdlInterpreterCommandEntry>&);
           void         save_command_details(CdlInterpreter, Tcl_Channel, int, bool);
    static int          savefile_handle_command(CdlInterpreter, int, const char*[]);
    static int          savefile_handle_unsupported(CdlInterpreter, int, const char*[]);
    static int          savefile_handle_unknown(CdlInterpreter, int, const char*[]);
           void         save_unsupported_commands(CdlInterpreter, Tcl_Channel, int, bool);
    static cdl_int      get_library_savefile_version();
    static int          savefile_handle_version(CdlInterpreter, int, const char*[]);
    static cdl_int      get_savefile_version(CdlInterpreter);
           void         save_conflicts(CdlInterpreter, Tcl_Channel, int, bool);
    static void         save_separator(CdlInterpreter, Tcl_Channel, std::string, bool);
        
    virtual std::string get_class_name() const;
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  protected:
    CdlToplevelBody(CdlInterpreter);

  private:

    std::map<std::string,CdlNode>       lookup_table;
    std::vector<CdlLoadable>            loadables;
    std::map<std::string,CdlValue>      limbo;
    CdlInterpreter                      interp;
    CdlContainer                        orphans;
    std::string                         description;
    std::list<CdlConflict>              conflicts;
    std::list<CdlConflict>              structural_conflicts;

    // The savefile support corresponding to this application.
    static cdl_int savefile_version;
    static bool    savefile_commands_initialized;
    static std::vector<CdlSavefileCommand> savefile_commands;
    static std::map<std::string,std::vector<CdlSavefileCommand> > savefile_subcommands;

    // Per-toplevel support. A savefile may contain unrecognised
    // commands at the toplevel of a file, as well as unrecognised
    // commands in e.g. the body of a cdl_configuration command.
    // The latter is handled via the CdlNode base class.
    std::vector<std::string> unsupported_savefile_toplevel_strings;
    std::vector<std::string> unsupported_savefile_commands;
    std::map<std::string, std::vector<std::string> > unsupported_savefile_subcommands;

    // Keep track of the current active transaction for this toplevel (if any)
    CdlTransaction      transaction;
    
    enum {
        CdlToplevelBody_Invalid = 0,
        CdlToplevelBody_Magic   = 0x0834666e
    } cdltoplevelbody_cookie;
    
    // Invalid operations
    CdlToplevelBody(const CdlToplevelBody&);
    CdlToplevelBody& operator=(const CdlToplevelBody&);
};

//}}}
//{{{  CdlUserVisible                                   

// ----------------------------------------------------------------------------
// A user-visible object is likely to have properties such as display,
// description and doc. Many user-visible objects will have values but
// not all, for example custom dialogs are likely to have a doc
// property but they do not have a value.

class CdlUserVisibleBody : virtual public CdlNodeBody {

    friend class CdlTest;

  public:
    virtual ~CdlUserVisibleBody();

    std::string         get_display() const;
    std::string         get_description() const;
    std::string         get_doc() const;

    // NOTE: this will only work for absolute doc strings or for doc
    // strings that are relative to the package.
    std::string         get_doc_url() const;
    
    // Add property parsers and validation code appropriate for a
    // user-visible object such as doc and description 
    static void         add_property_parsers(std::vector<CdlInterpreterCommandEntry>& parsers);
    void                check_properties(CdlInterpreter);
    static int          parse_description(CdlInterpreter, int, const char*[]);
    static int          parse_display(CdlInterpreter, int, const char*[]);
    static int          parse_doc(CdlInterpreter, int, const char*[]);

    // Persistence support. The save code simply outputs some comments
    // corresponding to the display, doc and description properties.
    virtual void save(CdlInterpreter, Tcl_Channel, int, bool);
    
    virtual std::string get_class_name() const;
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  protected:
    CdlUserVisibleBody();

  private:

    enum {
        CdlUserVisibleBody_Invalid      = 0,
        CdlUserVisibleBody_Magic        = 0x13bbc817
    } cdluservisiblebody_cookie;

    // Illegal operations
    CdlUserVisibleBody(const CdlUserVisibleBody&);
    CdlUserVisibleBody& operator=(const CdlUserVisibleBody&);
};

//}}}
//{{{  CdlParentable                                    

// ----------------------------------------------------------------------------
// A parentable object may have the parent property, redefining its
// position in the hierarchy.

class CdlParentableBody : virtual public CdlNodeBody {

    friend class CdlTest;

  public:
    virtual ~CdlParentableBody();

    static void         add_property_parsers(std::vector<CdlInterpreterCommandEntry>& parsers);
    void                check_properties(CdlInterpreter);
    static int          parse_parent(CdlInterpreter, int, const char*[]);
    static void         update_handler(CdlTransaction, CdlNode, CdlProperty, CdlNode, CdlUpdate);

    virtual std::string get_class_name() const;
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  protected:
    CdlParentableBody();

  private:

    // Unloads may be cancelled. To restore the previous state exactly
    // it is necessary to keep track of the old position.
    int                 change_parent_save_position;
    
    enum {
        CdlParentableBody_Invalid      = 0,
        CdlParentableBody_Magic        = 0x40c6a077
    } cdlparentablebody_cookie;

    // Illegal operations
    CdlParentableBody(const CdlParentableBody&);
    CdlParentableBody& operator=(const CdlParentableBody&);
};

//}}}
//{{{  CdlValuable                                      

// ----------------------------------------------------------------------------
// A valuable body has a value. Many valuables can be modified but not all.
// Some properties make a valuable object read-only. In future there is
// likely to be support for locked values as well. There is a member function
// to check whether or not a valuable object is modifiable.
//
// Relevant properties for a valuable object are:
//
//  1) flavor           - readily available via CdlValue::get_flavor()
//  2) default_value    - an expression
//  3) legal_values     - a list expression
//  4) entry_proc       - for validation purposes, in addition to legal_values
//  5) check_proc       - ditto
//  6) active_if        - goal expression
//  7) requires         - goal expression
//  8) dialog           - a custom dialog for editing this value
//  9) calculated       - non-modifiable
// 10) implements       - for interfaces
//
// A CdlValuable does not inherit directly from CdlValue, since it should
// not be possible to modify a Valuable directly. Instead it contains a
// CdlValue member, and provides essentially the same functions as
// a CdlValue.

class CdlValuableBody : virtual public CdlNodeBody {

    friend class CdlTest;

    // Transaction commit operations require direct access to the CdlValue
    friend class CdlTransactionBody;
    
  private:
    CdlValue value;
    
  public:
    virtual ~CdlValuableBody();

    // Accessing the current value. There are variants for the global state
    // and for per-transaction operations.
    const CdlValue&     get_whole_value() const;
    
    CdlValueFlavor      get_flavor() const;
    CdlValueFlavor      get_flavor(CdlTransaction transaction) const
    {   // The transaction is irrelevant, it cannot change the flavor
        return this->get_flavor();
    }

    CdlValueSource      get_source() const;
    bool                has_source(        CdlValueSource) const;
    bool                is_enabled(        CdlValueSource = CdlValueSource_Current) const;
    std::string         get_value(         CdlValueSource = CdlValueSource_Current) const;
    bool                has_integer_value( CdlValueSource = CdlValueSource_Current) const;
    cdl_int             get_integer_value( CdlValueSource = CdlValueSource_Current) const;
    bool                has_double_value(  CdlValueSource = CdlValueSource_Current) const;
    double              get_double_value(  CdlValueSource = CdlValueSource_Current) const;
    CdlSimpleValue      get_simple_value(  CdlValueSource = CdlValueSource_Current) const;
    
    CdlValueSource      get_source(CdlTransaction) const;
    bool                has_source(        CdlTransaction, CdlValueSource) const;
    bool                is_enabled(        CdlTransaction, CdlValueSource = CdlValueSource_Current) const;
    std::string         get_value(         CdlTransaction, CdlValueSource = CdlValueSource_Current) const;
    bool                has_integer_value( CdlTransaction, CdlValueSource = CdlValueSource_Current) const;
    cdl_int             get_integer_value( CdlTransaction, CdlValueSource = CdlValueSource_Current) const;
    bool                has_double_value(  CdlTransaction, CdlValueSource = CdlValueSource_Current) const;
    double              get_double_value(  CdlTransaction, CdlValueSource = CdlValueSource_Current) const;
    CdlSimpleValue      get_simple_value(  CdlTransaction, CdlValueSource = CdlValueSource_Current) const;
    
    // -----------------------------------------------------------------
    // Modify access. There are two variants of all the functions:
    //
    // 1) no transaction argument. A transaction will be created,
    //    committed, and destroyed for the change in question.
    //
    // 2) a transaction argument. The existing transaction will be
    //    updated but not committed. This allows multiple changes
    //    to be grouped together.
    //
    // There are only a handful of exported functions, but lots
    // of inline variants.
    void set_source(CdlValueSource);
    void invalidate_source(CdlValueSource);
    void set_enabled(bool, CdlValueSource);
    void set_value(CdlSimpleValue&, CdlValueSource);
    void set_enabled_and_value(bool, CdlSimpleValue&, CdlValueSource);
    void set(CdlSimpleValue&, CdlValueSource);
    
    void set_source(CdlTransaction, CdlValueSource);
    void invalidate_source(CdlTransaction, CdlValueSource);
    void set_enabled(CdlTransaction, bool, CdlValueSource);
    void set_value(CdlTransaction, CdlSimpleValue&, CdlValueSource);
    void set_enabled_and_value(CdlTransaction, bool, CdlSimpleValue&, CdlValueSource);
    void set(CdlTransaction, CdlSimpleValue&, CdlValueSource);
    void set(CdlTransaction, const CdlValue&);
    
    void enable(CdlValueSource source)
    {
        set_enabled(true, source);
    }
    void disable(CdlValueSource source)
    {
        set_enabled(false, source);
    }
    void set_value(std::string data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_value(val, source);
    }
    void set_integer_value(cdl_int data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_value(val, source);
    }
    void set_double_value(double data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_value(val, source);
    }
    void set_enabled_and_value(bool enabled, std::string data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_enabled_and_value(enabled, val, source);
    }
    void set_enabled_and_value(bool enabled, cdl_int data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_enabled_and_value(enabled, val, source);
    }
    void set_enabled_and_value(bool enabled, double data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_enabled_and_value(enabled, val, source);
    }
    void enable_and_set_value(CdlSimpleValue& val, CdlValueSource source)
    {
        set_enabled_and_value(true, val, source);
    }
    void enable_and_set_value(std::string data, CdlValueSource source)
    {
        set_enabled_and_value(true, data, source);
    }
    void enable_and_set_value(cdl_int data, CdlValueSource source)
    {
        set_enabled_and_value(true, data, source);
    }
    void enable_and_set_value(double data, CdlValueSource source)
    {
        set_enabled_and_value(true, data, source);
    }
    void disable_and_set_value(CdlSimpleValue& val, CdlValueSource source)
    {
        set_enabled_and_value(false, val, source);
    }
    void disable_and_set_value(std::string data, CdlValueSource source)
    {
        set_enabled_and_value(false, data, source);
    }
    void disable_and_set_value(cdl_int data, CdlValueSource source)
    {
        set_enabled_and_value(false, data, source);
    }
    void disable_and_set_value(double data, CdlValueSource source)
    {
        set_enabled_and_value(false, data, source);
    }
    void enable(CdlTransaction transaction, CdlValueSource source)
    {
        set_enabled(transaction, true, source);
    }
    void disable(CdlTransaction transaction, CdlValueSource source)
    {
        set_enabled(transaction, false, source);
    }
    void set_value(CdlTransaction transaction, std::string data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_value(transaction, val, source);
    }
    void set_integer_value(CdlTransaction transaction, cdl_int data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_value(transaction, val, source);
    }
    void set_double_value(CdlTransaction transaction, double data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_value(transaction, val, source);
    }
    void set_enabled_and_value(CdlTransaction transaction, bool enabled, std::string data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_enabled_and_value(transaction, enabled, val, source);
    }
    void set_enabled_and_value(CdlTransaction transaction, bool enabled, cdl_int data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_enabled_and_value(transaction, enabled, val, source);
    }
    void set_enabled_and_value(CdlTransaction transaction, bool enabled, double data, CdlValueSource source)
    {
        CdlSimpleValue val(data);
        set_enabled_and_value(transaction, enabled, val, source);
    }
    void enable_and_set_value(CdlTransaction transaction, CdlSimpleValue& val, CdlValueSource source)
    {
        set_enabled_and_value(transaction, true, val, source);
    }
    void enable_and_set_value(CdlTransaction transaction, std::string data, CdlValueSource source)
    {
        set_enabled_and_value(transaction, true, data, source);
    }
    void enable_and_set_value(CdlTransaction transaction, cdl_int data, CdlValueSource source)
    {
        set_enabled_and_value(transaction, true, data, source);
    }
    void enable_and_set_value(CdlTransaction transaction, double data, CdlValueSource source)
    {
        set_enabled_and_value(transaction, true, data, source);
    }
    void disable_and_set_value(CdlTransaction transaction, CdlSimpleValue& val, CdlValueSource source)
    {
        set_enabled_and_value(transaction, false, val, source);
    }
    void disable_and_set_value(CdlTransaction transaction, std::string data, CdlValueSource source)
    {
        set_enabled_and_value(transaction, false, data, source);
    }
    void disable_and_set_value(CdlTransaction transaction, cdl_int data, CdlValueSource source)
    {
        set_enabled_and_value(transaction, false, data, source);
    }
    void disable_and_set_value(CdlTransaction transaction, double data, CdlValueSource source)
    {
        set_enabled_and_value(transaction, false, data, source);
    }

    // -----------------------------------------------------------------
    virtual bool   is_modifiable() const;
    void           get_widget_hint(CdlWidgetHint&);

    // -----------------------------------------------------------------
    // Propagation support. If a valuable becomes active or inactive
    // because e.g. its parent is disabled then this may affect
    // requires conflicts etc.
    virtual void update(CdlTransaction, CdlUpdate);
    
    virtual bool test_active(CdlTransaction);
    
    // -----------------------------------------------------------------
    // Property-related stuff.
    bool                                has_calculated_expression() const;
    bool                                has_default_value_expression() const;
    bool                                has_legal_values() const;
    bool                                has_entry_proc() const;
    bool                                has_check_proc() const;
    bool                                has_active_if_conditions() const;
    bool                                has_requires_goals() const;
    bool                                has_dialog() const;
    bool                                has_wizard() const;
    
    CdlProperty_Expression              get_calculated_expression() const;
    CdlProperty_Expression              get_default_value_expression() const;
    CdlProperty_ListExpression          get_legal_values() const;
    cdl_tcl_code                        get_entry_proc() const;
    cdl_tcl_code                        get_check_proc() const;
    void                                get_active_if_conditions(std::vector<CdlProperty_GoalExpression>&) const;
    void                                get_requires_goals(std::vector<CdlProperty_GoalExpression>&) const;
    CdlDialog                           get_dialog() const;
    CdlWizard                           get_wizard() const;
    void                                get_implemented_interfaces(std::vector<CdlInterface>&) const;
    
    // Add property parsers and validation code appropriate for a
    // valuable object such as default_value and legal_values
    static void         add_property_parsers(std::vector<CdlInterpreterCommandEntry>& parsers);
    void                check_properties(CdlInterpreter);
    static int          parse_active_if(CdlInterpreter, int, const char*[]);
    static void         active_if_update_handler(CdlTransaction, CdlNode, CdlProperty, CdlNode, CdlUpdate);
    static int          parse_calculated(CdlInterpreter, int, const char*[]);
    static void         calculated_update_handler(CdlTransaction, CdlNode, CdlProperty, CdlNode, CdlUpdate);
    static int          parse_check_proc(CdlInterpreter, int, const char*[]);
    static int          parse_default_value(CdlInterpreter, int, const char*[]);
    static void         default_value_update_handler(CdlTransaction, CdlNode, CdlProperty, CdlNode, CdlUpdate);
    static int          parse_dialog(CdlInterpreter, int, const char*[]);
    static void         dialog_update_handler(CdlTransaction, CdlNode, CdlProperty, CdlNode, CdlUpdate);
    static int          parse_entry_proc(CdlInterpreter, int, const char*[]);
    static int          parse_flavor(CdlInterpreter, int, const char*[]);
    static int          parse_group(CdlInterpreter, int, const char*[]);
    static int          parse_implements(CdlInterpreter, int, const char*[]);
    static void         implements_update_handler(CdlTransaction, CdlNode, CdlProperty, CdlNode, CdlUpdate);
    static int          parse_legal_values(CdlInterpreter, int, const char*[]);
    static void         legal_values_update_handler(CdlTransaction, CdlNode, CdlProperty, CdlNode, CdlUpdate);
    static int          parse_requires(CdlInterpreter, int, const char*[]);
    static void         requires_update_handler(CdlTransaction, CdlNode, CdlProperty, CdlNode, CdlUpdate);
    static int          parse_wizard(CdlInterpreter, int, const char*[]);
    static void         wizard_update_handler(CdlTransaction, CdlNode, CdlProperty, CdlNode, CdlUpdate);

    // Persistence suppot
    void save_valuable(CdlInterpreter, Tcl_Channel, int, bool /* modifiable */, bool /* minimal */);
    bool value_savefile_entry_needed() const;
    static void initialize_savefile_support(CdlToplevel, std::string);
    static int  savefile_value_source_command(CdlInterpreter, int, const char*[]);
    static int  savefile_user_value_command(CdlInterpreter, int, const char*[]);
    static int  savefile_wizard_value_command(CdlInterpreter, int, const char*[]);
    static int  savefile_inferred_value_command(CdlInterpreter, int, const char*[]);
    static int  savefile_xxx_value_command(CdlInterpreter, int, const char*[], CdlValueSource);
    
    // Make sure that the current value is legal. This gets called automatically
    // by all the members that modify values. It has to be a virtual function
    // since some derived classes, e.g. hardware-related valuables, may impose
    // constraints over and above legal_values etc.
    virtual void check_value(CdlTransaction);

    // Similarly check the requires properties
    void check_requires(CdlTransaction, CdlProperty_GoalExpression);
    void check_requires(CdlTransaction);

    // Enabling or disabling a valuable may affect the active state of children
    void check_children_active(CdlTransaction);

    virtual std::string get_class_name() const;
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  protected:
    CdlValuableBody(CdlValueFlavor = CdlValueFlavor_Bool);

    
  private:

    
    enum {
        CdlValuableBody_Invalid = 0,
        CdlValuableBody_Magic   = 0x2b2acc03
    } cdlvaluablebody_cookie;

    // Illegal operations
    CdlValuableBody(const CdlValuableBody&);
    CdlValuableBody& operator=(const CdlValuableBody&);
};

//}}}
//{{{  CdlTransaction etc.                              

//{{{  Description                      

// ----------------------------------------------------------------------------
// Transactions. These are used for all changes to a configuration. In some
// cases a transaction is implicit:
//
//    valuable->set_value(...)
//
// The actual implementation of this is:
//
//    valuable->set_value(...)
//        transact = CdlTransactionBody::make(valuable->get_toplevel())
//        valuable->set_value(transact, ...)
//        <complicated bits>
//        transact->commit()
//        delete transact
//
// Alternatively the use of transactions may be explicit. For implicit
// uses the library will invoke an inference callback at the
// appropriate time. For explicit transactions this is not necessary.
//
// The commit() operation invokes a transaction callback which should
// not be confused with the inference callback. The former is intended
// for display updates, it specifies everything that has changed
// during the transaction. The latter is used for reporting new
// conflicts to the user, suggesting fixes, etc.
//
// A whole bunch of information is associated with a transaction,
// including: all value changes, details of new conflicts, and details
// of existing conflicts that have gone away. The commit operation
// takes care of updating the toplevel. Until the commit happens
// the toplevel itself remains unchanged. It is also possible to cancel
// a transaction.
//
// An important concept related to transactions is propagation.
// Changing a value may have various effects, for example it may
// change the result of a legal_values list expression, resulting in a
// conflict object having to be created or destroyed. Changing one
// value may result in other value changes, e.g. because of a
// default_value property. All this is "propagation", and may
// happen multiple times within a single transaction.
//
// Transaction objects are also used during load or unload operations,
// but those are a little bit special. In particular it is not possible
// to cancel such a transaction, there will have been updates to the
// toplevel. Using a transaction is convenient because there is a 
// need for propagation.
//
// Currently a transaction should be deleted immediately after a
// commit or cancel. This may change in future, in that transaction
// objects can be used to hold undo information.
//
//
// The other big concept related to transactions is inference.
// Changing a value may result in one or more new conflicts being
// created. In some cases the library can figure out for itself how to
// resolve these conflicts, using an inference engine. There are
// parameters to control the operation of the inference engine,
// including whether it runs at all, what changes it is allowed
// to make automatically (usually default and inferred values can
// be updated, but not wizard or user values), and how much
// recursion will happen.
//
// Assuming a default setup in a GUI environment, a typical
// sequence of events would be:
//
//     valuable->set_value(...)
//         transact = CdlTransactionBody::make(valuable->get_toplevel())
//         valuable->set_value(transact, ...)
//             transact->set_whole_value(valuable, ...)
//         transact->propagate()
//         while (!finished)
//             transact->resolve()
//                 <inference>
//             invoke inference callback
//                 transact->apply_solution() (1 or more times)
//                     transact->set_whole_value(valuable, ...) (1 or more times)
//             transact->propagate()
//         transact->commit() | transact->cancel()
//         delete transact
//
// Note that the propagation steps have to be invoked explicitly,
// allowing multiple changes to be processed in one go. There is
// a utility function which combines the functionality from
// the first propagate() call up to but not including the
// transaction delete operator. 
//
//
// The inference engine itself is a complicated beast. There are
// a number of interfaces, but at the end of the day it ends up
// creating a sub-transaction and trying to resolve a single
// conflict in that sub-transaction. The conflict may belong to
// the current transaction or it may be global.
//
//     <inference>
//         for each conflict of interest
//             make sure that there is not already a valid solution
//             check that the inference engine can handle it
//             create a sub-transaction, associated with the conflict
//             apply the conflict resolution code
//             if the solution is ok
//                 install it
//             else if the solution might e.g. overwrite a user value
//                 keep it, the user can decide during the inference callback
//
// The conflict resolution typically works by attempting to change
// one or more values in the sub-transaction, propagating them,
// and seeing what new conflicts get created. If no new conflicts
// get created and one or more existing conflicts go away, groovy.
// Otherwise recursion can be used to try to resolve the new
// conflicts, or other strategies can be explored.
//
// NOTE: what is really necessary is some way of keeping track of the
// "best" solution to date, and allow exploration of alternatives.
// Or possibly keep track of all solutions. That has to be left to
// a future version.

//}}}
//{{{  CdlTransactionCommitCancelOp     

// ----------------------------------------------------------------------------
// The CdlTransaction class has built-in knowledge of how to handle values,
// active state, and a few things like that. However there are also more
// complicated operations such as loading and unloading, instantiating
// items, etc. which also need to happen in the context of a transaction
// but which the transaction class does not necessarily know about
// itself - or at least, not in any detail. Since the libcdl core is
// intended to be useful in various contexts, some sort of extensibility
// is essential.
//
// This is achieved by an auxiliary class, CdlTransactionCommitCancelOp.
// Clients of the transaction class can have their own utility class
// which derives from this, and create suitable objects. The transaction
// class maintains a vector of the pending commit/cancel operations.
//
// Each CdlTransactionCommitCancelOp object has two member functions,
// one for when the transaction gets committed and one for when it
// gets cancelled. If a sub-transaction gets committed then its
// pending ops are transferred across to the parent, allowing the
// parent to be cancelled sensibly: the commit ops only get run for
// the toplevel transaction. If a sub-transaction gets cancelled then
// the pending ops are invoked immediately.
//
// There is an assumption that commit/cancel ops get executed strictly
// in FIFO order. Specifically, commit ops get run from first one to
// the last one, allowing later operations in the transaction to
// overwrite earlier ones. Cancel ops get run in reverse order.

class CdlTransactionCommitCancelOp {
    friend class CdlTest;

  public:

    CdlTransactionCommitCancelOp() { }
    virtual ~CdlTransactionCommitCancelOp() { };

    // The default implementations of both of these do nothing.
    // Derived classes should override at least one of these
    // functions.
    virtual void commit(CdlTransaction transaction) {
        CYG_UNUSED_PARAM(CdlTransaction, transaction);
    }
    virtual void cancel(CdlTransaction transaction) {
        CYG_UNUSED_PARAM(CdlTransaction, transaction);
    }
    
  protected:

  private:
};

//}}}
//{{{  CdlTransaction class             

class CdlTransactionBody {

    friend class CdlTest;

    friend class CdlConflictBody;
    friend class CdlValuableBody;
    
  public:

    // Create a toplevel transaction
    static CdlTransaction make(CdlToplevel);
    virtual ~CdlTransactionBody();
    CdlToplevel get_toplevel() const;
    
    // Or a sub-transaction. Usually these are created in the context of
    // a conflict that is being resolved.
    CdlTransaction make(CdlConflict = 0);
    CdlTransaction get_parent() const;
    CdlConflict    get_conflict() const;
    
    // Commit all the changes. Essentially this means transferring
    // all of the per-transaction data to the toplevel, and then
    // invoking the transaction callback. All propagation, inference,
    // etc. should happen before the commit()
    // This routine can also be used to transfer changes from a
    // sub-transaction to the parent.
    void        commit();

    // A variant of the commit() operation can be used to
    // store a sub-transaction in a conflict's solution vector,
    // rather than updating the parent transaction. This is useful
    // for inferred solutions which cannot be applied without
    // user confirmation
    void        save_solution();

    // Can a solution held in a sub-transaction be applied without
    // e.g. overwriting a user value with an inferred value?
    bool        user_confirmation_required() const;

    // If the user has explicitly changed a value in the current transaction
    // then the inference engine should not undo this or suggest a solution
    // that will undo the change.
    bool        changed_by_user(CdlValuable) const;

    // A variant which is used for checking the hierarchy when disabling
    // a container
    bool        subnode_changed_by_user(CdlContainer) const;
    
    // Is one transaction preferable to another?
    bool        is_preferable_to(CdlTransaction) const;
    
    // Find out about per-transaction conflicts. This is particularly
    // useful for the inference callback. The other containers can
    // be accessed as well, for completeness.
    const std::list<CdlConflict>&       get_new_conflicts() const;
    const std::list<CdlConflict>&       get_new_structural_conflicts() const;
    const std::vector<CdlConflict>&     get_deleted_conflicts() const;
    const std::vector<CdlConflict>&     get_deleted_structural_conflicts() const;
    const std::vector<CdlConflict>&     get_resolved_conflicts() const ;
    const std::list<CdlConflict>&       get_global_conflicts_with_solutions() const;
    const std::map<CdlValuable, CdlValue>& get_changes() const;
    const std::set<CdlNode>&            get_activated() const;
    const std::set<CdlNode>&            get_deactivated() const;
    const std::set<CdlValuable>&        get_legal_values_changes() const;
    
    // Manipulate the current set of conflicts, allowing for nested
    // transactions and toplevel conflicts as well.
    void        clear_conflict(CdlConflict);
    bool        has_conflict_been_cleared(CdlConflict);
    
    bool        has_conflict(CdlNode, bool (*)(CdlConflict));
    CdlConflict get_conflict(CdlNode, bool (*)(CdlConflict));
    void        get_conflicts(CdlNode, bool (*)(CdlConflict), std::vector<CdlConflict>&);
    void        clear_conflicts(CdlNode, bool (*)(CdlConflict));
    bool        has_conflict(CdlNode, CdlProperty, bool (*)(CdlConflict));
    CdlConflict get_conflict(CdlNode, CdlProperty, bool (*)(CdlConflict));
    void        get_conflicts(CdlNode, CdlProperty, bool (*)(CdlConflict), std::vector<CdlConflict>&);
    void        clear_conflicts(CdlNode, CdlProperty, bool (*)(CdlConflict));

    bool        has_structural_conflict(CdlNode, bool (*)(CdlConflict));
    CdlConflict get_structural_conflict(CdlNode, bool (*)(CdlConflict));
    void        get_structural_conflicts(CdlNode, bool (*)(CdlConflict), std::vector<CdlConflict>&);
    void        clear_structural_conflicts(CdlNode, bool (*)(CdlConflict));
    bool        has_structural_conflict(CdlNode, CdlProperty, bool (*)(CdlConflict));
    CdlConflict get_structural_conflict(CdlNode, CdlProperty, bool (*)(CdlConflict));
    void        get_structural_conflicts(CdlNode, CdlProperty, bool (*)(CdlConflict), std::vector<CdlConflict>&);
    void        clear_structural_conflicts(CdlNode, CdlProperty, bool (*)(CdlConflict));

    // During the inference callback the user may decide to
    // apply one or more of the solutions.
    void        apply_solution(CdlConflict);
    void        apply_solutions(const std::vector<CdlConflict>&);
    void        apply_all_solutions();
    
    // Cancel all the changes done in this transaction. Essentially
    // this just involves clearing out all the STL containers.
    void        cancel();

    // Support for commit/cancel ops. These are used for
    // e.g. load and unload operations.
    void        add_commit_cancel_op(CdlTransactionCommitCancelOp *);
    void        cancel_last_commit_cancel_op();
    CdlTransactionCommitCancelOp* get_last_commit_cancel_op() const;
    const std::vector<CdlTransactionCommitCancelOp*>& get_commit_cancel_ops() const;
    
    // Propagation support
    void        add_active_change(CdlNode);
    void        add_legal_values_change(CdlValuable);
    void        propagate();
    bool        is_propagation_required() const;
    
    // Inference engine support.
    void        resolve(int = 0); // Process the new conflicts raised by this transaction
    void        resolve(CdlConflict, int = 0);
    void        resolve(const std::vector<CdlConflict>&, int = 0);
    
    // An auxiliary function called by the inference engine to perform recursion
    bool        resolve_recursion(int);
    
    // This function combines propagation, inference, and commit
    // in one easy-to-use package
    void        body();
    
    // Changes.
    // There is a call to get hold of a CdlValue reference. Modifications
    // should happen via a sequence of the form:
    //
    //    valuable->set_value(transact, ...)
    //        const CdlValue& old_value = transact->get_whole_value(CdlValuable);
    //        CdlValue new_value = old_value;
    //        <modify new_value>
    //        transact->set_whole_value(CdlValuable, old_value, new_value);
    //
    // When appropriate the get_whole_value() call takes care of
    // updating the current conflict's solution_references vector. The
    // set_whole_value() call updated the per-transaction changes map,
    // and also stores sufficient information to support propagation.
    // set_whole_value() requires both the old and new values, so
    // that propagation can be optimized.
    const CdlValue&     get_whole_value(CdlConstValuable) const;
    void                set_whole_value(CdlValuable, const CdlValue&, const CdlValue&);

    // Control over active vs. inactive also needs to happen inside
    // transactions
    bool                is_active(CdlNode) const;
    void                set_active(CdlNode, bool);
    
    // Callback and parameter settings
    static void (*get_callback_fn())(const CdlTransactionCallback&);
    static void                 set_callback_fn(void (*)(const CdlTransactionCallback&));
    static void                 set_inference_callback_fn(CdlInferenceCallback);
    static CdlInferenceCallback get_inference_callback_fn();
    static void                 enable_automatic_inference();
    static void                 disable_automatic_inference();
    static bool                 is_automatic_inference_enabled();
    static void                 set_inference_recursion_limit(int);
    static int                  get_inference_recursion_limit();
    // The override indicates the highest level of value source that the
    // library can overwrite without needing user confirmation. The
    // default value is CdlValueSource_Inferred, indicating that the
    // library can overwrite default and inferred values but not
    // wizard or user values.
    static void                 set_inference_override(CdlValueSource);
    static CdlValueSource       get_inference_override();
    
    bool        check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  protected:

  private:

    CdlTransactionBody(CdlToplevel, CdlTransaction, CdlConflict);

    // The associated toplevel and optionally the parent transaction
    // and the conflict being worked on
    CdlToplevel         toplevel;
    CdlTransaction      parent;
    CdlConflict         conflict;
    
    // Per-transaction information. All value changes, new conflicts
    // etc. first live in the context of a transaction. The global
    // configuration only gets updated if the transaction is commited.
    // There is also a vector of the pending commit/cancel ops.
    std::vector<CdlTransactionCommitCancelOp*> commit_cancel_ops;
    std::map<CdlValuable, CdlValue> changes;
    std::list<CdlConflict>          new_conflicts;
    std::list<CdlConflict>          new_structural_conflicts;
    std::vector<CdlConflict>        deleted_conflicts;  // Existing global ones
    std::vector<CdlConflict>        deleted_structural_conflicts;
    std::vector<CdlConflict>        resolved_conflicts; // New ones already fixed by the inference engine
    std::list<CdlConflict>          global_conflicts_with_solutions;
    std::set<CdlNode>               activated;
    std::set<CdlNode>               deactivated;
    std::set<CdlValuable>           legal_values_changes;
    bool                            dirty;
    
    // Change propagation. It is necessary to keep track of all
    // pending value changes, active changes, and of things being
    // loaded or unloaded. The set_value() call is used to update the
    // value_changes container.
    std::deque<CdlValuable>     value_changes;
    std::deque<CdlNode>         active_changes;


    // Control over the inference engine etc.
    static CdlInferenceCallback inference_callback;
    static bool                 inference_enabled;
    static int                  inference_recursion_limit;
    static CdlValueSource       inference_override;
    static void (*callback_fn)(const CdlTransactionCallback&);
    
    enum {
        CdlTransactionBody_Invalid = 0,
        CdlTransactionBody_Magic   = 0x3f91e4df
    } cdltransactionbody_cookie;

    // Illegal operations
    CdlTransactionBody();
    CdlTransactionBody(const CdlTransactionBody &);
    CdlTransactionBody& operator=(const CdlTransactionBody&);
};

//}}}
//{{{  CdlTransactionCallback           

// ----------------------------------------------------------------------------
// The callback class is used to inform applications about all the
// changes that are happening, including side effects. Application
// code can install a callback function which gets invoked at the
// end of every transaction.
//
// NOTE: this implementation is preliminary. In particular it is
// not extensible, it only deals with changes relevant to software
// configurations.

class CdlTransactionCallback {
    
    friend class CdlTest;
    friend class CdlTransactionBody;
    
  public:
    ~CdlTransactionCallback();
    static void (*get_callback_fn())(const CdlTransactionCallback&);
    static void set_callback_fn(void (*)(const CdlTransactionCallback&));

    // Callback functions should be able to retrieve information
    // about the current transaction and toplevel, to avoid the use
    // of statics.
    CdlTransaction              get_transaction() const;
    CdlToplevel                 get_toplevel() const;
    
    // active_changes and legal_values_changes get updated as the
    // transaction proceeds, so a set implementation is more
    // efficient. The others get filled in during a commit operation.
    // A transaction may result in multiple conflicts for a given node
    // being eliminated, so again a set is appropriate. For the others
    // there is no possibility of duplicates so a vector is better.
    std::vector<CdlValuable>    value_changes;
    std::vector<CdlNode>        active_changes;
    std::vector<CdlValuable>    legal_values_changes;
    std::vector<CdlValuable>    value_source_changes;
    std::vector<CdlConflict>    new_conflicts;
    std::vector<CdlConflict>    new_structural_conflicts;
    std::vector<CdlNode>        nodes_with_resolved_conflicts;
    std::vector<CdlNode>        nodes_with_resolved_structural_conflicts;
    
    bool check_this(cyg_assert_class_zeal = cyg_quick) const;
    
  protected:

  private:
    CdlTransactionCallback(CdlTransaction);
    CdlTransaction      transact;

    // Illegal operation.
    CdlTransactionCallback();
    
    enum {
        CdlTransactionCallback_Invalid     = 0,
        CdlTransactionCallback_Magic       = 0x0cec3a95
    } cdltransactioncallback_cookie;
};

//}}}
//{{{  CdlLocalTransaction              

// ----------------------------------------------------------------------------
// A utility class to create a per-function transaction object which gets
// cleaned up automatically should an exception happen.

class CdlLocalTransaction {
    
    friend class CdlTrest;
    
  public:
    CdlLocalTransaction(CdlToplevel toplevel) {
        transaction = CdlTransactionBody::make(toplevel);
    }
    ~CdlLocalTransaction() {
        // The destructor may get invoked during exception handling.
        // It is assumed that cancelling the transaction would be a
        // good thing when that happens. Normal operation should
        // go through the body() or commit() members, which clear
        // the transaction field.
        // There is a slight consistency here. Normally after a
        // transaction commit the transaction object is still
        // around. Here the transaction object get deleted. This
        // is unlikely to matter in practice.
        if (0 != transaction) {
            transaction->cancel();
            delete transaction;
        }
    }
    CdlTransaction get() {
        return transaction;
    }
    void body() {
        transaction->body();
        delete transaction;
        transaction = 0;
    }
    void commit() {
        transaction->commit();
        delete transaction;
        transaction = 0;
    }
    void propagate() {
        transaction->propagate();
    }
    void destroy() {
        if (0 != transaction) {
            transaction->cancel();
            delete transaction;
            transaction = 0;
        }
    }

  private:
    CdlTransaction transaction;
    CdlLocalTransaction();
};

//}}}

//}}}
//{{{  Build and define information                     

//{{{  Description                      

// ----------------------------------------------------------------------------
// There are two related concepts: buildable components, and
// definable components. The former typically refers to compiling
// sources files to produce libraries, although other types of build
// are possible. The latter refers to generating header files
// containing the current configuration data. Typically any loadable
// that is buildable is also definable, so that the source files can
// #include the appropriate generated headers and adapt to the
// configuration data that way. The inverse is not true: for example
// in HCDL it may be appropriate to generate a header file but there
// is nothing to be compiled, device drivers are software packages.
//
// The relevant base classes are as follows:
//
// 1) CdlBuildable      - this object can have build-related properties.
//                        All buildables are also valuables.
// 2) CdlBuildLoadable  - this is a base class for loadables, providing
//                        some extra properties that are relevant for
//                        loadables that can involve builds.
// 3) CdlDefinable      - this object can result in #define's in a
//                        header file. All exportables are also
//                        valuables.
// 4) CdlDefineLoadable - this is a base class for any loadables that
//                        can contain buildables.
//
// Support for both buildable and exportable components is part of the
// core library for now. This may change in future, depending on how
// many CDL variants get implemented.
//
// There are various properties related to building. First, the
// ones applicable to the CdlBuildLoadable class.
//
// 1) library xyz.
//    This specifies the default library for anything built in this
//    loadable. If there is no library property then it defaults to
//    libtarget.a (or rather to a class static that happens to be
//    initialized to libtarget.a)
//
// 2) include_dir <dir>.
//    This specifies where the loadable's exported header files should
//    end up. The default value is the toplevel, but e.g. the eCos
//    kernel specifies an include_dir of cyg/kernel. Note that fixed
//    header files are associated with buildables, not definables,
//    the latter deal with generated header files only.
//
// 3) include_files <hdr1 hdr2 ...>
//    The recommended directory hierarchy for non-trivial packages
//    involves separate subdirectories src, include, cdl, doc, and
//    test. This is too heavyweight for very simple packages where it
//    is better to keep everything in just one directory. However that
//    introduces a potential conflict between public and private
//    header files, which can be resolved by the include_files
//    property. The actual rules are:
//
//    a) if there an include_files property, that lists all the
//       headers that should be exported.
//
//    b) else if there is an include subdirectory, it is assumed that
//       all files below that should be exported.
//
//    c) otherwise all files matching a suitable glob pattern should
//       be exported. The default pattern is *.h *.hxx *.inl, but can
//       be overwritten.
//
// 4) makefile <file>
//    This allows component developers to provide a GNU makefile to be
//    used for building, rather than specify the relevant information
//    via properties.
//    NOTE: this property is ignored for now. It is roughly
//    equivalent to a custom build step where the command is
//    "make -C <dir> -f <file>", but in addition it is necessary to
//    worry about phony targets for default, clean, etc.
//
// A DefineLoadable adds the following property:
//
// 1) define_header <file>
//    This specifies the header file that will be generated. If this
//    property is absent then the library will generate a default one
//    based on the loadable's name, by discarding everything up to and
//    including the first underscore, lowercasing the rest, and
//    appending .h. For example, CYGPKG_KERNEL would result in a
//    header file kernel.h.
//
//    Hardware packages have an implicit "define_header hardware.h"
//    property.
//  
// A buildable has the following properties:
//
// 1) compile [-library xyz] <file1> <file2> ...
//    This specifies one or more files that need to be compiled.
//    By default the resulting object files will go into the
//    current library (set via a higher-level library or
//    defaulting to libtarget.a).
//
//    Legitimate filename suffixes for compile statements are .c, .cxx
//    and .S. Further suffixes may be supported in future. In the
//    long term we will need some external data files defining how
//    the various suffixes should be handled.
//
//    Associated with every compilation are details of the compiler to
//    be used and the compiler flags. For now no attempt is made
//    to do anything interesting in this area, although there is
//    sufficient information in the database for the needs of
//    command line tools.
//
//    Longer term there are complications. Packages may want some
//    control over the compiler flags that should be used, e.g.
//    "requires {!(flags ~= ".*-fno-rtti.*")}" to guarantee that the
//    compiler flags do not include -fno-rtti, rather useful if the
//    package's source code depends on that language feature. Mixed
//    architecture systems (e.g. ARM/Thumb) will cause problems when
//    it comes to selecting the compiler. The exact means by which
//    all this will work is not yet clear.
//
// 2) object [-library xyz] <file1> <file2> ...
//    This specifies one or more pre-built object files that should
//    go into the appropriate library.
//
//    The problem here is coping with different architectures, and for
//    many architectures it will also be necessary to worry about
//    multilibs. Third party component vendors are unlikely to supply
//    separate object files for every supported architecture and every
//    valid multilib within those architectures, so there are
//    constraints on the multilib-related compiler flags used for
//    building other packages and the application itself.
//
//    NOTE: this property is ignored for now.
//
// 3) make_object [-library xyz] [-priority pri] <file> <makefile fragment>
//
//    For example:
//
//    make_object toyslock.o {
//        toyslock.o : toyslock.y
//                yacc toyslock.y
//                $(CC) $(CFLAGS) -o toyslock.o y.tab.c
//    }
//
//    This defines a custom build step for an object file that
//    should go into a particular directory. A makefile syntax
//    is used to define the rule simply because it is likely
//    to be familiar to package developers, and does not
//    imply that the builds will happen via a makefile.
//
//    The optional priority field indicates at which stage during
//    the build the rule should trigger. The default value is
//    100, which is the same as for all files specified in
//    "compile" properties. A lower value means that the object
//    will be generated earlier. Libraries are generated at
//    priority 200, and "make" properties normally execute at
//    priority 300.
//    NOTE: it is not clear yet whether supporting priorities
//    in this way is a good idea, or whether the dependencies
//    information could be used instead.
//
//    Unresolved issues:
//
//    a) what commands can be used in the build rules? There
//       should be a core set of supported commands, as per
//       an eCos toolchain build. It should also be possible
//       for packages to provide their own host tools.
//
//       For sourceware folks, moving away from a single toolchain
//       tarball and expecting them to download and install
//       egcs, binutils and gdb separately is actually a bad
//       idea in this regard, it makes it much more likely that
//       some users will have an incomplete tools installation and
//       hence that builds will fail.
//
//    b) there is an obvious need for variable substitution in the
//       rules, e.g. $(CC). At what stage do these variables get
//       expanded, and where does the required information live?
//
//    c) who is responsible for header file dependency analysis?
//       Should the rules be modified automatically to do this,
//       or do we leave this to the package developer? It may be
//       very hard to do the former, but the latter will cause
//       problems for IDE integration.
//
//    d) in which directory will the rules get run? What prevents
//       filename conflicts between different packages?
//
//    NOTE: make_object is not actually required just yet, but the
//    issues are much the same as for the "make" property which is
//    required.
//
// 4) make [-priority pri] <target> <makefile fragment>
//
//    For example:
//
//    make target.ld {
//    target.ld : arm.ld
//            $(CC) -E -P -xc $(CFLAGS) -o $@ $<
//    }
//
//    This defines a custom build step for a target that is not going
//    to end up in a library. The main such targets at the moment are
//    the linker script, vectors.o, and extras.o, but there may well
//    be others in future.
//
//    The default priority for "make" properties is 300, which means
//    that the build rules trigger after all normal compilations and
//    after the libraries are generated. It is possible to specify
//    custom build steps that should run before any compilations
//    using a priority < 100.
//
//    Unresolved issues:
//
//    a) what commands can be used?
//
//    b) variable substitution?
//
//    c) header file dependency analysis?
//
//    d) directories and filenames?
//
//    e) where should the resulting files end up? Currently they can
//       all go into $(PREFIX)/lib, but in the long term we may
//       need to be a bit more flexible.
//
// 5) build_proc <tcl code>
//
//    This defines some Tcl code that should be run prior to any
//    build, for example to generate a source file. It must run
//    within the appropriate loadable's Tcl interpreter so that
//    it can query the current configuration.
//
//    NOTE: this property is not implemented yet.
//
//
// A definable has the following properties:
//
// 1) no_define
//    Usually the library will generate either one or two #define's
//    for every definable, inside the current header file. This can be
//    suppressed by the no_define property, which is typically
//    accompanied by some other #define-related property such as
//    define_proc or define.
//
// 2) define [-file <filename>] [-format <format_string>] symbol
//    This will result in an additional #define for the specified
//    symbol in the specified file. The only filenames that are valid
//    are the loadable's current filename (as per define_header), and
//    the global header file system.h. Use of the latter should be
//    avoided.
//
//    The optional format string behaves as per the define_format
//    property below.
//
// 3) define_format <format_string>
//    This is only relevant for booldata or data flavors. By default
//    two #define's will be generated (assuming the valuable is active
//    and enabled):
//
//        #define <symbol> value
//        #define <symbol>_value
//
//    The latter will only be generated if the resulting symbol is
//    a valid C preprocessor symbol, and is intended to allow the
//    use of #ifdef as well as #ifdef (useful if the value is
//    non-numerical). 
//
//    The define_format property provides control over the first of
//    these two #defines. The net result is that the #define will be
//    generated by evaluating the following Tcl fragment:
//
//        set result "#define <symbol> [<format> <value>]"
//
//    Command and variable substitution are available if desired,
//    but for anything that complicated the define_proc property
//    is normally more useful.
//
//    define_format is only applicable to the default definition,
//    so it cannot be used in conjunction with no_define. The
//    define property supports a -format option.
//
// 4) define_proc <tclcode>
//    This specifies some Tcl code that should be run when header
//    file generation takes place, in addition to any #define's
//    generated by default or courtesy of define properties.
//    The define_proc property is commonly used in conjunction with
//    no_define, but this is not required.
//
//    There will be two channels already set up: cdl_header
//    for the current loadable, and cdl_system_header for system.h.
//    Writing data to system.h should be avoided.
//
// 5) if_define <condition> <symbol>

//    This property provides direct support for a common programming
//    paradigm. It allows direct generation of code like the
//    following:
//
//    #ifdef CYGSRC_TOYS_BLOCKS
//    # define CYGDBG_INFRA_USE_PRECONDITIONS 1
//    #endif
//
//    In this case CYGSRC_TOYS_BLOCKS is the condition and
//    CYGDBG_INFRA_USE_PRECONDITIONS is the symbol. The
//    #ifdef/#define sequence will be generated in addition to
//    any other #define's resulting from the default behaviour,
//    the define property, or the define_proc property. It is
//    not affected by no_define.

//}}}
//{{{  The build process                

// ----------------------------------------------------------------------------
// For command-line operation the steps involved in doing a build are:
//
// 1) work out what needs to be built.
//
// 2) generate a build and install tree. This involves making sure that
//    the various directories exist and are accessible.
//
// 3) generate or update the toplevel makefile.
//
// 4) generate the configuration header files.
//
// For operation in an IDE steps (2) and (3) will be handled by
// different code.
//
// There is a library call to get hold of all the build information:
//
//     config->get_build_info(CdlBuildInfo &info);
//
// This erases anything previously present in the build-info argument
// and fills in the information appropriate to the current
// configuration, essentially by walking down the list of loadables
// and each loadable's list of nodes, checking for BuildLoadables
// and Buildables along the way. The BuildInfo class is defined
// further down.
//
// An alternative library call can be used to find out about all
// possible files that need to be compiled etc., irrespective of the
// current configuration settings. This could be useful when it
// comes to letting the user control compiler flags etc.
//
//    config->get_all_build_info(CdlBuildInfo& info);
//
// There is another library call for step (4):
//
//    config->generate_config_headers(std::string directory)
//
// This will create or update the header files appropriate to
// the current configuration. Temporary files will be generated,
// diff'ed with the current version, and existing files will
// only be modified if necessary. The directory argument
// indicates where the header files should go, i.e. it should
// be the equivalent of $(PREFIX)/include/pkgconf
//
// This library call does not delete any files it does not
// recognize, that is the responsibility of higher-level code.
// It is possible to get or update a list of the files that
// will be generated:
//
//    config->get_config_headers(std::vector<std::string>& headers)
//
// The argument will be cleared if necessary and then filled in with
// the current set of header files. Higher level code can compare the
// result with the current files in the directory and take or suggest
// remedial action.
//
// There is also a library call which combines all four stages:
//
//    config->generate_build_tree(std::string build_tree, std::string prefix = $(BUILD)/install)
//
//
// The order in which the various build steps happen is important.
//
// 1) non-configuration headers must be copied from the component
//    repository into $(PREFIX)/include. No compiles can happen
//    before this.
//
// 2) all compile properties can happen in parallel. These have an
//    effective priority of 100.
//
// 3) all make_object priorities can happen in parallel with
//    compiles. These have a default priority of 100, but the
//    priority can be modified.
//
// 4) the generated objects and any pre-built objects should be
//    incorporated into the appropriate library. This happens
//    at priority 200.
//
// 5) custom build steps associated with "make" properties should
//    now run. These have a default priority of 300, but it is
//    possible to override this.
//
// Usually all source files will come from the component repository,
// which means that they are read-only. Ideally it should also be
// possible for a source file to be copied into the build tree and
// edited there, and subsequent builds should pick up the copy rather
// than the original. The build data generated by libcdl will always
// be in the form of relative pathnames to facilitate this.

//}}}
//{{{  CdlBuildInfo class               

// ----------------------------------------------------------------------------
// Extracting the build information.
//
// libcdl.a defines the following classes related to build information.
//
// CdlBuildInfo
// CdlBuildInfo_Loadable
// CdlBuildInfo_Header
// CdlBuildInfo_Compile
// CdlBuildInfo_Object
// CdlBuildInfo_MakeObject
// CdlBuildInfo_Make
//
// The build information is organized on a per-loadable basis.
// Higher-level code may choose to flatten this or to keep the
// distinction. A CdlBuildInfo object is primarily a vector of
// CdlBuildInfo_Loadable objects. CdlBuildInfo objects can be created
// statically.
//
// In turn, each CdlBuildInfo_Loadable object is primarily a
// collection of five vectors, one each for Header, Compile, Object,
// MakeObject and Make.
//
// All pathnames in these data structures will use forward slashes as
// the directory separator, irrespective of the host platform. All
// pathnames will be relative.

struct CdlBuildInfo_Header {
    std::string         source;         /* include/cyg_ass.h    */
    std::string         destination;    /* cyg/infra/cyg_ass.h  */
};

struct CdlBuildInfo_Compile {
    std::string         library;        /* libtarget.a          */
    std::string         source;         /* src/fancy.cxx        */
    // Compiler and cflags data may be added in future.
};

struct CdlBuildInfo_Object {
    std::string         library;        /* libtarget.a          */
    std::string         object;         /* obj/hello.o          */
};

struct CdlBuildInfo_MakeObject {
    cdl_int             priority;       /* 100                  */
    std::string         library;        /* libtarget.a          */
    std::string         object;         /* toyslock.o           */
    std::string         deps;           /* toyslock.y           */
    /*
      It is not clear whether the deps field is actually useful in the
      context of IDE integration, but see the note about arm.inc
      above.
    */
    std::string         rules;
    /*
      A typical value for "rules" might be:

        yacc toyslock.y
        $(CC) $(CFLAGS) -o toyslock.o y.tab.c
        
      Leading white space is not significant. Newlines are significant.
      Backslash escapes in the text will not have been processed yet.
    */  
};

struct CdlBuildInfo_Make {
    cdl_int             priority;       /* 300                  */
    std::string         target;         /* extras.o             */
    std::string         deps;           /* libextras.a          */
    std::string         rules;
    /*
      Something like:
      
  $(CC) $(ARCHFLAGS) $(LDARCHFLAGS) -nostdlib -Wl,-r -Wl,--whole-archive $(PREFIX)/lib/libextras.a -o $(PREFIX)/lib/extras.o
  
    */
};

class CdlBuildInfo_Loadable {
    
    friend class CdlTest;

  public:
    std::string         name;           /* CYGPKG_INFRA         */
    std::string         repository;     /* arbitrary path       */
    std::string         directory;      /* infra/current        */
    std::vector<CdlBuildInfo_Header>            headers;
    std::vector<CdlBuildInfo_Compile>           compiles;
    std::vector<CdlBuildInfo_Object>            objects;
    std::vector<CdlBuildInfo_MakeObject>        make_objects;
    std::vector<CdlBuildInfo_Make>              makes;
    
  protected:

  private:
};

class CdlBuildInfo {

    friend class CdlTest;

  public:

    std::vector<CdlBuildInfo_Loadable>  entries;

  protected:

  private:
};

//}}}
//{{{  CdlBuildLoadable                 

// ----------------------------------------------------------------------------
// BuildLoadables are derived from Loadables and are appropriate for
// any loadables that can contain build information. There are a
// number of properties applicable at this level: makefile,
// include_dir, include_files and library. The main interface of
// interest is update_build_info().
//
// It is likely that all BuildLoadables are also Buildables, but this
// is not required.

class CdlBuildLoadableBody : virtual public CdlLoadableBody
{
    friend class CdlTest;

  public:
    virtual ~CdlBuildLoadableBody();

    // This is the main way to extract information about what should
    // get built. It takes into account the active and enabled states,
    // as appropriate.
    void        update_build_info(CdlBuildInfo&) const;

    // An alternative which ignores the active and enabled states.
    void        update_all_build_info(CdlBuildInfo&) const;
    
    // Property parsers and validation code appropriate for a
    // build-loadable object such as makefile
    static void add_property_parsers(std::vector<CdlInterpreterCommandEntry>& parsers);
    void        check_properties(CdlInterpreter);
    static int  parse_library(CdlInterpreter, int, const char*[]);
    static int  parse_makefile(CdlInterpreter, int, const char*[]);
    static int  parse_include_dir(CdlInterpreter, int, const char*[]);
    static int  parse_include_files(CdlInterpreter, int, const char*[]);
    
    // By default any compiled files will go into libtarget.a, which
    // is the default value for this variable. Individual applications may
    // specify an alternative default library.
    static const char*  default_library_name;

    // When filling in a build_info structure the library needs to know
    // what constitutes a header file. A glob pattern can be used for this.
    // NOTE: in the long term this should come out of a data file.
    static const char*  default_headers_glob_pattern;
    
    virtual std::string get_class_name() const;
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  protected:
    CdlBuildLoadableBody();

  private:

    enum {
        CdlBuildLoadableBody_Invalid    = 0,
        CdlBuildLoadableBody_Magic      = 0x55776643
    } cdlbuildloadablebody_cookie;

    // Illegal operations
    CdlBuildLoadableBody(const CdlBuildLoadableBody&);
    CdlBuildLoadableBody& operator=(const CdlBuildLoadableBody&);
};

//}}}
//{{{  CdlBuildable                     

// ----------------------------------------------------------------------------
// Buildable objects can have properties such as compile and
// make_object. These properties are not normally accessed
// directly. Instead there is a member function to update a
// CdlBuildInfo_Loadable object.
//
// The build properties for a given buildable have an effect iff
// that buildable is active, and in addition if the buildable is also
// a valuable then it must be enabled.

class CdlBuildableBody : virtual public CdlNodeBody
{

    friend class CdlTest;

  public:
    virtual ~CdlBuildableBody();

    // This is the main way to extract information about what should
    // get built. It takes into account the active and enabled states,
    // as appropriate. The second argument indicates the default
    // library for the current loadable.
    void        update_build_info(CdlBuildInfo_Loadable&, std::string) const;

    // An alternative which ignores the active and enabled states.
    void        update_all_build_info(CdlBuildInfo_Loadable&, std::string) const;
    
    // Add property parsers and validation code appropriate for a
    // buildable object such as compile and make_object
    static void add_property_parsers(std::vector<CdlInterpreterCommandEntry>& parsers);
    void        check_properties(CdlInterpreter);

    static int  parse_build_proc(CdlInterpreter, int, const char*[]);
    static int  parse_compile(CdlInterpreter, int, const char*[]);
    static int  parse_make(CdlInterpreter, int, const char*[]);
    static int  parse_make_object(CdlInterpreter, int, const char*[]);
    static int  parse_object(CdlInterpreter, int, const char*[]);
    static bool split_custom_build_step(std::string /* data */, std::string& /* target */, std::string& /* deps */,
                                        std::string& /* rules*/, std::string& /* error_msg */);

    virtual std::string get_class_name() const;
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  protected:
    CdlBuildableBody();

  private:

    enum {
        CdlBuildableBody_Invalid        = 0,
        CdlBuildableBody_Magic          = 0x16eb1c04
    } cdlbuildablebody_cookie;

    // Illegal operations
    CdlBuildableBody(const CdlBuildableBody&);
    CdlBuildableBody& operator=(const CdlBuildableBody&);
};

//}}}
//{{{  CdlDefineLoadable                

// ----------------------------------------------------------------------------
// DefineLoadables are derived from Loadables and are appropriate for
// any loadables that can result in generated header files containing
// configuration data. There is one applicable property,
// define_header. The main interface of interest is
// generate_config_headers().

class CdlDefineLoadableBody : virtual public CdlLoadableBody
{

    friend class CdlTest;

  public:
    virtual ~CdlDefineLoadableBody();

    // Update the header file for this loadable. The first argument
    // is a channel to the loadable-specific header file. The second
    // argument is a channel to the global header file.
    void        generate_config_header(Tcl_Channel, Tcl_Channel) const;

    // What header file should be generated for this loadable?
    virtual std::string get_config_header() const;
    
    // Add property parsers and validation code.
    static void         add_property_parsers(std::vector<CdlInterpreterCommandEntry>& parsers);
    void                check_properties(CdlInterpreter);
    static int          parse_define_header(CdlInterpreter, int, const char*[]);

    virtual std::string get_class_name() const;
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  protected:
    CdlDefineLoadableBody();

  private:

    enum {
        CdlDefineLoadableBody_Invalid   = 0,
        CdlDefineLoadableBody_Magic     = 0x7e211709
    } cdldefineloadablebody_cookie;

    // Illegal operations
    CdlDefineLoadableBody(const CdlDefineLoadableBody&);
    CdlDefineLoadableBody& operator=(const CdlDefineLoadableBody&);
};

//}}}
//{{{  CdlDefinable                     

// ----------------------------------------------------------------------------
// Definables are derived from Valuables and provide support for
// outputting a configuration header file.

class CdlDefinableBody : virtual public CdlValuableBody
{

    friend class CdlTest;

  public:
    virtual ~CdlDefinableBody();

    // Update the header file for this definable. The loadable's Tcl
    // interpreter will already have channels cdl_header and
    // cdl_system_header set up appropriately.
    void        generate_config_header( Tcl_Channel, Tcl_Channel) const;

    // Add property parsers and validation code.
    static void add_property_parsers(std::vector<CdlInterpreterCommandEntry>& parsers);
    void        check_properties(CdlInterpreter);
    static int  parse_define(CdlInterpreter, int, const char*[]);
    static int  parse_define_format(CdlInterpreter, int, const char*[]);
    static int  parse_define_proc(CdlInterpreter, int, const char*[]);
    static int  parse_if_define(CdlInterpreter, int, const char*[]);
    static int  parse_no_define(CdlInterpreter, int, const char*[]);

    virtual std::string get_class_name() const;
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();
    
  protected:
    CdlDefinableBody();

  private:

    enum {
        CdlDefinableBody_Invalid        = 0,
        CdlDefinableBody_Magic          = 0x65a2c95a
    } cdldefinablebody_cookie;

    // Illegal operations
    CdlDefinableBody(const CdlDefinableBody&);
    CdlDefinableBody& operator=(const CdlDefinableBody&);
};

//}}}

//}}}
//{{{  CdlDialog                                        

// ----------------------------------------------------------------------------
// A dialog simply inherits from CdlUserVisible and provides convenient
// access to several dialog-specific properties.

class CdlDialogBody :
    public virtual CdlUserVisibleBody,
    public virtual CdlParentableBody
{
    friend class CdlTest;

  public:

    virtual ~CdlDialogBody();

    // Dialogs may be enabled or disabled globally. This affects
    // CdlValuable::get_widget_hint() if the valuable has an associated
    // custom dialog.
    static void         disable_dialogs();
    static void         enable_dialogs();
    static bool         dialogs_are_enabled();

    bool                has_init_proc() const;
    bool                has_update_proc() const;
    const cdl_tcl_code& get_init_proc() const;
    const cdl_tcl_code& get_update_proc() const;
    const cdl_tcl_code& get_display_proc() const;
    const cdl_tcl_code& get_confirm_proc() const;
    const cdl_tcl_code& get_cancel_proc() const;
    
    static int          parse_dialog(CdlInterpreter, int, const char*[]);
    static int          parse_display_proc(CdlInterpreter, int, const char*[]);
    static int          parse_update_proc(CdlInterpreter, int, const char*[]);
    
    // Persistence support. Dialogs should just be ignored when it
    // comes to saving and restoring files.
    virtual void        save(CdlInterpreter, Tcl_Channel, int, bool);
                                                
    virtual std::string get_class_name() const;
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  private:
    // The constructor only gets invoked from inside parse_dialog()
    CdlDialogBody(std::string);

    static bool         dialogs_enabled;
    
    enum {
        CdlDialogBody_Invalid   = 0,
        CdlDialogBody_Magic     = 0x3f4df391
    } cdldialogbody_cookie;
    
    // Illegal operations. The dialog name must be known at the time
    // that the object is constructed.
    CdlDialogBody();
    CdlDialogBody(const CdlDialogBody&);
    CdlDialogBody& operator=(const CdlDialogBody&);
};

//}}}
//{{{  CdlWizard                                        

// ----------------------------------------------------------------------------
// A wizard is very much like a dialog, just a different set of properties.

class CdlWizardBody :
    public virtual CdlUserVisibleBody,
    public virtual CdlParentableBody
{
    friend class CdlTest;

  public:

    virtual ~CdlWizardBody();

    bool                has_init_proc() const;
    bool                has_decoration_proc() const;
    const cdl_tcl_code& get_init_proc() const;
    const cdl_tcl_code& get_decoration_proc() const;
    const cdl_tcl_code& get_confirm_proc() const;
    const cdl_tcl_code& get_cancel_proc() const;
    bool                has_screen(cdl_int) const;
    cdl_int             get_first_screen_number() const;
    const cdl_tcl_code& get_first_screen() const;
    const cdl_tcl_code& get_screen(cdl_int) const;
    static int          parse_wizard(CdlInterpreter, int, const char*[]);
    static int          parse_cancel_proc(CdlInterpreter, int, const char*[]);
    static int          parse_confirm_proc(CdlInterpreter, int, const char*[]);
    static int          parse_decoration_proc(CdlInterpreter, int, const char*[]);
    static int          parse_init_proc(CdlInterpreter, int, const char*[]);
    static int          parse_screen(CdlInterpreter, int, const char*[]);
    
    // Persistence support. Wizards should just be ignored when it
    // comes to saving and restoring files.
    virtual void        save(CdlInterpreter, Tcl_Channel, int, bool);
    
    virtual std::string get_class_name() const;
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  private:
    // The constructor only gets invoked from inside parse_wizard().
    CdlWizardBody(std::string);

    // Illegal operations.
    CdlWizardBody();
    CdlWizardBody(const CdlWizardBody&);
    CdlWizardBody& operator=(const CdlWizardBody&);
    
    enum {
        CdlWizardBody_Invalid   = 0,
        CdlWizardBody_Magic     = 0x4ec1c39a
    } cdlwizardbody_cookie;
};

//}}}
//{{{  CdlInterface class                               

// ----------------------------------------------------------------------------
// Similarly for interfaces.

class CdlInterfaceBody : public virtual CdlNodeBody,
                         public virtual CdlUserVisibleBody,
                         public virtual CdlValuableBody,
                         public virtual CdlParentableBody,
                         public virtual CdlBuildableBody,
                         public virtual CdlDefinableBody
{
    friend class CdlTest;

  public:

    ~CdlInterfaceBody();

    void                get_implementers(std::vector<CdlValuable>&) const;
    void                recalculate(CdlTransaction);
    
    static int          parse_interface(CdlInterpreter, int, const char*[]);
    
    // Persistence support. The interface data cannot sensibly be modified
    // by users, it is all calculated. However it is useful to have the
    // interface data present in the saved file so that users can examine
    // dependencies etc.
    virtual void        save(CdlInterpreter, Tcl_Channel, int, bool);
    static void         initialize_savefile_support(CdlToplevel);
    static int          savefile_interface_command(CdlInterpreter, int, const char*[]);

    bool                was_generated() const;
    virtual bool        is_modifiable() const;
    virtual std::string get_class_name() const;
    bool                check_this(cyg_assert_class_zeal = cyg_quick) const;
    CYGDBG_DECLARE_MEMLEAK_COUNTER();

  private:
    CdlInterfaceBody(std::string, bool /* generated */);
    bool        generated;
    
    enum {
        CdlInterfaceBody_Invalid   = 0,
        CdlInterfaceBody_Magic     = 0x67f7fbe5
    } cdlinterfacebody_cookie;
    CdlInterfaceBody();
    CdlInterfaceBody(const CdlInterfaceBody&);
    CdlInterfaceBody& operator=(const CdlInterfaceBody&);
};

//}}}

#endif  /* !__CDLCORE_HXX */
// EOF cdlcore.hxx