5 何时需要使用NewExpandableCommand?能否给一个最简单例子说明何为完全展开

发布于 2024-08-27 20:00:52

不理解NewExpandableDocumentCommand的用法和NewDocumentCommand的区别。
何为完全展开,下面是一个没测试出他们区别的MWE,希望得到一个非用NewExpandableDocumentCommand不可的使用情景.

这个链接也看的有点一头雾水url-difference

\documentclass[12pt]{article}
\usepackage{xparse}
\newcommand\foo{April Fool!}
\NewDocumentCommand{\barr}{}{\foo Ahahahaha!}
\NewDocumentCommand{\foobar}{}{\foo Ahahahaha! \barr}
\begin{document}
    \foo

    \barr

    \foobar

    \section{\foo}

    \section{\barr}

    \section{\foobar}

    \section{\foo,\barr}
\end{document}

查看更多

关注者
0
被浏览
719
雾月
雾月 2024-08-27
这家伙很懒,什么也没写!

你使用 \tableofcontents 然后查看 .toc 文件就能看到区别。可以再定义一个 expandable document cmd,放在 \section 里,再看看目录文件。

“展开”与上下文有关,需要区分“展开”和“执行”。“展开”是宏替换,把宏替换为其它东西。

在正常的上下文中,读入、展开、执行、输出这四个依次交替执行,这是一般情形。在所谓的“完全展开”的上下文中,比如 \expanded 的“参数”(也就是 latex3的 e 型展开),还有用 \write 把“参数”写入文件等等,这些参数都会被“展开”,但不会“执行”,“赋值”操作不会生效的。还有 f 型的展开,和 \csname \endcsname 之间的内容的展开。

与之相关的还有 protected 宏、robust 宏。前者不会在 e 型展开中被展开(但在正常的上下文中仍然会被展开)。后者是没有 protected 宏的时代为了阻止宏被展开的一个 trick。

interface3.pdf 中命令标有实心星号的可以在 e 型和 f 型中安全的展开,空心星号的可以在 e 型但不能在 f 型中安全的展开。

这些是下面要讲的内容的基础。

\NewDocumentCommand 定义的命令是 protected 宏,e 型展开不会展开它,所以写入文件时、做为 \expanded 的参数等情形,它都保持不变;而不是 protected 宏,比如 expandable document cmd,则会被替换为它的“替换文本”,这个替换是完全替换,也就是在此上下文中所有能被替换的都会替换,这种替换也就是“完全展开”。

要构造非得用 expandable document cmd 的情形,就比如在会展开而不会执行的上下文中,比如 \tl_set:Ne\str_set:Ne,然后用 \tl_show:N 查看它的值。你的例子只要把 \section 替换为 \tl_set:Ne 就好了。

另外,我们知道,latex3 除了有 int 类型,还有一种特殊的类型:flag,可以自己试试在 e 型展开中 \int_incr:N\flag_raise:N 有何区别。

2 个回答
Sagittarius Rover
Sagittarius Rover 2024-08-28
我要成为TikZ糕手/(ㄒoㄒ)/~~

Part0.基础知识汇总

section 0-1 脆弱命令(fragile command)与健壮(robust command)命令

该问题可谓是tse上最常被访问的问题之一,可见链接macros - What is the difference between Fragile and Robust commands? When and why do we need protect? - TeX - LaTeX Stack Exchange本部分的内容将总结自该回答。一个宏被处理的顺序是读入、展开(expand)执行(execute)、输出。下面是定义:

脆弱命令(Fragile Command)指的是在被展开时行为不正常,而在被执行时可以正常实现的命令。“A fragile command is one that does not behave properly when expanded, but not executed.”与之相对的,健壮命令(Robust Command)是指在展开和执行时均可以正常实现的命令。

这样的脆弱命令要正确执行,需要保证【在下一个token被展开之前】,某些命令被正确地执行,而健壮命令不需要这点。这样的命令只能在 normal(interleaved)mode中正确执行,而在只进行展开而不执行expansion-only contexts的某些情况下将导致错误。

“But in certain circumstances, most notably when writing to a file, TeX only expands things without executing them (the result will most probably be (re-expanded and) executed later when TeX reads the file back)”在某些情况下(例如执行tableofcontents时),TeX将只展开而不执行宏,此后将其写入辅助文件.toc后再次读入,以便生成正确的目录。因此下面可以使用\section并通过观察对比.toc文件来区分。

关于展开与执行的一些细节比较:

Expansion v.s. Execution

  • 展开仅仅只改变输入流(input stream),意味着将改变TeX引擎下一步将读取到什么内容
  • 执行指的是在展开之后TeX引擎将对读取到的内容进行剩下的操作

\input是可以展开的,TeX将会插入其他文件的内容

\def\kern命令由于均为TeX的原语(primitive),属于不可进一步展开的宏

**\show \def
> \def=\def.
**\show \kern
> \kern=\kern.

脆弱命令为什么会报错?这里直接借助回答里提供的例子来说明

