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.dtx182
1 files changed, 106 insertions, 76 deletions
diff --git a/macros/latex-dev/required/l3kernel/l3keys.dtx b/macros/latex-dev/required/l3kernel/l3keys.dtx
index f03c628a63..db580c525c 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-05-08}
+% \date{Released 2024-07-20}
%
% \maketitle
%
@@ -649,15 +649,13 @@
% { key } % Name of choice key
% { choice-a , choice-b , choice-c } % Valid choices
% { \exp_not:n {#1} } % Invalid choice given
-% %
-% %
% }
% \end{verbatim}
%
% Multiple choices are created in a very similar manner to mutually-exclusive
% choices, using the properties \texttt{.multichoice:} and
% \texttt{.multichoices:nn}. As with mutually exclusive choices, multiple
-% choices are define as sub-keys. Thus both
+% choices are defined as sub-keys. Thus both
% \begin{verbatim}
% \keys_define:nn { mymodule }
% {
@@ -792,36 +790,6 @@
% }
% \end{verbatim}
%
-% \begin{function}[added = 2011-08-23, updated = 2019-01-29]
-% {
-% \keys_set_known:nn, \keys_set_known:nV,
-% \keys_set_known:nv, \keys_set_known:ne,
-% \keys_set_known:no,
-% \keys_set_known:nnN, \keys_set_known:nVN,
-% \keys_set_known:nvN, \keys_set_known:neN,
-% \keys_set_known:noN,
-% \keys_set_known:nnnN, \keys_set_known:nVnN,
-% \keys_set_known:nvnN, \keys_set_known:nenN,
-% \keys_set_known:nonN
-% }
-% \begin{syntax}
-% \cs{keys_set_known:nn} \Arg{module} \Arg{keyval list}
-% \cs{keys_set_known:nnN} \Arg{module} \Arg{keyval list} \meta{tl}
-% \cs{keys_set_known:nnnN} \Arg{module} \Arg{keyval list} \Arg{root} \meta{tl}
-% \end{syntax}
-% These functions set keys which are known for the \meta{module}, and
-% simply ignore other keys. The \cs{keys_set_known:nn} function parses the
-% \meta{keyval list}, and sets those keys which are defined for
-% \meta{module}. Any keys which are unknown are not processed further by
-% the parser. In addition, \cs{keys_set_known:nnN} stores the key--value
-% pairs in the \meta{tl} in comma-separated form (\emph{i.e.}~an edited
-% version of the \meta{keyval list}). When a \meta{root} is given
-% (\cs{keys_set_known:nnnN}), the key--value entries are returned
-% relative to this point in the key tree. When it is absent, only the
-% key name and value are provided. The correct list is returned by
-% nested calls.
-% \end{function}
-%
% \section{Selective key setting}
% \label{sec:l3keys:selective}
%
@@ -862,33 +830,37 @@
% groups to be made \enquote{active}, or by marking one or more groups to
% be ignored in key setting.
%
-% \begin{function}[added = 2024-01-10]
+% \begin{function}[added = 2011-08-23, updated = 2019-01-29]
% {
-% \keys_set_exclude_groups:nnn, \keys_set_exclude_groups:nnV,
-% \keys_set_exclude_groups:nnv, \keys_set_exclude_groups:nno,
-% \keys_set_exclude_groups:nnnN, \keys_set_exclude_groups:nnVN,
-% \keys_set_exclude_groups:nnvN, \keys_set_exclude_groups:nnoN,
-% \keys_set_exclude_groups:nnnnN, \keys_set_exclude_groups:nnVnN,
-% \keys_set_exclude_groups:nnvnN, \keys_set_exclude_groups:nnonN,
+% \keys_set_known:nn, \keys_set_known:nV,
+% \keys_set_known:nv, \keys_set_known:ne,
+% \keys_set_known:no,
+% \keys_set_known:nnN, \keys_set_known:nVN,
+% \keys_set_known:nvN, \keys_set_known:neN,
+% \keys_set_known:noN,
+% \keys_set_known:nnnN, \keys_set_known:nVnN,
+% \keys_set_known:nvnN, \keys_set_known:nenN,
+% \keys_set_known:nonN
% }
% \begin{syntax}
-% \cs{keys_set_exclude_groups:nnn} \Arg{module} \Arg{groups} \Arg{keyval list}
-% \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}
+% \cs{keys_set_known:nn} \Arg{module} \Arg{keyval list}
+% \cs{keys_set_known:nnN} \Arg{module} \Arg{keyval list} \meta{tl~var}
+% \cs{keys_set_known:nnnN} \Arg{module} \Arg{keyval list} \Arg{root} \meta{tl~var}
% \end{syntax}
-% 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
-% 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_exclude_groups:nnn} version skips this stage.
-%
-% Use of \cs{keys_set_exclude_groups:nnnN} can be nested, with the correct residual
-% \meta{keyval list} returned at each stage. In the version which takes
-% a \meta{root} argument, the key list is returned relative to that point
-% in the key tree. In the cases without a \meta{root} argument, only
-% the key names and values are returned.
+% These functions set keys which are known for the \meta{module}, and
+% simply ignore other keys. The \cs{keys_set_known:nn} function parses the
+% \meta{keyval list}, and sets those keys which are defined for
+% \meta{module}. Any keys which are unknown are not processed further by
+% the parser.
+%
+% In addition, \cs{keys_set_known:nnN} and \cs{keys_set_known:nnnN}
+% store the key--value pairs for unknown keys in the \meta{tl~var}
+% in comma-separated form (\emph{i.e.}~an edited version of the
+% \meta{keyval list}). When a \meta{root} is given
+% (\cs{keys_set_known:nnnN}), the key--value entries are returned
+% relative to this point in the key tree. When it is absent, only the
+% key name and value are provided. The correct list is returned by
+% nested calls.
% \end{function}
%
% \begin{function}[added = 2013-07-14, updated = 2024-05-08]
@@ -902,25 +874,62 @@
% }
% \begin{syntax}
% \cs{keys_set_groups:nnn} \Arg{module} \Arg{groups} \Arg{keyval list}
+% \cs{keys_set_groups:nnnN} \Arg{module} \Arg{groups} \Arg{keyval list} \meta{tl~var}
+% \cs{keys_set_groups:nnnnN} \Arg{module} \Arg{groups} \Arg{keyval list} \Arg{root} \meta{tl~var}
+% \end{syntax}
+% These functions activate key selection 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.
+%
+% In addition, \cs{keys_set_groups:nnnN} and \cs{keys_set_groups:nnnnN}
+% store the key--value pairs for skipped keys in the \meta{tl~var}
+% in comma-separated form (\emph{i.e.}~an edited version of the
+% \meta{keyval list}). When a \meta{root} is given
+% (\cs{keys_set_groups:nnnnN}), the key--value entries are returned
+% relative to this point in the key tree. When it is absent, only the
+% key name and value are provided. The correct list is returned by
+% nested calls.
+% \end{function}
+%
+% \begin{function}[added = 2024-01-10]
+% {
+% \keys_set_exclude_groups:nnn, \keys_set_exclude_groups:nnV,
+% \keys_set_exclude_groups:nnv, \keys_set_exclude_groups:nno,
+% \keys_set_exclude_groups:nnnN, \keys_set_exclude_groups:nnVN,
+% \keys_set_exclude_groups:nnvN, \keys_set_exclude_groups:nnoN,
+% \keys_set_exclude_groups:nnnnN, \keys_set_exclude_groups:nnVnN,
+% \keys_set_exclude_groups:nnvnN, \keys_set_exclude_groups:nnonN,
+% }
+% \begin{syntax}
+% \cs{keys_set_exclude_groups:nnn} \Arg{module} \Arg{groups} \Arg{keyval list}
+% \cs{keys_set_exclude_groups:nnnN} \Arg{module} \Arg{groups} \Arg{keyval list} \meta{tl~var}
+% \cs{keys_set_exclude_groups:nnnnN} \Arg{module} \Arg{groups} \Arg{keyval list} \Arg{root} \meta{tl~var}
% \end{syntax}
-% 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. 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
+% These functions activate key selection in an \enquote{opt-out} sense:
+% keys assigned to one or more of the \meta{groups} specified are
+% \emph{not} set. The \meta{groups} are given as a comma-separated list.
+% Unknown keys are not assigned to any group and are thus always set.
+%
+% In addition, \cs{keys_set_exclude_groups:nnnN} and
+% \cs{keys_set_exclude_groups:nnnnN} store the key--value pairs for
+% skipped keys in the \meta{tl~var} in comma-separated form
+% (\emph{i.e.}~an edited version of the \meta{keyval list}). When a
+% \meta{root} is given (\cs{keys_set_exclude_groups:nnnnN}), the
+% key--value entries are returned relative to this point in the key
+% tree. When it is absent, only the key name and value are provided.
+% The correct list is returned by nested calls.
% \end{function}
%
% \section{Digesting keys}
%
% \begin{function}[added = 2022-03-09]{\keys_precompile:nnN}
% \begin{syntax}
-% \cs{keys_precompile:nnN} \Arg{module} \Arg{keyval list} \meta{tl}
+% \cs{keys_precompile:nnN} \Arg{module} \Arg{keyval list} \meta{tl~var}
% \end{syntax}
% Parses the \meta{keyval list} as for \cs{keys_set:nn}, placing the
% resulting code for those which set variables or functions into the
-% \meta{tl}. Thus this function \enquote{precompiles} the keyval list into
+% \meta{tl~var}. Thus this function \enquote{precompiles} the keyval list into
% a set of results which can be applied rapidly.
% \end{function}
%
@@ -1687,14 +1696,14 @@
% \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_clist
+\clist_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
+\clist_new:N \l_@@_tmp_clist
% \end{macrocode}
% \end{variable}
%
@@ -1915,19 +1924,21 @@
% \end{macro}
%
% \begin{macro}{\@@_define_code:n}
+% \begin{macro}[EXP]{\@@_define_code:nnn}
% \begin{macro}[EXP]{\@@_define_code:w}
% Two possible cases. If there is a value for the key, then just use
% the function. If not, then a check to make sure there is no need for
% a value with the property. If there should be one then complain,
-% otherwise execute it. There is no need to check for a |:| as if it
-% was missing the earlier tests would have failed.
+% otherwise execute it. For a \LaTeXe{} property like |.code| which
+% doesn't contain a |:|, treat it as having arity 1 and pass the
+% (empty) value to it.
% \begin{macrocode}
\cs_new_protected:Npn \@@_define_code:n #1
{
\bool_if:NTF \l_@@_no_value_bool
{
- \exp_after:wN \@@_define_code:w
- \l_@@_property_str \s_@@_stop
+ \@@_define_code:nnn
+ { \use:c { \c_@@_props_root_str \l_@@_property_str } {#1} }
{ \use:c { \c_@@_props_root_str \l_@@_property_str } }
{
\msg_error:nnee { keys } { property-requires-value }
@@ -1936,12 +1947,31 @@
}
{ \use:c { \c_@@_props_root_str \l_@@_property_str } {#1} }
}
-\exp_last_unbraced:NNNNo
- \cs_new:Npn \@@_define_code:w #1 \c_colon_str #2 \s_@@_stop
- { \tl_if_empty:nTF {#2} }
+\cs_new:Npe \@@_define_code:nnn
+ {
+ \exp_not:N \exp_after:wN \exp_not:N \@@_define_code:w
+ \exp_not:N \l_@@_property_str
+ \c_colon_str \c_colon_str
+ \exp_not:N \s_@@_stop
+ }
+\use:e
+ {
+ \cs_new:Npn \exp_not:N \@@_define_code:w
+ #1 \c_colon_str #2 \c_colon_str #3 \exp_not:N \s_@@_stop
+ }
+ {
+ \tl_if_empty:nTF {#3}
+ { \use_i:nnn }
+ {
+ \tl_if_empty:nTF {#2}
+ { \use_ii:nnn }
+ { \use_iii:nnn }
+ }
+ }
% \end{macrocode}
% \end{macro}
% \end{macro}
+% \end{macro}
%
% \subsection{Turning properties into actions}
%
@@ -2148,7 +2178,7 @@
%
% \begin{macro}{\@@_initialise:n}
% A set up for initialisation: just run the code if it exists.
-% We need to set the key string here, using the deprecated \texttt{tl}
+% We need to set the key string here, using the deprecated \texttt{tl~var}
% as a piece of scratch space.
% \begin{macrocode}
\cs_new_protected:Npn \@@_initialise:n #1