diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3keys.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3keys.dtx | 179 |
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} % |