How is \unexpanded defined?
\unexpanded
is an ε-TeX primitive. If you do
\documentclass{article}
\begin{document}
\show\unexpanded
\end{document}
you'll get in the log:
> \unexpanded=\unexpanded.
l.3 \show\unexpanded
which seems to be redundant information but actually tells you that it is a primitive control sequence. Primitives are listed in the TeX Book or TeX by Topic but you won't find \unexpanded
there because it is an ε-TeX primitive. It is described in the e-TeX manual, though:
\unexpanded<general text>
.The expansion is the token list
<balanced text>
.[...]
When building an expanded token list, the tokens resulting from the expansion of
\unexpanded
are not expanded further (this is the same behaviour as is exhibited by the tokens resulting from the expansion of\the<token>
variable in both TeX and ε-TeX).
As cgnieder's excellent answer says, \unexpanded
is a primitive of e-TeX, that is, an extension of the original TeX language. Primitives don't have a definition, they're commands directly understood by the engine. Some of them are expandable, that is, they don't reach TeX's “stomach” because they are expanded just like macros (the same happens to the conditionals, for example); \unexpanded
is one of these macros.
It's a generalization of \noexpand
which, in the context of an \edef
or a \write
, has a null expansion but also the effect of making the next token unexpandable for the task at hand. Thus
\def\foo{something}
\def\baz{else}
\edef\x{\foo\noexpand\baz}
would be equivalent to
\def\x{something\baz}
With \unexpanded
you can protect from expansion in an \edef
(or \xdef
) or \write
an entire token list, without the need to prepend \noexpand
to all expandable tokens.
Since \unexpanded
follows the pattern
\unexpanded <general text>
it has an interesting feature. When TeX wants to expand it, it looks forward to find a <general text>
which is defined as
<filler> { <balanced text> <right brace>
and expands tokens to recognize a <filler>
and, eventually, the {
. A <filler>
is just an arbitrary sequence of \relax
and space tokens which are simply ignored. The {
is an explicit or implicit token of category code 1.
A consequence of this is that
\unexpanded\expandafter{\cs}
will cause the expansion of \cs
before the {
that starts the list of tokens which will not be expanded any more. Indeed, the definition of \expandonce
is
\newcommand{\expandonce}[1]{\unexpanded\expandafter{#1}}
Also \detokenize
(another expandable primitive of e-TeX) has the same properties.
Beware of the <filler>
: it can cause some unexpected effects under certain circumstances as shown in Get the lion to run in loops. Tersely