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 name="LuaExtension::LargeGenerator">
00047  * 
00048  * <Documentation> 
00049  * Construct a generator by random.
00050  * </Documentation>
00051  * <Keywords> "luaextension" "example" </Keywords>
00052  *
00053  * <VariantSignatures>
00054  * <Signature name="LargeGen(#Q,#Sigma,GRes)">
00055  * <Parameter name="SizeQ"      ftype="Integer"   access="In"/>
00056  * <Parameter name="SizeSigma"  ftype="Integer"   access="In"/>
00057  * <Parameter name="Res"        ftype="Generator" access="Out" />
00058  * </Signature>
00059  * </VariantSignatures>
00060  * 
00061  * <LuaCode> 
00062  * __VERBATIM__
00063  * 
00064  * -- Extension reports on loading
00065  * print('loading luaextension "LargeGenerator"')
00066  *
00067  * -- Define my function (mangled version of variant name)
00068  * function LargeGen_Q_Sigma_GRes_(qn,sn,gen)
00069  *
00070  * -- Function reports on execution 
00071  * print(string.format('LargeGen(...): qn=%d sn=%d',qn,sn))
00072  *
00073  * -- Exeution code
00074  * gen:Clear()
00075  * for i=1,qn do
00076  *   gen:InsState(i)
00077  * end
00078  * for i=1,sn do 
00079  *   gen:InsEvent(string.format('ev_%d',i))
00080  * end
00081  *
00082  * -- By convention, we return all arguments
00083  * return qn,sn,gen
00084  * 
00085  * -- End of function definition
00086  * end
00087  * 
00088  * -- Extension reports on loading
00089  * print('loading luaextension: done')
00090  * 
00091  * __VERBATIM__
00092  * 
00093  * </LuaCode>
00094  * 
00095  * </LuaFunctionDefinition>
00096  * @endcode
00097  *
00098  * Alternatively to the embedded code, the luacode can be read from an external file, specified
00099  * by a section <tt>LuaFile</tt>. (not implemented)
00100  *
00101  * Restrictions and conventions:
00102  * - Typechecking is done via the Cast() function of the faudes type interface. As a 
00103  *   consequence, you may only use types that are registered with run-time-interface.
00104  * - On execution, the LuaFunction instance has to locate the respective function 
00105  *   in the supplied lua code. In order to allow for multiple variants, the convention is
00106  *   to have one lua function each with the name of the corresponding variant. Since
00107  *   variant names may contain funny characters, name matching is performed after
00108  *   replacing any sequence of non-alpha-numericals by "_". E.g. the variant "res=a+b" matches the
00109  *   lua function "res_a_b".
00110  * - Since luafaudes has no concept of const references, it is the responsability of the
00111  *   script programer to respect parameter types +In+, +Out+ and +InOut+.
00112  * - Integers, booleans ans strings are passed to Lua by value, any other parameters
00113  *   are passed by reference. To have a uniform interface, the convention is that the 
00114  *   lua function must return all specified parameters.
00115  *
00116  *
00117  *
00118  * @ingroup LuabindingsPlugin
00119  */
00120 
00121 class LuaFunctionDefinition : public FunctionDefinition {
00122 
00123   // faudes type
00124   FAUDES_TYPE_DECLARATION(LuaFunctionDefinition,LuaFunctionDefinition,FunctionDefinition)
00125 
00126 public:
00127 
00128   /** 
00129    * Constructor. 
00130    *
00131    * In contrast to the std FunctionDefinition, the default constructor 
00132    * sets up a valid lua function definition with a newly created LuaFunction 
00133    * as prototype.
00134    * Of course, you will need to set the signatures and the lua code
00135    * to obtain an operational function.
00136    */
00137   LuaFunctionDefinition(const std::string& name="");
00138 
00139   /** 
00140    * Copy constructor 
00141    */
00142   LuaFunctionDefinition(const LuaFunctionDefinition& rSrc);
00143 
00144   /**
00145    * Destructor
00146    */
00147   virtual ~LuaFunctionDefinition(void){};
00148 
00149 
00150   /**
00151    * Clear documentation-data, signature and script (keep prototype)
00152    */
00153   void Clear(void);
00154 
00155   /**
00156    * Get Lua code
00157    * 
00158    * @return
00159    *   Lua code as std string
00160    */
00161   const std::string& LuaCode(void) const;
00162 
00163   /**
00164    * Set Lua code
00165    * 
00166    * @param rCode
00167    *   Lua code as std string
00168    */
00169   void LuaCode(const std::string& rCode);
00170 
00171 
00172   /**
00173    * Syntax check lua code.
00174    *
00175    * This routine instantiates a LuaFunction from this function definition
00176    * and does all it needs to run the script, except to invoke the any of the
00177    * variant functions. The reasoning is, that the script may hang and, thus, 
00178    * never return. Errors are indicated by an exception.
00179    * 
00180    * @return
00181    *   Error message as string, or empty string on success
00182    */
00183   std::string SyntaxCheck(void);
00184 
00185 protected:
00186 
00187   /**
00188    * Std faudes type interface: assignment.
00189    *
00190    * @param rSrc 
00191    *    Source to copy from
00192    * @return Reference to this object.
00193    */
00194   virtual void DoAssign(const LuaFunctionDefinition& rSrc);
00195 
00196   /**
00197    * Std faudes type interface: test equality
00198    * 
00199    * @param rOther 
00200    *    Other object to compare with.
00201    * @return 
00202    *   True on match.
00203    */
00204   virtual bool DoEqual(const LuaFunctionDefinition& rOther) const;
00205 
00206   /**
00207    * Read configuration data of this object from TokenReader.
00208    * Actual reading is done by DoReadCore.
00209    *
00210    * The section defaults to "LuaFunctionDefinition", context ignored.
00211    *
00212    * @param rTr
00213    *   TokenReader to read from
00214    * @param rLabel
00215    *   Section to read
00216    * @param pContext
00217    *   Read context to provide contextual information (ignored)
00218    *
00219    * @exception Exception
00220    *   - Token mismatch (id 50, 51, 52)
00221    *   - IO error (id 1)
00222    */
00223   virtual void DoRead(TokenReader& rTr,  const std::string& rLabel = "", const Type* pContext=0);
00224  
00225   /**
00226    * Read configuration data of this object from TokenReader.
00227    *
00228    * This method reads members only, it does not read the section.
00229    *
00230    * @param rTr
00231    *   TokenReader to read from
00232    *
00233    * @exception Exception
00234    *   - Token mismatch (id 50, 51, 52)
00235    *   - IO error (id 1)
00236    */
00237   virtual void DoReadCore(TokenReader& rTr);
00238  
00239   /**
00240    * Write configuration data of this object to TokenWriter.
00241    *
00242    * The section defaults to "LuaFunctionDefinition", context ignored.
00243    *
00244    * @param rTw
00245    *   Reference to TokenWriter
00246    * @param rLabel
00247    *   Label of section to write
00248    * @param pContext
00249    *   Write context to provide contextual information
00250    *
00251    * @exception Exception 
00252    *   - IO errors (id 2)
00253    */
00254   virtual void DoWrite(TokenWriter& rTw, const std::string& rLabel="",const Type* pContext=0) const;
00255 
00256   /**
00257    * Write configuration data of this object to TokenWriter.
00258    *
00259    * This method writes plain member data, the section lables are not
00260    * written.
00261    *
00262    * @param rTw
00263    *   Reference to TokenWriter
00264    *
00265    * @exception Exception 
00266    *   - IO errors (id 2)
00267    */
00268   virtual void DoWriteCore(TokenWriter& rTw) const;
00269 
00270 
00271   /**
00272    * Assign prototype object
00273    *
00274    * @param pFunc
00275    *  Function instance
00276    *
00277    */
00278   virtual void Prototype(Function* pFunc);
00279 
00280   /** Typed prototype instance */
00281   LuaFunction* pLuaFunction;
00282 
00283   /** Lua code */
00284   std::string mLuaCode;
00285 
00286   /** Lua file */
00287   std::string mLuaFile;
00288 
00289 }; 
00290 
00291 
00292 /**
00293  * A LuaFunction is a faudes-function that executes a luafaudes script. 
00294  *
00295  * LuaFunction is derived from Function and implements the DoTypeCheck and DoExecute
00296  * interface to run the lua code as supplied by the corresponding function defintion.
00297  * Thus, it is considered an error to set the function definition to an object that
00298  * does not cast to a LuaFunctionDefinition.
00299  *
00300  * @ingroup LuabindingsPlugin
00301  */  
00302 
00303 class LuaFunction : public Function {
00304 
00305  public:
00306   /** 
00307    * Constructor. 
00308    * For the function to be operational, a valid reference to the corresponding 
00309    * LuaFunctionDefinition is required. The only exception is the prototype function
00310    * object used in the LuaFunctionDefinition itself. 
00311    */
00312   LuaFunction(const LuaFunctionDefinition* fdef);
00313 
00314   /** Destructor */
00315   ~LuaFunction(void){};
00316 
00317   /**
00318    * Construct on heap.
00319    * Create a new instance of this function class and return pointer.
00320    * The new instance will use the same function definition as this instance.
00321    *
00322    * @return
00323    *  Pointer to faudes::Function instance.
00324    *
00325    */
00326   virtual LuaFunction* New() const;
00327 
00328 
00329   /**
00330    * Set function definition.
00331    * Normally, functions are provided with a function definition on construction.
00332    * The only exception are prototype objects used in function definitions themselfs 
00333    * and in the function registry.
00334    *
00335    * @param fdef
00336    *  Function definition to set.
00337    *
00338    */
00339   void Definition(const FunctionDefinition* fdef);
00340 
00341 
00342   /**
00343    * Get function definition.
00344    *
00345    * @return 
00346    *  Function definition used by this function.
00347    *
00348    */
00349   const LuaFunctionDefinition* Definition(void) const;
00350 
00351 
00352   /**
00353    * Syntax check lua code.
00354    *
00355    * This routine does all it needs to run the script,
00356    * except to invoke the specified function. The reasoning is, that
00357    * the script may hang and, thus, never return. A consequence
00358    * is, that you must set a variant and you must supply parameter 
00359    * values befor checking. You may use AllocateValues() and FreeValues() 
00360    * for this purpose. Errors are indicated by an exception.
00361    *
00362    * Note that the LuaFunctionDefinition provides a convenience wrapper
00363    * that runs the check on all variants and cares about value allocation.
00364    * 
00365    * @exception Exception
00366    *   - Error in Lua script (id 49)
00367    */
00368   void SyntaxCheck(void);
00369 
00370 
00371  protected:
00372 
00373   /**
00374    * Method to test the type of an assigned parameter with the
00375    * specified faudes::Signature (i.e. their TypeDefinition label).
00376    *
00377    * Note: this method is called by Function::Execute() before actual function 
00378    * execution via DoExecute(). It may be used to perform a dynamic cast in 
00379    * preparation of DoExecute(). The latter is only called, if all types match.
00380    * 
00381    * @param n
00382    *   Position of parameter to check
00383    * @return
00384    *   True if type matches signature.
00385    *
00386    * @exception Exception
00387    *  - Signature undefined (id 48)
00388    *  - Parameter number out of range (id 48)
00389    */
00390   virtual bool DoTypeCheck(int n);
00391 
00392   /**
00393    * Executes code as supplied by FunctionDefinition
00394    *
00395    * @exception Exception
00396    *  - Exception during lua setup (id 49)
00397    *  - Any exception during execution of script
00398    */
00399   virtual void DoExecute();
00400 
00401   /**
00402    * Execute stages
00403    *
00404    * @exception Exception
00405    *  - Exception during lua setup (id 49)
00406    */
00407   virtual void DoExecuteA();
00408 
00409   /**
00410    * Execute stages
00411    *
00412    * @exception Exception
00413    *  - Exception during lua setup (id 49)
00414    */
00415   virtual void DoExecuteB();
00416 
00417   /**
00418    * Execute stages
00419    *
00420    * @exception Exception
00421    *  - Exception during lua setup (id 49)
00422    *  - Any exception during execution of script
00423    */
00424   virtual void DoExecuteC();
00425 
00426   /**
00427    * Execute stages
00428    *
00429    * @exception Exception
00430    *  - Exception during lua setup (id 49)
00431    */
00432   virtual void DoExecuteD();
00433 
00434   /** Typed reference to definition */
00435   const LuaFunctionDefinition* pLuaFuncDef;
00436 
00437   /** State of Lua interpreter */
00438   lua_State* mpL;
00439   int mFtable;
00440   void* mFType;
00441 }; 
00442 
00443 
00444 } // namespace
00445 #endif // include

libFAUDES 2.18b --- 2010-12-17 --- c++ source docu by doxygen 1.6.3