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 Copy (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 142 of file lbp_function.h.

#include <lbp_function.h>

Public Member Functions
	LuaFunctionDefinition (const std::string &name="")

	LuaFunctionDefinition (const LuaFunctionDefinition &rSrc)

virtual	~LuaFunctionDefinition (void)

void	Clear (void)

const std::string &	LuaCode (void) const

void	LuaCode (const std::string &rCode)

void	DefaultL (LuaState *pL)

LuaState *	DefaultL (void) const

std::string	SyntaxCheck (void)

std::string	Evaluate (LuaState *pL=NULL)

void	Install (LuaState *pL=NULL) const

void	Install (lua_State *pLL) const

Public Member Functions inherited from faudes::FunctionDefinition
	FunctionDefinition (const std::string &name="")

	FunctionDefinition (const FunctionDefinition &rSrc)

virtual	~FunctionDefinition ()

virtual void	ClearVariants (void)

const Function *	Prototype (void) const

Function *	NewFunction () const

int	VariantsSize (void) const

bool	ExistsVariant (const std::string &varname) const

int	VariantIndex (const std::string &rName) const

const Signature &	Variant (const std::string &rName) const

const Signature &	Variant (int n) const

virtual void	AppendVariant (const Signature &pVar)

Public Member Functions inherited from faudes::Documentation
	Documentation (void)

	Documentation (const Documentation &rOther)

virtual	~Documentation (void)

const std::string &	Name (void) const

const std::string &	PlugIn (void) const

const std::string &	CType (void) const

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

int	KeywordsSize (void) const

std::string	KeywordAt (int pos) const

bool	AutoRegistered (void) const

bool	ApplicationRegistered (void) const

virtual void	MergeDocumentation (TokenReader &rTr)

Type &	operator= (const Type &rSrc)

Type &	operator= (Type &&rSrc)

bool	operator== (const Type &rOther) const

bool	operator!= (const Type &rOther) const

Public Member Functions inherited from faudes::Type
	Type (void)

	Type (const Type &rType)

virtual	~Type (void)

virtual Type *	New (void) const

virtual Type *	NewCpy (void) const

virtual const Type *	Cast (const Type *pOther) const

virtual bool	IsDefault (void) const

virtual Type &	Copy (const Type &rSrc)

virtual Type &	Move (Type &rSrc)

Type &	operator= (const Type &rSrc)

Type &	operator= (Type &&rSrc)

virtual bool	Equal (const Type &rOther) const

bool	operator== (const Type &rOther) const

bool	operator!= (const Type &rOther) const

virtual const std::string &	TypeName (void) const

void	Write (const Type *pContext=0) const

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

void	Write (const std::string &pFileName, std::ios::openmode openmode) const

void	Write (TokenWriter &rTw, const std::string &rLabel="", const Type *pContext=0) const

virtual void	XWrite (const std::string &pFileName, const std::string &rLabel="", const Type *pContext=0) const

void	XWrite (const Type *pContext=0) const

void	XWrite (TokenWriter &rTw, const std::string &rLabel="", const Type *pContext=0) const

std::string	ToString (const std::string &rLabel="", const Type *pContext=0) const

std::string	ToText (const std::string &rLabel="", const Type *pContext=0) const

void	DWrite (const Type *pContext=0) const

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

void	DWrite (TokenWriter &rTw, const std::string &rLabel="", const Type *pContext=0) const

void	SWrite (TokenWriter &rTw) const

void	SWrite (void) const

std::string	ToSText (void) const

void	Read (const std::string &rFileName, const std::string &rLabel="", const Type *pContext=0)

void	FromString (const std::string &rString, const std::string &rLabel="", const Type *pContext=0)

void	Read (TokenReader &rTr, const std::string &rLabel="", const Type *pContext=0)

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="")

template<class T >
static FunctionDefinition *	FromFile (const std::string &rFileName)

Protected Member Functions
virtual void	DoCopy (const LuaFunctionDefinition &rSrc)

virtual bool	DoEqual (const LuaFunctionDefinition &rOther) const

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

virtual void	DoReadCore (TokenReader &rTr)

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

virtual void	DoWriteCore (TokenWriter &rTw) const

virtual void	Prototype (Function *pFunc)

Protected Member Functions inherited from faudes::FunctionDefinition
void	DoCopy (const FunctionDefinition &rSrc)

bool	DoEqual (const FunctionDefinition &rOther) const

Protected Member Functions inherited from faudes::Documentation
void	Name (const std::string &name)

