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

libFAUDES 2.33h --- 2025.06.18 --- c++ api documentaion by doxygen