\newcommand\foo[1]{\def\arg{#1}\ifx\arg\empty T\else F\fi}
%定义一个单参数命令`\foo`,当传入参数为空时返回`T`,否则返回`F`

在正常的文本模式(normal context)中,\foo{} => T \foo{stuff} => F;在执行过程中TeX读入\def并尝试将其展开,发现其不可展开之后,将执行\def,这时TeX吞入并移除了作为命令\def参数的\arg{#1};进一步TeX吞入了\ifx命令,尝试展开后执行,执行的时候吞入并移除了其参数\arg\empty,最终按照条件判断的逻辑输出结果TF

而在只进行展开的模式(expand-only context)中,相信我们已经知道会发生什么了,在吞入\def并展开失败之后,并不会执行\def吞入下一个token\arg,此时\arg可能并未被定义,然后TeX将会raise an error msg;如果宏\arg已经被定义(例如\def\arg{\abc}),那么在这种只展开的模式内,使用\foo{}将会得到\def \abc{},这将重新定义宏\abc,而这种操作远不是我们想实现的效果,脆弱命令在expand-only context并没有那么稳健。

section0-2 \protect命令的用法

从一个Eureka大神给出的例子出发,下面是一个体现fragile command的例子

\documentclass[12pt]{article}
\newcommand{\testA}{testA}
\NewDocumentCommand{\testB}{}{testB}
\NewExpandableDocumentCommand{\testC}{}{testC}
\begin{document}
\tableofcontents
\section{\testA}
\section{\protect\testA}
\section{\testB}
\section{\testC}
\end{document}

输出的.toc文件的结果形如:

\contentsline {section}{\numberline {1}testA}{1}{}%
\contentsline {section}{\numberline {2}\testA }{1}{}%
\contentsline {section}{\numberline {3}\testB }{1}{}%
\contentsline {section}{\numberline {4}testC}{1}{}%
上述使用\newcommand命令定义的\testA不是protected宏,因此在\section内部会被直接展开结果为testA;而是用\protect命令“保护”了\testA后其不会被展开;使用NewDocumentCommand定义的\testB属于\protected宏,因此不会被展开;而使用NewExpandableDocumentCommand定义的\testC\newcommnd的行为类似,均会在\section内部这一expand-only context中被展开,最后一起输出到.toc文件被二次读入后执行。在这种流程下,得到的pdf文件的四个section均正常显示,其差别仅在于在被\tableofcontents命令读入展开(但不执行)后写入.toc文件时是否展开上有所不同。

LaTeX2e的源码source2e.pdf\protect宏的工作原理如下:

  • 在正常文本模式中,\protect将会被展开至\relax,意味着什么事也不做
  • 在只进行展开的模式中,\protect将意味着\noexpand,该命令将阻止下一个token的展开,因此也就是保护了下一个命令命令,让其不被展开。这正好fix了脆弱命令在只进行展开模式下的脆弱性。

section0-3 plain TeX中的展开有关的命令

本部分部分参考自链接macros - When to use edef, noexpand, and expandafter? - TeX - LaTeX Stack Exchange,关于命令定义部分参考自The TeXBook chap20

  • \expandafter<token>:首先读取紧随其后的一个token,同时展开该token后的另一个token,同时将原先紧随其后的token添加到展开结果之前
  • \noexpand<token>:展开的结果为被展开的token本身,但该token如果是一个【按照TeX展开规则一般要被展开的命令】,则其含义此时等同于\relax
  • \csname<string>\endcsname:将<string>转换为宏\<string>,如果宏\<string>未被定义,则默认定义为\relax
  • \string<token> :将token转换为字符记号本身
  • \def\def<cs><parameter text>{<replacement text>}意为将控制序列定义为<replacement text>的内容;\gdef等同于命令\global\def,这使得命令在编组外可用
  • \edef\edef<cs><parameter text>{<replacement text>}意为在定义\cs完全地展开<replacement text>再将其作为控制系列\cs的定义;\xdef等同于\global\edef

\expanded是pdftex、xetex、luatex、uptex 等引入的,knuth tex、etex中都没有,其定义如下:
image.png
而查阅 The TeXBook中可以知道\message命令的定义如下(不需要双写##参数符号):
image.png

  • \message的行为与\edef类似, 完全展开所有参数后输出到终端, 唯一的区别是内部参数不需要双写(double)
  • \expanded的行为与\message类似,这也与下文中e型展开不需要双写一脉相承

下面学习一下上面链接中有关展开的小例子

\def\examplea{more stuff}
\def\exampleb{Some stuff First \expandafter\noexpand\csname examplea\endcsname}
\edef\examplec{Some stuff Second \expandafter\noexpand\csname examplea\endcsname}

\examplea %=> more stuff

\exampleb %=> Some stuff First

\examplec %=> Some stuff Second more stuff 
%(使用\edef在定义时即展开了\expandafter,此时\noexpand组织了\expandafter的展开,最终保留了\relax\examplea)

section0-4 latex3中不同展开方式

LaTeX3中,关于展开有以下不同的参数类型(由于我对expl3的也不熟悉,在这里浅浅搬运并翻译一下interface3.pdf中关于展开参数的几种类型的介绍):

image.png

  • c型展开,意为csname,是一种完全展开,是N的变体(要求传入参数为一个token),类似于\csname<cmd string>\endcsname,该命令将会对其内的字符串内容构建作为命令名称后展开,常用于拼接命令字符串,或通过传入命令的字符串形式而直接使用该命令
  • o型展开,与n类似,会读入一个token list的内容,但对其中的内容只进行一次展开
  • x (exhaustive expansion一展到底),同样地读入一个token list的内容,并将每一个参数递归地展开直至遇到不可展开的参数类型为止;与Plain-TeX的原语(primitive)中的命令\edef有相同的行为。当函数的参数带有x型参数时,该函数是不可展开的(not expandable)
  • e型展开,e型展开在大多数情况下的行为与x型展开完全相同,但与此对应的是TeX原语中的\expanded命令。参数变量(通常是#)在被使用时不需要双写(doubled)。当函数使用e型参数时,该函数可能可以展开的(expandable)
  • ffull expansion),fx型展开类似,均会对参数的宏进行递归展开,但会在展开至(遇到)第一个不可展开的 token 时停止。当传入的token list包含空格(space token)时,空格将会被吞下(gobble),并立刻停止,后面的内容保持不变,此后的其他空格也不会被移除。
  • Vv型参数意为变量的值(value of variable),该参数用于获取变量的内容而不用担心数据内在的TeX 结构V型参数对应N类型,要求传入一个token(例如\foo:V \MyVariable); 而v型参数对应n类型,要求传入一个token list(例如\foo:v {MyVariable})【关于expl3的问题点: V型展开和其他类型的展开的区别是什么,何时需要使用V型展开,何时需要使用x/e/f型展开】
\write,\csname \endcsname,以及\expandafter等命令均只会进行展开而不会执行

LaTeX3中关于f型展开/e型展开均不会进行执行操作,赋值操作也均不会生效

Part1.构造一个只能使用NewExpandableDocumentCommand的例子

关于构造的问题,首先感谢一下交流群友Eureka给出的下面的例子:

\documentclass[border=6pt]{standalone}
\usepackage{tikz}
\NewDocumentCommand\testA{m}{#1}
\NewExpandableDocumentCommand\testB{m}{#1}
\newcommand{\testC}[1]{#1}
\begin{document}
\begin{tikzpicture}
    %\draw[\testA{orange}] (0,0)--(1,1);   % fails
    \draw[\testB{magenta}] (0,0)--(1,1);  % works
    \draw[\testC{cyan}] (0,0)--(1,0);  % works
\end{tikzpicture}
\end{document}
% Thanks Eureka!
由于在tikznode命令选项(option)中的参数默认不会被展开,因此需要使用NewExpandableDocumentCommand才可正常使用(也可以直接使用\newcommand).

Part2.雾月指出使用.toc测试展开方式的差异

测试代码和效果如下

\documentclass[12pt]{article}
\newcommand\foo{April Fool!}
\NewDocumentCommand{\barr}{}{\foo\ Ahahaha!}
\NewDocumentCommand{\foobar}{}{\foo\ Ahaha! \barr}
\NewExpandableDocumentCommand{\expbarr}{}{\foo\ Ahaha!}
\NewExpandableDocumentCommand{\expfoobar}{}{\foo\ Ahaha! \barr}
\begin{document}
    \tableofcontents
    
    \section{\foo}
    
    \section{\barr}
    
    \section{\foobar}
    
    \section{\expbarr}
    
    \section{\expfoobar}
\end{document}

image.png

按照上面的回答,在正常的上下文中,读入展开执行输出这四个将依次交替执行。上述代码在生成初次编译生成.toc文件写入时执行的是e型展开【问题点:哪里的文档对此有介绍咧(?)】,而由于NewDocumentCommand定义是的protected宏,并不会被e型展开展开,因此从结果来看,命令\barr\foobar均不会被展开;而对于NewExpandableDocumentCommand定义的命令,由于其定义的宏不是protected宏,在写入.toc文件时执行e型展开则会被完全替换为宏的定义文本<replacement text>,这种替换也被称为“完全展开”。、

Part3.在latex3中e型展开与\int\flag对比

下面尝试使用latex3来构造例子,可见下面的文件

mwe.pdf

expand-mwe.zip

image.png

image.png

待补充,希望路过的各位uu不吝赐教批评指正(😭😭😭)

还挖了好多坑的,我还是一个个开新的提问尝试一下能否解决,会把新的问题移到这里的

  • \section中使用\verb以及宏包fancyvrb提供的\Verb报错的原因…..
  • protected宏和robust宏这一trick的实现,\protect\protected的区别,以及cprotect宏包用法
  • expl3f型展开与e型展开吞空格的差异….
  • interface3中提到的fully expandable functionsrestricted expandable functions的区别与例
    image.png

撰写答案

请登录后再发布答案,点击登录

发布
问题

分享
好友

手机
浏览

扫码手机浏览