cfl_attributes.h

Go to the documentation of this file.
00001 /** @file cfl_attributes.h Classes AttributeVoid and AttributeFlags  */
00002 
00003 
00004 /* FAU Discrete Event Systems Library (libfaudes)
00005 
00006 Copyright (C) 2007  Thomas Moor
00007 Exclusive copyright is granted to Klaus Schmidt
00008 
00009 This library is free software; you can redistribute it and/or
00010 modify it under the terms of the GNU Lesser General Public
00011 License as published by the Free Software Foundation; either
00012 version 2.1 of the License, or (at your option) any later version.
00013 
00014 This library is distributed in the hope that it will be useful,
00015 but WITHOUT ANY WARRANTY; without even the implied warranty of
00016 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00017 Lesser General Public License for more details.
00018 
00019 You should have received a copy of the GNU Lesser General Public
00020 License along with this library; if not, write to the Free Software
00021 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA */
00022 
00023 
00024 #ifndef FAUDES_ATTRIBUTES_H
00025 #define FAUDES_ATTRIBUTES_H
00026 
00027 #include "cfl_types.h"
00028 #include "cfl_registry.h"
00029 #include "cfl_tokenreader.h"
00030 #include "cfl_tokenwriter.h"
00031 
00032 namespace faudes {
00033 
00034 
00035 /**
00036  * Minimal Attribute. Attributes are used as template parameters for
00037  * faudes containers and generators and facilitate the modelling of customized  
00038  * properties of events, states and transitions.  The AttributeVoid class defines
00039  * the minimal interface of faudes attributes and therefore is the designated
00040  * base class for all attribute implementations. The AttributeVoid class does
00041  * not define any actual properties. See AttributeFlags for a non-trivial example.
00042  *
00043  * To derive a class from AttributeVoid you should reimplement the virtual
00044  * interface
00045  * - virtual methody DoRead and DoWrtie for token io (as in faudes::Type)
00046  * - virtual methods for DoAssign() (as in faudes::Type) 
00047  * - the factory method New() (use provided macro from faudes::Type)
00048  * - the rti typecast method Cast() (use provided macro from faudes::Type)
00049  * - user level Assign() method (use provided macro from faudes::Type)
00050  */
00051 
00052 class AttributeVoid : public Type {
00053  
00054 FAUDES_TYPE_DECLARATION(Void,AttributeVoid,Type)
00055 
00056 public:
00057 
00058   /** Constructor */
00059   AttributeVoid(void);
00060 
00061   /** Destructor */
00062   virtual ~AttributeVoid(void);
00063 
00064   /** 
00065    * Test for default value.
00066    */
00067   virtual bool IsDefault(void) const {return true;};
00068 
00069   /**
00070    * Set to default value.
00071    * Derived classes must reimplement this function for Clear to operate properly.
00072    */
00073   virtual void SetDefault(void) {};
00074 
00075   /**
00076    *   Synonym for SetDefault to match std interface
00077    */
00078   virtual void Clear(void) { SetDefault(); };
00079 
00080   /**
00081    * Skip attribute tokens.
00082    *
00083    * Helper method to be called after all sttribute derived classes had their
00084    * chance to read their data. It skips all tokens and sections until it reaches a 
00085    * String or decimal Integer.
00086    *
00087    * @param rTr
00088    *   TokenReader to read from
00089    * @exception Exception
00090    *   - IO error (id 1)
00091    */
00092   static void Skip(TokenReader& rTr);
00093 
00094 protected:
00095 
00096   /**
00097    * Assign attribute members. 
00098    * Since AttributeVoid has no members, this method does nothing.
00099    * Derived classes are meant to reimplement DoAssign by first calling
00100    * their base and then assigning additional member variables.
00101    *
00102    * @param rSrcAttr
00103    *    Source to assign from
00104    */
00105   virtual void DoAssign(const AttributeVoid& rSrcAttr) { (void) rSrcAttr; };
00106 
00107   /**
00108    * Test equality of configuration data.
00109    * Derived attributes should reimplement this class to compare
00110    * configuration data. The base AttributeVoid returns true as a default.
00111    * @param rOther 
00112    *    Other object to compare with.
00113    * @return 
00114    *   True on match.
00115    */
00116   virtual bool DoEqual(const AttributeVoid& rOther) const { (void) rOther; return true; }
00117 
00118   /**
00119    * Actual read method to read attribute from tokenreader.
00120    *
00121    * For derived attributue classes, this method must either read all tokens that
00122    * belong to the respective attribute, or none. It may throw exceptions on token
00123    * mismatch within the relevant attribute, but it may not throw exceptions when
00124    * it encounters tokens that possibly belong to another attribute. The latter are
00125    * to be skipped by the provided Skip method. See Type::Read
00126    * for public wrappers.
00127    *
00128    * @param rTr
00129    *   TokenReader to read from
00130    * @param rLabel
00131    *   Section to read
00132    * @param pContext
00133    *   Read context to provide contextual information
00134    *
00135    * @exception Exception
00136    *   - IO error (id 1)
00137    */
00138   virtual void DoRead(TokenReader& rTr,  const std::string& rLabel = "", const Type* pContext=0);
00139  
00140   /**
00141    * Actual write method to write the attribute to a TokenWriter.
00142    *
00143    * Reimplement this method for derived attribute classes to define the token io 
00144    * format. See Type::Write for public wrappers.
00145    *
00146    * @param rTw
00147    *   Reference to TokenWriter
00148    * @param rLabel
00149    *   Label of section to write
00150    * @param pContext
00151    *   Write context to provide contextual information
00152    *
00153    * @exception Exception 
00154    *   - IO errors (id 2)
00155    */
00156   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00157 
00158 
00159 
00160 }; // class AttributeVoid
00161 
00162 
00163 /** Convenience typdef flag data */
00164 typedef unsigned long int fType;
00165 
00166 /**
00167  * Boolean flags Attribute. This attribute class uses a flag word to represent 
00168  * boolean values. The current implementation uses a long int type and hence handles
00169  * up to 32 flags. Each flag is accessed by the according bit mask. 
00170  *
00171  * The current version
00172  * of libFAUDES uses bits 0,1,2 of event attributes for controllability properties 
00173  * (see AttributeCFlags) and the bits 31 and 32 of state attributes for the Qt based
00174  * GUI project. Further versions may use the lower 8 bits of the event aflags and the higher 8
00175  * bits of state flags. You are free to use any flags for your application, but if possible try
00176  * to avoid the above mentioned. For extensive use of flags, you may also consider to
00177  * define a separate attribute class, perhaps with a different fType.
00178  */
00179 
00180 
00181 
00182 class AttributeFlags : public AttributeVoid {
00183 
00184 FAUDES_TYPE_DECLARATION(Void,AttributeFlags,AttributeVoid)
00185 
00186 public:
00187 
00188   /** Default constructor */
00189   AttributeFlags(void) : AttributeVoid(), mFlags(mDefFlags) {};
00190 
00191   /** Copy constructor */
00192   AttributeFlags(const AttributeFlags& rOther) : AttributeVoid(), mFlags(rOther.mFlags) {};
00193 
00194   /** Destructor */
00195   virtual ~AttributeFlags(void) {};
00196 
00197   /**
00198    * Test a flag
00199    */
00200   bool Test(fType mask) const { return ( (mFlags & mask) != 0 ); };
00201 
00202   /**
00203    * Test multible flags, combine by "and"
00204    */
00205   bool TestAll(fType mask) const { return ( (mFlags & mask) == mask ); };
00206 
00207   /**
00208    * Test multible flags, combine by "or"
00209    */
00210   bool TestSome(fType mask) const { return ( (mFlags & mask) != 0 ); };
00211 
00212   /**
00213    * Test multible flags, combine by "not or"
00214    */
00215   bool TestNone(fType mask) const { return ( (mFlags & mask) == 0 ); };
00216 
00217   /**
00218    * Set multiple flags
00219    */
00220   void Set(fType mask) {mFlags |= mask; };
00221 
00222   /**
00223    * Clear multiple flags
00224    */
00225   void Clr(fType mask) {mFlags &= ~mask; };
00226 
00227   /** 
00228    * Test for default value
00229    */
00230   virtual bool IsDefault(void) const {return mFlags==mDefFlags;};
00231 
00232   /** Flags (public access for convenience)  */
00233   fType mFlags;
00234 
00235   /* default flags */
00236   const static fType mDefFlags=0x0;
00237 
00238 
00239 protected:
00240 
00241   /**
00242    * Assignment method. 
00243    *
00244    * @param rSrcAttr
00245    *    Source to assign from
00246    */
00247   void DoAssign(const AttributeFlags& rSrcAttr);
00248 
00249   /**
00250    * Test equality of configuration data.
00251    *
00252    * @param rOther 
00253    *    Other object to compare with.
00254    * @return 
00255    *   True on match.
00256    */
00257   virtual bool DoEqual(const AttributeFlags& rOther) const;
00258 
00259 
00260   /**
00261    * Reads attribute from TokenReader, see Type for public wrappers.
00262    *
00263    * Test whether the current token is an integer with base 16. If so, read the token to the
00264    * flags value. Else, dont take any tokens. The label and context arguments are ignored.
00265    *
00266    * @param rTr
00267    *   TokenReader to read from
00268    * @param rLabel
00269    *   Section to read
00270    * @param pContext
00271    *   Read context to provide contextual information
00272    *
00273    * @exception Exception
00274    *   - IO error (id 1)
00275    */
00276   virtual void DoRead(TokenReader& rTr,  const std::string& rLabel = "", const Type* pContext=0);
00277  
00278   /**
00279    * Write to TokenWriter, see Type for public wrappers.
00280    *
00281    * If not the defult value, write the flag value as base 16 integer token. Else,
00282    * do nothing. The label and context arguments are ignored.
00283    *
00284    * @param rTw
00285    *   Reference to TokenWriter
00286    * @param rLabel
00287    *   Label of section to write
00288    * @param pContext
00289    *   Write context to provide contextual information
00290    *
00291    * @exception Exception 
00292    *   - IO errors (id 2)
00293    */
00294   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00295 
00296   /**
00297    * Write to TokenWriter, see Type for public wrappers.
00298    *
00299    * If not the defult value, write the flags in XML format.
00300    * Else, do nothing. The label and context arguments are ignored.
00301    *
00302    * @param rTw
00303    *   Reference to TokenWriter
00304    * @param rLabel
00305    *   Label of section to write
00306    * @param pContext
00307    *   Write context to provide contextual information
00308    *
00309    * @exception Exception 
00310    *   - IO errors (id 2)
00311    */
00312   virtual void DoXWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00313 
00314 
00315 
00316 }; // class AttributeFlags
00317 
00318 
00319 } // namespace faudes
00320 
00321 #endif

libFAUDES 2.23h --- 2014.04.03 --- c++ api documentaion by doxygen