|
libFAUDES
Sections
Index
|
cfl_types.hGo 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