# What does \luaescapestring do for us?

It seems that all TeX command are expanded into unexpandable tokens (say, TOKENS1) and these token are converted into some other tokens (say, TOKENS2). For example

\directlua{
local var = [[\luaescapestring{\TeX}]]
print("*****" .. var .. "*****")}
\bye


when finishing excuting \luaescapestring{\TeX}, what we get is this

  T\\kern -.1667em\\lower .5ex\\hbox {E}\\kern -.125emX


Why does \luaescapestring do this work and why we need this command in LuaTeX?

• According to the LuaTeX reference, "this primitive converts a TeX token sequence so that it can be safely used as the contents of a Lua string: 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. The token sequence is fully expanded." – Paulo Cereda Apr 23 '13 at 17:34
• @Paulo Cereda I read the manual, but don't know how to apply this and don't know why we need this. – Lucas Li Apr 24 '13 at 0:49
• Please, don't get me wrong on my quotation from the manual. :) I was just pointing at the description. Patrick's answer is very detailed and it will surely help us all. :) – Paulo Cereda Apr 24 '13 at 0:58
• @PauloCereda oh, I don't mean that. After reading the manual, I said to myself: I can't understand that, so I have to come here and ask this question :-) – Lucas Li Apr 24 '13 at 2:58

## 1 Answer

To answer the second question (first question later):

Why we need this command in LuaTeX?

Imagine the following document:

\documentclass{article}
\newcommand\foo[1]{%
\directlua{tex.sprint("#1") }}
\begin{document}
\foo{bar}
\end{document}


\foo{bar} is expanded to \directlua{tex.sprint("bar")} which outputs bar.

Now let's change the macro call:

\documentclass{article}
\newcommand\foo[1]{%
\directlua{tex.sprint("#1") }}
\begin{document}
\foo{"baz"}
\end{document}


Now \foo{"baz"} gets expanded to \directlua{tex.sprint(""baz"") } which is not valid Lua syntax. To protect us from users who want to print quotation marks ", one can either check the argument manually (which tends to be very very difficult) or you can rely on the magic of \luaescapestring{...} - in LaTeX it's prefixed with luatex:

\documentclass{article}
\newcommand\foo[1]{%
\directlua{tex.sprint("\luatexluaescapestring{#1}") }}
\begin{document}
\foo{"baz"}
\end{document}


now it expands to something like this: \directlua{tex.sprint("\"baz\"")}.

To answer the first question:

Why does \luaescapestring do this work?

\TeX is defined in plain TeX:

\def\TeX{T\kern-.1667em\lower.5ex\hbox{E}\kern-.125emX}


so the expansion of TeX is T\kern-.1667em\lower.5ex\hbox{E}\kern-.125emX which contains \k, \l, \h, which are control codes in Lua's strings (or could be). Therefore \luaescapestring adds a backslash to have \\k, \\l and \\h as the string source. Now you have tricked the system by using [[...]] to define the string, and in this double bracket string the backslashes don't do any harm. So in your case you didn't have to use \luaescapestring.

• Thanks for your wonderful explaination. Since I read your code last time, I am curious about the \luaescapestring and don't know why we need its help. Now, I understand that :-) – Lucas Li Apr 24 '13 at 0:52