void	PlugIn (const std::string &plugin)

void	CType (const std::string &name)

void	TextDoc (const std::string &textdoc)

void	AutoRegistered (bool flag)

void	ApplicationRegistered (bool flag)

void	HtmlDoc (const std::string &fname)

void	AddKeyword (const std::string &rKeyword)

void	DoCopy (const Documentation &rSrc)

bool	DoEqual (const Documentation &rOther) const

Protected Member Functions inherited from faudes::Type
void	DoCopy (const Type &rSrc)

void	DoMove (Type &rSrc)

bool	DoEqual (const Type &rOther) const

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

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

virtual void	DoSWrite (TokenWriter &rTw) const

virtual const TypeDefinition *	TypeDefinitionp (void) const

virtual Token	XBeginTag (const std::string &rLabel="", const std::string &rFallbackLabel="") const

Protected Attributes
LuaFunction *	pLuaFunction

std::string	mLuaCode

std::string	mLuaFile

LuaState *	pDefaultL

Protected Attributes inherited from faudes::FunctionDefinition
Function *	mpFunction

std::vector< faudes::Signature >	mVariants

std::map< std::string, int >	mVariantIndexMap

Protected Attributes inherited from faudes::Documentation
std::string	mName

std::string	mPlugIn

std::string	mCType

std::string	mTextDoc

std::string	mHtmlDoc

std::string	mKeywords

bool	mAutoRegistered

bool	mApplicationRegistered

Additional Inherited Members
Static Protected Attributes inherited from faudes::Documentation
static const char	mDelim = ';'

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

◆ LuaFunctionDefinition() [2/2]

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

Copy constructor

Definition at line 192 of file lbp_function.cpp.

◆ ~LuaFunctionDefinition()

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

inlinevirtual

Destructor

Definition at line 168 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 227 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 261 of file lbp_function.cpp.

◆ DefaultL() [2/2]

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

Get default lua state.

Returns: Lua state

Definition at line 255 of file lbp_function.cpp.

◆ DoCopy()

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

protectedvirtual

Std faudes type interface: assignment.

Parameters

rSrc	Source to copy from

Definition at line 201 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 217 of file lbp_function.cpp.

◆ DoRead()

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.

Definition at line 534 of file lbp_function.cpp.

◆ DoReadCore()

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.

Definition at line 573 of file lbp_function.cpp.

◆ DoWrite()

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.

Definition at line 598 of file lbp_function.cpp.

◆ DoWriteCore()

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.

Definition at line 607 of file lbp_function.cpp.

◆ 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 304 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 327 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 321 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 250 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 245 of file lbp_function.cpp.

◆ Prototype()

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

protectedvirtual

Copy prototype object

Parameters

pFunc Function instance

Reimplemented from faudes::FunctionDefinition.

Definition at line 237 of file lbp_function.cpp.

◆ Register()

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

static

Definition at line 549 of file lbp_function.cpp.

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

Member Data Documentation

◆ mLuaCode

std::string faudes::LuaFunctionDefinition::mLuaCode

protected

Lua code

Definition at line 391 of file lbp_function.h.

◆ mLuaFile

std::string faudes::LuaFunctionDefinition::mLuaFile

protected

Lua file

Definition at line 394 of file lbp_function.h.

◆ pDefaultL

LuaState* faudes::LuaFunctionDefinition::pDefaultL

protected

Default lua state

Definition at line 397 of file lbp_function.h.

◆ pLuaFunction

LuaFunction* faudes::LuaFunctionDefinition::pLuaFunction

protected

Typed prototype instance

Definition at line 388 of file lbp_function.h.

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

Detailed Description

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Constructor & Destructor Documentation

◆ LuaFunctionDefinition() [1/2]

◆ LuaFunctionDefinition() [2/2]

◆ ~LuaFunctionDefinition()

Member Function Documentation

◆ Clear()

◆ DefaultL() [1/2]

◆ DefaultL() [2/2]

◆ DoCopy()

◆ DoEqual()

◆ DoRead()

◆ DoReadCore()

◆ DoWrite()

◆ DoWriteCore()

◆ Evaluate()

◆ Install() [1/2]

◆ Install() [2/2]

◆ LuaCode() [1/2]

◆ LuaCode() [2/2]

◆ Prototype()

◆ Register()

◆ SyntaxCheck()

Member Data Documentation

◆ mLuaCode

◆ mLuaFile

◆ pDefaultL

◆ pLuaFunction