diff options
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3keys.dtx')
-rw-r--r-- | macros/latex/contrib/l3kernel/l3keys.dtx | 177 |
1 files changed, 158 insertions, 19 deletions
diff --git a/macros/latex/contrib/l3kernel/l3keys.dtx b/macros/latex/contrib/l3kernel/l3keys.dtx index 51bfbec712..dab5a8f423 100644 --- a/macros/latex/contrib/l3kernel/l3keys.dtx +++ b/macros/latex/contrib/l3kernel/l3keys.dtx @@ -2,7 +2,7 @@ % %% File: l3keys.dtx % -% Copyright (C) 2006-2021 The LaTeX Project +% Copyright (C) 2006-2022 The LaTeX Project % % It may be distributed and/or modified under the conditions of the % LaTeX Project Public License (LPPL), either version 1.3c of this @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2021-11-22} +% \date{Released 2022-01-12} % % \maketitle % @@ -358,6 +358,24 @@ % require a value at point-of-use unless a default is set. % \end{function} % +% \begin{function}[updated = 2021-11-22] +% { +% .legacy_if_set:n, .legacy_if_gset:n, +% .legacy_if_set_inverse:n, .legacy_if_gset_inverse:n +% } +% \begin{syntax} +% \meta{key} .legacy_if_set:n = \meta{switch} +% \end{syntax} +% Defines \meta{key} to set legacy \cs{if} \meta{switch} to \meta{value} +% (which must be either \enquote{\texttt{true}} or \enquote{\texttt{false}}). +% The \meta{switch} is the name of the switch \emph{without the leading +% \cs{if}}. Note that in contrast to \pkg{expl3} variables, the \meta{switch} +% will \emph{not} be created if it does not exist. +% +% The \texttt{inverse} versions will set the \meta{switch} to the logical +% opposite of the \meta{value}. +% \end{function} +% % \begin{function}[updated = 2013-07-10]{.meta:n} % \begin{syntax} % \meta{key} .meta:n = \Arg{keyval list} @@ -661,6 +679,31 @@ % \cs{l_keys_choice_tl} and \cs{l_keys_choice_int} in exactly % the same way as described for \texttt{.choices:nn}. % +% \subsection{Key usage scope} +% +% Some keys will be used as settings which have a strictly limited scope +% of usage. Some will be only available once, others will only be valid +% until typesetting begins. To allow formats to support this in a structured +% way, \pkg{l3keys} allows this information to be specified using the +% \texttt{.usage:n} property. +% +% \begin{function}[added = 2022-01-10]{.usage:n} +% \begin{syntax} +% \meta{key} .usage:n = \meta{scope} +% \end{syntax} +% Defines the \meta{key} to have usage within the \meta{scope}, which +% should be one of \texttt{general}, \texttt{preamble} or \texttt{load}. +% \end{function} +% +% \begin{variable}[added = 2022-01-10] +% {\l_keys_usage_load_prop, \l_keys_usage_preamble_prop} +% \pkg{l3keys} itself does \emph{not} attempt to redefine keys based on the +% usage scope. Rather, this information is made available with these +% two property lists. These hold an entry for each module (prefix); the +% value of each entry is a comma-separated list of the usage-restricted +% key(s). +% \end{variable} +% % \section{Setting keys} % % \begin{function}[updated = 2017-11-14] @@ -831,7 +874,8 @@ % % \section{Utility functions for keys} % -% \begin{function}[EXP, pTF, updated = 2017-11-14]{\keys_if_exist:nn} +% \begin{function}[EXP, pTF, updated = 2022-01-10] +% {\keys_if_exist:nn, \keys_if_exist:ne} % \begin{syntax} % \cs{keys_if_exist_p:nn} \Arg{module} \Arg{key} \\ % \cs{keys_if_exist:nnTF} \Arg{module} \Arg{key} \Arg{true code} \Arg{false code} @@ -1461,20 +1505,20 @@ % \begin{variable} % { % \c_@@_code_root_str , +% \c_@@_check_root_str , % \c_@@_default_root_str , % \c_@@_groups_root_str , -% \c_@@_inherit_root_str , -% \c_@@_type_root_str , -% \c_@@_validate_root_str +% \c_@@_inherit_root_str , +% \c_@@_type_root_str % } % Various storage areas for the different data which make up keys. % \begin{macrocode} \str_const:Nn \c_@@_code_root_str { key~code~>~ } +\str_const:Nn \c_@@_check_root_str { key~check~>~ } \str_const:Nn \c_@@_default_root_str { key~default~>~ } \str_const:Nn \c_@@_groups_root_str { key~groups~>~ } \str_const:Nn \c_@@_inherit_root_str { key~inherit~>~ } \str_const:Nn \c_@@_type_root_str { key~type~>~ } -\str_const:Nn \c_@@_validate_root_str { key~validate~>~ } % \end{macrocode} % \end{variable} % @@ -1607,6 +1651,14 @@ % \end{macrocode} % \end{variable} % +% \begin{variable}{\l_keys_usage_load_prop, \l_keys_usage_preamble_prop} +% Global data for document-level information. +% \begin{macrocode} +\prop_new:N \l_keys_usage_load_prop +\prop_new:N \l_keys_usage_preamble_prop +% \end{macrocode} +% \end{variable} +% % \subsubsection{Internal auxiliaries} % % \begin{variable}{\s_@@_nil,\s_@@_mark,\s_@@_stop} @@ -1916,7 +1968,7 @@ % \end{macro} % % \begin{macro}{\@@_default_set:n} -% Setting a default value is easy. These are stored using \cs{cs_set:cpx} as this +% Setting a default value is easy. These are stored using \cs{cs_set_nopar:cpx} as this % avoids any worries about whether a token list exists. % \begin{macrocode} \cs_new_protected:Npn \@@_default_set:n #1 @@ -2060,7 +2112,7 @@ \cs_new_protected:Npn \@@_undefine: { \clist_map_inline:nn - { code , default , groups , inherit , type , validate } + { code , default , groups , inherit , type , check } { \cs_set_eq:cN { \tl_use:c { c_@@_ ##1 _root_str } \l_keys_path_str } @@ -2071,7 +2123,7 @@ % \end{macro} % % \begin{macro}{\@@_value_requirement:nn} -% \begin{macro}{\@@_validate_forbidden:, \@@_validate_required:} +% \begin{macro}{\@@_check_forbidden:, \@@_check_required:} % 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 @@ -2085,17 +2137,17 @@ { true } { \cs_set_eq:cc - { \c_@@_validate_root_str \l_keys_path_str } - { @@_validate_ #1 : } + { \c_@@_check_root_str \l_keys_path_str } + { @@_check_ #1 : } } { false } { \cs_if_eq:ccT - { \c_@@_validate_root_str \l_keys_path_str } - { @@_validate_ #1 : } + { \c_@@_check_root_str \l_keys_path_str } + { @@_check_ #1 : } { \cs_set_eq:cN - { \c_@@_validate_root_str \l_keys_path_str } + { \c_@@_check_root_str \l_keys_path_str } \tex_undefined:D } } @@ -2106,7 +2158,7 @@ { .value_ #1 :n } } } -\cs_new_protected:Npn \@@_validate_forbidden: +\cs_new_protected:Npn \@@_check_forbidden: { \bool_if:NF \l_@@_no_value_bool { @@ -2115,7 +2167,7 @@ \use_none:nnn } } -\cs_new_protected:Npn \@@_validate_required: +\cs_new_protected:Npn \@@_check_required: { \bool_if:NT \l_@@_no_value_bool { @@ -2128,6 +2180,62 @@ % \end{macro} % \end{macro} % +% \begin{macro}{\@@_usage:n} +% \begin{macro}{\@@_usage:NN} +% \begin{macro}{\@@_usage:w} +% Save the relevant data. +% \begin{macrocode} +\cs_new_protected:Npn \@@_usage:n #1 + { + \str_case:nnF {#1} + { + { general } + { + \@@_usage:NN \l_keys_usage_load_prop + \c_false_bool + \@@_usage:NN \l_keys_usage_preamble_prop + \c_false_bool + } + { load } + { + \@@_usage:NN \l_keys_usage_load_prop + \c_true_bool + \@@_usage:NN \l_keys_usage_preamble_prop + \c_false_bool + } + { preamble } + { + \@@_usage:NN \l_keys_usage_load_prop + \c_false_bool + \@@_usage:NN \l_keys_usage_preamble_prop + \c_true_bool + } + } + { + \msg_error:nnnn { keys } + { choice-unknown } + { .usage:n } + {#1} + } + } +\cs_new_protected:Npn \@@_usage:NN #1#2 + { + \prop_get:NVNF #1 \l_@@_module_str \l_@@_tmpa_tl + { \tl_clear:N \l_@@_tmpa_tl } + \tl_set:Nx \l_@@_tmpb_tl + { \exp_after:wN \@@_usage:w \l_keys_path_str \s_@@_stop } + \bool_if:NTF #2 + { \clist_put_right:NV \l_@@_tmpa_tl \l_@@_tmpb_tl } + { \clist_remove_all:NV \l_@@_tmpa_tl \l_@@_tmpb_tl } + \prop_put:NVV #1 \l_@@_module_str + \l_@@_tmpa_tl + } +\cs_new:Npn \@@_usage:w #1 / #2 \s_@@_stop {#2} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% % \begin{macro}{\@@_variable_set:NnnN, \@@_variable_set:cnnN} % \begin{macro}{\@@_variable_set_required:NnnN, \@@_variable_set_required:cnnN} % Setting a variable takes the type and scope separately so that @@ -2529,6 +2637,13 @@ % \end{macrocode} % \end{macro} % +% \begin{macro}{.usage:n} +% \begin{macrocode} +\cs_new_protected:cpn { \c_@@_props_root_str .usage:n } #1 + { \@@_usage:n {#1} } +% \end{macrocode} +% \end{macro} +% % \begin{macro}{.value_forbidden:n} % \begin{macro}{.value_required:n} % These are very similar, so both call the same function. @@ -2541,6 +2656,29 @@ % \end{macro} % \end{macro} % +% \subsection{Key properties for \LaTeXe{} options} +% +% \begin{macro}{.if, .store, .usage} +% \begin{macrocode} +\group_begin: + \cs_set_protected:Npn \@@_tmp:nn #1#2 + { + \quark_if_recursion_tail_stop:n {#1} + \cs_new_eq:cc + { \c_@@_props_root_str . #2 } + { \c_@@_props_root_str . #1 } + \@@_tmp:nn + } + \@@_tmp:nn + { legacy_if:n } { if } + { tl_set:N } { store } + { usage:n } { usage } + { \q_recursion_tail } { } + \q_recursion_stop +\group_end: +% \end{macrocode} +% \end{macro} +% % \subsection{Setting keys} % % \begin{macro} @@ -2968,7 +3106,7 @@ { \cs_if_exist:cTF { \c_@@_code_root_str \l_keys_path_str } { - \cs_if_exist_use:c { \c_@@_validate_root_str \l_keys_path_str } + \cs_if_exist_use:c { \c_@@_check_root_str \l_keys_path_str } \@@_execute:no \l_keys_path_str \l_keys_value_tl } { @@ -2992,7 +3130,7 @@ { \c_@@_code_root_str ##1 / \l_keys_key_str } { \str_set:Nn \l_@@_inherit_str {##1} - \cs_if_exist_use:c { \c_@@_validate_root_str ##1 / \l_keys_key_str } + \cs_if_exist_use:c { \c_@@_check_root_str ##1 / \l_keys_key_str } \@@_execute:no { ##1 / \l_keys_key_str } \l_keys_value_tl \clist_map_break:n \use_none:n } @@ -3231,6 +3369,7 @@ { \prg_return_true: } { \prg_return_false: } } +\prg_generate_conditional_variant:Nnn \keys_if_exist:nn { ne } { T , F , TF } % \end{macrocode} % \end{macro} % |