MIME-Version: 1.0
References: <CAM2dePV5k2+Q+H=jCj=bsvc-hWanc3_CLYw1-ukhB8UMhzU_Lw@mail.gmail.com>
            <51C94FA0.1080803@morningstar2.co.uk>
Content-Type: text/plain; charset=ISO-8859-1
Message-ID:  <CAM2dePUfzF_Bj5QX7qbAmsyO7Udjy1yb5j43zTVexOwG2rmtVQ@mail.gmail.com>
Date:         Tue, 25 Jun 2013 17:02:50 -0400
Reply-To: Mailing list for the LaTeX3 project
              <LATEX-L@LISTSERV.UNI-HEIDELBERG.DE>
Sender: Mailing list for the LaTeX3 project <LATEX-L@LISTSERV.UNI-HEIDELBERG.DE>
From: Jura Pintar <jura.pintar@GMAIL.COM>
Subject: Re: l3keys feature request
To: LATEX-L@LISTSERV.UNI-HEIDELBERG.DE
In-Reply-To:  <51C94FA0.1080803@morningstar2.co.uk>
Precedence: list
Envelope-To: <rainer.schoepf@GMX.NET>
Status: R

> 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.