diff options
author | Karl Berry <karl@freefriends.org> | 2019-02-16 22:39:34 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2019-02-16 22:39:34 +0000 |
commit | 0d6184fa42ed741f956e55a1c6e7d48ab0cac9d8 (patch) | |
tree | 683bec4b5fa84f1f9b84aaf0d4fdf8db2be83728 /Master/texmf-dist/source/latex/l3kernel/l3keys.dtx | |
parent | f3d6932fe4c7946fdb0582306715b251bf561f7e (diff) |
l3kernel (16feb19)
git-svn-id: svn://tug.org/texlive/trunk@50036 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3keys.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3keys.dtx | 479 |
1 files changed, 347 insertions, 132 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx b/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx index 9fdcda9e6aa..062880a45c4 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-01-28} +% \date{Released 2019-02-15} % % \maketitle % @@ -382,6 +382,17 @@ % Choices are discussed in detail in section~\ref{sec:l3keys:choice}. % \end{function} % +% \begin{function}[added = 2019-01-31] +% {.prop_put:N, .prop_put:c, .prop_gput:N, .prop_gput:c} +% \begin{syntax} +% \meta{key} .prop_put:N = \meta{property list} +% \end{syntax} +% Defines \meta{key} to put the \meta{value} onto the \meta{property list} +% stored under the \meta{key}. +% If the variable does not exist, it +% is created globally at the point that the key is set up. +% \end{function} +% % \begin{function}{.skip_set:N, .skip_set:c, .skip_gset:N, .skip_gset:c} % \begin{syntax} % \meta{key} .skip_set:N = \meta{skip} @@ -442,7 +453,7 @@ % them into several sub-groups for a given module. This can be achieved % either by adding a sub-division to the module name: % \begin{verbatim} -% \keys_define:nn { module / subgroup } +% \keys_define:nn { mymodule / subgroup } % { key .code:n = code } % \end{verbatim} % or to the key name: @@ -453,7 +464,7 @@ % As illustrated, the best choice of token for sub-dividing keys in % this way is |/|. This is because of the method that is % used to represent keys internally. Both of the above code fragments -% set the same key, which has full name \texttt{module/subgroup/key}. +% set the same key, which has full name \texttt{mymodule/subgroup/key}. % % As illustrated in the next section, this subdivision is % particularly relevant to making multiple choices. @@ -655,28 +666,31 @@ % } % \end{verbatim} % -% \begin{function}[added = 2011-08-23, updated = 2017-05-27] +% \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:no, % \keys_set_known:nnN, \keys_set_known:nVN, % \keys_set_known:nvN, \keys_set_known:noN, -% \keys_set_known:nn, \keys_set_known:nV, -% \keys_set_known:nv, \keys_set_known:no +% \keys_set_known:nnnN, \keys_set_known:nVnN, +% \keys_set_known:nvnN, \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} -% In some cases, the desired behavior is to simply ignore unknown keys, -% collecting up information on these for later processing. The -% \cs{keys_set_known:nnN} 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. -% The key--value pairs for each \emph{unknown} key name 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_known:nn} version -% skips this stage. -% -% Use of \cs{keys_set_known:nnN} can be nested, with the correct residual -% \meta{keyval list} returned at each stage. +% 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} @@ -719,15 +733,19 @@ % groups to be made \enquote{active}, or by marking one or more groups to % be ignored in key setting. % -% \begin{function}[added = 2013-07-14, updated = 2017-05-27] +% \begin{function}[added = 2013-07-14, updated = 2019-01-29] % { +% \keys_set_filter:nnn, \keys_set_filter:nnV, +% \keys_set_filter:nnv, \keys_set_filter:nno, % \keys_set_filter:nnnN, \keys_set_filter:nnVN, % \keys_set_filter:nnvN, \keys_set_filter:nnoN, -% \keys_set_filter:nnn, \keys_set_filter:nnV, -% \keys_set_filter:nnv, \keys_set_filter:nno +% \keys_set_filter:nnnnN, \keys_set_filter:nnVnN, +% \keys_set_filter:nnvnN, \keys_set_filter:nnonN, % } % \begin{syntax} +% \cs{keys_set_filter:nnn} \Arg{module} \Arg{groups} \Arg{keyval list} % \cs{keys_set_filter:nnnN} \Arg{module} \Arg{groups} \Arg{keyval list} \meta{tl} +% \cs{keys_set_filter:nnnnN} \Arg{module} \Arg{groups} \Arg{keyval list} \meta{root} \meta{tl} % \end{syntax} % Activates key filtering in an \enquote{opt-out} sense: keys assigned to any % of the \meta{groups} specified are ignored. The \meta{groups} are @@ -738,7 +756,10 @@ % list}). The \cs{keys_set_filter:nnn} version skips this stage. % % Use of \cs{keys_set_filter:nnnN} can be nested, with the correct residual -% \meta{keyval list} returned at each stage. +% \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. % \end{function} % % \begin{function}[added = 2013-07-14, updated = 2017-05-27] @@ -1215,6 +1236,14 @@ % \end{macrocode} % \end{variable} % +% \begin{variable}{\l_@@_relative_tl} +% The relative path for passing keys back to the user. +% \begin{macrocode} +\tl_new:N \l_@@_relative_tl +\tl_set:Nn \l_@@_relative_tl { \q_no_value } +% \end{macrocode} +% \end{variable} +% % \begin{variable}{\l_@@_property_tl} % The \enquote{property} begin set for a key at definition time is % stored here. @@ -1254,10 +1283,12 @@ % \end{macrocode} % \end{variable} % -% \begin{variable}{\l_@@_tmp_bool} +% \begin{variable}{\l_@@_tmp_bool, \l_@@_tmpa_tl, \l_@@_tmpb_tl} % Scratch space. % \begin{macrocode} \bool_new:N \l_@@_tmp_bool +\tl_new:N \l_@@_tmpa_tl +\tl_new:N \l_@@_tmpb_tl % \end{macrocode} % \end{variable} % @@ -1274,7 +1305,7 @@ { \@@_define:onn \l_@@_module_tl } \cs_new_protected:Npn \@@_define:nnn #1#2#3 { - \tl_set:Nx \l_@@_module_tl { \@@_remove_spaces:n {#2} } + \tl_set:Nx \l_@@_module_tl { \@@_trim_spaces:n {#2} } \keyval_parse:NNn \@@_define:n \@@_define:nn {#3} \tl_set:Nn \l_@@_module_tl {#1} } @@ -1327,7 +1358,7 @@ % \begin{macrocode} \cs_new_protected:Npn \@@_property_find:n #1 { - \tl_set:Nx \l_@@_property_tl { \@@_remove_spaces:n {#1} } + \tl_set:Nx \l_@@_property_tl { \@@_trim_spaces:n {#1} } \exp_after:wN \@@_property_find:w \l_@@_property_tl . . \q_stop {#1} } @@ -1509,7 +1540,7 @@ { \int_incr:N \l_keys_choice_int \@@_cmd_set:nx - { \l_keys_path_tl / \@@_remove_spaces:n {##1} } + { \l_keys_path_tl / \@@_trim_spaces:n {##1} } { \tl_set:Nn \exp_not:N \l_keys_choice_tl {##1} \int_set:Nn \exp_not:N \l_keys_choice_int @@ -1552,7 +1583,7 @@ \tex_undefined:D } { - \cs_set:cpx + \cs_set_nopar:cpx { \c_@@_default_root_tl \l_keys_path_tl } { \exp_not:n {#1} } } @@ -1623,6 +1654,28 @@ % \end{macro} % \end{macro} % +% \begin{macro}{\@@_prop_put:Nn, \@@_prop_put:cn} +% Much the same as other variables, but needs a dedicated auxiliary. +% \begin{macrocode} +\cs_new_protected:Npn \@@_prop_put:Nn #1#2 + { + \prop_if_exist:NF #1 { \prop_new:N #1 } + \exp_after:wN \@@_find_key_module:NNw + \exp_after:wN \l_@@_tmpa_tl + \exp_after:wN \l_@@_tmpb_tl + \l_keys_path_tl / \q_stop + \@@_cmd_set:nx { \l_keys_path_tl } + { + \exp_not:c { prop_ #2 put:Nnn } + \exp_not:N #1 + { \l_@@_tmpb_tl } + \exp_not:n { {##1} } + } + } +\cs_generate_variant:Nn \@@_prop_put:Nn { c } +% \end{macrocode} +% \end{macro} +% % \begin{macro}{\@@_undefine:} % Undefining a key has to be done without \cs{cs_undefine:c} as that % function acts globally. @@ -1944,6 +1997,20 @@ % \end{macro} % \end{macro} % +% \begin{macro}{.prop_put:N, .prop_put:c, .prop_gput:N, .prop_gput:c} +% Setting a variable is very easy: just pass the data along. +% \begin{macrocode} +\cs_new_protected:cpn { \c_@@_props_root_tl .prop_put:N } #1 + { \@@_prop_put:Nn #1 { } } +\cs_new_protected:cpn { \c_@@_props_root_tl .prop_put:c } #1 + { \@@_prop_put:cn {#1} { } } +\cs_new_protected:cpn { \c_@@_props_root_tl .prop_gput:N } #1 + { \@@_prop_put:Nn #1 { g } } +\cs_new_protected:cpn { \c_@@_props_root_tl .prop_gput:c } #1 + { \@@_prop_put:cn {#1} { g } } +% \end{macrocode} +% \end{macro} +% % \begin{macro}{.skip_set:N, .skip_set:c} % \begin{macro}{.skip_gset:N, .skip_gset:c} % Setting a variable is very easy: just pass the data along. @@ -2010,20 +2077,43 @@ % % \subsection{Setting keys} % -% \begin{macro}{\keys_set:nn, \keys_set:nV, \keys_set:nv, \keys_set:no} -% \begin{macro}{\@@_set:nnn, \@@_set:onn} -% A simple wrapper again. +% \begin{macro} +% { +% \keys_set:nn, \keys_set:nV, \keys_set:nv, \keys_set:no, +% \@@_set:nn +% } +% \begin{macro}{\@@_set:nnn} +% A simple wrapper allowing for nesting. % \begin{macrocode} -\cs_new_protected:Npn \keys_set:nn - { \@@_set:onn { \l_@@_module_tl } } +\cs_new_protected:Npn \keys_set:nn #1#2 + { + \use:x + { + \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 } + } + } +\cs_generate_variant:Nn \keys_set:nn { nV , nv , no } +\cs_new_protected:Npn \@@_set:nn #1#2 + { \exp_args:No \@@_set:nnn \l_@@_module_tl {#1} {#2} } \cs_new_protected:Npn \@@_set:nnn #1#2#3 { - \tl_set:Nx \l_@@_module_tl { \@@_remove_spaces:n {#2} } - \keyval_parse:NNn \@@_set:n \@@_set:nn {#3} + \tl_set:Nx \l_@@_module_tl { \@@_trim_spaces:n {#2} } + \keyval_parse:NNn \@@_set_keyval:n \@@_set_keyval:nn {#3} \tl_set:Nn \l_@@_module_tl {#1} } -\cs_generate_variant:Nn \keys_set:nn { nV , nv , no } -\cs_generate_variant:Nn \@@_set:nnn { o } % \end{macrocode} % \end{macro} % \end{macro} @@ -2033,133 +2123,172 @@ % \keys_set_known:nnN, \keys_set_known:nVN, % \keys_set_known:nvN, \keys_set_known:noN % } -% \begin{macro}{\@@_set_known:nnnN, \@@_set_known:onnN} +% \begin{macro} +% { +% \keys_set_known:nnnN, \keys_set_known:nVnN, +% \keys_set_known:nvnN, \keys_set_known:nonN +% } +% \begin{macro}{\@@_set_known:nnnnN} % \begin{macro} % { % \keys_set_known:nn, \keys_set_known:nV, % \keys_set_known:nv, \keys_set_known:no % } -% \begin{macro}{\@@_keys_set_known:nn} +% \begin{macro}{\@@_set_known:nnn} % Setting known keys simply means setting the appropriate flag, 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! % \begin{macrocode} -\cs_new_protected:Npn \keys_set_known:nnN - { \@@_set_known:onnN \l_@@_unused_clist } +\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 , no } -\cs_new_protected:Npn \@@_set_known:nnnN #1#2#3#4 +\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 + } +\cs_generate_variant:Nn \keys_set_known:nnnN { nV , nv , no } +\cs_new_protected:Npn \@@_set_known:nnnnN #1#2#3#4#5 { \clist_clear:N \l_@@_unused_clist - \keys_set_known:nn {#2} {#3} - \tl_set:Nx #4 { \exp_not:o { \l_@@_unused_clist } } + \@@_set_known:nnn {#2} {#3} {#4} + \tl_set:Nx #5 { \exp_not:o { \l_@@_unused_clist } } \tl_set:Nn \l_@@_unused_clist {#1} } -\cs_generate_variant:Nn \@@_set_known:nnnN { o } \cs_new_protected:Npn \keys_set_known:nn #1#2 - { - \bool_if:NTF \l_@@_only_known_bool - { \keys_set:nn } - { \@@_set_known:nn } - {#1} {#2} - } + { \@@_set_known:nnn { \q_no_value } {#1} {#2} } \cs_generate_variant:Nn \keys_set_known:nn { nV , nv , no } -\cs_new_protected:Npn \@@_set_known:nn #1#2 +\cs_new_protected:Npn \@@_set_known:nnn #1#2#3 { - \bool_set_true:N \l_@@_only_known_bool - \keys_set:nn {#1} {#2} - \bool_set_false:N \l_@@_only_known_bool + \use:x + { + \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} % { % \keys_set_filter:nnnN, \keys_set_filter:nnVN, \keys_set_filter:nnvN, % \keys_set_filter:nnoN % } -% \begin{macro}{\@@_set_filter:nnnnN, \@@_set_filter:onnnN} +% \begin{macro} +% { +% \keys_set_filter:nnnnN, \keys_set_filter:nnVnN, +% \keys_set_filter:nnvnN, \keys_set_filter:nnonN +% } +% \begin{macro}{\@@_set_filter:nnnnnN} % \begin{macro} % { % \keys_set_filter:nnn, \keys_set_filter:nnV, \keys_set_filter:nnv, % \keys_set_filter:nno % } -% \begin{macro}{\@@_set_filter:nnn} +% \begin{macro}{\@@_set_filter:nnnn} % \begin{macro} % { % \keys_set_groups:nnn, \keys_set_groups:nnV, \keys_set_groups:nnv, % \keys_set_groups:nno % } -% \begin{macro}{\@@_set_groups:nnn} % \begin{macro}{\@@_set_selective:nnn} -% \begin{macro}{\@@_set_selective:nnnn, \@@_set_selective:onnn} -% \begin{macro}{\@@_set_selective:nn} +% \begin{macro}{\@@_set_selective:nnnn} % The idea of setting keys in a selective manner again uses flags % 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. % \begin{macrocode} -\cs_new_protected:Npn \keys_set_filter:nnnN - { \@@_set_filter:onnnN \l_@@_unused_clist } +\cs_new_protected:Npn \keys_set_filter:nnnN #1#2#3#4 + { + \exp_args:No \@@_set_filter:nnnnnN + \l_@@_unused_clist + { \q_no_value } {#1} {#2} {#3} #4 + } \cs_generate_variant:Nn \keys_set_filter:nnnN { nnV , nnv , nno } -\cs_new_protected:Npn \@@_set_filter:nnnnN #1#2#3#4#5 +\cs_new_protected:Npn \keys_set_filter:nnnnN #1#2#3#4#5 + { + \exp_args:No \@@_set_filter:nnnnnN + \l_@@_unused_clist {#4} {#1} {#2} {#3} #5 + } +\cs_generate_variant:Nn \keys_set_filter:nnnnN { nnV , nnv , nno } +\cs_new_protected:Npn \@@_set_filter:nnnnnN #1#2#3#4#5#6 { \clist_clear:N \l_@@_unused_clist - \keys_set_filter:nnn {#2} {#3} {#4} - \tl_set:Nx #5 { \exp_not:o { \l_@@_unused_clist } } + \@@_set_filter:nnnn {#2} {#3} {#4} {#5} + \tl_set:Nx #6 { \exp_not:o { \l_@@_unused_clist } } \tl_set:Nn \l_@@_unused_clist {#1} } -\cs_generate_variant:Nn \@@_set_filter:nnnnN { o } \cs_new_protected:Npn \keys_set_filter:nnn #1#2#3 - { - \bool_if:NTF \l_@@_filtered_bool - { \@@_set_selective:nnn } - { \@@_set_filter:nnn } - {#1} {#2} {#3} - } + {\@@_set_filter:nnnn { \q_no_value } {#1} {#2} {#3} } \cs_generate_variant:Nn \keys_set_filter:nnn { nnV , nnv , nno } -\cs_new_protected:Npn \@@_set_filter:nnn #1#2#3 +\cs_new_protected:Npn \@@_set_filter:nnnn #1#2#3#4 { - \bool_set_true:N \l_@@_filtered_bool - \@@_set_selective:nnn {#1} {#2} {#3} - \bool_set_false:N \l_@@_filtered_bool + \use:x + { + \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 } + } } \cs_new_protected:Npn \keys_set_groups:nnn #1#2#3 { - \bool_if:NTF \l_@@_filtered_bool - { \@@_set_groups:nnn } - { \@@_set_selective:nnn } - {#1} {#2} {#3} + \use:x + { + \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 } + } } \cs_generate_variant:Nn \keys_set_groups:nnn { nnV , nnv , nno } -\cs_new_protected:Npn \@@_set_groups:nnn #1#2#3 - { - \bool_set_false:N \l_@@_filtered_bool - \@@_set_selective:nnn {#1} {#2} {#3} - \bool_set_true:N \l_@@_filtered_bool - } \cs_new_protected:Npn \@@_set_selective:nnn - { \@@_set_selective:onnn \l_@@_selective_seq } + { \exp_args:No \@@_set_selective:nnnn \l_@@_selective_seq } \cs_new_protected:Npn \@@_set_selective:nnnn #1#2#3#4 { \seq_set_from_clist:Nn \l_@@_selective_seq {#3} - \bool_if:NTF \l_@@_selective_bool - { \keys_set:nn } - { \@@_set_selective:nn } - {#2} {#4} + \@@_set:nn {#2} {#4} \tl_set:Nn \l_@@_selective_seq {#1} } -\cs_generate_variant:Nn \@@_set_selective:nnnn { o } -\cs_new_protected:Npn \@@_set_selective:nn #1#2 - { - \bool_set_true:N \l_@@_selective_bool - \keys_set:nn {#1} {#2} - \bool_set_false:N \l_@@_selective_bool - } % \end{macrocode} % \end{macro} % \end{macro} @@ -2169,26 +2298,25 @@ % \end{macro} % \end{macro} % \end{macro} -% \end{macro} % -% \begin{macro}{\@@_set:n, \@@_set:nn} -% \begin{macro}{\@@_set_aux:nnn, \@@_set_aux:onn} -% \begin{macro}{\@@_find_key_module:w} -% \begin{macro}{\@@_set_aux:, \@@_set_selective:} +% \begin{macro}{\@@_set_keyval:n, \@@_set_keyval:nn} +% \begin{macro}{\@@_set_keyval:nnn, \@@_set_keyval:onn} +% \begin{macro}{\@@_find_key_module:NNw} +% \begin{macro}{\@@_set_selective:} % A shared system once again. First, set the current path and add a % default if needed. There are then checks to see if the a value is % required or forbidden. If everything passes, move on to execute the % code. % \begin{macrocode} -\cs_new_protected:Npn \@@_set:n #1 +\cs_new_protected:Npn \@@_set_keyval:n #1 { \bool_set_true:N \l_@@_no_value_bool - \@@_set_aux:onn \l_@@_module_tl {#1} { } + \@@_set_keyval:onn \l_@@_module_tl {#1} { } } -\cs_new_protected:Npn \@@_set:nn #1#2 +\cs_new_protected:Npn \@@_set_keyval:nn #1#2 { \bool_set_false:N \l_@@_no_value_bool - \@@_set_aux:onn \l_@@_module_tl {#1} {#2} + \@@_set_keyval:onn \l_@@_module_tl {#1} {#2} } % \end{macrocode} % The key path here can be fully defined, after which there is a search @@ -2197,34 +2325,38 @@ % that happens on a per-key basis, we use the stack approach to restore % the module name without a group. % \begin{macrocode} -\cs_new_protected:Npn \@@_set_aux:nnn #1#2#3 +\cs_new_protected:Npn \@@_set_keyval:nnn #1#2#3 { \tl_set:Nx \l_keys_path_tl { \tl_if_blank:nF {#1} { #1 / } - \@@_remove_spaces:n {#2} + \@@_trim_spaces:n {#2} } \tl_clear:N \l_@@_module_tl - \exp_after:wN \@@_find_key_module:w \l_keys_path_tl / \q_stop + \tl_clear:N \l_@@_inherit_tl + \exp_after:wN \@@_find_key_module:NNw + \exp_after:wN \l_@@_module_tl + \exp_after:wN \l_keys_key_tl + \l_keys_path_tl / \q_stop \@@_value_or_default:n {#3} \bool_if:NTF \l_@@_selective_bool { \@@_set_selective: } { \@@_execute: } \tl_set:Nn \l_@@_module_tl {#1} } -\cs_generate_variant:Nn \@@_set_aux:nnn { o } -\cs_new_protected:Npn \@@_find_key_module:w #1 / #2 \q_stop +\cs_generate_variant:Nn \@@_set_keyval:nnn { o } +\cs_new_protected:Npn \@@_find_key_module:NNw #1#2#3 / #4 \q_stop { - \tl_if_blank:nTF {#2} - { \tl_set:Nn \l_keys_key_tl {#1} } + \tl_if_blank:nTF {#4} + { \tl_set:Nn #2 {#3} } { - \tl_put_right:Nx \l_@@_module_tl + \tl_put_right:Nx #1 { - \tl_if_empty:NF \l_@@_module_tl { / } - #1 + \tl_if_empty:NF #1 { / } + #3 } - \@@_find_key_module:w #2 \q_stop + \@@_find_key_module:NNw #1#2 #4 \q_stop } } % \end{macrocode} @@ -2286,6 +2418,7 @@ % \end{macro} % % \begin{macro}{\@@_value_or_default:n} +% \begin{macro}{\@@_default_inherit:} % If a value is given, return it as |#1|, otherwise send a default if % available. % \begin{macrocode} @@ -2299,16 +2432,37 @@ \l_keys_value_tl { \c_@@_default_root_tl \l_keys_path_tl } } - { \tl_clear:N \l_keys_value_tl } + { + \tl_clear:N \l_keys_value_tl + \cs_if_exist:cT + { \c_@@_inherit_root_tl \@@_parent:o \l_keys_path_tl } + { \@@_default_inherit: } + } } { \tl_set:Nn \l_keys_value_tl {#1} } } +\cs_new_protected:Npn \@@_default_inherit: + { + \clist_map_inline:cn + { \c_@@_inherit_root_tl \@@_parent:o \l_keys_path_tl } + { + \cs_if_exist:cT + { \c_@@_default_root_tl ##1 / \l_keys_key_tl } + { + \tl_set_eq:Nc + \l_keys_value_tl + { \c_@@_default_root_tl ##1 / \l_keys_key_tl } + \clist_map_break: + } + } + } % \end{macrocode} % \end{macro} +% \end{macro} % % \begin{macro}{\@@_execute:, \@@_execute_inherit:, \@@_execute_unknown:} % \begin{macro}[EXP]{\@@_execute:nn} -% \begin{macro}{\@@_store_unused:} +% \begin{macro}{\@@_store_unused:,\@@_store_unused_aux:} % Actually executing a key is done in two parts. First, look for the % key itself, then look for the \texttt{unknown} key with the same % path. If both of these fail, complain. What exactly happens if a key @@ -2378,15 +2532,70 @@ } {#2} } +% \end{macrocode} +% When there is no relative path, things here are easy: just save the key +% name and value. When we are working with a relative path, first we +% need to turn it into a string: that can't happen earlier as we need +% to store |\q_no_value|. Then, use a standard delimited approach to fish +% out the partial path. +% \begin{macrocode} \cs_new_protected:Npn \@@_store_unused: { - \clist_put_right:Nx \l_@@_unused_clist + \quark_if_no_value:NTF \l_@@_relative_tl + { + \clist_put_right:Nx \l_@@_unused_clist + { + \exp_not:o \l_keys_key_tl + \bool_if:NF \l_@@_no_value_bool + { = { \exp_not:o \l_keys_value_tl } } + } + } + { + \tl_if_empty:NTF \l_@@_relative_tl + { + \clist_put_right:Nx \l_@@_unused_clist + { + \exp_not:o \l_keys_path_tl + \bool_if:NF \l_@@_no_value_bool + { = { \exp_not:o \l_keys_value_tl } } + } + } + { \@@_store_unused_aux: } + } + } +\cs_new_protected:Npn \@@_store_unused_aux: + { + \tl_set:Nx \l_@@_relative_tl + { \exp_args:No \@@_trim_spaces:n \l_@@_relative_tl } + \use:x + { + \cs_set_protected:Npn \@@_store_unused:w + ####1 \l_@@_relative_tl / + ####2 \l_@@_relative_tl / + ####3 \exp_not:N \q_stop + } + { + \tl_if_blank:nF {##1} + { + \__kernel_msg_error:nnxx { kernel } { bad-relative-key-path } + \l_keys_path_tl + \l_@@_relative_tl + } + \clist_put_right:Nx \l_@@_unused_clist + { + \exp_not:n {##2} + \bool_if:NF \l_@@_no_value_bool + { = { \exp_not:o \l_keys_value_tl } } + } + } + \use:x { - \exp_not:o \l_keys_key_tl - \bool_if:NF \l_@@_no_value_bool - { = { \exp_not:o \l_keys_value_tl } } + \@@_store_unused:w \l_keys_path_tl + \l_@@_relative_tl / \l_@@_relative_tl / + \exp_not:N \q_stop } } +\cs_new_protected:Npn \@@_store_unused:w { } % \end{macrocode} % \end{macro} % \end{macro} @@ -2411,8 +2620,8 @@ } \cs_new:Npn \@@_choice_find:nn #1#2 { - \cs_if_exist:cTF { \c_@@_code_root_tl #1 / \@@_remove_spaces:n {#2} } - { \use:c { \c_@@_code_root_tl #1 / \@@_remove_spaces:n {#2} } {#2} } + \cs_if_exist:cTF { \c_@@_code_root_tl #1 / \@@_trim_spaces:n {#2} } + { \use:c { \c_@@_code_root_tl #1 / \@@_trim_spaces:n {#2} } {#2} } { \use:c { \c_@@_code_root_tl #1 / unknown } {#2} } } \cs_new:Npn \@@_multichoice_find:n #1 @@ -2434,7 +2643,10 @@ \cs_new:Npn \@@_parent:w #1 / #2 / #3 \q_stop #4 { \tl_if_blank:nTF {#2} - { \use_none:n #4 } + { + \tl_if_blank:nF {#4} + { \use_none:n #4 } + } { \@@_parent:w #2 / #3 \q_stop { #4 / #1 } } @@ -2443,10 +2655,10 @@ % \end{macro} % \end{macro} % -% \begin{macro}[EXP]{\@@_remove_spaces:n} +% \begin{macro}[EXP]{\@@_trim_spaces:n} % Used in a few places so worth handling as a dedicated function. % \begin{macrocode} -\cs_new:Npn \@@_remove_spaces:n #1 +\cs_new:Npn \@@_trim_spaces:n #1 { \tl_trim_spaces:o { \tl_to_str:n {#1} } } % \end{macrocode} % \end{macro} @@ -2457,7 +2669,7 @@ \prg_new_conditional:Npnn \keys_if_exist:nn #1#2 { p , T , F , TF } { \cs_if_exist:cTF - { \c_@@_code_root_tl \@@_remove_spaces:n { #1 / #2 } } + { \c_@@_code_root_tl \@@_trim_spaces:n { #1 / #2 } } { \prg_return_true: } { \prg_return_false: } } @@ -2471,7 +2683,7 @@ { p , T , F , TF } { \cs_if_exist:cTF - { \c_@@_code_root_tl \@@_remove_spaces:n { #1 / #2 / #3 } } + { \c_@@_code_root_tl \@@_trim_spaces:n { #1 / #2 / #3 } } { \prg_return_true: } { \prg_return_false: } } @@ -2488,7 +2700,7 @@ \cs_new_protected:Npn \@@_show:Nnn #1#2#3 { #1 { LaTeX / kernel } { show-key } - { \@@_remove_spaces:n { #2 / #3 } } + { \@@_trim_spaces:n { #2 / #3 } } { \keys_if_exist:nnT {#2} {#3} { @@ -2497,7 +2709,7 @@ \exp_args:Nc \token_get_replacement_spec:N { \c_@@_code_root_tl - \@@_remove_spaces:n { #2 / #3 } + \@@_trim_spaces:n { #2 / #3 } } } } @@ -2511,6 +2723,9 @@ % % For when there is a need to complain. % \begin{macrocode} +\__kernel_msg_new:nnnn { kernel } { bad-relative-key-path } + { The~key~'#1'~is~not~inside~the~'#2'~path. } + { The~key~'#1'~cannot~be~expressed~relative~to~path~'#2'. } \__kernel_msg_new:nnnn { kernel } { boolean-values-only } { Key~'#1'~accepts~boolean~values~only. } { The~key~'#1'~only~accepts~the~values~'true'~and~'false'. } |