summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3keys.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3keys.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/l3keys.dtx177
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}
%