faudes::LuaFunctionDefinition Class Reference

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.

#include <lbp_function.h>

Public Member Functions
	LuaFunctionDefinition (const std::string &name="")
	Constructor. More...
	LuaFunctionDefinition (const LuaFunctionDefinition &rSrc)
	Copy constructor. More...
virtual	~LuaFunctionDefinition (void)
	Destructor. More...
void	Clear (void)
	Clear documentation-data, signature and script (keep prototype) More...
const std::string &	LuaCode (void) const
	Get Lua code. More...
void	LuaCode (const std::string &rCode)
	Set Lua code. More...
void	DefaultL (LuaState *pL)
	Set default lua state. More...
LuaState *	DefaultL (void) const
	Get default lua state. More...
std::string	SyntaxCheck (void)
	Syntax check lua code. More...
std::string	Evaluate (LuaState *pL=NULL)
	Evaluate lua code. More...
void	Install (LuaState *pL=NULL) const
	Install this function to a Lua state. More...
void	Install (lua_State *pLL) const
	Install this function to a Lua state. More...
Public Member Functions inherited from faudes::FunctionDefinition
	FunctionDefinition (const std::string &name="")
	Constructor. More...
	FunctionDefinition (const FunctionDefinition &rSrc)
	Copy Constructor. More...
virtual	~FunctionDefinition ()
	Destructor. More...
virtual void	ClearVariants (void)
	Clear variants (keep docu and prototype) More...
const Function *	Prototype (void) const
	Return pointer to function object prototype. More...
Function *	NewFunction () const
	Construct function on heap. More...
int	VariantsSize (void) const
	Return number of supported Signature instances. More...
bool	ExistsVariant (const std::string &varname) const
	Test existence of variant by its name. More...
int	VariantIndex (const std::string &rName) const
	Return index of Signature by name. More...
const Signature &	Variant (const std::string &rName) const
	Return reference to Signature by name. More...
const Signature &	Variant (int n) const
	Return reference to Signature by index. More...
virtual void	AppendVariant (const Signature &pVar)
	Add Signature to function definition. More...
Public Member Functions inherited from faudes::Documentation
	Documentation (void)
	Constructor. More...
	Documentation (const Documentation &rOther)
	Copy constructor. More...
virtual	~Documentation (void)
	Destructor. More...
const std::string &	Name (void) const
	Get name of the entety to document (aka faudes-type or faudes-function). More...
const std::string &	PlugIn (void) const
	Get name of plugin. More...
const std::string &	CType (void) const
	Get corresponding C++ type. More...
const std::string &	TextDoc (void) const
const std::string &	HtmlDoc (void) const
const std::string &	Keywords (void) const
std::string	MatchKeyword (const std::string &rPattern) const
	Search comma-seperated keywords for a substring. More...
int	KeywordsSize (void) const
	Not implemented. More...
std::string	KeywordAt (int pos) const
bool	AutoRegistered (void) const
	Get auto-register flag. More...
bool	ApplicationRegistered (void) const
	Get application-registered flag. More...
virtual void	MergeDocumentation (TokenReader &rTr)
	Merge documentation from token stream. More...
Public Member Functions inherited from faudes::Type
	Type (void)
	Constructor. More...
	Type (const Type &rType)
	Copy constructor. More...
virtual	~Type (void)
	Destructor. More...
virtual Type *	New (void) const
	Construct on heap. More...
virtual Type *	Copy (void) const
	Construct on heap. More...
virtual const Type *	Cast (const Type *pOther) const
	Cast other object to this type. More...
virtual Type &	Assign (const Type &rSrc)
	Assign configuration data from other object. More...
virtual Type &	operator= (const Type &rSrc)
	Assign configurationdata from other object. More...
virtual bool	Equal (const Type &rOther) const
	Test equality of configuration data. More...
virtual bool	operator== (const Type &rOther) const
	Test equality of configuration data. More...
virtual bool	operator!= (const Type &rOther) const
	Test equality of configuration data. More...
virtual const std::string &	TypeName (void) const
	Get objects's type name. More...
void	Write (const Type *pContext=0) const
	Write configuration data to console. More...
void	Write (const std::string &pFileName, const std::string &rLabel="", const Type *pContext=0, std::ios::openmode openmode=std::ios::out|std::ios::trunc) const
	Write configuration data to a file. More...
void	Write (const std::string &pFileName, std::ios::openmode openmode) const
	Write configuration data to a file. More...
void	Write (TokenWriter &rTw, const std::string &rLabel="", const Type *pContext=0) const
	Write configuration data to TokenWriter. More...
virtual void	XWrite (const std::string &pFileName, const std::string &rLabel="", const Type *pContext=0) const
	Write configuration data to an XML file. More...
void	XWrite (const Type *pContext=0) const
	Write configuration data in XML format to concole Note: this write function uses the virtual function DoXWrite(), to be reimplemented by derived classes. More...
