X-Git-Url: https://git.decadent.org.uk/gitweb/?a=blobdiff_plain;f=doc%2Fluaif.tex;fp=doc%2Fluaif.tex;h=0000000000000000000000000000000000000000;hb=a6561c9679cd701b0d50c3cfd44e4664f7df2b2f;hp=76789a7e28b25da67c57d6d1a23368faa4062c65;hpb=cd09055902de482a1be019bf4b4efdae64c98d35;p=ion3.git diff --git a/doc/luaif.tex b/doc/luaif.tex deleted file mode 100644 index 76789a7..0000000 --- a/doc/luaif.tex +++ /dev/null @@ -1,148 +0,0 @@ - -\section{The Lua interface} - -This section finally describes the implementation details and how modules -should us the Lua interface. First, in section \ref{sec:supptypes} -we look at types supported by the interface, how objects are passed to Lua -code and how Lua tables should be accessed from Ion and modules. In section -\ref{sec:exporting} the methods for exporting functions and how they -are called from Lua are explained and in section \ref{sec:calling} the -method for calling Lua functions is explained. - -\subsection{Supported types} -\label{sec:supptypes} - -The following types are supported in passing parameters between the -C side of Ion and Lua: - -\begin{tabular}{rll} -\hline - Identifier - character & C type & Description\\ -\hline - \spec{i} & \type{int} & Integer\\ - \spec{s} & \type{char*} & String\\ - \spec{S} & \type{const char*} & Constant string\\ - \spec{d} & \type{double} &\\ - \spec{b} & \type{bool} &\\ - \spec{t} & \type{ExtlTab}\indextype{ExtlTab} & - Reference to Lua table\\ - \spec{f} & \type{ExltFn}\indextype{ExtlFn} & - Reference to Lua function.\\ - \spec{o} & Any \type{WObj*} &\\ -\end{tabular} - -The difference between identifiers '\spec{s}' and '\spec{S}' is that constant -strings as return values are not free'd by the level 1 call handler -(see below) after passing to Lua (\code{lua_pushstring} always makes a -copy) unlike normal strings. String parameters are always assumed to be -the property of the caller and thus implicitly const. - -Likewise, if a reference to '\spec{t}' or '\spec{f}' is wished to be stored -beyond the lifetime of a function receiving such as an argument, a new -reference should be created with \code{extl_ref_table}/\code{fn}. -References can be free'd with -\code{extl_unref_table}/\code{fn}. References gotten as return values with -the \code{extl_table_get} (how these work should be self-explanatory!) -functions are property of the caller and should be unreferenced with the -above-mentioned functions when no longer needed. -The functions \code{extl_fn}/\code{table_none()} -return the equivalent of NULL. - -\type{WObj}s are passed to Lua code with WWatch userdatas pointing to -them so the objects can be safely deleted although Lua code might still be -referencing them. (This is why SWIG or tolua would not have helped in -creating the interface: extra wrappers for each function would still -have been needed to nicely integrate into Ion's object system. Even in -the case that Ion was written in C++ this would be so unless extra bloat -adding pointer-like objects were used everywhere instead of pointers.) -It may be sometimes necessary check in Lua code that a value known to -be an Ion \type{WObj} is of certain type. This can be accomplished with -\code{obj_is(obj, "typename")}. \code{obj_typename(obj)} returns type -name for a \type{WObj}. - - -\subsection{Exporting functions} -\label{sec:exporting} - -Exported functions (those available to the extension language) are -defined by placing \code{EXTL_EXPORT} before the function implementation -in the C source. The script mkexports.pl is then used to automatically -generate \file{exports.c} from the source files if -\code{MAKE_EXPORTS=modulename} -is specified in the Makefile. All pointers with type beginning with a 'W' -are assumed to be pointers to something inheriting \type{WObj}. In -addition to a table of exported functions and second level call handlers -for these, \file{exports.c} will contain two functions -\code{module_register_exports()} and -\code{module_unregister_exports()} that should then be called in module -initialisation and deinitialisation code. - -You've seen the terms level 1 and 2 call handler mentioned above. -\index{call handler} -The Lua support code uses two so called call handlers to convert and check -the types of parameters passed from Lua to C and back to Lua. The first -one of these call handlers is the same for all exported functions and -indeed lua sees all exported as the same C function (the L1 call handler) -but with different upvalues passing a structure describing the actual -function and the second level call handler. The L1 call handler checks -that the parameters received from Lua match a template given as a string -of the identifier characters defined above. If everything checks out ok, -the parameters are then put in an array of C unions that can contain -anyof these known types and the L2 call handler is called. - -The L2 call handler (which is automatically generated by the mkexports.pl -script) for each exported function checks that the passed \type{WObj}s -are of the more refined type required by the function and then calls the -actual function. While the WObj checking could be done in the L1 handler -too, the L2 call handlers are needed because we may not know how the target -platform passes each parameter type to the called function. Thefore we -must let the C compiler generate the code to convert from a simple and -known enough parameter passing method (the unions) to the actual -parameter passing method. When the called function returns everything -is done in reverse order for return values (only one return value is -supported by the generated L2 call handlers). - - -\subsection{Calling Lua functions and code} -\label{sec:calling} - -The functions -\code{extl_call}\index{extl-call@\code{extl_call}}, -\code{extl_call_named}\index{extl-call-named@\code{extl_call_named}}, -\code{extl_dofile}\index{extl-dofile@\code{extl_dofile}} and -\code{extl_dostring}\index{extl-dostring@\code{extl_dostring}} -call a referenced function (\type{ExtlFn}), named function, execute a -string and a file, respectively. The rest of the parameters for all these -functions are similar. The 'spec' argument is a string of identifier -characters (see above) describing the parameters to be passed. These -parameters follow after 'rspec'. For dofile and dostring these parameters -are passed in the global table arg (same as used for program command -lien parameters) and for functions as you might expect. The parameter -'rspec' is a similar description of return values. Pointers to variables -that should be set to the return values follow after the input values. -The return value of all these functions tells if the call and parameter -passing succeeded or not. - -Sometimes it is necessary to block calls to all but a limited set of -Ion functions. This can be accomplished with -\code{extl_set_safelist}\index{extl-set-safelist@\code{extl_set_safelist}}. -The parameter to this function is a NULL-terminated array of strings -and the return value is a similar old safelist. -The call \code{extl_set_safelist(NULL)} removes any safelist and allows -calls to all exported functions. - - -\subsection{Miscellaneous notes} - -Configuration files should be read as before with the function -\code{read_config_for}\index{read-config-for@\code{read_config_for}} -except that the list of known options is no longer present. - -Winprops are now stored in Lua tables and can contain arbitrary -properties. The 'proptab' entry in each \type{WClientWin} is a reference -to a winprop table or \code{extl_table_none()} if such does not exist -and properties may be read with the \code{extl_table_gets} functions. -(It is perfectly legal to pass \code{extl_table_none()} references to -\code{extl_table_get*}.) -