URL
https://opencores.org/ocsvn/openrisc/openrisc/trunk
Subversion Repositories openrisc
[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [tools/] [src/] [libcdl/] [cdlcore.hxx] - Rev 379
Go to most recent revision | Compare with Previous | Blame | View Log
#ifndef __CDLCORE_HXX
# define __CDLCORE_HXX
//{{{ Banner
//==========================================================================
//
// cdlcore.hxx
//
// The core parts of the library. This header defines aspects of
// CDL that are shared between software cdl, hcdl, scdl, and any
// future languages based on the same core technology.
//
//==========================================================================
//####COPYRIGHTBEGIN####
//
// ----------------------------------------------------------------------------
// Copyright (C) 2002 Bart Veer
// Copyright (C) 1999, 2000, 2001 Red Hat, Inc.
//
// This file is part of the eCos host tools.
//
// This program is free software; you can redistribute it and/or modify it
// under the terms of the GNU General Public License as published by the Free
// Software Foundation; either version 2 of the License, or (at your option)
// any later version.
//
// This program is distributed in the hope that it will be useful, but WITHOUT
// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
// FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
// more details.
//
// You should have received a copy of the GNU General Public License along with
// this program; if not, write to the Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
//
// ----------------------------------------------------------------------------
//
//####COPYRIGHTEND####
//==========================================================================
//#####DESCRIPTIONBEGIN####
//
// Author(s): bartv
// Contributors: bartv
// Date: 1999-04-15
//
//####DESCRIPTIONEND####
//==========================================================================
//}}}
//{{{ Platform dependencies
// ----------------------------------------------------------------------------
// Visual C++ has the delightful feature that the source browser will generate
// warnings if there are any identifiers of length >= 256 characters, while at
// the same time use of templates in the standard C++ library can easily
// generate functions that long. It appears that the only way to disable the
// warnings is by use of a %$#@(%*&%! #pragma.
//
// Similarly, VC++ gives spurious warnings when it comes to multiple virtual
// inheritance.
#ifdef _MSC_VER
# pragma warning( disable: 4786 )
# pragma warning( disable: 4250 )
#endif
//}}}
//{{{ nested #include's
// ----------------------------------------------------------------------------
// The libcdl API is defined using parts of the standard C++ library,
// including strings and various bits of STL. Therefore these headers must
// be #include'd here for the header file to work.
#include <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 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 */, 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,
char**, void (*)(CdlInterpreter, CdlProperty_Minimal));
static int parse_string_property(CdlInterpreter, int, const char*[], std::string,
char**, void (*)(CdlInterpreter, CdlProperty_String));
static int parse_tclcode_property(CdlInterpreter, int, const char*[], std::string,
char**, void (*)(CdlInterpreter, CdlProperty_TclCode));
static int parse_stringvector_property(CdlInterpreter, int, const char*[], std::string,
char**, void (*)(CdlInterpreter, CdlProperty_StringVector),
bool /* allow_empty */ = false);
static int parse_reference_property(CdlInterpreter, int, const char*[], std::string,
char**, void (*)(CdlInterpreter, CdlProperty_Reference),
bool /* allow_empty */,
CdlUpdateHandler);
static int parse_expression_property(CdlInterpreter, int, const char*[], std::string,
char **, void (*)(CdlInterpreter, CdlProperty_Expression),
CdlUpdateHandler);
static int parse_listexpression_property(CdlInterpreter, int, const char*[], std::string,
char **, void (*)(CdlInterpreter, CdlProperty_ListExpression),
CdlUpdateHandler);
static int parse_goalexpression_property(CdlInterpreter, int, const char*[], std::string,
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_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 /* directory */);
// Needed by derived classes, but not actually used.
CdlLoadableBody();
private:
std::vector<CdlNode> owned;
CdlInterpreter interp;
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 should also have an associated directory for
// the component repository. It is not required that all loadables
// are relative to this, but that is the default behaviour.
std::string get_directory() 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, std::string);
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::string directory;
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(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 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 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 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
Go to most recent revision | Compare with Previous | Blame | View Log