faudes::LuaFunctionDefinition Class Reference
[Lua Bindings PlugIn]

A LuaFunctionDefinition is derived from FunctionDefinition to define a faudes-function by a Lua script. More...

#include <lbp_function.h>

List of all members.

Public Member Functions

 LuaFunctionDefinition (const std::string &name="")
 Constructor.
 LuaFunctionDefinition (const LuaFunctionDefinition &rSrc)
 Copy constructor.
virtual ~LuaFunctionDefinition (void)
 Destructor.
void Clear (void)
 Clear documentation-data, signature and script (keep prototype).
const std::string & LuaCode (void) const
 Get Lua code.
void LuaCode (const std::string &rCode)
 Set Lua code.
void DefaultL (LuaState *pL)
 Set default lua state.
LuaStateDefaultL (void) const
 Get default lua state.
std::string SyntaxCheck (void)
 Syntax check lua code.
std::string Evaluate (LuaState *pL=NULL)
 Evaluate lua code.
void Install (LuaState *pL=NULL) const
 Install this function to a Lua state.
void Install (lua_State *pLL) const
 Install this function to a Lua state.

Static Public Member Functions

static void Register (const std::string &rFilename)

Protected Member Functions

virtual void DoAssign (const LuaFunctionDefinition &rSrc)
 Std faudes type interface: assignment.
virtual bool DoEqual (const LuaFunctionDefinition &rOther) const
 Std faudes type interface: test equality.
virtual void DoRead (TokenReader &rTr, const std::string &rLabel="", const Type *pContext=0)
 Read configuration data of this object from TokenReader.
virtual void DoReadCore (TokenReader &rTr)
 Read configuration data of this object from TokenReader.
virtual void DoWrite (TokenWriter &rTw, const std::string &rLabel="", const Type *pContext=0) const
 Write configuration data of this object to TokenWriter.
virtual void DoWriteCore (TokenWriter &rTw) const
 Write configuration data of this object to TokenWriter.
virtual void Prototype (Function *pFunc)
 Assign prototype object.

Protected Attributes

LuaFunctionpLuaFunction
 Typed prototype instance.
std::string mLuaCode
 Lua code.
std::string mLuaFile
 Lua file.
LuaStatepDefaultL
 Default lua state.

Detailed Description

A LuaFunctionDefinition is derived from FunctionDefinition to define a faudes-function by a Lua script.

It has the Lua code as an additional member variable and uses a LuaFunction as a prototype object. In particular, LuaFunctionDefinitions are allways valid in the sense that hey have a prototype. The LuaFunction object implements DoTypeCheck and DoExecute to run the specifed Lua code. Thus, a LuaFunction can be tranparently accessed via the run-time interface and bahves like any other registered faudes function.

Alternatively, you can use the Install() method to install a LuaFunctionDefinition to a LuaState. Then, the function can be accessed by the Lua interpreter. Install() will generate code to dispatch the function variants with the same semantics as the SWIG generated interface for other faudes functions. Again, integeration is transparent from the perspective of the Lua interpreter.

The token io format is demonstrated by the following example:

 <LuaFunctionDefinition name="LuaExtension::LargeGenerator">
 
 <Documentation> 
 Construct a generator by random.
 </Documentation>
 <Keywords> "luaextension" "example" </Keywords>

 <VariantSignatures>
 <Signature name="LargeGen(#Q,#Sigma,GRes)">
 <Parameter name="SizeQ"      ftype="Integer"   access="In"/>
 <Parameter name="SizeSigma"  ftype="Integer"   access="In"/>
 <Parameter name="Res"        ftype="Generator" access="Out" />
 </Signature>
 </VariantSignatures>
 
 <LuaCode> 
 <[CDATA[
 
 -- Extension reports on loading
 print('loading luaextension "LargeGenerator"')

 -- Define my function (mangled version of variant name)
 function faudes.LargeGen_Q_Sigma_GRes(qn,sn,gen)

 -- Function reports on execution 
 print(string.format('LargeGen(...): qn=%d sn=%d',qn,sn))

 -- Exeution code
 gen:Clear()
 for i=1,qn do
   gen:InsState(i)
 end
 for i=1,sn do 
   gen:InsEvent(string.format('ev_%d',i))
 end

 -- Done
 return 
 
 -- End of function definition
 end
 
 -- Extension reports on loading
 print('loading luaextension: done')
 
 ]]>
 </LuaCode>
 
 </LuaFunctionDefinition>

