cfl_generator.h
Go to the documentation of this file.
1 /** @file cfl_generator.h Class vGenerator */
2 
3 /* FAU Discrete Event Systems Library (libfaudes)
4 
5 Copyright (C) 2006 Bernd Opitz
6 Copyright (C) 2007 Thomas Moor
7 Exclusive copyright is granted to Klaus Schmidt
8 
9 This library is free software; you can redistribute it and/or
10 modify it under the terms of the GNU Lesser General Public
11 License as published by the Free Software Foundation; either
12 version 2.1 of the License, or (at your option) any later version.
13 
14 This library is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCANTABILITY or FITNES FOR A PARTICULAR PURPOSE. See the GNU
17 Lesser General Public License for more details.
18 
19 You should have received a copy of the GNU Lesser General Public
20 License along with this library; if not, write to the Free Software
21 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22 
23 
24 #ifndef FAUDES_VGENERATOR_H
25 #define FAUDES_VGENERATOR_H
26 
27 #include "cfl_definitions.h"
28 #include "cfl_exception.h"
29 #include "cfl_types.h"
30 #include "cfl_symboltable.h"
31 #include "cfl_indexset.h"
32 #include "cfl_nameset.h"
33 #include "cfl_transset.h"
34 #include "cfl_token.h"
35 #include "cfl_tokenreader.h"
36 #include "cfl_tokenwriter.h"
37 
38 #include <map>
39 #include <set>
40 #include <sstream>
41 #include <cstdlib>
42 #include <cassert>
43 
44 namespace faudes {
45 
46 /**
47  * Base class of all FAUDES generators.
48  *
49  * \section GeneratorMembers Overview
50  *
51  * The faudes::vGenerator models the plain five-tupel G = (X, Sigma, Delta, X_0, X_m) to represent
52  * the marked language L(G) and closed language L_m(G), respectively. It provides read and write
53  * access to core menbers, e.g. methods for inserting/deleting events, states
54  * and transitions.
55  *
56  *
57  * States, events and transitions in a generator can be addressed in three alternative methods:
58  *
59  * - by index, involves a search on a sorted set (efficient)
60  * - by name, involves two searches on sorted sets (not quite so efficient)
61  * - by iterator, involves pointer dereferencing (very efficient)
62  *
63  * For read access, const refererences to sets are provided. In order to allow for consistency checks,
64  * write access is via generator methods only. When the compiletime option FAUDES_CHECKED is
65  * defined, write methods throw an exception on inconsistent data, eg. setting an initial state
66  * that is not an element of the state set, or introducing a transition with an event label that
67  * is not in the alphabet.
68  *
69  *
70  * \section SecEventsVersusStates Events Versus States
71  *
72  * While both, events and states, are represented by the integer type faudes::Idx, there
73  * is a fundamental distinction between both, which stems from the design choice to use generators
74  * as a tool to represent formal languages. From this perspective, events are global enteties while states
75  * are local to the respective generator. Any two events within libFAUDES are related while states only
76  * compare within a generator.
77  *
78  * In consequence, there is global sybmoltable for event name resolution,
79  * while there is one local state symboltable for
80  * each generator. Furthermore, state names are considered cosmetic and hence are optional, while
81  * event names are mandatory.
82  *
83  * Example: two machines both refer to the event name "alpha" that models the process of passing
84  * a workpiece from one machine to the other. In libFAUDES this is indeed modelled as one event
85  * which is represented by one index. However, both machines may have a state "Idle" which indicates
86  * that the respective machine is idle. In libFAUDES the two states are treated locally to the
87  * generators and whether or not they have the same index is regarded irrelevant.
88  *
89  * The generator class carries a flag to indicate that functions with result type
90  * generator shall attach names to the newly created states, based on the state names
91  * of the respective arguments. Turning of this feature and avoiding state names alltogether
92  * considerably increases libFAUDES performance.
93  *
94  * \section GeneratorFileFormat File I/O (default format)
95  *
96  * Generators inherit the standard token IO interface from the libFAUDES general purpose base Type,
97  * so you may use Read and Write functions for generators. The file-format consists of a generator
98  * section that includes one subsection for each core member. It is illustrated by the below example
99  *
100  * @code
101  * <Generator>
102  * % libFAUDES Generator for the simple machine
103  * "simple machine"
104  *
105  * <Alphabet>
106  * alpha beta mue lambda
107  * </Alphabet>
108  *
109  * <States>
110  * idle busy down
111  * </States>
112  *
113  * <TransRel>
114  * idle alpha busy
115  * busy beta idle
116  * busy mue down
117  * down lambda idle
118  * </TransRel>
119  *
120  * <InitStates>
121  * idle
122  * </InitStates>
123  *
124  * <MarkedStates>
125  * idle
126  * </MarkedStates>
127  * </Generator>
128  * @endcode
129  *
130  * Technical Detail: Since symbolic state names are optional, states may alternatively be represented
131  * by their index. In order to consitently read a generator from a token stream, the convention
132  * was that states are indexed consecutively starting from 1. This convention produces nice and human-readable output.
133  * However, it requires a re-indexing when writing the generator. As of libFAUDES 2.20j, the token format was extended to
134  * allow for explicit symbol table entries in the format "symbolic_state_name#index". Whether or not re-indexing
135  * is applied can be configured via ReindexOnWrite(bool). The default is not to re-index. If you want to read your token
136  * stream with libFAUDES pre 2.20j, you must turn re-index on.
137  *
138  *
139  * Technical Detail: The generator name, the alphabet and the state set are optional. The generator
140  * name defaults to "generator"; the alphabet and the state set are extracted from the transition relation.
141  * Furthermore, there alternative short labels "A" for "Alphabet", "S" for "States" etc. are accepted.
142  * This short format has been introduced in 2.24e and is meant for embedding data concisely into luafaudes scripts.
143  * In general, the full format is preferable.
144  *
145  * @code
146  * <Generator>
147  * <T>
148  * idle alpha busy
149  * busy beta idle
150  * busy mue down
151  * down lambda idle
152  * </T>
153  * <I> idle </I>
154  * <M> idle </M>
155  * </Generator>
156  * @endcode
157  *
158  * \section GeneratorFileFormat File I/O (XML file-format)
159  *
160  * The alternative file file format prodiced by XWrite() is meant to accomodate
161  * for additional attributes attached to states, events and transitions, including e.g.
162  * graph data for a graphical representation. It starts with the outer element "Generator" with
163  * name attribute (optionally) and type attribute (mandatory).
164  *
165  *
166  * @code
167  * <Generator name="simpla machine" ftype="Generator">
168  * <Alphabet>
169  * <Event name="alpha"/>
170  * <Event name="beta"/>
171  * <Event name="mue"/>
172  * <Event name="lambda"/>
173  * </Alphabet>
174  *
175  * <StateSet>
176  * <State name="idle" id="1">
177  <Marked/><Initial/>
178  <State/>
179  * <State name="busy" id="2"/>
180  * <State name="down" id="3"/>
181  * </StateSet>
182  *
183  * <TransitionRelation>
184  * <Transition x1="1" event="alphs" x2="2"/>
185  * <Transition x1="2" event="beta" x2="2"/>
186  * <Transition x1="2" event="mue" x2="3"/>
187  * <Transition x1="3" event="lambda" x2="1"/>
188  * <TransitionRelation/>
189  *
190  * </Generator>
191  * @endcode
192  *
193  *
194  * \section GeneratorAttributes Attributes
195  *
196  * libFAUDES generators provide an interface to access so called attributes, ie data that
197  * is optionally attached to individual states, events, transitions, or globally to the generator.
198  *
199  * The faudes::Generator's interface to attributes is abstract in the sense that a generator
200  * is not aware of the actual type of its attributes.
201  * Instances of the class Generator indeed have trivial attributes that hold no data at all.
202  * To use attributes, you are meant to instantiate objects of the derived class TaGenerator
203  * with template parameters to specify attribute types. Basic algorithms
204  * implemented for plain generators will accept attributed generators as arguments. Such algorithms may
205  * occasionally inspect or set attributes using the abstract interface and C++ dynamic casts. For
206  * specialised algorithms that refer to extended generator semantics, we recommend derived
207  * generator classes as argument type.
208  *
209  *
210  * @ingroup GeneratorClasses
211  */
212 
213 
214 class vGenerator : public Type {
215 
216  public:
217 
218  /** @name Constructors & Destructor */
219  /** @{ doxygen group */
220 
221  /**
222  * Default constructor
223  */
224  vGenerator(void);
225 
226  /**
227  * Copy-constructror
228  */
229  vGenerator(const vGenerator& rOtherGen);
230 
231  /**
232  * Construct from file. This constructor
233  * effectively uses the DoRead(TokenReader&) function to read.
234  *
235  * @param rFileName
236  * Name of file
237  *
238  * @exception Exception
239  * - IO errors (id 1)
240  * - Token mismatch (id 50, 51, 52, 80, 85)
241  */
242  vGenerator(const std::string& rFileName);
243 
244  /**
245  * Construct on heap.
246  * Technically not a constructor, this function creates a vGenerator with the
247  * same event symboltable. It is the callers responsebilty to delete the object
248  * when no longer needed. Derived classes must reimplement
249  * this function to create an object of the same class and the same event
250  * symboltable.
251  *
252  * @return
253  * New vGenerator
254  */
255  virtual vGenerator* New(void) const;
256 
257  /**
258  * Construct copy on heap.
259  * Technically not a constructor, this function creates a vGenerator with the
260  * same event symboltable. It is the callers responsebilty to delete the object
261  * when no longer needed. Derived classes must reimplement
262  * this function to create an object of the same class and the same event
263  * symboltable.
264  *
265  * @return
266  * New vGenerator
267  */
268  virtual vGenerator* Copy(void) const;
269 
270  /**
271  * Type test.
272  * Uses C++ dynamic cast to test whether the specified object
273  * casts to a vGenerator.
274  *
275  * @return
276  * vGenerator reference if dynamic cast succeeds, else NULL
277  */
278  virtual const Type* Cast(const Type* pOther) const;
279 
280  /**
281  * Destructor
282  */
283  virtual ~vGenerator(void);
284 
285  /** @} doxygen group */
286 
287  /*****************************************
288  *****************************************
289  *****************************************
290  *****************************************/
291 
292  /** @name Copy and Assignment */
293  /** @{ doxygen group */
294 
295 
296  /**
297  * Copy from other vGenerator.
298  * The current implementation tries to be smart and copies attributes
299  * if types can be casted. Use AssignWithoutAttributes to
300  * explicitely ignore attributes.
301  *
302  * @param rSrc
303  * Source to copy from.
304  */
305  virtual vGenerator& Assign(const vGenerator& rSrc);
306 
307  /**
308  * Copy from other faudes type.
309  * The current implementation tests whether the source
310  * object can be casted to a generator and then performs
311  * the according assignment.
312  *
313  * @param rSrc
314  * Source to copy from.
315  */
316  virtual vGenerator& Assign(const Type& rSrc);
317 
318  /**
319  * Copy from other vGenerator, ignore attributes.
320  *
321  * @param rGen
322  * Source to copy from.
323  */
324  virtual vGenerator& AssignWithoutAttributes(const vGenerator& rGen);
325 
326  /**
327  * Destructive copy to other vGenerator.
328  * Copy method with increased performance at the cost of invalidating
329  * the source data. If attribute types of source and destination differ,
330  * a std copy is invoked.
331  *
332  *
333  * @param rGen
334  * Destination for copy operation.
335  */
336  virtual void Move(vGenerator& rGen);
337 
338  /**
339  * Assignment operator (uses Assign method)
340  * Note: you must reimplement this operator in derived
341  * classes in order to handle internal pointers correctly.
342  *
343  * @param rOtherGen
344  * Other generator
345  */
346  virtual vGenerator& operator= (const vGenerator& rOtherGen);
347 
348  /**
349  * Create another version of this generator.
350  * Assembles a copy of this generator, however, with versioned events.
351  * The new event names are created by appending an underscore and a specified string.
352  * State names and indices as well as any attributes are maintained.
353  *
354  * @param rVersion
355  * String value to be appended to event names
356  * @param rResGen
357  * Resulting versioned generator
358  *
359  * @exception Exception
360  * - Source must not match destination (id 96)
361  */
362  virtual void Version(const std::string& rVersion, vGenerator& rResGen) const;
363 
364  /**
365  * Create another version of this generator.
366  * Assembles a copy of this generator, however, with versioned events.
367  * The new event names are created by appending an underscore and a numeric index.
368  * State names and indices as well as any attributes are maintained.
369  *
370  * @param version
371  * Numeric value to be appended to event names
372  * @param rResGen
373  * Resulting versioned generator
374  * @exception Exception
375  * - Source must not match destination (id 96)
376  */
377  virtual void Version(Idx version, vGenerator& rResGen) const;
378 
379  /**
380  * Create another version of this generator.
381  * Assembles a copy of this generator, however, with versioned events.
382  * The new event names are created by replacing all substrings matching
383  * a specified string pattern by a replacement string.
384  * State names and indices as well as any attributes are maintained.
385  *
386  * @param rPattern
387  * String value to be replaced in event names
388  * @param rReplacement
389  * String value to be inserted in event names in place of rPattern
390  * @param rResGen
391  * Resulting versioned generator
392  * @exception Exception
393  * - Source must not match destination (id 96)
394  */
395  virtual void Version(const std::string& rPattern,const std::string& rReplacement, vGenerator& rResGen) const;
396 
397 
398 
399  /** @} doxygen group */
400 
401 
402  /*****************************************
403  *****************************************
404  *****************************************
405  *****************************************/
406 
407  /** @name Basic Maintenance */
408  /** @{ doxygen group */
409 
410 
411  /**
412  * Set the generator's name
413  *
414  * @param rName
415  * Generator name
416  */
417  void Name(const std::string& rName);
418 
419  /**
420  * Get generator's name
421  *
422  * @return
423  * Name of generator
424  */
425  const std::string& Name(void) const;
426 
427  /**
428  * Check if generator is valid.
429  * Performs internal consistency tests, This method is intendend
430  * to test generators that have been manipulated by methods without
431  * consistency tests, eg InjectAlphabet.
432  *
433  * @return
434  * True for success
435  */
436  virtual bool Valid(void);
437 
438  /**
439  * Clear generator data.
440  * Clears state set, alphabet and transitionrealtion. Behavioural flags
441  * eg StateNamesEnabled are maintained.
442  */
443  virtual void Clear(void);
444 
445 
446  /**
447  * Clear all states and transitions, maintain alphabet.
448  */
449  void ClearStates(void);
450 
451  /**
452  * Get number of events in alphabet
453  *
454  * @return
455  * Number of events
456  */
457  Idx AlphabetSize(void) const;
458 
459  /**
460  * Get generator size (number of states)
461  *
462  * @return
463  * Number of states
464  */
465  Idx Size(void) const;
466 
467  /**
468  * Get number of transitions
469  *
470  * @return
471  * Number of transitions
472  */
473  Idx TransRelSize(void) const;
474 
475  /**
476  * Get number of initial states
477  *
478  * @return
479  * Number of initial states
480  */
481  Idx InitStatesSize(void) const;
482 
483  /**
484  * Get number of marked states
485  *
486  * @return
487  * Number of marked states
488  */
489  Idx MarkedStatesSize(void) const;
490 
491  /**
492  * Check if generator is empty (no states)
493  *
494  * @return
495  * True if state set is empty
496  */
497  bool Empty(void) const;
498 
499  /**
500  * Check if alphabet is Empty
501  *
502  * @return
503  * True if mpAlphabet is empty
504  */
505  bool AlphabetEmpty(void) const;
506 
507  /**
508  * Check if transition relation is empty
509  *
510  * @return
511  * True if transition relation is empty
512  */
513  bool TransRelEmpty(void) const;
514 
515  /**
516  * Check if set of initial states are empty
517  *
518  * @return
519  * True if mInitStates is empty
520  */
521  bool InitStatesEmpty(void) const;
522 
523  /**
524  * Check if set of marked states are empty
525  *
526  * @return
527  * True if mMarkedStates is empty
528  */
529  bool MarkedStatesEmpty(void) const;
530 
531 
532  /** @} doxygen group */
533 
534  /*****************************************
535  *****************************************
536  *****************************************
537  *****************************************/
538 
539  /** @name Event Symboltable */
540  /** @{ doxygen group */
541 
542  /**
543  * Get Pointer to EventSymbolTable currently used
544  * by this vGenerator.
545  *
546  * @return
547  * Pointer to EventSymbolTable
548  */
549  SymbolTable* EventSymbolTablep(void) const;
550 
551  /**
552  * Set EventSymbolTable to be used by this vGenerator.
553  * This function sets the reference to the event symboltable. The current implementation
554  * in derived classes clears the generator, future versions may implement a re-indexing.
555  *
556  * @param pSymTab
557  * Pointer to SymbolTable
558  */
559  virtual void EventSymbolTablep(SymbolTable* pSymTab);
560 
561  /**
562  * Set EventSymbolTable as given by rOtherGen.
563  * This function sets the reference to the event symboltable. The current implementation
564  * clears the generator, future versions may implement a re-indexing.
565  *
566  * @param rOtherGen
567  * Other generator
568  *
569  */
570  virtual void EventSymbolTablep(const vGenerator& rOtherGen);
571 
572  /**
573  * Create EventSet with generator's EventSymbolTable (on stack).
574  *
575  * @return
576  * New empty EventSet on stack
577  */
578  EventSet NewEventSet(void) const;
579 
580  /**
581  * Create EventSet with generator's EventSymbolTable (on heap).
582  *
583  * @return
584  * Pointer to new empty EventSet on heap
585  */
586  EventSet* NewEventSetp(void) const;
587 
588  /**
589  * Event index lookup
590  *
591  * @param rName
592  * Name of event to lookup
593  *
594  * @return
595  * Valid index or 0 if name unknown to symboltable
596  */
597  Idx EventIndex(const std::string& rName) const;
598 
599  /**
600  * Event name lookup
601  *
602  * @param index
603  * Index of event to look up
604  *
605  * @return
606  * Name or empty std::string if non-existent
607  */
608  std::string EventName(Idx index) const;
609 
610  /**
611  * Set name for existing event
612  *
613  * Note: since the event symboltable is global, this affect all
614  * generators that refer to the specified event.
615  *
616  * @param index
617  * Event index
618  * @param rName
619  * New name
620  *
621  * @exception Exception
622  * - index not found in EventSymbolMap (id 42)
623  * - name already associated with another index (id 44)
624  * - event does not exist in generator (id 89)
625  */
626  void EventName(Idx index, const std::string& rName);
627 
628  /**
629  * Create a new unique symbolic event name.
630  * See also SymbolTable::UniqueSymbol().
631  *
632  * @param rName
633  * suggestion for new state name
634  */
635  std::string UniqueEventName(const std::string& rName) const;
636 
637 
638  /**
639  * Rename event in this generator.
640  * This method renames the specified event. It does so by
641  * removing and adding transitions. This does not
642  * effect other generators.
643  *
644  * @param event
645  * Event to rename
646  * @param rNewName
647  * New name
648  * @return
649  * True, if the new name did already exist
650  *
651  * @exception Exception
652  * - specified event does not exist (id 89)
653  */
654  bool EventRename(Idx event, const std::string& rNewName);
655 
656 
657  /**
658  * Rename event in this generator.
659  * Convenience wrapper for EventRename(Idx, const std::string&).
660  *
661  * @param event
662  * Event to rename
663  * @param rNewName
664  * New name
665  * @return
666  * True, if the new name did already exist
667  *
668  * @exception Exception
669  * - specified event does not exist (id 89)
670  */
671  bool EventRename(const std::string& rOldName, const std::string& rNewName);
672 
673 
674  /** @} doxygen group */
675 
676  /* statics outside doxygen group */
677 
678  /**
679  * Get Pointer to global EventSymbolTable. This is
680  * a static member of SymbolTable and used as default
681  * for all derived generator classes and instantiated objects.
682  *
683  * @return
684  * Pointer to global EventSymbolTable
685  */
686  static SymbolTable* GlobalEventSymbolTablep(void);
687 
688 
689  /*****************************************
690  *****************************************
691  *****************************************
692  *****************************************/
693 
694  /** @name State Symboltable */
695  /** @{ doxygen group */
696 
697 
698  /**
699  * Get StateSymbolTable.
700  *
701  * @return
702  * ref to state-symboltable
703  */
704  const SymbolTable& StateSymbolTable(void) const;
705 
706  /**
707  * Set StateSymbolTable.
708  *
709  * By convention, state names and indices are local to the
710  * respective generator. It is most unlikely that you want to use
711  * this function.
712  *
713  * @return
714  * Pointer to mpStateSymbolTable
715  */
716  void StateSymbolTable(const SymbolTable& rSymTab);
717 
718  /**
719  * State index lookup.
720  *
721  * @param rName
722  *
723  * @return
724  * Valid index (or 0 for non-existent)
725  */
726  Idx StateIndex(const std::string& rName) const;
727 
728  /**
729  * State name lookup
730  *
731  * @param index
732  *
733  * @return name (or empty string if no such exists)
734  */
735  std::string StateName(Idx index) const;
736 
737  /**
738  * Set name of state
739  *
740  * @param index
741  * Index
742  * @param rName
743  * Name
744  *
745  * @exception Exception
746  * - name already associated with another index (id 44)
747  * - state does not exist in generator (id 90)
748  */
749  void StateName(Idx index, const std::string& rName);
750 
751  /**
752  * Remove all names from generator's StateSymbolTable
753  */
754  void ClearStateNames(void);
755 
756  /**
757  * Clear name for individual state
758  *
759  * @param index
760  * State index
761  * @exception Exception
762  * - state does not exist in generator (id 90)
763  */
764  void ClrStateName(Idx index);
765 
766  /**
767  * Clear name for individual state
768  *
769  * @param rName
770  * State name
771  */
772  void ClrStateName(const std::string& rName);
773 
774  /**
775  * Whether libFAUEDS functions are requested to generate state names.
776  * Most libFAUDES functions that introduce new states to a generator can be enabled
777  * to also assign (more or less sensible) names to those states. This feature is
778  * purely cosmetic and may be disabled for performance reasons.
779  *
780  *
781  * @return
782  * True, if generation of statenames is enabled.
783  */
784  bool StateNamesEnabled(void) const;
785 
786  /**
787  * Enable/disable libFAUEDS functions to automatically generate state names.
788  * Disabling state name generation implies ClearStateNames().
789  *
790  * @param flag
791  * True enables statenames / false disables them
792  */
793  void StateNamesEnabled(bool flag);
794 
795  /**
796  * Assign each state a default name based on its index.
797  */
798  void SetDefaultStateNames(void);
799 
800  /**
801  * For all states without a symbolic name, assign a name
802  * based on suggested template and the index.
803  *
804  * @param rTemplate
805  * Basis for name generation
806  */
807  void EnforceStateNames(const std::string& rTemplate);
808 
809  /**
810  * Create a new unique symbolic state name.
811  * See also SymbolTable::UniqueSymbol().
812  *
813  * @param rName
814  * suggestion for new state name
815  */
816  std::string UniqueStateName(const std::string& rName) const;
817 
818 
819  /** @} doxygen group */
820 
821  /* statics outside doxygen group */
822 
823  /**
824  * Sets the default for automatic state name generation.
825  * This flag takes effect only on generators newly created by the default
826  * constructor. The copy constructor copies the state name flag from the
827  * source generator. See also StateNamesEnabled(bool).
828  *
829  * @param flag
830  * True enables statenames / false disables them
831  */
832  static void StateNamesEnabledDefault(bool flag);
833 
834 
835  /*****************************************
836  *****************************************
837  *****************************************
838  *****************************************
839  *****************************************/
840 
841  /** @name Read Access to Core Members */
842  /** @{ doxygen group */
843 
844  /**
845  * Iterator to Begin() of alphabet
846  *
847  * @return
848  * Iterator to begin of mpAlphabet
849  */
850  EventSet::Iterator AlphabetBegin(void) const;
851 
852  /**
853  * Iterator to End() of alphabet
854  *
855  * @return
856  * Iterator to end of mpAlphabet
857  */
858  EventSet::Iterator AlphabetEnd(void) const;
859 
860  /**
861  * Test existence of event in alphabet
862  *
863  * @param index
864  * Event index
865  *
866  * @return
867  * True / false
868  */
869  bool ExistsEvent(Idx index) const;
870 
871  /**
872  * Test existence of event in alphabet
873  *
874  * @param rName
875  * Event name
876  *
877  * @return
878  * True / false
879  */
880  bool ExistsEvent(const std::string& rName) const;
881 
882  /**
883  * Returns a iterator to event index in alphabet
884  *
885  * @param index
886  * Index to find
887  *
888  * @return
889  * Iterator to event index
890  */
891  EventSet::Iterator FindEvent(Idx index) const;
892 
893  /**
894  * Returns a iterator to event index in alphabet
895  *
896  * @param rName
897  * Event name of index to find
898  *
899  * @return
900  * Iterator to event index
901  */
902  EventSet::Iterator FindEvent(const std::string& rName) const;
903 
904  /**
905  * Return const reference to alphabet
906  *
907  * @return EventSet
908  * Reference to mpAlphabet
909  */
910  const EventSet& Alphabet(void) const;
911 
912  /**
913  * Iterator to Begin() of state set
914  *
915  * @return
916  * Iterator to begin of state set
917  */
918  StateSet::Iterator StatesBegin(void) const;
919 
920  /**
921  * Iterator to End() of state set
922  *
923  * @return
924  * Iterator to end of state set
925  */
926  StateSet::Iterator StatesEnd(void) const;
927 
928  /**
929  * Test existence of state in state set
930  *
931  * @param index
932  * State index
933  *
934  * @return
935  * true / false
936  */
937  bool ExistsState(Idx index) const;
938 
939  /**
940  * Test existence of state in state set
941  *
942  * @param name
943  * State name
944  *
945  * @return
946  * true / false
947  */
948  bool ExistsState(const std::string& name) const;
949 
950  /**
951  * Returns a iterator to state index in state set
952  *
953  * @param index
954  * Index to find
955  *
956  * @return
957  * StateSet::Iterator to state index
958  */
959  StateSet::Iterator FindState(Idx index) const;
960 
961  /**
962  * Returns a iterator to state with specified name
963  *
964  * @param rName
965  * name of state to find
966  *
967  * @return
968  * StateSet::Iterator to state
969  */
970  StateSet::Iterator FindState(const std::string& rName) const;
971 
972 
973  /**
974  * Return reference to state set
975  *
976  * @return
977  * StateSet reference incl actual attribute type
978  */
979  const StateSet& States(void) const;
980 
981  /**
982  * Return initial state
983  *
984  * If the initial state is not unique, this function
985  * returns 0.
986  *
987  * @return
988  * Index of initial state
989  *
990  */
991  Idx InitState(void) const;
992 
993  /**
994  * Iterator to Begin() of mInitStates
995  *
996  * @return
997  * Iterator to begin of mInitStates
998  */
999  StateSet::Iterator InitStatesBegin(void) const;
1000 
1001  /**
1002  * Iterator to End() of mInitStates
1003  *
1004  * @returns
1005  * Iterator to end of mInitStates
1006  */
1007  StateSet::Iterator InitStatesEnd(void) const;
1008 
1009  /**
1010  * Test existence of state in mInitStates
1011  *
1012  * @param index
1013  * State index
1014  *
1015  * @return
1016  * true / false
1017  */
1018  bool ExistsInitState(Idx index) const;
1019 
1020  /**
1021  * Iterator to state index in mInitStates
1022  *
1023  * @param index
1024  * Index to find
1025  *
1026  * @return
1027  * StateSet::Iterator to state index
1028  */
1029  StateSet::Iterator FindInitState(Idx index) const;
1030 
1031  /**
1032  * Const ref to initial states
1033  *
1034  * @return StateSet
1035  */
1036  const StateSet& InitStates(void) const;
1037 
1038  /**
1039  * Iterator to Begin() of mMarkedStates
1040  *
1041  * @returns
1042  * iterator to Begin of mMarkedStates
1043  */
1044  StateSet::Iterator MarkedStatesBegin(void) const;
1045 
1046  /**
1047  * Iterator to End() of mMarkedStates
1048  *
1049  * @returns
1050  * iterator to End of mMarkedStates
1051  */
1052  StateSet::Iterator MarkedStatesEnd(void) const;
1053 
1054  /**
1055  * Test existence of state in mMarkedStates
1056  *
1057  * @param index
1058  * State index
1059  *
1060  * @return
1061  * true / false
1062  */
1063  bool ExistsMarkedState(Idx index) const;
1064 
1065  /**
1066  * Returns a iterator to state index in mMarkedStates
1067  *
1068  * @param index
1069  * Index to find
1070  *
1071  * @return
1072  * StateSet::Iterator to state index
1073  */
1074  StateSet::Iterator FindMarkedState(Idx index) const;
1075 
1076  /**
1077  * Return const ref of marked states
1078  *
1079  * @return StateSet
1080  */
1081  const StateSet& MarkedStates(void) const;
1082 
1083  /**
1084  * Iterator to Begin() of transition relation
1085  *
1086  * @return
1087  * Iterator to Begin of mpTransRel
1088  */
1089  TransSet::Iterator TransRelBegin(void) const;
1090 
1091  /**
1092  * Iterator to End() of transition relation
1093  *
1094  * @return
1095  * Iterator to End of mpTransRel
1096  */
1097  TransSet::Iterator TransRelEnd(void) const;
1098 
1099  /**
1100  * Iterator to begin of transitions with x1 as predecessor state.
1101  *
1102  * @param x1
1103  * Predecessor state
1104  *
1105  * @return
1106  * iterator to begin of transitions with x1
1107  */
1109 
1110  /**
1111  * iterator to end of transitions with x1 as predecessor state.
1112  *
1113  * Note: Set the End(x1) iterator to a variable, so it won't be
1114  * recalculated every iteration.
1115  *
1116  * @param x1
1117  * Predecessor state
1118  *
1119  * @return
1120  * iterator to end of transitions with x1
1121  * (one after last matching transition)
1122  */
1124 
1125  /**
1126  * iterator to begin of transitions with x1 as predecessor state and
1127  * event ev.
1128  *
1129  * @param x1
1130  * Predecessor state
1131  * @param ev
1132  * Event
1133  *
1134  * @return
1135  * iterator to begin of transitions with x1 and ev
1136  */
1137  TransSet::Iterator TransRelBegin(Idx x1, Idx ev) const;
1138 
1139  /**
1140  * Iterator to end of transitions with x1 as predecessor state and
1141  * event ev.
1142  *
1143  * Note: Set the End(x1,ev) iterator to a variable, so it won't be
1144  * recalculated every iteration.
1145  *
1146  * @param x1
1147  * Predecessor state
1148  * @param ev
1149  * Event
1150  *
1151  * @return
1152  * iterator to end of transitions with x1 and ev
1153  * (one after last matching transition)
1154  */
1155  TransSet::Iterator TransRelEnd(Idx x1, Idx ev) const;
1156 
1157  /**
1158  * iterator to transition given by x1, ev, x2
1159  *
1160  *
1161  * @param rX1
1162  * name of Predecessor state
1163  * @param rEv
1164  * name of Event
1165  * @param rX2
1166  * name of Successor state
1167  *
1168  * @return
1169  * iterator to transition or end() if not exists
1170  */
1172  const std::string& rX1, const std::string& rEv, const std::string& rX2) const;
1173 
1174  /**
1175  * Iterator to transition given by x1, ev, x2
1176  *
1177  *
1178  * @param x1
1179  * Predecessor state
1180  * @param ev
1181  * Event
1182  * @param x2
1183  * Successor state
1184  *
1185  * @return
1186  * iterator to transition or End() if not exists
1187  */
1188  TransSet::Iterator FindTransition(Idx x1, Idx ev, Idx x2) const;
1189 
1190  /**
1191  * Iterator to transition
1192  *
1193  *
1194  * @param rTrans
1195  * transition
1196  *
1197  * @return
1198  * iterator to transition or end() if not exists
1199  */
1200  TransSet::Iterator FindTransition(const Transition& rTrans) const;
1201 
1202  /**
1203  * Test for transition given by x1, ev, x2
1204  *
1205  *
1206  * @param rX1
1207  * name of Predecessor state
1208  * @param rEv
1209  * name of Event
1210  * @param rX2
1211  * name of Successor state
1212  *
1213  * @return
1214  * true / false
1215  */
1216  bool ExistsTransition(
1217  const std::string& rX1, const std::string& rEv, const std::string& rX2) const;
1218 
1219  /**
1220  * Test for transition given by x1, ev, x2
1221  *
1222  * @param x1
1223  * Predecessor state
1224  * @param ev
1225  * Event
1226  * @param x2
1227  * Successor state
1228  *
1229  * @return
1230  * true / false
1231  */
1232  bool ExistsTransition(Idx x1, Idx ev, Idx x2) const;
1233 
1234  /**
1235  * test for transition
1236  *
1237  *
1238  * @param rTrans
1239  * transition
1240  *
1241  * @return
1242  * true / false
1243  */
1244  bool ExistsTransition(const Transition& rTrans) const;
1245 
1246  /**
1247  * Test for transition given by x1, ev
1248  *
1249  * @param x1
1250  * Predecessor state
1251  * @param ev
1252  * Event
1253  *
1254  * @return
1255  * true / false
1256  */
1257  bool ExistsTransition(Idx x1, Idx ev) const;
1258 
1259  /**
1260  * Test for transition given by x1
1261  *
1262  * @param x1
1263  * Predecessor state
1264  *
1265  * @return
1266  * true / false
1267  */
1268  bool ExistsTransition(Idx x1) const;
1269 
1270  /**
1271  * Return reference to transition relation
1272  *
1273  * @return TransRel
1274  */
1275  const TransSet& TransRel(void) const;
1276 
1277  /**
1278  * Get copy of trantision relation sorted by other compare
1279  * operator, e.g. "x2,ev,x1"
1280  *
1281  * @param res
1282  * resulting transition relation
1283  */
1284  void TransRel(TransSetX1EvX2& res) const;
1285  void TransRel(TransSetEvX1X2& res) const;
1286  void TransRel(TransSetEvX2X1& res) const;
1287  void TransRel(TransSetX2EvX1& res) const;
1288  void TransRel(TransSetX2X1Ev& res) const;
1289  void TransRel(TransSetX1X2Ev& res) const;
1290 
1291  /**
1292  * Convebience function.
1293  *
1294  * @param rX1
1295  * Name of Predecessor state
1296  * @param rEv
1297  * Name of Event
1298  * @param rX2
1299  * Name of Successor state
1300  *
1301  * @return
1302  * Transition as specified.
1303  */
1305  const std::string& rX1, const std::string& rEv, const std::string& rX2) const;
1306 
1307  /** @} doxygen group */
1308 
1309 
1310 
1311  /*****************************************
1312  *****************************************
1313  *****************************************
1314  *****************************************/
1315 
1316  /** @name Write Access to Core Members */
1317  /** @{ doxygen group */
1318 
1319 
1320  /**
1321  * Add an existing event to alphabet by index. It is an error to insert
1322  * an event index that is not known to the mpEventSymbolTable.
1323  *
1324  * @param index
1325  * Event index
1326  * @return
1327  * True, if event was new to alphabet
1328  */
1329  bool InsEvent(Idx index);
1330 
1331  /**
1332  * Add named event to generator. An entry in the mpEventSymbolTable will
1333  * be made if event name is not known so far.
1334  *
1335  * @param rName
1336  * Name of the event to add
1337  *
1338  * @return
1339  * New unique index
1340  */
1341  Idx InsEvent(const std::string& rName);
1342 
1343  /**
1344  * Add new named events to generator.
1345  * If the event allready exists, the attribute is maintained.
1346  *
1347  * @param events
1348  * EventSet
1349  */
1350  void InsEvents(const EventSet& events);
1351 
1352  /**
1353  * Delete event from generator by index. mpEventSymbolTable stays untouched.
1354  * Transitions containing event will be removed too.
1355  *
1356  * @param index
1357  * Index of event
1358  * @return
1359  * True, if event was in alphabet
1360  *
1361  */
1362  bool DelEvent(Idx index);
1363 
1364  /**
1365  * Delete event from generator by name. mpEventSymbolTable stays untouched.
1366  * Transitions containing event will be removed too.
1367  *
1368  * @param rName
1369  * Name of event
1370  * @return
1371  * True, if event was in alphabet
1372  *
1373  */
1374  bool DelEvent(const std::string& rName);
1375 
1376  /**
1377  * Delete a set of events from generator. mpEventSymbolTable stays untouched.
1378  * Transitions containing events will be removed too.
1379  *
1380  * @param rEvents
1381  * EventSet containing events to remove
1382  */
1383  void DelEvents(const EventSet& rEvents);
1384 
1385  /**
1386  * Delete event from alphabet without consistency check. The event is only
1387  * deleted from mpAlphabet but not from transition relation.
1388  *
1389  * @param index
1390  * Index of event
1391  * @return
1392  * True, if event was in alphabet
1393  *
1394  */
1395  bool DelEventFromAlphabet(Idx index);
1396 
1397  /**
1398  * Set mpAlphabet without consistency check.
1399  * Sets the alphabet incl attributes, if provided.
1400  *
1401  * @param rNewalphabet
1402  * EventSet with new alphabet
1403  */
1404  void InjectAlphabet(const EventSet& rNewalphabet);
1405 
1406  /**
1407  * Restricts mpAlphabet incl removing resp. transition.
1408  * Maintains attributes if any.
1409  *
1410  * Note: before libFAUDES 2.23, this method did not remove
1411  * transitions. Use InjectAlphabet(const EventSet&) for direct
1412  * write acces to the alphabet.
1413  *
1414  * @param rNewalphabet
1415  * EventSet with alphabet
1416  */
1417  void RestrictAlphabet(const EventSet& rNewalphabet);
1418 
1419  /**
1420  * Add new anonymous state to generator
1421  *
1422  * @return
1423  * Index of new unique state
1424  */
1425  Idx InsState(void);
1426 
1427  /**
1428  * Add (perhaps new) state to generator
1429  *
1430  * @return
1431  * True to indicate that state was new to generator
1432  */
1433  bool InsState(Idx index);
1434 
1435  /**
1436  * Add new named state to generator.
1437  *
1438  * @param rName
1439  * Name of the state to add
1440  *
1441  * @return
1442  * Index of new unique state
1443  *
1444  * @exception Exception
1445  * Name already exists (id 44)
1446  */
1447  Idx InsState(const std::string& rName);
1448 
1449  /**
1450  * Add anonymous states to generator
1451  *
1452  * @param rStates
1453  * Set of states to add
1454  */
1455  void InsStates(const StateSet& rStates);
1456 
1457  /**
1458  * Delete a state from generator by index.
1459  * Cleans mpStates, mInitStates, mMarkedStates, mpTransRel and mpStateSymbolTable.
1460  *
1461  * @param index
1462  * Index of state to delete.
1463  * @return
1464  * True, if state was in stateset
1465  */
1466  bool DelState(Idx index);
1467 
1468  /**
1469  * Delete a state from generator by name.
1470  * Cleans mpStates, mInitStates, mMarkedStates, mpTransRel and mpStateSymbolTable.
1471  *
1472  * @param rName
1473  * Name of state to delete. Will be erased in mpStateSymbolTable too
1474  * @return
1475  * True, if state was in stateset
1476  *
1477  * @exception Exception
1478  * - Symbolic name not known (id 90)
1479  */
1480  bool DelState(const std::string& rName);
1481 
1482  /**
1483  * Delete a set of states
1484  * Cleans mpStates, mInitStates, mMarkedStates, mpTransrel, and mpStateSymboltable
1485  *
1486  * @param rDelStates
1487  * StateSet containing states aka indicees to delete
1488  */
1489  void DelStates(const StateSet& rDelStates);
1490 
1491 
1492  /**
1493  * Delete a state from generator without consistency check. This removes the
1494  * state from mpStates and mpStateSymbolTable but doesn't touch mpTransRel,
1495  * mInitStates and mMarkedStates.
1496  *
1497  * @param index
1498  * Index of state to delete.
1499  * @return
1500  * True, if state was in stateset
1501  *
1502  */
1503  bool DelStateFromStates(Idx index);
1504 
1505  /**
1506  * Delete a state from generator without consistency check. This removes the
1507  * state from mpStates and mpStateSymbolTable but doesn't touch mpTransRel,
1508  * mInitStates and mMarkedStates.
1509  * Index to delete is given by iterator.
1510  *
1511  * @param pos
1512  * StateSet::Iterator
1513  * @return
1514  * Iteraror to next state
1515  */
1516  StateSet::Iterator DelStateFromStates(StateSet::Iterator pos);
1517 
1518  /**
1519  * Restrict states
1520  * Cleans mpStates, mInitStates, mMarkedStates, mpTransrel, and mpStateSymboltable
1521  *
1522  * @param rStates
1523  * StateSet containing valid states
1524  */
1525  void RestrictStates(const StateSet& rStates);
1526 
1527 
1528  /**
1529  * Inject an existing state index into generators mStates
1530  * Use with care! For use in performance optimized functions.
1531  *
1532  * @param index
1533  * State index to inject
1534  */
1535  void InjectState(Idx index);
1536 
1537  /**
1538  * Inject a complete state set without consistency checks (without attributes)
1539  *
1540  * @param rNewStates
1541  * StateSet
1542  */
1543  void InjectStates(const StateSet& rNewStates);
1544 
1545 
1546  /**
1547  * Create new anonymous state and set as initial state
1548  *
1549  * @return
1550  * Index of new unique
1551  */
1552  Idx InsInitState(void);
1553 
1554  /**
1555  * Add (perhaps new) state to generator and turn it
1556  * into a initial state.
1557  *
1558  * @param index
1559  * State to insert
1560  * @return
1561  * True to indicate that state was new to generator
1562  */
1563  bool InsInitState(Idx index);
1564 
1565  /**
1566  * Create a new named state and set as initial state
1567  *
1568  * @param rName
1569  * Name of the state to add
1570  *
1571  * @return
1572  * Index of new unique state
1573  */
1574  Idx InsInitState(const std::string& rName);
1575 
1576  /**
1577  * Add (perhaps new) anonymous initial states to generator
1578  *
1579  * @param rStates
1580  * Set of states to add
1581  */
1582  void InsInitStates(const StateSet& rStates);
1583 
1584  /**
1585  * Create new anonymous state and set as marked state
1586  *
1587  * @return
1588  * Index of new unique state
1589  */
1590  Idx InsMarkedState(void);
1591 
1592  /**
1593  * Add (perhaps new) state to generator and turn it
1594  * into a marked state.
1595  *
1596  * @param index
1597  * State to insert
1598  * @return
1599  * True to indicate that state was new to generator
1600  */
1601  bool InsMarkedState(Idx index);
1602 
1603  /**
1604  * Create a new named state and set as marked state
1605  *
1606  * @param rName
1607  * Name of the state to add
1608  *
1609  * @return
1610  * Index of new unique state
1611  */
1612  Idx InsMarkedState(const std::string& rName);
1613 
1614  /**
1615  * Add (perhaps new) anonymous initial states to generator
1616  *
1617  * @param rStates
1618  * Set of states to add
1619  */
1620  void InsMarkedStates(const StateSet& rStates);
1621 
1622  /**
1623  * Set an existing state as initial state by index.
1624  *
1625  * @param index
1626  * Index of state to set as initial state
1627  * @exception Exception
1628  * - State index not found in generator (id 91)
1629  */
1630  void SetInitState(Idx index);
1631 
1632  /**
1633  * Set an existing state as initial state by name.
1634  *
1635  * @param rName
1636  * Name of state to set as initial state
1637  *
1638  * @exception Exception
1639  * - State name not known in generator (id 90)
1640  */
1641  void SetInitState(const std::string& rName);
1642 
1643  /**
1644  * Replace mInitStates with StateSet given as parameter without consistency checks.
1645  *
1646  * @param rNewInitStates
1647  * StateSet containing new mInitStates
1648  */
1649  void InjectInitStates(const StateSet& rNewInitStates);
1650 
1651  /**
1652  * Unset an existing state as initial state by index
1653  *
1654  * Define FAUDES_CHECKED for consistency checks.
1655  *
1656  * @param index
1657  * State index
1658  *
1659  * @exception Exception
1660  * - State index not found in generator (id 91)
1661  */
1662  void ClrInitState(Idx index);
1663 
1664  /**
1665  * Unset an existing state as initial state by name
1666  *
1667  * @param rName
1668  * State name
1669  *
1670  * @exception Exception
1671  * - State name not known in generator (id 90)
1672  */
1673  void ClrInitState(const std::string& rName);
1674 
1675  /**
1676  * Unset an existing state as initial state by iterator
1677  *
1678  * @param pos
1679  * StateSet::iterator
1680  * @return
1681  * Iterator to next init state
1682  */
1683  StateSet::Iterator ClrInitState(StateSet::Iterator pos);
1684 
1685  /**
1686  * Clear all mInitStates
1687  */
1688  void ClearInitStates(void);
1689 
1690  /**
1691  * Set an existing state as marked state by index
1692  *
1693  * @param index
1694  * Index of state to set as initial state
1695  * @exception Exception
1696  * - State index not found in generator (id 91)
1697  */
1698  void SetMarkedState(Idx index);
1699 
1700  /**
1701  * Set an existing state as marked state by name.
1702  *
1703  * @param rName
1704  * Name of state to set as marked state
1705  *
1706  * @exception Exception
1707  * - State name not known in generator (id 90)
1708  */
1709  void SetMarkedState(const std::string& rName);
1710 
1711  /**
1712  * Unset an existing state as marked state by index
1713  *
1714  * @param index
1715  * State index
1716  *
1717  * @exception Exception
1718  * - State index not found in generator (id 91)
1719  */
1720  void ClrMarkedState(Idx index);
1721 
1722  /**
1723  * Unset an existing state as marked state by name
1724  *
1725  * @param rName
1726  * State name
1727  *
1728  * @exception Exception
1729  * - State index not found in generator (id 91)
1730  */
1731  void ClrMarkedState(const std::string& rName);
1732 
1733  /**
1734  * Unset an existing state as marked state by iterator
1735  *
1736  * @param pos
1737  * StateSet::iterator
1738  * @return
1739  * Iterator to next marked state
1740  */
1741  StateSet::Iterator ClrMarkedState(StateSet::Iterator pos);
1742 
1743  /**
1744  * Clear all marked states
1745  */
1746  void ClearMarkedStates(void);
1747 
1748  /**
1749  * Replace mMarkedStates with StateSet given as parameter without consistency checks.
1750  *
1751  * @param rNewMarkedStates
1752  * StateSet containing new marked states
1753  */
1754  void InjectMarkedStates(const StateSet& rNewMarkedStates);
1755 
1756  /**
1757  * Add a transition to generator by indices. States and event
1758  * must already exist.
1759  *
1760  * @param x1
1761  * Predecessor state index
1762  * @param ev
1763  * Event index
1764  * @param x2
1765  * Successor state index
1766  *
1767  * @return
1768  * True, if the transition was new the generator
1769  *
1770  * @exception Exception
1771  * - state or event not in generator (id 95)
1772  */
1773  bool SetTransition(Idx x1, Idx ev, Idx x2);
1774 
1775  /**
1776  * Add a transition to generator by names. Statename and eventname
1777  * must already exist.
1778  *
1779  * @param rX1
1780  * Predecessor state name
1781  * @param rEv
1782  * Event name
1783  * @param rX2
1784  * Successor state name
1785  *
1786  * @return
1787  * True, if the transition was new the generator
1788  *
1789  * @exception Exception
1790  * - state or event not in generator (id 95)
1791  * - state name not known (id 90)
1792  * - event name not known (id 66)
1793  */
1794  bool SetTransition(const std::string& rX1, const std::string& rEv,
1795  const std::string& rX2);
1796 
1797  /**
1798  * Add a transition to generator. States and event
1799  * must already exist.
1800  *
1801  *
1802  * @param rTransition
1803  * Transition
1804  *
1805  * @return
1806  * True, if the transition was new the generator
1807  * @exception Exception
1808  * - state or event not in generator (id 95)
1809  */
1810  bool SetTransition(const Transition& rTransition);
1811 
1812  /**
1813  * Remove a transition by indices
1814  *
1815  * @param x1
1816  * Predecessor state index
1817  * @param ev
1818  * Event index
1819  * @param x2
1820  * Successor state index
1821  */
1822  void ClrTransition(Idx x1, Idx ev, Idx x2);
1823 
1824  /**
1825  * Remove a transition by transition object
1826  *
1827  * @param rTrans
1828  * Transition object
1829  */
1830  void ClrTransition(const Transition& rTrans);
1831 
1832  /**
1833  * Remove a transition by iterator
1834  *
1835  * @param it
1836  * TransSet::iterator
1837  * @return
1838  * Iterator to next transition
1839  */
1841 
1842  /**
1843  * Remove a transitions by state and event
1844  *
1845  * @param x1
1846  * Predecessor state index
1847  * @param ev
1848  * Event index
1849  */
1850  void ClrTransitions(Idx x1, Idx ev);
1851 
1852  /**
1853  * Remove a transitions by state
1854  *
1855  * @param x1
1856  * Predecessor state index
1857  */
1858  void ClrTransitions(Idx x1);
1859 
1860  /**
1861  * Clear all transitions
1862  */
1863  void ClearTransRel(void);
1864 
1865  /**
1866  * Set transition without consistency check.
1867  *
1868  * @param rTrans
1869  * Transition to insert
1870  */
1871  void InjectTransition(const Transition& rTrans);
1872 
1873  /**
1874  * Set transition relation without consistency check (no attributes)
1875  *
1876  * @param rNewtransrel
1877  * TransRel to insert
1878  */
1879  void InjectTransRel(const TransSet& rNewtransrel);
1880 
1881  /** @} doxygen group */
1882 
1883 
1884 
1885  /*****************************************
1886  *****************************************
1887  *****************************************
1888  *****************************************/
1889 
1890  /** @name Attributes */
1891  /** @{ doxygen group */
1892 
1893 
1894  /**
1895  * Clear Attributes
1896  */
1897  virtual void ClearAttributes(void);
1898 
1899  /**
1900  * Updates internal attributes.
1901  * This method does nothing and may be reimplemented
1902  * by a any class that adds semantics to attributes
1903  * Eg. you may set a particular state flag, if this state
1904  * is reachable.
1905  *
1906  * @return True if value changed
1907  */
1908  virtual bool UpdateAttributes(void) {return false;};
1909 
1910  /**
1911  * Clear event attributes
1912  */
1913  virtual void ClearEventAttributes(void);
1914 
1915  /**
1916  * Clear attribute for existing event
1917  *
1918  * @param index
1919  * Event index
1920  */
1921  virtual void ClrEventAttribute(Idx index);
1922 
1923  /**
1924  * Set attribute for existing event.
1925  * This version uses a dynamic cast
1926  * to test the actual type of the provided attribute. An exception is
1927  * thrown for an invalid attribute type.
1928  * In a context where
1929  * the attribute type is known, you may prefer the TaGenerator method.
1930  *
1931  * @param index
1932  * Event index
1933  * @param rAttr
1934  * New attribute
1935  *
1936  * @exception Exception
1937  * - Index not found in alphabet (id 60)
1938  * - Cannot cast attribute (id 63)
1939  */
1940  virtual void EventAttribute(Idx index, const Type& rAttr);
1941 
1942  /**
1943  * Set attributes for existing events.
1944  * This version uses a dynamic cast
1945  * to test the actual type of the provided attributes. An exception is
1946  * thrown for an invalid attribute type.
1947  *
1948  * @param rEventSet
1949  * Set of attributed events
1950  * @exception Exception
1951  * - Element not found in alphabet (id 60)
1952  * - Cannot cast attribute (id 63)
1953  */
1954  virtual void EventAttributes(const EventSet& rEventSet);
1955 
1956  /**
1957  * Event attribute lookup.
1958  * In a context where
1959  * the attribute type is known, you may prefer the TaGenerator method.
1960  *
1961  * @param index
1962  *
1963  * @return
1964  * reference to attribute
1965  */
1966  virtual const AttributeVoid& EventAttribute(Idx index) const;
1967 
1968  /**
1969  * Event attribute lookup.
1970  * In a context where the attribute type is known,
1971  * you may prefer the TaGenerator method.
1972  *
1973  * @param rName
1974  *
1975  * @return
1976  * reference to attribute
1977  */
1978  virtual const AttributeVoid& EventAttribute(const std::string& rName) const;
1979 
1980  /**
1981  * Event attribute pointer to access Attribute methods.
1982  * If there are no attributes (plain vGenerator) this method
1983  * returs 0. If there are attributes, an explicit default value
1984  * may be inserted.
1985  * In a context where the attribute type is known,
1986  * you may prefer the TaGenerator method.
1987  *
1988  * @param index
1989  *
1990  * @return
1991  * pointer to attribute
1992  */
1993  virtual AttributeVoid* EventAttributep(Idx index);
1994 
1995  /**
1996  * Event attribute pointer to access Attribute methods.
1997  * If there are no attributes (plain vGenerator) this method
1998  * returs 0. If there are attributes, an explicit default value
1999  * may be inserted.
2000  * In a context where the attribute type is known,
2001  * you may prefer the TaGenerator method.
2002  *
2003  * @param rName
2004  *
2005  * @return
2006  * pointer to attribute
2007  */
2008  virtual AttributeVoid* EventAttributep(const std::string& rName);
2009 
2010 
2011  /**
2012  * Clear state attributes
2013  */
2014  virtual void ClearStateAttributes(void);
2015 
2016  /**
2017  * Clear attribute for existing state
2018  *
2019  * @param index
2020  * State index
2021  */
2022  virtual void ClrStateAttribute(Idx index);
2023 
2024  /**
2025  * Set attribute for existing state.
2026  * This version uses a dynamic cast
2027  * to test the actual type of the provided attribute. An exception is
2028  * thrown for an invalid attribute type.
2029  * In a context where
2030  * the attribute type is known, you may prefer the TaGenerator method.
2031  *
2032  * @param index
2033  * State index
2034  * @param rAttr
2035  * New attribute
2036  *
2037  * @exception Exception
2038  * - Index not found in Stateset (id 60)
2039  * - Cannot cast attribute (id 63)
2040  */
2041  virtual void StateAttribute(Idx index, const Type& rAttr);
2042 
2043  /**
2044  * State attribute lookup.
2045  * In a context where the attribute type is known,
2046  * you may prefer the TaGenerator method.
2047  *
2048  * @param index
2049  * State index
2050  *
2051  * @return Ref to attribute of state
2052  */
2053  virtual const AttributeVoid& StateAttribute(Idx index) const;
2054 
2055  /**
2056  * State attribute pointer to access Attribute methods.
2057  * If there are no attributes (plain vGenerator) this method
2058  * returns 0. If there are attributes, an explicit default value
2059  * may be inserted.
2060  * In a context where the attribute type is known,
2061  * you may prefer the TaGenerator method.
2062  *
2063  * @param index
2064  * State index
2065  *
2066  * @return Pointer to attribute of state
2067  */
2068  virtual AttributeVoid* StateAttributep(Idx index);
2069 
2070  /**
2071  * Clear transition attributes
2072  */
2073  virtual void ClearTransAttributes(void);
2074 
2075  /**
2076  * Set attribute for existing transition.
2077  * This version uses a dynamic cast
2078  * to test the actual type of the provided attribute. An exception is
2079  * thrown for an invalid attribute type.
2080  * In a context where
2081  * the attribute type is known, you may prefer the TaGenerator method.
2082  *
2083  * @param rTrans
2084  * Transition
2085  * @param rAttr
2086  * New attribute
2087  *
2088  * @exception Exception
2089  * - Transition not found in transition relation(id 60)
2090  * - Cannot cast attribute (id 63)
2091  */
2092  virtual void TransAttribute(const Transition& rTrans, const Type& rAttr);
2093 
2094 
2095  /**
2096  * Clear attribute for existing transition
2097  *
2098  * @param rTrans
2099  * transition
2100  */
2101  virtual void ClrTransAttribute(const Transition& rTrans);
2102 
2103  /**
2104  * Transition attribute lookup.
2105  * In a context where the attribute type is known,
2106  * you may prefer the TaGenerator method.
2107  *
2108  * @return
2109  * Attribute
2110  *
2111  */
2112  virtual const AttributeVoid& TransAttribute(const Transition& rTrans) const;
2113 
2114  /**
2115  * Transition attribute pointer to access Attribute methods.
2116  * If there are no attributes (plain vGenerator) this method
2117  * returns 0. If there are attributes, an explicit default value
2118  * may be inserted.
2119  * In a context where the attribute type is known,
2120  * you may prefer the TaGenerator method.
2121  *
2122  * @return
2123  * Attribute pointer
2124  *
2125  */
2126  virtual AttributeVoid* TransAttributep(const Transition& rTrans);
2127 
2128  /**
2129  * Clear global attribute
2130  */
2131  virtual void ClearGlobalAttribute(void);
2132 
2133  /**
2134  * Set global attribute.
2135  * The vGenerator does not have attributes, so this function throws an exception for
2136  * any specified attribute different to AttributeVoid.
2137  * The TaGenarator provides a re-implementation to actually set the global attribute.
2138  *
2139  * @param rAttr
2140  * Attribute
2141  * @exception Exception
2142  * - Cannot cast attribute (id 63)
2143  */
2144  virtual void GlobalAttribute(const Type& rAttr);
2145 
2146  /**
2147  * Set global attribute.
2148  * The vGenerator does not have attributes, so this function does nothing.
2149  * The TaGenarator provides a re-implementation to actually set the global attribute.
2150  *
2151  * @param rAttr
2152  * Attribute
2153  */
2154  virtual void GlobalAttributeTry(const Type& rAttr);
2155 
2156  /**
2157  * Global attribute lookup.
2158  * In a context where the attribute type is known,
2159  * you may prefer the TaGenerator method.
2160  */
2161  virtual const AttributeVoid& GlobalAttribute(void) const;
2162 
2163 
2164  /**
2165  * Get attribute pointer
2166  * The global attribute allways exits. For the vGenerator its of
2167  * type AttributeVoid, the TaGenerator sets a nontrivial type.
2168  * In a context where the attribute type is known,
2169  * you may prefer the TaGenerator method.
2170  */
2171  virtual AttributeVoid* GlobalAttributep(void);
2172 
2173 
2174  /** @} doxygen group */
2175 
2176 
2177 
2178  /*****************************************
2179  *****************************************
2180  *****************************************
2181  *****************************************/
2182 
2183  /** @name Reachability */
2184  /** @{ doxygen group */
2185 
2186 
2187  /**
2188  * Compute set of accessible states
2189  */
2190  StateSet AccessibleSet(void) const;
2191 
2192  /**
2193  * Make generator accessible.
2194  *
2195  * @return
2196  * True if generator contains at least one initial state
2197  */
2198  bool Accessible(void);
2199 
2200  /**
2201  * Check if generator is accessible
2202  *
2203  * @return
2204  * True if generator is accesssible
2205  */
2206  bool IsAccessible(void) const;
2207 
2208  /**
2209  * Compute set of Coaccessible states
2210  */
2211  StateSet CoaccessibleSet(void) const;
2212 
2213  /**
2214  * Make generator Coaccessible
2215  *
2216  * @return
2217  * True if generator contains at least one marked state
2218  */
2219  bool Coaccessible(void);
2220 
2221  /**
2222  * Check if generator is Coaccessible
2223  *
2224  * @return
2225  * True if generator is coaccessible
2226  */
2227  bool IsCoaccessible(void) const;
2228 
2229  /**
2230  * Compute set of blocking states.
2231  *
2232  * A state is considered blocking it is accessible but not coaccessible.
2233  */
2234  StateSet BlockingStates(void) const;
2235 
2236 
2237  /**
2238  * Compute set of terminal states.
2239  *
2240  * A terminal state is a state with no successor state.
2241  * If and only if the set of terminal states is empty, the generator is complete.
2242  * @return
2243  * Set of terminal states.
2244  */
2245  StateSet TerminalStates(void) const;
2246 
2247 
2248  /**
2249  * Compute set of terminal states.
2250  *
2251  * A terminal state is a state with no successor state.
2252  * This function returns the the set terminal states contained
2253  * in the specified state ste.
2254  *
2255  * @param rStates
2256  * Set of state indices to restrict the search
2257  * @return
2258  * Set of terminal states.
2259  */
2260  StateSet TerminalStates(const StateSet& rStates) const;
2261 
2262  /**
2263  * Check if generator is complete.
2264  *
2265  * A generator is considered complete, if each state has at least
2266  * one successor state.
2267  *
2268  * If the generator is accessible, completeness
2269  * is equivalent to completeness of the generated language, ie
2270  * forall s in L(G) there exists r>s such that r in L(G)
2271  *
2272  * If the generator is trim, completeness is equivalent to
2273  * completeness of the markede language, ie forall s in Lm(G) there exists
2274  * r>s such that r in Lm(G)
2275  *
2276  * @return
2277  * True if generator is complete
2278  */
2279  bool IsComplete(void) const;
2280 
2281  /**
2282  * Check if generator is complete.
2283  *
2284  * Same as IsComplete(void), however, only the specified
2285  * states are considered. The rational is to e.g. apply the test
2286  * to accessible (resp. trim) states only. Then, test is equivalent
2287  * to completeness of the generated (resp. marked) language.
2288  *
2289  * @param rStates
2290  * Set of state indices to restrict the completeness test
2291  * @return
2292  * True if generator is relatively complete
2293  */
2294  bool IsComplete(const StateSet& rStates) const;
2295 
2296 
2297  /**
2298  * Check if generator is complete w.r.t. an alphabet
2299  *
2300  * A generator is considered complete w.r.t. an alphabet Sigma_o,
2301  * if each state can be continued to a state in which a symbol
2302  * of Sigma_c is enabled.
2303  *
2304  * If the generator is accessible, completeness w.r.t. Sigma_o
2305  * is equivalent to:
2306  *
2307  * forall s in L(G) there exists t in (Sigma*)Sigma_u such that st in L(G)
2308  *
2309  * @param rSigmaO
2310  * Specified alphabet Sigma_o
2311  *
2312  * @return
2313  * True if generator is complete
2314  */
2315  bool IsComplete(const EventSet& rSigmaO) const;
2316 
2317 
2318  /**
2319  * Make generator Complete.
2320  *
2321  * This procedure removes all states that are guaranteed to evolve
2322  * into a terminal state within a finite number of transitios.
2323  * The current implementations is initialized by
2324  * the set of terminal states and then performs a backward
2325  * reachability analysis.
2326  *
2327  * @return
2328  * True if generator contains at least one initial state
2329  */
2330  bool Complete(void);
2331 
2332  /**
2333  * Make generator Complete w.r.t. an alphabet
2334  *
2335  * This procedure removes all states that conflict with
2336  * completes w.r.t. the specified alphabet Sigma_o until
2337  * a fixpoint is reached. The current implementation consists of
2338  * an outer iteration to restrict a domain of states and an inner iteration
2339  * for abcakwar reachability analyis.
2340  *
2341  * THIS IS EXPERIMENTAL / NEEDS TESTING
2342  *
2343  * @param rSigmaHi
2344  * Specified alphabet Sigma_o
2345  *
2346  * @return
2347  * True if generator contains at least one initial state
2348  */
2349  bool Complete(const EventSet& rSigmaO);
2350 
2351 
2352 
2353 
2354  /**
2355  * Compute set of trim states
2356  */
2357  StateSet TrimSet(void) const;
2358 
2359  /**
2360  * Make generator trim
2361  *
2362  * This function removes all states are not accessible or not
2363  * coaccessible. In other words: only those states are kept, that
2364  * contribute to that marked language.
2365  *
2366  * @return
2367  * True if resulting generator contains at least one initial state and at least one marked state.
2368  */
2369  bool Trim(void);
2370 
2371  /**
2372  * Check if generator is trim.
2373  *
2374  * Returns true if all states are rechable and coreachale.
2375  *
2376  * @return
2377  * True if generator is trim
2378  */
2379  bool IsTrim(void) const;
2380 
2381 
2382  /**
2383  * Make generator omega-trim
2384  *
2385  * This function removes states such that the generator becomes
2386  * omega trim while not affecting the induced omega language.
2387  *
2388  * The implementation first makes the generator accessible
2389  * and then iteratively removes state that either
2390  * never reach a marked state or that are guaranteed to eventually
2391  * reach a terminal state. There might be a more efficient
2392  * approach.
2393  *
2394  * @return
2395  * True if resulting generator contains at least one initial state and at least one marked state.
2396  */
2397  bool OmegaTrim(void);
2398 
2399 
2400  /**
2401  * Check if generator is omega-trim.
2402  *
2403  * Returns true if all states are accessible, coacessible, and
2404  * have a successor state.
2405  *
2406  * @return
2407  * True if generator is omega-trim
2408  */
2409  bool IsOmegaTrim(void) const;
2410 
2411 
2412 
2413  /** @} doxygen group */
2414 
2415  /*****************************************
2416  *****************************************
2417  *****************************************
2418  *****************************************/
2419 
2420  /** @name File IO */
2421  /** @{ doxygen group */
2422 
2423  /**
2424  * Write generators alphabet to console
2425  */
2426  void WriteAlphabet(void) const;
2427 
2428  /**
2429  * Write generators alphabet to string
2430  *
2431  * @return
2432  * std::string
2433  * @exception Exception
2434  * - IO errors (id 2)
2435  */
2436  std::string AlphabetToString(void) const;
2437 
2438  /**
2439  * Write generators alphabet to tokenwriter
2440  *
2441  * @param rTw
2442  * Reference to TokenWriter
2443  *
2444  * @exception Exception
2445  * - IO errors (id 2)
2446  */
2447  void WriteAlphabet(TokenWriter& rTw) const;
2448 
2449  /**
2450  * Write a stateset to console (no re-indexing).
2451  * Uses WriteStateSet(TokenWriter& rTw, const StateSet&) const to write
2452  * the specified state set to console referring to this generators state names.
2453  *
2454  * @param rStateSet
2455  * Reference to stateset
2456  */
2457  void WriteStateSet(const StateSet& rStateSet) const;
2458 
2459  /**
2460  * Write a stateset to string (no re-indexing).
2461  * Uses WriteStateSet(TokenWriter& rTw, const StateSet&) const to write
2462  * the specified state set to a string referring to this generators state names.
2463  *
2464  * @param rStateSet
2465  * Reference to stateset
2466  * @return
2467  * std::string
2468  * @exception Exception
2469  * - IO errors (id 2)
2470  */
2471  std::string StateSetToString(const StateSet& rStateSet) const;
2472 
2473  /**
2474  * Write a stateset to formated text (no re-indexing).
2475  * Uses WriteStateSet(TokenWriter& rTw, const StateSet&) const to write
2476  * the specified state set to a string referring to this generators state names.
2477  *
2478  * @param rStateSet
2479  * Reference to stateset
2480  * @return
2481  * std::string
2482  * @exception Exception
2483  * - IO errors (id 2)
2484  */
2485  std::string StateSetToText(const StateSet& rStateSet) const;
2486 
2487  /**
2488  * Write a stateset to TokenWriter.
2489  * All native output of external state sets done with this function.
2490  * Technically, a StateSet is a set of plain indices with no references
2491  * to symbolic names. Thus, it is only the context of a Generator that provides
2492  * the symbolic names for file output.
2493  *
2494  * Output of state sets always uses the mMinStateIndexMap to re-index states.
2495  * However, this map is only set up automatically for file output. If You require
2496  * re-indexed output to e.g. a string, you must set up the map by calling SetMinStateIndexMap().
2497  * To ensure that no re-indexing takes place, call ClearMinStateIndexMap().
2498  *
2499  * @param rTw
2500  * Reference to TokenWriter
2501  * @param rStateSet
2502  * Reference to stateset
2503  *
2504  * @exception Exception
2505  * - IO errors (id 2)
2506  */
2507  void WriteStateSet(TokenWriter& rTw, const StateSet& rStateSet) const;
2508 
2509  /**
2510  * Write a stateset to TokenWriter (debug version, no re-indexing)
2511  *
2512  * @param rTw
2513  * Reference to TokenWriter
2514  * @param rStateSet
2515  * Reference to stateset
2516  *
2517  * @exception Exception
2518  * - IO errors (id 2)
2519  */
2520  void DWriteStateSet(TokenWriter& rTw, const StateSet& rStateSet) const;
2521 
2522  /**
2523  * Write stateset of this generator to a string (no re-indexing)
2524  *
2525  * @return
2526  * std::string
2527  * @exception Exception
2528  * - IO errors (id 2)
2529  */
2530  std::string StatesToString(void) const;
2531 
2532  /**
2533  * Write stateset of this generator to formated text (no re-indexing)
2534  *
2535  * @return
2536  * std::string
2537  * @exception Exception
2538  * - IO errors (id 2)
2539  */
2540  std::string StatesToText(void) const;
2541 
2542  /**
2543  * Write set of marked states to a string (no re-indexing)
2544  *
2545  * @return
2546  * std::string
2547  * @exception Exception
2548  * - IO errors (id 2)
2549  */
2550  std::string MarkedStatesToString(void) const;
2551 
2552  /**
2553  * Write set of initial states to a string (no re-indexing)
2554  *
2555  * @return
2556  * std::string
2557  * @exception Exception
2558  * - IO errors (id 2)
2559  */
2560  std::string InitStatesToString(void) const;
2561 
2562  /**
2563  * Write transition relation to console (no re-indexing)
2564  */
2565  void WriteTransRel(void) const;
2566 
2567  /**
2568  * Write transition relation to string (no re-indexing)
2569  */
2570  std::string TransRelToString(void) const;
2571 
2572  /**
2573  * Write transition relation to formated text (no re-indexing)
2574  */
2575  std::string TransRelToText(void) const;
2576 
2577  /**
2578  * Write transition relation to tokenwriter.
2579  * Re-indexing and symbolic state names are handled in the same way
2580  * as with state sets: this function refers to the generators state symboltable to
2581  * obtain state names and uses the mMinStateIndexMap to re-index the output.
2582  *
2583  * @param rTw
2584  * Reference to TokenWriter
2585  *
2586  * @exception Exception
2587  * - IO errors (id 2)
2588  */
2589  void WriteTransRel(TokenWriter& rTw) const;
2590 
2591  /**
2592  * Write transition relation to tokenwriter (debug version)
2593  * @param rTw
2594  * Reference to TokenWriter
2595  *
2596  * @exception Exception
2597  * - IO errors (id 2)
2598  */
2599  void DWriteTransRel(TokenWriter& rTw) const;
2600 
2601 
2602  /**
2603  * Writes generator to dot input format.
2604  * The dot file format is specified by the graphiz package; see http://www.graphviz.org.
2605  * The package includes the dot command line tool to generate a graphical
2606  * representation of the generators graph. See also GraphWrite().
2607  * This functions sets the re-indexing to minimal indices.
2608  *
2609  * @param rFileName
2610  * File to write
2611  *
2612  * @exception Exception
2613  * - IO errors (id 2)
2614  */
2615  virtual void DotWrite(const std::string& rFileName) const;
2616 
2617  /**
2618  * Writes generator to dot input format (no re-indexing).
2619  * Variant of DotWrite() without re-indexing.
2620  *
2621  * @param rFileName
2622  * File to write
2623  *
2624  * @exception Exception
2625  * - IO errors (id 2)
2626  */
2627  virtual void DDotWrite(const std::string& rFileName) const;
2628 
2629  /**
2630  * Writes generator to dot input format for export to VioLib.
2631  * Variant of DotWrite() using strategic state and event names
2632  * to simplify import to VioLib (qt widget for graphical representation
2633  * of FAUDES generators).
2634  *
2635  * @param rFileName
2636  * File to write
2637  * @exception Exception
2638  * - IO errors (id 2)
2639  */
2640  virtual void XDotWrite(const std::string& rFileName) const;
2641 
2642  /**
2643  * Read a state set.
2644  * Refer to the generators state symboltable while reading a state set.
2645  * Ignore any attributes.
2646  *
2647  * @param rTr
2648  * Reference to TokenReader
2649  * @param rLabel
2650  * Label of set in source
2651  * @param rStateSet
2652  * Destination state set
2653  *
2654  * @exception Exception
2655  * - IO errors (id 1)
2656  * - token mismatch (id 50, 51, 52, 80, 85)
2657  */
2658  void ReadStateSet(TokenReader& rTr, const std::string& rLabel, StateSet& rStateSet) const;
2659 
2660 
2661  /**
2662  * Test whether file-i/o uses minimal state indicees.
2663  *
2664  * @return
2665  * True when minimal state indicees are enabled
2666  */
2667  bool ReindexOnWrite(void) const;
2668 
2669  /**
2670  * Enable/disable minimal state indicees for file-i/o.
2671  *
2672  * @param flag
2673  * True enables reindexing.
2674  */
2675  void ReindexOnWrite(bool flag);
2676 
2677 
2678  /**
2679  * Enable/disable reindexing states for file-i/o.
2680  *
2681  * Set default value for re-indexing. Initially, the default
2682  * is set to "false".
2683  *
2684  * @param flag
2685  * True enables reindexing.
2686  */
2687  static void ReindexOnWriteDefault(bool flag);
2688 
2689 
2690  /**
2691  * Enable/disable reindexing states for file-i/o.
2692  *
2693  * Set default value for re-indexing.
2694  *
2695  * @return
2696  * True for reindexing enabled.
2697  */
2698  static bool ReindexOnWriteDefault(void);
2699 
2700 
2701  /** @} doxygen group */
2702 
2703 
2704  /*****************************************
2705  *****************************************
2706  *****************************************
2707  *****************************************/
2708 
2709  /** @name Misc */
2710  /** @{ doxygen group */
2711 
2712  /**
2713  * Return used events (executed in transitions)
2714  *
2715  * @return EventSet
2716  */
2717  EventSet UsedEvents(void) const;
2718 
2719  /**
2720  * Return unused events
2721  *
2722  * @return EventSet
2723  */
2724  EventSet UnusedEvents(void) const;
2725 
2726  /**
2727  * Set the alphabet to used events
2728  */
2729  void MinimizeAlphabet(void);
2730 
2731  /**
2732  * Return active event set at state x1
2733  *
2734  * @param x1
2735  * Index of x1
2736  *
2737  * @return EventSet
2738  */
2739  EventSet ActiveEventSet(Idx x1) const;
2740 
2741  /**
2742  * Return active transition set at state x1
2743  *
2744  * @param x1
2745  * Index of x1
2746  *
2747  * @return EventSet
2748  */
2749  TransSet ActiveTransSet(Idx x1) const;
2750 
2751  /**
2752  * Return the states covered by transitions
2753  *
2754  * @return StateSet
2755  */
2756  StateSet TransRelStates(void) const;
2757 
2758  /**
2759  * Return the successor state of state x1 with event ev.
2760  * If no such transition exists, return 0.
2761  * If multiple such transitions exit, through expection.
2762  *
2763  * A more egeneral set valued interface is provided by TransSet
2764  *
2765  * @return next state
2766  * @exception Exception
2767  * - Successor state does not exist uniquely (id 92)
2768  */
2769  Idx SuccessorState(Idx x1, Idx ev) const;
2770 
2771  /**
2772  * Return the successor states of state x1
2773  *
2774  * @return StateSet
2775  */
2776  StateSet SuccessorStates(Idx x1) const;
2777 
2778  /**
2779  * Return the successor states of state x1 with event ev
2780  *
2781  * @return StateSet
2782  */
2783  StateSet SuccessorStates(Idx x1, Idx ev) const;
2784 
2785  /**
2786  * Check if generator is deterministic.
2787  *
2788  * We require the transition relation to be a partial function
2789  * and at most one initial state.
2790  *
2791  * Note: pre 2.19 libFAUDES also insisted in exactly one initial state.
2792  *
2793  *
2794  * @return
2795  * True if generator is deterministic
2796  */
2797  bool IsDeterministic(void) const;
2798 
2799  /**
2800  * Set minimal index map for file io of generator states
2801  *
2802  * This function is implemented as fake-const to allow for
2803  * const Write function.
2804  *
2805  */
2806  void SetMinStateIndexMap(void) const;
2807 
2808  /**
2809  * Clear minimal index map for 1:1 file io
2810  *
2811  */
2812  void ClearMinStateIndexMap(void) const;
2813 
2814  /**
2815  * Get state index as is it will be written to file.
2816  *
2817  * @param index
2818  * state index
2819  * @return
2820  * minimal index
2821  */
2822  Idx MinStateIndex(Idx index) const;
2823 
2824 
2825  /**
2826  * Re-enumerate states.
2827  *
2828  * This method re-enumerates states such that the resulting
2829  * state set consist of consecutive indexes; i.e. Size()=MaxStateIndex().
2830  * The current implementation sets up the minimal-state-index map used for
2831  * file i/o and applies it to the state set and the transition relation.
2832  *
2833  * Note: libFAUDES does not maintain consecutive state indices.
2834  * This was a design decision and it comes pros and cons. The method MinStateIndex()
2835  * was implemented to provide some limited support for the implementation of algorithms in a
2836  * consecutive state enumeration paradigm. However, mixing both paradigms most likely
2837  * involves an overall performace penalty.
2838  */
2839  void MinStateIndex(void);
2840 
2841 
2842  /**
2843  * Get maximum state index used in this generator.
2844  * Returns 0 if no states at all.
2845  * @return
2846  * maximal index
2847  */
2848  Idx MaxStateIndex(void) const;
2849 
2850 
2851  /**
2852  * Get state index translation map
2853  *
2854  * @return
2855  * minimal index map
2856  */
2857  const std::map<Idx,Idx>& MinStateIndexMap(void) const;
2858 
2859 
2860  /**
2861  * Pretty printable event name for index (eg for debugging).
2862  *
2863  * @param index
2864  * Event index
2865  *
2866  * @return
2867  * std::string
2868  */
2869  std::string EStr(Idx index) const;
2870 
2871  /**
2872  * Return pretty printable state name for index (eg for debugging)
2873  *
2874  * @param index
2875  * State index
2876  *
2877  * @return
2878  * std::string
2879  */
2880  std::string SStr(Idx index) const;
2881 
2882 
2883  /**
2884  * Return pretty printable transition (eg for debugging)
2885  *
2886  * @param rTrans
2887  * Transition
2888  *
2889  * @return
2890  * std::string
2891  */
2892  std::string TStr(const Transition& rTrans) const;
2893 
2894 
2895  /**
2896  * Produce graphical representation of this generator.
2897  * This method calls the generator's DotWrite function and then processes the output
2898  * with the dot tool from graphiz package. If no output format is given,
2899  * try to guess from filename extension. See also ProcessDot().
2900  *
2901  * @param rFileName
2902  * Name of output file
2903  * @param rOutFormat
2904  * Graphics file format, eg "png", "jpg", "svg"
2905  * @param rDotExec
2906  * path/name of executable
2907  * @exception Exception
2908  * - IO errors (id 2)
2909  * - error during systemcall for dot (id 3)
2910  */
2911  void GraphWrite(const std::string& rFileName, const std::string& rOutFormat="",
2912  const std::string& rDotExec="dot") const;
2913 
2914  /**
2915  * Order for sorting containers of generators
2916  */
2917  bool operator < (const vGenerator& rOtherGen) const {
2918  return (mId < rOtherGen.mId);
2919  }
2920 
2921 
2922  /** @} doxygen group */
2923 
2924 
2925  protected:
2926 
2927  /** Name of generator */
2928  std::string mMyName;
2929 
2930  /** Number of generator */
2932 
2933  /** Number of generator objects */
2935 
2936  /** State symbol table (local per Generator)*/
2938 
2939  /** Pointer to State symbol table */
2941 
2942  /** Pointer to Event symbol table */
2944 
2945  /** Automatic state names */
2947 
2948  /** Default for automatic statenames */
2950 
2951  /** Reindex states on file-i/o */
2953 
2954  /** Default for automatic statenames */
2956 
2957  /** Pointer to alphabet (actual type depends on attributes) */
2959 
2960  /** Pointer to state set (actual type depends on attributes) */
2962 
2963  /** Pointer to ransition relation (actual type depends on attributes) */
2965 
2966  /** Pointer to lobal attribute (actual type depends on attributes) */
2968 
2969  /** Pointer to alphabet prototype (incl. attribute type) */
2971 
2972  /** Pointer to state set prototype (incl. attribute type) */
2974 
2975  /** Pointer to transition relation prototype (incl. attribute type) */
2977 
2978  /** Pointer to global attribute prototype (configures global attribute type) */
2980 
2981  /** Static default alphabet prototype (incl. attribute type) */
2982  static const EventSet& AlphabetVoid(void);
2983 
2984  /** Static default state set prototype (incl. attribute type) */
2985  static const StateSet& StatesVoid(void);
2986 
2987  /** Static default transition relation prototype (incl. attribute type) */
2988  static const TransSet& TransRelVoid(void);
2989 
2990  /** Static default global attribute prototype (configures global attribute type) */
2991  static const AttributeVoid& GlobalVoid(void);
2992 
2993  /** Initial states */
2995 
2996  /** Marked states */
2998 
2999  /** Map State indices to consecutive indices */
3000  std::map<Idx,Idx> mMinStateIndexMap;
3001 
3002  /** Allocate my heap members (attribute dependent types) */
3003  virtual void NewCore(void);
3004 
3005  /** Free my heap members (attribute dependent types) */
3006  virtual void DeleteCore(void);
3007 
3008  /** Callback for core update */
3009  virtual void UpdateCore(void);
3010 
3011  /** Configure attribute types */
3012  void ConfigureAttributeTypes(const AttributeVoid* pNewGlobalPrototype,
3013  const StateSet* pNewStatesPrototype, const EventSet* pNewAlphabetPrototype,
3014  const TransSet* pNewTransRelPrototype);
3015 
3016  /**
3017  * Read generator object from TokenReader, see Type::Read for public wrappers.
3018  *
3019  * Virtual function for std token io interface. Context is ignored,
3020  * label defaults to "Generator".
3021  *
3022  * @param rTr
3023  * TokenReader to read from
3024  * @param rLabel
3025  * Section to read
3026  * @param pContext
3027  * Read context to provide contextual information (ignored)
3028  *
3029  * @exception Exception
3030  * - token mismatch (id 50, 51, 52, 80, 85)
3031  * - IO error (id 1)
3032  */
3033  virtual void DoRead(TokenReader& rTr, const std::string& rLabel = "", const Type* pContext=0);
3034 
3035  /**
3036  * Write generator to TokenWriter, see Type::Write for public wrappers.
3037  *
3038  * Virtual function for std token io interface. Context is ignored,
3039  * label defaults to "Generator". If the tokenwriter writes to a file,
3040  * state indices will be re-indext to start from 1.
3041  *
3042  * @param rTw
3043  * Reference to TokenWriter
3044  * @param rLabel
3045  * Label of section to write
3046  * @param pContext
3047  * Write context to provide contextual information (ignored)
3048  *
3049  * @exception Exception
3050  * - IO errors (id 2)
3051  */
3052  virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
3053 
3054  /**
3055  * Write generator in debugging format to TokenWriter, see Type::DWrite for public wrappers.
3056  *
3057  * Reimplement this method in derived classes to provide the std token io
3058  * interface defined in the public section of Type.
3059  *
3060  * @param rTw
3061  * Reference to TokenWriter
3062  * @param rLabel
3063  * Label of section to write
3064  * @param pContext
3065  * Write context to provide contextual information (ignored)
3066  *
3067  * @exception Exception
3068  * - IO errors (id 2)
3069  */
3070  virtual void DoDWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
3071 
3072  /**
3073  * Write generator statistics as comment to TokenWriter, see Type::SWrite for public wrappers.
3074  *
3075  * Reimplement this method in derived classes to provide the std token io
3076  * interface defined in the public section of Type.
3077  *
3078  * @param rTw
3079  * Reference to TokenWriter
3080  *
3081  * @exception Exception
3082  * - IO errors (id 2)
3083  */
3084  virtual void DoSWrite(TokenWriter& rTw) const;
3085 
3086  /**
3087  * Write generator to TokenWriter, see Type::XWrite for public wrappers.
3088  *
3089  * Virtual function for std token io interface. Context is ignored,
3090  * label defaults to "Generator".
3091  *
3092  * @param rTw
3093  * Reference to TokenWriter
3094  * @param rLabel
3095  * Label of section to write
3096  * @param pContext
3097  * Write context to provide contextual information (ignored)
3098  *
3099  * @exception Exception
3100  * - IO errors (id 2)
3101  */
3102  virtual void DoXWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
3103 
3104  /**
3105  * Read the generator's alphabet from a TokenReader.
3106  * As of 2.24e, this method returns silently if no alphabet-tag is found.
3107  *
3108  * @param rTr
3109  * Reference to TokenReader
3110  *
3111  * @exception Exception
3112  * - IO errors (id 1)
3113  * - token mismatch (id 50, 51, 52)
3114  */
3115  void ReadAlphabet(TokenReader& rTr);
3116 
3117  /**
3118  * Write generators stateset to TokenWriter.
3119  *
3120  * This method differs from the general purpos version
3121  * WriteStateSet(TokenWriter&, const StateSet&) in that it
3122  * can optionally write an explicit symbol table for state names.
3123  * This will happen whenever writing is done without re-indexing
3124  * states.
3125  *
3126  * @param rTw
3127  * Reference to TokenWriter
3128  * @param rStateSet
3129  * Reference to stateset
3130  *
3131  * @exception Exception
3132  * - IO errors (id 2)
3133  */
3134  void WriteStates(TokenWriter& rTw) const;
3135 
3136  /**
3137  * Read the generator's stateset from a TokenReader.
3138  * This sets up the StateSymbolTable.
3139  * As of 2.24e, this method returns silently if no alphabet-tag is found.
3140  *
3141  * @param rTr
3142  * Reference to TokenReader
3143  * @exception Exception
3144  * - IO errors (id 1)
3145  * - token mismatch (id 50, 51, 52)
3146  */
3147  void ReadStates(TokenReader& rTr);
3148 
3149  /**
3150  * Read a stateset from TokenReader in XML format.
3151  *
3152  * This version for file IO supports the XML format introduced with libFAUDES 2.20.
3153  * Note that for Generators and derived classes, the native libFAUDES token
3154  * format is considered the default. To read XML fromated data,
3155  * use the XRead() interface.
3156  *
3157  * @param rTr
3158  * Reference to TokenReader
3159  * @param rStateSet
3160  * Reference to stateset
3161  * @param rLabel
3162  * Section name, defaults to name of set
3163  *
3164  * @exception Exception
3165  * - IO errors (id 1)
3166  * - token mismatch (id 50, 51, 52)
3167  */
3168  void XReadStateSet(TokenReader& rTr, StateSet& rStateSet, const std::string& rLabel="") const;
3169 
3170  /**
3171  * Read the generator's transition relation from a file.
3172  *
3173  * @param rFileName
3174  * File to read from
3175  *
3176  * @exception Exception
3177  * - IO errors (id 1)
3178  * - token mismatch (id 50, 51, 52)
3179  */
3180  void ReadTransRel(const std::string& rFileName);
3181 
3182  /**
3183  * Read the generator's transition relation from a TokenReader.
3184  *
3185  * @param rTr
3186  * Reference to TokenReader
3187  *
3188  * @exception Exception
3189  * - IO errors (id 1)
3190  * - token mismatch (id 50, 51, 52)
3191  */
3192  void ReadTransRel(TokenReader& rTr);
3193 
3194  /**
3195  * Read the generator's transition relation from a TokenReader.
3196  *
3197  * @param rTr
3198  * Reference to TokenReader
3199  *
3200  * @exception Exception
3201  * - IO errors (id 1)
3202  * - token mismatch (id 50, 51, 52)
3203  */
3204  void XReadTransRel(TokenReader& rTr);
3205 
3206  /**
3207  * Write a stateset to TokenWriter in XML format.
3208  *
3209  * This version for file IO supports the XML format introduced with libFAUDES 2.20.
3210  * Note that for Generators and derived classes, the native libFAUDES token
3211  * format is considered the default. To obtain XML fromated output of a Generator,
3212  * use the XWrite() interface.
3213  *
3214  * @param rTw
3215  * Reference to TokenWriter
3216  * @param rStateSet
3217  * Reference to stateset
3218  * @param rLabel
3219  * Section name, defaults to name of set
3220  *
3221  * @exception Exception
3222  * - IO errors (id 2)
3223  */
3224  void XWriteStateSet(TokenWriter& rTw, const StateSet& rStateSet, const std::string& rLabel="") const;
3225 
3226  /**
3227  * Write transition relation to tokenwriter in XML format.
3228  *
3229  * This version for file IO supports the XML format introduced with libFAUDES 2.20.
3230  * Note that for Generators and derived classes, the native libFAUDES token
3231  * format is considered the default. To obtain XML fromated output of a Generator,
3232  * use the XWrite() interface.
3233  *
3234  *
3235  * @param rTw
3236  * Reference to TokenWriter
3237  *
3238  * @exception Exception
3239  * - IO errors (id 2)
3240  */
3241  void XWriteTransRel(TokenWriter& rTw) const;
3242 
3243 
3244 };
3245 
3246 /**
3247  * Plain generator, api typedef for generator with no attributes.
3248  * \ingroup GeneratorClasses
3249  */
3251 
3252 /**
3253  * Convenience typedef for vectors og generators
3254  * \ingroup GeneratorClasses
3255  */
3257 
3258 
3259 /**
3260  * RTI wrapper function. See also vGenerator::IsAccessible().
3261  * \ingroup GeneratorFunctions
3262  */
3263 bool IsAccessible(const vGenerator& rGen);
3264 
3265 /**
3266  * RTI wrapper function. See also vGenerator::IsCoaccessible().
3267  * \ingroup GeneratorFunctions
3268  */
3269 bool IsCoaccessible(const vGenerator& rGen);
3270 
3271 /**
3272  * RTI wrapper function. See also vGenerator::IsTrim().
3273  * \ingroup GeneratorFunctions
3274  */
3275 bool IsTrim(const vGenerator& rGen);
3276 
3277 /**
3278  * RTI wrapper function. See also vGenerator::IsOmegaTrim().
3279  * \ingroup GeneratorFunctions
3280  */
3281 bool IsOmegaTrim(const vGenerator& rGen);
3282 
3283 /**
3284  * RTI wrapper function. See also vGenerator::IsComplete().
3285  * \ingroup GeneratorFunctions
3286  */
3287 bool IsComplete(const vGenerator& rGen);
3288 
3289 /**
3290  * RTI wrapper function. See also vGenerator::IsComplete().
3291  * \ingroup GeneratorFunctions
3292  */
3293 bool IsComplete(const vGenerator& rGen, const EventSet& rSigmaO);
3294 
3295 /**
3296  * RTI wrapper function. See also vGenerator::IsDeterministic().
3297  * \ingroup GeneratorFunctions
3298  */
3299 bool IsDeterministic(const vGenerator& rGen);
3300 
3301 
3302 /**
3303  * RTI wrapper function. See also vGenerator::Accessible().
3304  * \ingroup GeneratorFunctions
3305  */
3306 void Accessible(vGenerator& rGen);
3307 
3308 /**
3309  * RTI wrapper function. See also vGenerator::Accessible().
3310  * \ingroup GeneratorFunctions
3311  */
3312 void Accessible(const vGenerator& rGen, vGenerator& rRes);
3313 
3314 /**
3315  * RTI wrapper function. See also vGenerator::Coaccessible().
3316  * \ingroup GeneratorFunctions
3317  */
3318 void Coaccessible(vGenerator& rGen);
3319 
3320 /**
3321  * RTI wrapper function. See also vGenerator::Coaccessible().
3322  * \ingroup GeneratorFunctions
3323  */
3324 void Coaccessible(const vGenerator& rGen, vGenerator& rRes);
3325 
3326 /**
3327  * RTI wrapper function. See also vGenerator::Complete().
3328  * \ingroup GeneratorFunctions
3329  */
3330 void Complete(vGenerator& rGen);
3331 
3332 /**
3333  * RTI wrapper function. See also vGenerator::Complete().
3334  * \ingroup GeneratorFunctions
3335  */
3336 void Complete(const vGenerator& rGen, vGenerator& rRes);
3337 
3338 /**
3339  * RTI wrapper function. See also vGenerator::Complete().
3340  * \ingroup GeneratorFunctions
3341  */
3342 void Complete(vGenerator& rGen, const EventSet& rSigmaO);
3343 
3344 /**
3345  * RTI wrapper function. See also vGenerator::Complete().
3346  * \ingroup GeneratorFunctions
3347  */
3348 void Complete(const vGenerator& rGen, const EventSet& rSigmaO, vGenerator& rRes);
3349 
3350 /**
3351  * RTI wrapper function. See also vGenerator::Trim().
3352  * \ingroup GeneratorFunctions
3353  */
3354 void Trim(vGenerator& rGen);
3355 
3356 /**
3357  * RTI wrapper function. See also vGenerator::Trim().
3358  * \ingroup GeneratorFunctions
3359  */
3360 void Trim(const vGenerator& rGen, vGenerator& rRes);
3361 
3362 /**
3363  * RTI wrapper function. See also vGenerator::OmegaTrim().
3364  * \ingroup GeneratorFunctions
3365  */
3366 void OmegaTrim(vGenerator& rGen);
3367 
3368 /**
3369  * RTI wrapper function. See also vGenerator::OmegaTrim().
3370  * \ingroup GeneratorFunctions
3371  */
3372 void OmegaTrim(const vGenerator& rGen, vGenerator& rRes);
3373 
3374 /**
3375  * RTI wrapper function.
3376  * \ingroup GeneratorFunctions
3377  */
3378 void MarkAllStates(vGenerator& rGen);
3379 
3380 /**
3381  * RTI wrapper function.
3382  * \ingroup GeneratorFunctions
3383  */
3384 void AlphabetExtract(const vGenerator& rGen, EventSet& rRes);
3385 
3386 
3387 /**
3388  * RTI convenience function.
3389  */
3390 void SetIntersection(const vGenerator& rGenA, const vGenerator& rGenB, EventSet& rRes);
3391 
3392 /**
3393  * RTI convenience function.
3394  */
3395 void SetIntersection(const GeneratorVector& rGenVec, EventSet& rRes);
3396 
3397 /**
3398  * RTI convenience function.
3399  */
3400 void SetUnion(const vGenerator& rGenA, const vGenerator& rGenB, EventSet& rRes);
3401 
3402 /**
3403  * RTI convenience function.
3404  */
3405 void SetUnion(const GeneratorVector& rGenVec, EventSet& rRes);
3406 
3407 /**
3408  * RTI convenience function.
3409  */
3410 void SetDifference(const vGenerator& rGenA, const vGenerator& rGenB, EventSet& rRes);
3411 
3412 
3413 
3414 
3415 } // namespace faudes
3416 
3417 /*
3418 
3419 #define FAUDES_GENERATOR_DECLARATION(gtype,GlobalAttr,StateAttr,EventAttr,TransAttr) \
3420  public: \
3421  virtual void EventAttribute(Idx index, const EventAttr& rAttr); \
3422  virtual void EventAttributes(const TaEventSet<EventAttr>& rEventSet); \
3423  virtual const EventAttr& EventAttribute(Idx index) const; \
3424  virtual const EventAttr& EventAttribute(const std::string& rName) const; \
3425  virtual EventAttr* EventAttributep(Idx index); \
3426  virtual EventAttr* EventAttributep(const std::string& rName); \
3427  virtual void StateAttribute(Idx index, const StateAttr& rAttr); \
3428  virtual const StateAttr& StateAttribute(Idx index) const; \
3429  virtual StateAttr* StateAttributep(Idx index); \
3430  virtual void TransAttribute(const Transition& rTrans, const TransAttr& rAttr); \
3431  virtual const TransAttr& TransAttribute(const Transition& rTrans) const; \
3432  virtual TransAttr* TransAttributep(const Transition& rTrans); \
3433  virtual void GlobalAttribute(const GlobalAttr& rAttr); \
3434  virtual void GlobalAttributeTry(const Type& rAttr); \
3435  virtual const GlobalAttr& GlobalAttribute(void) const; \
3436  virtual GlobalAttr* GlobalAttributep(void);
3437 
3438 #define FAUDES_GENERATOR_IMPLEMENTATION(gtype,GlobalAttr,StateAttr,EventAttr,TransAttr) \
3439  public: \
3440  virtual void EventAttribute(Idx index, const EventAttr& rAttr); \
3441  virtual void EventAttributes(const TaEventSet<EventAttr>& rEventSet); \
3442  virtual const EventAttr& EventAttribute(Idx index) const; \
3443  virtual const EventAttr& EventAttribute(const std::string& rName) const; \
3444  virtual EventAttr* EventAttributep(Idx index); \
3445  virtual EventAttr* EventAttributep(const std::string& rName); \
3446  virtual void StateAttribute(Idx index, const StateAttr& rAttr); \
3447  virtual const StateAttr& StateAttribute(Idx index) const; \
3448  virtual StateAttr* StateAttributep(Idx index); \
3449  virtual void TransAttribute(const Transition& rTrans, const TransAttr& rAttr); \
3450  virtual const TransAttr& TransAttribute(const Transition& rTrans) const; \
3451  virtual TransAttr* TransAttributep(const Transition& rTrans); \
3452  virtual void GlobalAttribute(const GlobalAttr& rAttr); \
3453  virtual void GlobalAttributeTry(const Type& rAttr); \
3454  virtual const GlobalAttr& GlobalAttribute(void) const; \
3455  virtual GlobalAttr* GlobalAttributep(void);
3456 
3457 */
3458 
3459 
3460 #endif
3461 

libFAUDES 2.24g --- 2014.09.15 --- c++ api documentaion by doxygen