luacode 1.2 (29dec11)

git-svn-id: svn://tug.org/texlive/trunk@24969 c570f23f-e606-0410-a88d-b1316a301751

4 files changed, 187 insertions, 30 deletions

diff --git a/Master/texmf-dist/doc/lualatex/luacode/News b/Master/texmf-dist/doc/lualatex/luacode/News
index c7d1e0ccfce..fb5dde8675a 100644
--- a/Master/texmf-dist/doc/lualatex/luacode/News
+++ b/Master/texmf-dist/doc/lualatex/luacode/News
@@ -1,3 +1,7 @@
+2011/12/29 v1.2
+    * new helper macros \luastring, \luastringO, \luastringN
+    * new debug (logging) feature
+
 2011/05/24 v1.1
     * compatibility with luatexbase 0.4
 
diff --git a/Master/texmf-dist/doc/lualatex/luacode/luacode.pdf b/Master/texmf-dist/doc/lualatex/luacode/luacode.pdf
index 2a211e20bb4..bdfc949579c 100644
--- a/Master/texmf-dist/doc/lualatex/luacode/luacode.pdf
+++ b/Master/texmf-dist/doc/lualatex/luacode/luacode.pdf
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}
diff --git a/Master/texmf-dist/tex/lualatex/luacode/luacode.sty b/Master/texmf-dist/tex/lualatex/luacode/luacode.sty
index 68f281f425f..6acca9a7149 100644
--- a/Master/texmf-dist/tex/lualatex/luacode/luacode.sty
+++ b/Master/texmf-dist/tex/lualatex/luacode/luacode.sty
@@ -42,7 +42,7 @@
     \noexpand\else \noexpand\expandafter\noexpand\endinput%
     \noexpand\fi}%
 \expandafter\y\csname luacode@sty@endinput\endcsname%
-\ProvidesPackage{luacode}[2011/05/24 v1.0 lua-in-tex helpers (mpg)]
+\ProvidesPackage{luacode}[2011/12/29 v1.2 lua-in-tex helpers (mpg)]
 \RequirePackage{ifluatex}
 \ifluatex\else
   \PackageError{luacode}{LuaTeX is required for this package. Aborting.}{%
@@ -52,9 +52,22 @@
   \expandafter\luacode@sty@endinput
 \fi
 \RequirePackage{luatexbase}
+\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)')
+}
+\newcommand \luacode@dbg@exec [1] {%
+  \directlua {
+    \luacode@maybe@printdbg{#1}
+    #1
+  }%
+}
 \begingroup \catcode`\~\active \expandafter\endgroup
 \@firstofone{%
-  \newcommand*\luacode@execute [1] {%
+  \newcommand \luacode@execute [1] {%
     \begingroup
     \escapechar92
     \newlinechar10
@@ -63,7 +76,7 @@
     \let\%=\luacode@percentchar
     \let\#=\luacode@sharpchar
     \expandafter\expandafter\expandafter\endgroup
-    \luatexbase@directlua{#1}}
+    \luacode@dbg@exec{#1}}
 }
 \begingroup \escapechar\m@ne \edef\aux{\endgroup
   \unexpanded{\newcommand\luacode@percentchar}{\string\%}%
@@ -85,8 +98,8 @@
   \luacode@next}
 \newtoks\luacode@lines
 \newcommand*\luacode@addline [1] {%
-  \luacode@lines\expandafter{\the\luacode@lines^^J#1}}
-\newcommand \luacode@grab@body {
+  \luacode@lines\expandafter{\the\luacode@lines#1^^J}}
+\newcommand \luacode@grab@body [1] {
   \luacode@lines{}%
   \endlinechar10
   \luacode@grab@lines}
@@ -133,12 +146,18 @@
   \SetCatcodeRange {97}{122}{11}
 }
 \endgroup
-\@ifdefinable\luadirect {\let\luadirect\luatexbase@directlua}
+\newcommand \LuaCodeDebugOn  {\let \luacode@maybe@printdbg \luacode@printdbg}
+\newcommand \LuaCodeDebugOff {\let \luacode@maybe@printdbg \@gobble}
+\LuaCodeDebugOff
+\@ifdefinable\luadirect {\let\luadirect\luacode@dbg@exec}
 \newcommand*\luaexec [1] {\luacode@execute{#1}}
 \newenvironment {luacode}  {\luacode@begin\luacode@table@soft} {}
 \newenvironment {luacode*} {\luacode@begin\CatcodeTableOther}  {}
 \newcommand     \luacodestar    {\@nameuse{luacode*}}
 \def            \endluacodestar {\@nameuse{endluacode*}}
+\newcommand \luastring   [1] {"\luatexluaescapestring{#1}"}
+\newcommand \luastringO  [1] {\luastring{\unexpanded\expandafter{#1}}}
+\newcommand \luastringN  [1] {\luastring{\unexpanded{#1}}}
 \luacode@sty@endinput
 \endinput
 %%