libFAUDES

Sections

Index

cfl_types.h

Go to the documentation of this file.
00001 /** @file cfl_types.h Runtime interface, faudes types */
00002 
00003 /* FAU Discrete Event Systems Library (libfaudes)
00004 
00005 Copyright (C) 2009 Ruediger Berndt
00006 Copyright (C) 2010 Thomas Moor
00007 
00008 This library is free software; you can redistribute it and/or
00009 modify it under the terms of the GNU Lesser General Public
00010 License as published by the Free Software Foundation; either
00011 version 2.1 of the License, or (at your option) any later version.
00012 
00013 This library is distributed in the hope that it will be useful,
00014 but WITHOUT ANY WARRANTY; without even the implied warranty of
00015 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00016 Lesser General Public License for more details.
00017 
00018 You should have received a copy of the GNU Lesser General Public
00019 License along with this library; if not, write to the Free Software
00020 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA */
00021 
00022 
00023 #ifndef FAUDES_RTITYPES_H
00024 #define FAUDES_RTITYPES_H
00025 
00026 #include <list>
00027 #include <string>
00028 #include <vector>
00029 #include <map>
00030 #include <utility>
00031 #include <string>
00032 #include <iostream>
00033 #include <typeinfo>
00034 #include <algorithm>
00035 
00036 #include "cfl_definitions.h"
00037 #include "cfl_token.h"
00038 #include "cfl_tokenreader.h"
00039 #include "cfl_tokenwriter.h"
00040 #include "cfl_exception.h"
00041 
00042 
00043 
00044 namespace faudes {
00045 
00046 
00047 /************************************************
00048  ************************************************
00049  ************************************************/
00050 
00051 
00052 /** @defgroup RunTimeInterface  Run-Time Interface
00053 
00054 The libFAUDES run-time interface (RTI) facilitates the development 
00055 of applications that are transparent to libFAUDES extensions, e.g.
00056 the libFAUDES version of the Lua interpreter luafaudes and the 
00057 graphical user interface  DESTool.
00058 
00059 The run-time interface  provides a TypeRegistry for the application 
00060 to instantiate objects by specifying their type as a std::string. 
00061 The TypeRegistry is accompanied by the FunctionRegistry for 
00062 the application to execute functions by their name. Thus, a libFAUDES
00063 application can query both registries and provide the 
00064 supported types and functions to the user. 
00065 The <a href="../registry/index.html">libFAUDES user-reference</a> 
00066 is set up by the build system to represent the contents of both
00067 registries.
00068 
00069 The run-time interface is implemented
00070 by the following components:
00071 - base class faudes::Type for RTI enabled classes (faudes-types)
00072 - documentation class faudes::TypeDefinition to accompany faudes-types;
00073 - container class faudes::TypeRegistry to hold faudes::TypeDefintiion objects;
00074 - base class faudes::Function for RTI enabled function wrappers (faudes-functions);
00075 - documentation class faudes::FunctionDefinition to accompany faudes-functions;
00076 - container class faudes::FunctionRegistry to hold FunctionDefintiion objects.
00077 
00078 @section RunTimeInterfaceSec2 Faudes-Types
00079 
00080 Classes that participate in the run-time interface are referred to
00081 as faudes-types, instances are so called faudes-objects. Any faudes-type must
00082 be derived from the base class faudes::Type. A faudes-type inherits
00083 the convenience interface for token IO from Type, and, most relevent for the run-time 
00084 interface, the factory function New(): each faudes-types must reimplement New() 
00085 to allocate a new object of their respective type on heap. For a fully functional
00086 faudes-type, also an appropriate assignment operator and a copy constructor
00087 are required.
00088 
00089 
00090 @section RunTimeInterfaceSec3 Faudes-Type Definitions
00091 
00092 A faudes-type is accompanied by an instance of faudes::TypeDefinition. It holds
00093 a name (std::string) to identify the faudes-type,
00094 documentation (short text and html reference), 
00095 and one faudes-object of the respective faudes-type.
00096 The latter is referred to as the prototype object and its New() method is used to construct 
00097 new faudes-objects of the respective faudes-type. Thus, given a TypeDefinition,
00098 one can instantiate a corresponding faudes-object. To setup a
00099 TypeDefinition, you are meant to provide the faudes-type name, the protototype
00100 and a file from which to read the documentation.
00101 
00102 
00103 @section RunTimeInterfaceSec4 Faudes-Functions and Faudes-Function Definitions
00104 
00105 Functions that participate in the run-time interface are organized similar
00106 to faudes-types. There is a base class faudes::Function from which to derive 
00107 particular faudes-functions. The base class provides an interface to set
00108 function parameter values and to actually  execute the function on the parameters. 
00109 To derive a class from Function, you must reimplement the methods New(), DoTypeCheck(), 
00110 and DoExecute(). The DoTypeCheck method is supposed to use a dynamic cast
00111 to initialize typed references to the function parameters. The DoExecute method
00112 then executes the function, typically by invoking a function via its
00113 C++ API. Each Function class is accompanied by a faudes::FunctionDefinition instance
00114 which holds a prototype, basic documentation and a list of valid signatures. Each signature
00115 represents a valid parameter type configurations in terms of faudes-types. 
00116 
00117 @section RunTimeInterfaceSec5 Type- and Function-Registry 
00118 
00119 The faudes::TypeRegistry and the faudes::FunctionRegistry are containers for TypeDefinition
00120 and FunctionDefinition instances, respectively. Applications access the registries via
00121 faudes-type names and faudes-function names, see e.g. the global functions NewObject() and
00122 NewFunction(). There is also in interface to iterate through the regsitries and
00123 to test for the existence of an entry. However, while both registries inherit the std token-io
00124 interface, neither registry can be fully configured by reading from file. This is because
00125 each entry requires not only data (documentation, signature, etc) but also a prototype
00126 instance. The std C++ run-time type information (RTTI) does not provide a mechanism
00127 to instantiate an object of a class that is specified at runtime. Thus, each protototype
00128 must be defined at compiletime. The global function LoadRegistry() is automatically
00129 set-up by the build system to gather all relevant prototypes, insert them in the 
00130 registries and to subsequently read further documentation from a configuration 
00131 file.
00132 
00133 @section RunTimeInterfaceSec6 RTI and the Build System
00134 
00135 At stage <tt>make configure</tt>, the build system sets up the function LoadRegistry()
00136 by  
00137 - setting the macro FAUDES_PLUGINS_RTILOAD to a list of function calls in order to invoke
00138   one load function per plugin;
00139 - running the tool <tt>rti2code</tt> to generate c code to register faudes-types and-functions 
00140   found in the configuration file ("libfaudes.rti").
00141 
00142 Code generation should work for all types and functions with documentation entry "CType()" specified. 
00143 Since there is only one CType() entry, all signatures of a function must be implemented by a single
00144 c-function. The generated code is placed at "./include/rtiautoload.*". The build system also provides 
00145 support to merge the configuration "libfaudes.rti" file from various sources, incl. plugins.
00146 
00147 To have your C++ class participate in the libFAUDES run-time interface:
00148 
00149 -# derive your class from faudes::Type;
00150 -# make sure your class has a public default constructor and a public copy constructor;
00151 -# use the provided macros to reimplement the virtual functions FType(), New(), Copy(), Cast(), 
00152    Assign(), Equal(), and the acording operators =, == and !=;
00153 -# reimplement the virtual functions DoAssign(), DoEqual(), DoRead(), DoWrite() and Clear();
00154 -# optionally, reimplement the alternative output formats DoDWrite(), DoSWrite(), DoXWrite()
00155 -# provide an .rti file for the formal TypeDefinition; 
00156 -# supplement your .rti file by an html formated documentation text;  
00157  
00158 You will need to inspect and edit the main Makefile or your plugin's Makefile
00159 to advertise your additional sources. A <tt>make configure</tt> will then
00160 assemble all the bits and pieces.
00161 
00162 To have your C++ function participate in the libFAUDES run-time interface:
00163 
00164 -# make sure all your parameters are faudes-types (exceptions being
00165    the elementary types bool, string and integer, which are converted automatically);
00166 -# provide an .rti file for the formal FunctionDefinition, advertise this file;
00167    either in the main Makefile or in the Makefile of your plugin;
00168 -# supplement yout .rti file by an html formated documentation text;  
00169 
00170 
00171 */
00172 
00173 // forward
00174 class TypeDefinition;
00175 
00176 /**
00177  * Base class of all libFAUDES objects that participate in
00178  * the run-time interface. Eg, generator, alphabet, attributes etc.
00179  * The class is designed to impose as little overhead as possible, and
00180  * hence, does not hold any data. It does, however, provide a
00181  * uniform interface for assignment, factory functions, and token IO.
00182  *
00183  * We think of a faudes-typed object to be configured by defining
00184  * data and, in due course, manipulated via its public interface 
00185  * by faudes-functions. Any faudes-type must provide a Clear() method that
00186  * resets the object configuration to a unique default value.
00187  * It is the configuration data that can be read from and written to token
00188  * streams, and it is the configuration data that is used for assigments.
00189  * Any additional data a faudes-typed object may host, is ignored by the
00190  * interface inherited from the the base faudes::Type. Examples for such
00191  * additional data is the unique id of a Generator, and the deferred copy
00192  * pointers in faudes sets derived from faudes::TBaseSet.
00193  *
00194  * The faudes::Type assignment semantics are not meant to create exact copies
00195  * of a given source object. Thogether with the uniquely defined default value,
00196  * we can have assignments by both up- and downcasts. A faudes::Generator can be
00197  * assigned from the derived faudes::System (a Generator with controllability 
00198  * attributes) by dropping the extra features. Vice versa, when a System is assigned
00199  * from a plain Generator, any extra features take their respective default values.
00200  * This relaxed interpretation of assignments is implemented by the method
00201  * Assign().  The token format for file IO is organised in a similar fashion: any generator 
00202  * derivate can be configured from the token stream produced by any other generator class. 
00203  * In contrast, faudes-typed objects also implement an assignment operator
00204  * that uses the standard C++ conventions.
00205  *
00206  * The follwoing methods are used to implement the faudes::Type interface:
00207  * 
00208  * - DoRead() to read the defining data from a token stream
00209  * - DoWrite() to write the defining data to a token stream
00210  * - DoXWrite() to write the defining data to a token stream in an alternative XML format
00211  * - DoSWrite() and DoDWrite for alternative output formats (statistical summary and debugging)
00212  *
00213  * - Name() to get/set the name of an optional (and purely cosmetic) object name
00214  * - Clear() to reset all configuration data,
00215  * - New() to construct an object of identical type on heap (factory method),
00216  * - Copy() to construct an object of identical type and configuration on heap (factory method),
00217  * - Cast() to dynamically cast another object to this type (type check method)
00218  * - Assign() to do an assignment from any castable Type derivate
00219  * - DoAssign(), or the operator "=", to assign from an object with identical type.
00220  * - Equal() to test relaxed equality with any castable Type derivate
00221  * - DoEqual(), or the operators "==" and "!=", to test exact equality of configuration data
00222  * 
00223  * In most cases, only DoRead(), DoWrite(), DoAssign() and DoEqual() need to me implemented
00224  * manualy. the other methods can be declared and implemented by macros
00225  * FAUDES_TYPE_DELARATION and FAUDES_TYPE_IMPLEMENTATION, respectively. The various
00226  * Attribute classes illustrate their ussage.
00227  *
00228  *
00229  * Note on token IO: In libFAUDES 2.16e, implementation of a new file format is prepared 
00230  * by the virtual function interface DoXWrite(). The intention is to better support advanced 
00231  * XML editors, in particular for configuration files. When implementing DoXWrite() for a 
00232  * derived class, make sure that DoRead() will gracefully accept tokens written by both DoWrite() 
00233  * and DoXWrite(), as a basis for a fileformat conversion tool. Future versions of libFAUDES will drop 
00234  * compatibility with the old token format, except for model data (generators, alphabets). 
00235  *
00236  * @ingroup RunTimeInterface
00237  */
00238    
00239 class Type {
00240 
00241  public:
00242 
00243   /** Constructor */
00244   Type(void);
00245 
00246   /** Copy constructor */
00247   Type(const Type& rType);
00248 
00249   /** Destructor */
00250   virtual ~Type(void);
00251 
00252   /**
00253    * Construct on heap. 
00254    * Technically not a constructor, this function creates an object with the
00255    * same type Type. New() is defined as a virtual function and derived
00256    * classes are meant to re-implement with the appropiate constructor.
00257    * This can be done via the provided macros FAUDES_TYPE_DECLARATION and
00258    * FAUDES_TYPE_IMPLEMENTATION.
00259    * As with new, it is the callers reponsabilty to delete the object when no longer needed.
00260    *
00261    * @return 
00262    *   Pointer to new Type object
00263    */
00264   virtual Type* New(void) const;
00265 
00266   /**
00267    * Construct on heap. 
00268    * Technically not a constructor, this function creates an object with the
00269    * same type Type and the same configuration. Copy() is defined as a virtual function and derived
00270    * classes are meant to re-implement with the appropiate copy constructor.
00271    * This can be done via the provided macros FAUDES_TYPE_DECLARATION and
00272    * FAUDES_TYPE_IMPLEMENTATION.
00273    * As with new, it is the callers reponsabilty to delete the object when no longer needed.
00274    *
00275    * @return 
00276    *   Pointer to new Type object
00277    */
00278   virtual Type* Copy(void) const;
00279 
00280   /**
00281    * Cast other object to this type.
00282    * Enables the run-time interface to test whether pObject is derived
00283    * from this object. This feature is used e.g. in the faudes container
00284    * classes to test attributes. Derived classes must reimplement this
00285    * function using the appropriate dynamic cast.
00286    *
00287    * Re-implementation can be done via the convenience macros
00288    * FAUDES_TYPE_DECLARATION and FAUDES_TYPE_IMPLEMENTATION.
00289    *
00290    * @return 
00291    *   Typed pointer object
00292    */
00293   virtual const Type* Cast(const Type* pOther) const;
00294 
00295   /**
00296    * Clear configuration data.  Derived classes should re-implement this
00297    * method to ensure some consistent configuration data.
00298    */
00299   virtual void Clear(void);
00300 
00301   /**
00302    * Assign configuration data from other object. 
00303    * Derived classes should reimplement this method to first try to cast
00304    * the source to the respective class. If successful, the protected 
00305    * function DoAssign is invoked to perform the actual assignment. If the cast fails,
00306    * the Assign method of the parent class is called. Thus, faudes
00307    * objects are up- and downcatsed for assignment, maintaining as much of
00308    * the source data as digestable by the destination object. On the downside,
00309    * there is no sensible typechecking at compile-time.
00310    *
00311    * Re-implementation can be done via the convenience macros
00312    * FAUDES_TYPE_DECLARATION and FAUDES_TYPE_IMPLEMENTATION.
00313    * 
00314    * @param rSrc 
00315    *    Source to copy from
00316    * @return Reference to this object.
00317    */
00318   virtual Type& Assign(const Type& rSrc);
00319 
00320 
00321   /**
00322    * Assign configurationdata from other object. 
00323    * Derived classes should implement the operator form for the assignment
00324    * for each source type which allows for a non-trivial assignment. This includes
00325    * the particular case were the source and destination types match exactly. In the
00326    * latter case the DoAssign method should be invoked. In contrast to
00327    * the Assign function, the operator form must not be reimplemented for
00328    * missmatched source types: the operator form only accepts sensible source types.
00329    * This allows for compiletime typeckecking. However, the downside is that
00330    * when the type is not known at compiletime, configuration is not properly
00331    * assigned.
00332    *
00333    * Re-implementation can be done via the convenience macros
00334    * FAUDES_TYPE_DECLARATION and FAUDES_TYPE_IMPLEMENTATION.
00335    * 
00336    * @param rSrc 
00337    *    Source to copy from
00338    * @return Reference to this object.
00339    */
00340   virtual Type& operator=(const Type& rSrc);
00341 
00342   /**
00343    * Test equality of configuration data.
00344    * Derived classes should reimplement this method to return true
00345    * if both actual types and configuration data match.
00346    * The object name or id  (if any) is not considered in the test.
00347    *
00348    * This method calls the virtual method DoEqual(). Re-implementation can 
00349    * be done via the convenience macros
00350    * FAUDES_TYPE_DECLARATION and FAUDES_TYPE_IMPLEMENTATION.
00351    * 
00352    * @param rOther 
00353    *    Other object to compare with.
00354    * @return 
00355    *   True on match.
00356    */
00357   virtual bool Equal(const Type& rOther) const;
00358 
00359   /**
00360    * Test equality of configuration data.
00361    * The operator form of the equality test is only defined for matching
00362    * types, no cast will be performed. Thus, the test will be optimistic
00363    * if the type is not known at compiletime.
00364    * The object name or id  is not considered in the test.
00365    *
00366    * This methoc calls the virtual method DoEqual(). Re-implementation can 
00367    * be done via the convenience macros
00368    * FAUDES_TYPE_DECLARATION and FAUDES_TYPE_IMPLEMENTATION.
00369    * 
00370    * @param rOther 
00371    *    Other object to compare with.
00372    * @return 
00373    *   True on match.
00374    */
00375   virtual bool operator==(const Type& rOther) const;
00376 
00377 
00378   /**
00379    * Test equality of configuration data.
00380    * See operator==(const Type&).
00381    *
00382    * This method calls the virtual method DoEqual(). Re-implementation can 
00383    * be done via the convenience macros
00384    * FAUDES_TYPE_DECLARATION and FAUDES_TYPE_IMPLEMENTATION.
00385    * 
00386    * @param rOther 
00387    *    Other objevt to compare with.
00388    * @return 
00389    *   True on mismatch.
00390    */
00391   virtual bool operator!=(const Type& rOther) const;
00392 
00393 
00394   /** 
00395    * Set the objects's name.
00396    *
00397    * The base class Type does not implement an object name,
00398    * derivatives usually do so, except for attributes. 
00399    *
00400    * @param rName
00401    *   Name
00402    */
00403   virtual void Name(const std::string& rName);
00404 
00405   /** 
00406    * Get objects's name.
00407    *
00408    * The base class Type does not implement an object name,
00409    * derivatives usually do so, except for attributes. 
00410    * @return 
00411    *   Name of generator
00412    */
00413   virtual const std::string& Name(void) const;
00414 
00415   /**
00416    * Write configuration data to console.
00417    * Note: this write function uses the virtual function DoWrite(), to be 
00418    * reimplemented by derived classes.
00419    *
00420    * @param pContext
00421    *   Write context to provide contextual information
00422    *
00423    */
00424   void Write(const Type* pContext=0) const;
00425 
00426   /**
00427    * Write configuration data to a file. 
00428    * Note: this write function uses the virtual function DoWrite(), to be 
00429    * reimplemented by derived classes.
00430    *
00431    * @param pFileName
00432    *   Name of file
00433    * @param rLabel
00434    *   Label of section to write
00435    * @param pContext
00436    *   Write context to provide contextual information
00437    * @param openmode
00438    *   ios::openmode 
00439    *
00440    * @exception Exception
00441    *   - IO errors (id 2)
00442    */
00443   void Write(const std::string& pFileName, const std::string& rLabel="",
00444        const Type* pContext=0, std::ios::openmode openmode = std::ios::out|std::ios::trunc) const;
00445 
00446   /**
00447    * Write configuration data to a file. 
00448    * Note: this write function uses the virtual function DoWrite(), to be 
00449    * reimplemented by derived classes.
00450    *
00451    * @param pFileName
00452    *   Name of file
00453    * @param openmode
00454    *   ios::openmode 
00455    *
00456    * @exception Exception
00457    *   - IO errors (id 2)
00458    */
00459   void Write(const std::string& pFileName, std::ios::openmode openmode) const;
00460 
00461   /**
00462    * Write configuration data to TokenWriter.
00463    * Note: this write function uses the virtual function DoWrite(), to be 
00464    * reimplemented by derived classes.
00465    *
00466    * @param rTw
00467    *   Reference to TokenWriter
00468    * @param rLabel
00469    *   Label of section to write
00470    * @param pContext
00471    *   Write context to provide contextual information
00472    *
00473    * @exception Exception 
00474    *   - IO errors (id 2)
00475    */
00476   void Write(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00477 
00478   /**
00479    * Write configuration data to an XML file. 
00480    * Note: this method uses the faudes type to set a DOCTYPE markup; for derived classes
00481    * which do not report their faudes type, you should reimplement this
00482    * function. Actual token io is done via DoXWrite().
00483    *
00484    * @param pFileName
00485    *   Name of file
00486    * @param rLabel
00487    *   Label of section to write
00488    * @param pContext
00489    *   Write context to provide contextual information
00490    *
00491    * @exception Exception
00492    *   - IO errors (id 2)
00493    */
00494   virtual void XWrite(const std::string& pFileName, const std::string& rLabel="",
00495        const Type* pContext=0) const;
00496 
00497   /**
00498    * Write configuration data in XML format to TokenWriter.
00499    * Note: this write function uses the virtual function DoXWrite(), to be 
00500    * reimplemented by derived classes. No DOCTYPE markup will be written.
00501    *
00502    * @param pContext
00503    *   Write context to provide contextual information
00504    *
00505    */
00506   void XWrite(const Type* pContext=0) const;
00507 
00508   /**
00509    * Write configuration data in XML format to TokenWriter.
00510    * Note: this write function uses the virtual function DoXWrite(), to be 
00511    * reimplemented by derived classes.
00512    *
00513    * @param rTw
00514    *   Reference to TokenWriter
00515    * @param rLabel
00516    *   Label of section to write
00517    * @param pContext
00518    *   Write context to provide contextual information
00519    *
00520    * @exception Exception 
00521    *   - IO errors (id 2)
00522    */
00523   void XWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00524 
00525   /**
00526    * Write configuration data to a string.
00527    * Note: this write function uses the virtual function DoWrite(), to be 
00528    * reimplemented by derived classes.
00529    *
00530    * @param rLabel
00531    *   Label of section to write
00532    * @param pContext
00533    *   Write context to provide contextual information
00534    * @return
00535    *   output string
00536    * @exception Exception
00537    *   - IO errors (id 2)
00538    */
00539   std::string ToString(const std::string& rLabel="", const Type* pContext=0) const;
00540 
00541   /**
00542    * Write configuration data to a formated string.
00543    * In contrast to ToString, ToText does not suppress comments and
00544    * End-Of-Line marks. 
00545    * Note: this write function uses the virtual function DoWrite(), to be 
00546    * reimplemented by derived classes.
00547    *
00548    * @param rLabel
00549    *   Label of section to write
00550    * @param pContext
00551    *   Write context to provide contextual information
00552    * @return
00553    *   output string
00554    * @exception Exception
00555    *   - IO errors (id 2)
00556    */
00557   std::string ToText(const std::string& rLabel="", const Type* pContext=0) const;
00558 
00559   /**
00560    * Write configuration data to console, debugging format.
00561    * Note: this write function uses the virtual function DoDWrite(), to be 
00562    * reimplemented by derived classes.
00563    *
00564    * @param pContext
00565    *   Write context to provide contextual information
00566    *
00567    */
00568   void DWrite(const Type* pContext=0) const;
00569 
00570   /**
00571    * Write configuration data to a file, debugging format. 
00572    * Note: this write function uses the virtual function DoDWrite(), to be 
00573    * reimplemented by derived classes.
00574    *
00575    * @param pFileName
00576    *   Name of file
00577    * @param rLabel
00578    *   Label of section to write
00579    * @param pContext
00580    *   Write context to provide contextual information
00581    * @param openmode
00582    *   ios::openmode 
00583    *
00584    * @exception Exception
00585    *   - IO errors (id 2)
00586    */
00587   void DWrite(const std::string& pFileName, const std::string& rLabel="",
00588         const Type* pContext=0, std::ios::openmode openmode = std::ios::out|std::ios::trunc) const;
00589 
00590   /**
00591    * Write configuration data in debug format to TokenWriter.
00592    * Note: this write function uses the virtual function DoWrite(), to be 
00593    * reimplemented by derived classes.
00594    *
00595    * @param rTw
00596    *   Reference to TokenWriter
00597    * @param rLabel
00598    *   Label of section to write
00599    * @param pContext
00600    *   Write context to provide contextual information
00601    *
00602    * @exception Exception 
00603    *   - IO errors (id 2)
00604    */
00605   void DWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00606 
00607   /**
00608    * Write statistics comment to TokenWriter.
00609    * Note: this write function use the virtual function DoSWrite(), to be 
00610    * reimplemented by derived classes.
00611    *
00612    * @param rTw
00613    *   Reference to TokenWriter
00614    *
00615    * @exception Exception 
00616    *   - IO errors (id 2)
00617    */
00618   void SWrite(TokenWriter& rTw) const;
00619 
00620   /**
00621    * Write statistics comment to console.
00622    * Note: this write function uses the virtual function DoSWrite(), to be 
00623    * reimplemented by derived classes.
00624    *
00625    */
00626   void SWrite(void) const;
00627 
00628   /**
00629    * Write statistics to a string.
00630    * Note: this write function uses the virtual function DoSWrite(), to be 
00631    * reimplemented by derived classes.
00632    *
00633    * @return
00634    *   output string
00635    * @exception Exception
00636    *   - IO errors (id 2)
00637    */
00638   std::string ToSText(void) const;
00639 
00640   /**
00641    * Read configuration data from file with label specified.
00642    * Note: all read functions use the virtual function DoRead(), to be 
00643    * reimplemented for by derived classes.
00644    *
00645    * @param rFileName
00646    *   Name of file
00647    * @param rLabel
00648    *   Section to read from 
00649    * @param pContext
00650    *   Read context to provide contextual information
00651    *
00652    * @exception Exception
00653    *   - IO errors (id 1)
00654    *   - token mismatch from DoRead()
00655    */
00656   void Read(const std::string& rFileName, const std::string& rLabel = "", const Type* pContext=0);
00657 
00658   /**
00659    * Write configuration data to a string.
00660    * Note: this write function uses the virtual function DoWrite(), to be 
00661    * reimplemented by derived classes.
00662    *
00663    * @param rString
00664    *   String to read from
00665    * @param rLabel
00666    *   Section to read
00667    * @param pContext
00668    *   Read context to provide contextual information
00669    * @exception Exception
00670    *   - IO errors (id 1)
00671    *   - token mismatch from DoRead()
00672    */
00673   void FromString(const std::string& rString, const std::string& rLabel="", const Type* pContext=0);
00674 
00675   /**
00676    * Read configuration data from TokenReader with label sepcified.
00677    * Note: all read functions use the virtual function DoRead(), to be 
00678    * reimplemented for by derived classes.
00679    *
00680    * @param rTr
00681    *   Reference to tokenreader
00682    * @param rLabel
00683    *   Section to read
00684    * @param pContext
00685    *   Read context to provide contextual information
00686    *
00687    * @exception Exception
00688    *   - IO errors (id 1)
00689    *   - token mismatch from DoRead()
00690    */
00691   void Read(TokenReader& rTr, const std::string& rLabel = "", const Type* pContext=0);
00692 
00693 
00694  protected:
00695 
00696   /**
00697    * Assign configuration data from other object. 
00698    *
00699    * Reimplement this function to copy all configuration data from
00700    * another faudes object. Typically, you will first call the base class'
00701    * DoAssign, which includes a Clear(). Then, you will set up any additional members.
00702    *
00703    * @param rSrc 
00704    *    Source to copy from
00705    */
00706   virtual void DoAssign(const Type& rSrc);
00707 
00708   /**
00709    * Test equality of configuration data.
00710    * Derived classes should reimplement this method to compare all relevant 
00711    * configuration, except the name.
00712    * 
00713    * @param rOther 
00714    *    Other object to compare with.
00715    * @return 
00716    *   True on match.
00717    */
00718   virtual bool DoEqual(const Type& rOther) const;
00719 
00720 
00721   /**
00722    * Read configuration data of this object from TokenReader.
00723    *
00724    * Reimplement this method in derived classes to provide the std token io
00725    * interface defined in the public section of Type.
00726    *
00727    * @param rTr
00728    *   TokenReader to read from
00729    * @param rLabel
00730    *   Section to read
00731    * @param pContext
00732    *   Read context to provide contextual information
00733    *
00734    * @exception Exception
00735    *   - IO error (id 1)
00736    */
00737   virtual void DoRead(TokenReader& rTr,  const std::string& rLabel = "", const Type* pContext=0);
00738  
00739   /**
00740    * Write configuration data of this object to TokenWriter.
00741    *
00742    * Reimplement this method in derived classes to provide the std token io
00743    * interface defined in the public section of Type.
00744    *
00745    * @param rTw
00746    *   Reference to TokenWriter
00747    * @param rLabel
00748    *   Label of section to write
00749    * @param pContext
00750    *   Write context to provide contextual information
00751    *
00752    * @exception Exception 
00753    *   - IO errors (id 2)
00754    */
00755   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00756 
00757   /**
00758    * Write configuration data of this object to TokenWriter in XML format.
00759    *
00760    * Reimplement this method in derived classes to provide the XML
00761    * token io interface defined in the public section of Type. The default implementation
00762    * invokes the std token output via 
00763    * DoWrite(TokenWriter&, const std::string&,const Type* )
00764    *
00765    * @param rTw
00766    *   Reference to TokenWriter
00767    * @param rLabel
00768    *   Label of section to write
00769    * @param pContext
00770    *   Write context to provide contextual information
00771    *
00772    * @exception Exception 
00773    *   - IO errors (id 2)
00774    */
00775   virtual void DoXWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00776 
00777   /**
00778    * Write configuration data in debugging format to TokenWriter.
00779    *
00780    * Reimplement this method in derived classes to provide the std token io
00781    * interface defined in the public section of Type.
00782    *
00783    * @param rTw
00784    *   Reference to TokenWriter
00785    * @param rLabel
00786    *   Label of section to write
00787    * @param pContext
00788    *   Write context to provide contextual information
00789    *
00790    * @exception Exception 
00791    *   - IO errors (id 2)
00792    */
00793   virtual void DoDWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00794 
00795   /**
00796    * Write statistical data as a comment to TokenWriter.
00797    *
00798    * Reimplement this method in derived classes to provide the std token io
00799    * interface defined in the public section of Type.
00800    *
00801    * @param rTw
00802    *   Reference to TokenWriter
00803    *
00804    * @exception Exception 
00805    *   - IO errors (id 2)
00806    */
00807   virtual void DoSWrite(TokenWriter& rTw) const;
00808 
00809   /** 
00810    * Get objects's type definition. 
00811    *
00812    * Returns the type definition corresponding to this object, or
00813    * NULL if the object is not of a registered type.
00814    *
00815    * Technical note: for minimal memory requirement, the type definition
00816    * is not cached but retrieved on every invokation of this method.
00817    * Derived classes may reimplement this method for performance 
00818    * reasons. Options include a look-up cache or a static member 
00819    * for the actual type definition. The latter variant will make the
00820    * type independant from the type registry.
00821    *
00822    * @return 
00823    *   Type definition reference.
00824    */
00825   virtual const TypeDefinition* TypeDefinitionp(void) const;
00826 
00827 
00828   /** 
00829    * Get objects's type name. 
00830    *
00831    * Retrieve the faudes-type name from the type registry.
00832    * However, this method silently returns the empty string if the type is 
00833    * not (yet) registered.
00834    *
00835    * @return 
00836    *   Faudes-type name or empty string.
00837    */
00838   virtual const std::string& TypeName(void) const;
00839 
00840 
00841 private:
00842 
00843   // static string constant
00844   static std::string msStringVoid;
00845   static std::string msStringEmpty;
00846 };
00847 
00848 
00849 
00850 
00851 /** faudes type declaration macros, individual */
00852 #define FAUDES_TYPE_DECLARATION_NEW(ftype,ctype,cbase)  \
00853   public: virtual ctype* New(void) const; 
00854 #define FAUDES_TYPE_DECLARATION_COPY(ftype,ctype,cbase) \
00855   public: virtual ctype* Copy(void) const; 
00856 #define FAUDES_TYPE_DECLARATION_CAST(ftype,ctype,cbase) \
00857   public: virtual const Type* Cast(const Type* pOther) const; 
00858 #define FAUDES_TYPE_DECLARATION_ASSIGN(ftype,ctype,cbase) \
00859   public: virtual ctype& Assign(const Type& rSrc); 
00860 #define FAUDES_TYPE_DECLARATION_EQUAL(ftype,ctype,cbase)  \
00861   public: virtual bool Equal(const Type& rOther) const; \
00862   public: virtual ctype& operator=(const ctype& rSrc); \
00863   public: virtual bool operator==(const ctype& rOther) const; \
00864   public: virtual bool operator!=(const ctype& rOther) const; 
00865 
00866 /** faudes type declaration macro, overall */
00867 #define FAUDES_TYPE_DECLARATION(ftype,ctype,cbase)  \
00868  public: \
00869   virtual ctype* New(void) const; \
00870   virtual ctype* Copy(void) const; \
00871   virtual const Type* Cast(const Type* pOther) const; \
00872   virtual ctype& Assign(const Type& rSrc); \
00873   virtual bool Equal(const Type& rOther) const; \
00874   virtual ctype& operator=(const ctype& rSrc); \
00875   virtual bool operator==(const ctype& rOther) const; \
00876   virtual bool operator!=(const ctype& rOther) const; 
00877 
00878 /** faudes type declaration macro, template version */
00879 #define FAUDES_TYPE_TDECLARATION(ftype,ctype,cbase) \
00880  public: \
00881   virtual ctype* New(void) const; \
00882   virtual ctype* Copy(void) const; \
00883   virtual const Type* Cast(const Type* pOther) const; \
00884   virtual ctype& Assign(const Type& rSrc); \
00885   virtual bool Equal(const Type& rOther) const; \
00886   virtual ctype& operator=(const ctype& rSrc); \
00887   virtual bool operator==(const ctype& rOther) const; \
00888   virtual bool operator!=(const ctype& rOther) const; 
00889 
00890 /** faudes type implementation macros, individual */
00891 #define FAUDES_TYPE_IMPLEMENTATION_NEW(ftype,ctype,cbase) \
00892   ctype* ctype::New(void) const {     \
00893     return new ctype(); } 
00894 #define FAUDES_TYPE_IMPLEMENTATION_COPY(ftype,ctype,cbase)  \
00895   ctype* ctype::Copy(void) const {      \
00896     return new ctype(*this); } 
00897 #define FAUDES_TYPE_IMPLEMENTATION_CAST(ftype,ctype,cbase)  \
00898   const Type* ctype::Cast(const Type* pOther) const { \
00899     return dynamic_cast<const ctype*>(pOther); } 
00900 #define FAUDES_TYPE_IMPLEMENTATION_ASSIGN(ftype,ctype,cbase)  \
00901   ctype& ctype::Assign(const Type& rSrc) { \
00902     if(const ctype* csattr=dynamic_cast<const ctype*>(&rSrc)) { \
00903       this->Clear(); DoAssign(*csattr);} \
00904     else {    \
00905       cbase::Assign(rSrc);};  \
00906     return *this;} \
00907   ctype& ctype::operator=(const ctype& rSrc) { this->Clear(); DoAssign(rSrc); return *this; }
00908 #define FAUDES_TYPE_IMPLEMENTATION_EQUAL(ftype,ctype,cbase) \
00909   bool ctype::Equal(const Type& rOther) const { \
00910     if(&rOther==this) return true; \
00911     if(typeid(rOther) != typeid(*this)) return false; \
00912     const ctype* csattr=dynamic_cast<const ctype*>(&rOther); \
00913     if(!csattr) return false; \
00914     if(!DoEqual(*csattr)) return false;   \
00915     return true;} \
00916   bool ctype::operator==(const ctype& rOther) const { return DoEqual(rOther); } \
00917   bool ctype::operator!=(const ctype& rOther) const { return !DoEqual(rOther); }
00918 
00919 
00920 /** faudes type implementation macros, overall */
00921 #define FAUDES_TYPE_IMPLEMENTATION(ftype,ctype,cbase)  \
00922   ctype* ctype::New(void) const {     \
00923     return new ctype(); }  \
00924   ctype* ctype::Copy(void) const {      \
00925     return new ctype(*this); }      \
00926   const Type* ctype::Cast(const Type* pOther) const { \
00927     return dynamic_cast<const ctype*>(pOther); } \
00928   ctype& ctype::Assign(const Type& rSrc) { \
00929     if(const ctype* csattr=dynamic_cast<const ctype*>(&rSrc)) \
00930       { this->Clear(); DoAssign(*csattr); return *this;}      \
00931     cbase::Assign(rSrc); \
00932     return *this;} \
00933   ctype& ctype::operator=(const ctype& rSrc) { this->Clear(); DoAssign(rSrc); return *this;} \
00934   bool ctype::Equal(const Type& rOther) const { \
00935     if(&rOther==this) return true; \
00936     if(typeid(rOther) != typeid(*this)) return false; \
00937     const ctype* csattr=dynamic_cast<const ctype*>(&rOther);  \
00938     if(!csattr) return false; \
00939     if(!DoEqual(*csattr)) return false;   \
00940     return true;} \
00941   bool ctype::operator==(const ctype& rOther) const { return DoEqual(rOther); } \
00942   bool ctype::operator!=(const ctype& rOther) const { return !DoEqual(rOther); } 
00943 
00944 
00945 /** obsolete, registration is now via rti2code */
00946 // #define FAUDES_TYPE_IMPLEMENTATION_REGISTER(ftype,ctype,cbase)       
00947 //   RegisterType<ctype> gRtiAutoRegister##ctype(#ftype);
00948 
00949 
00950 /** faudes type implementation macros, individual, template version */
00951 #define FAUDES_TYPE_TIMPLEMENTATION_NEW(ftype,ctype,cbase,ctemp)  \
00952   ctemp ctype* ctype::New(void) const {     \
00953     return new ctype(); } 
00954 #define FAUDES_TYPE_TIMPLEMENTATION_COPY(ftype,ctype,cbase,ctemp) \
00955   ctemp ctype* ctype::Copy(void) const {      \
00956     return new ctype(*this); } 
00957 #define FAUDES_TYPE_TIMPLEMENTATION_CAST(ftype,ctype,cbase,ctemp) \
00958   ctemp const Type* ctype::Cast(const Type* pOther) const { \
00959     return dynamic_cast<const ctype*>(pOther);} 
00960 #define FAUDES_TYPE_TIMPLEMENTATION_ASSIGN(ftype,ctype,cbase,ctemp) \
00961   ctemp ctype& ctype::Assign(const Type& rSrc) { \
00962     if(const ctype* csattr=dynamic_cast<const ctype*>(&rSrc)) { \
00963       this->Clear(); DoAssign(*csattr); return *this;}    \
00964     cbase::Assign(rSrc); \
00965     return *this;} \
00966   ctemp ctype& ctype::operator=(const ctype& rSrc) { this->Clear(); DoAssign(rSrc); return *this; }
00967 #define FAUDES_TYPE_TIMPLEMENTATION_EQUAL(ftype,ctype,cbase,ctemp)  \
00968   ctemp bool ctype::Equal(const Type& rOther) const { \
00969     if(&rOther==this) return true; \
00970     if(typeid(rOther) != typeid(*this)) return false; \
00971     const ctype* csattr=dynamic_cast<const ctype*>(&rOther); \
00972     if(!csattr) return false; \
00973     if(!DoEqual(*csattr)) return false;   \
00974     return true;} \
00975   ctemp bool ctype::operator==(const ctype& rOther) const { return DoEqual(rOther); } \
00976   ctemp bool ctype::operator!=(const ctype& rOther) const { return !DoEqual(rOther); }
00977 
00978 
00979 /** faudes type implementation macros, overall, template version */
00980 #define FAUDES_TYPE_TIMPLEMENTATION(ftype,ctype,cbase,ctemp)  \
00981   ctemp ctype* ctype::New(void) const {   \
00982     return new ctype(); }  \
00983   ctemp ctype* ctype::Copy(void) const {      \
00984     return new ctype(*this); }  \
00985   ctemp const Type* ctype::Cast(const Type* pOther) const { \
00986     return dynamic_cast<const ctype*>(pOther);} \
00987   ctemp ctype& ctype::Assign(const Type& rSrc) { \
00988     if(const ctype* csattr=dynamic_cast<const ctype*>(&rSrc)) \
00989       { this->Clear(); DoAssign(*csattr); return *this;}      \
00990     cbase::Assign(rSrc); \
00991     return *this;} \
00992   ctemp ctype& ctype::operator=(const ctype& rSrc) { this->Clear(); DoAssign(rSrc); return *this; } \
00993   ctemp bool ctype::Equal(const Type& rOther) const { \
00994     if(&rOther==this) return true; \
00995     if(typeid(rOther) != typeid(*this)) return false; \
00996     const ctype* csattr=dynamic_cast<const ctype*>(&rOther);  \
00997     if(!csattr) return false; \
00998     if(!DoEqual(*csattr)) return false;   \
00999     return true;} \
01000   ctemp bool ctype::operator==(const ctype& rOther) const { return DoEqual(rOther); } \
01001   ctemp bool ctype::operator!=(const ctype& rOther) const { return !DoEqual(rOther); } 
01002 
01003 
01004 /** faudes type implementation macros, overall, debug version */
01005 /*
01006 #define FAUDES_TYPE_IMPLEMENTATION(ctype,cbase,ctemp) \
01007   ctemp ctype* ctype::New(void) const {     \
01008     return new ctype(); }  \
01009   ctemp const ctype* ctype::Cast(const Type* pOther) const { \
01010     return dynamic_cast<const ctype*>(pOther);} \
01011   ctemp ctype& ctype::Assign(const Type& rSrc) { \
01012     FD_WARN("RTI "<< typeid(ctype).name() << "::ASSIGN() V: " << typeid(*this).name() << \
01013       " from " << typeid(rSrc).name()); \
01014     if(const ctype* csattr=dynamic_cast<const ctype*>(&rSrc)) { this->Clear(); return DoAssign(*csattr);} \
01015     cbase::Assign(rSrc); \
01016     return *this;} \
01017   ctemp ctype& ctype::operator=(const ctype& rSrc) { \
01018     FD_WARN("RTI "<< typeid(ctype).name() << "::ASSIGN() O: " << typeid(*this).name() << \
01019       " from " << typeid(rSrc).name()); \
01020     this->Clear(); \
01021     return DoAssign(rSrc); }
01022 */
01023 
01024 
01025 
01026 /**
01027  * Structure to hold documentation data relating to a faudes-type or -function. 
01028  * This class is the common base for faudes::TypeDefinition and faudes::FunctionDefinition. 
01029  * It supports token io as demonstrated by the follwoing example for a type defintion:
01030  *
01031  * @code
01032  *  <TypeDefinition name="CoreFaudes::Generator" ctype="faudes::vGenerator">
01033  *
01034  *  <Documentation ref="generators.html#plain"> 
01035  *      The common 5 tuple G=(Sigma, Q, delta, Qo, Qm).
01036  *  <Documentation/>
01037  *
01038  *  <Keywords> "generator" "language" </Keywords>
01039  *
01040  *  </TypeDefinition>
01041  * @endcode
01042  *
01043  * Technical detail: Documentation is derived from Type for the purpose of token IO. We
01044  * still implement the faudes type interface to make it a fully qualified faudes data type.
01045  *
01046  * Technical detail: To facilitate inheritance, token io of member data and token io of
01047  * the section tags is separated.
01048  */
01049 
01050 class Documentation : public Type {
01051 
01052   // std faudes type interface
01053   FAUDES_TYPE_DECLARATION(Void,Documentation,Type)
01054   
01055 public:
01056   /** Constructor */
01057   Documentation(void);
01058 
01059   /** Copy constructor */
01060   Documentation(const Documentation& rOther);
01061 
01062   /** Destructor */
01063   virtual ~Documentation(void){};
01064 
01065   /**
01066    * Clear 
01067    */
01068   void Clear(void);
01069 
01070   /**
01071    * Get name of the entety to document (aka faudes-type or faudes-function).
01072    *
01073    * @return
01074    *  Name
01075    */
01076   const std::string& Name(void) const;
01077 
01078   /**
01079    * Get name of plugin.
01080    * The plugin name defaults to CoreFaudes.
01081    *
01082    * @return
01083    *  Name
01084    */
01085   const std::string& PlugIn(void) const;
01086 
01087   /**
01088    * Get corresponding C++ type
01089    *
01090    * @return
01091    *  CType, or "" if no such
01092    */
01093   const std::string& CType(void) const;
01094 
01095   /**
01096    * @return
01097    *  Short textual documentation.
01098    */
01099   const std::string& TextDoc(void) const;
01100 
01101   /**
01102    * @return
01103    *  Filename pointing to the html documentation.
01104    */
01105   const std::string& HtmlDoc(void) const;
01106 
01107   /**
01108    * @return
01109    *  CSV-string containing keywords.
01110    */
01111   const std::string& Keywords(void) const;
01112 
01113   /**
01114    * Search comma-seperated keywords for a substring. This should be
01115    * extended to regular expressions in a future release.
01116    *
01117    * @param rPattern
01118    *  String-pattern.
01119    *
01120    * @return
01121    *  Matching keyword or "" if no match
01122    */
01123   std::string MatchKeyword(const std::string& rPattern) const;
01124 
01125   /**
01126    * Not implemented
01127    * @return
01128    *  Number of keywords.
01129    */
01130   int KeywordsSize(void) const;
01131 
01132   /**
01133    * @param pos
01134    *   Position of keyword
01135    * @return
01136    *  Keyword at specified position (or "" if pos out of range)
01137    */
01138   std::string KeywordAt(int pos) const;
01139 
01140   /**
01141    * Get auto-register flag.
01142    *
01143    * @return
01144    *  True <> automatic registration
01145    */
01146   bool AutoRegister(void) const;
01147 
01148   /**
01149    * Merge documentation from token stream.
01150    * An exception is thrown if the current type name differs from the one in the documentation.
01151    *
01152    * @param rTr
01153    *  TokenReader to read from.
01154    *
01155    * @exception Exception
01156    *  - Type mismatch (id )
01157    *  - Token mismatch (id 50, 51, 52)
01158    *  - IO Error (id 1)
01159    */
01160   virtual void MergeDocumentation(TokenReader& rTr);
01161 
01162 
01163 
01164  protected:
01165 
01166   /**
01167    * Set name.
01168    *
01169    * @param name
01170    *  New name.
01171    */
01172   void Name(const std::string& name);
01173 
01174   /**
01175    * Set name of plugin
01176    *
01177    * @param plugin
01178    *  New name.
01179    */
01180   void PlugIn(const std::string& plugin);
01181 
01182   /**
01183    * Set C++ type
01184    *
01185    * @param name
01186    *  New ctype.
01187    */
01188   void CType(const std::string& name);
01189 
01190   /**
01191    * Set a short textual documentation.
01192    *
01193    * @param textdoc
01194    *  New textual documentation.
01195    */
01196   void TextDoc(const std::string& textdoc);
01197 
01198   /**
01199    * Set name of file pointing to the html documentation.
01200    *
01201    * @param fname
01202    *  Filename
01203    */
01204   void HtmlDoc(const std::string& fname);
01205 
01206   /**
01207    * Append keyword.
01208    *
01209    * @param rKeyword
01210    *  Keyword
01211    */
01212   void AddKeyword(const std::string& rKeyword);
01213 
01214   /**
01215    * Set auto-register flag.
01216    *
01217    * @param flag
01218    *  Flag value.
01219    */
01220   void AutoRegister(bool flag);
01221 
01222   /**
01223    * Std faudes type interface: assignment.
01224    *
01225    * @param rSrc 
01226    *    Source to copy from
01227    * @return Reference to this object.
01228    */
01229   virtual void DoAssign(const Documentation& rSrc);
01230 
01231   /**
01232    * Std faudes type interface: test equality
01233    * 
01234    * @param rOther 
01235    *    Other object to compare with.
01236    * @return 
01237    *   True on match.
01238    */
01239   virtual bool DoEqual(const Documentation& rOther) const;
01240 
01241   /**
01242    * Read configuration data of this object from TokenReader.
01243    *
01244    * This virtual function reads documentation from a token stream. 
01245    * The section defaults to Documentation. It invokes DoReadCore to
01246    * do the member data token reading. 
01247    *
01248    * @param rTr
01249    *   TokenReader to read from
01250    * @param rLabel
01251    *   Section to read
01252    * @param pContext
01253    *   Read context to provide contextual information (ignored)
01254    *
01255    * @exception Exception
01256    *  - Token mismatch (id 50, 51, 52)
01257    *  - IO Error (id 1)
01258    */
01259   virtual void DoRead(TokenReader& rTr,  const std::string& rLabel = "", const Type* pContext=0);
01260  
01261   /**
01262    * Read configuration data of this object from TokenReader.
01263    *
01264    * This virtual function reads documentation member data only. 
01265    * It does NOT read the enclosing begin and end tokens.
01266    *
01267    * @param rTr
01268    *   TokenReader to read from
01269    *
01270    * @exception Exception
01271    *  - Token mismatch (id 50, 51, 52)
01272    *  - IO Error (id 1)
01273    */
01274   virtual void DoReadCore(TokenReader& rTr);
01275  
01276 
01277 
01278   /**
01279    * Write configuration data of this object to TokenWriter.
01280    *
01281    * This virtual function writes documentation to a token stream. 
01282    * The section defaults to Documentation. It invokes DoWriteCore to
01283    * do the actual member data writing. 
01284    *
01285    * @param rTw
01286    *   Reference to TokenWriter
01287    * @param rLabel
01288    *   Label of section to write
01289    * @param pContext
01290    *   Write context to provide contextual information
01291    *
01292    * @exception Exception 
01293    *   - IO errors (id 2)
01294    */
01295   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
01296 
01297 
01298   /**
01299    * Write configuration data of this object to TokenWriter.
01300    *
01301    * This virtual function reads documentation members only. 
01302    * It does NOT write enclosing begin and end tokens.
01303    *
01304    * @param rTw
01305    *   Reference to TokenWriter
01306    *
01307    * @exception Exception 
01308    *   - IO errors (id 2)
01309    */
01310   virtual void DoWriteCore(TokenWriter& rTw) const;
01311 
01312 
01313   /** Faudes name. */
01314   std::string mName;
01315 
01316   /** Faudes plugin. */
01317   std::string mPlugIn;
01318 
01319   /** Corresponing C++ type, or "" if no such. */
01320   std::string mCType;
01321 
01322   /** String containing the text-documentation. */
01323   std::string mTextDoc;
01324 
01325   /** String containing the filename of the corresponding html-documentation. */
01326   std::string mHtmlDoc;
01327 
01328   /** Comma-seperated string containing all keywords. */
01329   std::string mKeywords;
01330 
01331   /** Constant characted used to seperate keywords */
01332   static const char mDelim = ';';
01333 
01334   /** Flag to indicate automated registration */
01335   bool mAutoRegister;
01336 
01337 }; // Documentation
01338 
01339 
01340 
01341 /**
01342  * A TypeDefinition defines a faudes-type in that it specifies
01343  * a faudes-type name to identify the type and a method
01344  * NewObject() to instantiate objects of the respective type. 
01345  * In this sense, TypeDefinition is a so called factory class.
01346  * Technically, the TypeDefinition holds one instance of the faude type,
01347  * the so called prototype object, and NewObject() invokes the New() method
01348  * of the prototype. Notebly, there is only one class TypeDefinition that by
01349  * parametrisation defins all derivates of Type.
01350  * 
01351  * TypeDefinition is derived from faudes::Documentation and therefore additional
01352  * documentation-data can be associated.
01353  *
01354  *
01355  * @ingroup RunTimeInterface
01356  */
01357 
01358 class TypeDefinition : public Documentation {
01359 
01360  // std faudes type interface
01361  FAUDES_TYPE_DECLARATION(Void,TypeDefinition,Documentation)
01362 
01363  // regisry is friend to set protected valued
01364  friend class TypeRegistry;
01365 
01366  public:
01367 
01368   /** 
01369    * Constructor 
01370    *
01371    * The default constructor instantiates an invalid type definition
01372    * without prototype. To construct
01373    * a valid type definition, use the static Constructor() template
01374    * function.
01375    */
01376   TypeDefinition(const std::string& name="") : Documentation(), mpType(NULL) {Name(name);};
01377 
01378   /**
01379    * Destructor.
01380    *
01381    * Delete prototype object.
01382    */
01383   virtual ~TypeDefinition(void){ Prototype(NULL); };
01384 
01385   /**
01386    * Construct empty TypeDefinition object.
01387    * The given template parameter denotes any libFAUDES class derived from faudes::Type
01388    * A new instance of this class is assigned to member variable (pType)
01389    * whereas the name is set as specified.
01390    *
01391    * @tparam T
01392    *   Actual c class, derived from Type
01393    * @param rTypeName
01394    *   Name to identify this faudes-type<; defaults to the plattform
01395    *   dependand typeid from the c++ runtime type information system.
01396    * @return
01397    *   Newly constructed type definition.
01398    *
01399    */
01400   template<class T>
01401   static TypeDefinition* Constructor(const std::string& rTypeName="");
01402 
01403   /**
01404    * Construct empty TypeDefinition object.
01405    * The given prototype is assigned to the member variable pType,
01406    *
01407    * @param pProto
01408    *   Prototype, derived from Type
01409    * @param rTypeName
01410    *   Name to identify this faudes-type<; defaults to the plattform
01411    *   dependand typeid from the c++ runtime type information system.
01412    * @return
01413    *   Newly constructed type definition.
01414    *
01415    */
01416   static TypeDefinition* Constructor(Type* pProto, const std::string& rTypeName="");
01417 
01418   /**
01419    * Construct TypeDefinition object and read name and
01420    * documentation-data from TokenReader.
01421    *
01422    * @tparam T
01423    *   Actual c class, derived from Type
01424    * @param rFileName
01425    *   Name of file to read.
01426    * @return
01427    *   Newly constructed type definition.
01428    *
01429    * @exception Exception
01430    *  - Token mismatch (id 50, 51, 52)
01431    *  - IO Error (id 1)
01432    */
01433   template<class T>
01434   static TypeDefinition* FromFile(const std::string& rFileName);
01435 
01436 
01437   /**
01438    * Return pointer to faudes-object prototype 
01439    *
01440    * Note: this method is meant for inspection only, control over
01441    * the prototype remains with the TypeDefinition. Use
01442    * NewObject() to instantiate a new faudes-object.
01443    *
01444    * @return
01445    *   Reference to prototype object
01446    */
01447   const Type* Prototype(void) const;
01448 
01449 
01450   /**
01451    * Construct faudes-object on heap.
01452    * Return pointer to new instance of assigned Type class.
01453    *
01454    * Note: If no prototype is installed, NULL is returned.
01455    *
01456    * @return
01457    *  Pointer to new Type instance.
01458    */
01459   Type* NewObject(void) const;
01460 
01461 
01462   /** 
01463    * Parameter access: Xml Element Tag
01464    *
01465    * This parameter is used for Xml IO of sets and vectors. It determines
01466    * the tag to used for individual elments.
01467    *
01468    * @return
01469    *   Tag parameter.
01470    */
01471   const std::string& XElementTag(void) const; 
01472 
01473   /** 
01474    * Parameter access: Xml Element Tag
01475    *
01476    * @param rTag
01477    *   New tag parameter
01478    */
01479   void XElementTag(const std::string& rTag); 
01480 
01481 protected:
01482 
01483 
01484   /**
01485    * Std faudes type interface: assignment.
01486    *
01487    * @param rSrc 
01488    *    Source to copy from
01489    * @return Reference to this object.
01490    */
01491   virtual void DoAssign(const TypeDefinition& rSrc);
01492 
01493   /**
01494    * Std faudes type interface: test equality
01495    * 
01496    * @param rOther 
01497    *    Other object to compare with.
01498    * @return 
01499    *   True on match.
01500    */
01501   virtual bool DoEqual(const TypeDefinition& rOther) const;
01502 
01503   /** Disable copy constructor */
01504  TypeDefinition(const TypeDefinition& rOther) : Documentation(rOther) {}; // todo: implement ?? for stl maps ?
01505 
01506   /**
01507    * Clear documentation-data; do *NOT* delete prototype  (this is for using Read to 
01508    * merge/overwrite documentation)
01509    */
01510   void Clear(void);
01511 
01512   /**
01513    * Use given object as prototype.
01514    *
01515    * The TypeDefinition takes ownership of the
01516    * provided object.
01517    *
01518    * @param pType
01519    *  Any class that inherits Type.
01520    */
01521   virtual void Prototype(Type* pType);
01522 
01523   /**
01524    * Read configuration data of this object from TokenReader.
01525    *
01526    * The section defaults to "TypeDefinition", context ignored.
01527    * Actual reading is done by DoReadCore.
01528    *
01529    * @param rTr
01530    *   TokenReader to read from
01531    * @param rLabel
01532    *   Section to read
01533    * @param pContext
01534    *   Read context to provide contextual information (ignored)
01535    *
01536    * @exception Exception
01537    *   - Token mismatch (id 50, 51, 52)
01538    *   - IO error (id 1)
01539    */
01540   virtual void DoRead(TokenReader& rTr,  const std::string& rLabel = "", const Type* pContext=0);
01541  
01542   /**
01543    * Read configuration data of this object from TokenReader.
01544    *
01545    * This method reads members only, it does not read the section.
01546    *
01547    * @param rTr
01548    *   TokenReader to read from
01549    *
01550    * @exception Exception
01551    *   - Token mismatch (id 50, 51, 52)
01552    *   - IO error (id 1)
01553    */
01554   virtual void DoReadCore(TokenReader& rTr);
01555  
01556   /**
01557    * Write configuration data of this object to TokenWriter.
01558    *
01559    * The section defaults to "TypeDefinition", context ignored.
01560    * Actual writing is done by DoWriteCore.
01561    *
01562    * @param rTw
01563    *   Reference to TokenWriter
01564    * @param rLabel
01565    *   Label of section to write
01566    * @param pContext
01567    *   Write context to provide contextual information
01568    *
01569    * @exception Exception 
01570    *   - IO errors (id 2)
01571    */
01572   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
01573 
01574   /**
01575    * Write configuration data of this object to TokenWriter.
01576    *
01577    * This method wrtite plain member data, the section lables are not
01578    * written.
01579    *
01580    * @param rTw
01581    *   Reference to TokenWriter
01582    *
01583    * @exception Exception 
01584    *   - IO errors (id 2)
01585    */
01586   virtual void DoWriteCore(TokenWriter& rTw) const;
01587 
01588   /** Type-pointer tp prototype instance */
01589   Type* mpType;
01590 
01591   /** Extra documentation/parameter: Xml Element Tag */
01592   std::string mXElementTag;
01593 
01594 }; //TypeDefinition
01595 
01596 
01597 
01598 
01599 /**********************************************************************************************
01600 ***********************************************************************************************
01601 ***********************************************************************************************
01602 
01603 Implemention of template members functions
01604 
01605 ***********************************************************************************************
01606 ***********************************************************************************************
01607 **********************************************************************************************/
01608 
01609 
01610 // Typedefinition constructor function
01611 template<class T>
01612 TypeDefinition* TypeDefinition::Constructor(const std::string& rTypeName){
01613   FD_DRTI("TypeDefinition::Construct<" << typeid(T).name() << ">(" << rTypeName << ")");
01614   return Constructor(new T, rTypeName);
01615 }
01616 
01617 
01618 // Type definition constructor function
01619 template<class T>
01620 TypeDefinition* TypeDefinition::FromFile(const std::string& rFileName){
01621   FD_DRTI("TypeDefinition::FromFile<" << typeid(T).name() << ">()");
01622   // construct with fallback name
01623   TypeDefinition* td = Constructor<T>();
01624   // read docu, incl actual name
01625   td->Read(rFileName);
01626   // done
01627   return(td);
01628 }
01629 
01630 
01631 
01632 
01633 
01634 } // namespace
01635 
01636 #endif /* FAUDES_RTITYPES_H */

libFAUDES 2.18b --- 2010-12-17 --- c++ source docu by doxygen 1.6.3