Restrictions and conventions:

  • Type-checking is done via the Cast() function of the faudes Type interface. As a consequence, you may only use types that are registered with the run-time-interface.
  • On execution, the LuaFunction instance has to locate the respective function in the supplied lua code. In order to allow for multiple variants, the convention is to have one lua function each with the name of the corresponding variant. Since variant names may contain funny characters, name matching is performed after so called mangeling: any sequence of non-alpha-numerics is replaced by a single "_", a trailing "_" is dropped. E.g. the variant res=a+b matches the Lua function res_a_b.
  • Parameters other than elementary (integer, boolean and string) are passed to the Lua function by reference. However, Lua will consistently interpret the reference itself as a parameter value. Thus, to assign a value to an access="Out" or access="InOut" parameter, you must use the assigment memberfunction Assign (as opposed to the assignment operator "=").
  • Elementary types (i.e. integers, booleans and strings) are passed to the Lua function by value. Thus, it would be pointless to have an elementary typed parameter with access attribute other than access="In". In order to implement elementary typed return values, the respective Lua function must return the corresponding values by an approriate return statement. The signature should indicate this by the attribute creturn="true". The current implementation will automatically imply creturn="true" for any access="Out" or access="InOut".
  • Since luafaudes has no concept of const references, it is the responsability of the script programer to respect parameter access attributes.
  • When using Install() to install the function to a LuaState, a single wrapper function will be defined to dispatch variants. By convention, this function is located in faudes.name_of_fdef, where name_of_fdef is the name of the respective LuaFunctionDefinition.

Definition at line 140 of file lbp_function.h.


Constructor & Destructor Documentation

faudes::LuaFunctionDefinition::LuaFunctionDefinition ( const std::string &  name = ""  ) 

Constructor.

In contrast to the std FunctionDefinition, the default constructor sets up a valid lua function definition with a newly created LuaFunction as prototype. Of course, you will need to set the signatures and the lua code to obtain an operational function.

Definition at line 177 of file lbp_function.cpp.

faudes::LuaFunctionDefinition::LuaFunctionDefinition ( const LuaFunctionDefinition rSrc  ) 

Copy constructor.

Definition at line 188 of file lbp_function.cpp.

virtual faudes::LuaFunctionDefinition::~LuaFunctionDefinition ( void   )  [inline, virtual]

Destructor.

Definition at line 166 of file lbp_function.h.


Member Function Documentation

void faudes::LuaFunctionDefinition::Clear ( void   )  [virtual]

Clear documentation-data, signature and script (keep prototype).

Reimplemented from faudes::FunctionDefinition.

Definition at line 223 of file lbp_function.cpp.

LuaState * faudes::LuaFunctionDefinition::DefaultL ( void   )  const

Get default lua state.

Returns:
Lua state

Definition at line 251 of file lbp_function.cpp.

void faudes::LuaFunctionDefinition::DefaultL ( LuaState pL  ) 

Set default lua state.

Sets the default lua state on which functions that refer to this function definition will use for execution. If set to NULL (e.g. on consruction), the global state is used. However, the function object itself may overwrite the default.

Parameters:
pL Lua state

Definition at line 257 of file lbp_function.cpp.

void faudes::LuaFunctionDefinition::DoAssign ( const LuaFunctionDefinition rSrc  )  [protected, virtual]

Std faudes type interface: assignment.

Parameters:
rSrc Source to copy from
Returns:
Reference to this object.

Definition at line 197 of file lbp_function.cpp.

bool faudes::LuaFunctionDefinition::DoEqual ( const LuaFunctionDefinition rOther  )  const [protected, virtual]

Std faudes type interface: test equality.

Parameters:
rOther Other object to compare with.
Returns:
True on match.

Definition at line 213 of file lbp_function.cpp.

void faudes::LuaFunctionDefinition::DoRead ( TokenReader rTr,
const std::string &  rLabel = "",
const Type pContext = 0 
) [protected, virtual]

Read configuration data of this object from TokenReader.

Actual reading is done by DoReadCore.

The section defaults to "LuaFunctionDefinition", context ignored.

Parameters:
rTr TokenReader to read from
rLabel Section to read
pContext Read context to provide contextual information (ignored)
Exceptions:
Exception 
  • Token mismatch (id 50, 51, 52)
  • IO error (id 1)

Reimplemented from faudes::FunctionDefinition.

Definition at line 528 of file lbp_function.cpp.

void faudes::LuaFunctionDefinition::DoReadCore ( TokenReader rTr  )  [protected, virtual]

