pgfkeys' first char syntax detection failure

Question

I saved the following code in the file ~/Test.tex.

\documentclass{article}
\usepackage{pgfkeys}
\pgfkeys{
   /handlers/first char syntax=true,
   /handlers/first char syntax/the character a/.initial=\LowercaseA
}
\def\LowercaseA#1{#1}
\begin{document}
\pgfkeys{aardvark}
\end{document}

The code configures the \pgfkeys command to inspect the first character of each key, and if this character is the letter a, to call the \LowercaseA command with a single argument: the key. The \LowercaseA command simply expands to its argument. The code then calls \pgfkeys, passing it the key aardvark.

Then I executed the following commands in the Terminal.

> cd ~
> pdflatex Test

The compilation failed, and ~/Test.log contained the following error message.

! Package pgfkeys Error: I do not know the key '/aardvark' and I am going to ignore it. Perhaps you misspelled it.
See the pgfkeys package documentation for explanation.
Type  H <return>  for immediate help.
 ...
l.9 \pgfkeys{aardvark}

This came as an undesirable surprise. I expected the compilation to succeed, and for the PDF file to display the string "aardvark". My expectations were based on the following quote from section 87.3.1 First Char Syntax Detection of the PGF & TikZ manual for version 3.1.9a (the current version), on p. 977:

Usually, keys are of the form 〈key〉=〈value〉 and how such keys are handled is discussed in the rest of this section. However, it is also possible to setup a different syntax for certain parts of the input to \pgfkeys. [...] this special syntax detection is the very first thing that is done when a key is processed, before any of the following operations are performed.

Questions

Why did the compilation fail?
How can I change my code so that the generated PDF file displays the string "aardvark"?

score 3 · Answer 1 · answered Dec 14 '22 at 22:20

It needs to be

/handlers/first char syntax/the letter a/.initial=\LowercaseA

The manual states

The <meaning of character> should be the text that TeX’s command \meaning returns […].

Since a is a letter (catcode 11) and not a character (catcode 12, other), this is the letter a.

You can check this yourself with – as the manual states –

\meaning a

or, if you want to just let TeX do the work, just do

/handlers/first char syntax/\meaning a/.initial=\LowercaseA

in the first place.

Of course, your code won't work anymore if the catcode of a changes but if it does you've got bigger problems …

Code

\documentclass{article}
\usepackage{pgfkeys}
\pgfkeys{
   /handlers/first char syntax=true,
%   /handlers/first char syntax/\meaning a/.initial=\LowercaseA,
   /handlers/first char syntax/the letter a/.initial=\LowercaseA,
}
\def\LowercaseA#1{#1}
\begin{document}
\pgfkeys{aardvark}
%\begingroup % This will fail because a is no longer a letter
%  \catcode`\a=12
%  \pgfkeys{aardvark}
%\endgroup
\end{document}

David Carlisle · Accepted Answer · 2022-12-14T22:13:32.937

2

check \meaning a it's catcode 11 letter so:

\documentclass{article}
\usepackage{pgfkeys}
\pgfkeys{
   /handlers/first char syntax=true,
   /handlers/first char syntax/the letter a/.initial=\LowercaseA
}
\def\LowercaseA#1{#1}
\begin{document}
\pgfkeys{aardvark}
\end{document}

edited Dec 14 '22 at 22:13

answered Dec 14 '22 at 22:10

David Carlisle

757,742

Oof, I can't believe I made this silly mistake. Thanks! – Evan Aad Dec 14 '22 at 22:12
I realize why I made this mistake. In my real life code (as opposed to the minimal working example that I listed in my original post) I use as first letter flags for pgfkeys not only alphabetical letters but also digits, and the \meaning of digits starts with the character (as opposed to the letter), so I assumed this applied to letters as well, and simply copied-and-pasted without verifying with the \meaning command. – Evan Aad Dec 14 '22 at 22:19
@EvanAad digits are catcode 12 – David Carlisle Dec 14 '22 at 22:20

pgfkeys' first char syntax detection failure

2 Answers2

Code