luafaudes Overview

luafaudes is a scripting environment based on the Lua interpreter to access libFAUDES data-types and functions. For demonstration purposes, the interactive luafaudes-console can be executed in a browser window, allthough we recommend the installation of native executables; see below for further instructions.

Technically, the integration of libFAUDES within Lua is implemented in the luabindings plug-in. Whilst data-types are adopted by tailored interface definitions, libFAUDES functions are automatically bound via the run-time interface. Thus, the libFAUDES user-reference also applies to luafaudes functions.

The remainder of this page gives directions for first steps with luafaudes. There is an extra page for more technical details regarding the intergation of libFAUDES with Lua, addressing a number of potential pitfalls.

Usage

Natively, luafaudes is invoked from the command line (also known as shell or terminal window) provided by the operating system; see also installation instructions. When no arguments are specified, luafaudes shows a welcome message at start-up and accepts any valid Lua statement or any valid Lua expresssion at the prompt, e.g.

$ ./luafaudes
Welcome to luafaudes console 
[...]
> for i=1,3 do print(i) end
1
2
3
> 

There are many tutorials on the Lua language available from the web, e.g. http://lua-users.org/wiki/TutorialDirectory. luafaudes extends Lua to execute libFAUDES functions. Technically, the extensions are installed to the namespace faudes, i.e. functions related to libFAUDES are addressed with the prefix faudes.. The faudes.Help() function provides some overview on libFAUDES related features:


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("IndexSet")            IndexSet methods
  faudes.Help("TransSet")            TransSet methods
  faudes.Help("Synthesis")           Synthesis PlugIn

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.Print("message")            print as faudes debugging message
  faudes.Error("message")            abort script with error message
  faudes.Mute(bool)                  mute faudes debugging messages
  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.

The EventSet Data Type

luafaudes maps most libFAUDES C++ classes to Lua user-data pointers with corresponding access functions. The C++ 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, within Lua, the assignment operator = 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.

> alph2 = alph1:Copy()                   -- construct a copy of alph1
> alph3 = faudes.EventSet(alph1)         -- construct a copy of alph1
> alph4 = 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> 

Note: Lua automatically converts numbers to strings and vice versa, which can be quite handy. However, if you wanted to insert an event with name 2 by passing a string constant "2" to the Insert method, this may get confused with the event index 2. Thus, it is best *not* to use names that start with a digit.

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 ***
            IndexSet 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.

Calling libFAUDES Functions

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.

For more detailed information on how libFAUDES functions can be accessed from the Lua interpreter, see details on functions.

Installation

The interpreter luafaudes is part of the libFAUDES package, with precompiled versions available for Linux and Windows operating systems. Alternatively, the console window of the libFAUDES GUI DESTool can be used to run Lua scripts. DESTool is distributed as a developper preview, with binaries available for Linux, Mac OS and Windows.

  • 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 provided libfaudes-setup.exe. 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 a welcome message and the command prompt

Welcome to luafaudes console.
Versions: libFAUDES 2.18a / synthesis-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 MS 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 generator
gen:GraphWrite("tmp_simplemachine.jpg");                             -- write image 

libFAUDES 2.32b --- 2024.03.01 --- with "synthesis-observer-observability-diagnosis-hiosys-iosystem-multitasking-coordinationcontrol-timed-simulator-iodevice-luabindings-hybrid-example-pybindings"