diff options
Diffstat (limited to 'macros/latex-dev/required/l3kernel/l3keys.dtx')
-rw-r--r-- | macros/latex-dev/required/l3kernel/l3keys.dtx | 182 |
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 |