cfl_attributes.h
Go to the documentation of this file.
1 /** @file cfl_attributes.h Classes AttributeVoid and AttributeFlags */
2 
3 
4 /* FAU Discrete Event Systems Library (libfaudes)
5 
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 MERCHANTABILITY or FITNESS 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_ATTRIBUTES_H
25 #define FAUDES_ATTRIBUTES_H
26 
27 #include "cfl_types.h"
28 #include "cfl_registry.h"
29 #include "cfl_tokenreader.h"
30 #include "cfl_tokenwriter.h"
31 
32 namespace faudes {
33 
34 
35 /**
36  * Minimal Attribute. Attributes are used as template parameters for
37  * faudes containers and generators and facilitate the modelling of customized
38  * properties of events, states and transitions. The AttributeVoid class defines
39  * the minimal interface of faudes attributes and therefore is the designated
40  * base class for all attribute implementations. The AttributeVoid class does
41  * not define any actual properties. See AttributeFlags for a non-trivial example.
42  *
43  * To derive a class from AttributeVoid you should reimplement the virtual
44  * interface
45  * - virtual methody DoRead and DoWrtie for token io (as in faudes::Type)
46  * - virtual methods for DoAssign() (as in faudes::Type)
47  * - the factory method New() (use provided macro from faudes::Type)
48  * - the rti typecast method Cast() (use provided macro from faudes::Type)
49  * - user level Assign() method (use provided macro from faudes::Type)
50  */
51 
52 class AttributeVoid : public Type {
53 
55 
56 public:
57 
58  /** Constructor */
59  AttributeVoid(void);
60 
61  /** Destructor */
62  virtual ~AttributeVoid(void);
63 
64  /**
65  * Test for default value.
66  */
67  virtual bool IsDefault(void) const {return true;};
68 
69  /**
70  * Set to default value.
71  * Derived classes must reimplement this function for Clear to operate properly.
72  */
73  virtual void SetDefault(void) {};
74 
75  /**
76  * Synonym for SetDefault to match std interface
77  */
78  virtual void Clear(void) { SetDefault(); };
79 
80  /**
81  * Skip attribute tokens.
82  *
83  * Helper method to be called after all sttribute derived classes had their
84  * chance to read their data. It skips all tokens and sections until it reaches a
85  * String or decimal Integer.
86  *
87  * @param rTr
88  * TokenReader to read from
89  * @exception Exception
90  * - IO error (id 1)
91  */
92  static void Skip(TokenReader& rTr);
93 
94 protected:
95 
96  /**
97  * Assign attribute members.
98  * Since AttributeVoid has no members, this method does nothing.
99  * Derived classes are meant to reimplement DoAssign by first calling
100  * their base and then assigning additional member variables.
101  *
102  * @param rSrcAttr
103  * Source to assign from
104  */
105  virtual void DoAssign(const AttributeVoid& rSrcAttr) { (void) rSrcAttr; };
106 
107  /**
108  * Test equality of configuration data.
109  * Derived attributes should reimplement this class to compare
110  * configuration data. The base AttributeVoid returns true as a default.
111  * @param rOther
112  * Other object to compare with.
113  * @return
114  * True on match.
115  */
116  virtual bool DoEqual(const AttributeVoid& rOther) const { (void) rOther; return true; }
117 
118  /**
119  * Actual read method to read attribute from tokenreader.
120  *
121  * For derived attributue classes, this method must either read all tokens that
122  * belong to the respective attribute, or none. It may throw exceptions on token
123  * mismatch within the relevant attribute, but it may not throw exceptions when
124  * it encounters tokens that possibly belong to another attribute. The latter are
125  * to be skipped by the provided Skip method. See Type::Read
126  * for public wrappers.
127  *
128  * @param rTr
129  * TokenReader to read from
130  * @param rLabel
131  * Section to read
132  * @param pContext
133  * Read context to provide contextual information
134  *
135  * @exception Exception
136  * - IO error (id 1)
137  */
138  virtual void DoRead(TokenReader& rTr, const std::string& rLabel = "", const Type* pContext=0);
139 
140  /**
141  * Actual write method to write the attribute to a TokenWriter.
142  *
143  * Reimplement this method for derived attribute classes to define the token io
144  * format. See Type::Write for public wrappers.
145  *
146  * @param rTw
147  * Reference to TokenWriter
148  * @param rLabel
149  * Label of section to write
150  * @param pContext
151  * Write context to provide contextual information
152  *
153  * @exception Exception
154  * - IO errors (id 2)
155  */
156  virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
157 
158 
159 
160 }; // class AttributeVoid
161 
162 
163 /** Convenience typdef flag data */
164 typedef unsigned long int fType;
165 
166 /**
167  * Boolean flags Attribute. This attribute class uses a flag word to represent
168  * boolean values. The current implementation uses a long int type and hence handles
169  * up to 32 flags. Each flag is accessed by the according bit mask.
170  *
171  * The current version
172  * of libFAUDES uses bits 0,1,2 of event attributes for controllability properties
173  * (see AttributeCFlags) and the bits 31 and 32 of state attributes for the Qt based
174  * GUI project. Further versions may use the lower 8 bits of the event aflags and the higher 8
175  * bits of state flags. You are free to use any flags for your application, but if possible try
176  * to avoid the above mentioned. For extensive use of flags, you may also consider to
177  * define a separate attribute class, perhaps with a different fType.
178  */
179 
180 
181 
183 
185 
186 public:
187 
188  /** Default constructor */
190 
191  /** Copy constructor */
192  AttributeFlags(const AttributeFlags& rOther) : AttributeVoid(), mFlags(rOther.mFlags) {};
193 
194  /** Destructor */
195  virtual ~AttributeFlags(void) {};
196 
197  /**
198  * Test a flag
199  */
200  bool Test(fType mask) const { return ( (mFlags & mask) != 0 ); };
201 
202  /**
203  * Test multible flags, combine by "and"
204  */
205  bool TestAll(fType mask) const { return ( (mFlags & mask) == mask ); };
206 
207  /**
208  * Test multible flags, combine by "or"
209  */
210  bool TestSome(fType mask) const { return ( (mFlags & mask) != 0 ); };
211 
212  /**
213  * Test multible flags, combine by "not or"
214  */
215  bool TestNone(fType mask) const { return ( (mFlags & mask) == 0 ); };
216 
217  /**
218  * Set multiple flags
219  */
220  void Set(fType mask) {mFlags |= mask; };
221 
222  /**
223  * Clear multiple flags
224  */
225  void Clr(fType mask) {mFlags &= ~mask; };
226 
227  /**
228  * Test for default value
229  */
230  virtual bool IsDefault(void) const {return mFlags==mDefFlags;};
231 
232  /** Flags (public access for convenience) */
233  fType mFlags;
234 
235  /* default flags */
236  const static fType mDefFlags=0x0;
237 
238 
239 protected:
240 
241  /**
242  * Assignment method.
243  *
244  * @param rSrcAttr
245  * Source to assign from
246  */
247  void DoAssign(const AttributeFlags& rSrcAttr);
248 
249  /**
250  * Test equality of configuration data.
251  *
252  * @param rOther
253  * Other object to compare with.
254  * @return
255  * True on match.
256  */
257  virtual bool DoEqual(const AttributeFlags& rOther) const;
258 
259 
260  /**
261  * Reads attribute from TokenReader, see Type for public wrappers.
262  *
263  * Test whether the current token is an integer with base 16. If so, read the token to the
264  * flags value. Else, dont take any tokens. The label and context arguments are ignored.
265  *
266  * @param rTr
267  * TokenReader to read from
268  * @param rLabel
269  * Section to read
270  * @param pContext
271  * Read context to provide contextual information
272  *
273  * @exception Exception
274  * - IO error (id 1)
275  */
276  virtual void DoRead(TokenReader& rTr, const std::string& rLabel = "", const Type* pContext=0);
277 
278  /**
279  * Write to TokenWriter, see Type for public wrappers.
280  *
281  * If not the defult value, write the flag value as base 16 integer token. Else,
282  * do nothing. The label and context arguments are ignored.
283  *
284  * @param rTw
285  * Reference to TokenWriter
286  * @param rLabel
287  * Label of section to write
288  * @param pContext
289  * Write context to provide contextual information
290  *
291  * @exception Exception
292  * - IO errors (id 2)
293  */
294  virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
295 
296  /**
297  * Write to TokenWriter, see Type for public wrappers.
298  *
299  * If not the defult value, write the flags in XML format.
300  * Else, do nothing. The label and context arguments are ignored.
301  *
302  * @param rTw
303  * Reference to TokenWriter
304  * @param rLabel
305  * Label of section to write
306  * @param pContext
307  * Write context to provide contextual information
308  *
309  * @exception Exception
310  * - IO errors (id 2)
311  */
312  virtual void DoXWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
313 
314 
315 
316 }; // class AttributeFlags
317 
318 
319 } // namespace faudes
320 
321 #endif

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