User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:17.0)
            Gecko/20130620 Thunderbird/17.0.7
MIME-Version: 1.0
References: <CAM2dePV5k2+Q+H=jCj=bsvc-hWanc3_CLYw1-ukhB8UMhzU_Lw@mail.gmail.com> <51C94FA0.1080803@morningstar2.co.uk> 
            <CAM2dePUfzF_Bj5QX7qbAmsyO7Udjy1yb5j43zTVexOwG2rmtVQ@mail.gmail.com> <51DD0EBD.6080308@morningstar2.co.uk> 
            <CAM2dePUxFs1eNU1iTCrnp=CbDFo1eMjE813gZQH3vVhBkH=zDg@mail.gmail.com>           
            <51DF2000.30703@morningstar2.co.uk>
            <CAM2dePW67rUcSRqRYEeccS6AUVmGjW5XuY74ZCYPfgqObK=BcA@mail.gmail.com>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
Message-ID:  <51E12031.4060600@morningstar2.co.uk>
Date:         Sat, 13 Jul 2013 10:38:57 +0100
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: Joseph Wright <joseph.wright@MORNINGSTAR2.CO.UK>
Subject: Re: l3keys feature request
To: LATEX-L@LISTSERV.UNI-HEIDELBERG.DE
In-Reply-To:  <CAM2dePW67rUcSRqRYEeccS6AUVmGjW5XuY74ZCYPfgqObK=BcA@mail.gmail.com>
Precedence: list
Envelope-To: <rainer.schoepf@GMX.NET>
Status: R

Hello Jura,

>> The above interface leaves open a few questions:
>>
>>  - How is nesting handled? Does \keys_set:nn within
>>    \keys_set_grouped:nnn respect groups? Does
>>    \keys_set_grouped:nnn within \keys_set_grouped:nnn
>>    work in a union or intersection way?
> 
> I'd say, 'yes' to the first (that would be closest to what is done in
> pgfkeys), and given that, 'intersection' to the second.

I've been looking at this in more detail, and I suspect that sticking to
the 'no nesting' position is easiest (other than \keys_set:nn within
\keys_set_... respects the outer position: needed for .meta:n, etc.). I
don't see a lot a real use cases for nesting, while I do see quite a bit
of complexity in allowing it!

>>  - Do unknown keys raise an error, or are they ignored as they
>>    are not in any group?
> 
> Following pgfkeys again, I think they should raise an error.

See below.

>>  - Do unused options need to be collected/available?
> 
> I've not had the occasion to use this myself, but pgfkeys does provide
> it. One application that immediately pops to my mind is the control of
> key-setting order when the order is important, which is potentially
> rather useful. So why not have \keys_set_grouped:nnnN, allowing
> something like:

OK, I can build in the ability to do this. Worth bearing in mind that
grouping is intended for the case where you want to have a 'second axis'
for keys. If you always want to be able to set stuff in an order, then
\keys_set_known:nnN plus subtrees already works. (We added this a while
ago, primarily as Will needed it for fontspec.)

> \cs_new_protected:Npn \__mymodule_keys_set_in_order_and_do_something:n #1

