diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3luatex.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3luatex.dtx | 214 |
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 |