> Here I'm less certain, both in functionality and name terms. I wonder if
> we might have a real-life use case for this?
I certainly feel no close attachment to the proposed names! :) They were
just the first to pop into my mind. Perhaps \keys_subgroups_set:nnn
(\keys_subgroups_set_known:nnn) or even just \keys_set:nnn
(\keys_set_known:nnn) would be better. You'd be the best judge of what the
closest fit with the current naming scheme is.
The way I see it, these commands would be a replacement of sorts for
\pgfkeysactivatefamilies{<family list>}{<deactivate macro name>} followed by
\pgfqkeysfiltered{<path>}{<key-value list>} and their kin.
Let's say we wanted to define some user commands that take a key-value list
as an argument, but each command should accept a different subset of the
available keys. With pgfkeys (and L2) we could do
\pgfkeys{
/mymodule/.cd,
subgroup-A/.is family,
subgroup-B/.is family,
subgroup-C/.is family,
key-A-i/.code={<code>},
key-A-i/.belongs to family={/mymodule/subgroup-A},
...
key-B-i/.code={<code>},
key-B-i/.belongs to family={/mymodule/subgroup-B},
...
key-C-i/.code={<code>},
key-C-i/.belongs to family={/mymodule/subgroup-C},
...
}
\pgfkeysinstallkeyfilter{
/pgf/key filters/active families
}{}
\DeclareDocumentCommand\fooABC{ m }{%
\pgfqkeys{/mymodule}{#1}%
\mymodule@fooABC%
}
\DeclareDocumentCommand\fooAB{ m }{%
\pgfkeysactivatefamilies{
/mymodule/subgroup-A,
/mymodule/subgroup-B
}{\mymodule@AB@filter@stop}%
\pgfqkeysfiltered{/mymodule}{#1}%
\mymodule@fooAB%
\mymodule@AB@filter@stop%
}
\DeclareDocumentCommand\fooBC{ m }{%
\pgfkeysactivatefamilies{
/mymodule/subgroup-B,
/mymodule/subgroup-C
}{\mymodule@BC@filter@stop}%
\pgfqkeysfiltered{/mymodule}{#1}%
\mymodule@fooBC%
\mymodule@BC@filter@stop%
}
With the proposed commands, we could do the same in l3keys by writing
\keys_define:nn { mymodule }
{
subgroup-A / key-A-i .code:n = { <code> } ,
...
subgroup-B / key-B-i .code:n = { <code> } ,
...
subgroup-C / key-C-i .code:n = { <code> } ,
...
}
\DeclareDocumentCommand \fooABC { m }
{
\keys_subgroups_set_known:nnnN { mymodule }
{ subgroup-A , subgroup-B , subgroup-C }
{#1}
\l__mymodule_tmp_clist
\__mymodule_fooABC:
}
\DeclareDocumentCommand \fooAB { m }
{
\keys_subgroups_set_known:nnnN { mymodule }
{ subgroup-A , subgroup-B }
{#1}
\l__mymodule_tmp_clist
\__mymodule_fooAB:
}
\DeclareDocumentCommand \fooBC { m }
{
\keys_subgroups_set_known:nnnN { mymodule }
{ subgroup-B , subgroup-C }
{#1}
\l__mymodule_tmp_clist
\__mymodule_fooBC:
}
Right now, to achieve this we would need to write something like
\DeclareDocumentCommand \fooABC { m }
{
\keys_set_known:nnN { mymodule / subgroup-A } {#1}
\l__mymodule_tmp_clist
\keys_set_known:noN { mymodule / subgroup-B } { \l__mymodule_tmp_clist }
\l__mymodule_tmp_clist
\keys_set_known:noN { mymodule / subgroup-C } { \l__mymodule_tmp_clist }
\l__mymodule_tmp_clist
\__mymodule_fooABC:
}
\DeclareDocumentCommand \fooAB { m }
{
\keys_set_known:nnN { mymodule / subgroup-A } {#1}
\l__mymodule_tmp_clist
\keys_set_known:noN { mymodule / subgroup-B } { \l__mymodule_tmp_clist }
\l__mymodule_tmp_clist
\__mymodule_fooAB:
}
\DeclareDocumentCommand \fooBC { m }
{
\keys_set_known:nnN { mymodule / subgroup-B } {#1}
\l__mymodule_tmp_clist
\keys_set_known:noN { mymodule / subgroup-C } { \l__mymodule_tmp_clist }
\l__mymodule_tmp_clist
\__mymodule_fooBC:
}
We could, of course, define a \__mymodule_keys_subgroups_set:nnn command,
that would map the clist of subgroups and use \keys_set_known:nnN inside,
with only the minimal overhead of an extra pair of of \cs_set_eq:NN on each
iteration, but I do feel adding a kernel command would be the more elegant
solution here.
I have a real-life-use example to offer, too. I've been working on a new and
much expanded version of the turnstile package
(http://www.ctan.org/pkg/turnstile). Two notable the features of this new
version are its ability to have turnstile symbols match the designs of a
number of specified maths typefaces, and its ability to produce the full
range of Unicode-recognised turnstiles (plus a few extras, like an
extensible |~). And there are many other tweaks available to the user via a
key-value interface.
I have five key groups:
1) keys that should only be used at loading time or in a setup command (e.g.
the choice of whether commands like \models and \vdash should be redefined
to their package equivalents);
2) keys that affect the overall design of a turnstile symbol (e.g. the
choice of which typeface to match);
3) keys that affect only some small design details (e.g. the vertical offset
of the superscript box from the turnstile crossbar);
4) keys that should only be used in an optional argument to a turnstile
command and are short aliases of key-value pairs from group 2;
5) keys that should only be used in an optional argument to a turnstile
command and are short aliases of key-value pairs from group 3.
In each turnstile command, the user should have the choice of either using
the full key-value expression, or using the short aliases.
A turnstile command that produces the equivalent of \gleichstark (U+29E6)
then has three optional arguments: the first should accept keys from groups
2-5 (fixing the overall design of =||=), but the second and third should
only accept keys from groups 3 and 5 (to tweak each of =| and |=
independently, without making them badly mismatched, e.g. by having one
mimic ArevMath and the other MnSymbol). I originally implemented this with
the pgfkeys filtering commands, but I've since decided to rework the whole
thing in L3 - hence my interest in achieving something similar in l3keys.
|