luafaudes

Tutorials

luafaudes Overview

luafaudes is a scripting environment to utilise libFAUDES without the hassle of developing a C++ application. It provides access to user relevant data-types and algorithms of libFAUDES within the scripting language Lua. Lua itself is easy to use and there are many tutorials to be found in the web, e.g. http://lua-users.org/wiki/TutorialDirectory.

Technically, the integration of libFAUDES within Lua is implemented in the luabindings plug-in. Whilst data-types are adopted by tailored interface definitions, most functions are directly derived from the libFAUDES run-time interface. Thus, the libFAUDES user-reference serves as a reference documentation for luafaudes functions.

The remainder of this page gives directions for first steps with luafaudes.

Installation

The current implementation of luafaudes is part of the libFAUDES package.

  • To use the Linux precompiled binary that comes with the libFAUDES package, open a command shell to un-tar the package and set the PATH variable accordingly:

    $ tar -xvzf libfaudes-current.tar.gz
    $ export PATH=$PATH:$(pwd)/libfaudes-current/bin
    $ luafaudes
    

    In the case you observe error messages about missing libraries, or if you prefer to run luafaudes with advanced readline support (command history, etc) you need to re-compile; see the Build-System Documentation.

  • To use the MS Windows installers, download and double-click/execute the installer. Then open a command shell to set the PATH variable accordingly:

    C:> set PATH %PATH%;c:\FAUDES\libFAUDES
    C:> luafaudes
    

    There is no advanced readline support for the MS Windows version of luafaudes. Rather than to use luafaudes interactively, we recommend you edit scripts with e.g. Ms NotePad and run them from the command-line

  • To (re-)compile luafaudes for POSIX compliant platforms e.g. Mac OsX, follow the instructions for the libFAUDES build-system. This will create the binary luafaudes.

On startup, luafaudes shows the welcome screen and the command prompt

Welcome to luafaudes console.
Versions: libFAUDES 2.12a / example-observer-timed-simulator-iodevice-luabindings / Lua 5.1
Credits: This libFAUDES interpreter is based on the projects Lua and SWIG.
Type 'faudes.Help()' for a list of faudes related types and functions.

>

To test the installation, run an example script from the luabindings tutorial:

$ cd ./libfaudes/plugins/luabindings/tutorial
$ ls *.lua
1_containers.lua 2_generators.lua 3_regular.lua
$ luafaudes 3_regular.lua

By convention, the provided example scripts read input data from the data subdirectory, relative to the location of the script. Thus, it is mandatory to cd to the location of the script.

For image output of generator graphs, luafaudes relies on the the tool dot from the Graphviz package. For most Linux distributions, dot can be installed by the package manager or is included anyway. For Mac OsX and Windows, installers are available from the Graphviz site. For all systems, the location of the binary dot must either be in the PATH variable or specified within luafaudes as follows:

Welcome to luafaudes console 
[...]
>
faudes.DotExecPath("/usr/bin/dot")                                      -- eg Linux  
faudes.DotExecPath("c:\\Programs\Graphviz\dot")                         -- eg Windows
faudes.DotExecPath("/Applications/Graphviz.app/Contents/MacOS/dot");    -- eg MacOS
>
gen=faudes.Generator("data/simplemachine.gen")                          -- read some generator
gen:GraphWrite("tmp_simplemachine.jpg");                                -- write to image file

Usage

When no command-line arguments are supplied, luafaudes runs interactively. At the command prompt ">", the interpreter accepts any valid Lua language input, e.g.

> for i=1,3 do print(i) end
1
2
3
> 

libFAUDES related extensions are located in the namespace faudes. I.e. libFAUDES data-types and functions are addressed with the prefix faudes.. The faudes.Help() function provides some overview on available libFAUDES related commands:

Luafaudes extends the Lua scripting language to execute libFAUDES functions. 
For detailed information on algorithms and data structures, please consult
the libFAUDES doxygen documentation.

All faudes bindings are in the Lua module 'faudes', ie access is via 'faudes.*'.
You may copy faudes bindings to the global name space by 'faudes.MakeGlobal()'.