void	XWrite (TokenWriter &rTw, const std::string &rLabel="", const Type *pContext=0) const
	Write configuration data in XML format to TokenWriter. More...
std::string	ToString (const std::string &rLabel="", const Type *pContext=0) const
	Write configuration data to a string. More...
std::string	ToText (const std::string &rLabel="", const Type *pContext=0) const
	Write configuration data to a formated string. More...
void	DWrite (const Type *pContext=0) const
	Write configuration data to console, debugging format. More...
void	DWrite (const std::string &pFileName, const std::string &rLabel="", const Type *pContext=0, std::ios::openmode openmode=std::ios::out|std::ios::trunc) const
	Write configuration data to a file, debugging format. More...
void	DWrite (TokenWriter &rTw, const std::string &rLabel="", const Type *pContext=0) const
	Write configuration data in debug format to TokenWriter. More...
void	SWrite (TokenWriter &rTw) const
	Write statistics comment to TokenWriter. More...
void	SWrite (void) const
	Write statistics comment to console. More...
std::string	ToSText (void) const
	Write statistics to a string. More...
void	Read (const std::string &rFileName, const std::string &rLabel="", const Type *pContext=0)
	Read configuration data from file with label specified. More...
void	FromString (const std::string &rString, const std::string &rLabel="", const Type *pContext=0)
	Read configuration data from a string. More...
void	Read (TokenReader &rTr, const std::string &rLabel="", const Type *pContext=0)
	Read configuration data from TokenReader with label sepcified. More...

Static Public Member Functions
static void	Register (const std::string &rFilename)
Static Public Member Functions inherited from faudes::FunctionDefinition
template<class T >
static FunctionDefinition *	Constructor (const std::string &rFunctName="")
	Construct empty FunctionDefinition object. More...
template<class T >
static FunctionDefinition *	FromFile (const std::string &rFileName)
	Construct FunctionDefinition object and get name and docu from file. More...

Protected Member Functions
virtual void	DoAssign (const LuaFunctionDefinition &rSrc)
	Std faudes type interface: assignment. More...
virtual bool	DoEqual (const LuaFunctionDefinition &rOther) const
	Std faudes type interface: test equality. More...
virtual void	DoRead (TokenReader &rTr, const std::string &rLabel="", const Type *pContext=0)
	Read configuration data of this object from TokenReader. More...
virtual void	DoReadCore (TokenReader &rTr)
	Read configuration data of this object from TokenReader. More...
virtual void	DoWrite (TokenWriter &rTw, const std::string &rLabel="", const Type *pContext=0) const
	Write configuration data of this object to TokenWriter. More...
virtual void	DoWriteCore (TokenWriter &rTw) const
	Write configuration data of this object to TokenWriter. More...
virtual void	Prototype (Function *pFunc)
	Assign prototype object. More...
Protected Member Functions inherited from faudes::FunctionDefinition
void	DoAssign (const FunctionDefinition &rSrc)
	Std faudes type interface: assignment. More...
bool	DoEqual (const FunctionDefinition &rOther) const
	Std faudes type interface: test equality. More...
Protected Member Functions inherited from faudes::Documentation
void	Name (const std::string &name)
	Set name. More...
void	PlugIn (const std::string &plugin)
	Set name of plugin. More...
void	CType (const std::string &name)
	Set C++ type. More...
void	TextDoc (const std::string &textdoc)
	Set a short textual documentation. More...
void	AutoRegistered (bool flag)
	Set auto-register flag. More...
void	ApplicationRegistered (bool flag)
	Set application-registered flag. More...
void	HtmlDoc (const std::string &fname)
	Set name of file pointing to the html documentation. More...
void	AddKeyword (const std::string &rKeyword)
	Append keyword. More...
void	DoAssign (const Documentation &rSrc)
	Std faudes type interface: assignment. More...
bool	DoEqual (const Documentation &rOther) const
	Std faudes type interface: test equality. More...
Protected Member Functions inherited from faudes::Type
void	DoAssign (const Type &rSrc)
	Assign configuration data from other object. More...
bool	DoEqual (const Type &rOther) const
	Test equality of configuration data. More...
virtual void	DoXWrite (TokenWriter &rTw, const std::string &rLabel="", const Type *pContext=0) const
	Write configuration data of this object to TokenWriter in XML format. More...
virtual void	DoDWrite (TokenWriter &rTw, const std::string &rLabel="", const Type *pContext=0) const
	Write configuration data in debugging format to TokenWriter. More...
virtual void	DoSWrite (TokenWriter &rTw) const
	Write statistical data as a comment to TokenWriter. More...
virtual const TypeDefinition *	TypeDefinitionp (void) const
	Get objects's type definition. More...
virtual Token	XBeginTag (const std::string &rLabel="", const std::string &rFallbackLabel="") const

Protected Attributes
LuaFunction *	pLuaFunction
	Typed prototype instance. More...
std::string	mLuaCode
	Lua code. More...
std::string	mLuaFile
	Lua file. More...
