Why does pgfkeys .initial not work in these cases?

Question

I think I finally have a reasonable understanding of pgfkeys, but initializing a key with or without the .initial handler is giving me trouble. I do understand the distinction between .default and .initial in that the former specifies a value when none is given for a key and the latter specifies a value otherwise (that is my understanding, anyway). The MWE contains four example cases.

The first one seems to work correctly, except that trying to initialize paintwhat and paintshade with .initial gives an error about an undefined control sequence. The second example seems to work correctly, but again trying to initialize units with .initial while .default seems to work perfectly. In the third example, I understand that .initial doesn't work with subkeys and I think that's why I can't use it in this example. How, then, can I initialize sunits? Finally, in the fourth example, when I initialize zunits LAST inside \pgfkeys{...} the initial use of \picktheunits works as expected, but the final use does not.

Ultimately, my question is: what causes these difficulties in initializing a key? Is is something trivial I'm overlooking, or is it something subtle?

(In case anyone is wondering, this example with units is my prototypical test case for testing keys and values.)

Here is the MWE:

% !TEX TS-program = lualatexmk
% !TEX encoding = UTF-8 Unicode

\documentclass{article}
\usepackage{pgfkeys}

\begin{document}

A command about painting things.\par
%\newcommand*{\paintit}{}   % this appears to be optional
%\newcommand*{paintshadw}{} % this appears to be optional
\pgfkeys{%
  /paintthe/.is family, /paintthe,
  paintwhat/.store in=\paintit,
  paintwhat/.default=building, % used when just paintwhat is given
  paintwhat = barn,            % initial value of paintwhat; can be overwritten
  paintshade/.store in=\paintshade,
  paintshade/.default=light,   % used when just paintshade is given
  paintshade = light,          % initial value of paintshade; can be overwritten
}%

