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.dtx125
1 files changed, 111 insertions, 14 deletions
diff --git a/macros/latex/contrib/l3kernel/l3keys.dtx b/macros/latex/contrib/l3kernel/l3keys.dtx
index 360a008995..81eb124edd 100644
--- a/macros/latex/contrib/l3kernel/l3keys.dtx
+++ b/macros/latex/contrib/l3kernel/l3keys.dtx
@@ -43,7 +43,7 @@
% }^^A
% }
%
-% \date{Released 2022-02-24}
+% \date{Released 2022-04-10}
%
% \maketitle
%
@@ -882,6 +882,18 @@
% group and are thus never set.
% \end{function}
%
+% \section{Digesting keys}
+%
+% \begin{function}[added = 2022-03-09]{\keys_precompile:nnN}
+% \begin{syntax}
+% \cs{keys_precompile:nnN} \Arg{module} \Arg{keyval list} \meta{tl}
+% \end{syntax}
+% Parses the \meta{keyval list} as for \cs{keys_set:nn}, placing the
+% resulting code for those which set variables or functions into the
+% \meta{tl}. Thus this function \enquote{precompiles} the keyval list into
+% a set of results which can be applied rapidly.
+% \end{function}
+%
% \section{Utility functions for keys}
%
% \begin{function}[EXP, pTF, updated = 2022-01-10]
@@ -1661,6 +1673,14 @@
% \end{macrocode}
% \end{variable}
%
+% \begin{variable}{\l_@@_precompile_bool, \l_@@_precompile_tl}
+% For digesting keys.
+% \begin{macrocode}
+\bool_new:N \l_@@_precompile_bool
+\tl_new:N \l_@@_precompile_tl
+% \end{macrocode}
+% \end{variable}
+%
% \begin{variable}{\l_keys_usage_load_prop, \l_keys_usage_preamble_prop}
% Global data for document-level information.
% \begin{macrocode}
@@ -1694,6 +1714,19 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\@@_precompile:n}
+% An auxiliary to allow cleaner showing of code.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_precompile:n #1
+ {
+ \bool_if:NTF \l_@@_precompile_bool
+ { \tl_put_right:Nn \l_@@_precompile_tl }
+ { \use:n }
+ {#1}
+ }
+% \end{macrocode}
+% \end{macro}
+%
% \subsection{The key defining mechanism}
%
% \begin{macro}{\keys_define:nn}
@@ -1866,7 +1899,7 @@
{ \exp_not:c { bool_ #2 set_ #3 :N } \exp_not:N #1 }
\@@_cmd_set:nx { \l_keys_path_str / false }
{ \exp_not:c { bool_ #2 set_ #4 :N } \exp_not:N #1 }
- \@@_cmd_set:nn { \l_keys_path_str / unknown }
+ \@@_cmd_set_direct:nn { \l_keys_path_str / unknown }
{
\msg_error:nnx { keys } { boolean-values-only }
\l_keys_key_str
@@ -1909,8 +1942,8 @@
{
\cs_set_nopar:cpn { \c_@@_type_root_str \l_keys_path_str }
{ choice }
- \@@_cmd_set:nn \l_keys_path_str { #1 {##1} }
- \@@_cmd_set:nn { \l_keys_path_str / unknown }
+ \@@_cmd_set_direct:nn \l_keys_path_str { #1 {##1} }
+ \@@_cmd_set_direct:nn { \l_keys_path_str / unknown }
{
\msg_error:nnxx { keys } { choice-unknown }
\l_keys_path_str {##1}
@@ -1952,13 +1985,18 @@
% \end{macro}
%
% \begin{macro}
-% {\@@_cmd_set:nn, \@@_cmd_set:nx, \@@_cmd_set:Vn, \@@_cmd_set:Vo}
+% {
+% \@@_cmd_set:nn, \@@_cmd_set:nx, \@@_cmd_set:Vn, \@@_cmd_set:Vo,
+% \@@_cmd_set_direct:nn
+% }
% Setting the code for a key first logs if appropriate that we are
% defining a new key, then saves the code.
% \begin{macrocode}
\cs_new_protected:Npn \@@_cmd_set:nn #1#2
- { \cs_set_protected:cpn { \c_@@_code_root_str #1 } ##1 {#2} }
+ { \@@_cmd_set_direct:nn {#1} { \@@_precompile:n {#2} } }
\cs_generate_variant:Nn \@@_cmd_set:nn { nx , Vn , Vo }
+\cs_new_protected:Npn \@@_cmd_set_direct:nn #1#2
+ { \cs_set_protected:cpn { \c_@@_code_root_str #1 } ##1 {#2} }
% \end{macrocode}
% \end{macro}
%
@@ -1970,7 +2008,10 @@
\cs_new_protected:Npn \@@_cs_set:NNpn #1#2#3#
{
\cs_set_protected:cpx { \c_@@_code_root_str \l_keys_path_str } ##1
- { #1 \exp_not:N #2 \exp_not:n {#3} {##1} }
+ {
+ \@@_precompile:n
+ { #1 \exp_not:N #2 \exp_not:n {#3} {##1} }
+ }
\use_none:n
}
\cs_generate_variant:Nn \@@_cs_set:NNpn { Nc }
@@ -2089,13 +2130,17 @@
% \begin{macrocode}
\cs_new_protected:Npn \@@_meta_make:n #1
{
- \@@_cmd_set:Vo \l_keys_path_str
+ \exp_args:NVo \@@_cmd_set_direct:nn \l_keys_path_str
{
- \exp_after:wN \keys_set:nn \exp_after:wN { \l_@@_module_str } {#1}
+ \exp_after:wN \keys_set:nn \exp_after:wN
+ { \l_@@_module_str } {#1}
}
}
\cs_new_protected:Npn \@@_meta_make:nn #1#2
- { \@@_cmd_set:Vn \l_keys_path_str { \keys_set:nn {#1} {#2} } }
+ {
+ \exp_args:NV \@@_cmd_set_direct:nn
+ \l_keys_path_str { \keys_set:nn {#1} {#2} }
+ }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -2895,6 +2940,20 @@
% \end{macro}
% \end{macro}
%
+% \begin{macro}{\keys_precompile:nnN}
+% A simple wrapper.
+% \begin{macrocode}
+\cs_new_protected:Npn \keys_precompile:nnN #1#2#3
+ {
+ \bool_set_true:N \l_@@_precompile_bool
+ \tl_clear:N \l_@@_precompile_tl
+ \keys_set:nn {#1} {#2}
+ \bool_set_false:N \l_@@_precompile_bool
+ \tl_set_eq:NN #3 \l_@@_precompile_tl
+ }
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\@@_set_keyval:n, \@@_set_keyval:nn}
% \begin{macro}{\@@_set_keyval:nnn, \@@_set_keyval:onn}
% \begin{macro}{\@@_find_key_module:wNN}
@@ -3379,7 +3438,11 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\keys_show:nn, \keys_log:nn, \@@_show:Nnn}
+% \begin{macro}{\keys_show:nn, \keys_log:nn}
+% \begin{macro}{\@@_show:Nnn}
+% \begin{macro}{\@@_show:n}
+% \begin{macro}{\@@_show:w}
+% \begin{macro}{\@@_show:Nw}
% To show a key, show its code using a message.
% \begin{macrocode}
\cs_new_protected:Npn \keys_show:nn
@@ -3395,18 +3458,52 @@
{
\exp_args:Nnf \msg_show_item_unbraced:nn { code }
{
- \exp_args:Nc \cs_replacement_spec:N
+ \exp_args:Ne \@@_show:n
{
- \c_@@_code_root_str
- \@@_trim_spaces:n { #2 / #3 }
+ \exp_args:Nc \cs_replacement_spec:N
+ {
+ \c_@@_code_root_str
+ \@@_trim_spaces:n { #2 / #3 }
+ }
}
}
}
}
{ } { }
}
+\cs_new:Npx \@@_show:n #1
+ {
+ \exp_not:N \@@_show:w
+ #1
+ \tl_to_str:n { \@@_precompile:n }
+ #1
+ \tl_to_str:n { \@@_precompile:n }
+ \exp_not:N \s_@@_stop
+ }
+\use:x
+ {
+ \cs_new:Npn \exp_not:N \@@_show:w
+ ##1 \tl_to_str:n { \@@_precompile:n }
+ ##2 \tl_to_str:n { \@@_precompile:n }
+ ##3 \exp_not:N \s_@@_stop
+ }
+ {
+ \tl_if_blank:nTF {#2}
+ {#1}
+ { \@@_show:Nw #2 \s_@@_stop }
+ }
+\use:x
+ {
+ \cs_new:Npn \exp_not:N \@@_show:Nw ##1##2
+ \c_right_brace_str \exp_not:N \s_@@_stop
+ }
+ {#2}
% \end{macrocode}
% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
%
% \subsection{Messages}
%