luafaudes
Tutorials
|
LuaExtensionsLuaExtensions 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 ExtensionsLuaExtensions 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 luafaudesThe 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 LuaExtensionThe 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:
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.20s --- 2011.10.12 --- with "synthesis-observer-observability-diagnosis-hiosys-iosystem-multitasking-coordinationcontrol-timed-simulator-iodevice-luabindings"