On 25/06/2013 22:02, Jura Pintar wrote:
>> 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.

Looking at this, both Bruno and I noticed that if you are allowing a
clist then in principal you could simply extend \keys_set:nn to have a
list for the first argument. However, I'm not sure that's quite right.

If you look at the pgfkeys demo above, what you see is that all of the
keys are in the same path:

  /mymodule/key-A-i
  /mymodule/key-B-i

with the family as a 'secondary path' (or something like that). This
means three things:

 1) With filtering turned 'off', the keys can all be set in one
    operation (no need to try different places)

 2) The key names are unique

 3) If the key is not found, there is one place to look for an
    unknown handler: /mymodule/unknown

On the other hand, the proposed extension to l3keys uses key path for
filtering, so we find in contrast

 1) The keys can only all be set by actively choosing each subgroup

 2) Key names may not be unique, so the order of subgroups becomes
    important

 3) Handling for unknown keys is far from clear (do we look in
    /mymodule/, /mymodule/subgroup-A/, ...?)

I'm going to take a look at how pgfkeys actually handles this.
--
Joseph Wright