LuaState *	pDefaultL
	Default lua state. More...
Protected Attributes inherited from faudes::FunctionDefinition
Function *	mpFunction
	Prototype instance. More...
std::vector< faudes::Signature >	mVariants
	Vector containing all supported Signatures. More...
std::map< std::string, int >	mVariantIndexMap
	Variant name to index map. More...
Protected Attributes inherited from faudes::Documentation
std::string	mName
	Faudes name. More...
std::string	mPlugIn
	Faudes plugin. More...
std::string	mCType
	Corresponing C++ type, or "" if no such. More...
std::string	mTextDoc
	String containing the text-documentation. More...
std::string	mHtmlDoc
	String containing the filename of the corresponding html-documentation. More...
std::string	mKeywords
	Comma-seperated string containing all keywords. More...
bool	mAutoRegistered
	Flag to indicate automated registration. More...
bool	mApplicationRegistered
	Flag to indicate application registration. More...

Additional Inherited Members
Static Protected Attributes inherited from faudes::Documentation
static const char	mDelim = ';'
	Constant characted used to seperate keywords. More...

Constructor & Destructor Documentation

LuaFunctionDefinition() [1/2]

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 180 of file lbp_function.cpp.

LuaFunctionDefinition() [2/2]

faudes::LuaFunctionDefinition::LuaFunctionDefinition

(

const LuaFunctionDefinition &

rSrc

)

Copy constructor.

Definition at line 191 of file lbp_function.cpp.

~LuaFunctionDefinition()

virtual faudes::LuaFunctionDefinition::~LuaFunctionDefinition ( void  )

inlinevirtual

Destructor.

Definition at line 166 of file lbp_function.h.

Member Function Documentation

Clear()

void faudes::LuaFunctionDefinition::Clear ( void  )

virtual

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

Reimplemented from faudes::FunctionDefinition.

Definition at line 226 of file lbp_function.cpp.

DefaultL() [1/2]

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 260 of file lbp_function.cpp.

DefaultL() [2/2]

LuaState * faudes::LuaFunctionDefinition::DefaultL

(

void

)

const

Get default lua state.

Returns

Lua state

Definition at line 254 of file lbp_function.cpp.

DoAssign()

void faudes::LuaFunctionDefinition::DoAssign ( const LuaFunctionDefinition &  rSrc )

protectedvirtual

Std faudes type interface: assignment.

Parameters

rSrc	Source to copy from

Returns

Reference to this object.

Definition at line 200 of file lbp_function.cpp.

DoEqual()

bool faudes::LuaFunctionDefinition::DoEqual ( const LuaFunctionDefinition &  rOther ) const

protectedvirtual

Std faudes type interface: test equality.

Parameters

rOther

Other object to compare with.

Returns

True on match.

Definition at line 216 of file lbp_function.cpp.

DoRead()

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

protectedvirtual

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.

DoReadCore()

virtual void faudes::LuaFunctionDefinition::DoReadCore ( TokenReader &  rTr )

protectedvirtual

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.

DoWrite()

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

protectedvirtual

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.

DoWriteCore()

virtual void faudes::LuaFunctionDefinition::DoWriteCore ( TokenWriter &  rTw ) const

protectedvirtual

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.

Evaluate()

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 303 of file lbp_function.cpp.

Install() [1/2]

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 326 of file lbp_function.cpp.

Install() [2/2]

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 320 of file lbp_function.cpp.

LuaCode() [1/2]

void faudes::LuaFunctionDefinition::LuaCode

(

const std::string &

rCode

)

Set Lua code.

Parameters

rCode

Lua code as std string

Definition at line 249 of file lbp_function.cpp.

LuaCode() [2/2]

const std::string & faudes::LuaFunctionDefinition::LuaCode

(

void

)

const

Get Lua code.

Returns

Lua code as std string

Definition at line 244 of file lbp_function.cpp.

Prototype()

void faudes::LuaFunctionDefinition::Prototype ( Function *  pFunc )

protectedvirtual

Assign prototype object.

Parameters

pFunc

Function instance

Reimplemented from faudes::FunctionDefinition.

Definition at line 236 of file lbp_function.cpp.

Register()

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

static

SyntaxCheck()

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 265 of file lbp_function.cpp.

Member Data Documentation

mLuaCode

std::string faudes::LuaFunctionDefinition::mLuaCode

protected

Lua code.

Definition at line 390 of file lbp_function.h.

mLuaFile

std::string faudes::LuaFunctionDefinition::mLuaFile

protected

Lua file.

Definition at line 393 of file lbp_function.h.

pDefaultL

LuaState* faudes::LuaFunctionDefinition::pDefaultL

protected

Default lua state.

Definition at line 396 of file lbp_function.h.

pLuaFunction

LuaFunction* faudes::LuaFunctionDefinition::pLuaFunction

protected

Typed prototype instance.

Definition at line 387 of file lbp_function.h.

---

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

• lbp_function.h
• lbp_function.cpp