|
libFAUDES
Sections
Index
|
lbp_function.hGo 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