summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/lualatex/luacode
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-12-29 23:02:47 +0000
committerKarl Berry <karl@freefriends.org>2011-12-29 23:02:47 +0000
commit56ecd0d3d0de54cebdeb29cc8a056001ee93b02e (patch)
tree04502c1a012256ad6d34c6150c8812f4dc1a663c /Master/texmf-dist/source/lualatex/luacode
parent1ff96ce12187f58bcdc638d5b3187f8a270b23ca (diff)
luacode 1.2 (29dec11)
git-svn-id: svn://tug.org/texlive/trunk@24969 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/lualatex/luacode')
-rw-r--r--Master/texmf-dist/source/lualatex/luacode/luacode.dtx182
1 files changed, 158 insertions, 24 deletions
diff --git a/Master/texmf-dist/source/lualatex/luacode/luacode.dtx b/Master/texmf-dist/source/lualatex/luacode/luacode.dtx
index 498d5840768..4b0ca0ecf00 100644
--- a/Master/texmf-dist/source/lualatex/luacode/luacode.dtx
+++ b/Master/texmf-dist/source/lualatex/luacode/luacode.dtx
@@ -77,8 +77,9 @@ See the source file for author and licensing information.
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{lmodern}
-\usepackage{fixltx2e}
+\usepackage{fixltx2e, mparhack}
+\usepackage{xcolor}
\usepackage{booktabs}
\usepackage{xspace}
\usepackage[a4paper]{geometry}
@@ -95,6 +96,7 @@ See the source file for author and licensing information.
\def\cs#1{\@backslashchar #1}}
\MakeShortVerb\|
+\renewcommand\MacroFont{\ttfamily\small\color{blue}}
\begin{document}
\DocInput{luacode.dtx}%
@@ -122,7 +124,7 @@ See the source file for author and licensing information.
%
% \title{The \pk{luacode} package}
% \author{Manuel P\'egouri\'e-Gonnard \email{mpg@elzevir.fr}}
-% \date{v1.0 2010/11/08}
+% \date{v1.2 2011/12/29}
%
% \maketitle
%
@@ -138,6 +140,8 @@ See the source file for author and licensing information.
%
% \section{Documentation}
%
+% \subsection{Lua code in \LaTeX}
+%
% For an introduction to the most important gotchas of |\directlua|, see
% \file{lualatex-doc.pdf}. Before presenting the tools in this package, let me
% insist that the best way to manage a non-trivial piece of Lua code is
@@ -146,11 +150,13 @@ See the source file for author and licensing information.
%
% \medskip
%
+% \DescribeMacro\luadirect
% First, the exact syntax of |\directlua| has changed along version of
% Lua\TeX, so this package provides a |\luadirect| command which is an exact
% synonym of |\directlua| except that it doesn't have the funny, changing
-% parts of its syntax.\footnote{And it expands in two steps If you don't known
-% what it means, then you hopefully don't need to.}
+% parts of its syntax, and benefits from the debugging facilities described
+% below (\ref{dbg}).\footnote{And expands in two steps instead of one. If
+% you don't know what it means, then you hopefully don't need to.}
%
% The problems with |\directlua| (or |\luadirect|) are mainly with \TeX\
% special characters. Actually, things are not that bad, since most special
@@ -160,25 +166,33 @@ See the source file for author and licensing information.
% it allows to pass information from \TeX\ to Lua, but you must be careful
% and use only purely expandable macros.
%
+% \DescribeMacro\luaexec
% The |\luaexec| command is similar to |\luadirect| but with a few additional
% features:\footnote{And one major drawback: it is not purely expandable. See
-% above.} |\\| gives a double backslash (convenient in Lua strings), |\%| a
-% percent character, and |~| just works. If you happen to need a single
+% previous note.} |\\| gives a double backslash (convenient in Lua strings),
+% |\%| a percent character, and |~| just works. If you happen to need a single
% backslash, you can still use a construct like |\string\n| just as with
% |\luadirect|. Also, \TeX\ macros are expanded.
%
+% \DescribeEnv{luacode}
% The |luacode| environment is similar, except that you can use |%| and other
% special characters directly (but |\%| also works). Only the backslash and
% the braces keep their special meaning, so that macros still work as usual,
% and you still need to use a |\string| trick to get a single backslash.
+% Technical note: you are supposed to leave a space (or end-of-line) after
+% the |\begin{luacode}|, which is probably a natural thing to do anyway.
%
+% \DescribeEnv{luacode*}
% A variant |luacode*| goes further and makes even backslash a normal
% character, so that you don't need any trick to obtain a single backslash. On
-% the other end, macros don't work any more.
+% the other end, macros don't work any more. In addition, the line breaks in
+% the environments are respected, so that you can use line-wise Lua comments
+% in the normal way, without mistakenly commenting the rest of the chunk.
+%
+% \medskip
%
-% In addition, the line breaks in the environments are respected, so that you
-% can use line-wise Lua comments in the normal way, without mistakenly
-% commenting the rest of the chunk.
+% The following table summarizes how to use special characters with the
+% various commands and environments.
%
% \begin{center}
% \begin{tabular}{rcccc}
@@ -189,14 +203,15 @@ See the source file for author and licensing information.
% Single backslash & Using |\string| & Using |\string| & Using |\string| & Just |\| \\
% Double backslash & |\string\\| & |\\| & |\\| & |\\| \\
% Tilde & |\string~| & |~| & |~| & |~| \\
-% Sharp & |\string#| & |\#| & |\#| or |#| & |#| \\
-% Percent & No easy way & |\%| & |\%| or |%| & |%| \\
-% \TeX\ line comments & Yes & Yes & No & No \\
+% Sharp & |\string#| & |\#| & |#| (or |\#|) & |#| \\
+% Percent & No easy way & |\%| & |%| (or |\%|) & |%| \\
+% \TeX\ comments & Yes & Yes & No & No \\
% Lua line comments & No & No & Yes & Yes \\
% \bottomrule
% \end{tabular}
% \end{center}
%
+% \DescribeEnv{luacodestar}
% Note that you cannot use the environments inside the argument of a command
% (just as with verbatim commands and environments). If you wish to define
% derived environments, you'll need to use |\luacode| \dots |\endluacode|
@@ -206,6 +221,52 @@ See the source file for author and licensing information.
% The test file (section~\ref{test}, or \file{test-luacode.tex} in the same
% directory as this document) provides stupid but complete examples.
%
+% \subsection{Helper macros}
+%
+% As mentioned in the previous section, except for trivial pieces of codes (or
+% examples) it is good practice to keep all your Lua code in separate |.lua|
+% files and then use |\luadirect| only to |require()| or |dofile()| it and
+% define \LaTeX\ wrappers for some functions, eg:
+% \begin{quote}
+% |\newcommand*\foo[2]{\luadirect{foo("#1", #2)}}|
+% \end{quote}
+% This way, problems with \TeX\ special characters are avoided, since most of
+% the Lua is never seen by \TeX. Unfortunately, there is still potential
+% for problems. For example |\foo{a"b}{2}| will cause the Lua interpreter to
+% complain since the |"| in |#1| will end the string; we want the Lua
+% interpreter to see |"a\"b"| as the first argument.
+%
+% \DescribeMacro\luastring
+% Fortunately, Lua\TeX\ offers a primitive that does exactly what we need:
+% escape characters that need to be escaped in a Lua string. Unfortunately, it
+% has a very long name (especially in the prefixed form available in \LaTeX):
+% |\luatexluaescapestring|. Also, you need to think to use quotes in addition
+% to this primitive. So this package provides a shorter version: |\luastring|
+% that also include the quotes, so a safer version of |\foo| might be defined
+% as
+% \begin{quote}
+% |\newcommand*\foo[2]{\luadirect{foo(\luastring{#1}, #2)}}|
+% \end{quote}
+%
+% \DescribeMacro\luastringN
+% \DescribeMacro\luastringO
+% It should be noted that the argument of |\luastring| is fully
+% expanded\footnote{If you don't know what this means, just skip this
+% paragraph.} before being turned into a Lua string. In case where such an
+% expansion is unwanted, two variants are provided: |\luastringN| for no
+% expansion, and |\luastringO| for one-level expansion (of the first token)
+% only.
+%
+% \subsection{Debugging} \label{dbg}
+%
+% \DescribeMacro\LuaCodeDebugOn
+% \DescribeMacro\LuaCodeDebugOff
+% The commands |\luadirect| and |\luaexec| as well as the environments
+% |luacode| and |luacode*| can optionally print the Lua code as it will be
+% seen by the Lua interpreter in the log file before executing it. The feature
+% is disabled by default and can be turned on and off using |\LuaCodeDebugOn|
+% and |\LuaCodeDebugOff| (which obey the usual \TeX\ scoping rules).
+%
% \section{Implementation}
%
% \begin{macrocode}
@@ -256,7 +317,7 @@ See the source file for author and licensing information.
% Package declaration.
%
% \begin{macrocode}
-\ProvidesPackage{luacode}[2011/05/24 v1.0 lua-in-tex helpers (mpg)]
+\ProvidesPackage{luacode}[2011/12/29 v1.2 lua-in-tex helpers (mpg)]
% \end{macrocode}
%
% Make sure Lua\TeX\ is used.
@@ -280,6 +341,29 @@ See the source file for author and licensing information.
%
% \subsection{Internal code}
%
+% Produce Lua code printing debug info for the given argument.
+%
+% \begin{macrocode}
+\newcommand \luacode@printdbg [1] {%
+ texio.write_nl('log',
+ '-- BEGIN luacode debug (on input line \the\inputlineno)')
+ texio.write_nl('log', "\luatexluaescapestring{#1}")
+ texio.write_nl('log',
+ '-- END luacode debug (on input line \the\inputlineno)')
+}
+% \end{macrocode}
+%
+% Execute a piece of Lua code, possibly printing debug info.
+% |maybe@printdbg| will be either |printdbg| or |gobble|, see user macros.
+%
+% \begin{macrocode}
+\newcommand \luacode@dbg@exec [1] {%
+ \directlua {
+ \luacode@maybe@printdbg{#1}
+ #1
+ }%
+}
+% \end{macrocode}
% Execute a piece of code, with shortcuts for double-backslash, percent and
% tilde, and trying to preserve newlines. This internal macro is long so
% that we can use in the environment, while the corresponding user command
@@ -288,7 +372,7 @@ See the source file for author and licensing information.
% \begin{macrocode}
\begingroup \catcode`\~\active \expandafter\endgroup
\@firstofone{%
- \newcommand*\luacode@execute [1] {%
+ \newcommand \luacode@execute [1] {%
\begingroup
\escapechar92
\newlinechar10
@@ -297,7 +381,7 @@ See the source file for author and licensing information.
\let\%=\luacode@percentchar
\let\#=\luacode@sharpchar
\expandafter\expandafter\expandafter\endgroup
- \luatexbase@directlua{#1}}
+ \luacode@dbg@exec{#1}}
}
% \end{macrocode}
%
@@ -348,14 +432,16 @@ See the source file for author and licensing information.
% \begin{macrocode}
\newtoks\luacode@lines
\newcommand*\luacode@addline [1] {%
- \luacode@lines\expandafter{\the\luacode@lines^^J#1}}
+ \luacode@lines\expandafter{\the\luacode@lines#1^^J}}
% \end{macrocode}
%
% Loop initialisation. Set endlinechar explicitely so that we can use it
-% as a delimiter (and later when writing the code to Lua).
+% as a delimiter (and later when writing the code to Lua). Eat up the first
+% token which is supposed to be a (catcode 12) |\endlinechar| character
+% token.
%
% \begin{macrocode}
-\newcommand \luacode@grab@body {
+\newcommand \luacode@grab@body [1] {
\luacode@lines{}%
\endlinechar10
\luacode@grab@lines}
@@ -375,9 +461,9 @@ See the source file for author and licensing information.
\fi}
% \end{macrocode}
%
-% Strip catcode 12 spaces from the beginning the token list inside
-% |\luacode@curr|. First we need catcode 12 space, then we
-% procede in the usual way.
+% Strip catcode 12 spaces from the beginning of the token list inside
+% |\luacode@curr|. First we need catcode 12 space, then we procede in the
+% usual way.
%
% \begin{macrocode}
\begingroup\catcode32 12 \expandafter\endgroup
@@ -429,10 +515,18 @@ See the source file for author and licensing information.
%
% \subsection{Public macros and environments}
%
-% The |\luadirect| and |\luaexec| macro.
+% Debugging.
%
% \begin{macrocode}
-\@ifdefinable\luadirect {\let\luadirect\luatexbase@directlua}
+\newcommand \LuaCodeDebugOn {\let \luacode@maybe@printdbg \luacode@printdbg}
+\newcommand \LuaCodeDebugOff {\let \luacode@maybe@printdbg \@gobble}
+\LuaCodeDebugOff
+% \end{macrocode}
+%
+% The |\luadirect| and |\luaexec| macros.
+%
+% \begin{macrocode}
+\@ifdefinable\luadirect {\let\luadirect\luacode@dbg@exec}
\newcommand*\luaexec [1] {\luacode@execute{#1}}
% \end{macrocode}
%
@@ -445,6 +539,14 @@ See the source file for author and licensing information.
\def \endluacodestar {\@nameuse{endluacode*}}
% \end{macrocode}
%
+% Helper macros
+%
+% \begin{macrocode}
+\newcommand \luastring [1] {"\luatexluaescapestring{#1}"}
+\newcommand \luastringO [1] {\luastring{\unexpanded\expandafter{#1}}}
+\newcommand \luastringN [1] {\luastring{\unexpanded{#1}}}
+% \end{macrocode}
+%
% We're already done!
%
% \begin{macrocode}
@@ -523,6 +625,38 @@ See the source file for author and licensing information.
-- a lua comment: no way to use a TeX variable here
\end{mathluacode*}
+\begin{luacode*}
+ function myfunc(str)
+ assert(type(str) == 'string')
+ tex.sprint(-2, str)
+ end
+\end{luacode*}
+
+\newcommand*\mymac [1] {\texttt{\luadirect{myfunc(\luastring{#1})}}\par}
+\mymac{abc}
+\mymac{123}
+\mymac{a"b\string\nc'd}
+
+\def\mac{\onelevel}
+\def\onelevel{fully expanded}
+string : \texttt{\luadirect{myfunc(\luastring \mac)}}\par
+stringO: \texttt{\luadirect{myfunc(\luastringO\mac)}}\par
+stringN: \texttt{\luadirect{myfunc(\luastringN\mac)}}\par
+
+\LuaCodeDebugOn
+\luadirect {local foo = 'bar' .. \luastring{a"b'c}}
+\luaexec {local foo = 'bar\%\#' .. \luastring{a"b'c}}
+\begin{luacode}
+ local foo = 'bar'
+ local baz = 12 % 2
+ assert(\luastring\mac == 'fully expanded')
+ -- assert(\luastringO\mac == '\\onelevel')
+ -- assert(\luastringN\mac == '\\mac')
+\end{luacode}
+
+\LuaCodeDebugOff
+\luadirect{local rem = 'dbg should be disabled here'}
+
\end{document}
%</testlatex>
% \end{macrocode}