libFAUDES

Sections

Index

lbp_function.h

Go to the documentation of this file.
00001 /** @file lbp_function.h luafaudes class to run scripts as rti functions */
00002 
00003 /* FAU Discrete Event Systems Library (libfaudes)
00004 
00005 Copyright (C) 2010 Thomas Moor
00006 
00007 This library is free software; you can redistribute it and/or
00008 modify it under the terms of the GNU Lesser General Public
00009 License as published by the Free Software Foundation; either
00010 version 2.1 of the License, or (at your option) any later version.
00011 
00012 This library is distributed in the hope that it will be useful,
00013 but WITHOUT ANY WARRANTY; without even the implied warranty of
00014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00015 Lesser General Public License for more details.
00016 
00017 You should have received a copy of the GNU Lesser General Public
00018 License along with this library; if not, write to the Free Software
00019 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA */
00020 
00021 
00022 #ifndef FAUDES_LBPFUNCTION_H
00023 #define FAUDES_LBPFUNCTION_H
00024 
00025 #include "corefaudes.h"
00026 
00027 // forward
00028 struct lua_State;
00029 
00030 namespace faudes{
00031 
00032 class LuaFunction;
00033 
00034 /**
00035  * A LuaFunctionDefinition is derived from FaunctionDefinition to
00036  * defines a faudes-function to be a luafaudes script. Thus, it has
00037  * the lua code as an additional member variable and uses a LuaFunction as a
00038  * prototype object. In particular, LuaFunctionDefinitions are allways
00039  * valid in the sense that hey have a prototype. The LuaFunction object 
00040  * implements DoTypeCheck and DoExecute to run the specifed lua code. 
00041  *
00042  * The token io format is demonstrated by the
00043  * following example:
00044  *
00045  * @code
00046  * <LuaFunctionDefinition>
00047  *
00048  * "LuaInteregrSum::LuaExtension"
00049  *
00050  * <TextDoc> "Returns the sum of two integer arguments." </TextDoc>
00051  * <HtmlDoc> "integersum.html" </HtmlDoc>
00052  * <Keywords> "luafunctions" "example" </Keywords>
00053  *
00054  * <VariantSignatures>
00055  * <Signature>
00056  * "Res=A+B"
00057  * "ArgA"  "Integer"   +In+
00058  * "ArgB"  "Integer"   +In+
00059  * "Res"   "Integer"   +Out+
00060  * </Signature>
00061  * </VariantSignatures>
00062  * 
00063  * <LuaCode> 
00064  * __VERBATIM__
00065  *
00066  * -- Define my function
00067  * function Res_A_B(a,b,res)
00068  *   print(string.format('Res_A_B(...): a=%d b=%d',a,b))
00069  *   res=a+b
00070  *   return a,b,res
00071  * end
00072  *
00073  * __VERBATIM__
00074  * </LuaCode>
00075  *
00076  * </LuaFunctionDefinition>
00077  * @endcode
00078  *
00079  * Alternatively to the embedded code, the luacode can be read from an external file, specified
00080  * by a section <tt>LuaFile</tt>. (not implemented)
00081  *
00082  * Restrictions and conventions:
00083  * - Typechecking is done via the Cast() function of the faudes type interface. As a 
00084  *   consequence, you may only use types that are registered with run-time-interface.
00085  * - On execution, the LuaFunction instance has to locate the respective function 
00086  *   in the supplied lua code. In order to allow for multiple variants, the convention is
00087  *   to have one lua function each with the name of the corresponding variant. Since
00088  *   variant names may contain funny characters, name matching is performed after
00089  *   replacing any sequence of non-alpha-numericals by "_". E.g. the variant "res=a+b" matches the
00090  *   lua function "res_a_b".
00091  * - Since luafaudes has no concept of const references, it is the responsability of the
00092  *   script programer to respect parameter types +In+, +Out+ and +InOut+.
00093  * - Integers, booleans ans strings are passed to Lua by value, any other parameters
00094  *   are passed by reference. To have a uniform interface, the convention is that the 
00095  *   lua function must return all specified parameters.
00096  *
00097  *
00098  *
00099  * @ingroup LuabindingsPlugin
00100  */
00101 
00102 class LuaFunctionDefinition : public FunctionDefinition {
00103 
00104   // faudes type
00105   FAUDES_TYPE_DECLARATION(LuaFunctionDefinition,FunctionDefinition)
00106 
00107 public:
00108 
00109   /** 
00110    * Constructor 
00111    *
00112    * In contrast to the std FunctionDefinition, the default constructor 
00113    * sets up a valid lua function definition with a newly created LuaFunction 
00114    * as prototype.
00115    * Of course, you will need to set the signatures and the lua code
00116    * to obtain an operational function.
00117    */
00118   LuaFunctionDefinition(const std::string& name="");
00119 
00120   /** 
00121    * Copy constructor 
00122    */
00123   LuaFunctionDefinition(const LuaFunctionDefinition& rSrc);
00124 
00125   /**
00126    * Destructor
00127    */
00128   virtual ~LuaFunctionDefinition(void){};
00129 
00130 
00131   /**
00132    * Clear documentation-data, signature and script (keep prototype)
00133    */
00134   void Clear(void);
00135 
00136   /**
00137    * Get Lua code
00138    * 
00139    * @return
00140    *   Lua code as std string
00141    */
00142   const std::string& LuaCode(void) const;
00143 
00144   /**
00145    * Set Lua code
00146    * 
00147    * @param rCode
00148    *   Lua code as std string
00149    */
00150   void LuaCode(const std::string& rCode);
00151 
00152 
00153   /**
00154    * Syntax check lua code.
00155    *
00156    * This routine instantiates a LuaFunction from this function definition
00157    * and does all it needs to run the script, except to invoke the any of the
00158    * variant functions. The reasoning is, that the script may hang and, thus, 
00159    * never return. Errors are indicated by an exception.
00160    * 
00161    * @return
00162    *   Error message as string, or empty string on success
00163    */
00164   std::string SyntaxCheck(void);
00165 
00166 protected:
00167 
00168   /**
00169    * Std faudes type interface: assignment.
00170    *
00171    * @param rSrc 
00172    *    Source to copy from
00173    * @return Reference to this object.
00174    */
00175   virtual LuaFunctionDefinition& DoAssign(const LuaFunctionDefinition& rSrc);
00176 
00177   /**
00178    * Std faudes type interface: test equality
00179    * 
00180    * @param rOther 
00181    *    Other object to compare with.
00182    * @return 
00183    *   True on match.
00184    */
00185   virtual bool DoEqual(const LuaFunctionDefinition& rOther) const;
00186 
00187   /**
00188    * Read configuration data of this object from TokenReader.
00189    * Actual reading is done by DoReadCore.
00190    *
00191    * The section defaults to "LuaFunctionDefinition", context ignored.
00192    *
00193    * @param rTr
00194    *   TokenReader to read from
00195    * @param rLabel
00196    *   Section to read
00197    * @param pContext
00198    *   Read context to provide contextual information (ignored)
00199    *
00200    * @exception Exception
00201    *   - Token mismatch (id 50, 51, 52)
00202    *   - IO error (id 1)
00203    */
00204   virtual void DoRead(TokenReader& rTr,  const std::string& rLabel = "", const Type* pContext=0);
00205  
00206   /**
00207    * Read configuration data of this object from TokenReader.
00208    *
00209    * This method reads members only, it does not read the section.
00210    *
00211    * @param rTr
00212    *   TokenReader to read from
00213    *
00214    * @exception Exception
00215    *   - Token mismatch (id 50, 51, 52)
00216    *   - IO error (id 1)
00217    */
00218   virtual void DoReadCore(TokenReader& rTr);
00219  
00220   /**
00221    * Write configuration data of this object to TokenWriter.
00222    *
00223    * The section defaults to "LuaFunctionDefinition", context ignored.
00224    *
00225    * @param rTw
00226    *   Reference to TokenWriter
00227    * @param rLabel
00228    *   Label of section to write
00229    * @param pContext
00230    *   Write context to provide contextual information
00231    *
00232    * @exception Exception 
00233    *   - IO errors (id 2)
00234    */
00235   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00236 
00237   /**
00238    * Write configuration data of this object to TokenWriter.
00239    *
00240    * This method writes plain member data, the section lables are not
00241    * written.
00242    *
00243    * @param rTw
00244    *   Reference to TokenWriter
00245    *
00246    * @exception Exception 
00247    *   - IO errors (id 2)
00248    */
00249   virtual void DoWriteCore(TokenWriter& rTw) const;
00250 
00251 
00252   /**
00253    * Assign prototype object
00254    *
00255    * @param pFunc
00256    *  Function instance
00257    *
00258    */
00259   virtual void Prototype(Function* pFunc);
00260 
00261   /** Typed prototype instance */
00262   LuaFunction* pLuaFunction;
00263 
00264   /** Lua code */
00265   std::string mLuaCode;
00266 
00267   /** Lua file */
00268   std::string mLuaFile;
00269 
00270 }; 
00271 
00272 
00273 /**
00274  * A LuaFunction is a faudes-function that executes a luafaudes script. 
00275  *
00276  * LuaFunction is derived from Function and implements the DoTypeCheck and DoExecute
00277  * interface to run the lua code as supplied by the corresponding function defintion.
00278  * Thus, it is considered an error to set the function definition to an object that
00279  * does not cast to a LuaFunctionDefinition.
00280  *
00281  * @ingroup LuabindingsPlugin
00282  */  
00283 
00284 class LuaFunction : public Function {
00285 
00286  public:
00287   /** 
00288    * Constructor 
00289    * For the function to be operational, a valid reference to the corresponding 
00290    * FunctionDefinition is required. The only exception is the prototype function
00291    * object used in the FunctionDefinition itself. 
00292    */
00293   LuaFunction(const LuaFunctionDefinition* fdef);
00294 
00295   /** Destructor */
00296   ~LuaFunction(void){};
00297 
00298   /**
00299    * Construct on heap.
00300    * Create a new instance of this function class and return pointer.
00301    * The new instance will use the same function definition as this instance.
00302    *
00303    * @return
00304    *  Pointer to faudes::Function instance.
00305    *
00306    */
00307   virtual LuaFunction* New() const;
00308 
00309 
00310   /**
00311    * Set function definition.
00312    * Normally, functions are provided with a function definition on construction.
00313    * The only exception are prototype objects used in function definitions themselfs 
00314    * and in the function registry.
00315    *
00316    * @param fdef
00317    *  Function definition to set.
00318    *
00319    */
00320   void Definition(const FunctionDefinition* fdef);
00321 
00322 
00323   /**
00324    * Get function definition.
00325    *
00326    * @return 
00327    *  Function definition used by this function.
00328    *
00329    */
00330   const LuaFunctionDefinition* Definition(void) const;
00331 
00332 
00333   /**
00334    * Syntax check lua code.
00335    *
00336    * This routine does all it needs to run the script,
00337    * except to invoke the specified function. The reasoning is, that
00338    * the script may hang and, thus, never return. A consequence
00339    * is, that you must set a variant and you must supply parameter 
00340    * values befor checking. You may use AllocateValues() and FreeValues() 
00341    * for this purpose. Errors are indicated by an exception.
00342    *
00343    * Note that the LuaFunctionDefinition provides a convenience wrapper
00344    * that runs the check on all variants and cares about value allocation.
00345    * 
00346    * @exception Exception
00347    *   - Error in Lua script (id 49)
00348    */
00349   void SyntaxCheck(void);
00350 
00351 
00352  protected:
00353 
00354   /**
00355    * Method to test the type of an assigned parameter with the
00356    * specified faudes::Signature (i.e. their TypeDefinition label).
00357    *
00358    * Note: this method is called by Function::Execute() before actual function 
00359    * execution via DoExecute(). It may be used to perform a dynamic cast in 
00360    * preparation of DoExecute(). The latter is only called, if all types match.
00361    * 
00362    * @param n
00363    *   Position of parameter to check
00364    * @return
00365    *   True if type matches signature.
00366    *
00367    * @exception Exception
00368    *  - Signature undefined (id 48)
00369    *  - Parameter number out of range (id 48)
00370    */
00371   virtual bool DoTypeCheck(int n);
00372 
00373   /**
00374    * Executes code as supplied by FunctionDefinition
00375    *
00376    * @exception Exception
00377    *  - Exception during lua setup (id 49)
00378    *  - Any exception during execution of script
00379    */
00380   virtual void DoExecute();
00381 
00382   /**
00383    * Execute stages
00384    *
00385    * @exception Exception
00386    *  - Exception during lua setup (id 49)
00387    */
00388   virtual void DoExecuteA();
00389 
00390   /**
00391    * Execute stages
00392    *
00393    * @exception Exception
00394    *  - Exception during lua setup (id 49)
00395    */
00396   virtual void DoExecuteB();
00397 
00398   /**
00399    * Execute stages
00400    *
00401    * @exception Exception
00402    *  - Exception during lua setup (id 49)
00403    *  - Any exception during execution of script
00404    */
00405   virtual void DoExecuteC();
00406 
00407   /**
00408    * Execute stages
00409    *
00410    * @exception Exception
00411    *  - Exception during lua setup (id 49)
00412    */
00413   virtual void DoExecuteD();
00414 
00415   /** Typed reference to definition */
00416   const LuaFunctionDefinition* pLuaFuncDef;
00417 
00418   /** State of Lua interpreter */
00419   lua_State* mpL;
00420   int mFtable;
00421 }; 
00422 
00423 
00424 } // namespace
00425 #endif // include

libFAUDES 2.16b --- 2010-9-8 --- c++ source docu by doxygen 1.6.3