luaif.tex

   1
   2 \section{The Lua interface}
   3
   4 This section finally describes the implementation details and how modules
   5 should us the Lua interface. First, in section \ref{sec:supptypes}
   6 we look at types supported by the interface, how objects are passed to Lua
   7 code and how Lua tables should be accessed from Ion and modules. In section
   8 \ref{sec:exporting} the methods for exporting functions and how they
   9 are called from Lua are explained and in section \ref{sec:calling} the
  10 method for calling Lua functions is explained.
  11
  12 \subsection{Supported types}
  13 \label{sec:supptypes}
  14
  15 The following types are supported in passing parameters between the
  16 C side of Ion and Lua:
  17
  18 \begin{tabular}{rll}
  19 \hline
  20  Identifier
  21  character &    C type &        Description\\
  22 \hline
  23         \spec{i} & \type{int} & Integer\\
  24         \spec{s} & \type{char*} &       String\\
  25         \spec{S} & \type{const char*} & Constant string\\
  26         \spec{d} & \type{double} &\\
  27         \spec{b} & \type{bool} &\\
  28         \spec{t} & \type{ExtlTab}\indextype{ExtlTab} &
  29                         Reference to Lua table\\
  30         \spec{f} & \type{ExltFn}\indextype{ExtlFn} &
  31                         Reference to Lua function.\\
  32         \spec{o} & Any \type{WObj*} &\\
  33 \end{tabular}
  34
  35 The difference between identifiers '\spec{s}' and '\spec{S}' is that constant
  36 strings as return values are not free'd by the level 1 call handler
  37 (see below) after passing to Lua (\code{lua_pushstring} always makes a
  38 copy) unlike normal strings. String parameters are always assumed to be
  39 the property of the caller and thus implicitly const.
  40
  41 Likewise, if a reference to '\spec{t}' or '\spec{f}' is wished to be stored
  42 beyond the lifetime of a function receiving such as an argument, a new
  43 reference should be created with \code{extl_ref_table}/\code{fn}.
  44 References can be free'd with
  45 \code{extl_unref_table}/\code{fn}. References gotten as return values with
  46 the \code{extl_table_get} (how these work should be self-explanatory!)
  47 functions are property of the caller and should be unreferenced with the
  48 above-mentioned functions when no longer needed.
  49 The functions \code{extl_fn}/\code{table_none()}
  50 return the equivalent of NULL.
  51
  52 \type{WObj}s are passed to Lua code with WWatch userdatas pointing to
  53 them so the objects can be safely deleted although Lua code might still be
  54 referencing them. (This is why SWIG or tolua would not have helped in
  55 creating the interface: extra wrappers for each function would still
  56 have been needed to nicely integrate into Ion's object system. Even in
  57 the case that Ion was written in C++ this would be so unless extra bloat
  58 adding pointer-like objects were used everywhere instead of pointers.)
  59 It may be sometimes necessary check in Lua code that a value known to
  60 be an Ion \type{WObj} is of certain type. This can be accomplished with
  61 \code{obj_is(obj, "typename")}. \code{obj_typename(obj)} returns type
  62 name for a \type{WObj}.
  63
  64
  65 \subsection{Exporting functions}
  66 \label{sec:exporting}
  67
  68 Exported functions (those available to the extension language) are
  69 defined by placing \code{EXTL_EXPORT} before the function implementation
  70 in the C source. The script mkexports.pl is then used to automatically
  71 generate \file{exports.c} from the source files if
  72 \code{MAKE_EXPORTS=modulename}
  73 is specified in the Makefile. All pointers with type beginning with a 'W'
  74 are assumed to be pointers to something inheriting \type{WObj}. In
  75 addition to a table of exported functions and second level call handlers
  76 for these, \file{exports.c} will contain two functions
  77 \code{module_register_exports()} and
  78 \code{module_unregister_exports()} that should then be called in module
  79 initialisation and deinitialisation code.
  80
  81 You've seen the terms level 1 and 2 call handler mentioned above.
  82 \index{call handler}
  83 The Lua support code uses two so called call handlers to convert and check
  84 the types of parameters passed from Lua to C and back to Lua. The first
  85 one of these call handlers is the same for all exported functions and
  86 indeed lua sees all exported as the same C function (the L1 call handler)
  87 but with different upvalues passing a structure describing the actual
  88 function and the second level call handler. The L1 call handler checks
  89 that the parameters received from Lua match a template given as a string
  90 of the identifier characters defined above. If everything checks out ok,
  91 the parameters are then put in an array of C unions that can contain
  92 anyof these known types and the L2 call handler is called.
  93
  94 The L2 call handler (which is automatically generated by the mkexports.pl
  95 script) for each exported function checks that the passed \type{WObj}s
  96 are of the more refined type required by the function and then calls the
  97 actual function. While the WObj checking could be done in the L1 handler
  98 too, the L2 call handlers are needed because we may not know how the target
  99 platform passes each parameter type to the called function. Thefore we
 100 must let the C compiler generate the code to convert from a simple and
 101 known enough parameter passing method (the unions) to the actual
 102 parameter passing method. When the called function returns everything
 103 is done in reverse order for return values (only one return value is
 104 supported by the generated L2 call handlers).
 105
 106
 107 \subsection{Calling Lua functions and code}
 108 \label{sec:calling}
 109
 110 The functions
 111 \code{extl_call}\index{extl-call@\code{extl_call}},
 112 \code{extl_call_named}\index{extl-call-named@\code{extl_call_named}},
 113 \code{extl_dofile}\index{extl-dofile@\code{extl_dofile}} and
 114 \code{extl_dostring}\index{extl-dostring@\code{extl_dostring}}
 115 call a referenced function (\type{ExtlFn}), named function, execute a
 116 string and a file, respectively. The rest of the parameters for all these
 117 functions are similar. The 'spec' argument is a string of identifier
 118 characters (see above) describing the parameters to be passed. These
 119 parameters follow after 'rspec'. For dofile and dostring these parameters
 120 are passed in the global table arg (same as used for program command
 121 lien parameters) and for functions as you might expect. The parameter
 122 'rspec' is a similar description of return values. Pointers to variables
 123 that should be set to the return values follow after the input values.
 124 The return value of all these functions tells if the call and parameter
 125 passing succeeded or not.
 126
 127 Sometimes it is necessary to block calls to all but a limited set of
 128 Ion functions. This can be accomplished with
 129 \code{extl_set_safelist}\index{extl-set-safelist@\code{extl_set_safelist}}.
 130 The parameter to this function is a NULL-terminated array of strings
 131 and the return value is a similar old safelist.
 132 The call \code{extl_set_safelist(NULL)} removes any safelist and allows
 133 calls to all exported functions.
 134
 135
 136 \subsection{Miscellaneous notes}
 137
 138 Configuration files should be read as before with the function
 139 \code{read_config_for}\index{read-config-for@\code{read_config_for}}
 140 except that the list of known options is no longer present.
 141
 142 Winprops are now stored in Lua tables and can contain arbitrary
 143 properties. The 'proptab' entry in each \type{WClientWin} is a reference
 144 to a winprop table or \code{extl_table_none()} if such does not exist
 145 and properties may be read with the \code{extl_table_gets} functions.
 146 (It is perfectly legal to pass \code{extl_table_none()} references to
 147 \code{extl_table_get*}.)
 148