| |
luafaudes is a scripting environment to utilize 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-refernce serves as a reference documentation for luafaudes functions.
The remainder of this page gives directions for first steps with luafaudes. For further readings, you may inspect the example scripts provided in the luabindings tutorial:
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 commad 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 runtime 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 wellcome 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 containers.lua generators.lua regular.lua synthesis.lua $ luafaudes synthesis.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.
When no commandline 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("StateSet") StateSet methods faudes.Help("TransSet") TransSet methods faudes.Help("Example") Example plugin 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. Plugins that provide additional luabindings will advertise themselfs with their plugin 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>
luafaudes maps most libFAUDES C++ classes to Lua user-data pointers with corresponding access functions. The cEventSet class 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()
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 explicitely invoke the copy constructor. In the following code, alph2 is a copy of alph1, while alph3 refers to the same object as alph1.
> alph2 = faudes.EventSet(alph1) > alph3 = 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) *** Controllablity attributes *** AttributeCFlag Attribute(string)
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 libFAUDES class cGenerators 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.
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) *** Synthesis *** Parallel(gen1_arg, gen2_arg, gen_res) SelfLoop(gen, alph_arg) SupCon(plant, spec, super) SupConNB(plant, spec, super) bool IsControllable(plant, super) *** 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, and a tutorial on basic controller synthesis demonstrate access to libFAUDES functions.
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 primaly addresses application and libraray developers.
Documentation of the Lua programming language can be found on the Lua documentation site.