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.dtx179
1 files changed, 79 insertions, 100 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx b/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx
index aee66866591..c6d11150a4d 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx
@@ -7,7 +7,7 @@
% license or (at your option) any later version. The latest version
% of this license is in the file
%
-% http://www.latex-project.org/lppl.txt
+% https://www.latex-project.org/lppl.txt
%
% This file is part of the "l3kernel bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
@@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
-\documentclass[full]{l3doc}
+\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
@@ -41,7 +41,7 @@
% }^^A
% }
%
-% \date{Released 2017/11/14}
+% \date{Released 2017/12/05}
%
% \maketitle
%
@@ -935,8 +935,8 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[aux]{\@@_sanitise_equals:, \@@_sanitise_comma:}
-% \begin{macro}[aux]
+% \begin{macro}{\@@_sanitise_equals:, \@@_sanitise_comma:}
+% \begin{macro}
% {
% \@@_sanitise_equals_auxi:w, \@@_sanitise_equals_auxii:w,
% \@@_sanitise_comma_auxi:w, \@@_sanitise_comma_auxii:w,
@@ -1007,7 +1007,7 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[aux]{\@@_loop:NNw}
+% \begin{macro}{\@@_loop:NNw}
% A fast test for the end of the loop, remembering to remove the leading
% quark first. Assuming that is not the case, look for a key and value then
% loop around, re-inserting a leading quark in front of the next position.
@@ -1025,9 +1025,9 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[aux]{\@@_split:NNw, \@@_split_value:NNw}
-% \begin{macro}[aux]{\@@_split_tidy:w}
-% \begin{macro}[aux]{\@@_action:}
+% \begin{macro}{\@@_split:NNw, \@@_split_value:NNw}
+% \begin{macro}{\@@_split_tidy:w}
+% \begin{macro}{\@@_action:}
% The value is picked up separately from the key so there can be another
% quark inserted at the front, keeping braces and allowing both parts to
% share the same code paths. The key is found first then there's a check
@@ -1085,9 +1085,9 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[aux]{\@@_def:Nn}
-% \begin{macro}[aux, EXP]{\@@_def_aux:n}
-% \begin{macro}[aux, EXP]{\@@_def_aux:w}
+% \begin{macro}{\@@_def:Nn}
+% \begin{macro}[EXP]{\@@_def_aux:n}
+% \begin{macro}[EXP]{\@@_def_aux:w}
% First trim spaces off, then potentially remove a set of braces. By using
% the internal interface |\__tl_trim_spaces:nn| we can take advantage of the
% fact it needs a leading |\q_mark| in this process. The |\exp_after:wN|
@@ -1250,7 +1250,7 @@
% \subsection{The key defining mechanism}
%
% \begin{macro}{\keys_define:nn}
-% \begin{macro}[aux]{\@@_define:nnn, \@@_define:onn}
+% \begin{macro}{\@@_define:nnn, \@@_define:onn}
% The public function for definitions is just a wrapper for the lower
% level mechanism, more or less. The outer function is designed to
% keep a track of the current module, to allow safe nesting. The module is set
@@ -1269,9 +1269,9 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[int]{\@@_define:n}
-% \begin{macro}[int]{\@@_define:nn}
-% \begin{macro}[aux]{\@@_define_aux:nn}
+% \begin{macro}{\@@_define:n}
+% \begin{macro}{\@@_define:nn}
+% \begin{macro}{\@@_define_aux:nn}
% The outer functions here record whether a value was given and then
% converge on a common internal mechanism. There is first a search for
% a property in the current key name, then a check to make sure it is
@@ -1305,8 +1305,8 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[int]{\@@_property_find:n}
-% \begin{macro}[aux]{\@@_property_find:w}
+% \begin{macro}{\@@_property_find:n}
+% \begin{macro}{\@@_property_find:w}
% Searching for a property means finding the last |.| in the input,
% and storing the text before and after it. Everything is turned into
% strings, so there is no problem using an \texttt{x}-type expansion.
@@ -1356,8 +1356,8 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[int]{\@@_define_code:n}
-% \begin{macro}[aux, EXP]{\@@_define_code:w}
+% \begin{macro}{\@@_define_code:n}
+% \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,
@@ -1391,7 +1391,7 @@
%
% \subsection{Turning properties into actions}
%
-% \begin{macro}[int]{\@@_bool_set:Nn, \@@_bool_set:cn}
+% \begin{macro}{\@@_bool_set:Nn, \@@_bool_set:cn}
% Boolean keys are really just choices, but all done by hand. The
% second argument here is the scope: either empty or \texttt{ g } for
% global.
@@ -1415,7 +1415,7 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[int]{\@@_bool_set_inverse:Nn, \@@_bool_set_inverse:cn}
+% \begin{macro}{\@@_bool_set_inverse:Nn, \@@_bool_set_inverse:cn}
% Inverse boolean setting is much the same.
% \begin{macrocode}
\cs_new_protected:Npn \@@_bool_set_inverse:Nn #1#2
@@ -1437,9 +1437,9 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[int]{\@@_choice_make:, \@@_multichoice_make:}
-% \begin{macro}[aux]{\@@_choice_make:N}
-% \begin{macro}[aux]{\@@_choice_make_aux:N}
+% \begin{macro}{\@@_choice_make:, \@@_multichoice_make:}
+% \begin{macro}{\@@_choice_make:N}
+% \begin{macro}{\@@_choice_make_aux:N}
% To make a choice from a key, two steps: set the code, and set the
% unknown key. As multichoices and choices are essentially the same bar one
% function, the code is given together.
@@ -1479,8 +1479,8 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[int]{\@@_choices_make:nn, \@@_multichoices_make:nn}
-% \begin{macro}[aux]{\@@_choices_make:Nnn}
+% \begin{macro}{\@@_choices_make:nn, \@@_multichoices_make:nn}
+% \begin{macro}{\@@_choices_make:Nnn}
% Auto-generating choices means setting up the root key as a choice, then
% defining each choice in turn.
% \begin{macrocode}
@@ -1508,7 +1508,7 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[int]
+% \begin{macro}
% {\@@_cmd_set:nn, \@@_cmd_set:nx, \@@_cmd_set:Vn, \@@_cmd_set:Vo}
% Setting the code for a key first logs if appropriate that we are
% defining a new key, then saves the code.
@@ -1525,7 +1525,7 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[int]{\@@_default_set:n}
+% \begin{macro}{\@@_default_set:n}
% Setting a default value is easy. These are stored using \cs{cs_set:cpx} as this
% avoids any worries about whether a token list exists.
% \begin{macrocode}
@@ -1546,7 +1546,7 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[int]{\@@_groups_set:n}
+% \begin{macro}{\@@_groups_set:n}
% Assigning a key to one or more groups uses comma lists. As the list of
% groups only exists if there is anything to do, the setting is done using
% a scratch list. For the usual grouping reasons we use the low-level
@@ -1569,7 +1569,7 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[int]{\@@_inherit:n}
+% \begin{macro}{\@@_inherit:n}
% Inheritance means ignoring anything already said about the key:
% zap the lot and set up.
% \begin{macrocode}
@@ -1581,7 +1581,7 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[int]{\@@_initialise:n}
+% \begin{macro}{\@@_initialise:n}
% A set up for initialisation: just run the code if it exists.
% \begin{macrocode}
\cs_new_protected:Npn \@@_initialise:n #1
@@ -1591,8 +1591,8 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[int]{\@@_meta_make:n}
-% \begin{macro}[int]{\@@_meta_make:nn}
+% \begin{macro}{\@@_meta_make:n}
+% \begin{macro}{\@@_meta_make:nn}
% To create a meta-key, simply set up to pass data through.
% \begin{macrocode}
\cs_new_protected:Npn \@@_meta_make:n #1
@@ -1609,7 +1609,7 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[int]{\@@_undefine:}
+% \begin{macro}{\@@_undefine:}
% Undefining a key has to be done without \cs{cs_undefine:c} as that
% function acts globally.
% \begin{macrocode}
@@ -1626,9 +1626,9 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[int]{\@@_value_requirement:nn}
-% \begin{macro}[aux]{\@@_validate_forbidden:, \@@_validate_required:}
-% \begin{macro}[aux]{\@@_validate_cleanup:w}
+% \begin{macro}{\@@_value_requirement:nn}
+% \begin{macro}{\@@_validate_forbidden:, \@@_validate_required:}
+% \begin{macro}{\@@_validate_cleanup:w}
% Validating key input is done using a second function which runs before
% the main key code. Setting that up means setting it equal to a generic
% stub which does the check. This approach makes the lookup very fast at
@@ -1686,7 +1686,7 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[int]{\@@_variable_set:NnnN, \@@_variable_set:cnnN}
+% \begin{macro}{\@@_variable_set:NnnN, \@@_variable_set:cnnN}
% Setting a variable takes the type and scope separately so that
% it is easy to make a new variable if needed.
% \begin{macrocode}
@@ -1996,7 +1996,7 @@
% \subsection{Setting keys}
%
% \begin{macro}{\keys_set:nn, \keys_set:nV, \keys_set:nv, \keys_set:no}
-% \begin{macro}[aux]{\@@_set:nnn, \@@_set:onn}
+% \begin{macro}{\@@_set:nnn, \@@_set:onn}
% A simple wrapper again.
% \begin{macrocode}
\cs_new_protected:Npn \keys_set:nn
@@ -2018,13 +2018,13 @@
% \keys_set_known:nnN, \keys_set_known:nVN,
% \keys_set_known:nvN, \keys_set_known:noN
% }
-% \begin{macro}[aux]{\@@_set_known:nnnN, \@@_set_known:onnN}
+% \begin{macro}{\@@_set_known:nnnN, \@@_set_known:onnN}
% \begin{macro}
% {
% \keys_set_known:nn, \keys_set_known:nV,
% \keys_set_known:nv, \keys_set_known:no
% }
-% \begin{macro}[aux]{\@@_keys_set_known:nn}
+% \begin{macro}{\@@_keys_set_known:nn}
% 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
@@ -2067,22 +2067,22 @@
% \keys_set_filter:nnnN, \keys_set_filter:nnVN, \keys_set_filter:nnvN,
% \keys_set_filter:nnoN
% }
-% \begin{macro}[aux]{\@@_set_filter:nnnnN, \@@_set_filter:onnnN}
+% \begin{macro}{\@@_set_filter:nnnnN, \@@_set_filter:onnnN}
% \begin{macro}
% {
% \keys_set_filter:nnn, \keys_set_filter:nnV, \keys_set_filter:nnv,
% \keys_set_filter:nno
% }
-% \begin{macro}[aux]{\@@_set_filter:nnn}
+% \begin{macro}{\@@_set_filter:nnn}
% \begin{macro}
% {
% \keys_set_groups:nnn, \keys_set_groups:nnV, \keys_set_groups:nnv,
% \keys_set_groups:nno
% }
-% \begin{macro}[aux]{\@@_set_groups:nnn}
-% \begin{macro}[aux]{\@@_set_selective:nnn}
-% \begin{macro}[aux]{\@@_set_selective:nnnn, \@@_set_selective:onnn}
-% \begin{macro}[aux]{\@@_set_selective:nn}
+% \begin{macro}{\@@_set_groups:nnn}
+% \begin{macro}{\@@_set_selective:nnn}
+% \begin{macro}{\@@_set_selective:nnnn, \@@_set_selective:onnn}
+% \begin{macro}{\@@_set_selective:nn}
% 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
@@ -2156,10 +2156,10 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[int]{\@@_set:n, \@@_set:nn}
-% \begin{macro}[aux]{\@@_set_aux:nnn, \@@_set_aux:onn}
-% \begin{macro}[aux]{\@@_find_key_module:w}
-% \begin{macro}[aux]{\@@_set_aux:, \@@_set_selective:}
+% \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:}
% 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
@@ -2270,7 +2270,7 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[int]{\@@_value_or_default:n}
+% \begin{macro}{\@@_value_or_default:n}
% If a value is given, return it as |#1|, otherwise send a default if
% available.
% \begin{macrocode}
@@ -2291,9 +2291,9 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[aux]{\@@_execute:, \@@_execute_unknown:}
-% \begin{macro}[aux, EXP]{\@@_execute:nn}
-% \begin{macro}[aux]{\@@_store_unused:}
+% \begin{macro}{\@@_execute:, \@@_execute_unknown:}
+% \begin{macro}[EXP]{\@@_execute:nn}
+% \begin{macro}{\@@_store_unused:}
% 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
@@ -2367,8 +2367,8 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[int, EXP]{\@@_choice_find:n}
-% \begin{macro}[int, EXP]{\@@_multichoice_find:n}
+% \begin{macro}[EXP]{\@@_choice_find:n}
+% \begin{macro}[EXP]{\@@_multichoice_find:n}
% Executing a choice has two parts. First, try the choice given, then
% if that fails call the unknown key. That always exists, as it is created
% when a choice is first made. So there is no need for any escape code.
@@ -2387,8 +2387,8 @@
%
% \subsection{Utilities}
%
-% \begin{macro}[EXP, int]{\@@_parent:n, \@@_parent:o}
-% \begin{macro}[EXP, aux]{\@@_parent:w}
+% \begin{macro}[EXP]{\@@_parent:n, \@@_parent:o}
+% \begin{macro}[EXP]{\@@_parent:w}
% Used to strip off the ending part of the key path after the last~|/|.
% \begin{macrocode}
\cs_new:Npn \@@_parent:n #1
@@ -2406,7 +2406,7 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[EXP, int]{\@@_remove_spaces:n}
+% \begin{macro}[EXP]{\@@_remove_spaces:n}
% Used in a few places so worth handling as a dedicated function.
% \begin{macrocode}
\cs_new:Npn \@@_remove_spaces:n #1
@@ -2441,52 +2441,31 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\keys_show:nn}
-% \begin{macro}[aux]{\@@_show:N}
-% To show a key, test for its existence to issue the correct message
-% (same message, but with a |t| or |f| argument, then build the
-% control sequences which contain the code and other information
-% about the key, call an intermediate auxiliary which constructs the
-% code to be displayed to the terminal, and finally conclude
-% with \cs{__msg_show_wrap:n}.
+% \begin{macro}{\keys_show:nn, \keys_log:nn, \@@_show:Nnn}
+% To show a key, show its code using a message.
% \begin{macrocode}
-\cs_new_protected:Npn \keys_show:nn #1#2
- {
- \keys_if_exist:nnTF {#1} {#2}
- {
- \__msg_show_pre:nnxxxx { LaTeX / kernel } { show-key }
- { \@@_remove_spaces:n { #1 / #2 } } { t } { } { }
- \exp_args:Nc \@@_show:N
- { \c_@@_code_root_tl \@@_remove_spaces:n { #1 / #2 } }
- }
- {
- \__msg_show_pre:nnxxxx { LaTeX / kernel } { show-key }
- { \@@_remove_spaces:n { #1 / #2 } } { f } { } { }
- \__msg_show_wrap:n { }
- }
- }
-\cs_new_protected:Npn \@@_show:N #1
+\cs_new_protected:Npn \keys_show:nn
+ { \@@_show:Nnn \msg_show:nnxxxx }
+\cs_new_protected:Npn \keys_log:nn
+ { \@@_show:Nnn \msg_log:nnxxxx }
+\cs_new_protected:Npn \@@_show:Nnn #1#2#3
{
- \use:x
+ #1 { LaTeX / kernel } { show-key }
+ { \@@_remove_spaces:n { #2 / #3 } }
{
- \__msg_show_wrap:n
+ \keys_if_exist:nnT {#2} {#3}
{
- \exp_not:N \__msg_show_item_unbraced:nn { code }
- { \token_get_replacement_spec:N #1 }
+ \exp_args:Nnf \msg_show_item_unbraced:nn { code }
+ {
+ \exp_args:Nc \token_get_replacement_spec:N
+ { \c_@@_code_root_tl \@@_remove_spaces:n { #2 / #3 } }
+ }
}
}
+ { } { }
}
% \end{macrocode}
% \end{macro}
-% \end{macro}
-%
-% \begin{macro}{\keys_log:nn}
-% Redirect output of \cs{keys_show:nn} to the log.
-% \begin{macrocode}
-\cs_new_protected:Npn \keys_log:nn
- { \__msg_log_next: \keys_show:nn }
-% \end{macrocode}
-% \end{macro}
%
% \subsection{Messages}
%
@@ -2557,9 +2536,9 @@
\__msg_kernel_new:nnn { kernel } { show-key }
{
The~key~#1~
- \str_if_eq:nnTF {#2} { t }
- { has~the~properties: }
+ \tl_if_empty:nTF {#2}
{ is~undefined. }
+ { has~the~properties: #2 . }
}
% \end{macrocode}
%