cfl_functions.h

Go to the documentation of this file.
00001 /** @file cfl_functions.h Runtime interface, operations on faudes types */
00002 
00003 /* FAU Discrete Event Systems Library (libfaudes)
00004 
00005 Copyright (C) 2009 Ruediger Berndt
00006 Copyright (C) 2010 Thomas Moor
00007 
00008 This library is free software; you can redistribute it and/or
00009 modify it under the terms of the GNU Lesser General Public
00010 License as published by the Free Software Foundation; either
00011 version 2.1 of the License, or (at your option) any later version.
00012 
00013 This library is distributed in the hope that it will be useful,
00014 but WITHOUT ANY WARRANTY; without even the implied warranty of
00015 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00016 Lesser General Public License for more details.
00017 
00018 You should have received a copy of the GNU Lesser General Public
00019 License along with this library; if not, write to the Free Software
00020 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA */
00021 
00022 
00023 #ifndef FAUDES_RTIFNCTS_H
00024 #define FAUDES_RTIFNCTS_H
00025 
00026 // todo: fix/hide copy constructor
00027 
00028 #include "cfl_types.h"
00029 
00030 namespace faudes{
00031 
00032 /**
00033  * Structure to model a parameter type within the Signature of a 
00034  * Function.
00035  * A Parameter is made of a descriptive name, a faudes type and
00036  * an io-attribute. The latter specifies whether the parameter 
00037  * is a const argument (<tt>In</tt>), a result (<tt>Out</tt>) or a both-ways 
00038  * parameter (<tt>InOut</tt>). To support the code generators of the run-time-interface,
00039  * you may use the CReturn  flag to indicate that the parameter is implemented 
00040  * as the return value in the corresponding C function. The current version of the
00041  * code generators will handle this case for the elementary types Integer, Boolean and
00042  * String. They will, however, fail on any other faudes types. 
00043  */
00044 
00045 class Parameter {
00046 
00047  public:
00048 
00049   /**
00050    * A function parameter has has one out of four so called io-attrributes;
00051    */
00052   enum ParamAttr{
00053     In,    //// Input parameter, aka argument, remains constant while execution
00054     Out,   //// Output parameter, aka result, is generated during function execution
00055     InOut, //// InOut parameter, is interpreted and possibly altered during execution
00056     UnDef  //// UnDef parameter indicates unconfigured signature
00057   };
00058 
00059   /** Constructor, default */
00060   Parameter(void);
00061 
00062   /** Constructor, by member values */
00063   Parameter(const std::string& rName, const std::string& rTypeName, 
00064       ParamAttr attr=UnDef, bool cret=false);
00065 
00066   /** Desctructor */
00067   ~Parameter(void);
00068 
00069   /** 
00070    * Get name
00071    *
00072    * @return
00073    *   Name of parameter
00074    */
00075   const std::string& Name(void) const;
00076 
00077   /** 
00078    * Set name
00079    *
00080    * @param rName
00081    *   New name of parameter
00082    */
00083   void Name(const std::string& rName);
00084 
00085   /** 
00086    * Get type
00087    *
00088    * @return
00089    *   Faudes type  of parameter
00090    */
00091   const std::string& Type(void) const;
00092 
00093   /** 
00094    * Set type
00095    *
00096    * @param rTypeName
00097    *   New faudes type  of parameter
00098    */
00099   void Type(const std::string& rTypeName);
00100 
00101   /** 
00102    * Get Attribute
00103    *
00104    * @return
00105    *   In/Out/InOut attribute of parameter.
00106    */
00107   const ParamAttr& Attribute(void) const;
00108 
00109   /** 
00110    * Set Attribute
00111    *
00112    * @param rAttr
00113    *   In/Out/InOut attribute of parameter.
00114    */
00115   void Attribute(const ParamAttr& rAttr);
00116 
00117   /** 
00118    * Set Attribute by string.
00119    * Convenience method, defaults to UnDef.
00120    *
00121    * @param rAttrStr
00122    *   In/Out/InOut attribute of parameter.
00123    */
00124   void Attribute(const std::string& rAttrStr);
00125 
00126   /** 
00127    * Get C-Return flag.
00128    *
00129    * @return
00130    *   C-Return flag
00131    */
00132   bool CReturn(void) const;
00133 
00134   /** 
00135    * Set C-Return flag.
00136    *
00137    * @param cret
00138    *   New value of C-Return flag.
00139    */
00140   void CReturn(bool cret);
00141 
00142   /**
00143    * Convenience method to produce a textual representation of an io attribute.
00144    *
00145    * @param attr
00146    *  Enum value denoting the attribute.
00147    * @return
00148    *  Parameter IO attribute as std::string
00149    */
00150   static std::string AStr(Parameter::ParamAttr attr);
00151 
00152   /**
00153    * Convenience method to produce a textual representation of a parameter.
00154    *
00155    */
00156   std::string Str(void) const;
00157 
00158   /**
00159    * Set to "undefined"
00160    */
00161   void Clear();
00162 
00163   /**
00164    * Test equality
00165    *
00166    * @param rOther
00167    *   Other signature to compare with.
00168    */  
00169   bool operator==(const Parameter& rOther) const;
00170 
00171 protected:
00172 
00173   /** Name */
00174   std::string mName;
00175 
00176   /** Faudes type */
00177   std::string mTDName;
00178 
00179   /** IO-Attribute */
00180   ParamAttr mAttr;
00181 
00182   /** C-Return flag */
00183   bool mCReturn;
00184 
00185 }; // Parameter
00186 
00187 
00188 
00189 
00190 /**
00191  * Signature of a Function.
00192  * 
00193  * A Signature describes the faudes types of the positional
00194  * parameters. Tecnically, a Signature is a vector of Parameters.
00195  * Each Function may execute serveral variants indicated by setting
00196  * a particular Signature. A list of valid Signatures is maintained in 
00197  * the coresponding FunctionDefinition.
00198  *
00199  * Core members are
00200  * - mName: string to identify ths signature
00201  * - mParameters: vector of Paramters. 
00202  *
00203  * The Signature is formally derived from Type to inherit the std token io
00204  * interface. It is not meant to be registered as a faudes type.
00205  * The token io format is demonstrated by the following example:
00206  *
00207  * @code
00208  *  <Signature name="Sum of two integers">
00209  *  <Parameter name="arg1" ftype="Integer"   access="InOut"/>
00210  *  <Parameter name="arg2" ftype="Integer"   access="In"/>
00211  *  <Parameter name="res"  ftype="String"    access="Out" creturn="true"/>
00212  *  </Signature>
00213  * @endcode
00214  *
00215  * Technical note: the variable parameter feature offered by FunctionDefinition is a purely
00216  * cosmetic hack implemented in FunctionDefinition:MergeDocumentation. It is superseeded
00217  * by vector parameters and will hence disappear in a future implementation.
00218  */
00219 
00220 class Signature : public Type {
00221 
00222   // std faudes type interface (cannot autoregister)
00223   FAUDES_TYPE_DECLARATION_NEW(Void,Signature,Type)
00224   FAUDES_TYPE_DECLARATION_COPY(Void,Signature,Type)
00225   FAUDES_TYPE_DECLARATION_CAST(Void,Signature,Type)
00226   FAUDES_TYPE_DECLARATION_ASSIGN(Void,Signature,Type)
00227   FAUDES_TYPE_DECLARATION_EQUAL(Void,Signature,Type)
00228 
00229 public:
00230 
00231   /** Constructor */
00232   Signature(void);
00233 
00234   /** Copy constructor */
00235   Signature(const Signature& rSrc);
00236 
00237   /** Destructor */
00238   ~Signature(void){};
00239 
00240   /**
00241    * Return signature name.
00242    *
00243    * @return
00244    *  Name
00245    */
00246   const std::string& Name(void) const;
00247 
00248   /**
00249    * Set signature name.
00250    *
00251    * @param
00252    *  rName
00253    */
00254   void Name(const std::string& rName);
00255 
00256   /**
00257    * Clear signature
00258    */
00259   void Clear(void);
00260 
00261   /**
00262    * Return number of parameters.
00263    *
00264    * @return
00265    *  int
00266    */
00267   int Size(void) const;
00268 
00269   /**
00270    * Get parameter type by position.
00271    *
00272    * @param n
00273    *  Position of patameter.
00274    *
00275    * @exception Exception
00276    *  - Index out of range
00277    */
00278   const Parameter& At(int n) const;
00279 
00280   /**
00281    * Set parameter type by position.
00282    *
00283    * @param n
00284    *  Position of patameter.
00285    * @param rParam
00286    *  Paraeter value
00287    *
00288    * @exception Exception
00289    *  - Index out of range
00290    */
00291   void At(int n,const Parameter& rParam);
00292 
00293   /**
00294    * Append positional parameter.
00295    *
00296    * @param rParam
00297    *  Parameter to append
00298    */
00299   void Append(const Parameter& rParam);
00300 
00301 
00302  protected:
00303 
00304   /**
00305    * Std faudes type interface: assignment.
00306    *
00307    * @param rSrc 
00308    *    Source to copy from
00309    * @return Reference to this object.
00310    */
00311   virtual void DoAssign(const Signature& rSrc);
00312 
00313   /**
00314    * Std faudes type interface: test equality
00315    * 
00316    * @param rOther 
00317    *    Other object to compare with.
00318    * @return 
00319    *   True on match.
00320    */
00321   virtual bool DoEqual(const Signature& rOther) const;
00322 
00323   /**
00324    * Read signature from from TokenReader.
00325    *
00326    * The section is hardcoded to "Signature", context is ignored.
00327    *
00328    * @param rTr
00329    *   TokenReader to read from
00330    * @param rLabel
00331    *   Section to read
00332    * @param pContext
00333    *   Read context to provide contextual information (ignored)
00334    *
00335    * @exception Exception
00336    *   - IO error (id 1)
00337    *   - Token mismatch (id 50, 51, 52)
00338    */
00339   virtual void DoRead(TokenReader& rTr,  const std::string& rLabel = "", const Type* pContext=0);
00340  
00341   /**
00342    * Write configuration data of this object to TokenWriter.
00343    *
00344    * The section is hardcoded to "Signature", context is ignored.
00345    *
00346    * @param rTw
00347    *   Reference to TokenWriter
00348    * @param rLabel
00349    *   Label of section to write
00350    * @param pContext
00351    *   Write context to provide contextual information
00352    *
00353    * @exception Exception 
00354    *   - IO errors (id 2)
00355    */
00356   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00357 
00358   /** Variable to store name */
00359   std::string mName;
00360 
00361   /** Vector of Parameter-objects */
00362   std::vector<Parameter> mParameters;
00363 
00364 }; // Signature
00365 
00366 
00367 
00368 // forward 
00369 class Function;
00370 
00371 
00372 /**
00373  * A FunctionDefinition defines the interface to a faudes-function.
00374  * The latter consists of a descriptive name to identify the function and 
00375  * a list of Signatures the function can operate on. 
00376  * Technically, the class FunctionDefinition is derived from Documentation and 
00377  * thereby inherits members for additional
00378  * documentation-data.
00379  *
00380  * Similar to Type and TypeDefinition, a FunctionDefinition uses a prototype object to
00381  * provide the method NewFunction() which instantiates the corresponding Function object.
00382  *
00383  * FunctionDefinition inherits the token io interface from Type, however, the class is
00384  * not intended to register as a faudes type. The token io format is demonstrated by the
00385  * following example:
00386  *
00387  * @code
00388  * <FunctionDefinition name="CoreFaudes::IntegerSum" ctype="faudes::IntegerSum">
00389  *
00390  * <Documentation ref="integersum.html">
00391  * Returns the sum of integer arguments. 
00392  * <Documentation/>
00393  *
00394  * <Keywords> "integer" "elemetary types" </Keywords>
00395  *
00396  * <VariantSignatures>
00397  *
00398  * <Signature name="Two arguments">
00399  * <Parameter name="Arg1" ftype="Integer" access="In">
00400  * <Parameter name="Arg2" ftype="Integer" access="In">
00401  * <Parameter name="Res"  ftype="Integer" access="Out" creturn="true">
00402  * </Signature>
00403  *
00404  * <Signature name="Three arguments">
00405  * <Parameter name="Arg1" ftype="Integer" access="In">
00406  * <Parameter name="Arg2" ftype="Integer" access="In">
00407  * <Parameter name="Arg3" ftype="Integer" access="In">
00408  * <Parameter name="Res"  ftype="Integer" access="Out" creturn="true">
00409  * </Signature>
00410  *
00411  * </VariantSignatures>
00412  *
00413  * </FunctionDefinition>
00414  * @endcode
00415  *
00416  *
00417  * @ingroup RunTimeInterface
00418  */
00419 
00420 class FunctionDefinition : public Documentation {
00421 
00422  // std faudes type interface (cannot autoregister)
00423  FAUDES_TYPE_DECLARATION_NEW(Void,FunctionDefinition,Documentation)
00424  FAUDES_TYPE_DECLARATION_COPY(Void,FunctionDefinition,Documentation)
00425  FAUDES_TYPE_DECLARATION_CAST(Void,FunctionDefinition,Documentation)
00426  FAUDES_TYPE_DECLARATION_ASSIGN(Void,FunctionDefinition,Documentation)
00427  FAUDES_TYPE_DECLARATION_EQUAL(Void,FunctionDefinition,Documentation)
00428 
00429 public:
00430 
00431   /** 
00432    * Constructor 
00433    *
00434    * The default constructor instantiates an invalid function definition
00435    * without prototype. To construct a valid function definition, use the static 
00436    * Constructor() template function.
00437    */
00438   FunctionDefinition(const std::string& name="");
00439 
00440   /** 
00441    * Copy Constructor 
00442    *
00443    * The copy constructor copies all members one-to-one, except for
00444    * the prototype object. The latter is re-created using its factory function.
00445    */
00446   FunctionDefinition(const FunctionDefinition& rSrc);
00447 
00448   /**
00449    * Destructor
00450    */
00451   virtual ~FunctionDefinition(){ Prototype(NULL);};
00452 
00453   /**
00454    * Construct empty FunctionDefinition object.
00455    * The given template parameter denotes a Function class.
00456    * Member variable (mpFunction) is set to a new instance of that class
00457    * whereas the name is set as specified. No further documentation
00458    * or signatures are recorded.
00459    *
00460    * @tparam T
00461    *   Actual function class, derived from Function
00462    * @param rFunctName
00463    *   Name to identify this faudes-function
00464    * @return
00465    *   Newly constructed function definition.
00466    */
00467   template<class T>
00468   static FunctionDefinition* Constructor(const std::string& rFunctName="");
00469 
00470   /**
00471    * Construct FunctionDefinition object and get name and docu from file.
00472    *
00473    * The member variable mpFunction is set to a new instance of class T.
00474    * which must be derived from Function. The function name, any documentation
00475    * as well as supported signatures are read from the specified file.
00476    *
00477    * @tparam T
00478    *   Actual function class, derived from Function
00479    * @param rFileName
00480    *   File to read documentation and signatures from.
00481    * @return
00482    *   Newly constructed function definition.
00483    */
00484   template<class T>
00485   static FunctionDefinition* FromFile(const std::string& rFileName);
00486 
00487   /**
00488    * Clear documentation-data and signature (keep prototype)
00489    */
00490   virtual void Clear(void);
00491 
00492 
00493   /**
00494    * Clear variants (keep docu and prototype)
00495    */
00496   virtual void ClearVariants(void);
00497 
00498   /**
00499    * Return pointer to function object prototype 
00500    *
00501    * Note: this method is meant for inspection only, control over
00502    * the prototype remains with the FunctionDefinition. Use
00503    * NewFunction() to instantiate a new function object.
00504    *
00505    * @return
00506    *  Reference to prototype function.
00507    */
00508   const Function* Prototype(void) const;
00509 
00510   /**
00511    * Construct function on heap.
00512    * Return pointer to new instance of assigned Function class.
00513    *
00514    * Note: If no prototype is installed, NULL is returned.
00515    *
00516    * @return
00517    *  Pointer to new Function instance.
00518    */
00519   Function* NewFunction() const;
00520 
00521 
00522   /**
00523    * Return number of supported Signature instances.
00524    *
00525    * @return
00526    *  Size of signature vector.
00527    */
00528   int VariantsSize(void) const;
00529 
00530   /**
00531    * Test existence of variant by its name.
00532    *
00533    * @return
00534    *  True if variant exists
00535    */
00536   bool ExistsVariant(const std::string& varname) const;
00537 
00538   /**
00539    * Return index of Signature by name.
00540    *
00541    * @param rName
00542    *  Name of signature to search.
00543    * @return
00544    *  Index of signature, or -1 if not existant
00545    */
00546   int VariantIndex(const std::string& rName) const;
00547 
00548   /**
00549    * Return reference to Signature by name.
00550    *
00551    * @param rName
00552    *  Name of signature to search.
00553    * @return
00554    *  Reference to Signature 
00555    * @exception Exception
00556    *  - No such signature (id 47)
00557    */
00558   const Signature& Variant(const std::string& rName) const;
00559 
00560   /**
00561    * Return reference to Signature by index.
00562    *
00563    * @param n
00564    *  Index to look up
00565    * @return
00566    *  Reference to Signature 
00567    * @exception Exception
00568    *  - Index out of range (id 47)
00569    */
00570   const Signature& Variant(int n) const;
00571 
00572   /**
00573    * Add Signature to function definition.
00574    *
00575    * @param pVar
00576    *  Signature to insert
00577    * @exception Exception 
00578    *   - Signature with same name exists (id 47)
00579    */
00580   virtual void AppendVariant(const Signature& pVar);
00581 
00582 protected:
00583 
00584   /**
00585    * Std faudes type interface: assignment.
00586    *
00587    * @param rSrc 
00588    *    Source to copy from
00589    * @return Reference to this object.
00590    */
00591   virtual void DoAssign(const FunctionDefinition& rSrc);
00592 
00593   /**
00594    * Std faudes type interface: test equality
00595    * 
00596    * @param rOther 
00597    *    Other object to compare with.
00598    * @return 
00599    *   True on match.
00600    */
00601   virtual bool DoEqual(const FunctionDefinition& rOther) const;
00602 
00603   /**
00604    * Read configuration data of this object from TokenReader.
00605    * Actual reading is done by DoReadCore.
00606    *
00607    * The section defaults to "FunctionDefinition", context ignored.
00608    *
00609    * @param rTr
00610    *   TokenReader to read from
00611    * @param rLabel
00612    *   Section to read
00613    * @param pContext
00614    *   Read context to provide contextual information (ignored)
00615    *
00616    * @exception Exception
00617    *   - Token mismatch (id 50, 51, 52)
00618    *   - IO error (id 1)
00619    */
00620   virtual void DoRead(TokenReader& rTr,  const std::string& rLabel = "", const Type* pContext=0);
00621  
00622   /**
00623    * Read configuration data of this object from TokenReader.
00624    *
00625    * This method reads members only, it does not read the section.
00626    *
00627    * @param rTr
00628    *   TokenReader to read from
00629    *
00630    * @exception Exception
00631    *   - Token mismatch (id 50, 51, 52)
00632    *   - IO error (id 1)
00633    */
00634   virtual void DoReadCore(TokenReader& rTr);
00635  
00636   /**
00637    * Write configuration data of this object to TokenWriter.
00638    *
00639    * The section defaults to "FunctionDefinition", context ignored.
00640    *
00641    * @param rTw
00642    *   Reference to TokenWriter
00643    * @param rLabel
00644    *   Label of section to write
00645    * @param pContext
00646    *   Write context to provide contextual information
00647    *
00648    * @exception Exception 
00649    *   - IO errors (id 2)
00650    */
00651   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00652 
00653   /**
00654    * Write configuration data of this object to TokenWriter.
00655    *
00656    * This method writes plain member data, the section lables are not
00657    * written.
00658    *
00659    * @param rTw
00660    *   Reference to TokenWriter
00661    *
00662    * @exception Exception 
00663    *   - IO errors (id 2)
00664    */
00665   virtual void DoWriteCore(TokenWriter& rTw) const;
00666 
00667   /**
00668    * Assign prototype object
00669    *
00670    * @param pFunc
00671    *  Function instance
00672    *
00673    */
00674   virtual void Prototype(Function* pFunc);
00675 
00676   /** Prototype instance */
00677   Function* mpFunction;
00678 
00679   /** Vector containing all supported Signatures */
00680   std::vector<faudes::Signature> mVariants;
00681 
00682   /** Variant name to index map */
00683   std::map<std::string,int> mVariantIndexMap;
00684 
00685 }; // FunctionDefinition
00686 
00687 
00688 
00689 /**
00690  * A faudes-function hosts parameter values of some faudes type and provides 
00691  * a method to perform an operation on the specified paramters, e.g. the 
00692  * parallel composition on two generators. The class Function is the base
00693  * for all faudes-functions, which essenitally differ in the operation method.
00694  *
00695  * The base class provides an application interface to
00696  * - select a variant signature, see Variant(); 
00697  * - set and get parameter values of any faudes type, see ParamValue();
00698  * - type check the provided parameter values, see TypeCheck(); 
00699  * - perform the operation, see Execute().
00700  *
00701  * Derivates of the base class, that acually implement an operation,
00702  * are required to cast the parameter values to the corresponding c types and then
00703  * call the respective c function. To derive a class from Function, one will
00704  * reimplment three virtual functions:
00705  * - DoTypeCheck() to perform the cast
00706  * - DoExecute() to call the c function.
00707  * - the constructor New() to replicate the function object.
00708  *
00709  * See IntegerSum in the autogenerated ./include/rtiautoload.h" for a simple example 
00710  * of a derived faudes-function.
00711  * 
00712  *
00713  * Technichal note: In contrast to faudes objects (derivates from Type), a faudes-function
00714  * must be provided a reference to the corresponding FunctionDefinition. This is because
00715  * a function must be aware of its signature(s). You must not delete 
00716  * the FunctionDefinition object during the lifetime of a faudes-function.
00717  *
00718  *
00719  * @ingroup RunTimeInterface
00720  */  
00721 
00722 class Function : public Type {
00723 
00724  public:
00725   /** 
00726    * Constructor 
00727    * For the function to be operational, a valid reference to the corresponding 
00728    * FunctionDefinition is required. The only exception is the prototype function
00729    * object used in the FunctionDefinition itself. 
00730    */
00731   Function(const FunctionDefinition* fdef);
00732 
00733   /** Destructor */
00734   ~Function(){}
00735 
00736   /**
00737    * Construct on heap.
00738    * Create a new instance of this function class and return pointer.
00739    * The new instance will use the same function definition as this instance.
00740    *
00741    * @return
00742    *  Pointer to faudes::Function instance.
00743    *
00744    */
00745   virtual Function* New() const = 0;
00746 
00747 
00748   /**
00749    * Set function definition.
00750    * Normally, functions are provided with a function definition on construction.
00751    * The only exception are prototype objects used in function definitions themselfs 
00752    * and in the function registry.
00753    *
00754    * @param fdef
00755    *  Function definition to set.
00756    *
00757    */
00758   virtual void Definition(const FunctionDefinition* fdef);
00759 
00760 
00761   /**
00762    * Get function definition.
00763    *
00764    * @return 
00765    *  Function definition used by this function.
00766    *
00767    */
00768   const FunctionDefinition* Definition(void) const;
00769 
00770 
00771   /**
00772    * Return number of variants.
00773    *
00774    * @return
00775    *  Size of vector.
00776    */
00777   int VariantsSize(void) const;
00778 
00779   /**
00780    * Set signature from function definition.
00781    *
00782    * The index n refers this function's FunctionDefinition.
00783    * An exception is thrown if no such FunctionDefinition is set, as it
00784    * is the case for prototype instances.
00785    *
00786    * @param n
00787    *  Variant index 
00788    *
00789    * @exception Exception
00790    *  - No function definition available (id 47)
00791    *  - No such variant (id 48)
00792    */
00793    void Variant(int n);
00794 
00795 
00796   /**
00797    * Set signature from function definition.
00798    *
00799    * The name refers to this function's FunctionDefinition.
00800    * An exception is thrown if no such FunctionDefinition is set, as it
00801    * is the case for prototype instances.
00802    *
00803    * @param rVariantName
00804    *  Variant name
00805    *
00806    * @exception Exception
00807    *  - No function definition available (id 47)
00808    *  - No such variant (id 48)
00809    */
00810   void Variant(const std::string& rVariantName);
00811 
00812 
00813   /**
00814    * Return pointer to assigned faudes::Signature.
00815    *
00816    * @return
00817    *  Pointer to faudes::Signature.
00818    */
00819   const Signature* Variant(void) const;
00820 
00821 
00822   /**
00823    * Return number of parameters with current signature.
00824    *
00825    * @return
00826    *  Size of vector.
00827    */
00828   int ParamsSize(void) const;
00829 
00830   /**
00831    * Set parameter at certain position.
00832    *
00833    * Sets the internal refernce of the parameter value
00834    * at the spcefied index. The ownership of the value remains with
00835    * the caller, ie it will not be deleted in the destructor of the 
00836    * function object.
00837    * You may set the parameter value to any faudes type
00838    * (classes derived from Type). A type check will be performed before the function
00839    * is executed.
00840    *
00841    * @param n
00842    *  Position index of parameter 
00843    * @param param
00844    *  Pointer to faudes object.
00845    *
00846    * @exception Exception
00847    *  - Index out of range (id 47)
00848    *  - No variant set (id 47)
00849    */
00850   void ParamValue(int n, Type* param);
00851 
00852   /**
00853    * Get parameter value.
00854    * Returns a reference to the parameter value at the specified position.
00855    *
00856    * @param n
00857    *  Position index of parameter.
00858    *
00859    * @exception Exception
00860    *  - Index out of range (id 47)
00861    */
00862   Type* ParamValue(int n) const;
00863 
00864   /**
00865    * Construct parameter values.
00866    *
00867    * This is a convenience method to allocate faudes objects for 
00868    * parameter values with the type specified by the current signature.
00869    * Note that the function does not take ownetship of the parameter values and
00870    * it is the callers responsibility to delete them when no longer required.
00871    *
00872    */
00873   void AllocateValues(void);
00874   void AllocateValue(int i);
00875 
00876   /**
00877    * Destruct parameter values.
00878    *
00879    * This is a convenience method to delete the assigned paramer values.
00880    *
00881    */
00882   void FreeValues(void);
00883 
00884   /**
00885    * Perform a type check one parameter value.
00886    * 
00887    * The type check is based on c type cast and should accept any types
00888    * derived from the type given in the signature.
00889    *
00890    * @param n
00891    *   Position of parameter to check
00892    * @return
00893    *   True if type matches  
00894    *
00895    * @exception Exception
00896    *  - No variant specified (id 48)
00897    *  - Number of parameter is outside the specified signature (id 48)
00898    *
00899    */
00900   bool TypeCheck(int n);
00901 
00902   /**
00903    * Perform a type check on the list of current parameter values.
00904    * 
00905    * The type check is based on c type cast and should accept any types
00906    * derived from those given in the signature.
00907    *
00908    * @return
00909    *   True if all parameter types matche the signature
00910    *
00911    * @exception Exception
00912    *  - No variant specified (id 48)
00913    *  - Number of parameters does not match signature (id 48)
00914    *
00915    */
00916   bool TypeCheck(void);
00917 
00918   /**
00919    * Perform operation.
00920    *
00921    * Runs a type check and then the actual function.
00922    *
00923    * @exception Exception
00924    *  - No variant specified (id 48)
00925    *  - Parameter position out of range (id 48)
00926    *  - Type mismatch (id 48)
00927    *  - Any other exception thrown ba the actual function (id xxx)
00928    */
00929   void Execute(void);
00930 
00931 
00932  protected:
00933 
00934   /**
00935    * Helper: generate typed reference for parameter.
00936    *
00937    * @param n
00938    *   Parameter position to cast
00939    * @param rTypedRef
00940    *   Typed reference to generyte
00941    * @tparam T
00942    *   c type to use for cast
00943    * @return
00944    *   True if cast succeeded.
00945    * @exception Exception
00946    *  - No variant specified (id 48)
00947    *  - Parameter position out of range (id 48)
00948    */  
00949    template<class T>
00950    bool DoTypeCast(int n, T*& rTypedRef) {
00951     if(!Variant()) {
00952        std::stringstream err;
00953        err << "No variant specified";
00954        throw Exception("Function::DoTypeCast()", err.str(), 48);
00955     }
00956     if(n<0 || n >= ParamsSize()) {
00957        std::stringstream err;
00958        err << "Parameter position out of range";
00959        throw Exception("Function::DoTypeCast()", err.str(), 48);
00960     }
00961     rTypedRef=dynamic_cast<T*>(ParamValue(n));
00962     return rTypedRef!=NULL;
00963   }
00964 
00965   /*
00966    * Do set variant from function definition.
00967    *
00968    * The index n refers this function's FunctionDefinition.
00969    * An exception is thrown if no FunctionDefinition is set, as it
00970    * is the case for prototype instances.
00971    *
00972    * @param n
00973    *  Variant index 
00974    *
00975    * @exception Exception
00976    *  - No function definition available (id 47)
00977    *  - No such variant (id 48)
00978    */
00979    virtual void DoVariant(int n);
00980 
00981   /**
00982    * Method to test the type of an assigned parameter with the
00983    * specified faudes::Signature (i.e. their TypeDefinition label).
00984    *
00985    * Note: this method is called by Function::Execute() before actual function 
00986    * execution via DoExecute(). It may be used to perform a dynamic cast in 
00987    * preparation of DoExecute(). The latter is only called, if all types match.
00988    * 
00989    * @param n
00990    *   Position of parameter to check
00991    * @return
00992    *   True if type matches signature.
00993    *
00994    * @exception Exception
00995    *  - Signature undefined (id 48)
00996    *  - Parameter number out of range (id 48)
00997    */
00998   virtual bool DoTypeCheck(int n) = 0;
00999 
01000   /**
01001    * Executes code of reimplemented method of child class(es).
01002    */
01003   virtual void DoExecute() = 0;
01004 
01005   /**
01006    * Write function-data (typeid-name of arguments) to TokenWriter.
01007    *
01008    * @param rTw
01009    *  Reference to Tokenwriter.
01010    * @param rLabel
01011    *  Label of section to write.
01012    * @param pContext
01013    *  Context pointer, ignored
01014    *
01015    * @exception Exception
01016    *  - IO Error
01017    */
01018   void DoWrite(TokenWriter& rTw, const std::string& rLabel = "", const Type* pContext=0) const;
01019 
01020   /** corresponding function definition */
01021   const FunctionDefinition* pFuncDef;
01022 
01023   /** current variant aka signature as index w.r.t. the function definition */
01024   int mVariantIndex;
01025 
01026   /** Vector of arguments. */
01027   std::vector<Type*> mParameterValues;
01028 
01029 }; // Function
01030 
01031 
01032 
01033 /**********************************************************************************************
01034 ***********************************************************************************************
01035 ***********************************************************************************************
01036 
01037 Implemention of template members functions
01038 
01039 ***********************************************************************************************
01040 ***********************************************************************************************
01041 **********************************************************************************************/
01042 
01043 
01044 // typedefinition constructor function
01045 template<class T>
01046 FunctionDefinition* FunctionDefinition::Constructor(const std::string& rFunctionName){
01047   FD_DRTI("FunctionDefinition::Construct<" << typeid(T).name() << ">()");
01048   // construct void definition
01049   FunctionDefinition* td = new FunctionDefinition();
01050   // set its prototype object (note the 0 param in the new constructor)
01051   td->Prototype(new T(0));
01052   // set minmum values ie the function name
01053   std::string name=rFunctionName;
01054   if(name=="") name=typeid(T).name();
01055   td->Name(name);
01056   FD_DRTI("FunctionDefinition::Constructor<" << typeid(T).name() << ">(): done");
01057   return(td);
01058 }
01059 
01060 
01061 // function definition constructor function
01062 template<class T>
01063 FunctionDefinition* FunctionDefinition::FromFile(const std::string& rFileName){
01064   FD_DRTI("FunctionDefinition::FromFile<" << typeid(T).name() << ">()");
01065   // construct with fallback name
01066   FunctionDefinition* td = Constructor<T>();
01067   // read docu, incl actual name
01068   td->Read(rFileName);
01069   // done
01070   FD_DRTI("FunctionDefinition::FromFile<" << typeid(T).name() << ">(): done");
01071   return(td);
01072 }
01073 
01074 
01075 } // namespace
01076 
01077 
01078 #endif /* FAUDES_FUNCTIONS_H */

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