summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3luatex.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3luatex.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3luatex.dtx214
1 files changed, 214 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3luatex.dtx b/Master/texmf-dist/source/latex/l3kernel/l3luatex.dtx
new file mode 100644
index 00000000000..32950238227
--- /dev/null
+++ b/Master/texmf-dist/source/latex/l3kernel/l3luatex.dtx
@@ -0,0 +1,214 @@
+% \iffalse meta-comment
+%
+%% File: l3luatex.dtx Copyright (C) 2010-2015 The LaTeX3 Project
+%%
+%% It may be distributed and/or modified under the conditions of the
+%% LaTeX Project Public License (LPPL), either version 1.3c of this
+%% license or (at your option) any later version. The latest version
+%% of this license is in the file
+%%
+%% http://www.latex-project.org/lppl.txt
+%%
+%% This file is part of the "l3kernel bundle" (The Work in LPPL)
+%% and all files in that bundle must be distributed together.
+%%
+%% The released version of this bundle is available from CTAN.
+%%
+%% -----------------------------------------------------------------------
+%%
+%% The development version of the bundle can be found at
+%%
+%% http://www.latex-project.org/svnroot/experimental/trunk/
+%%
+%% for those people who are interested.
+%%
+%%%%%%%%%%%
+%% NOTE: %%
+%%%%%%%%%%%
+%%
+%% Snapshots taken from the repository represent work in progress and may
+%% not work or may contain conflicting material! We therefore ask
+%% people _not_ to put them into distributions, archives, etc. without
+%% prior consultation with the LaTeX3 Project.
+%%
+%% -----------------------------------------------------------------------
+%
+%<*driver>
+\documentclass[full]{l3doc}
+%</driver>
+%<*driver|package>
+\GetIdInfo$Id: l3luatex.dtx 5646 2015-06-30 21:19:24Z joseph $
+ {L3 Experimental LuaTeX-specific functions}
+%</driver|package>
+%<*driver>
+\begin{document}
+ \DocInput{\jobname.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \title{^^A
+% The \pkg{l3luatex} package\\LuaTeX-specific functions^^A
+% \thanks{This file describes v\ExplFileVersion,
+% last revised \ExplFileDate.}^^A
+% }
+%
+% \author{^^A
+% The \LaTeX3 Project\thanks
+% {^^A
+% E-mail:
+% \href{mailto:latex-team@latex-project.org}
+% {latex-team@latex-project.org}^^A
+% }^^A
+% }
+%
+% \date{Released \ExplFileDate}
+%
+% \maketitle
+%
+% \begin{documentation}
+%
+% \section{Breaking out to \Lua{}}
+%
+% The \LuaTeX{} engine provides access to the \Lua{} programming language,
+% and with it access to the \enquote{internals} of \TeX{}. In order to use
+% this within the framework provided here, a family of functions is
+% available. When used with \pdfTeX{} or \XeTeX{} these will raise an
+% error: use \cs{luatex_if_engine:T} to avoid this. Details of coding
+% the \LuaTeX{} engine are detailed in the \LuaTeX{} manual.
+%
+% \begin{function}[EXP, added = 2015-06-29]{\lua_now_x:n, \lua_now:n}
+% \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.
+%
+% In the case of the \cs{lua_now_x:n} version the input is fully expanded
+% by \TeX{} in an \texttt{x}-type manner \emph{but} the function remains
+% fully expandable.
+% \begin{texnote}
+% \cs{lua_now_x:n} is a macro wrapper around \tn{directlua}: when
+% \LuaTeX{} is in use two expansions will be required to yield the
+% result of the \Lua{} code.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}[added = 2015-06-30]{\lua_shipout_x:n, \lua_shipout:n}
+% \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: no \TeX{} expansion of the \meta{\Lua{} input}
+% will occur at this stage.
+%
+% In the case of the \cs{lua_shipout_x:n} version the input is fully
+% expanded by \TeX{} in an \texttt{x}-type manner during the shipout
+% operation.
+% \begin{texnote}
+% At a \TeX{} level, the \meta{\Lua{} input} is stored as a
+% \enquote{whatsit}.
+% \end{texnote}
+% \end{function}
+%
+% \begin{function}[EXP, added = 2015-06-29]{\lua_escape_x:n, \lua_escape:n}
+% \begin{syntax}
+% \cs{lua_escape:n} \Arg{token list}
+% \end{syntax}
+% Converts the \meta{token list} such that it can safely be passed to
+% \Lua{}: embedded backslashes, double and single quotes, and newlines
+% and carriage returns are escaped. This is done by prepending an extra
+% token consisting of a backslash with category code~$12$, and for the line
+% endings, converting them to |\n| and |\r|, respectively.
+%
+% In the case of the \cs{lua_escape_x:n} version the input is fully expanded
+% by \TeX{} in an \texttt{x}-type manner \emph{but} the function remains
+% fully expandable.
+% \begin{texnote}
+% \cs{lua_escape_x:n} is a macro wrapper around \tn{luaescapestring}:
+% when \LuaTeX{} is in use two expansions will be required to yield the
+% result of the \Lua{} code.
+% \end{texnote}
+% \end{function}
+%
+% \end{documentation}
+%
+% \begin{implementation}
+%
+% \section{\pkg{l3luatex} implementation}
+%
+% \begin{macrocode}
+%<*initex|package>
+% \end{macrocode}
+%
+% \subsubsection{Breaking out to \Lua{}}
+%
+% \begin{macro}[EXP]{\lua_now_x:n, \lua_now:n}
+% \begin{macro}{\lua_shipout_x:n, \lua_shipout:n}
+% \begin{macro}[EXP]{\lua_escape_x:n, \lua_escape:n}
+% Wrappers around the primitives. As with engines other than \LuaTeX{}
+% these have to be macros, we give them the same status in all cases.
+% When \LuaTeX{} is not in use, simply give an error message/
+% \begin{macrocode}
+\cs_new:Npn \lua_now_x:n #1 { \luatex_directlua:D {#1} }
+\cs_new:Npn \lua_now:n #1 { \lua_now_x:n { \exp_not:n {#1} } }
+\cs_new_protected:Npn \lua_shipout_x:n #1 { \luatex_latelua:D {#1} }
+\cs_new_protected:Npn \lua_shipout:n #1
+ { \lua_shipout_x:n { \exp_not:n {#1} } }
+\cs_new:Npn \lua_escape_x:n #1 { \luatex_luaescapestring:D {#1} }
+\cs_new:Npn \lua_escape:n #1 { \lua_escape_x:n { \exp_not:n {#1} } }
+\luatex_if_engine:F
+ {
+ \clist_map_inline:nn
+ { \lua_now_x:n , \lua_now:n , \lua_escape_x:n , \lua_escape:n }
+ {
+ \cs_set:Npn #1 ##1
+ {
+ \__msg_kernel_expandable_error:nnn
+ { kernel } { luatex-required } { #1 }
+ }
+ }
+ \clist_map_inline:nn
+ { \lua_shipout_x :n , \lua_shipout:n }
+ {
+ \cs_set_protected:Npn #1 ##1
+ {
+ \__msg_kernel_error:nnn
+ { kernel } { luatex-required } { #1 }
+ }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Messages}
+%
+% \begin{macrocode}
+\__msg_kernel_new:nnnn { kernel } { luatex-required }
+ { LuaTeX~engine~not~in~use!~Ignoring~#1. }
+ {
+ The~feature~you~are~using~is~only~available~
+ with~the~LuaTeX~engine.~LaTeX3~ignored~'#1'.
+ }
+% \end{macrocode}
+%
+% \begin{macrocode}
+%</initex|package>
+% \end{macrocode}
+%
+%\end{implementation}
+%
+%\PrintIndex