[luatex] l3luatex module

[Joseph Wright]

On 03/01/2011 14:09, Joseph Wright wrote:
> On 03/01/2011 13:56, Taco Hoekwater wrote:
>> On 01/03/2011 02:39 PM, Philipp Stephani wrote:
>>>
>>> Reading the source code, I guess \directlua behaves identically to
>>> \immediate\write, while \latelua corresponds to \write. If that is
>>> true, then the naming convention of the \iow_… macros should be
>>> applied.
>>
>> The correspondence is correct, but \directlua is expandable
>> (\immediate\write is not).
>
> Thanks Taco (and Philipp). I will revisit the l3luatex stuff later today
> and try to tighten both the expl3 function names and description up.

(With apologies to those on the LuaTeX list who are not interested in 
LaTeX3 - I think I need some LuaTeX experts to check the following.)

Okay, to save everyone needing to read the SVN feed, I've revised the 
documentation to:

%\begin{function}{
%  \lua_now:n / (EXP) |
%  \lua_now:x / (EXP) |
%}
%  \begin{syntax}
%    \cs{lua_now:n} \Arg{token list}
%  \end{syntax}
%  The \meta{token list} is first tokenized by \TeX, which will include
%  converting line ends to spaces in the usual \TeX\ manner and which
%  respects currently-applicable \TeX\ category codes. The resulting
%  \meta{\Lua\ input} is passed to the \Lua\ interpreter for processing.
%  Each \cs{lua_now:n} block is treated by \Lua\ as a separate chunk.
%  The \Lua\ interpreter will execute the \meta{\Lua\ input} immediately,
%  and in an expandable manner.
%  \begin{texnote}
%    \cs{lua_now:x} is the \LuaTeX\ primitive \cs{directlua} renamed.
%  \end{texnote}
%\end{function}
%
%\begin{function}{
%  \lua_shipout:n |
%  \lua_shipout:x |
%}
%  \begin{syntax}
%    \cs{lua_shipout:x} \Arg{token list}
%  \end{syntax}
%  The \meta{token list} is first tokenized by \TeX, which will include
%  converting line ends to spaces in the usual \TeX\ manner and which
%  respects currently-applicable \TeX\ category codes.  The resulting
%  \meta{\Lua\ input} is passed to the \Lua\ interpreter when the
%  current page is finalised (\emph{i.e}.~at shipout).  Each
%  \cs{lua_shipout:n} block is treated by Lua as a separate chunk.
%  The \Lua\ interpreter will execute the \meta{\Lua\ input} during the
%  page-building routine: no \TeX\ expansion of the \meta{\Lua\ input}
%  will occur at this stage.
%  \begin{texnote}
%    At a \TeX\ level, the \meta{\Lua\ input} is stored as a
%    `whatsit'.
%  \end{texnote}
%\end{function}
%
%\begin{function}{
%  \lua_shipout_x:n |
%  \lua_shipout_x:x |
%}
%  \begin{syntax}
%    \cs{lua_shipout:n} \Arg{token list}
%  \end{syntax}
%  The \meta{token list} is first tokenized by \TeX, which will include
%  converting line ends to spaces in the usual \TeX\ manner and which
%  respects currently-applicable \TeX\ category codes.  The resulting
%  \meta{\Lua\ input} is passed to the \Lua\ interpreter when the
%  current page is finalised (\emph{i.e}.~at shipout).  Each
%  \cs{lua_shipout:n} block is treated by Lua as a separate chunk.
%  The \Lua\ interpreter will execute the \meta{\Lua\ input} during the
%  page-building routine: the \meta{\Lua\ input} is expanded during this
%  process in addition to any expansion when the argument was read. This
%  makes these functions suitable for including material finalised
%  during the page building process (such as the page number).
%  \begin{texnote}
%    \cs{lua_sjhipout_x:n} is the \LuaTeX\ primitive \cs{latelua}
%    named using the \LaTeX3 scheme.
%
%    At a \TeX\ level, the \meta{\Lua\ input} is stored as a
%    `whatsit'.
%  \end{texnote}
%\end{function}

with the code block reading

%\begin{macro}{\lua_now:n}
%\begin{macro}{\lua_now:x}
%\begin{macro}{\lua_shipout_x:n}
%\begin{macro}{\lua_shipout_x:x}
%\begin{macro}{\lua_shipout:n}
%\begin{macro}{\lua_shipout:x}
%\begin{macro}{\lua_wrong_engine:}
% When \LuaTeX\ is in use, this is all a question of primitives with new
% names. On the other hand, for \pdfTeX\ and \XeTeX\ the argument should
% be removed from the input stream before issuing an error. This needs
% to be expandable, so the same idea is used as for \texttt{V}-type
% expansion, with an appropriately-named but undefined function.
%    \begin{macrocode}
\luatex_if_engine:TF
   {
     \cs_new_eq:NN \lua_now:x       \luatex_directlua:D
     \cs_new_eq:NN \lua_shipout_x:n \luatex_latelua:D
   }
   {
     \cs_new:Npn \lua_now:x #1 { \lua_wrong_engine: }
     \cs_new_protected:Npn \lua_shipout_x:n #1 { \lua_wrong_engine: }
   }
\cs_new:Npn \lua_now:n #1 {
   \lua_now:x { \exp_not:n {#1} }
}
\cs_generate_variant:Nn \lua_shipout_x:n { x }
\cs_new_protected:Npn \lua_shipout:n #1 {
   \lua_shipout_x:n { \exp_not:n {#1} }
}
\cs_generate_variant:Nn \lua_shipout:n { x }
\group_begin:
\char_make_letter:N\!
\char_make_letter:N\ %
\cs_gset:Npn\lua_wrong_engine:{%
\LuaTeX engine not in use!%
}%
\group_end:%
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}

This is modelled on the expl3 wrappers for \write, noting as Taco has 
pointed out that \directlua is expandable, but I take it that \latelua 
is not.

Once this is sorted out correctly then I'll sort out a CTAN snapshot.
-- 
Joseph Wright