|
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> 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