summaryrefslogtreecommitdiff
path: root/macros/latex-dev/required/l3kernel/l3keys.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex-dev/required/l3kernel/l3keys.dtx')
-rw-r--r--macros/latex-dev/required/l3kernel/l3keys.dtx309
1 files changed, 153 insertions, 156 deletions
diff --git a/macros/latex-dev/required/l3kernel/l3keys.dtx b/macros/latex-dev/required/l3kernel/l3keys.dtx
index a1d2c01169..f03c628a63 100644
--- a/macros/latex-dev/required/l3kernel/l3keys.dtx
+++ b/macros/latex-dev/required/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:
}