libFAUDES Bindings:

  faudes.Help("EventSet")            EventSet methods
  faudes.Help("Generator")           Generator methods
  faudes.Help("System")              System methods
  faudes.Help("StateSet")            StateSet methods
  faudes.Help("TransSet")            TransSet methods
  faudes.Help("Example")             Example plug-in function

libFAUDES Configuration:

  faudes.StatenamesOn()              enable automatic state names
  faudes.StatenamesOff()             disable automatic state names
  faudes.DotExecPath("filename")     path of dot executable
  faudes.Version()                   report libFAUDES version string

luafaudes Console Commands:

  faudes.InitLog("filename")         init logging of commands
  faudes.CloseLog()                  stop logging of commands
  Ctrl-C                             exit luafaudes interpreter

> 

You may specify a keyword by calling faudes.Help("keyword") to obtain a list of relevant functions. Plug-ins that provide additional luabindings will advertise themselves with their plug-in name as keyword.

luafaudes has a built-in command logging facility. You can initialize command logging by calling the faudes.InitLog("filename") command to record all subsequent commands to the log file filename, until faudes.CloseLog() is called or the interpreter is terminated. The log-file can then later be executed as a Lua script by

$ ./luafaudes <filename>

The EventSet Data Type

luafaudes maps most libFAUDES C++ classes to Lua user-data pointers with corresponding access functions. The class faudes::EventSet is used as the class to represent sets of events within Lua and you can create a variable of that type by using the default constructor:

> alph1 = faudes.EventSet()

Note: A consequence of mapping to Lua user-data pointers is that an assignment within Lua does *not* create a copy of the object, but only passes on the reference. In order to create a copy of a libFAUDES object, you need to explicitly invoke the copy constructor or the copy method. In the following code, alph2 and alph3 are copies of alph1, while alph4 refers to the same object as alph1.

> alph2 = alph1:Copy()                   -- construct a copy of alph1
> alph2 = faudes.EventSet(alph1)         -- construct a copy of alph1
> alph3 = alph1                          -- have another reference to alph1

The available methods for EventSet objects are shown by the faudes.Help("EventSet") command. The first column shows the return type, the second the method name and arguments.

Luafaudes help topic: "EventSet" [extract]

                 *** Constructors ***
            EventSet EventSet()
            EventSet EventSet(EventSet)
                    
                 *** Maintenance ***
              string Name()
                     Name(string)
                 int Size()
                     Lock()
                     Detach()
                 int Index(string)
              string SymbolicName(int)
                    
                 *** Element access ***
                bool Empty()
                bool Insert(string)
                bool Erase(string)
                bool Exists(string)
                    
                 *** Set operations ***
                     InsertSet(EventSet)
                     EraseSet(EventSet)
            EventSet SetIntersection(EventSet)
            EventSet SetUnion(EventSet)
                    

All(most all) methods directly correspond to their C++ counterpart. To call a method for an EventSet, the method name is appended to the object by a colon :

> alph1:Insert("alpha")
> alph1:Insert("beta")
> alph1:Insert("gamma")

The integration with the native Lua commands (see Lua documentation) is seamless. E.g. the Lua print(..) statement can be used to print the integer index of an individual event or the tokenized version of an event set to the screen:

> print(alph1:Index("beta"))
2
> print(alph1)
<NameSet> "alpha" "beta" "gamma" </NameSet> 

The tutorial section of the luabindings plug-in provides a tutorial on containers to demonstrate basic access to events sets, state sets and transition relations.

The Generator Data Type

The libFAUDES class faudes::vGenerators is used to represent generators within Lua. A Generator object is created by the statement

> gen1 = faudes.Generator()

The available methods for Generator objects are shown by the faudes.Help("Generator") command. The first column shows the return type, the second the method name:

Luafaudes help topic: "Generator" [extract]
    
                 *** Constructors ***
           Generator Generator()
           Generator Generator(gen)
           Generator Generator(filename)
                    
                 *** Maintenance ***
                     Name(string)
              string Name()
                bool IsDeterministic()
                                        
                 *** Alphabet ***
            EventSet Alphabet()
                bool InsEvent(name)
                bool DelEvent(name)
                bool ExistsEvent(name)
                    
                 *** State set ***
            StateSet States()
                 idx InsState(name)
                bool DelState(name)
                bool ExistsState(name)
                     SetInitState(name)
                     ClrInitState(idx)
                     SetMarkedState(name)
                     ClrMarkedState(idx)
                    
                 *** Transitions ***
            TransSet TransRel()
                bool SetTransition(trans)
                bool SetTransition(x1,ev,x2)
                bool SetTransition(x1name,evname,x2name)
                     ClrTransition(trans)
                     ClrTransition(x1,ev,x2)

As with the EventSet, a method for a Generator object is called by appending the method to the object with a colon:

> gen1:InsEvent("alpha")
> gen1:InsEvent("beta")
> gen1:InsEvent("gamma")
> gen1:InsState("waiting")
> gen1:InsState("working")
> gen1:InsState("dump state")
> gen1:SetInitState("waiting")
> gen1:SetMarkedState("waiting")
> gen1:SetTransition("waiting", "alpha", "working")
> gen1:SetTransition("working", "beta", "waiting")

...

The tutorial section of the luabindings plug-in provides a tutorial on generators to demonstrate access to generator class members.

Note: luafaudes does not implement a concept of read-only variables, aka const. As a consequence, any access to a container member within a generator returns a writable reference. You should *not* use this reference to alter the container's content.

> gen = faudes.Generator("some_file.gen")
> alph = gen:Alphabet()                   -- get a reference to generator's alphabet
> alph:Clear()                            -- dont do this
> alph = gen:Alphabet():Copy()            -- get a copy of generator's alphabet
> alph:Clear()                            -- ok, wont mess up the generator

Calling libFAUDES Algorithms

Most algorithms implemented in libFAUDES are also available in luafaudes. To get a list of the available algorithms from the libFAUDES core, type faudes.Help("Functions"):

Luafaudes help topic: "Functions" [extract]

                 *** Regular expressions ***
                bool LanguageEquality(gen1_arg, gen2_arg)
                bool LanguageIncludion(gen1_arg, gen2_arg)
                bool LanguageDisjoint(gen1_arg, gen2_arg)
                     LanguageComplement(gen)
                     LanguageConcatenate(gen1_arg, gen2_arg, gen_res)
                     LanguageConcatenateNonDet(gen1_arg, gen2_arg, gen_res)
                     LanguageUnion(gen1_arg, gen2_arg, gen_res)
                     LanguageIntersection(gen1_arg, gen2_arg, gen_res)
                     FullLanguage(alph_arg, gen_res)
                     AlphabetLanguage(alph_arg, gen_res)
                     KleeneClosure(gen)
                     KleeneClosureNonDet(gen)

                 *** Reachability ***
                     Accessible(gen)
                bool IsAccessible(gen_arg)
                     CoAccessible(gen)
                bool IsCoAccessible(gen_arg)
                     Trim(gen)
                bool IsTrim(gen_arg)

                 *** Misc ***
                bool IsDeterministic(gen_arg)
                     Deterministic(gen_arg, gen_res)
                     StateMin(gen_arg, gen_res
                     Project(gen, alph)
                     InvProject(gen, alph)
                     PrefixClosure(gen)

The tutorial section of the luabindings plug-in provides a tutorial on regular expressions, to demonstrate access to libFAUDES functions.

More Documentation

Regarding functions, libFAUDES luabindings (are meant to) match the libFAUDES user-reference. The latter is auto generated from the libFAUDES run-time interface and is intended to provide documentation relevant to the user of libFAUDES applications.

For more detailed information on libFAUDES classes and functions, we refer to the libFAUDES C++ API Documentation, which is directly generated from the libFAUDES source code. It primarily addresses application and library developers.

Documentation of the Lua programming language can be found on the Lua documentation site.

libFAUDES 2.14g --- 2009-12-3 --- plugins "example synthesis observer diagnosis hiosys multitasking timed simulator iodevice luabindings"