%  version with shade
\newcommand*{\paintthecolor}[2][]{%
  \begingroup % make key values local to this instance
    \pgfkeys{/paintthe,#1}
    Paint the \paintit\ \paintshade\ #2.
  \endgroup
}%

\paintthecolor{green}\par
\paintthecolor[paintwhat]{green}\par
\paintthecolor[paintwhat=house,paintshade=dark]{red}\par
\paintthecolor[paintwhat=car,paintshade=medium]{blue}\par
\paintthecolor{gray}\par

% These commands will already be defined, albeit not as they are here.
\newcommand*{\perpusederivedunits}{You'll get derived units.}
\newcommand*{\perpusebaseunits}{You'll get base units.}
\newcommand*{\perpusealternateunits}{You'll get alternate units.}

A command about selecting default units. Seems to work correctly.\par
\pgfkeys{%
  /chooseunits/.is family, /chooseunits,
  units/.store in=\chosenunits,
  units/.default=alternate,
  units=derived, % .initial doesn't work here
}%

\newcommand*{\choosetheunits}[1][]{%
  \begingroup
    \pgfkeys{/chooseunits,#1}
    \csname perpuse\chosenunits units\endcsname % this builds the command that selects the units
  \endgroup
}%
\choosetheunits\par % works correctly
\choosetheunits[units=base]\par
\choosetheunits[units]\par
\choosetheunits[units=derived]\par
\choosetheunits[units=alternate]\par
\choosetheunits[units=derived]\par
\choosetheunits[units]\par
\choosetheunits\par % works correctly

A different approach using \texttt{.is choice} handler. Can't initialize.\par
\pgfkeys{%
  /selectunits/.is family, /selectunits,% /.cd,
  sunits/.is choice,
  sunits/.initial={\perpusederivedunits}, % .initial doesn't work with .is choice
  sunits/.default=alternate,
  sunits/base/.code={\perpusebaseunits},
  sunits/derived/.code={\perpusederivedunits},
  sunits/alternate/.code={\perpusealternateunits},
}%
\newcommand*{\settheunits}[1][]{%
  \begingroup
    \pgfkeys{/selectunits,#1}
  \endgroup
}%
\settheunits\par % doesn't work since .initial doesn't apply to .is choice
\settheunits[sunits=base]\par
\settheunits[sunits]\par
\settheunits[sunits=derived]\par
\settheunits[sunits=alternate]\par
\settheunits[sunits=derived]\par
\settheunits[sunits]\par
\settheunits\par % doesn't work since .initial doesn't apply to .is choice

Another approach to the unit problem. Partially works.\par
\pgfkeys{%
  /pickunits/.is family, /pickunits,
  %zunits=derived, % throws unknown key error when placed here
  zunits/.default=alternate,
  zunits/.code={\csname perpuse#1units\endcsname},
  zunits=derived, % works partially when placed here
}%
\newcommand*{\picktheunits}[1][]{%
  \begingroup
    \pgfkeys{/pickunits,#1}
  \endgroup
}%
\picktheunits\par % works correctly
\picktheunits[zunits=base]\par
\picktheunits[zunits]\par
\picktheunits[zunits=derived]\par
\picktheunits[zunits=alternate]\par
\picktheunits[zunits=derived]\par
\picktheunits[zunits]\par
\picktheunits\par % does not work
\end{document}

Answer 1

The .initial key handler is used to store a value inside the key in pgfkey's name space. If a key has no other handler associated other than the .initial handler, it becomes similar to a .store in key, in that it'll store new values inside the key when used. The stored values can then be retrieved either via the .get handler, or with \pgfkeysvalueof.

When you also use .code the key will continue to store the last value stored (either from before adding .code, or from a later use of .initial), but now the .code takes precedence when the key is used without a handler. So when you now do \pgfkeys{/foo=abc} it'll not store abc, but execute .code for abc.

Any (or most?) of the other handlers are internally using .code, so as soon as you add another handler to a key it loses the functionality to store values inside key itself from normal use.

However in your case, you never had the intention to use the storage functionality of pgfkeys, but use handlers, such as .store in. So you don't use .initial inside pgfkeys for initial values, as you would with some other key=value packages (like l3keys or expkv-def). Instead the correct way to set an initial value for a key using a handler like .choice or .store in is to just use the key, e.g., with \pgfkeys{/foo=bar}.

Btw. your undefined control sequence stems from the fact that .store in doesn't initialize the macros used, so after \pgfkeys{/foo/.store in=\foo} the macro \foo isn't defined yet, it'll just be defined after you use the key for the first time.

---

Another method to define an initial value for a macro defined via .store in would be to use \newcommand*:

\newcommand*\foo{bar}
\pgfkeys{/foo/.store in=\foo,/foo/.default=baz}

would add a key /foo, that stores inside \foo, has the initial value bar and the default baz.

Answer 2

After more experimentation, I finally found what I think is a good solution using \NewDocumentCommand. There are two \pfgkeys{...} blocks, one that uses .is choice and one that does not. Obviously only one of the two can be used at a time, but both give the same results and the new command's syntax works exactly as I expect it to. The idea is to test for the presence of the optional argument containing keys, or the absence thereof, and execute the appropriate code. I want to eventually use \NewDocumentCommand as much as possible so this seems to be a nice solution. I assume someone will let me know if I've committed any atrocities.

EDIT: I added a sanity check on the key value.

Here is the MWE:

% !TEX TS-program = lualatexmk
% !TEX encoding = UTF-8 Unicode

\documentclass{article}
\usepackage{pgfkeys}

\begin{document}

\newcommand*{\perpusebaseunits}{You'll get base units.}
\newcommand*{\perpusederivedunits}{You'll get derived units.}
\newcommand*{\perpusealternateunits}{You'll get alternate units.}

% This block does not use .is choice
\pgfkeys{%
  /selectunits/.is family, /selectunits,%
  sunits/.initial=alternate,%
  sunits/.default=derived,%
  sunits/.code={%
    \ifcsname perpuse#1units\endcsname
      \csname perpuse#1units\endcsname
    \else
      \GenericError{}
        {\MessageBreak settheunits: Illegal key value}
        {Key 'sunits' can only be one of base, derived, or alternate.}
        {Read the documentation for help.}
    \fi
  }%
  %sunits/.code={\csname perpuse#1units\endcsname},%
}%

% This block uses .is choice
%\pgfkeys{%
%  /selectunits/.is family, /selectunits,%
%  sunits/.is choice,%
%  sunits/.initial=alternate,%
%  sunits/.default=derived,%
%  sunits/base/.code={\perpusebaseunits},%
%  sunits/derived/.code={\perpusederivedunits},%
%  sunits/alternate/.code={\perpusealternateunits},%
%}%

\NewDocumentCommand{\settheunits}{ o }{%
  \IfValueTF {#1}
    { \pgfkeys{/selectunits,#1} }
    { \csname perpuse\pgfkeysvalueof{/selectunits/sunits}units\endcsname }
}%

\settheunits\par
\settheunits[sunits]\par
\settheunits[sunits=base]\par
\settheunits[sunits=derived]\par
\settheunits[sunits=alternate]\par
\settheunits[sunits]\par
\settheunits\par
\settheunits[sunits=blubb]\par % This will halt processing with an error.

\end{document}