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 FAUDES_API 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  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  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 DoDWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
157 
158  /**
159  * Actual write method to write the attribute to a TokenWriter.
160  *
161  * Reimplement this method for derived attribute classes to define the token io
162  * format. See Type::Write for public wrappers.
163  *
164  * @param rTw
165  * Reference to TokenWriter
166  * @param rLabel
167  * Label of section to write
168  * @param pContext
169  * Write context to provide contextual information
170  *
171  * @exception Exception
172  * - IO errors (id 2)
173  */
174  virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
175 
176 
177 
178 }; // class AttributeVoid
179 
180 
181 /** Convenience typdef flag data */
182 typedef unsigned long int fType;
183 
184 /**
185  * Boolean flags Attribute. This attribute class uses a flag word to represent
186  * boolean values. The current implementation uses a long int type and hence handles
187  * up to 32 flags. Each flag is accessed by the according bit mask.
188  *
189  * The current version
190  * of libFAUDES uses bits 0,1,2 of event attributes for controllability properties
191  * (see AttributeCFlags) and the bits 31 and 32 of state attributes for the Qt based
192  * GUI project. Further versions may use the lower 8 bits of the event aflags and the higher 8
193  * bits of state flags. You are free to use any flags for your application, but if possible try
194  * to avoid the above mentioned. For extensive use of flags, you may also consider to
195  * define a separate attribute class, perhaps with a different fType.
196  */
197 
198 
199 
201 
203 
204 public:
205 
206  /** Default constructor */
207  AttributeFlags(void) : AttributeVoid(), mFlags(mDefFlags) {};
208 
209  /** Copy constructor */
210  AttributeFlags(const AttributeFlags& rOther) : AttributeVoid(), mFlags(rOther.mFlags) {};
211 
212  /** Destructor */
213  virtual ~AttributeFlags(void) {};
214 
215  /**
216  * Test a flag
217  */
218  bool Test(fType mask) const { return ( (mFlags & mask) != 0 ); };
219 
220  /**
221  * Test multible flags, combine by "and"
222  */
223  bool TestAll(fType mask) const { return ( (mFlags & mask) == mask ); };
224 
225  /**
226  * Test multible flags, combine by "or"
227  */
228  bool TestSome(fType mask) const { return ( (mFlags & mask) != 0 ); };
229 
230  /**
231  * Test multible flags, combine by "not or"
232  */
233  bool TestNone(fType mask) const { return ( (mFlags & mask) == 0 ); };
234 
235  /**
236  * Set multiple flags
237  */
238  void Set(fType mask) {mFlags |= mask; };
239 
240  /**
241  * Clear multiple flags
242  */
243  void Clr(fType mask) {mFlags &= ~mask; };
244 
245  /**
246  * Test for default value
247  */
248  virtual bool IsDefault(void) const {return mFlags==mDefFlags;};
249 
250  /** Flags (public access for convenience) */
251  fType mFlags;
252 
253  /* default flags */
254  const static fType mDefFlags=0x0;
255 
256 
257 protected:
258 
259  /**
260  * Assignment method.
261  *
262  * @param rSrcAttr
263  * Source to assign from
264  */
265  void DoAssign(const AttributeFlags& rSrcAttr);
266 
267  /**
268  * Test equality of configuration data.
269  *
270  * @param rOther
271  * Other object to compare with.
272  * @return
273  * True on match.
274  */
275  bool DoEqual(const AttributeFlags& rOther) const;
276 
277 
278  /**
279  * Reads attribute from TokenReader, see Type for public wrappers.
280  *
281  * Test whether the current token is an integer with base 16. If so, read the token to the
282  * flags value. Else, dont take any tokens. The label and context arguments are ignored.
283  *
284  * @param rTr
285  * TokenReader to read from
286  * @param rLabel
287  * Section to read
288  * @param pContext
289  * Read context to provide contextual information
290  *
291  * @exception Exception
292  * - IO error (id 1)
293  */
294  virtual void DoRead(TokenReader& rTr, const std::string& rLabel = "", const Type* pContext=0);
295 
296  /**
297  * Write to TokenWriter, see Type for public wrappers.
298  *
299  * If not the defult value, write the flag value as base 16 integer token. Else,
300  * 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 DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
313 
314  /**
315  * Write to TokenWriter, see Type for public wrappers.
316  *
317  * If not the defult value, write the flags in XML format.
318  * Else, do nothing. The label and context arguments are ignored.
319  *
320  * @param rTw
321  * Reference to TokenWriter
322  * @param rLabel
323  * Label of section to write
324  * @param pContext
325  * Write context to provide contextual information
326  *
327  * @exception Exception
328  * - IO errors (id 2)
329  */
330  virtual void DoXWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
331 
332 
333 
334 }; // class AttributeFlags
335 
336 
337 } // namespace faudes
338 
339 #endif

libFAUDES 2.28a --- 2016.09.13 --- c++ api documentaion by doxygen