> Another question is what should happen to keys that haven't been
> assigned a group. Right now, they're filtered out, but perhaps it
> would be better to set them. In that way, if there are keys that
> should never be filtered, they won't need to be assigned a fallback
> group to accomplish this. Pgfkeys provides both options, but it seems
> to me it's easier for package writers using l3keys to just follow the
> principle that they should assign a key to a group only if they ever
> want to filter it out. This ties in with one aspect of how the draft
> \keys_set_groups:nnn behaves that I feel should be definitely changed.
> Right now, when the second argument is empty, all the keys get set,
> which is the opposite of what one would expect. I think, instead, no
> keys should be set, except for those that have no group assigned to
> them. I believe changing \tl_set:Nx \l__keys_groups_clist {#4} to
> \tl_set:Nx \l__keys_groups_clist { , #4 } in the definition of
> \__keys_set_grouped:nnnnn would do this.

I get the feeling there are two related but distinct requirements here:

 - Set only keys from specified groups ('opt-in')
 - Set keys unless they are in groups specified to be filtered out
   ('opt-out')

The following implements that, but note that you will need the 'burning
edge' expl3 from GitHub/SVN as I've made some adjustments to the l3keys
code to allow for things we certainly will want whatever the final form
of groups/families.

\cs_new_protected:Npn \__keys_groups_set:n #1
  {
    \prop_if_exist:cT { \c__keys_info_root_tl \l_keys_path_tl }
      {
        \prop_put:cnn { \c__keys_info_root_tl \l_keys_path_tl }
          { groups } {#1}
      }
  }
\cs_new_protected:cpn { \c__keys_props_root_tl .groups:n } #1
  { \__keys_groups_set:n {#1} }

\bool_new:N \l__keys_filter_bool
\bool_new:N \l__keys_groups_bool
\seq_new:N \l__keys_groups_seq
\tl_new:N \l__keys_groups_tl
\bool_new:N \l__keys_tmp_bool

\cs_new_protected:Npn \keys_set_filter:nnn #1#2#3
  {
    \bool_set_true:N \l__keys_filter_bool
    \seq_set_from_clist:Nn \l__keys_groups_seq {#2}
    \keys_set:nn {#1} {#3}
    \bool_set_false:N \l__keys_filter_bool
  }
\cs_new_protected:Npn \keys_set_filter:nnnN #1#2#3#4
  {
    \clist_clear:N \l__keys_unused_clist
    \keys_set_filter:nn {#1} {#2} {#3}
    \tl_set:Nx #3 { \exp_not:o { \l__keys_unused_clist } }
  }
\cs_new_protected:Npn \keys_set_groups:nnn #1#2#3
  {
    \bool_set_true:N \l__keys_groups_bool
    \seq_set_from_clist:Nn \l__keys_groups_seq {#2}
    \keys_set:nn {#1} {#3}
    \bool_set_false:N \l__keys_groups_bool
  }

\cs_set_protected:Npn \__keys_set_elt_aux:nn #1#2
  {
    \tl_set:Nx \l_keys_key_tl { \tl_to_str:n {#1} }
    \tl_set:Nx \l_keys_path_tl { \l__keys_module_tl / \l_keys_key_tl }
    \__keys_value_or_default:n {#2}
    \bool_if:nTF { \l__keys_filter_bool || \l__keys_groups_bool }
      { \__keys_set_elt_grouped: }
      { \__keys_set_elt_aux: }
  }
\cs_new_protected_nopar:Npn \__keys_set_elt_aux:
  {
    \bool_if:nTF
      {
        \__keys_if_value_p:n { required } &&
        \l__keys_no_value_bool
      }
      {
        \__msg_kernel_error:nnx { kernel } { value-required }
          { \l_keys_path_tl }
      }
      {
        \bool_if:nTF
          {
              \__keys_if_value_p:n { forbidden } &&
            ! \l__keys_no_value_bool
          }
          {
            \__msg_kernel_error:nnxx { kernel } { value-forbidden }
              { \l_keys_path_tl } { \l_keys_value_tl }
          }
          { \__keys_execute: }
      }
  }
\cs_new_protected_nopar:Npn \__keys_set_elt_grouped:
  {
    \prop_if_exist:cTF { \c__keys_info_root_tl \l_keys_path_tl }
      {
        \prop_get:cnNTF { \c__keys_info_root_tl \l_keys_path_tl }
          { groups } \l__keys_groups_tl
          { \__keys_check_groups: }
          {
            \bool_if:NTF \l__keys_filter_bool
              { \__keys_set_elt_aux: }
              { \__keys_store_unused: }
          }
      }
      {
        \bool_if:NTF \l__keys_filter_bool
          { \__keys_set_elt_aux: }
          { \__keys_store_unused: }
      }
  }
\cs_new_protected_nopar:Npn \__keys_store_unused:
  {
    \clist_put_right:Nx \l__keys_unknown_clist
      {
        \exp_not:o \l_keys_key_tl
        \bool_if:NF \l__keys_no_value_bool
          { = { \exp_not:o \l_keys_value_tl } }
      }
  }
\cs_new_protected_nopar:Npn \__keys_check_groups:
  {
    \bool_set_false:N \l__keys_tmp_bool
    \seq_map_inline:Nn \l__keys_groups_seq
      {
        \clist_map_inline:Vn \l__keys_groups_tl
          {
            \str_if_eq:nnT {##1} {####1}
              {
                \bool_set_true:N \l__keys_tmp_bool
                \clist_map_break:n { \seq_map_break: }
              }
          }
      }
    \bool_if:NTF \l__keys_tmp_bool
      {
        \bool_if:NTF \l__keys_filter_bool
          { \__keys_store_unused: }
          { \__keys_set_elt_aux: }
      }
      {
        \bool_if:NTF \l__keys_filter_bool
          { \__keys_set_elt_aux: }
          { \__keys_store_unused: }
      }
  }
\cs_generate_variant:Nn \clist_map_inline:nn { V }


\keys_define:nn { module }
  {
    key-one .code:n   = { \tl_show:n { key-one } },
    key-one .groups:n = { a , b },
    key-two .code:n   = { \tl_show:n { SAW:~key-two } },
    key-two .groups:n = { c , f },
  }

\keys_set_groups:nnn { module } { a , c }
  { key-one = value , key-two = value-test , key-odd = value }
-- 
Joseph Wright