2
edits
Changes
Jump to navigation
Jump to search
m
{{note | This is a wikified version of [https://www.tug.org/members/TUGboat/tb30-2/tb95mahajan-luatex.pdf this TugBoat article ]. Feel free to modify it. }}= Calling Lua from TeX =
In this article, I explain how to use The interweaving of ConTeXt and Lua to write macros in [[LuaTeX]]. I give some examples consists of macros two elements: first you tell TeX that are complicated in [[PdfTeX]]you're starting some Lua code; then, but can be defined easily using once inside Lua in LuaTeX. These examples include macros that do arithmetic on their arguments, you need to use loops, parse their arguments, and manipulate verbatim textthe appropriate functions to put things into the TeX stream.
As its name suggests, [[LuaTeX]] adds Lua, a programming language, to TeX, the typesetter. This allows us to program TeX in a high-level programming language. For example, consider a TeX macro that divides two numbers. Such a macro is provided by the <tt>fp</tt> package and also by <tt>pgfmath</tt> library of the <tt>TikZ</tt> package. The following comment is from the <tt>fp</tt> package
\def\FP@div#1#$2.#3.#4+ 5 \relax#5.#6.#7neq \relaxctxlua{% % [...] algorithmic idea context(for x>03+5)}$, y>0) % - %determine but is equal to \FP@shift such that % y*10^\FP@shift < 100000000 % <=y*10^ctxlua{context(\FP@shift2+15)}. % - %determine This is \FP@shift' such that % x*10^\FP@shift'< 100000000 % <=x*10^ctxlua{context(string.upper(\FP@shift+1"absolutely")) % - x=x*\FP@shift' % - y=y*\FP@shift % - \FP@shift=\FP@shift-\FP@shift' % - res=0 % - while y>0 %fixed-point representation! % - \FP@times=0 % - while x>y % - \FP@times=\FP@times+1 % - x=x-y % - end % - y=y/10 % - res=10*res+\FP@times/1000000000 % - end % - %shift the result according to \FP@shift} true.
The <tt>pgfmath</tt> library implements {{cmd|ctxlua}} operates under the macro in a similar way, but limits the number of shifts that it doesnormal TeX catcodes (category codes). These macros highlight This means the state of affairs in writing TeX macros. Even simple following two things like multiplying two numbers are hard; you either have to work extremely hard to circumvent for the programming limitations of Lua code inside:* all newlines get treated as spaces* special TeXcharacters like &, #, $, or{, more frequently}, hope that someone else has done the hard work for youetc., need to be escaped. In LuaTeXaddition, such a function can be written using the <warning above still holds. All the Lua code>/</, even the comments, must be valid TeX. Some code> operator (I will explain to illustrate the details later)newline problem:
ThusThe problem with special TeX characters. (<code>#t</code> is Lua for 'the length of array <code>t</code>.)<texcode>% This doesn't work:%\ctxlua% {local t = {1,2,3,4}% tex.print("length " .. #t)}\ctxlua {local t = {1, with LuaTeX ordinary users can write simple macros; and2, perhaps more importantly3, can read and understand macros written by TeX wizards4} tex.print("length " ..\string#t)}</texcode>
Since the LuaTeX project started it has been actively supported by ConTeXt. <ref>Not surprising, as two of LuaTeX main developers—Taco Hoekwater and Hans Hagen—are also the main ConTeXt developers.</ref> These days, the various <em>How do I write such a macro</em> questions on the ConTeXt mailing list are answered by a solution that uses Lua. I present a few such examples in this article. I have deliberately avoided examples about [[Fonts in LuaTeX | fonts]] and non-Latin languages. There is already quite a bit of documentation about them. In this article, I highlight how to use LuaTeX to write macros that require some <em>flow control</em>: randomized outputs, loops, and parsing.
To One can execute a first approximation, the interaction between Lua code from within TeX and Lua is straightforward. When TeX (i.e., the LuaTeX engine) starts, it loads get back the input file result in memory and processes it token TeX by tokenusing {{cmd|cldcontext}}. When TeX encounters <code>\directlua</code>, it stops reading the file in memoryThus, <em>fully expands the argument of <if {{code>\directlua</code></em>, and passes the control to |myfunction}} is a Lua instance. The Lua instance, which runs with function of a few preloaded libraries, processes the expanded arguments of <variable {{code>\directlua</code>. This |x}} defined in Lua instance has a special output stream which can be accessed using <code>tex.print, {{cmd|cldcontext|{myfunction(...5)</code>. The function <code>tex.print(...)</code> is just like }}} returns the Lua function <value {{code>print|myfunction(...5)</code> except that <code>tex.print(...)</code> prints to a <em>}} in TeX stream</em> rather than to the standard output. When the Lua instance finishes processing its input, it passes the contents of the <em>TeX stream</em> back This is equivalent to TeX.<ref>The output of <code>tex.print{{cmd|ctxlua|{context(myfunction(...5))</code> is buffered and not passed to TeX until the Lua instance has stopped.</ref> TeX then inserts the contents of the <em>TeX stream</em> at the current location of the file that it was reading; expands the contents of the <em>TeX stream</em>; and continues. If TeX encounters another <code>\directlua</code>, the above process is repeated}}}.
As an exercise== A larger Lua block: {{cmd|startluacode}}…{{cmd|stopluacode}} == Inside the {{cmd|startluacode}}…{{cmd|stopluacode}} environment, imagine what happens when newlines and special characters behave normally. This solves the following input is processed by LuaTeXcatcode problem that {{cmd|ctxlua}} suffers from. <ref>In this exampleApart from these special characters, I used two different kinds of quotations to avoid escaping quotes. Escaping quotes inside <the main warning remains in force: all the Lua code>\directlua</code> is tricky. The above was a contrived example; if you ever need to escape quotes, you can use even the <code>\startluacode ... \stopluacode</code> syntax explained latercomments, must be valid TeX.</ref>
On top of these LuaTeX primitives, ConTeXt provides a higher level interface. There are two ways to call == Putting Lua from ConTeXt. The first is a macro <code>\ctxlua</in an external file == You can put your lua code> in an external file (read as ConTeXt Lua), which is similar to with the <code>\directlua</code>. (Aside: It is possible to run the Lua instance under different name spaces. <code>\ctxlualua</code> is extension) and include it with the default name space; other name spaces are explained later.) <code>\ctxluarequire</code> is good for calling small snippets of Lua. The argument of <code>\ctxlua</code> is parsed under normal TeX catcodes (category codes), so the end of line character has the same catcode as a space. This can lead to surprises. For example, if you try to use a Lua comment, everything after the comment gets ignored.command:
This can be avoided by using == Namespaces == It is a TeX comment instead of a Lua comment. However, working under normal TeX catcodes poses a bigger problem: special TeX characters like &, #, $, {, }, etc., need good habit to be escapedput your custom-defined functions in their own namespace. For example, # has to be escaped with The traditional namespace for this is <code>\stringuserdata</code> to be used in <code>\ctxlua</code>.:
As the argument The full list of <code>\ctxlua<canonical namespaces, taken from [https://code> is fully expanded, escaping characters can sometimes be trickydistribution. To circumvent this problem, ConTeXt defines a environment called <code>\startluacode contextgarden.net/current/context/latest/tex/context/base/mkxl/luat-ini.lmt luat-ini. \stopluacodelmt]: </code><pre>userdata = userdata or { } -- for users (e. This sets the catcodes to what one would expect in Luag. Basically functions etc)thirddata = thirddata or { } -- only for third party modulesmoduledata = moduledata or { } -- only for development teamdocumentdata = documentdata or { } -- for users (e.g. raw data)parametersets = parametersets or { } -- experimental for team<code/pre>\</code> has its usual TeX meaning If your module, environment, the catcode of everything else or document is set going to be used by otherpeople, you should create your own subnamespaces within these tables. So, for all practical purposes, we can forget about catcodes inside <code>\startluacode <pre>moduledata['mymodule'] = { }mm = moduledata.mymodulefunction mm.. \stopluacodemainfunction() -- do stuffend</pre></code> == Undefined Commands in Lua Comments == Lua code invoked inside TeX doesn’t allow TeX undefined commands ''even inside comments''. The above two examples can be written as
-- A Lua comment tex.print("This is printed.") local t = {1,2,3,4} tex.print("length " .. #t)\undefinedcommandfromme
The contents of To get the sample above working (as [https://www.mail-archive.com/ntg-context@ntg.nl/msg103892.html explained by Hans in a NTG-context thread from jan. 2023 entitled “Minor bug in Lua or ConTeXt”]), you would need a fallback definition: <codetexcode>\ifdefined\undefinedcommandfromme \else \let\undefinedcommandfromme\startluacoderelax \fi</codetexcode> {{cmd|undefinedcommandfromme}} gets only defined (as {{cmd|relax}}, to do nothing), if and only if it is undefined. = Calling TeX from Lua = Being a topic on itself, pages are dedicated:* '''[[CLD|ConTeXt Lua Documents]]''', or CLD, are way to access TeX from inside Lua scripts.A page give clues about [[CLD_passing_variables|passing variables]] within CLD (2018). * [[Lua|Wiki page dedicated to Lua]]** [[Extensions to the Lua I/O library]]** [[String manipulation]]** [[Table manipulation]] = Putting stuff in your TeX document from Lua = == Simple printing: context(), tex.print(), and tex.sprint() ==Use <code>\stopluacodecontext(…)</code>, like the argument of for most things. It is equivalent to <code>\ctxluatex.print(string.format(…))</code> are fully expanded. '''This mean that even the Lua comments should be valid TeX statements!''' For example,so
name = "Jane"date = "today"context("Hello %s, how are you %s?", name, date)-- \undefinedBecomes 'Hello Jane, how are you today?'
will give an error because when TeX expands the contents, it encounters <code>\undefined</code> which is an undefined TeX macro. This error can be avoided by using <code>\type{\undefined}</code> or <code>\\undefined</code>. In general, the <code>\startluacode</code> ... <code>\stopluacode</code> environment is meant for moderately sized code snippets. For longer Lua code, it is more convenient to write the code in a separate Lua file and then load it using Lua's <code>dofile(...)</code> function.
ConTeXt also provides More primitively, you have <code>tex.print()</code> and <code>tex.sprint()</code>. Either one can take as an argument either a Lua function to conveniently write to number of strings, or an array of strings, and will then insert the strings into the TeX stream. The function only difference is called that <code>contexttex.print()</code> treats each string as a separate input line, while <code>tex...sprint()</code> and it is equivalent to doesn't. So the following lines <codetexcode>\ctxlua{tex.print(string"a", "b")}\ctxlua{tex.formatprint(...){"a", "b"})}</texcode> are both interpreted by TeX as <texcode>ab</texcode> but when we use <code>tex. sprint</code> instead, either of the following
Using the above, it is easy to define TeX macros that pass control to Lua, do some processing in Lua, and then pass the result back to TeX. For example, a macro to convert a decimal number to hexadecimal can be written simply, by asking Lua to do the conversion.
\def\TOHEX#1{\ctxlua{contexttex.sprint("\%Xa",#1"b")}}\TOHEXctxlua{35tex.sprint({"a", "b"})}
The percent sign had to will be escaped because read by TeX as <codetexcode>\ctxluaab</codetexcode> assumes TeX catcodes without any space in between. Sometimes, escaping arguments can be difficult; instead == Context commands == Most commands that you would type with a backslash in plain ConTeXt, it you can be easier to define a access from Lua function inside with <code>\startluacode .context.. \stopluacode</codeem> and call it using command<code/em>\ctxlua</code>. For example, a macro that takes a comma separated list of Unadorned strings and prints a random item can be written end up in TeX as arguments in curly braces; Lua tables end up in TeX as paramater blocks in square brackets. The following two pieces of code are equivalent:
userdata = userdata or context.chapter({first}, "Some title") math context.randomseedstartcolumns( os{n = 3, rule = "on"}) context("Hello one") context.timecolumn() context("Hello two") function userdata context.randomcolumn(...) context("Hello three") context(arg[math.randomstopcolumns(1, #arg)]) end
\def\CHOOSERANDOM#1% {\ctxlua{userdata.random(#1)}}</texcode>
I could have written For a wrapper so that fuller account of the context.commands, see the function takes a list [http://www.pragma-ade.nl/general/manuals/cld-mkiv.pdf ConTeXt Lua document] manual. It is old, but most of words and chooses a random word among themit still applies. For an example One final note: arguments can also be specified in the form of such a conversionnested functions. Because LuaTeX evaluates the deepest-nested argument first, see this may cause the <emcode>sorting a list of tokenscontext()</emcode> page calls to be evaluated in the wrong order. For more on this, see the article on [[CLD|ConTeXt Lua documents]], and also, again, the [http://Luatexwww.bluwikipragma-ade.comnl/general/gomanuals/Sort_a_token_list LuaTeX wikicld-mkiv.pdf CLD manual]. = Passing arguments and buffers: ConTeXt commands that hook into Lua =
In the above== Making \command{arg1}{arg2} hook into Lua ==First, I created define a name space called <code>userdata</code> and defined the Lua function <code>random</code> in that name space. Using a name space avoids clashes with the Lua functions defined in LuaTeX and ConTeXt.:
In order to avoid name clashes<texcode>\startluacode -- remember, ConTeXt also defines independent name spaces of Lua instancesusing the userdata namespace prevents conflicts userdata = userdata or {} function userdata. They are surroundwithdashes(str) context("--" .. str .. "--") end\stopluacode</texcode>
Thus, for example, instead of <code>\ctxlua</code> and <code>\startluacode ... \stopluacode</code>, the <code>user</code> instance can be accessed via the macros <code>\usercode</code> and <code>\startusercode ... \stopusercode</code>. In instances other than <code>isolated</code>, all the Lua functions defined by ConTeXt (but not the inbuilt Lua functions) are stored in a <code>global</code> name space. In the <code>isolated</code> instance, all Lua functions defined by ConTeXt are hidden and cannot be accessed. Using these instances, we could write the above <code>\CHOOSERANDOM</code> macro as follows
Since I defined the function <code>random</code> in the <code>user</code> instance of Lua, I did not bother to use a separate name space for the function. The Lua functions <code>os.time</code>, which is defined by a LuaTeX library, and <code>context</code>, which is defined by ConTeXt, needed to be accessed through a <code>global</code> name space. On the other handNext, we define the <code>math.randomseed</code> function, which is part start command of Lua, could be accessed as is. our custom buffer:
A separate Lua instance also makes debugging slightly easier. With <code>\ctxlua</code> the error message starts with
! LuaTeX error <main ctx instance>\def\startverynarrow% {\dostartbuffer [verynarrow] % buffer name [startverynarrow] % command where buffer starts [stopverynarrow]} % command where buffer ends % also:command invoked when buffer stops
With Lastly, we define the {{cmd|stopverynarrow}} command such that it passes the recently-complated buffer to our <code>\usercodeverynarrow</code> the error message starts withLua function:
! LuaTeX error <private user instance>:\def\stopverynarrow {\ctxlua {userdata.verynarrow(buffers.getcontent('verynarrow'))}}
This makes And that's it easier to narrow down the source ! The rest of errorthis article will consist of examples.
Normally, it is best to define your Lua functions in the <code>user</code> name space. If you are writing a module, then define your Lua functions in the <code>third</code> instance and in a name space which is the name of your module. In this article, I will simply use the default Lua instance, but take care to define all my Lua functions in a <code>userdata</code> name space.= Examples =
Now that we have some idea of how to work with LuaTeX, let's look at some examples.== Arithmetic without using an abacus ==
= Arithmetic without using an abacus =''This example demonstrates writing simple commands that invoke \ctxlua.''
The tedious (but faster!) way to achieve this This is to simply type easy in LuaTeX. Once a Lua instance starts, TeX does not see anything until the whole table by handLua instance exits. It is however natural to want to So, we can write this table as a the loopin Lua, and compute simply print the valuesthat we would have typed to the TeX stream. When the control is passed to TeX, TeX sees the input as if we had typed it by hand. A first ConTeXt implementation using This is the Lua code for the recursion level might beabove table:
We only needed to add three <code>\expandafter</code>s to make the naive loop work. Nevertheless, finding the right location of <code>\expandafter</code> can be frustrating, especially for a non-expert.
By contrast, in LuaTeX writing loops is easy. Once a Lua instance starts, TeX does not see anything until the Lua instance exits. So, we can write the loop in Lua, and simply print the values that we would have typed to the TeX stream. When the control is passed to TeX, TeX sees the input as if we had typed it by hand. Consequently, macro expansion is no longer an issue. For example, we can get the above table by:
<texcode>
The Lua functions such as <code>context.bTABLE()</code> and <code>context.bTR()</code> are just abbreviations for running <code>context ("\\bTABLE")</code>, <code>context("\\bTR")</code>, etc. See the [http://www.pragma-ade.com/general/manuals/cld-mkiv.pdf ConTeXt Lua document] manual for more details about such functions. The rest of the code is a simple nested for-loop that computes the sum of two dice. We do not need to worry about macro expansion at all!== Parsing input without exploding your head ==
= Parsing input without exploding your head =As an example, let's consider typesetting chemical molecules in TeX. Normally, molecules should be typeset in text mode rather than math mode. If we want :H<sub>3</sub>SO<sub>4</sub><sup>+</sup>,we must type :<code>H{{cmd|low|{3}}}SO{{cmd|lohi|{4}}}{{{cmd|textplus}}}</code>,but we'd much rather type:{{cmd|molecule|{H_3SO_4^+}}}.
In order to get around the weird rules of macro expansionSo, writing we need a parser in TeX involves function that can take a lot of macro jugglery string like that, parse it, and catcode trickeryturn it into the appropriate TeX code. It is LuaTeX includes a black artgeneral parser based on PEG (parsing expression grammar) called [http://www.inf.puc-rio.br/~roberto/lpeg/lpeg.html lpeg], one and it makes writing little parsers positively joyful. (Once you've got the knack of it, at least.) For example, the biggest mysteries of TeX for ordinary usersabove {{cmd|molecule}} macro can be written as follows.
As an example, let's consider typesetting chemical molecules in TeX. Normally, molecules should be typeset in text mode rather than math mode. For example, <context>H\low{2}SO\lohi{4}{--}</context>, can be input as <code>H\low{2}SO\lohi{4}{--}</code>. Typing so much markup can be cumbersome. Ideally, we want a macro such that we type <code>\molecule{H_2SO_4^-}</code> and the macro translates this into <code>H\low{2}SO\lohi{4}{--}</code>. Such a macro can be written in TeX as follows.
\def\chemhigh#1% -- we will put our molecule function in the userdata namespace. userdata = userdata or {\ifvoid\chemlowbox \high{{\switchtobodyfont[small]#1}}% \else \lohi{\box\chemlowbox} {{\switchtobodyfont[small]#1}} \fi}
\def\finishchem%-- The formatting functions into which the captured {\ifvoid\chemlowbox\else -- superscript/subscript blocks will be fed \lowlocal formatters = {\box\chemlowbox} \fi}
\unexpanded\def\molecule% {\bgroup \catcode`\_=\active \uccode`\~=`\_ \uppercase{\let~\chemlow}% \catcode`\^=\active \uccode`\~=`\^ \uppercase{\let~\chemhigh}% \dostepwiserecurse {65}{90}{1} {\catcode \recurselevel = \active function formatters.low(one) return string.format("\uccode`\~=\recurselevel \uppercaselow{\edef~{\noexpand\finishchem \rawcharacter{\recurselevel}}}}% \catcode`\-=\active \uccode`\~=`\- \uppercase{\def~{--}s}% ", one) \domolecule }% end
This monstrosity is a typical TeX parserfunction formatters. Appropriate characters need to be made active; occasionallylowhigh(one, <code>two) return string.format("\lccode</code> and <code>\uccode</code> need to be set; signaling tricks are needed (for instancelohi{%s}{%s}", one, checking if <code>\chemlowbox</code> is void); and then magic happens (or so it seems to a flabbergasted usertwo). More sophisticated parsers involve creating finite state automata, which look even more monstrous.end
With LuaTeX, things are differentfunction formatters. LuaTeX includes a general parser based on PEG highlow(parsing expression grammarone, two,three) called [http://www return string.inf.puc-rio.br/roberto/lpeg/lpeg.html lpeg]. This makes writing parsers in TeX much more comprehensible. For exampleformat("\\lohi{%s}{%s}", one, the above <code>\molecule</code> macro can be written astwo)end
<texcode>-- These are the characters we may encounter-- The `/` means we want to expand + and - to \startluacodetextplus c.q. \textminus;-- this substition is not instant, but will take place inside the first -- surrounding lpeg.Cs() call.local plus = lpeg.P("+") / "\\textplus "userdata local minus = userdata or lpeg.P("-") / "\\textminus "local character = lpeg.R("az", "AZ", "09") -- R is for 'range'local subscript = lpeg.P("_") -- P is simply for 'pattern'local superscript = lpeg.P("^")local leftbrace = lpeg.P("{")local rightbrace = lpeg.P("}")
local lowercase = lpeg.R("az")local uppercase = lpeg.R("AZ")local backslash = lpeg.P("\\")local csname = backslash * lpeg.P(1) * (1-backslash)- a ^0or _ affects either a single character, or a brace-delimitedlocal plus = lpeg-- block.P("+") / "\\textplus "local minus = lpegWhichever it is, call it `content`.P("-") / "\\textminus "local digit = lpeg.R("09")local sign single = character + plus + minuslocal cardinal = digit^1local integer = sign^0 * cardinallocal leftbrace = lpeg.P("{")local rightbrace multiple = lpeg.P("}")local nobrace = 1 - (leftbrace + rightbrace)local nested = lpeg.P {leftbrace * (csname + sign + nobrace + lpeg.V(single^1))^0 * rightbrace}local any content = lpeg.P(1)single + multiple
local lowhigh = lpegfunction thirddata.Ccmolecule("\\lohi{%s}{%s}"string) * subscript * content * superscript -- * content / `:match` returns the matched string.formatOur patternlocal highlow = lpeg -- `moleculepattern` should match the entire input string.Cc("\\hilo{%s}{%s}") Any * superscript -- * content performed* subscript * content / stringsubstitutions are retained.formatlocal low = lpeg(`.CcCs("\\low{%s}") ` performs a * subscript -- * content / stringpreviously defined substitution.format)local high = lpeg.Cc -- * `context("\\high{%s}") * superscript * content / ` inserts the resulting string.formatinto the stream, ready forlocal justtext -- = (1 - somescript)^1TeX to evaluate.local parser = lpeg.Cscontext(moleculepattern:match(csname + lowhigh + highlow + low + high + sign + anystring)^0)end
userdata.moleculeparser = parser \stopluacode
function userdata\def\molecule#1{\ctxlua{thirddata.molecule(str"#1") return parser:match(str)end\stopluacode}}
This is more verbose than the TeX solution, but is easier to read Quite terse and write. With a proper readable by parserstandards, I do not have to use tricks to check if either one or both <code>_</code> and <code>^</code> are present. More importantly, anyone (once they know the lpeg syntax) can read the parser and easily understand what isn't it does. This is in contrast to the implementation based on TeX macro jugglery which require you to implement a TeX interpreter in your head to understand.?
Writing macros ''This example demonstrates defining a custom {{cmd|start}}…{{cmd|stop}} buffer that manipulate verbatim text involve catcode finesse that only TeX wizards can mastergets processed through Lua in its entirety.''
Consider a simple example. Suppose we want to write an environment <code>\{{cmd|startdedentedtyping</code> ... <code>\}} … {{cmd|stopdedentedtyping</code> }} that removes the indentation of the first line from every line. Thus, the output of ...…
... … should be the same as the output of ...…
... … even though the leading whitespace is different.
I don't even know how to write Defining an environment in TeX that will remove removes the leading spaces but leave leavesother spaces untouchedis complicated. On the other hand, once we capture the contents of the environment, removing the leading indent or ''dedenting'' the content in Lua is easy. Here is a Lua function that uses lpegsimple stringsubstitutions.
local newline = lpeg.P("\n\r") + lpeg.P("\r\n") + lpeg.P("\n") + lpeg.P("\r") local splitter = lpeg.Ct(lpeg.splitat(newline)) local lines = lpegstring.matchsplitlines(splitter, content)
indent = lpeg.P(indent) local any pattern = lpeg'^' ..Cs(1) local parser = indent * lpeg.C(any^0)
<texcode>\unprotect\def\startdedentedtyping% Here is the code for defining the {\begingroup \obeyspaces \obeylines \long\def\dostartdedentedtyping##1\stopdedentedtyping% {\ctxluacmd|startdedentedtyping}} … {userdata.dedentedtyping(\!!bs \detokenize{##1} \!!es)}% \endgroupcmd|stopdedentedtyping}% \dostartdedentedtyping}\protect</texcode>The above macro works for simple cases, but there are some limitations. For example, there is an extra space of <code>\n</code> in the output. This macro will also fail if the contents have unbalanced braces (try removing the <code>}</code> from the example).pair:
A more robust solution is to use ConTeXt's built in support for buffers. Using buffers, the above macro can be written as <texcode>% Create an environment that stores everything
Unlike MkII, where the contents of a buffer were written to an external file, in MkIV buffers are stored in memory. Thus, with LuaTeX is really simple to manipulate verbatim text: pass the contents of the environment to Lua; use Lua functions to do the text-manipulation; and in Lua call [[cld|<code>context.something()</code>]] functions to produce the ConTeXt code you want.
= Conclusion =That's all. Finally, we will go into a little more detail on how TeX and Lua communicate with each other.
LuaTeX is removing many TeX barriers: using system fonts, reading and writing Unicode files, typesetting non-Latin languages, among others. However, the biggest feature of LuaTeX is the ability to use a high-level programming language to program TeX. This can potentially lower the learning curve for programming TeX.== Other examples ==
→Undefined Commands in Lua Comments: Fix a broken link. And add enough information to be able to re-fix it easily. (I guess this last part could go in a footnote reference, but I am not sure how to do that properly…)
There are two main ways to execute Lua code in a ConTeXt document: The command {{cmd|ctxlua}}, and the environment {{cmd|startluacode}}…{{cmd|stopluacode}}. Both are wrappers around the LuaTeX primitive {{cmd|directlua}}, which you should never need to use. In general, you will define a function inside a {{cmd|startluacode}} block, and then define a TeX command that calls the function using {{cmd|ctxlua</code>, especially because {{cmd|ctxlua}} has a few idiosyncracies. <blockquote>The main thing about Lua code in a TeX document is this: the code is expanded by TeX ''before'' Lua gets to it. '''This means that all the Lua code, even the comments, must be valid TeX!''' A string like {{cmd|undefined}} will cause an immediate failure.</blockquote> = Introduction =Calling a bit of Lua inline: {{cmd|ctxlua}} == The command {{cmd|ctxlua}} is for short inline snippets of Lua, suchas
<texcode>
</texcode>
<texcode>
\def\DIVIDE#1#2ctxlua {-- A Lua comment tex.print("This is not printed")}\directluactxlua {% A Tex comment tex.print(#1/#2"This is printed")}}
</texcode>
= Interaction between TeX = Calling a lua function with {{cmd|cldcontext}} and Lua get the return ==
<texcode>
\directlua%startluacode {tex -- The unknown command \undefined will cause this entire block to fail.print -- Print a countdown '10, 8, …, 0!' -- `..` is Lua for string concatenation for i = 10, 2, -2 do context(i .. ", ") end context("Depth 1 0!") -- \\directlua{texpar is equivalent to a blank line in the input -- (Notice the escaped backslash: TeX won't mind the above comment.print) context.par('Depth 2')} -- Look! we can use # and $ with impunity! context("Unless we print them, then we must \\#\\$\\& print the escape characters, too.")}\stopluacode
</texcode>
<texcode>
\ctxluastartluacode {-- A Lua commentinclude the file my-lua-lib.lua tex.printrequire("This is not printedmy-lua-lib")}\stopluacode
</texcode>
<texcode>
\ctxluastartluacode {local -- if userdata doesn't exist yet, create it userdata = userdata or {1,2,3,4} tex -- define a shorter synonym u = userdata -- create my custom function inside the userdata namespace function u.printmyfunction("length " .. ) -- do stuff end\string#t)}stopluacode
</texcode>
<texcode>
\starttext
\startluacode
\stopluacode
Hello
\ctxlua{--\undefinedcommandfromme}
\stoptext
</texcode>
<texcode>
\startluacode
\stopluacode
</texcode>
<texcode>
</texcode>
<texcode>
\startluacode
\stopluacode
<texcode> \CHOOSERANDOMchapter[first]{"Some title} \startcolumns[n=3, rule=on] Hello one", " \column Hello two", " \column Hello three"} \stopcolumns
</texcode>
Then define the TeX command that expands to a {{cmd| |- | '''user''' | a private user instance |- | '''third''' | third party module instance |- | '''module''' | ConTeXt module instance |- | '''isolated''' | an isolated instance |ctxlua}}call:
<texcode>
\startusercodedef\surroundwd#1% math {\ctxlua{userdata.randomseed( global.os.timesurroundwithdashes([==[#1]==]) )}}</texcode> ''NB'': quoting with <code>[==[#1]==]</code> function random([http://www.lua.org/manual/5.2/manual.html#3.1 long strings]) globalworks just like <code>"#1"</code> in most cases, but in addition it is robust against <code>#1</code> containing the quotation mark<code>"</code> which would terminate the Lua string prematurely.Inside {{cmd|protect}}…{{cmd|unprotect}} the macros {{cmd|!!bs}}and {{cmd|!!es} are at your disposition.They are equivalent to <code>[===[</code> and <code>]===]</code> and --being single tokens to TeX -- parsed faster.context(argSee [mathhttp://repo.or.random(1, cz/w/context.git/blob/refs/heads/origin:/tex/context/base/luat-ini.mkiv#arg)l174 <code>luat-ini.mkiv</code>].) end== Making {{cmd|startenv}}…{{cmd|stopenv}} hook into Lua ==The first job is, as ever, to have the Lua function at the ready<texcode>\stopusercodestartluacode userdata = userdata or {}
function userdata.verynarrow(buffer) -- equivalent to \def\CHOOSERANDOM#1%startnarrower[10em] context.startnarrower({\usercode{random"10em"}) context(buffer) context.stopnarrower(#1)}} end\stopluacode
</texcode>
<texcode>
</texcode>
<texcode>
</texcode>
Doing simple arithmetic in TeX can be extremely difficult, as illustrated by the division macro in the introduction. With Lua, simple arithmetic becomes trivial. For example, if you want a macro to find the cosine of an angle (in degrees), you can write
<texcode>
\def\COSINE#1%
$\pi = \ctxlua{context(math.pi)}$
</texcode>
or , if you want less precision (notice the percent sign is escaped):
<texcode>
$\pi = \ctxlua{context("\%letterpercent.6f", math.pi)}$</texcode>Notice that the percent sign is escaped with letterpercent. === mathexpr with LMTX === In LMTX there is a new way to use calculated expressions with mathexpr through ([https://github.com/contextgarden/context-mirror/blob/7fd782dace8f90e7e032ca8f449f8ca4eada450b/doc/context/sources/general/manuals/math/math-fun.tex math-fun]). Some examples are: <texcode>$ \pi = \mathexpr[.40N]{pi} $$ \pi = \mathexpr[.80N]{sqrt(11)} $$ \pi = \decimalexpr[.80N]{sqrt(11)} $$ \pi = \decimalexpr{sqrt(11)} $$ c = \complexexpr{123 + new(456,789)}$
</texcode>
== Loops without worrying about expansion ==
''This example demonstrates using Lua to write a quasi-repetitive piece of ConTeXt code.'' Loops in TeX are tricky , because macro assignments and macro expansion interact in strange ways. For example, suppose we want to typeset a table showing the sum of the roll of two dice and want the output to look like this:
<context source="yes">
\setupcolors[state=start]
</context>
<texcode>
\bTABLE \bTR \bTD $(+)$ \eTD \dorecurse{6} {\bTD \recurselevel \eTD} \eTR \dorecurse{6} {\bTR \bTD \recurselevel \eTD \edef\firstrecurselevel{\recurselevel} \dorecurse{6} {\bTD \the\numexpr\firstrecurselevel+\recurselevel \eTD}% \eTR} setupcolors[state=start]\eTABLE</texcode> HoweversetupTABLE[each][each][width=2em, this does not work as expectedheight=2em, yielding all zeros. A natural table stores the contents of all the cellsalign={middle, before typesetting it. But it does not expand the contents of its cell before storing them. So, at the time the table is actually typeset, TeX has already finished the <code>\dorecurse</code> and <code>\recurselevel</code> is set to 0. The solution is to place <code>\expandafter</code> at the correct location(s) to coax TeX into expanding the <code>\recurselevel</code> macro before the natural table stores the cell contents. The difficult part is figuring out the exact location of <code>\expandafter</code>s. Here is a solution that works: <texcode>\bTABLE \bTR \bTD $(+)$ \eTD \dorecurse{6middle} ] {\expandafter \bTD \recurselevel \eTD} setupTABLE[r][1][background=color,backgroundcolor=gray] \eTR \dorecurse{6} {\bTR \edef\firstrecurselevel{\recurselevel} \expandafter\bTD \recurselevel \eTD \dorecurse{6} {\expandafter\bTD \the\numexpr\firstrecurselevel+\recurselevel \relax \eTD} \eTR} \eTABLE </texcode>setupTABLE[c][1][background=color,backgroundcolor=gray]
\startluacode
context.bTABLE()
</texcode>
''This example demonstrates parsing simple ASCII notation with Lua's lpeg parser.''
<texcode>
\newbox\chemlowbox \def\chemlow#1% {\setbox\chemlowbox \hbox{{\switchtobodyfont[small]#1}}} startluacode
function formatters.high(one) return string.format("\def\domolecule#1high{#1\finishchem\egroup%s}", one)</texcode>end
-- These are our top-level elements: non-special text, of course, and-- blocks of superscript/subscript/both.-- lpeg.Cs(content) does two things:-- (1) not all matches go into the `/ function` construction; only-- *captures* go in. The C in Cs stands for Capture. This way, -- the superscript/subscript mark gets discarded.-- (2) it expands plus/minus before they go into the formatter. The-- s in Cs stands for 'substitute in the replacement values, if any'local text = single^1local low = subscript * lpeg.Cs(content) / formatters.lowlocal high = superscript * lpeg.PCs("_"content) / formatters.highlocal lowhigh = subscript * lpeg.Cs(content) * superscript = * lpeg.PCs("^"content) / formatters.lowhighlocal somescript highlow = superscript * lpeg.Cs(content) * subscript + superscript* lpeg.Cs(content) / formatters.highlow
-- Finally, the root element: 'moleculepattern'local content moleculepattern = lpeg.Cs(csname (lowhigh + highlow + nested low + sign high + anytext)^0)
\defstarttext \molecule#1% {Hg^+}, \ctxluamolecule{SO_4^{userdata.molecule("#1")2-}}\stoptext</texcode>
== Manipulating verbatim text for dummies ==
<texcode>
\stopdedentedtyping
</texcode>
<texcode>
\stoptyping
</texcode>
<texcode>
\startluacode
-- Initialise Initialize a userdata namespace name space to keep our own functions in.
-- That way, we won't interfere with anything ConTeXt keeps in
-- the global namespacename space.
userdata = userdata or {}
function userdata.dedentedtyping(content)
local indent = string.match(lines[1], '^ +') or ''
for i=1,#lines do
lines[i] = lpegstring.matchgsub(parser, lines[i],pattern,"")
end
-- does.
end
\stopluacode</texcode>The only hard part is capturing the content of the environment and passing it to Lua. As explained in [[Inside_ConTeXt#Passing_verbatim_text_as_macro_parameter|Inside ConText]], the trick to capturing the content of an environment verbatim is to ensure that spaces and newlines have a catcode that makes them significant. This is done using <code>\obeyspaces</code> and <code>\obeylines</code>. Using that trick, we can write this macro as
% between \startdedentedtyping and \stopdedentedtyping
% in a buffer named 'dedentedtyping'.
\def\stopdedentedtyping
{\ctxlua
{userdata.dedentedtyping(buffers.getcontent('dedentedtyping'))}}
</texcode>
* [[Calculations_in_Lua|Calculations in Lua]] (warning date 2012)* [[LPeg|Writing a parser with LPeg]] (Lua Parsing Expression Grammars)* [[Random|Random numbers]] in ConTeXt and MetaPost* [[SQL|An example with SQL database]]* [[Pascal's Triangle]] = In this articledetail: the interaction between TeX and Lua = To a first approximation, I have mentioned only one aspect of programming the interaction between TeX and Lua is straightforward. When TeX: macros that manipulate their (i.e., the LuaTeX engine) starts, it loads the input file in memory and processes it token by token. When TeX encounters {{cmd|directlua}}, it stops reading the file in memory, <em>fully expands the argument of {{cmd|directlua}}</em>, and passes the control to a Lua instance. The Lua instance, which runs with a few preloaded libraries, processes the expanded arguments of {{cmd|directlua}}. This Lua instance has a special output some text stream which can be accessed using <code>tex.print(…)</code>. The function <code>tex.print(…)</code> is just like the Lua function <code>print(…)</code> except that <code>tex.print(…)</code> prints to a <em>TeX stream</em> rather than to the main standard output. When the Lua instance finishes processing its input, it passes the contents of the <em>TeX stream</em> back to TeX. Many other kinds <ref>The output of manipulations are possible: LuaTeX provides access <code>tex.print(…)</code> is buffered and not passed to TeX boxesuntil the Lua instance has stopped.</ref> TeX then inserts the contents of the <em>TeX stream</em> at the current location of the file that it was reading; expands the contents of the <em>TeX stream</em>; and continues. If TeX encounters another {{cmd|directlua{{cmd|, token liststhe above process is repeated. As an exercise, dimensionsimagine what happens when the following input is processed by LuaTeX. The answer is in the footnotes. <ref>In this example, gluestwo different kinds of quotations are used to avoid escaping quotes. Escaping quotes inside {{cmd|directlua}} is tricky. The above was a contrived example; if you ever need to escape quotes, catcodesyou can use the {{cmd|startluacode}}…{{cmd|\stopluacode{{cmd| syntax.</ref> <texcode>\directlua% {tex.print("Depth 1 \\directlua{tex.print('Depth 2')}")}</texcode> For more on this, direction parameters, math parameters, etcsee the [http://wiki.luatex.org/index. The details can be found in php/Writing_Lua_in_TeX] article on the [http://wwwwiki.luatex.org/documentationindex.html php/Main_Page LuaTeX manualwiki].
= Notes =
<references />
{{note | This article is originally based on [https://www.tug.org/members/TUGboat/tb30-2/tb95mahajan-luatex.pdf this TugBoat article ]. Feel free to modify it.}}
[[Category:Programming and Databases]]
