diff options
author | Karl Berry <karl@freefriends.org> | 2024-05-08 19:35:25 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2024-05-08 19:35:25 +0000 |
commit | a19dbb52dd2cf8e16144bcb532416b796dd10430 (patch) | |
tree | ff9cce4dad042da1444dea49182b58ed6c183464 /Master/texmf-dist/source/latex-dev/l3kernel/l3keys.dtx | |
parent | a2b1e144f8c72c4e95ca6576f4e8e73e5b51085b (diff) |
l3-dev (8may24)
git-svn-id: svn://tug.org/texlive/trunk@71211 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex-dev/l3kernel/l3keys.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex-dev/l3kernel/l3keys.dtx | 309 |
1 files changed, 153 insertions, 156 deletions
diff --git a/Master/texmf-dist/source/latex-dev/l3kernel/l3keys.dtx b/Master/texmf-dist/source/latex-dev/l3kernel/l3keys.dtx index a1d2c011691..f03c628a63f 100644 --- a/Master/texmf-dist/source/latex-dev/l3kernel/l3keys.dtx +++ b/Master/texmf-dist/source/latex-dev/l3kernel/l3keys.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2024-04-11} +% \date{Released 2024-05-08} % % \maketitle % @@ -585,7 +585,7 @@ % by creating sub-keys of the choice key. This can be carried out in % two ways. % -% In many cases, choices execute similar code which is dependant only +% In many cases, choices execute similar code which is dependent only % on the name of the choice or the position of the choice in the % list of all possibilities. Here, the keys can share the same code, and can % be rapidly created using the \texttt{.choices:nn} property. @@ -876,7 +876,7 @@ % \cs{keys_set_exclude_groups:nnnN} \Arg{module} \Arg{groups} \Arg{keyval list} \meta{tl} % \cs{keys_set_exclude_groups:nnnnN} \Arg{module} \Arg{groups} \Arg{keyval list} \meta{root} \meta{tl} % \end{syntax} -% Sets keys by excluding those in the specificied \meta{groups}. +% Sets keys by excluding those in the specified \meta{groups}. % The \meta{groups} are % given as a comma-separated list. Unknown keys are not assigned to any % group and are thus always set. The key--value pairs for each @@ -891,10 +891,14 @@ % the key names and values are returned. % \end{function} % -% \begin{function}[added = 2013-07-14, updated = 2017-05-27] +% \begin{function}[added = 2013-07-14, updated = 2024-05-08] % { % \keys_set_groups:nnn, \keys_set_groups:nnV, -% \keys_set_groups:nnv, \keys_set_groups:nno +% \keys_set_groups:nnv, \keys_set_groups:nno, +% \keys_set_groups:nnnN, \keys_set_groups:nnVN, +% \keys_set_groups:nnvN, \keys_set_groups:nnoN, +% \keys_set_groups:nnnnN, \keys_set_groups:nnVnN, +% \keys_set_groups:nnvnN, \keys_set_groups:nnonN, % } % \begin{syntax} % \cs{keys_set_groups:nnn} \Arg{module} \Arg{groups} \Arg{keyval list} @@ -902,7 +906,10 @@ % Activates key filtering in an \enquote{opt-in} sense: only keys assigned to % one or more of the \meta{groups} specified are set. The \meta{groups} are % given as a comma-separated list. Unknown keys are not assigned to any -% group and are thus never set. +% group and are thus never set. The key--value pairs for each +% key which is filtered out are stored in the \meta{tl} in a +% comma-separated form (\emph{i.e.}~an edited version of the \meta{keyval +% list}). The \cs{keys_set_groups:nnn} version skips this stage % \end{function} % % \section{Digesting keys} @@ -1667,20 +1674,27 @@ % \end{macrocode} % \end{variable} % -% \begin{variable}{\l_@@_selective_bool, \l_@@_filtered_bool} +% \begin{variable}{\l_@@_selective_bool, \l_@@_exclude_bool} % Two booleans for using key groups: one to indicate that \enquote{selective} % setting is active, a second to specify which type (\enquote{opt-in} % or \enquote{opt-out}). % \begin{macrocode} \bool_new:N \l_@@_selective_bool -\bool_new:N \l_@@_filtered_bool +\bool_new:N \l_@@_exclude_bool % \end{macrocode} % \end{variable} % -% \begin{variable}{\l_@@_selective_seq} +% \begin{variable}{\l_@@_selective_clist} % The list of key groups being filtered in or out during selective setting. % \begin{macrocode} -\seq_new:N \l_@@_selective_seq +\seq_new:N \l_@@_selective_clist +% \end{macrocode} +% \end{variable} +% +% \begin{variable}{\l_@@_tmp_clist} +% Scratch space used as a data dump. +% \begin{macrocode} +\seq_new:N \l_@@_tmp_clist % \end{macrocode} % \end{variable} % @@ -2787,36 +2801,58 @@ % % \subsection{Setting keys} % -% \begin{macro} -% { -% \keys_set:nn, \keys_set:nV, \keys_set:nv, \keys_set:ne, -% \keys_set:no, \keys_set:nx, -% \@@_set:nn -% } +% \begin{macro}{\@@_set:nnnnNn} +% \begin{macro}{\@@_set:nnnnnnnNn} +% \begin{macro}[EXP]{\@@_reset_bool:N, \@@_reset_var:N} +% \begin{macro}{\@@_set:nn} % \begin{macro}{\@@_set:nnn} -% A simple wrapper allowing for nesting. -% \begin{macrocode} -\cs_new_protected:Npn \keys_set:nn #1#2 +% The aim here is to allow nesting of key setting without needing lots of +% tracking. That is done by expanding the appropriate tokens \enquote{around} +% the core keyval parsing. As there are several different sub-paths, this +% needs a few steps and some generic auxiliaries. The arguments here are +% \begin{enumerate} +% \item The root for keys +% \item The key groups +% \item The keys themselves +% \item The relative root for return of unset keys +% \item The \texttt{clist} var for returning unset keys +% \item The code to set up the correct selection approach +% \end{enumerate} +% \begin{macrocode} +\cs_new_protected:Npn \@@_set:nnnnNn + { + \exp_args:Nooo \@@_set:nnnnnnnNn + \l_@@_unused_clist + \l_@@_selective_clist + \l_@@_relative_tl + } +\cs_new_protected:Npn \@@_set:nnnnnnnNn #1#2#3#4#5#6#7#8#9 { + \clist_clear:N \l_@@_unused_clist + \clist_set:Ne \l_@@_selective_clist { \tl_to_str:n {#5} } + \tl_set:Nn \l_@@_relative_tl {#7} \use:e { - \bool_set_false:N \exp_not:N \l_@@_only_known_bool - \bool_set_false:N \exp_not:N \l_@@_filtered_bool - \bool_set_false:N \exp_not:N \l_@@_selective_bool - \tl_set:Nn \exp_not:N \l_@@_relative_tl - { \exp_not:N \q_@@_no_value } - \@@_set:nn \exp_not:n { {#1} {#2} } - \bool_if:NT \l_@@_only_known_bool - { \bool_set_true:N \exp_not:N \l_@@_only_known_bool } - \bool_if:NT \l_@@_filtered_bool - { \bool_set_true:N \exp_not:N \l_@@_filtered_bool } - \bool_if:NT \l_@@_selective_bool - { \bool_set_true:N \exp_not:N \l_@@_selective_bool } - \tl_set:Nn \exp_not:N \l_@@_relative_tl - { \exp_not:o \l_@@_relative_tl } + \exp_not:n + { + #9 + \@@_set:nn {#4} {#6} + } + \@@_reset_bool:N \l_@@_only_known_bool + \@@_reset_bool:N \l_@@_exclude_bool + \@@_reset_bool:N \l_@@_selective_bool } + \clist_set_eq:NN #8 \l_@@_unused_clist + \__kernel_tl_set:Nx \l_@@_unused_clist { \exp_not:n {#1} } + \__kernel_tl_set:Nx \l_@@_selective_clist {#2} + \__kernel_tl_set:Nx \l_@@_relative_tl { \exp_not:n {#3} } + } +\cs_new:Npn \@@_reset_bool:N #1 + { + \exp_not:c + { bool_set_ \bool_if:NTF #1 { true } { false } :N } + \exp_not:N #1 } -\cs_generate_variant:Nn \keys_set:nn { nV , nv , ne , no , nx } \cs_new_protected:Npn \@@_set:nn #1#2 { \exp_args:No \@@_set:nnn \l_@@_module_str {#1} {#2} } \cs_new_protected:Npn \@@_set:nnn #1#2#3 @@ -2828,80 +2864,72 @@ % \end{macrocode} % \end{macro} % \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} % % \begin{macro} % { -% \keys_set_known:nnN, \keys_set_known:nVN, -% \keys_set_known:nvN, \keys_set_known:neN, -% \keys_set_known:noN +% \keys_set:nn, \keys_set:nV, \keys_set:nv, \keys_set:ne, +% \keys_set:no, \keys_set:nx % } +% A simple wrapper allowing for nesting. +% \begin{macrocode} +\cs_new_protected:Npn \keys_set:nn #1#2 + { + \@@_set:nnnnNn + {#1} { } {#2} { \q_@@_no_value } \l_@@_tmp_clist + { + \bool_set_false:N \l_@@_only_known_bool + \bool_set_false:N \l_@@_exclude_bool + \bool_set_false:N \l_@@_selective_bool + } + } +\cs_generate_variant:Nn \keys_set:nn { nV , nv , ne , no , nx } +% \end{macrocode} +% \end{macro} +% % \begin{macro} % { % \keys_set_known:nnnN, \keys_set_known:nVnN, % \keys_set_known:nvnN, \keys_set_known:nenN, % \keys_set_known:nonN % } -% \begin{macro}{\@@_set_known:nnnnN} +% \begin{macro} +% { +% \keys_set_known:nnN, \keys_set_known:nVN, +% \keys_set_known:nvN, \keys_set_known:neN, +% \keys_set_known:noN +% } % \begin{macro} % { % \keys_set_known:nn, \keys_set_known:nV, % \keys_set_known:nv, \keys_set_known:ne, % \keys_set_known:no % } -% \begin{macro}{\@@_set_known:nnn} -% Setting known keys simply means setting the appropriate boolean, then -% running the standard code. To allow for nested setting, any existing -% value of \cs{l_@@_unused_clist} is saved on the stack and reset -% afterwards. Note that for speed/simplicity reasons we use a \texttt{tl} -% operation to set the \texttt{clist} here! +% Simply set the right variables. % \begin{macrocode} -\cs_new_protected:Npn \keys_set_known:nnN #1#2#3 - { - \exp_args:No \@@_set_known:nnnnN - \l_@@_unused_clist \q_@@_no_value {#1} {#2} #3 - } -\cs_generate_variant:Nn \keys_set_known:nnN { nV , nv , ne , no } \cs_new_protected:Npn \keys_set_known:nnnN #1#2#3#4 { - \exp_args:No \@@_set_known:nnnnN - \l_@@_unused_clist {#3} {#1} {#2} #4 + \@@_set:nnnnNn + {#1} { } {#2} {#3} #4 + { + \bool_set_true:N \l_@@_only_known_bool + \bool_set_false:N \l_@@_exclude_bool + \bool_set_false:N \l_@@_selective_bool + } } \cs_generate_variant:Nn \keys_set_known:nnnN { nV , nv , ne , no } -\cs_new_protected:Npn \@@_set_known:nnnnN #1#2#3#4#5 - { - \clist_clear:N \l_@@_unused_clist - \@@_set_known:nnn {#2} {#3} {#4} - \__kernel_tl_set:Nx #5 { \exp_not:o \l_@@_unused_clist } - \__kernel_tl_set:Nx \l_@@_unused_clist { \exp_not:n {#1} } - } +\cs_new_protected:Npn \keys_set_known:nnN #1#2#3 + { \keys_set_known:nnnN {#1} {#2} { \q_@@_no_value } #3 } +\cs_generate_variant:Nn \keys_set_known:nnN { nV , nv , ne , no } \cs_new_protected:Npn \keys_set_known:nn #1#2 - { \@@_set_known:nnn \q_@@_no_value {#1} {#2} } + { \keys_set_known:nnnN {#1} {#2} { \q_@@_no_value } \l_@@_tmp_clist } \cs_generate_variant:Nn \keys_set_known:nn { nV , nv , ne , no } -\cs_new_protected:Npn \@@_set_known:nnn #1#2#3 - { - \use:e - { - \bool_set_true:N \exp_not:N \l_@@_only_known_bool - \bool_set_false:N \exp_not:N \l_@@_filtered_bool - \bool_set_false:N \exp_not:N \l_@@_selective_bool - \tl_set:Nn \exp_not:N \l_@@_relative_tl { \exp_not:n {#1} } - \@@_set:nn \exp_not:n { {#2} {#3} } - \bool_if:NF \l_@@_only_known_bool - { \bool_set_false:N \exp_not:N \l_@@_only_known_bool } - \bool_if:NT \l_@@_filtered_bool - { \bool_set_true:N \exp_not:N \l_@@_filtered_bool } - \bool_if:NT \l_@@_selective_bool - { \bool_set_true:N \exp_not:N \l_@@_selective_bool } - \tl_set:Nn \exp_not:N \l_@@_relative_tl - { \exp_not:o \l_@@_relative_tl } - } - } % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} -% \end{macro} -% \end{macro} % % \begin{macro} % { @@ -2913,97 +2941,68 @@ % \keys_set_exclude_groups:nnnnN, \keys_set_exclude_groups:nnVnN, % \keys_set_exclude_groups:nnvnN, \keys_set_exclude_groups:nnonN % } -% \begin{macro}{\@@_set_exclude_groups:nnnnnN} % \begin{macro} % { % \keys_set_exclude_groups:nnn, \keys_set_exclude_groups:nnV, % \keys_set_exclude_groups:nnv, \keys_set_exclude_groups:nno % } -% \begin{macro}{\@@_set_exclude_groups:nnnn} % \begin{macro} % { -% \keys_set_groups:nnn, \keys_set_groups:nnV, \keys_set_groups:nnv, -% \keys_set_groups:nno +% \keys_set_groups:nnnN, \keys_set_groups:nnVN, +% \keys_set_groups:nnvN, \keys_set_groups:nnoN +% } +% \begin{macro} +% { +% \keys_set_groups:nnnnN, \keys_set_groups:nnVnN, +% \keys_set_groups:nnvnN, \keys_set_groups:nnonN +% } +% \begin{macro} +% { +% \keys_set_groups:nnn, \keys_set_groups:nnV, +% \keys_set_groups:nnv, \keys_set_groups:nno % } -% \begin{macro}{\@@_set_selective:nnn} -% \begin{macro}{\@@_set_selective:nnnn} -% The idea of setting keys in a selective manner again uses booleans -% wrapped around the basic code. The comments on \cs{keys_set_known:nnN} -% also apply here. We have a bit more shuffling to do to keep everything -% nestable. +% The same for (exclusion) groups. % \begin{macrocode} -\cs_new_protected:Npn \keys_set_exclude_groups:nnnN #1#2#3#4 - { - \exp_args:No \@@_set_exclude_groups:nnnnnN - \l_@@_unused_clist - \q_@@_no_value {#1} {#2} {#3} #4 - } -\cs_generate_variant:Nn \keys_set_exclude_groups:nnnN { nnV , nnv , nno } \cs_new_protected:Npn \keys_set_exclude_groups:nnnnN #1#2#3#4#5 { - \exp_args:No \@@_set_exclude_groups:nnnnnN - \l_@@_unused_clist {#4} {#1} {#2} {#3} #5 + \@@_set:nnnnNn + {#1} {#2} {#3} {#4} #5 + { + \bool_set_false:N \l_@@_only_known_bool + \bool_set_true:N \l_@@_exclude_bool + \bool_set_true:N \l_@@_selective_bool + } } \cs_generate_variant:Nn \keys_set_exclude_groups:nnnnN { nnV , nnv , nno } -\cs_new_protected:Npn \@@_set_exclude_groups:nnnnnN #1#2#3#4#5#6 +\cs_new_protected:Npn \keys_set_exclude_groups:nnnN #1#2#3#4 + { \keys_set_exclude_groups:nnnnN {#1} {#2} {#3} { \q_@@_no_value } #4 } +\cs_generate_variant:Nn \keys_set_exclude_groups:nnnN { nnV , nnv , nno } +\cs_new_protected:Npn \keys_set_exclude_groups:nnn #1#2#3 { - \clist_clear:N \l_@@_unused_clist - \@@_set_exclude_groups:nnnn {#2} {#3} {#4} {#5} - \__kernel_tl_set:Nx #6 { \exp_not:o \l_@@_unused_clist } - \__kernel_tl_set:Nx \l_@@_unused_clist { \exp_not:n {#1} } + \keys_set_exclude_groups:nnnnN {#1} {#2} {#3} + { \q_@@_no_value } \l_@@_tmp_clist } -\cs_new_protected:Npn \keys_set_exclude_groups:nnn #1#2#3 - {\@@_set_exclude_groups:nnnn \q_@@_no_value {#1} {#2} {#3} } \cs_generate_variant:Nn \keys_set_exclude_groups:nnn { nnV , nnv , nno } -\cs_new_protected:Npn \@@_set_exclude_groups:nnnn #1#2#3#4 +\cs_new_protected:Npn \keys_set_groups:nnnnN #1#2#3#4#5 { - \use:e + \@@_set:nnnnNn + {#1} {#2} {#3} {#4} #5 { - \bool_set_false:N \exp_not:N \l_@@_only_known_bool - \bool_set_true:N \exp_not:N \l_@@_filtered_bool - \bool_set_true:N \exp_not:N \l_@@_selective_bool - \tl_set:Nn \exp_not:N \l_@@_relative_tl { \exp_not:n {#1} } - \@@_set_selective:nnn \exp_not:n { {#2} {#3} {#4} } - \bool_if:NT \l_@@_only_known_bool - { \bool_set_true:N \exp_not:N \l_@@_only_known_bool } - \bool_if:NF \l_@@_filtered_bool - { \bool_set_false:N \exp_not:N \l_@@_filtered_bool } - \bool_if:NF \l_@@_selective_bool - { \bool_set_false:N \exp_not:N \l_@@_selective_bool } - \tl_set:Nn \exp_not:N \l_@@_relative_tl - { \exp_not:o \l_@@_relative_tl } + \bool_set_false:N \l_@@_only_known_bool + \bool_set_false:N \l_@@_exclude_bool + \bool_set_true:N \l_@@_selective_bool } } +\cs_generate_variant:Nn \keys_set_groups:nnnnN { nnV , nnv , nno } +\cs_new_protected:Npn \keys_set_groups:nnnN #1#2#3#4 + { \keys_set_groups:nnnnN {#1} {#2} {#3} { \q_@@_no_value } #4 } +\cs_generate_variant:Nn \keys_set_groups:nnnN { nnV , nnv , nno } \cs_new_protected:Npn \keys_set_groups:nnn #1#2#3 { - \use:e - { - \bool_set_false:N \exp_not:N \l_@@_only_known_bool - \bool_set_false:N \exp_not:N \l_@@_filtered_bool - \bool_set_true:N \exp_not:N \l_@@_selective_bool - \tl_set:Nn \exp_not:N \l_@@_relative_tl - { \exp_not:N \q_@@_no_value } - \@@_set_selective:nnn \exp_not:n { {#1} {#2} {#3} } - \bool_if:NT \l_@@_only_known_bool - { \bool_set_true:N \exp_not:N \l_@@_only_known_bool } - \bool_if:NF \l_@@_filtered_bool - { \bool_set_true:N \exp_not:N \l_@@_filtered_bool } - \bool_if:NF \l_@@_selective_bool - { \bool_set_false:N \exp_not:N \l_@@_selective_bool } - \tl_set:Nn \exp_not:N \l_@@_relative_tl - { \exp_not:o \l_@@_relative_tl } - } + \keys_set_groups:nnnnN {#1} {#2} {#3} + { \q_@@_no_value } \l_@@_tmp_clist } \cs_generate_variant:Nn \keys_set_groups:nnn { nnV , nnv , nno } -\cs_new_protected:Npn \@@_set_selective:nnn - { \exp_args:No \@@_set_selective:nnnn \l_@@_selective_seq } -\cs_new_protected:Npn \@@_set_selective:nnnn #1#2#3#4 - { - \exp_args:NNe \seq_set_from_clist:Nn - \l_@@_selective_seq { \tl_to_str:n {#3} } - \@@_set:nn {#2} {#4} - \tl_set:Nn \l_@@_selective_seq {#1} - } % \end{macrocode} % \end{macro} % \end{macro} @@ -3011,8 +3010,6 @@ % \end{macro} % \end{macro} % \end{macro} -% \end{macro} -% \end{macro} % % \begin{macro}{\keys_precompile:nnN} % A simple wrapper. @@ -3127,7 +3124,7 @@ \@@_check_groups: } { - \bool_if:NTF \l_@@_filtered_bool + \bool_if:NTF \l_@@_exclude_bool \@@_execute: \@@_store_unused: } @@ -3138,7 +3135,7 @@ % set active. That requires two mappings, and again a different outcome % depending on whether opt-in or opt-out is set. % It is safe to use \cs{clist_if_in:NnTF} because -% both \cs{l_@@_selective_seq} and \cs{l_@@_groups_clist} contain the +% both \cs{l_@@_selective_clist} and \cs{l_@@_groups_clist} contain the % groups as strings, without leading/trailing spaces in any item, % since the \pkg{l3clist} functions were applied to the result of % applying \cs{tl_to_str:n}. @@ -3146,22 +3143,22 @@ \cs_new_protected:Npn \@@_check_groups: { \bool_set_false:N \l_@@_tmp_bool - \seq_map_inline:Nn \l_@@_selective_seq + \clist_map_inline:Nn \l_@@_selective_clist { \clist_if_in:NnT \l_@@_groups_clist {##1} { \bool_set_true:N \l_@@_tmp_bool - \seq_map_break: + \clist_map_break: } } \bool_if:NTF \l_@@_tmp_bool { - \bool_if:NTF \l_@@_filtered_bool + \bool_if:NTF \l_@@_exclude_bool \@@_store_unused: \@@_execute: } { - \bool_if:NTF \l_@@_filtered_bool + \bool_if:NTF \l_@@_exclude_bool \@@_execute: \@@_store_unused: } |