How to fix a LaTeX command not being evaluated when it's an argument for another command? - TeX

TopAnswers TeX

Meta

Databases

TeX

Code Golf

APL

C++

.net

db<>fiddle

Java

*nix

PHP

PowerShell

Python

Rust

टेक्-मराठी

Typst

Web Client Dev

Web Server Dev

How to fix a LaTeX command not being evaluated when it's an argument for another command?

programming add tag

nsajko

I want to color some parts of an equation, but I'm running into issues.

Reproducer:
```
\documentclass{scrartcl}
\usepackage{mathtools}
\usepackage[svgnames]{xcolor}

\ExplSyntaxOn

\NewDocumentCommand{\quotientColor}{m}{
  \str_case:nnF {#1}
    {
      {0}{Tomato}
      {1}{SpringGreen}
      {2}{Fuchsia}}
    {\msg_error:nn {just-my-document} {unknown-value-given-as-input}}}

\NewDocumentCommand{\cq}{m m}{
  \mathcolor{\quotientColor{#1}}{#2}}

\ExplSyntaxOff

\begin{document}
  \( \mathcolor{Fuchsia}{27} \)

  \( \cq{1}{34} \)
\end{document}
```

Using `\mathcolor` directly works fine, but using `\cq` fails with
```
Package xcolor Error: Undefined color `\quotientColor {1}'
```

So the command `\quotientColor` isn't being evaluated.

I know that some relevant terms here are "protected" and "expandable", but don't know what should I do now.

EDIT: a workaround is to define `\cq` like so:
```
\NewDocumentCommand{\cq}{m m}{
  \mathcolor{
    \str_case:nnF{#1}
      {
        {0}{Tomato}
        {1}{SpringGreen}
        {2}{Fuchsia}}
      {\msg_error:nn {just-my-document} {unknown-value-given-as-input}}}{
    #2}}
```

This is an OK fix for me in this case, but I hope a real solution exists, so that I could use commands within commands, instead of having one huge, unmaintainable, command.

Top Answer

AnonymousRabbit

There are quite a few things you might've misunderstood:

TeX is a macro expansion language. As long as you don't explicitly expand things yourself no "argument" (parameter) is expanded when another macro is reading it. So your provided your `\quotientColor` could expand to `Tomato` directly and you'd have a macro `\newcommand\test[2]{1 is #1, 2 is #2}` and used this:

```
\NewDocumentCommand \cq {m m}
  { \test { \quotientColor {#1} } {#2} }
```

You'd get the following expansion results:

```
% 0
\cq{0}{34}
% 1
\test{\quotientColor{0}}{34}
% 2
1 is \quotientColor{0}, 2 is 34
```

So `\quotientColor` is not expanded just because `\test` or `\mathcolor` is. However in the case of the colour commands (like `\mathcolor`) they expand their argument in the search for the colour name. If you want to actively expand a macro before the next is expanded you'll have to use `\expandafter` or `\expanded` like so:

```
\expandafter\test\expandafter{\quotientColor{#1}} % only 1 step of expansion, most likely not sufficient
\expandafter\test\expanded{{\quotientColor{#1}}} % full expansion
```

However, your `\quotientColor` is not expandable! For this to work you'll have to define it expandable, which `\NewDocumentCommand` doesn't. Instead use `\NewExpandableDocumentCommand`, also you should recover in case of an error, and you should use an expandable error message. So I'd code your `\quotientColor` in the following way:

```
\documentclass{scrartcl}

\usepackage{mathtools}
\usepackage[svgnames]{xcolor}

\ExplSyntaxOn
\msg_new:nnn { just-my-document } { unknown-value } { Unknown value given: #1 }
\NewExpandableDocumentCommand \quotientColor { m }
  {
    \str_case:nnF {#1}
      {
        { 0 } { Tomato }
        { 1 } { SpringGreen }
        { 2 } { Fuchsia }
      }
      {
        \msg_expandable_error:nnn { just-my-document } { unknown-value } {#1}
        Tomato
      }
  }
\NewDocumentCommand \cq { m m }
  { \mathcolor { \quotientColor {#1} } {#2} }
\ExplSyntaxOff

\begin{document}
\(\cq{1}{34}\)
\end{document}
```

`\newcommand` creates an expandable (and without you using the starred form) long macro. It's ok if your macro should be expandable and lives on the 2e layer (not in `expl3`). Be aware that its optional argument mechanism isn't expandable and it uses the `\protect`-mechanism (since `\protected` wasn't around when `\newcommand` was created).

Right, so `\quotientColor`is just a helper for `cq` so it's better to make it an expl3 function (e.g. `\nsajko_quotient_color:n`). But when would I want to use `\newcommand`, assuming I'm writing LaTeX and not plain TeX or another format?

It is the right thing to define a *document*-level command (so something like `\textbf`, or `\sisetup`), but it's not correct to define programming interfaces or auxiliary functions with it. Case to prove this: `\quotientColor`. That's a mapping most likely not intended for document level use, so shouldn't be defined as a *document* command. The downside is a considerable parsing overhead. Even a command that takes *no arguments* is two orders of magnitude slower if defined via `\NewDocumentCommand` vs `\protected\def` (same applies for expandable commands)[^1]. That doesn't hurt for macros used every now and then, and the advantages of the robust argument parsing (if it has arguments, especially optional ones) outweigh that performance hit. But build-ins seldomly have optional arguments (honestly, they shouldn't ever, imho), so that's that, you're punishing the user for no reason. What you should use instead: - `expl3`'s `\cs_new:Npn` for expandable, and `\cs_new_protected:Npn` for unexpandable commands - `\newcommand` for expandable stuff, unfortunately on the 2e layer there is no good interface to define protected macros (except for `\NewDocumentCommand`) so there I'd use: - `\@ifdefinable` paired with low level TeX assignments (the `\@ifdefinable` to get `\newcommand`-like behaviour): ``` \@ifdefinable\foo{\protected\def\foo{<internal stuff>}} \@ifdefinable\lfoo{\protected\long\def\lfoo#1{<internal stuff>}} ``` [^1]: Proof: ``` \RequirePackage{l3benchmark} \NewDocumentCommand \documentidle {} {} \protected\def\lowlevelidle{} \NewExpandableDocumentCommand \documentexpandableidle {} {} \def\lowlevelexpandableidle{} \ExplSyntaxOn \benchmark:n { \documentidle } \benchmark:n { \lowlevelidle } \benchmark:n { \documentexpandableidle } \benchmark:n { \lowlevelexpandableidle } \stop ```

> The real issue is that often the \New(Expandable)?DocumentCommand gets overused for everything as beginners think it’s the proper way to define any macro in LaTeX3 that doesn’t live on the expl3 layer. Is it not? What's the downside? (If you want perhaps it's better to move this discussion to the global chat?)

yes, but still the wording sounds discouraging even if I know what I'm doing, hence why I'd like my short explanation better: Use the protected macros, just if you know you'll need expandable ones use this. The real issue is that often the `\New(Expandable)?DocumentCommand` gets overused for everything as beginners think it's the proper way to define any macro in LaTeX3 that doesn't live on the `expl3` layer.

I think the exact wording of this disclaimer is poor. It should be something like: "Rule of thumb: Don't use an expansion-only grabber unless you know that it's necessary". Here it is necessary (but if you intend to use `\quotientColor` only as a pseudo-internal utility function I'd not define it with `\NewExpandableDocumentCommand` at all, rather I'd step a level down and use `\cs_new:Npn \nsajko_quotient_color:n #1 { \str_case:nnF ... }`.

@AnonymousRabbit, re: [your answer](#a2984), regarding `NewExpandableDocumentCommand`, in usrguide3.pdf it is said: > There are *very rare* occasion when it may be useful to create functions using a expansion-only grabber. [...] This facility should only be used when *absolutely necessary*. Do you agree with this disclaimer? If so, I'm confused, because this use doesn't seem "very rare".

1 Answer