
\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*}.)

