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="../reference/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 following 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(), DoEqual() and Clear() need to be 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; see e.g. AttributeFlags.
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 concole
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    * 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    * Convenience function to set up std begin token
00842    * for XML mode token I/O.
00843    *
00844    *
00845    * @param rLabel
00846    *   User specified label
00847    * @param rFallbackLabel 
00848    *   Class defined  fallback label
00849    * @return
00850    *   Configured begin token
00851    */
00852   virtual Token XBeginTag(const std::string& rLabel="", const std::string& rFallbackLabel="") const;
00853 
00854 
00855 private:
00856 
00857   // static string constant
00858   static std::string msStringVoid;
00859   static std::string msStringEmpty;
00860 
00861 };
00862 
00863 
00864 
00865 
00866 /** faudes type declaration macros, individual */
00867 #define FAUDES_TYPE_DECLARATION_NEW(ftype,ctype,cbase)  \
00868   public: virtual ctype* New(void) const; 
00869 #define FAUDES_TYPE_DECLARATION_COPY(ftype,ctype,cbase) \
00870   public: virtual ctype* Copy(void) const; 
00871 #define FAUDES_TYPE_DECLARATION_CAST(ftype,ctype,cbase) \
00872   public: virtual const Type* Cast(const Type* pOther) const; 
00873 #define FAUDES_TYPE_DECLARATION_ASSIGN(ftype,ctype,cbase) \
00874   public: virtual ctype& Assign(const Type& rSrc); 
00875 #define FAUDES_TYPE_DECLARATION_EQUAL(ftype,ctype,cbase)  \
00876   public: virtual bool Equal(const Type& rOther) const; \
00877   public: virtual ctype& operator=(const ctype& rSrc); \
00878   public: virtual bool operator==(const ctype& rOther) const; \
00879   public: virtual bool operator!=(const ctype& rOther) const; 
00880 
00881 /** faudes type declaration macro, overall */
00882 #define FAUDES_TYPE_DECLARATION(ftype,ctype,cbase)  \
00883  public: \
00884   virtual ctype* New(void) const; \
00885   virtual ctype* Copy(void) const; \
00886   virtual const Type* Cast(const Type* pOther) const; \
00887   virtual ctype& Assign(const Type& rSrc); \
00888   virtual bool Equal(const Type& rOther) const; \
00889   virtual ctype& operator=(const ctype& rSrc); \
00890   virtual bool operator==(const ctype& rOther) const; \
00891   virtual bool operator!=(const ctype& rOther) const; 
00892 
00893 /** faudes type declaration macro, template version */
00894 #define FAUDES_TYPE_TDECLARATION(ftype,ctype,cbase) \
00895  public: \
00896   virtual ctype* New(void) const; \
00897   virtual ctype* Copy(void) const; \
00898   virtual const Type* Cast(const Type* pOther) const; \
00899   virtual ctype& Assign(const Type& rSrc); \
00900   virtual bool Equal(const Type& rOther) const; \
00901   virtual ctype& operator=(const ctype& rSrc); \
00902   virtual bool operator==(const ctype& rOther) const; \
00903   virtual bool operator!=(const ctype& rOther) const; 
00904 
00905 /** faudes type implementation macros, individual */
00906 #define FAUDES_TYPE_IMPLEMENTATION_NEW(ftype,ctype,cbase) \
00907   ctype* ctype::New(void) const {     \
00908     return new ctype(); } 
00909 #define FAUDES_TYPE_IMPLEMENTATION_COPY(ftype,ctype,cbase)  \
00910   ctype* ctype::Copy(void) const {      \
00911     return new ctype(*this); } 
00912 #define FAUDES_TYPE_IMPLEMENTATION_CAST(ftype,ctype,cbase)  \
00913   const Type* ctype::Cast(const Type* pOther) const { \
00914     return dynamic_cast<const ctype*>(pOther); } 
00915 #define FAUDES_TYPE_IMPLEMENTATION_ASSIGN(ftype,ctype,cbase)  \
00916   ctype& ctype::Assign(const Type& rSrc) { \
00917     if(const ctype* csattr=dynamic_cast<const ctype*>(&rSrc)) { \
00918       this->Clear(); DoAssign(*csattr);} \
00919     else {    \
00920       cbase::Assign(rSrc);};  \
00921     return *this;} \
00922   ctype& ctype::operator=(const ctype& rSrc) { this->Clear(); DoAssign(rSrc); return *this; }
00923 #define FAUDES_TYPE_IMPLEMENTATION_EQUAL(ftype,ctype,cbase) \
00924   bool ctype::Equal(const Type& rOther) const { \
00925     if(&rOther==this) return true; \
00926     if(typeid(rOther) != typeid(*this)) return false; \
00927     const ctype* csattr=dynamic_cast<const ctype*>(&rOther); \
00928     if(!csattr) return false; \
00929     if(!DoEqual(*csattr)) return false;   \
00930     return true;} \
00931   bool ctype::operator==(const ctype& rOther) const { return DoEqual(rOther); } \
00932   bool ctype::operator!=(const ctype& rOther) const { return !DoEqual(rOther); }
00933 
00934 
00935 /** faudes type implementation macros, overall */
00936 #define FAUDES_TYPE_IMPLEMENTATION(ftype,ctype,cbase)  \
00937   ctype* ctype::New(void) const {     \
00938     return new ctype(); }  \
00939   ctype* ctype::Copy(void) const {      \
00940     return new ctype(*this); }      \
00941   const Type* ctype::Cast(const Type* pOther) const { \
00942     return dynamic_cast<const ctype*>(pOther); } \
00943   ctype& ctype::Assign(const Type& rSrc) { \
00944     if(const ctype* csattr=dynamic_cast<const ctype*>(&rSrc)) \
00945       { this->Clear(); DoAssign(*csattr); return *this;}      \
00946     cbase::Assign(rSrc); \
00947     return *this;} \
00948   ctype& ctype::operator=(const ctype& rSrc) { this->Clear(); DoAssign(rSrc); return *this;} \
00949   bool ctype::Equal(const Type& rOther) const { \
00950     if(&rOther==this) return true; \
00951     if(typeid(rOther) != typeid(*this)) return false; \
00952     const ctype* csattr=dynamic_cast<const ctype*>(&rOther);  \
00953     if(!csattr) return false; \
00954     if(!DoEqual(*csattr)) return false;   \
00955     return true;} \
00956   bool ctype::operator==(const ctype& rOther) const { return DoEqual(rOther); } \
00957   bool ctype::operator!=(const ctype& rOther) const { return !DoEqual(rOther); } 
00958 
00959 
00960 
00961 
00962 /** faudes type implementation macros, individual, template version */
00963 #define FAUDES_TYPE_TIMPLEMENTATION_NEW(ftype,ctype,cbase,ctemp)  \
00964   ctemp ctype* ctype::New(void) const {     \
00965     return new ctype(); } 
00966 #define FAUDES_TYPE_TIMPLEMENTATION_COPY(ftype,ctype,cbase,ctemp) \
00967   ctemp ctype* ctype::Copy(void) const {      \
00968     return new ctype(*this); } 
00969 #define FAUDES_TYPE_TIMPLEMENTATION_CAST(ftype,ctype,cbase,ctemp) \
00970   ctemp const Type* ctype::Cast(const Type* pOther) const { \
00971     return dynamic_cast<const ctype*>(pOther);} 
00972 #define FAUDES_TYPE_TIMPLEMENTATION_ASSIGN(ftype,ctype,cbase,ctemp) \
00973   ctemp ctype& ctype::Assign(const Type& rSrc) { \
00974     if(const ctype* csattr=dynamic_cast<const ctype*>(&rSrc)) { \
00975       this->Clear(); DoAssign(*csattr); return *this;}    \
00976     cbase::Assign(rSrc); \
00977     return *this;} \
00978   ctemp ctype& ctype::operator=(const ctype& rSrc) { this->Clear(); DoAssign(rSrc); return *this; }
00979 #define FAUDES_TYPE_TIMPLEMENTATION_EQUAL(ftype,ctype,cbase,ctemp)  \
00980   ctemp bool ctype::Equal(const Type& rOther) const { \
00981     if(&rOther==this) return true; \
00982     if(typeid(rOther) != typeid(*this)) return false; \
00983     const ctype* csattr=dynamic_cast<const ctype*>(&rOther); \
00984     if(!csattr) return false; \
00985     if(!this->DoEqual(*csattr)) return false;   \
00986     return true;} \
00987   ctemp bool ctype::operator==(const ctype& rOther) const { return this->DoEqual(rOther); } \
00988   ctemp bool ctype::operator!=(const ctype& rOther) const { return !this->DoEqual(rOther); }
00989 
00990 
00991 /** faudes type implementation macros, overall, template version */
00992 #define FAUDES_TYPE_TIMPLEMENTATION(ftype,ctype,cbase,ctemp)  \
00993   ctemp ctype* ctype::New(void) const {   \
00994     return new ctype(); }  \
00995   ctemp ctype* ctype::Copy(void) const {      \
00996     return new ctype(*this); }  \
00997   ctemp const Type* ctype::Cast(const Type* pOther) const { \
00998     return dynamic_cast<const ctype*>(pOther);} \
00999   ctemp ctype& ctype::Assign(const Type& rSrc) { \
01000     if(const ctype* csattr=dynamic_cast<const ctype*>(&rSrc)) \
01001       { this->Clear(); DoAssign(*csattr); return *this;}      \
01002     cbase::Assign(rSrc); \
01003     return *this;} \
01004   ctemp ctype& ctype::operator=(const ctype& rSrc) { this->Clear(); DoAssign(rSrc); return *this; } \
01005   ctemp bool ctype::Equal(const Type& rOther) const { \
01006     if(&rOther==this) return true; \
01007     if(typeid(rOther) != typeid(*this)) return false; \
01008     const ctype* csattr=dynamic_cast<const ctype*>(&rOther);  \
01009     if(!csattr) return false; \
01010     if(!this->DoEqual(*csattr)) return false;   \
01011     return true;} \
01012   ctemp bool ctype::operator==(const ctype& rOther) const { return this->DoEqual(rOther); } \
01013   ctemp bool ctype::operator!=(const ctype& rOther) const { return !this->DoEqual(rOther); } 
01014 
01015 
01016 /** faudes type implementation macros, overall, debug version */
01017 /*
01018 #define FAUDES_TYPE_IMPLEMENTATION(ctype,cbase,ctemp) \
01019   ctemp ctype* ctype::New(void) const {     \
01020     return new ctype(); }  \
01021   ctemp const ctype* ctype::Cast(const Type* pOther) const { \
01022     return dynamic_cast<const ctype*>(pOther);} \
01023   ctemp ctype& ctype::Assign(const Type& rSrc) { \
01024     FD_WARN("RTI "<< typeid(ctype).name() << "::ASSIGN() V: " << typeid(*this).name() << \
01025       " from " << typeid(rSrc).name()); \
01026     if(const ctype* csattr=dynamic_cast<const ctype*>(&rSrc)) { this->Clear(); return DoAssign(*csattr);} \
01027     cbase::Assign(rSrc); \
01028     return *this;} \
01029   ctemp ctype& ctype::operator=(const ctype& rSrc) { \
01030     FD_WARN("RTI "<< typeid(ctype).name() << "::ASSIGN() O: " << typeid(*this).name() << \
01031       " from " << typeid(rSrc).name()); \
01032     this->Clear(); \
01033     return DoAssign(rSrc); }
01034 */
01035 
01036 
01037 
01038 /**
01039  * Structure to hold documentation data relating to a faudes-type or -function. 
01040  * This class is the common base for faudes::TypeDefinition and faudes::FunctionDefinition. 
01041  * It supports token io as demonstrated by the follwoing example for a type defintion:
01042  *
01043  * @code
01044  *  <TypeDefinition name="CoreFaudes::Generator" ctype="faudes::Generator">
01045  *
01046  *  <Documentation ref="generators.html#plain"> 
01047  *      The common 5 tuple G=(Sigma, Q, delta, Qo, Qm).
01048  *  <Documentation/>
01049  *
01050  *  <Keywords> "generator" "language" </Keywords>
01051  *
01052  *  </TypeDefinition>
01053  * @endcode
01054  *
01055  * Technical detail: Documentation is derived from Type for the purpose of token IO. We
01056  * still implement the faudes type interface to make it a fully qualified faudes data type.
01057  *
01058  * Technical detail: To facilitate inheritance, token io of member data and token io of
01059  * the section tags is separated.
01060  */
01061 
01062 class Documentation : public Type {
01063 
01064   // std faudes type interface
01065   FAUDES_TYPE_DECLARATION(Void,Documentation,Type)
01066   
01067 public:
01068   /** Constructor */
01069   Documentation(void);
01070 
01071   /** Copy constructor */
01072   Documentation(const Documentation& rOther);
01073 
01074   /** Destructor */
01075   virtual ~Documentation(void){};
01076 
01077   /**
01078    * Clear 
01079    */
01080   void Clear(void);
01081 
01082   /**
01083    * Get name of the entety to document (aka faudes-type or faudes-function).
01084    *
01085    * @return
01086    *  Name
01087    */
01088   const std::string& Name(void) const;
01089 
01090   /**
01091    * Get name of plugin.
01092    * The plugin name defaults to CoreFaudes.
01093    *
01094    * @return
01095    *  Name
01096    */
01097   const std::string& PlugIn(void) const;
01098 
01099   /**
01100    * Get corresponding C++ type
01101    *
01102    * @return
01103    *  CType, or "" if no such
01104    */
01105   const std::string& CType(void) const;
01106 
01107   /**
01108    * @return
01109    *  Short textual documentation.
01110    */
01111   const std::string& TextDoc(void) const;
01112 
01113   /**
01114    * @return
01115    *  Filename pointing to the html documentation.
01116    */
01117   const std::string& HtmlDoc(void) const;
01118 
01119   /**
01120    * @return
01121    *  CSV-string containing keywords.
01122    */
01123   const std::string& Keywords(void) const;
01124 
01125   /**
01126    * Search comma-seperated keywords for a substring. This should be
01127    * extended to regular expressions in a future release.
01128    *
01129    * @param rPattern
01130    *  String-pattern.
01131    *
01132    * @return
01133    *  Matching keyword or "" if no match
01134    */
01135   std::string MatchKeyword(const std::string& rPattern) const;
01136 
01137   /**
01138    * Not implemented
01139    * @return
01140    *  Number of keywords.
01141    */
01142   int KeywordsSize(void) const;
01143 
01144   /**
01145    * @param pos
01146    *   Position of keyword
01147    * @return
01148    *  Keyword at specified position (or "" if pos out of range)
01149    */
01150   std::string KeywordAt(int pos) const;
01151 
01152   /**
01153    * Get auto-register flag.
01154    *
01155    * This flag indicated that the respective type  was (will be)
01156    * registered by a libFAUDES static initialisation protorype.
01157    *
01158    * @return
01159    *  True <> C++-automatic-registration
01160    */
01161   bool AutoRegistered(void) const;
01162 
01163   /**
01164    * Get application-registered flag.
01165    *
01166    * @return
01167    *  True <> registered by application
01168    */
01169   bool ApplicationRegistered(void) const;
01170 
01171   /**
01172    * Merge documentation from token stream.
01173    * An exception is thrown if the current type name differs from the one in the documentation.
01174    *
01175    * @param rTr
01176    *  TokenReader to read from.
01177    *
01178    * @exception Exception
01179    *  - Type mismatch (id )
01180    *  - Token mismatch (id 50, 51, 52)
01181    *  - IO Error (id 1)
01182    */
01183   virtual void MergeDocumentation(TokenReader& rTr);
01184 
01185 
01186 
01187  protected:
01188 
01189   /**
01190    * Set name.
01191    *
01192    * @param name
01193    *  New name.
01194    */
01195   void Name(const std::string& name);
01196 
01197   /**
01198    * Set name of plugin
01199    *
01200    * @param plugin
01201    *  New name.
01202    */
01203   void PlugIn(const std::string& plugin);
01204 
01205   /**
01206    * Set C++ type
01207    *
01208    * @param name
01209    *  New ctype.
01210    */
01211   void CType(const std::string& name);
01212 
01213   /**
01214    * Set a short textual documentation.
01215    *
01216    * @param textdoc
01217    *  New textual documentation.
01218    */
01219   void TextDoc(const std::string& textdoc);
01220 
01221   /**
01222    * Set auto-register flag.
01223    * 
01224    * See also AutoRegistered(void)
01225    *
01226    * @param flag
01227    *  Flag value.
01228    */
01229   void AutoRegistered(bool flag);
01230 
01231   /**
01232    * Set application-registered flag.
01233    * 
01234    * See also AutoRegistered(void)
01235    *
01236    * @param flag
01237    *  Flag value.
01238    */
01239   void ApplicationRegistered(bool flag);
01240 
01241   /**
01242    * Set name of file pointing to the html documentation.
01243    *
01244    * @param fname
01245    *  Filename
01246    */
01247   void HtmlDoc(const std::string& fname);
01248 
01249   /**
01250    * Append keyword.
01251    *
01252    * @param rKeyword
01253    *  Keyword
01254    */
01255   void AddKeyword(const std::string& rKeyword);
01256 
01257   /**
01258    * Std faudes type interface: assignment.
01259    *
01260    * @param rSrc 
01261    *    Source to copy from
01262    * @return Reference to this object.
01263    */
01264   virtual void DoAssign(const Documentation& rSrc);
01265 
01266   /**
01267    * Std faudes type interface: test equality
01268    * 
01269    * @param rOther 
01270    *    Other object to compare with.
01271    * @return 
01272    *   True on match.
01273    */
01274   virtual bool DoEqual(const Documentation& rOther) const;
01275 
01276   /**
01277    * Read configuration data of this object from TokenReader.
01278    *
01279    * This virtual function reads documentation from a token stream. 
01280    * The section defaults to Documentation. It invokes DoReadCore to
01281    * do the member data token reading. 
01282    *
01283    * @param rTr
01284    *   TokenReader to read from
01285    * @param rLabel
01286    *   Section to read
01287    * @param pContext
01288    *   Read context to provide contextual information (ignored)
01289    *
01290    * @exception Exception
01291    *  - Token mismatch (id 50, 51, 52)
01292    *  - IO Error (id 1)
01293    */
01294   virtual void DoRead(TokenReader& rTr,  const std::string& rLabel = "", const Type* pContext=0);
01295  
01296   /**
01297    * Read configuration data of this object from TokenReader.
01298    *
01299    * This virtual function reads documentation member data only. 
01300    * It does NOT read the enclosing begin and end tokens.
01301    *
01302    * @param rTr
01303    *   TokenReader to read from
01304    *
01305    * @exception Exception
01306    *  - Token mismatch (id 50, 51, 52)
01307    *  - IO Error (id 1)
01308    */
01309   virtual void DoReadCore(TokenReader& rTr);
01310  
01311 
01312 
01313   /**
01314    * Write configuration data of this object to TokenWriter.
01315    *
01316    * This virtual function writes documentation to a token stream. 
01317    * The section defaults to Documentation. It invokes DoWriteCore to
01318    * do the actual member data writing. 
01319    *
01320    * @param rTw
01321    *   Reference to TokenWriter
01322    * @param rLabel
01323    *   Label of section to write
01324    * @param pContext
01325    *   Write context to provide contextual information
01326    *
01327    * @exception Exception 
01328    *   - IO errors (id 2)
01329    */
01330   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
01331 
01332 
01333   /**
01334    * Write configuration data of this object to TokenWriter.
01335    *
01336    * This virtual function reads documentation members only. 
01337    * It does NOT write enclosing begin and end tokens.
01338    *
01339    * @param rTw
01340    *   Reference to TokenWriter
01341    *
01342    * @exception Exception 
01343    *   - IO errors (id 2)
01344    */
01345   virtual void DoWriteCore(TokenWriter& rTw) const;
01346 
01347 
01348   /** Faudes name. */
01349   std::string mName;
01350 
01351   /** Faudes plugin. */
01352   std::string mPlugIn;
01353 
01354   /** Corresponing C++ type, or "" if no such. */
01355   std::string mCType;
01356 
01357   /** String containing the text-documentation. */
01358   std::string mTextDoc;
01359 
01360   /** String containing the filename of the corresponding html-documentation. */
01361   std::string mHtmlDoc;
01362 
01363   /** Comma-seperated string containing all keywords. */
01364   std::string mKeywords;
01365 
01366   /** Constant characted used to seperate keywords */
01367   static const char mDelim = ';';
01368 
01369   /** Flag to indicate automated registration */
01370   bool mAutoRegistered;
01371 
01372   /** Flag to indicate application registration */
01373   bool mApplicationRegistered;
01374 
01375 }; // Documentation
01376 
01377 
01378 
01379 /**
01380  * A TypeDefinition defines a faudes-type in that it specifies
01381  * a faudes-type name to identify the type and a method
01382  * NewObject() to instantiate objects of the respective type. 
01383  * In this sense, TypeDefinition is a so called factory class.
01384  * Technically, the TypeDefinition holds one instance of the faude type,
01385  * the so called prototype object, and NewObject() invokes the New() method
01386  * of the prototype. Notebly, there is only one class TypeDefinition that by
01387  * parametrisation defins all derivates of Type.
01388  * 
01389  * TypeDefinition is derived from faudes::Documentation and therefore additional
01390  * documentation-data can be associated.
01391  *
01392  *
01393  * @ingroup RunTimeInterface
01394  */
01395 
01396 class TypeDefinition : public Documentation {
01397 
01398  // std faudes type interface
01399  FAUDES_TYPE_DECLARATION(Void,TypeDefinition,Documentation)
01400 
01401  // regisry is friend to set protected values
01402  friend class TypeRegistry;
01403 
01404  public:
01405 
01406   /** 
01407    * Constructor 
01408    *
01409    * The default constructor instantiates an invalid type definition
01410    * without prototype. To construct
01411    * a valid type definition, use the static Constructor() template
01412    * function.
01413    */
01414   TypeDefinition(const std::string& name="") : Documentation(), mpType(NULL) {Name(name);};
01415 
01416   /**
01417    * Destructor.
01418    *
01419    * Delete prototype object.
01420    */
01421   virtual ~TypeDefinition(void){ Prototype(NULL); };
01422 
01423   /**
01424    * Construct empty TypeDefinition object.
01425    * The given template parameter denotes any libFAUDES class derived from faudes::Type
01426    * A new instance of this class is assigned to member variable (pType)
01427    * whereas the name is set as specified.
01428    *
01429    * @tparam T
01430    *   Actual c class, derived from Type
01431    * @param rTypeName
01432    *   Name to identify this faudes-type<; defaults to the plattform
01433    *   dependand typeid from the c++ runtime type information system.
01434    * @return
01435    *   Newly constructed type definition.
01436    *
01437    */
01438   template<class T>
01439   static TypeDefinition* Constructor(const std::string& rTypeName="");
01440 
01441   /**
01442    * Construct empty TypeDefinition object.
01443    * The given prototype is assigned to the member variable pType,
01444    *
01445    * @param pProto
01446    *   Prototype, derived from Type
01447    * @param rTypeName
01448    *   Name to identify this faudes-type<; defaults to the plattform
01449    *   dependand typeid from the c++ runtime type information system.
01450    * @return
01451    *   Newly constructed type definition.
01452    *
01453    */
01454   static TypeDefinition* Constructor(Type* pProto, const std::string& rTypeName="");
01455 
01456   /**
01457    * Construct TypeDefinition object and read name and
01458    * documentation-data from TokenReader.
01459    *
01460    * @tparam T
01461    *   Actual c class, derived from Type
01462    * @param rFileName
01463    *   Name of file to read.
01464    * @return
01465    *   Newly constructed type definition.
01466    *
01467    * @exception Exception
01468    *  - Token mismatch (id 50, 51, 52)
01469    *  - IO Error (id 1)
01470    */
01471   template<class T>
01472   static TypeDefinition* FromFile(const std::string& rFileName);
01473 
01474 
01475   /**
01476    * Return pointer to faudes-object prototype 
01477    *
01478    * Note: this method is meant for inspection only, control over
01479    * the prototype remains with the TypeDefinition. Use
01480    * NewObject() to instantiate a new faudes-object.
01481    *
01482    * @return
01483    *   Reference to prototype object
01484    */
01485   const Type* Prototype(void) const;
01486 
01487 
01488   /**
01489    * Construct faudes-object on heap.
01490    * Return pointer to new instance of assigned Type class.
01491    *
01492    * Note: If no prototype is installed, NULL is returned.
01493    *
01494    * @return
01495    *  Pointer to new Type instance.
01496    */
01497   Type* NewObject(void) const;
01498 
01499 
01500   /** 
01501    * Parameter access: Xml Element Tag
01502    *
01503    * This parameter is used for Xml IO of sets and vectors. It determines
01504    * the tag to used for individual elments.
01505    *
01506    * @return
01507    *   Tag parameter.
01508    */
01509   const std::string& XElementTag(void) const; 
01510 
01511   /** 
01512    * Parameter access: Xml Element Tag
01513    *
01514    * @param rTag
01515    *   New tag parameter
01516    */
01517   void XElementTag(const std::string& rTag); 
01518 
01519 protected:
01520 
01521 
01522   /**
01523    * Std faudes type interface: assignment.
01524    *
01525    * @param rSrc 
01526    *    Source to copy from
01527    * @return Reference to this object.
01528    */
01529   virtual void DoAssign(const TypeDefinition& rSrc);
01530 
01531   /**
01532    * Std faudes type interface: test equality
01533    * 
01534    * @param rOther 
01535    *    Other object to compare with.
01536    * @return 
01537    *   True on match.
01538    */
01539   virtual bool DoEqual(const TypeDefinition& rOther) const;
01540 
01541   /** Disable copy constructor */
01542  TypeDefinition(const TypeDefinition& rOther) : Documentation(rOther) {}; // todo: implement ?? for stl maps ?
01543 
01544   /**
01545    * Clear documentation-data; do *NOT* delete prototype  (this is for using Read to 
01546    * merge/overwrite documentation)
01547    */
01548   void Clear(void);
01549 
01550   /**
01551    * Use given object as prototype.
01552    *
01553    * The TypeDefinition takes ownership of the
01554    * provided object.
01555    *
01556    * @param pType
01557    *  Any class that inherits Type.
01558    */
01559   virtual void Prototype(Type* pType);
01560 
01561   /**
01562    * Read configuration data of this object from TokenReader.
01563    *
01564    * The section defaults to "TypeDefinition", context ignored.
01565    * Actual reading is done by DoReadCore.
01566    *
01567    * @param rTr
01568    *   TokenReader to read from
01569    * @param rLabel
01570    *   Section to read
01571    * @param pContext
01572    *   Read context to provide contextual information (ignored)
01573    *
01574    * @exception Exception
01575    *   - Token mismatch (id 50, 51, 52)
01576    *   - IO error (id 1)
01577    */
01578   virtual void DoRead(TokenReader& rTr,  const std::string& rLabel = "", const Type* pContext=0);
01579  
01580   /**
01581    * Read configuration data of this object from TokenReader.
01582    *
01583    * This method reads members only, it does not read the section.
01584    *
01585    * @param rTr
01586    *   TokenReader to read from
01587    *
01588    * @exception Exception
01589    *   - Token mismatch (id 50, 51, 52)
01590    *   - IO error (id 1)
01591    */
01592   virtual void DoReadCore(TokenReader& rTr);
01593  
01594   /**
01595    * Write configuration data of this object to TokenWriter.
01596    *
01597    * The section defaults to "TypeDefinition", context ignored.
01598    * Actual writing is done by DoWriteCore.
01599    *
01600    * @param rTw
01601    *   Reference to TokenWriter
01602    * @param rLabel
01603    *   Label of section to write
01604    * @param pContext
01605    *   Write context to provide contextual information
01606    *
01607    * @exception Exception 
01608    *   - IO errors (id 2)
01609    */
01610   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
01611 
01612   /**
01613    * Write configuration data of this object to TokenWriter.
01614    *
01615    * This method wrtite plain member data, the section lables are not
01616    * written.
01617    *
01618    * @param rTw
01619    *   Reference to TokenWriter
01620    *
01621    * @exception Exception 
01622    *   - IO errors (id 2)
01623    */
01624   virtual void DoWriteCore(TokenWriter& rTw) const;
01625 
01626   /** Type-pointer tp prototype instance */
01627   Type* mpType;
01628 
01629   /** Extra documentation/parameter: Xml Element Tag */
01630   std::string mXElementTag;
01631 
01632 }; //TypeDefinition
01633 
01634 
01635 
01636 
01637 /**********************************************************************************************
01638 ***********************************************************************************************
01639 ***********************************************************************************************
01640 
01641 Implemention of template members functions
01642 
01643 ***********************************************************************************************
01644 ***********************************************************************************************
01645 **********************************************************************************************/
01646 
01647 
01648 // Typedefinition constructor function
01649 template<class T>
01650 TypeDefinition* TypeDefinition::Constructor(const std::string& rTypeName){
01651   FD_DRTI("TypeDefinition::Construct<" << typeid(T).name() << ">(" << rTypeName << ")");
01652   return Constructor(new T, rTypeName);
01653 }
01654 
01655 
01656 // Type definition constructor function
01657 template<class T>
01658 TypeDefinition* TypeDefinition::FromFile(const std::string& rFileName){
01659   FD_DRTI("TypeDefinition::FromFile<" << typeid(T).name() << ">()");
01660   // construct with fallback name
01661   TypeDefinition* td = Constructor<T>();
01662   // read docu, incl actual name
01663   td->Read(rFileName);
01664   // done
01665   return(td);
01666 }
01667 
01668 
01669 
01670 
01671 
01672 } // namespace
01673 
01674 #endif /* FAUDES_RTITYPES_H */

libFAUDES 2.23h --- 2014.04.03 --- c++ api documentaion by doxygen