lbp_include.h

Go to the documentation of this file.
00001 
00002 /** @file lbp_include.h Includes all luabindings plug-in headers */
00003 
00004 /*
00005  **************************************************** 
00006  Convenience header file that includes all headers
00007  relevant to the luabindings plug-in. 
00008 
00009  (c) Thomas Moor 2008
00010  ****************************************************
00011  */
00012 
00013 
00014 #ifndef FAUDES_LBP_INCLUDE_H
00015 #define FAUDES_LBP_INCLUDE_H
00016 
00017 #endif
00018 
00019 
00020 
00021 /**
00022  
00023 @defgroup LuabindingsPlugin Lua Bindings PlugIn
00024 
00025 
00026 @ingroup AllPlugins
00027 
00028 <p>
00029 This plug-in generates libFAUDES bindings for the scripting language Lua; 
00030 see http://www.lua.org. 
00031 With this plug-in, a Lua interpreter may serve as 
00032 an interactive user interface to libFAUDES data types and functions. 
00033 The tutorial section includes a number of example scripts to demonstrate
00034 libFAUDES access from Lua. 
00035 </p>
00036 
00037 <p>
00038 The luabindings plug-in also includes the application luafaudes, a variation of 
00039 the std Lua interpreter that runs FAUDES extended lua scripts. If your target platform 
00040 is Linux, you really want to re-compile with LBP_LUAGOAL=linux in the Makefile.plug-in 
00041 in order to enable advanced readline support (tab key completion, command history etc).
00042 </p>
00043 
00044 @section SecLuabindingsIntro1 Example Script
00045 
00046 The following script runs a simple synthesis procedure to
00047 synthesise a supervisor - sic - for our two simple machines.
00048 For examples, see "./plugins/luabindings/tutorial/_*_.lua" and the 
00049 introduction given on http://www.rt.eei.uni-erlangen.de/FGdes/faudes/luafaudes 
00050 
00051 @code
00052 
00053 -- read original machine
00054 machine  = faudes.Generator("data/verysimplemachine.gen")
00055 
00056 -- prepare two copies
00057 machine1 = faudes.Generator();
00058 machine2 = faudes.Generator();
00059 faudes.Version(machine,"1",machine1);
00060 faudes.Version(machine,"2",machine2);
00061 
00062 -- compose overall plant
00063 plant = faudes.Generator();
00064 faudes.Parallel(machine1,machine2,plant);
00065 
00066 -- load specification
00067 spec = faudes.Generator("data/buffer12.gen");
00068 
00069 -- run synthesis
00070 super = faudes.Generator();
00071 faudes.SupConNB(plant,spec,super);
00072 
00073 
00074 -- report result
00075 plant:Write();
00076 spec:Write();
00077 super:Write();
00078 @endcode
00079 
00080 @section SecLuabindingsIntro2 Extending Luabindings
00081 
00082 
00083 When you use the libFAUDES plug-in mechanism to implement your algorithms,
00084 you may find it useful to include your extensions in the Lua based 
00085 interface. The wrapper code is automatically generated from so called interface
00086 definition files using the tool SWIG; see http://www.swig.org. 
00087 
00088 For data types with a tailored user interface, you will need to provide
00089 interface definitions directly to define the way a user may interact with
00090 variables of the respective type. For functions that are registered with
00091 the faudes run-time interface, the interface definitions will be generated
00092 by the build system. In both cases, the additional
00093 code required to integrate your plug-in into luafaudes is minimal. 
00094 
00095 The below is from the example plug-in and directly defines the interface for the
00096 AlternativeAccessible function. For more detailed information,
00097 see the <a href="../faudes_algorithm_example.html">Plug-In Example</a>
00098 
00099 
00100 @code
00101 // Set SWIG module name
00102 // Note: must match libFAUDES plug-in name
00103 %module example
00104 
00105 // Indicate plug-in to rti function definitions
00106 #ifndef SwigModule
00107 #define SwigModule "SwigExample"
00108 #endif
00109 
00110 // Load std faudes interface
00111 %include "faudesmodule.i"
00112 
00113 // Include rti generated functioninterface 
00114 #if SwigModule=="SwigExample"
00115 %include "../../../include/rtiautoload.i"
00116 #endif
00117 
00118 // Define interface to additional functions
00119 void OtherFunction(Generator& rGen, rEventSet& rAlph);
00120 bool IsGoodTest(Generator& rGen, rEventSet& rAlph);
00121 ...
00122 
00123 @endcode
00124 
00125 
00126 
00127 @section SecLuabindingsIntro3 Build System
00128 
00129 Since not every libFAUDES based application requires luabindings,
00130 the luabindings plug-in does not add code to libFAUDES itself but compiles
00131 to a seperate archive named libluafaudes (.a,.so,.dll) 
00132 
00133 The build system organises the compilation of the luabindings plug-in in two stages:
00134 - At stage one, SWIG is used to generate the wrapper code. Since the plug-in ships
00135   with appropriate wrapper code, this stage only needs to be processed if you want to 
00136   generate additional bindings for you plug-in. You will need SWIG version 1.3.36 installed on your system; see http://www.swig.org. 
00137   Use <tt>make luabindings-clean</tt> and <tt>make luabindings-prepare</tt> to re-build the wrapper code. 
00138   This stage is also processed by the configuration procedure, e.g. <tt>make dist-clean</tt> and <tt>make configure</tt>.
00139 - At stage two, the wrapper code and Lua is compiled to the archive
00140   <tt>libluafaudes.a</tt>. The plug-in includes the lua sources, no additional software requirements
00141   are imposed. This stage is processed by the std build procedure, eg <tt>make clean</tt> and <tt>make</tt>.
00142 
00143 
00144 @section SecLuabindingsIntro4 Advanced Topic: RTI extensions by Lua functions
00145 
00146 The Lua environment is designed to support both calling C code from a Lua script
00147 as well as calling Lua code from a C application. The latter direction is used
00148 by faudes::LuaFunction and faudes::LuaFunctionDefinition objects to extend libFAUDES 
00149 by Lua scripts that register with the libFAUDES run-time interface. Thus, libFAUDES applications 
00150 that interface to libFAUDES via the RTI can be transparently extended by Lua scripts. 
00151 
00152 
00153 @section License
00154 
00155 The luabindings plug-in is distributed with libFAUDES. 
00156 All code except Lua sources are provided under terms of the LGPL. 
00157 
00158 
00159 Copyright (c) 2008, 2010 Thomas Moor.
00160 
00161 
00162 Lua sources are included for convenience and come under terms of the following MIT License:
00163 
00164 License for Lua 5.0 and later versions
00165 Copyright (c) 1994-2008 Lua.org, PUC-Rio.
00166 
00167 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:
00168 
00169 The above copyright notice and this permission notice shall be included in all copies or substantial portions ofthe Software.
00170 
00171 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. 
00172 
00173 
00174 The luabindings plug-in also provides a variation of
00175 the advanced readline support, which is Copyright (C) 2004-2006 Mike Pall,
00176 with the same license as Lua. See also the file lbp_completion.cpp
00177 
00178 
00179 
00180 */
00181 

libFAUDES 2.23h --- 2014.04.03 --- c++ api documentaion by doxygen