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 
182 
183 #ifndef FAUDES_LIBLUAFAUDES_H
184 #define FAUDES_LIBLUAFAUDES_H
185 
186 
187 // lua essentials
188 #define lua_c
189 
190 
191 // lua essentials
192 extern "C" {
193 #include "lua/lua.h"
194 #include "lua/lauxlib.h"
195 #include "lua/lualib.h"
196 }
197 
198 
199 // std streams for console logging
200 #include <iostream>
201 #include <fstream>
202 #include <sstream>
203 #include <string>
204 
205 // c libs since we dont use lua.h
206 #include <csignal>
207 #include <cstdio>
208 #include <cstdlib>
209 #include <cstring>
210 
211 // luafaudes: include faudes plus lua addons
212 #include "corefaudes.h"
213 #include "lbp_function.h"
214 
215 // include declarations for SWIG generated module loaders
216 #include "lbp_load.h"
217 
218 // overall loader to initialize kernel
219 extern FAUDES_API void luafaudes_initialize(lua_State* pL);
220 
221 // luafaudes: logging externals, defined in commonfaudes.i
222 extern FAUDES_API std::ofstream* luafaudes_logstream;
223 extern FAUDES_API std::string luafaudes_lastline;
224 extern FAUDES_API void luafaudes_initlog(const std::string& filename, const std::string& mode="w");
225 extern FAUDES_API void luafaudes_closelog(void);
226 extern FAUDES_API void luafaudes_logwrite(const char* str);
227 extern FAUDES_API void luafaudes_logwrite(const std::string& str);
228 
229 // luafaudes: register faudes console variant for print, see commonfaudes.i
230 extern FAUDES_API void luafaudes_print_register(lua_State* L);
231 
232 // luafaudes: mute faudes console out, see commonfaudes.i
233 extern FAUDES_API void luafaudes_mute(bool on);
234 
235 // luafaudes: register faudes LoopCallback() as line hook, see commonfaudes.i
236 extern FAUDES_API void luafaudes_hook_register(lua_State* L);
237 
238 // luafaudes: help system, see commonfaudes.i
239 extern FAUDES_API void luafaudes_dict_insert_topic(const std::string& topic, const std::string& text);
240 extern FAUDES_API void luafaudes_dict_insert_entry(const std::string& topic, const std::string& key, const std::string& entry);
241 
242 // luafaudes: load extension, see commonfaudes.i
243 extern int FAUDES_API luafaudes_loadext(lua_State* pL, const char* filename);
244 extern int FAUDES_API luafaudes_loaddefext(lua_State* pL, const char* arg0);
245 
246 // luafaudes interface to completer, see commonfaudes.i
247 extern FAUDES_API char **luafaudes_complete(lua_State* pL, const char *text, int start, int end);
248 
249 
250 // luafaudes: dot test external, see commonfaudes.i
251 extern bool luafaudes_dotready(void);
252 
253 
254 
255 // luafaudes debugging facilities
256 #ifdef FAUDES_DEBUG_LUABINDINGS
257 #define FD_DLB(message) FAUDES_WRITE_CONSOLE("FAUDES_LUA_ERROR: " << message);
258 #else
259 #define FD_DLB(message)
260 #endif
261 
262 
263 
264 #endif

libFAUDES 2.28c --- 2016.09.30 --- c++ api documentaion by doxygen