lbp_include.h
Go to the documentation of this file.
1 
2 /** @file lbp_include.h Includes all luabindings plug-in headers */
3 
4 /*
5  ****************************************************
6  Convenience header file that includes all headers
7  relevant to the luabindings plug-in.
8 
9  (c) Thomas Moor 2008
10  ****************************************************
11  */
12 
13 
14 #ifndef FAUDES_LBP_INCLUDE_H
15 #define FAUDES_LBP_INCLUDE_H
16 
17 #endif
18 
19 
20 
21 /**
22 
23 @defgroup LuabindingsPlugin Lua Bindings PlugIn
24 
25 
26 @ingroup AllPlugins
27 
28 <p>
29 This plug-in generates libFAUDES bindings for the scripting language Lua;
30 see http://www.lua.org.
31 With this plug-in, a Lua interpreter may serve as
32 an interactive user interface to libFAUDES data types and functions.
33 The tutorial section includes a number of example scripts to demonstrate
34 libFAUDES access from Lua.
35 </p>
36 
37 <p>
38 The luabindings plug-in also includes the application luafaudes, a variation of
39 the std Lua interpreter that runs FAUDES extended lua scripts. If your target platform
40 is Linux, you really want to re-compile with LBP_LUAGOAL=linux in the Makefile.plug-in
41 in order to enable advanced readline support (tab key completion, command history etc).
42 </p>
43 
44 @section SecLuabindingsIntro1 Example Script
45 
46 The following script runs a simple synthesis procedure to
47 synthesise a supervisor - sic - for our two simple machines.
48 For examples, see "./plugins/luabindings/tutorial/_*_.lua" and the
49 introduction given on http://www.rt.eei.uni-erlangen.de/FGdes/faudes/luafaudes
50 
51 @code
52 
53 -- read original machine
54 machine = faudes.Generator("data/verysimplemachine.gen")
55 
56 -- prepare two copies
57 machine1 = faudes.Generator();
58 machine2 = faudes.Generator();
59 faudes.Version(machine,"1",machine1);
60 faudes.Version(machine,"2",machine2);
61 
62 -- compose overall plant
63 plant = faudes.Generator();
64 faudes.Parallel(machine1,machine2,plant);
65 
66 -- load specification
67 spec = faudes.Generator("data/buffer12.gen");
68 
69 -- run synthesis
70 super = faudes.Generator();
71 faudes.SupConNB(plant,spec,super);
72 
73 
74 -- report result
75 plant:Write();
76 spec:Write();
77 super:Write();
78 @endcode
79 
80 @section SecLuabindingsIntro2 Extending Luabindings
81 
82 
83 When you use the libFAUDES plug-in mechanism to implement your algorithms,
84 you may find it useful to include your extensions in the Lua based
85 interface. The wrapper code is automatically generated from so called interface
86 definition files using the tool SWIG; see http://www.swig.org.
87 
88 For data types with a tailored user interface, you will need to provide
89 interface definitions directly to define the way a user may interact with
90 variables of the respective type. For functions that are registered with
91 the faudes run-time interface, the interface definitions will be generated
92 by the build system. In both cases, the additional
93 code required to integrate your plug-in into luafaudes is minimal.
94 
95 The below is from the example plug-in and directly defines the interface for the
96 AlternativeAccessible function. For more detailed information,
97 see the <a href="../faudes_algorithm_example.html">Plug-In Example</a>
98 
99 
100 @code
101 // Set SWIG module name
102 // Note: must match libFAUDES plug-in name
103 %module example
104 
105 // Indicate plug-in to rti function definitions
106 #ifndef SwigModule
107 #define SwigModule "SwigExample"
108 #endif
109 
110 // Load std faudes interface
111 %include "faudesmodule.i"
112 
113 // Include rti generated functioninterface
114 #if SwigModule=="SwigExample"
115 %include "../../../include/rtiautoload.i"
116 #endif
117 
118 // Define interface to additional functions
119 void OtherFunction(Generator& rGen, rEventSet& rAlph);
120 bool IsGoodTest(Generator& rGen, rEventSet& rAlph);
121 ...
122 
123 @endcode
124 
125 
126 
127 @section SecLuabindingsIntro3 Build System
128 
129 Since not every libFAUDES based application requires luabindings,
130 the luabindings plug-in does not add code to libFAUDES itself but compiles
131 to a seperate archive named libluafaudes (.a,.so,.dll)
132 
133 The build system organises the compilation of the luabindings plug-in in two stages:
134 - At stage one, SWIG is used to generate the wrapper code. Since the plug-in ships
135  with appropriate wrapper code, this stage only needs to be processed if you want to
136  generate additional bindings for you plug-in. You will need SWIG version 1.3.36 installed on your system; see http://www.swig.org.
137  Use <tt>make luabindings-clean</tt> and <tt>make luabindings-prepare</tt> to re-build the wrapper code.
138  This stage is also processed by the configuration procedure, e.g. <tt>make dist-clean</tt> and <tt>make configure</tt>.
139 - At stage two, the wrapper code and Lua is compiled to the archive
140  <tt>libluafaudes.a</tt>. The plug-in includes the lua sources, no additional software requirements
141  are imposed. This stage is processed by the std build procedure, eg <tt>make clean</tt> and <tt>make</tt>.
142 
143 
144 @section SecLuabindingsIntro4 Advanced Topic: RTI extensions by Lua functions
145 
146 The Lua environment is designed to support both calling C code from a Lua script
147 as well as calling Lua code from a C application. The latter direction is used
148 by faudes::LuaFunction and faudes::LuaFunctionDefinition objects to extend libFAUDES
149 by Lua scripts that register with the libFAUDES run-time interface. Thus, libFAUDES applications
150 that interface to libFAUDES via the RTI can be transparently extended by Lua scripts.
151 
152 
153 @section License
154 
155 The luabindings plug-in is distributed with libFAUDES.
156 All code except Lua sources are provided under terms of the LGPL.
157 
158 
159 Copyright (c) 2008, 2010 Thomas Moor.
160 
161 
162 Lua sources are included for convenience and come under terms of the following MIT License:
163 
164 License for Lua 5.0 and later versions
165 Copyright (c) 1994-2008 Lua.org, PUC-Rio.
166 
167 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
168 
169 The above copyright notice and this permission notice shall be included in all copies or substantial portions ofthe Software.
170 
171 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
172 
173 
174 The luabindings plug-in also provides a variation of
175 the advanced readline support, which is Copyright (C) 2004-2006 Mike Pall,
176 with the same license as Lua. See also the file lbp_completion.cpp
177 
178 
179 
180 */
181 

libFAUDES 2.24g --- 2014.09.15 --- c++ api documentaion by doxygen