summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3keys.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3keys.dtx479
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'. }