From 56ecd0d3d0de54cebdeb29cc8a056001ee93b02e Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 29 Dec 2011 23:02:47 +0000 Subject: luacode 1.2 (29dec11) git-svn-id: svn://tug.org/texlive/trunk@24969 c570f23f-e606-0410-a88d-b1316a301751 --- .../texmf-dist/source/lualatex/luacode/luacode.dtx | 182 ++++++++++++++++++--- 1 file changed, 158 insertions(+), 24 deletions(-) (limited to 'Master/texmf-dist/source/lualatex/luacode') 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} % % \end{macrocode} -- cgit v1.2.3