Read configuration data of this object from TokenReader.

This method reads members only, it does not read the section.

Parameters:
rTr TokenReader to read from
Exceptions:
Exception 
  • Token mismatch (id 50, 51, 52)
  • IO error (id 1)

Reimplemented from faudes::FunctionDefinition.

Definition at line 567 of file lbp_function.cpp.

void faudes::LuaFunctionDefinition::DoWrite ( TokenWriter rTw,
const std::string &  rLabel = "",
const Type pContext = 0 
) const [protected, virtual]

Write configuration data of this object to TokenWriter.

The section defaults to "LuaFunctionDefinition", context ignored.

Parameters:
rTw Reference to TokenWriter
rLabel Label of section to write
pContext Write context to provide contextual information
Exceptions:
Exception 
  • IO errors (id 2)

Reimplemented from faudes::FunctionDefinition.

Definition at line 600 of file lbp_function.cpp.

void faudes::LuaFunctionDefinition::DoWriteCore ( TokenWriter rTw  )  const [protected, virtual]

Write configuration data of this object to TokenWriter.

This method writes plain member data, the section lables are not written.

Parameters:
rTw Reference to TokenWriter
Exceptions:
Exception 
  • IO errors (id 2)

Reimplemented from faudes::FunctionDefinition.

Definition at line 609 of file lbp_function.cpp.

std::string faudes::LuaFunctionDefinition::Evaluate ( LuaState pL = NULL  ) 

Evaluate lua code.

This routine evaluates the LuaCode literally. This method is used to execute LuaCode that is not part of any particular variant. To execute a particular variant, instantiate a LuaFunction and invoke Execute().

If you pass NULL as destination state, the global state will be used.

Parameters:
pL Reference to the Lua state
Returns:
Error message as string, or empty string on success

Definition at line 300 of file lbp_function.cpp.

void faudes::LuaFunctionDefinition::Install ( lua_State *  pLL  )  const

Install this function to a Lua state.

Alternative signature for applications that do not use the the LuaState wrapper class. See also Install(LuaState*).

Parameters:
pLL Reference to the Lua state

Definition at line 323 of file lbp_function.cpp.

void faudes::LuaFunctionDefinition::Install ( LuaState pL = NULL  )  const

Install this function to a Lua state.

This routine installs the Lua code of this function definition to the table "faudes" of the specified Lua state. It also constructs a wrapper function to dispatch signatures and palces this in the table "faudes". Effectively, the resulting Lua state is prepared to execute the Lua function with the same semantics as used for SWIG generated wrappers of C++ functions.

If you pass NULL as destination state, the global state will be used.

Parameters:
pL Reference to the Lua state

Definition at line 317 of file lbp_function.cpp.

void faudes::LuaFunctionDefinition::LuaCode ( const std::string &  rCode  ) 

Set Lua code.

Parameters:
rCode Lua code as std string

Definition at line 246 of file lbp_function.cpp.

const std::string & faudes::LuaFunctionDefinition::LuaCode ( void   )  const

Get Lua code.

Returns:
Lua code as std string

Definition at line 241 of file lbp_function.cpp.

void faudes::LuaFunctionDefinition::Prototype ( Function pFunc  )  [protected, virtual]

Assign prototype object.

Parameters:
pFunc Function instance

Reimplemented from faudes::FunctionDefinition.

Definition at line 233 of file lbp_function.cpp.

void faudes::LuaFunctionDefinition::Register ( const std::string &  rFilename  )  [static]

Definition at line 543 of file lbp_function.cpp.

std::string faudes::LuaFunctionDefinition::SyntaxCheck ( void   ) 

Syntax check lua code.

This routine instantiates a LuaFunction from this function definition and does all it needs to run the script, except to invoke the any of the variant functions. The reasoning is, that the script may hang and, thus, never return. Errors are indicated returned as an error string.

Returns:
Error message as string, or empty string on success

Definition at line 262 of file lbp_function.cpp.


Member Data Documentation

std::string faudes::LuaFunctionDefinition::mLuaCode [protected]

Lua code.

Definition at line 390 of file lbp_function.h.

std::string faudes::LuaFunctionDefinition::mLuaFile [protected]

Lua file.

Definition at line 393 of file lbp_function.h.

Default lua state.

Definition at line 396 of file lbp_function.h.

Typed prototype instance.

Definition at line 387 of file lbp_function.h.


The documentation for this class was generated from the following files:

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