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="../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 |