cfl_types.h
Go to the documentation of this file.
1 /** @file cfl_types.h Runtime interface, faudes types */
2 
3 /* FAU Discrete Event Systems Library (libfaudes)
4 
5 Copyright (C) 2009 Ruediger Berndt
6 Copyright (C) 2010 Thomas Moor
7 
8 This library is free software; you can redistribute it and/or
9 modify it under the terms of the GNU Lesser General Public
10 License as published by the Free Software Foundation; either
11 version 2.1 of the License, or (at your option) any later version.
12 
13 This library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Lesser General Public License for more details.
17 
18 You should have received a copy of the GNU Lesser General Public
19 License along with this library; if not, write to the Free Software
20 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
21 
22 
23 #ifndef FAUDES_RTITYPES_H
24 #define FAUDES_RTITYPES_H
25 
26 #include <list>
27 #include <string>
28 #include <vector>
29 #include <map>
30 #include <utility>
31 #include <string>
32 #include <iostream>
33 #include <typeinfo>
34 #include <algorithm>
35 
36 #include "cfl_definitions.h"
37 #include "cfl_token.h"
38 #include "cfl_tokenreader.h"
39 #include "cfl_tokenwriter.h"
40 #include "cfl_exception.h"
41 
42 
43 
44 namespace faudes {
45 
46 
47 /************************************************
48  ************************************************
49  ************************************************/
50 
51 
52 /** @defgroup RunTimeInterface Run-Time Interface
53 
54 The libFAUDES run-time interface (RTI) facilitates the development
55 of applications that are transparent to libFAUDES extensions, e.g.,
56 the libFAUDES version of the Lua interpreter luafaudes and the
57 graphical user interface DESTool.
58 
59 The run-time interface provides a TypeRegistry for the application
60 to instantiate objects by specifying their type as a std::string.
61 The TypeRegistry is accompanied by the FunctionRegistry for
62 the application to execute functions by their name. Thus, a libFAUDES
63 application can query both registries and provide the
64 supported types and functions to the user.
65 The <a href="../reference/index.html">libFAUDES user-reference</a>
66 is set up by the build system to represent the contents of both
67 registries.
68 
69 The run-time interface is implemented
70 by the following components:
71 - base class faudes::Type for RTI enabled classes (faudes-types)
72 - documentation class faudes::TypeDefinition to accompany faudes-types;
73 - container class faudes::TypeRegistry to hold faudes::TypeDefintiion objects;
74 - base class faudes::Function for RTI enabled function wrappers (faudes-functions);
75 - documentation class faudes::FunctionDefinition to accompany faudes-functions;
76 - container class faudes::FunctionRegistry to hold FunctionDefintiion objects.
77 
78 @section RunTimeInterfaceSec2 Faudes-Types
79 
80 Classes that participate in the run-time interface are referred to
81 as faudes-types, instances are so called faudes-objects. Any faudes-type must
82 be derived from the base class faudes::Type. A faudes-type inherits
83 the convenience interface for token IO from Type, and, most relevent for the run-time
84 interface, the factory function New(): each faudes-types must reimplement New()
85 to allocate a new object of their respective type on heap. For a fully functional
86 faudes-type, also an appropriate assignment operator and a copy constructor
87 are required.
88 
89 
90 @section RunTimeInterfaceSec3 Faudes-Type Definitions
91 
92 A faudes-type is accompanied by an instance of faudes::TypeDefinition. It holds
93 a name (std::string) to identify the faudes-type,
94 documentation (short text and html reference),
95 and one faudes-object of the respective faudes-type.
96 The latter is referred to as the prototype object and its New() method is used to construct
97 new faudes-objects of the respective faudes-type. Thus, given a TypeDefinition,
98 one can instantiate a corresponding faudes-object. To setup a
99 TypeDefinition, you are meant to provide the faudes-type name, the protototype
100 and a file from which to read the documentation.
101 
102 
103 @section RunTimeInterfaceSec4 Faudes-Functions and Faudes-Function Definitions
104 
105 Functions that participate in the run-time interface are organized similar
106 to faudes-types. There is a base class faudes::Function from which to derive
107 particular faudes-functions. The base class provides an interface to set
108 function parameter values and to actually execute the function on the parameters.
109 To derive a class from Function, you must reimplement the methods New(), DoTypeCheck(),
110 and DoExecute(). The DoTypeCheck method is supposed to use a dynamic cast
111 to initialize typed references to the function parameters. The DoExecute method
112 then executes the function, typically by invoking a function via its
113 C++ API. Each Function class is accompanied by a faudes::FunctionDefinition instance
114 which holds a prototype, basic documentation and a list of valid signatures. Each signature
115 represents a valid parameter type configurations in terms of faudes-types.
116 
117 @section RunTimeInterfaceSec5 Type- and Function-Registry
118 
119 The faudes::TypeRegistry and the faudes::FunctionRegistry are containers for TypeDefinition
120 and FunctionDefinition instances, respectively. Applications access the registries via
121 faudes-type names and faudes-function names, see e.g. the global functions NewObject() and
122 NewFunction(). There is also in interface to iterate through the regsitries and
123 to test for the existence of an entry. However, while both registries inherit the std token-io
124 interface, neither registry can be fully configured by reading from file. This is because
125 each entry requires not only data (documentation, signature, etc) but also a prototype
126 instance. The std C++ run-time type information (RTTI) does not provide a mechanism
127 to instantiate an object of a class that is specified at runtime. Thus, each protototype
128 must be defined at compiletime. The global function LoadRegistry() is automatically
129 set-up by the build system to gather all relevant prototypes, insert them in the
130 registries and to subsequently read further documentation from a configuration
131 file.
132 
133 @section RunTimeInterfaceSec6 RTI and the Build System
134 
135 At stage <tt>make configure</tt>, the build system sets up the function LoadRegistry()
136 by
137 - setting the macro FAUDES_PLUGINS_RTILOAD to a list of function calls in order to invoke
138  one load function per plugin;
139 - running the tool <tt>rti2code</tt> to generate c code to register faudes-types and-functions
140  found in the configuration file ("libfaudes.rti").
141 
142 Code generation should work for all types and functions with documentation entry "CType()" specified.
143 Since there is only one CType() entry, all signatures of a function must be implemented by a single
144 c-function. The generated code is placed at "./include/rtiautoload.*". The build system also provides
145 support to merge the configuration "libfaudes.rti" file from various sources, incl. plugins.
146 
147 To have your C++ class participate in the libFAUDES run-time interface:
148 
149 -# derive your class from faudes::Type;
150 -# make sure your class has a public default constructor and a public copy constructor;
151 -# use the provided macros to reimplement the virtual functions FType(), New(), Copy(), Cast(),
152  Assign(), Equal(), and the acording operators =, == and !=;
153 -# reimplement the virtual functions DoAssign(), DoEqual(), DoRead(), DoWrite() and Clear();
154 -# optionally, reimplement the alternative output formats DoDWrite(), DoSWrite(), DoXWrite()
155 -# provide an .rti file for the formal TypeDefinition;
156 -# supplement your .rti file by an html formated documentation text;
157 
158 You will need to inspect and edit the main Makefile or your plugin's Makefile
159 to advertise your additional sources. A <tt>make configure</tt> will then
160 assemble all the bits and pieces.
161 
162 To have your C++ function participate in the libFAUDES run-time interface:
163 
164 -# make sure all your parameters are faudes-types (exceptions being
165  the elementary types bool, string and integer, which are converted automatically);
166 -# provide an .rti file for the formal FunctionDefinition, advertise this file;
167  either in the main Makefile or in the Makefile of your plugin;
168 -# supplement yout .rti file by an html formated documentation text;
169 
170 
171 */
172 
173 // forward
174 class TypeDefinition;
175 
176 /**
177  * Base class of all libFAUDES objects that participate in
178  * the run-time interface. Eg, generator, alphabet, attributes etc.
179  * The class is designed to impose as little overhead as possible, and
180  * hence, does not hold any data. It does, however, provide a
181  * uniform interface for assignment, factory functions, and token IO.
182  *
183  * We think of a faudes-typed object to be configured by defining
184  * data and, in due course, manipulated via its public interface
185  * by faudes-functions. Any faudes-type must provide a Clear() method that
186  * resets the object configuration to a unique default value.
187  * It is the configuration data that can be read from and written to token
188  * streams, and it is the configuration data that is used for assigments.
189  * Any additional data a faudes-typed object may host, is ignored by the
190  * interface inherited from the the base faudes::Type. Examples for such
191  * additional data is the unique id of a Generator, and the deferred copy
192  * pointers in faudes sets derived from faudes::TBaseSet.
193  *
194  * The faudes::Type assignment semantics are not meant to create exact copies
195  * of a given source object. Thogether with the uniquely defined default value,
196  * we can have assignments by both up- and downcasts. A faudes::Generator can be
197  * assigned from the derived faudes::System (a Generator with controllability
198  * attributes) by dropping the extra features. Vice versa, when a System is assigned
199  * from a plain Generator, any extra features take their respective default values.
200  * This relaxed interpretation of assignments is implemented by the method
201  * Assign(). The token format for file IO is organised in a similar fashion: any generator
202  * derivate can be configured from the token stream produced by any other generator class.
203  * In contrast, faudes-typed objects also implement an assignment operator
204  * that uses the standard C++ conventions.
205  *
206  * The following methods are used to implement the faudes::Type interface:
207  *
208  * - DoRead() to read the defining data from a token stream
209  * - DoWrite() to write the defining data to a token stream
210  * - DoXWrite() to write the defining data to a token stream in an alternative XML format
211  * - DoSWrite() and DoDWrite for alternative output formats (statistical summary and debugging)
212  *
213  * - Name() to get/set the name of an optional (and purely cosmetic) object name
214  * - Clear() to reset all configuration data,
215  * - New() to construct an object of identical type on heap (factory method),
216  * - Copy() to construct an object of identical type and configuration on heap (factory method),
217  * - Cast() to dynamically cast another object to this type (type check method)
218  * - Assign() to do an assignment from any castable Type derivate
219  * - DoAssign(), or the operator "=", to assign from an object with identical type.
220  * - Equal() to test relaxed equality with any castable Type derivate
221  * - DoEqual(), or the operators "==" and "!=", to test exact equality of configuration data
222  *
223  * In most cases, only DoRead(), DoWrite(), DoAssign(), DoEqual() and Clear() need to be implemented
224  * manualy. The other methods can be declared and implemented by macros
225  * FAUDES_TYPE_DELARATION and FAUDES_TYPE_IMPLEMENTATION, respectively. The various
226  * attribute classes illustrate their ussage; see e.g. AttributeFlags.
227  *
228  *
229  * Note on token IO: In libFAUDES 2.16e, implementation of a new file format is prepared
230  * by the virtual function interface DoXWrite(). The intention is to better support advanced
231  * XML editors, in particular for configuration files. When implementing DoXWrite() for a
232  * derived class, make sure that DoRead() will gracefully accept tokens written by both DoWrite()
233  * and DoXWrite(), as a basis for a fileformat conversion tool. Future versions of libFAUDES will drop
234  * compatibility with the old token format, except for model data (generators, alphabets).
235  *
236  * @ingroup RunTimeInterface
237  */
238 
239 class Type {
240 
241  public:
242 
243  /** Constructor */
244  Type(void);
245 
246  /** Copy constructor */
247  Type(const Type& rType);
248 
249  /** Destructor */
250  virtual ~Type(void);
251 
252  /**
253  * Construct on heap.
254  * Technically not a constructor, this function creates an object with the
255  * same type Type. New() is defined as a virtual function and derived
256  * classes are meant to re-implement with the appropiate constructor.
257  * This can be done via the provided macros FAUDES_TYPE_DECLARATION and
258  * FAUDES_TYPE_IMPLEMENTATION.
259  * As with new, it is the callers reponsabilty to delete the object when no longer needed.
260  *
261  * @return
262  * Pointer to new Type object
263  */
264  virtual Type* New(void) const;
265 
266  /**
267  * Construct on heap.
268  * Technically not a constructor, this function creates an object with the
269  * same type Type and the same configuration. Copy() is defined as a virtual function and derived
270  * classes are meant to re-implement with the appropiate copy constructor.
271  * This can be done via the provided macros FAUDES_TYPE_DECLARATION and
272  * FAUDES_TYPE_IMPLEMENTATION.
273  * As with new, it is the callers reponsabilty to delete the object when no longer needed.
274  *
275  * @return
276  * Pointer to new Type object
277  */
278  virtual Type* Copy(void) const;
279 
280  /**
281  * Cast other object to this type.
282  * Enables the run-time interface to test whether pObject is derived
283  * from this object. This feature is used e.g. in the faudes container
284  * classes to test attributes. Derived classes must reimplement this
285  * function using the appropriate dynamic cast.
286  *
287  * Re-implementation can be done via the convenience macros
288  * FAUDES_TYPE_DECLARATION and FAUDES_TYPE_IMPLEMENTATION.
289  *
290  * @return
291  * Typed pointer object
292  */
293  virtual const Type* Cast(const Type* pOther) const;
294 
295  /**
296  * Clear configuration data. Derived classes should re-implement this
297  * method to ensure some consistent configuration data.
298  */
299  virtual void Clear(void);
300 
301  /**
302  * Assign configuration data from other object.
303  * Derived classes should reimplement this method to first try to cast
304  * the source to the respective class. If successful, the protected
305  * function DoAssign is invoked to perform the actual assignment. If the cast fails,
306  * the Assign method of the parent class is called. Thus, faudes
307  * objects are up- and downcatsed for assignment, maintaining as much of
308  * the source data as digestable by the destination object. On the downside,
309  * there is no sensible typechecking at compile-time.
310  *
311  * Re-implementation can be done via the convenience macros
312  * FAUDES_TYPE_DECLARATION and FAUDES_TYPE_IMPLEMENTATION.
313  *
314  * @param rSrc
315  * Source to copy from
316  * @return Reference to this object.
317  */
318  virtual Type& Assign(const Type& rSrc);
319 
320 
321  /**
322  * Assign configurationdata from other object.
323  * Derived classes should implement the operator form for the assignment
324  * for each source type which allows for a non-trivial assignment. This includes
325  * the particular case were the source and destination types match exactly. In the
326  * latter case the DoAssign method should be invoked. In contrast to
327  * the Assign function, the operator form must not be reimplemented for
328  * missmatched source types: the operator form only accepts sensible source types.
329  * This allows for compiletime typeckecking. However, the downside is that
330  * when the type is not known at compiletime, configuration is not properly
331  * assigned.
332  *
333  * Re-implementation can be done via the convenience macros
334  * FAUDES_TYPE_DECLARATION and FAUDES_TYPE_IMPLEMENTATION.
335  *
336  * @param rSrc
337  * Source to copy from
338  * @return Reference to this object.
339  */
340  virtual Type& operator=(const Type& rSrc);
341 
342  /**
343  * Test equality of configuration data.
344  * Derived classes should reimplement this method to return true
345  * if both actual types and configuration data match.
346  * The object name or id (if any) is not considered in the test.
347  *
348  * This method calls the virtual method DoEqual(). Re-implementation can
349  * be done via the convenience macros
350  * FAUDES_TYPE_DECLARATION and FAUDES_TYPE_IMPLEMENTATION.
351  *
352  * @param rOther
353  * Other object to compare with.
354  * @return
355  * True on match.
356  */
357  virtual bool Equal(const Type& rOther) const;
358 
359  /**
360  * Test equality of configuration data.
361  * The operator form of the equality test is only defined for matching
362  * types, no cast will be performed. Thus, the test will be optimistic
363  * if the type is not known at compiletime.
364  * The object name or id is not considered in the test.
365  *
366  * This methoc calls the virtual method DoEqual(). Re-implementation can
367  * be done via the convenience macros
368  * FAUDES_TYPE_DECLARATION and FAUDES_TYPE_IMPLEMENTATION.
369  *
370  * @param rOther
371  * Other object to compare with.
372  * @return
373  * True on match.
374  */
375  virtual bool operator==(const Type& rOther) const;
376 
377 
378  /**
379  * Test equality of configuration data.
380  * See operator==(const Type&).
381  *
382  * This method calls the virtual method DoEqual(). Re-implementation can
383  * be done via the convenience macros
384  * FAUDES_TYPE_DECLARATION and FAUDES_TYPE_IMPLEMENTATION.
385  *
386  * @param rOther
387  * Other objevt to compare with.
388  * @return
389  * True on mismatch.
390  */
391  virtual bool operator!=(const Type& rOther) const;
392 
393 
394  /**
395  * Set the objects's name.
396  *
397  * The base class Type does not implement an object name,
398  * derivatives usually do so, except for attributes.
399  *
400  * @param rName
401  * Name
402  */
403  virtual void Name(const std::string& rName);
404 
405  /**
406  * Get objects's name.
407  *
408  * The base class Type does not implement an object name,
409  * derivatives usually do so, except for attributes.
410  * @return
411  * Name of generator
412  */
413  virtual const std::string& Name(void) const;
414 
415  /**
416  * Write configuration data to console.
417  * Note: this write function uses the virtual function DoWrite(), to be
418  * reimplemented by derived classes.
419  *
420  * @param pContext
421  * Write context to provide contextual information
422  *
423  */
424  void Write(const Type* pContext=0) const;
425 
426  /**
427  * Write configuration data to a file.
428  * Note: this write function uses the virtual function DoWrite(), to be
429  * reimplemented by derived classes.
430  *
431  * @param pFileName
432  * Name of file
433  * @param rLabel
434  * Label of section to write
435  * @param pContext
436  * Write context to provide contextual information
437  * @param openmode
438  * ios::openmode
439  *
440  * @exception Exception
441  * - IO errors (id 2)
442  */
443  void Write(const std::string& pFileName, const std::string& rLabel="",
444  const Type* pContext=0, std::ios::openmode openmode = std::ios::out|std::ios::trunc) const;
445 
446  /**
447  * Write configuration data to a file.
448  * Note: this write function uses the virtual function DoWrite(), to be
449  * reimplemented by derived classes.
450  *
451  * @param pFileName
452  * Name of file
453  * @param openmode
454  * ios::openmode
455  *
456  * @exception Exception
457  * - IO errors (id 2)
458  */
459  void Write(const std::string& pFileName, std::ios::openmode openmode) const;
460 
461  /**
462  * Write configuration data to TokenWriter.
463  * Note: this write function uses the virtual function DoWrite(), to be
464  * reimplemented by derived classes.
465  *
466  * @param rTw
467  * Reference to TokenWriter
468  * @param rLabel
469  * Label of section to write
470  * @param pContext
471  * Write context to provide contextual information
472  *
473  * @exception Exception
474  * - IO errors (id 2)
475  */
476  void Write(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
477 
478  /**
479  * Write configuration data to an XML file.
480  * Note: this method uses the faudes type to set a DOCTYPE markup; for derived classes
481  * which do not report their faudes type, you should reimplement this
482  * function. Actual token io is done via DoXWrite().
483  *
484  * @param pFileName
485  * Name of file
486  * @param rLabel
487  * Label of section to write
488  * @param pContext
489  * Write context to provide contextual information
490  *
491  * @exception Exception
492  * - IO errors (id 2)
493  */
494  virtual void XWrite(const std::string& pFileName, const std::string& rLabel="",
495  const Type* pContext=0) const;
496 
497  /**
498  * Write configuration data in XML format to concole
499  * Note: this write function uses the virtual function DoXWrite(), to be
500  * reimplemented by derived classes. No DOCTYPE markup will be written.
501  *
502  * @param pContext
503  * Write context to provide contextual information
504  *
505  */
506  void XWrite(const Type* pContext=0) const;
507 
508  /**
509  * Write configuration data in XML format to TokenWriter.
510  * Note: this write function uses the virtual function DoXWrite(), to be
511  * reimplemented by derived classes.
512  *
513  * @param rTw
514  * Reference to TokenWriter
515  * @param rLabel
516  * Label of section to write
517  * @param pContext
518  * Write context to provide contextual information
519  *
520  * @exception Exception
521  * - IO errors (id 2)
522  */
523  void XWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
524 
525  /**
526  * Write configuration data to a string.
527  * Note: this write function uses the virtual function DoWrite(), to be
528  * reimplemented by derived classes.
529  *
530  * @param rLabel
531  * Label of section to write
532  * @param pContext
533  * Write context to provide contextual information
534  * @return
535  * output string
536  * @exception Exception
537  * - IO errors (id 2)
538  */
539  std::string ToString(const std::string& rLabel="", const Type* pContext=0) const;
540 
541  /**
542  * Write configuration data to a formated string.
543  * In contrast to ToString, ToText does not suppress comments and
544  * End-Of-Line marks.
545  * Note: this write function uses the virtual function DoWrite(), to be
546  * reimplemented by derived classes.
547  *
548  * @param rLabel
549  * Label of section to write
550  * @param pContext
551  * Write context to provide contextual information
552  * @return
553  * output string
554  * @exception Exception
555  * - IO errors (id 2)
556  */
557  std::string ToText(const std::string& rLabel="", const Type* pContext=0) const;
558 
559  /**
560  * Write configuration data to console, debugging format.
561  * Note: this write function uses the virtual function DoDWrite(), to be
562  * reimplemented by derived classes.
563  *
564  * @param pContext
565  * Write context to provide contextual information
566  *
567  */
568  void DWrite(const Type* pContext=0) const;
569 
570  /**
571  * Write configuration data to a file, debugging format.
572  * Note: this write function uses the virtual function DoDWrite(), to be
573  * reimplemented by derived classes.
574  *
575  * @param pFileName
576  * Name of file
577  * @param rLabel
578  * Label of section to write
579  * @param pContext
580  * Write context to provide contextual information
581  * @param openmode
582  * ios::openmode
583  *
584  * @exception Exception
585  * - IO errors (id 2)
586  */
587  void DWrite(const std::string& pFileName, const std::string& rLabel="",
588  const Type* pContext=0, std::ios::openmode openmode = std::ios::out|std::ios::trunc) const;
589 
590  /**
591  * Write configuration data in debug format to TokenWriter.
592  * Note: this write function uses the virtual function DoWrite(), to be
593  * reimplemented by derived classes.
594  *
595  * @param rTw
596  * Reference to TokenWriter
597  * @param rLabel
598  * Label of section to write
599  * @param pContext
600  * Write context to provide contextual information
601  *
602  * @exception Exception
603  * - IO errors (id 2)
604  */
605  void DWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
606 
607  /**
608  * Write statistics comment to TokenWriter.
609  * Note: this write function use the virtual function DoSWrite(), to be
610  * reimplemented by derived classes.
611  *
612  * @param rTw
613  * Reference to TokenWriter
614  *
615  * @exception Exception
616  * - IO errors (id 2)
617  */
618  void SWrite(TokenWriter& rTw) const;
619 
620  /**
621  * Write statistics comment to console.
622  * Note: this write function uses the virtual function DoSWrite(), to be
623  * reimplemented by derived classes.
624  *
625  */
626  void SWrite(void) const;
627 
628  /**
629  * Write statistics to a string.
630  * Note: this write function uses the virtual function DoSWrite(), to be
631  * reimplemented by derived classes.
632  *
633  * @return
634  * output string
635  * @exception Exception
636  * - IO errors (id 2)
637  */
638  std::string ToSText(void) const;
639 
640  /**
641  * Read configuration data from file with label specified.
642  * Note: all read functions use the virtual function DoRead(), to be
643  * reimplemented for by derived classes.
644  *
645  * @param rFileName
646  * Name of file
647  * @param rLabel
648  * Section to read from
649  * @param pContext
650  * Read context to provide contextual information
651  *
652  * @exception Exception
653  * - IO errors (id 1)
654  * - token mismatch from DoRead()
655  */
656  void Read(const std::string& rFileName, const std::string& rLabel = "", const Type* pContext=0);
657 
658  /**
659  * Read configuration data from a string.
660  * Note: this read function uses the virtual function DoRead(), to be
661  * reimplemented by derived classes.
662  *
663  * @param rString
664  * String to read from
665  * @param rLabel
666  * Section to read
667  * @param pContext
668  * Read context to provide contextual information
669  * @exception Exception
670  * - IO errors (id 1)
671  * - token mismatch from DoRead()
672  */
673  void FromString(const std::string& rString, const std::string& rLabel="", const Type* pContext=0);
674 
675  /**
676  * Read configuration data from TokenReader with label sepcified.
677  * Note: all read functions use the virtual function DoRead(), to be
678  * reimplemented for by derived classes.
679  *
680  * @param rTr
681  * Reference to tokenreader
682  * @param rLabel
683  * Section to read
684  * @param pContext
685  * Read context to provide contextual information
686  *
687  * @exception Exception
688  * - IO errors (id 1)
689  * - token mismatch from DoRead()
690  */
691  void Read(TokenReader& rTr, const std::string& rLabel = "", const Type* pContext=0);
692 
693 
694  protected:
695 
696  /**
697  * Assign configuration data from other object.
698  *
699  * Reimplement this function to copy all configuration data from
700  * another faudes object. Typically, you will first call the base class'
701  * DoAssign, which includes a Clear(). Then, you will set up any additional members.
702  *
703  * @param rSrc
704  * Source to copy from
705  */
706  virtual void DoAssign(const Type& rSrc);
707 
708  /**
709  * Test equality of configuration data.
710  * Derived classes should reimplement this method to compare all relevant
711  * configuration, except the name.
712  *
713  * @param rOther
714  * Other object to compare with.
715  * @return
716  * True on match.
717  */
718  virtual bool DoEqual(const Type& rOther) const;
719 
720 
721  /**
722  * Read configuration data of this object from TokenReader.
723  *
724  * Reimplement this method in derived classes to provide the std token io
725  * interface defined in the public section of Type.
726  *
727  * @param rTr
728  * TokenReader to read from
729  * @param rLabel
730  * Section to read
731  * @param pContext
732  * Read context to provide contextual information
733  *
734  * @exception Exception
735  * - IO error (id 1)
736  */
737  virtual void DoRead(TokenReader& rTr, const std::string& rLabel = "", const Type* pContext=0);
738 
739  /**
740  * Write configuration data of this object to TokenWriter.
741  *
742  * Reimplement this method in derived classes to provide the std token io
743  * interface defined in the public section of Type.
744  *
745  * @param rTw
746  * Reference to TokenWriter
747  * @param rLabel
748  * Label of section to write
749  * @param pContext
750  * Write context to provide contextual information
751  *
752  * @exception Exception
753  * - IO errors (id 2)
754  */
755  virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
756 
757  /**
758  * Write configuration data of this object to TokenWriter in XML format.
759  *
760  * Reimplement this method in derived classes to provide the XML
761  * token io interface defined in the public section of Type. The default implementation
762  * invokes the std token output via
763  * DoWrite(TokenWriter&, const std::string&,const Type* )
764  *
765  * @param rTw
766  * Reference to TokenWriter
767  * @param rLabel
768  * Label of section to write
769  * @param pContext
770  * Write context to provide contextual information
771  *
772  * @exception Exception
773  * - IO errors (id 2)
774  */
775  virtual void DoXWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
776 
777  /**
778  * Write configuration data in debugging format to TokenWriter.
779  *
780  * Reimplement this method in derived classes to provide the std token io
781  * interface defined in the public section of Type.
782  *
783  * @param rTw
784  * Reference to TokenWriter
785  * @param rLabel
786  * Label of section to write
787  * @param pContext
788  * Write context to provide contextual information
789  *
790  * @exception Exception
791  * - IO errors (id 2)
792  */
793  virtual void DoDWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
794 
795  /**
796  * Write statistical data as a comment to TokenWriter.
797  *
798  * Reimplement this method in derived classes to provide the std token io
799  * interface defined in the public section of Type.
800  *
801  * @param rTw
802  * Reference to TokenWriter
803  *
804  * @exception Exception
805  * - IO errors (id 2)
806  */
807  virtual void DoSWrite(TokenWriter& rTw) const;
808 
809  /**
810  * Get objects's type definition.
811  *
812  * Returns the type definition corresponding to this object, or
813  * NULL if the object is not of a registered type.
814  *
815  * Technical note: for minimal memory requirement, the type definition
816  * is not cached but retrieved on every invokation of this method.
817  * Derived classes may reimplement this method for performance
818  * reasons. Options include a look-up cache or a static member
819  * for the actual type definition. The latter variant will make the
820  * type independant from the type registry.
821  *
822  * @return
823  * Type definition reference.
824  */
825  virtual const TypeDefinition* TypeDefinitionp(void) const;
826 
827 
828  /**
829  * Get objects's type name.
830  *
831  * Retrieve the faudes-type name from the type registry.
832  * This method silently returns the empty string if the type is
833  * not (yet) registered.
834  *
835  * @return
836  * Faudes-type name or empty string.
837  */
838  virtual const std::string& TypeName(void) const;
839 
840  /*
841  * Convenience function to set up std begin token
842  * for XML mode token I/O.
843  *
844  *
845  * @param rLabel
846  * User specified label
847  * @param rFallbackLabel
848  * Class defined fallback label
849  * @return
850  * Configured begin token
851  */
852  virtual Token XBeginTag(const std::string& rLabel="", const std::string& rFallbackLabel="") const;
853 
854 
855 private:
856 
857  // static string constant
858  static std::string msStringVoid;
859  static std::string msStringEmpty;
860 
861 };
862 
863 
864 
865 
866 /** faudes type declaration macros, individual */
867 #define FAUDES_TYPE_DECLARATION_NEW(ftype,ctype,cbase) \
868  public: virtual ctype* New(void) const;
869 #define FAUDES_TYPE_DECLARATION_COPY(ftype,ctype,cbase) \
870  public: virtual ctype* Copy(void) const;
871 #define FAUDES_TYPE_DECLARATION_CAST(ftype,ctype,cbase) \
872  public: virtual const Type* Cast(const Type* pOther) const;
873 #define FAUDES_TYPE_DECLARATION_ASSIGN(ftype,ctype,cbase) \
874  public: virtual ctype& Assign(const Type& rSrc);
875 #define FAUDES_TYPE_DECLARATION_EQUAL(ftype,ctype,cbase) \
876  public: virtual bool Equal(const Type& rOther) const; \
877  public: virtual ctype& operator=(const ctype& rSrc); \
878  public: virtual bool operator==(const ctype& rOther) const; \
879  public: virtual bool operator!=(const ctype& rOther) const;
880 
881 /** faudes type declaration macro, overall */
882 #define FAUDES_TYPE_DECLARATION(ftype,ctype,cbase) \
883  public: \
884  virtual ctype* New(void) const; \
885  virtual ctype* Copy(void) const; \
886  virtual const Type* Cast(const Type* pOther) const; \
887  virtual ctype& Assign(const Type& rSrc); \
888  virtual bool Equal(const Type& rOther) const; \
889  virtual ctype& operator=(const ctype& rSrc); \
890  virtual bool operator==(const ctype& rOther) const; \
891  virtual bool operator!=(const ctype& rOther) const;
892 
893 /** faudes type declaration macro, template version */
894 #define FAUDES_TYPE_TDECLARATION(ftype,ctype,cbase) \
895  public: \
896  virtual ctype* New(void) const; \
897  virtual ctype* Copy(void) const; \
898  virtual const Type* Cast(const Type* pOther) const; \
899  virtual ctype& Assign(const Type& rSrc); \
900  virtual bool Equal(const Type& rOther) const; \
901  virtual ctype& operator=(const ctype& rSrc); \
902  virtual bool operator==(const ctype& rOther) const; \
903  virtual bool operator!=(const ctype& rOther) const;
904 
905 /** faudes type implementation macros, individual */
906 #define FAUDES_TYPE_IMPLEMENTATION_NEW(ftype,ctype,cbase) \
907  ctype* ctype::New(void) const { \
908  return new ctype(); }
909 #define FAUDES_TYPE_IMPLEMENTATION_COPY(ftype,ctype,cbase) \
910  ctype* ctype::Copy(void) const { \
911  return new ctype(*this); }
912 #define FAUDES_TYPE_IMPLEMENTATION_CAST(ftype,ctype,cbase) \
913  const Type* ctype::Cast(const Type* pOther) const { \
914  return dynamic_cast<const ctype*>(pOther); }
915 #define FAUDES_TYPE_IMPLEMENTATION_ASSIGN(ftype,ctype,cbase) \
916  ctype& ctype::Assign(const Type& rSrc) { \
917  if(const ctype* csattr=dynamic_cast<const ctype*>(&rSrc)) { \
918  this->Clear(); DoAssign(*csattr);} \
919  else { \
920  cbase::Assign(rSrc);}; \
921  return *this;} \
922  ctype& ctype::operator=(const ctype& rSrc) { this->Clear(); DoAssign(rSrc); return *this; }
923 #define FAUDES_TYPE_IMPLEMENTATION_EQUAL(ftype,ctype,cbase) \
924  bool ctype::Equal(const Type& rOther) const { \
925  if(&rOther==this) return true; \
926  if(typeid(rOther) != typeid(*this)) return false; \
927  const ctype* csattr=dynamic_cast<const ctype*>(&rOther); \
928  if(!csattr) return false; \
929  if(!DoEqual(*csattr)) return false; \
930  return true;} \
931  bool ctype::operator==(const ctype& rOther) const { return DoEqual(rOther); } \
932  bool ctype::operator!=(const ctype& rOther) const { return !DoEqual(rOther); }
933 
934 
935 /** faudes type implementation macros, overall */
936 #define FAUDES_TYPE_IMPLEMENTATION(ftype,ctype,cbase) \
937  ctype* ctype::New(void) const { \
938  return new ctype(); } \
939  ctype* ctype::Copy(void) const { \
940  return new ctype(*this); } \
941  const Type* ctype::Cast(const Type* pOther) const { \
942  return dynamic_cast<const ctype*>(pOther); } \
943  ctype& ctype::Assign(const Type& rSrc) { \
944  if(const ctype* csattr=dynamic_cast<const ctype*>(&rSrc)) \
945  { this->Clear(); DoAssign(*csattr); return *this;} \
946  cbase::Assign(rSrc); \
947  return *this;} \
948  ctype& ctype::operator=(const ctype& rSrc) { this->Clear(); DoAssign(rSrc); return *this;} \
949  bool ctype::Equal(const Type& rOther) const { \
950  if(&rOther==this) return true; \
951  if(typeid(rOther) != typeid(*this)) return false; \
952  const ctype* csattr=dynamic_cast<const ctype*>(&rOther); \
953  if(!csattr) return false; \
954  if(!DoEqual(*csattr)) return false; \
955  return true;} \
956  bool ctype::operator==(const ctype& rOther) const { return DoEqual(rOther); } \
957  bool ctype::operator!=(const ctype& rOther) const { return !DoEqual(rOther); }
958 
959 
960 
961 
962 /** faudes type implementation macros, individual, template version */
963 #define FAUDES_TYPE_TIMPLEMENTATION_NEW(ftype,ctype,cbase,ctemp) \
964  ctemp ctype* ctype::New(void) const { \
965  return new ctype(); }
966 #define FAUDES_TYPE_TIMPLEMENTATION_COPY(ftype,ctype,cbase,ctemp) \
967  ctemp ctype* ctype::Copy(void) const { \
968  return new ctype(*this); }
969 #define FAUDES_TYPE_TIMPLEMENTATION_CAST(ftype,ctype,cbase,ctemp) \
970  ctemp const Type* ctype::Cast(const Type* pOther) const { \
971  return dynamic_cast<const ctype*>(pOther);}
972 #define FAUDES_TYPE_TIMPLEMENTATION_ASSIGN(ftype,ctype,cbase,ctemp) \
973  ctemp ctype& ctype::Assign(const Type& rSrc) { \
974  if(const ctype* csattr=dynamic_cast<const ctype*>(&rSrc)) { \
975  this->Clear(); DoAssign(*csattr); return *this;} \
976  cbase::Assign(rSrc); \
977  return *this;} \
978  ctemp ctype& ctype::operator=(const ctype& rSrc) { this->Clear(); DoAssign(rSrc); return *this; }
979 #define FAUDES_TYPE_TIMPLEMENTATION_EQUAL(ftype,ctype,cbase,ctemp) \
980  ctemp bool ctype::Equal(const Type& rOther) const { \
981  if(&rOther==this) return true; \
982  if(typeid(rOther) != typeid(*this)) return false; \
983  const ctype* csattr=dynamic_cast<const ctype*>(&rOther); \
984  if(!csattr) return false; \
985  if(!this->DoEqual(*csattr)) return false; \
986  return true;} \
987  ctemp bool ctype::operator==(const ctype& rOther) const { return this->DoEqual(rOther); } \
988  ctemp bool ctype::operator!=(const ctype& rOther) const { return !this->DoEqual(rOther); }
989 
990 
991 /** faudes type implementation macros, overall, template version */
992 #define FAUDES_TYPE_TIMPLEMENTATION(ftype,ctype,cbase,ctemp) \
993  ctemp ctype* ctype::New(void) const { \
994  return new ctype(); } \
995  ctemp ctype* ctype::Copy(void) const { \
996  return new ctype(*this); } \
997  ctemp const Type* ctype::Cast(const Type* pOther) const { \
998  return dynamic_cast<const ctype*>(pOther);} \
999  ctemp ctype& ctype::Assign(const Type& rSrc) { \
1000  if(const ctype* csattr=dynamic_cast<const ctype*>(&rSrc)) \
1001  { this->Clear(); DoAssign(*csattr); return *this;} \
1002  cbase::Assign(rSrc); \
1003  return *this;} \
1004  ctemp ctype& ctype::operator=(const ctype& rSrc) { this->Clear(); DoAssign(rSrc); return *this; } \
1005  ctemp bool ctype::Equal(const Type& rOther) const { \
1006  if(&rOther==this) return true; \
1007  if(typeid(rOther) != typeid(*this)) return false; \
1008  const ctype* csattr=dynamic_cast<const ctype*>(&rOther); \
1009  if(!csattr) return false; \
1010  if(!this->DoEqual(*csattr)) return false; \
1011  return true;} \
1012  ctemp bool ctype::operator==(const ctype& rOther) const { return this->DoEqual(rOther); } \
1013  ctemp bool ctype::operator!=(const ctype& rOther) const { return !this->DoEqual(rOther); }
1014 
1015 
1016 /** faudes type implementation macros, overall, debug version */
1017 /*
1018 #define FAUDES_TYPE_IMPLEMENTATION(ctype,cbase,ctemp) \
1019  ctemp ctype* ctype::New(void) const { \
1020  return new ctype(); } \
1021  ctemp const ctype* ctype::Cast(const Type* pOther) const { \
1022  return dynamic_cast<const ctype*>(pOther);} \
1023  ctemp ctype& ctype::Assign(const Type& rSrc) { \
1024  FD_WARN("RTI "<< typeid(ctype).name() << "::ASSIGN() V: " << typeid(*this).name() << \
1025  " from " << typeid(rSrc).name()); \
1026  if(const ctype* csattr=dynamic_cast<const ctype*>(&rSrc)) { this->Clear(); return DoAssign(*csattr);} \
1027  cbase::Assign(rSrc); \
1028  return *this;} \
1029  ctemp ctype& ctype::operator=(const ctype& rSrc) { \
1030  FD_WARN("RTI "<< typeid(ctype).name() << "::ASSIGN() O: " << typeid(*this).name() << \
1031  " from " << typeid(rSrc).name()); \
1032  this->Clear(); \
1033  return DoAssign(rSrc); }
1034 */
1035 
1036 
1037 
1038 /**
1039  * Structure to hold documentation data relating to a faudes-type or -function.
1040  * This class is the common base for faudes::TypeDefinition and faudes::FunctionDefinition.
1041  * It supports token io as demonstrated by the follwoing example for a type defintion:
1042  *
1043  * @code
1044  * <TypeDefinition name="CoreFaudes::Generator" ctype="faudes::Generator">
1045  *
1046  * <Documentation ref="generators.html#plain">
1047  * The common 5 tuple G=(Sigma, Q, delta, Qo, Qm).
1048  * <Documentation/>
1049  *
1050  * <Keywords> "generator" "language" </Keywords>
1051  *
1052  * </TypeDefinition>
1053  * @endcode
1054  *
1055  * Technical detail: Documentation is derived from Type for the purpose of token IO. We
1056  * still implement the faudes type interface to make it a fully qualified faudes data type.
1057  *
1058  * Technical detail: To facilitate inheritance, token io of member data and token io of
1059  * the section tags is separated.
1060  */
1061 
1062 class Documentation : public Type {
1063 
1064  // std faudes type interface
1066 
1067 public:
1068  /** Constructor */
1069  Documentation(void);
1070 
1071  /** Copy constructor */
1072  Documentation(const Documentation& rOther);
1073 
1074  /** Destructor */
1075  virtual ~Documentation(void){};
1076 
1077  /**
1078  * Clear
1079  */
1080  void Clear(void);
1081 
1082  /**
1083  * Get name of the entety to document (aka faudes-type or faudes-function).
1084  *
1085  * @return
1086  * Name
1087  */
1088  const std::string& Name(void) const;
1089 
1090  /**
1091  * Get name of plugin.
1092  * The plugin name defaults to CoreFaudes.
1093  *
1094  * @return
1095  * Name
1096  */
1097  const std::string& PlugIn(void) const;
1098 
1099  /**
1100  * Get corresponding C++ type
1101  *
1102  * @return
1103  * CType, or "" if no such
1104  */
1105  const std::string& CType(void) const;
1106 
1107  /**
1108  * @return
1109  * Short textual documentation.
1110  */
1111  const std::string& TextDoc(void) const;
1112 
1113  /**
1114  * @return
1115  * Filename pointing to the html documentation.
1116  */
1117  const std::string& HtmlDoc(void) const;
1118 
1119  /**
1120  * @return
1121  * CSV-string containing keywords.
1122  */
1123  const std::string& Keywords(void) const;
1124 
1125  /**
1126  * Search comma-seperated keywords for a substring. This should be
1127  * extended to regular expressions in a future release.
1128  *
1129  * @param rPattern
1130  * String-pattern.
1131  *
1132  * @return
1133  * Matching keyword or "" if no match
1134  */
1135  std::string MatchKeyword(const std::string& rPattern) const;
1136 
1137  /**
1138  * Not implemented
1139  * @return
1140  * Number of keywords.
1141  */
1142  int KeywordsSize(void) const;
1143 
1144  /**
1145  * @param pos
1146  * Position of keyword
1147  * @return
1148  * Keyword at specified position (or "" if pos out of range)
1149  */
1150  std::string KeywordAt(int pos) const;
1151 
1152  /**
1153  * Get auto-register flag.
1154  *
1155  * This flag indicated that the respective type was (will be)
1156  * registered by a libFAUDES static initialisation protorype.
1157  *
1158  * @return
1159  * True <> C++-automatic-registration
1160  */
1161  bool AutoRegistered(void) const;
1162 
1163  /**
1164  * Get application-registered flag.
1165  *
1166  * @return
1167  * True <> registered by application
1168  */
1169  bool ApplicationRegistered(void) const;
1170 
1171  /**
1172  * Merge documentation from token stream.
1173  * An exception is thrown if the current type name differs from the one in the documentation.
1174  *
1175  * @param rTr
1176  * TokenReader to read from.
1177  *
1178  * @exception Exception
1179  * - Type mismatch (id )
1180  * - Token mismatch (id 50, 51, 52)
1181  * - IO Error (id 1)
1182  */
1183  virtual void MergeDocumentation(TokenReader& rTr);
1184 
1185 
1186 
1187  protected:
1188 
1189  /**
1190  * Set name.
1191  *
1192  * @param name
1193  * New name.
1194  */
1195  void Name(const std::string& name);
1196 
1197  /**
1198  * Set name of plugin
1199  *
1200  * @param plugin
1201  * New name.
1202  */
1203  void PlugIn(const std::string& plugin);
1204 
1205  /**
1206  * Set C++ type
1207  *
1208  * @param name
1209  * New ctype.
1210  */
1211  void CType(const std::string& name);
1212 
1213  /**
1214  * Set a short textual documentation.
1215  *
1216  * @param textdoc
1217  * New textual documentation.
1218  */
1219  void TextDoc(const std::string& textdoc);
1220 
1221  /**
1222  * Set auto-register flag.
1223  *
1224  * See also AutoRegistered(void)
1225  *
1226  * @param flag
1227  * Flag value.
1228  */
1229  void AutoRegistered(bool flag);
1230 
1231  /**
1232  * Set application-registered flag.
1233  *
1234  * See also AutoRegistered(void)
1235  *
1236  * @param flag
1237  * Flag value.
1238  */
1239  void ApplicationRegistered(bool flag);
1240 
1241  /**
1242  * Set name of file pointing to the html documentation.
1243  *
1244  * @param fname
1245  * Filename
1246  */
1247  void HtmlDoc(const std::string& fname);
1248 
1249  /**
1250  * Append keyword.
1251  *
1252  * @param rKeyword
1253  * Keyword
1254  */
1255  void AddKeyword(const std::string& rKeyword);
1256 
1257  /**
1258  * Std faudes type interface: assignment.
1259  *
1260  * @param rSrc
1261  * Source to copy from
1262  * @return Reference to this object.
1263  */
1264  virtual void DoAssign(const Documentation& rSrc);
1265 
1266  /**
1267  * Std faudes type interface: test equality
1268  *
1269  * @param rOther
1270  * Other object to compare with.
1271  * @return
1272  * True on match.
1273  */
1274  virtual bool DoEqual(const Documentation& rOther) const;
1275 
1276  /**
1277  * Read configuration data of this object from TokenReader.
1278  *
1279  * This virtual function reads documentation from a token stream.
1280  * The section defaults to Documentation. It invokes DoReadCore to
1281  * do the member data token reading.
1282  *
1283  * @param rTr
1284  * TokenReader to read from
1285  * @param rLabel
1286  * Section to read
1287  * @param pContext
1288  * Read context to provide contextual information (ignored)
1289  *
1290  * @exception Exception
1291  * - Token mismatch (id 50, 51, 52)
1292  * - IO Error (id 1)
1293  */
1294  virtual void DoRead(TokenReader& rTr, const std::string& rLabel = "", const Type* pContext=0);
1295 
1296  /**
1297  * Read configuration data of this object from TokenReader.
1298  *
1299  * This virtual function reads documentation member data only.
1300  * It does NOT read the enclosing begin and end tokens.
1301  *
1302  * @param rTr
1303  * TokenReader to read from
1304  *
1305  * @exception Exception
1306  * - Token mismatch (id 50, 51, 52)
1307  * - IO Error (id 1)
1308  */
1309  virtual void DoReadCore(TokenReader& rTr);
1310 
1311 
1312 
1313  /**
1314  * Write configuration data of this object to TokenWriter.
1315  *
1316  * This virtual function writes documentation to a token stream.
1317  * The section defaults to Documentation. It invokes DoWriteCore to
1318  * do the actual member data writing.
1319  *
1320  * @param rTw
1321  * Reference to TokenWriter
1322  * @param rLabel
1323  * Label of section to write
1324  * @param pContext
1325  * Write context to provide contextual information
1326  *
1327  * @exception Exception
1328  * - IO errors (id 2)
1329  */
1330  virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
1331 
1332 
1333  /**
1334  * Write configuration data of this object to TokenWriter.
1335  *
1336  * This virtual function reads documentation members only.
1337  * It does NOT write enclosing begin and end tokens.
1338  *
1339  * @param rTw
1340  * Reference to TokenWriter
1341  *
1342  * @exception Exception
1343  * - IO errors (id 2)
1344  */
1345  virtual void DoWriteCore(TokenWriter& rTw) const;
1346 
1347 
1348  /** Faudes name. */
1349  std::string mName;
1350 
1351  /** Faudes plugin. */
1352  std::string mPlugIn;
1353 
1354  /** Corresponing C++ type, or "" if no such. */
1355  std::string mCType;
1356 
1357  /** String containing the text-documentation. */
1358  std::string mTextDoc;
1359 
1360  /** String containing the filename of the corresponding html-documentation. */
1361  std::string mHtmlDoc;
1362 
1363  /** Comma-seperated string containing all keywords. */
1364  std::string mKeywords;
1365 
1366  /** Constant characted used to seperate keywords */
1367  static const char mDelim = ';';
1368 
1369  /** Flag to indicate automated registration */
1371 
1372  /** Flag to indicate application registration */
1374 
1375 }; // Documentation
1376 
1377 
1378 
1379 /**
1380  * A TypeDefinition defines a faudes-type in that it specifies
1381  * a faudes-type name to identify the type and a method
1382  * NewObject() to instantiate objects of the respective type.
1383  * In this sense, TypeDefinition is a so called factory class.
1384  * Technically, the TypeDefinition holds one instance of the faude type,
1385  * the so called prototype object, and NewObject() invokes the New() method
1386  * of the prototype. Notebly, there is only one class TypeDefinition that by
1387  * parametrisation defins all derivates of Type.
1388  *
1389  * TypeDefinition is derived from faudes::Documentation and therefore additional
1390  * documentation-data can be associated.
1391  *
1392  *
1393  * @ingroup RunTimeInterface
1394  */
1395 
1397 
1398  // std faudes type interface
1400 
1401  // regisry is friend to set protected values
1402  friend class TypeRegistry;
1403 
1404  public:
1405 
1406  /**
1407  * Constructor
1408  *
1409  * The default constructor instantiates an invalid type definition
1410  * without prototype. To construct
1411  * a valid type definition, use the static Constructor() template
1412  * function.
1413  */
1414  TypeDefinition(const std::string& name="") : Documentation(), mpType(NULL) {Name(name);};
1415 
1416  /**
1417  * Destructor.
1418  *
1419  * Delete prototype object.
1420  */
1421  virtual ~TypeDefinition(void){ Prototype(NULL); };
1422 
1423  /**
1424  * Construct empty TypeDefinition object.
1425  * The given template parameter denotes any libFAUDES class derived from faudes::Type
1426  * A new instance of this class is assigned to member variable (pType)
1427  * whereas the name is set as specified.
1428  *
1429  * @tparam T
1430  * Actual c class, derived from Type
1431  * @param rTypeName
1432  * Name to identify this faudes-type<; defaults to the plattform
1433  * dependand typeid from the c++ runtime type information system.
1434  * @return
1435  * Newly constructed type definition.
1436  *
1437  */
1438  template<class T>
1439  static TypeDefinition* Constructor(const std::string& rTypeName="");
1440 
1441  /**
1442  * Construct empty TypeDefinition object.
1443  * The given prototype is assigned to the member variable pType,
1444  *
1445  * @param pProto
1446  * Prototype, derived from Type
1447  * @param rTypeName
1448  * Name to identify this faudes-type<; defaults to the plattform
1449  * dependand typeid from the c++ runtime type information system.
1450  * @return
1451  * Newly constructed type definition.
1452  *
1453  */
1454  static TypeDefinition* Constructor(Type* pProto, const std::string& rTypeName="");
1455 
1456  /**
1457  * Construct TypeDefinition object and read name and
1458  * documentation-data from TokenReader.
1459  *
1460  * @tparam T
1461  * Actual c class, derived from Type
1462  * @param rFileName
1463  * Name of file to read.
1464  * @return
1465  * Newly constructed type definition.
1466  *
1467  * @exception Exception
1468  * - Token mismatch (id 50, 51, 52)
1469  * - IO Error (id 1)
1470  */
1471  template<class T>
1472  static TypeDefinition* FromFile(const std::string& rFileName);
1473 
1474 
1475  /**
1476  * Return pointer to faudes-object prototype
1477  *
1478  * Note: this method is meant for inspection only, control over
1479  * the prototype remains with the TypeDefinition. Use
1480  * NewObject() to instantiate a new faudes-object.
1481  *
1482  * @return
1483  * Reference to prototype object
1484  */
1485  const Type* Prototype(void) const;
1486 
1487 
1488  /**
1489  * Construct faudes-object on heap.
1490  * Return pointer to new instance of assigned Type class.
1491  *
1492  * Note: If no prototype is installed, NULL is returned.
1493  *
1494  * @return
1495  * Pointer to new Type instance.
1496  */
1497  Type* NewObject(void) const;
1498 
1499 
1500  /**
1501  * Parameter access: Xml Element Tag
1502  *
1503  * This parameter is used for Xml IO of sets and vectors. It determines
1504  * the tag to used for individual elments.
1505  *
1506  * @return
1507  * Tag parameter.
1508  */
1509  const std::string& XElementTag(void) const;
1510 
1511  /**
1512  * Parameter access: Xml Element Tag
1513  *
1514  * @param rTag
1515  * New tag parameter
1516  */
1517  void XElementTag(const std::string& rTag);
1518 
1519 protected:
1520 
1521 
1522  /**
1523  * Std faudes type interface: assignment.
1524  *
1525  * @param rSrc
1526  * Source to copy from
1527  * @return Reference to this object.
1528  */
1529  virtual void DoAssign(const TypeDefinition& rSrc);
1530 
1531  /**
1532  * Std faudes type interface: test equality
1533  *
1534  * @param rOther
1535  * Other object to compare with.
1536  * @return
1537  * True on match.
1538  */
1539  virtual bool DoEqual(const TypeDefinition& rOther) const;
1540 
1541  /** Disable copy constructor */
1542  TypeDefinition(const TypeDefinition& rOther) : Documentation(rOther) {}; // todo: implement ?? for stl maps ?
1543 
1544  /**
1545  * Clear documentation-data; do *NOT* delete prototype (this is for using Read to
1546  * merge/overwrite documentation)
1547  */
1548  void Clear(void);
1549 
1550  /**
1551  * Use given object as prototype.
1552  *
1553  * The TypeDefinition takes ownership of the
1554  * provided object.
1555  *
1556  * @param pType
1557  * Any class that inherits Type.
1558  */
1559  virtual void Prototype(Type* pType);
1560 
1561  /**
1562  * Read configuration data of this object from TokenReader.
1563  *
1564  * The section defaults to "TypeDefinition", context ignored.
1565  * Actual reading is done by DoReadCore.
1566  *
1567  * @param rTr
1568  * TokenReader to read from
1569  * @param rLabel
1570  * Section to read
1571  * @param pContext
1572  * Read context to provide contextual information (ignored)
1573  *
1574  * @exception Exception
1575  * - Token mismatch (id 50, 51, 52)
1576  * - IO error (id 1)
1577  */
1578  virtual void DoRead(TokenReader& rTr, const std::string& rLabel = "", const Type* pContext=0);
1579 
1580  /**
1581  * Read configuration data of this object from TokenReader.
1582  *
1583  * This method reads members only, it does not read the section.
1584  *
1585  * @param rTr
1586  * TokenReader to read from
1587  *
1588  * @exception Exception
1589  * - Token mismatch (id 50, 51, 52)
1590  * - IO error (id 1)
1591  */
1592  virtual void DoReadCore(TokenReader& rTr);
1593 
1594  /**
1595  * Write configuration data of this object to TokenWriter.
1596  *
1597  * The section defaults to "TypeDefinition", context ignored.
1598  * Actual writing is done by DoWriteCore.
1599  *
1600  * @param rTw
1601  * Reference to TokenWriter
1602  * @param rLabel
1603  * Label of section to write
1604  * @param pContext
1605  * Write context to provide contextual information
1606  *
1607  * @exception Exception
1608  * - IO errors (id 2)
1609  */
1610  virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
1611 
1612  /**
1613  * Write configuration data of this object to TokenWriter.
1614  *
1615  * This method wrtite plain member data, the section lables are not
1616  * written.
1617  *
1618  * @param rTw
1619  * Reference to TokenWriter
1620  *
1621  * @exception Exception
1622  * - IO errors (id 2)
1623  */
1624  virtual void DoWriteCore(TokenWriter& rTw) const;
1625 
1626  /** Type-pointer tp prototype instance */
1628 
1629  /** Extra documentation/parameter: Xml Element Tag */
1630  std::string mXElementTag;
1631 
1632 }; //TypeDefinition
1633 
1634 
1635 
1636 
1637 /**********************************************************************************************
1638 ***********************************************************************************************
1639 ***********************************************************************************************
1640 
1641 Implemention of template members functions
1642 
1643 ***********************************************************************************************
1644 ***********************************************************************************************
1645 **********************************************************************************************/
1646 
1647 
1648 // Typedefinition constructor function
1649 template<class T>
1650 TypeDefinition* TypeDefinition::Constructor(const std::string& rTypeName){
1651  FD_DRTI("TypeDefinition::Construct<" << typeid(T).name() << ">(" << rTypeName << ")");
1652  return Constructor(new T, rTypeName);
1653 }
1654 
1655 
1656 // Type definition constructor function
1657 template<class T>
1658 TypeDefinition* TypeDefinition::FromFile(const std::string& rFileName){
1659  FD_DRTI("TypeDefinition::FromFile<" << typeid(T).name() << ">()");
1660  // construct with fallback name
1661  TypeDefinition* td = Constructor<T>();
1662  // read docu, incl actual name
1663  td->Read(rFileName);
1664  // done
1665  return(td);
1666 }
1667 
1668 
1669 
1670 
1671 
1672 } // namespace
1673 
1674 #endif /* FAUDES_RTITYPES_H */

libFAUDES 2.26g --- 2015.08.17 --- c++ api documentaion by doxygen