About
User Reference
C++ API
luafaudes
Developer
Links
libFAUDES online
luafaudes

Tutorials

LuaExtensions

LuaExtensions provide a light-weight mechanism to extend libFAUDES by functions implemented as luafaudes scripts.

As with C++ plug-ins, LuaExtensions are transparently passed on to any application that interfaces to libFAUDES via the run-time-interface, e.g., luafaudes or DESTool. Extension developers can advertise their functions by end-user documentation that seamlessly integrates with the libFAUDES reference.

LuaExtensions are distributed as single container files (*.flx) for the luafaudes function definition, reference pages, and validation code. In contrast to C++ plug-ins, no further development tools (compilers, etc.) are required.

Installing and Removing Extensions

LuaExtensions are installed or removed from a libFAUDES distribution with the commandline tool flxinstall. Installation and removal is allways en-block, i.e., there is no support to install or remove individual extensions. It is therefore recommended that you organize your extensions (*.flx-files) to reside in a separate directory. Example extensions are located in libfaudes/plugins/luabindings/extensions.

Example:

To install the provided example extensions from the tutorial (currently only extintro.flx), run

> cd ./libfaudes
> ./bin/flxinstall -i /plugins/luabindings/extensions/*.flx ./

The last command-line parameter specifies the target directory, i.e., the directory in which the libFAUDES distribution resides. To remove any previously installed extensions, run

> cd ./libfaudes
> ./bin/flxinstall -r ./

You may inspect the reference documentation (./libfaudes/doc/index.html) to verify the installation/removal.

Accessing Extensions from luafaudes

The installation process assembles the file luafaudes.flx and places it next to luafaudes in ./libfaudes/bin. On startup, luafaudes will automatically load the extension file when present. Extensions typically are set up to produce some diagnostic output. This can be observed with the command-line option -d.

In order to load alternative extension files (e.g. for testing/debugging) you may run luafaudes with the command-line option -x file.flx, e.g.

> cd ./libfaudes
> ./bin/luafaudes -d -x extension_file.flx

From the Lua-promt, faudes.Help() will list all reference sections, including those introduced by LuaExtensions. Thus, for the example extention, faudes.Help("ExtIntro") should list the two functions provided by extintro.flx. Functions provided by extensions can be invoked like any other faudes function.

Example LuaExtension

The below example is meant to illustrate and document the .flx-file format. The example comes in two versions, namely the full version extintro.flx (including documentation, tutorial, etc) and a minimal version extintro_minimal_flx. Both files are located in libfaudes/plugins/luafaudes/extensions. They have been packaged by the tool flxinstall; see also below.

LuaExtension files are XML compliant and have the outer tag LuaExtension. As a mandatory attribute, LuaExtension must provide a unique name, ExtIntro for this example. The LuaExtension element must be composed from Lua-function definitions, using tags LuaFunctionDefinition. The latter again must provide a name attribute, where the value must be prefixed with the name of the extension.

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE LuaExtension SYSTEM "http://www.faudes.org/dtd/1.0/luaextension.dtd">

<LuaExtension name="ExtIntro">

<LuaFunctionDefinition name="ExtIntro::LargeGenerator">
[...]
<LuaFunctionDefinition>

<LuaFunctionDefinition name="ExtIntro::IsLargeGenerator">
[...]
<LuaFunctionDefinition>

[... more functions, reference documentation, images, tutorials ...]

</LuaExtension>

Optionally, an extension may provide reference documentation, embedded image files, tutorials and a protocol for validation. The respective sections are illustrated below.

Rather than to set up a LuaExtension by hand, it is recommended to maintain the indivdual components in separate files and to use the commandline tool flxinstall for packaging. The example extension extintro.flx was composed by

> cd libfaudes/
> ./bin/flxinstall -c plugins/luafaudes/extensions/extintro ./extintro.flx

The tool accepts source files with suffix .rti, .fref, .png or .lua for lua-function definitions, reference pages, tutorials, or images, respectively. If you specify a source directory, flxinstall consideres every file in that directory as a source file (however, no recursive search is performed). If you don't specify a source at all, the current directory is used as a source. The last parameter always specifies the destination .flx-file.

To inspect the contents of an extension file without installing it to libFAUDES, flxinstall can extract its components to any destination directory:

> cd libfaudes/
> ./bin/flxinstall -x plugins/luafaudes/extensions/extintro.flx /tmp/where-ever

Note: The current version of flxinstall maps all filenames to lower case. Thus, when a reference page embedds an image file or when a turorial reads input data, filenames must be specified in lower case. Furthermore, flxinstall is not expected work with non-ASCII filenames. Thus, at the current stage, you are best of in restricting filenames to lower-case ASCII.

Luafaudes functions

LuaFunctionDefinitions must comply with the restrictions and conventions as specified in the C++ API documentation of the luabindings plug-in.

Any documenation URL referenced by a function definition must be provided by the extension. For the example, the extension must provide a reference page extintro_largegenerator.fref, which on installation compiles to the HTML page extintro_largegenerator.html. If an extension does not provide any reference documentation, the install tool flxinstall will automatically generate an index page; here extintro_index.html. In this case, you should refer to extintro_index.html#function_name in the function definition.

<LuaFunctionDefinition name="ExtIntro::LargeGenerator">
<Documentation ref="extintro_largegenerator.html#LargeGenerator"> 
Construct a generator by random.
</Documentation>
<Keywords> "ExtIntro" "large generators" "first 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>

% embedded script
<LuaCode> 
<![CDATA[

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

-- Function reports on execution
faudes.Print(string.format('LargeGenerator(...): qn=%d sn=%d',qn,sn))

-- Declare local variables
local tn,tmax,x1,x2,ev,i

-- Clear result
gen:Clear()
 
-- Set events
for i=1,sn do 
  gen:InsEvent(string.format('e%d',i))
end

-- Set states
for i=1,qn do
  gen:InsState(string.format('s%d',i))
end

-- Set transitions
tn=qn*3
tmax=qn*qn
while tn>0 and tmax>0 do
 x1=math.random(1,qn)
 x2=math.random(1,qn)
 ev=math.random(1,sn)
 x1=string.format('s%d',x1)
 x2=string.format('s%d',x2)
 ev=string.format('e%d',ev)
 if not gen:ExistsTransition(x1,ev,x2) then
   gen:SetTransition(x1,ev,x2)
   tn=tn-1
 end
 tmax=tmax-1
end

-- End of function definition
end

]]>
</LuaCode>

</LuaFunctionDefinition>

Reference pages

Reference pages are formated as the reference pages from the run-time-interface, see also the build system. In the context of LuaExtensions, the following conventions apply:

  • the chapter must be set to Reference, i.e. chapter="Reference";

  • the section must match the extension name, here section="ExtIntro";

  • there must be exacly on page with label Index, i.e. page="Index";

When processing the LuaExtension, each reference page is extracted to an HTML page. The filename of the page is composed by appending the page label to the extension, seperated by an underscore _, extended by the suffix .html, and all mapped to lower case. In our example, the two pages are named extintro_index.html and extintro_largegenerator.html. This convention is relevant when referring to the documentation of a function.

<ReferencePage chapter="Reference" section="ExtIntro" page="Index" title="LuaExtensions - Introduction">
<h1> LuaExtensions - Introduction </h1>
<p>
LuaExtensions provide a light-weight mechanism to extend libFAUDES
by functions implemented as luafaudes scripts. 
</p>

[...]

<p>
We give some references to Lua related literature.
</p>

<fliterature name="L1">
<fauthors>R. Ierusalimschy, L.H .de Figueiredo, W. Celes</fauthors>
<ftitle>Lua 5.1 Reference Manual</ftitle>
<fjournal><a href="http://www.lua.org">Lua.org</a>, ISBN 85-903798-3-3</fjournal>
<fyear>2006</fyear>
</fliterature>

</ReferencePage>

For literatur references, as in the above example, care must be taken to avoid conflicts. The extension name as a prefix is better idea than just a single letter.

<ReferencePage chapter="Reference" section="ExtIntro" page="LargeGenerator" title="LuaExtension - Large Generators">
<h1>
LuaExtension - Large Generators
</h1>

<ffnct_reference name="LargeGenerator">
<fdetails/>
<p>
The function <ffnct>LargeGenerator</ffnct> sets up a generator by random,
where the number of states and the number of events are specified as parameters.
This function is expected to be completely useles, except for demonstration
purposes.
</p>

<fexample/>

<p>
Result for <fimath>qn=12</fimath> and <fimath>sn=5</fimath>
<br/>
<img  fsrc="FAUDES_IMAGES/extintro_lg.png" alt="large generator" width="600px"/>
</p>

<fconditions/>

<p>
There are no conditions on the parameters. The resulting generator
may be non-deterministic.
</p>

</ffnct_reference>

[...]

</ReferencePage>

Image Files

Any images used for the reference pages must be embedded in the extension file. During processing, embedded files get extracted to the faudes_images directory with file-name as specified by the name attribute and mapped to lower case. The actual content is Base64 encoded binary data with two extra "=", one at the beginning and one at the end.

<ImageFile name="extintro_lg.png"> 
=iVBORw0KGgoAAAANSUhEUgAABIsAAANpCAYAAACLpLlpAAAABmJLR0QA/wD/AP+gvaeTAAAgAElE
QVR4nOzdeVTV1eL+8YdJBBERRUARUQFRxCxnzQnnOdFMyzRtVWq/tDmvDdeuaTbcBi2Hsus89DXn
[...]
iWuCijmDXmdARUUQATUQBRnP74++nm/ebFAPfIDzfq11FtM5ez/HlXTO4977Y2MymUwCAAAAAAAA
pGhboxMAAAAAAACg9KAsAgAAAAAAgBllEQAAAAAAAMwoiwAAAAAAAGBGWQQAAAAAAAAzyiIAAAAA
AACYURYBAAAAAADAjLIIAAAAAAAAZpRFAAAAAAA===
<ImageFile> 

Tutorials

Tutorials can be provided for further illustration and effective advertisement of the extension. Typically, they are also used to generate the example output for the reference pages.

Tutorials are plain Lua scripts that reside within tags LuaTutorial. For the example extension, we provide the following test scenario.

<LuaTutorial name="extintro_example.lua"> 
<![CDATA[
-- Tutorial to illustrate the LuaExtension "ExtIntro"

-- Read input data
l1gen = faudes.Generator("data/gen_lg.gen")

-- Apply test and report
l1=faudes.IsLargeGenerator(l1gen);
if l1 then
  print("l1gen is a large generator [expected]")
else
  print("l1gen is not a large generator [test case error]")
end

-- Record test case
FAUDES_TEST_DUMP("lgen test 1",l1)

-- Constrcut a small generator
l2gen = faudes.Generator()
faudes.LargeGenerator(5,3,l2gen)

-- Produce graphical output for documentation
l2gen:GraphWrite("tmp_l2gen.png")

-- Apply test and report
l2=faudes.IsLargeGenerator(l2gen);
if l2 then
  print("l2gen is a large generator [test case error]")
else
  print("l2gen is not a large generator [expected]")
end

-- Record test case
FAUDES_TEST_DUMP("lgen test 2",l2)

-- Validate results
FAUDES_TEST_DIFF()
]]>
</LuaTutorial>

By convention, any input data used in a tutorial is read from the directory data relative to the tutorials location. The corresponding files can be packaged with the extension by using the tags DataFile and specifying filename and content (either as Base64 encoded binary or as token stream). When flxinstall -c is used to compose the extension, the source data is interpreted as data directory and any file within that directory is represented as DataFile section.

The above tutorial uses the functions FAUDES_TEST_DUMP(m,d) and FAUDES_TEST_DIFF for elementary validation; see also test cases.

The provided example comes with two files in the data directory: a generator input and the reference protocol for validation.

<DataFile name="gen_lg.gen">
=PEdlbmVyYXRvcj [...] KCiJsYXJnZSBn=== 
</DataFile>
<DataFile name="extintro_example_lua.prot"> 
=JSUlIHRlc3QgbW [...] SAKJSAKJSAKCg=== 
</DataFile>

libFAUDES 2.20d --- 2011.04.26 --- with "synthesis-observer-observability-diagnosis-hiosys-iosystem-multitasking-timed-simulator-iodevice-luabindings"