summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3tl.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3tl.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/l3tl.dtx141
1 files changed, 73 insertions, 68 deletions
diff --git a/macros/latex/contrib/l3kernel/l3tl.dtx b/macros/latex/contrib/l3kernel/l3tl.dtx
index 0249c36aef..5429f19c54 100644
--- a/macros/latex/contrib/l3kernel/l3tl.dtx
+++ b/macros/latex/contrib/l3kernel/l3tl.dtx
@@ -43,7 +43,7 @@
% }^^A
% }
%
-% \date{Released 2024-01-04}
+% \date{Released 2024-01-22}
%
% \maketitle
%
@@ -103,11 +103,11 @@
% \tl_const:cn, \tl_const:ce
% }
% \begin{syntax}
-% \cs{tl_const:Nn} \meta{tl~var} \Arg{token list}
+% \cs{tl_const:Nn} \meta{tl~var} \Arg{tokens}
% \end{syntax}
% Creates a new constant \meta{tl~var} or raises an error
% if the name is already taken. The value of the
-% \meta{tl~var} is set globally to the \meta{token list}.
+% \meta{tl~var} is set globally to the \meta{tokens}.
% \end{function}
%
% \begin{function}{\tl_clear:N, \tl_clear:c, \tl_gclear:N, \tl_gclear:c}
@@ -235,7 +235,7 @@
% \cs{tl_if_empty_p:N} \meta{tl~var}
% \cs{tl_if_empty:NTF} \meta{tl~var} \Arg{true code} \Arg{false code}
% \end{syntax}
-% Tests if the \meta{token list variable} is entirely empty
+% Tests if the \meta{tl~var} is entirely empty
% (\emph{i.e.}~contains no tokens at all).
% \end{function}
%
@@ -255,7 +255,7 @@
% \cs{tl_if_eq_p:NN} \meta{tl~var_1} \meta{tl~var_2}
% \cs{tl_if_eq:NNTF} \meta{tl~var_1} \meta{tl~var_2} \Arg{true code} \Arg{false code}
% \end{syntax}
-% Compares the content of two \meta{token list variables} and
+% Compares the content of \meta{tl~var_1} and \meta{tl~var_2} and
% is logically \texttt{true} if the two contain the same list of
% tokens (\emph{i.e.}~identical in both the list of characters they
% contain and the category codes of those characters). Thus for example
@@ -272,7 +272,7 @@
% \begin{syntax}
% \cs{tl_if_eq:NnTF} \meta{tl~var_1} \Arg{token list_2} \Arg{true code} \Arg{false code}
% \end{syntax}
-% Tests if the \meta{token list variable_1} and the \meta{token
+% Tests if the \meta{tl~var_1} and the \meta{token
% list_2} contain the same list of tokens, both in respect of
% character codes and category codes. This conditional is not
% expandable: see \cs{tl_if_eq:NNTF} for an expandable version when
@@ -540,12 +540,12 @@
% \begin{function}[added = 2012-05-13, EXP]
% {\tl_count:n, \tl_count:V, \tl_count:v, \tl_count:e, \tl_count:o}
% \begin{syntax}
-% \cs{tl_count:n} \Arg{tokens}
+% \cs{tl_count:n} \Arg{token list}
% \end{syntax}
-% Counts the number of \meta{items} in \meta{tokens} and leaves this
+% Counts the number of \meta{items} in the \meta{token list} and leaves this
% information in the input stream. Unbraced tokens count as one
% element as do each token group (|{|\ldots|}|). This process
-% ignores any unprotected spaces within \meta{tokens}. See also
+% ignores any unprotected spaces within the \meta{token list}. See also
% \cs{tl_count:N}. This function requires three expansions,
% giving an \meta{integer denotation}.
% \end{function}
@@ -564,9 +564,9 @@
%
% \begin{function}[EXP, added = 2019-02-25]{\tl_count_tokens:n}
% \begin{syntax}
-% \cs{tl_count_tokens:n} \Arg{tokens}
+% \cs{tl_count_tokens:n} \Arg{token list}
% \end{syntax}
-% Counts the number of \TeX{} tokens in the \meta{tokens} and leaves
+% Counts the number of \TeX{} tokens in the \meta{token list} and leaves
% this information in the input stream. Every token, including spaces and
% braces, contributes one to the total; thus for instance, the token count of
% |a~{bc}| is $6$.
@@ -603,7 +603,7 @@
% that \meta{item_1}\meta{item_2}\meta{item_3} \ldots \meta{item_n}
% becomes \meta{item_n}\ldots \meta{item_3}\meta{item_2}\meta{item_1}.
% This process preserves unprotected spaces within the
-% \meta{token list variable}. Braced token groups are copied without
+% \meta{tl~var}. Braced token groups are copied without
% reversing the order of tokens, but keep the outer set of braces.
% This is equivalent to a combination of an assignment and
% \cs{tl_reverse:V}. See also \cs{tl_reverse_items:n} for improved
@@ -769,11 +769,11 @@
% {\tl_map_tokens:Nn, \tl_map_tokens:cn, \tl_map_tokens:nn}
% \begin{syntax}
% \cs{tl_map_tokens:Nn} \meta{tl~var} \Arg{code}
-% \cs{tl_map_tokens:nn} \Arg{tokens} \Arg{code}
+% \cs{tl_map_tokens:nn} \Arg{token list} \Arg{code}
% \end{syntax}
% Analogue of \cs{tl_map_function:NN} which maps several tokens
% instead of a single function. The \meta{code} receives each \meta{item} in
-% the \meta{tl~var} or in \meta{tokens} as a trailing brace group. For
+% the \meta{tl~var} or in the \meta{token list} as a trailing brace group. For
% instance,
% \begin{verbatim}
% \tl_map_tokens:Nn \l_my_tl { \prg_replicate:nn { 2 } }
@@ -816,7 +816,7 @@
% \cs{tl_map_break:}
% \end{syntax}
% Used to terminate a \cs[no-index]{tl_map_\ldots} function before all
-% entries in the \meta{token list variable} have been processed. This
+% entries in the \meta{token list} have been processed. This
% normally takes place within a conditional statement, for example
% \begin{verbatim}
% \tl_map_inline:Nn \l_my_tl
@@ -830,9 +830,9 @@
% level \TeX{} errors.
% \begin{texnote}
% When the mapping is broken, additional tokens may be inserted
-% before the \meta{tokens} are
-% inserted into the input stream.
-% This depends on the design of the mapping function.
+% before further items are taken
+% from the input stream. This depends on the design of the mapping
+% function.
% \end{texnote}
% \end{function}
%
@@ -841,7 +841,7 @@
% \cs{tl_map_break:n} \Arg{code}
% \end{syntax}
% Used to terminate a \cs[no-index]{tl_map_\ldots} function before all
-% entries in the \meta{token list variable} have been processed, inserting
+% entries in the \meta{token list} have been processed, inserting
% the \meta{code} after the mapping has ended. This
% normally takes place within a conditional statement, for example
% \begin{verbatim}
@@ -1170,7 +1170,7 @@
% \cs{tl_remove_once:Nn} \meta{tl~var} \Arg{tokens}
% \end{syntax}
% Removes the first (leftmost) occurrence of \meta{tokens} from the
-% \meta{tl~var}. \meta{Tokens} cannot contain |{|, |}| or |#|
+% \meta{tl~var}. The \meta{tokens} cannot contain |{|, |}| or |#|
% (more precisely, explicit character tokens with category code $1$
% (begin-group) or $2$ (end-group), and tokens with category code $6$).
% \end{function}
@@ -1186,7 +1186,7 @@
% \cs{tl_remove_all:Nn} \meta{tl~var} \Arg{tokens}
% \end{syntax}
% Removes all occurrences of \meta{tokens} from the
-% \meta{tl~var}. \meta{Tokens} cannot contain |{|, |}| or |#|
+% \meta{tl~var}. The \meta{tokens} cannot contain |{|, |}| or |#|
% (more precisely, explicit character tokens with category code $1$
% (begin-group) or $2$ (end-group), and tokens with category code $6$).
% As this function
@@ -1346,12 +1346,12 @@
%
% \subsection{Functions}
%
-% \begin{macro}{\__kernel_tl_set:Ne,\__kernel_tl_gset:Ne}
+% \begin{macro}{\__kernel_tl_set:Nx,\__kernel_tl_gset:Nx}
% These two are supplied to get better performance for macros which would
% otherwise use \cs{tl_set:Ne} or \cs{tl_gset:Ne} internally.
% \begin{macrocode}
-\cs_new_eq:NN \__kernel_tl_set:Ne \cs_set_nopar:Npe
-\cs_new_eq:NN \__kernel_tl_gset:Ne \cs_gset_nopar:Npe
+\cs_new_eq:NN \__kernel_tl_set:Nx \cs_set_nopar:Npe
+\cs_new_eq:NN \__kernel_tl_gset:Nx \cs_gset_nopar:Npe
% \end{macrocode}
% \end{macro}
%
@@ -1374,7 +1374,7 @@
% \tl_const:cn, \tl_const:ce, \tl_const:cx
% }
% Constants are also easy to generate. They use \cs{cs_gset_nopar:Npe} instead
-% of \cs{__kernel_tl_gset:Ne} so that the correct scope checking for |c|,
+% of \cs{__kernel_tl_gset:Nx} so that the correct scope checking for |c|,
% instead of for |g|, is applied when
% \cs{debug_on:n} |{ check-declarations }| is used.
% Constant assignment functions are patched specially in \pkg{l3debug} to
@@ -1444,7 +1444,7 @@
% \begin{macrocode}
\cs_new_protected:Npn \tl_concat:NNN #1#2#3
{
- \__kernel_tl_set:Ne #1
+ \__kernel_tl_set:Nx #1
{
\__kernel_exp_not:w \exp_after:wN {#2}
\__kernel_exp_not:w \exp_after:wN {#3}
@@ -1452,7 +1452,7 @@
}
\cs_new_protected:Npn \tl_gconcat:NNN #1#2#3
{
- \__kernel_tl_gset:Ne #1
+ \__kernel_tl_gset:Nx #1
{
\__kernel_exp_not:w \exp_after:wN {#2}
\__kernel_exp_not:w \exp_after:wN {#3}
@@ -1519,13 +1519,13 @@
% by hand as it is used quite a lot.
% \begin{macrocode}
\cs_new_protected:Npn \tl_set:Nn #1#2
- { \__kernel_tl_set:Ne #1 { \__kernel_exp_not:w {#2} } }
+ { \__kernel_tl_set:Nx #1 { \__kernel_exp_not:w {#2} } }
\cs_new_protected:Npn \tl_set:No #1#2
- { \__kernel_tl_set:Ne #1 { \__kernel_exp_not:w \exp_after:wN {#2} } }
+ { \__kernel_tl_set:Nx #1 { \__kernel_exp_not:w \exp_after:wN {#2} } }
\cs_new_protected:Npn \tl_gset:Nn #1#2
- { \__kernel_tl_gset:Ne #1 { \__kernel_exp_not:w {#2} } }
+ { \__kernel_tl_gset:Nx #1 { \__kernel_exp_not:w {#2} } }
\cs_new_protected:Npn \tl_gset:No #1#2
- { \__kernel_tl_gset:Ne #1 { \__kernel_exp_not:w \exp_after:wN {#2} } }
+ { \__kernel_tl_gset:Nx #1 { \__kernel_exp_not:w \exp_after:wN {#2} } }
\cs_generate_variant:Nn \tl_set:Nn { NV , Nv , Ne , Nf }
\cs_generate_variant:Nn \tl_set:Nn { c, cV , cv , ce , cf }
\cs_generate_variant:Nn \tl_set:No { c }
@@ -1556,22 +1556,22 @@
% \begin{macrocode}
\cs_new_protected:Npn \tl_put_left:Nn #1#2
{
- \__kernel_tl_set:Ne #1
+ \__kernel_tl_set:Nx #1
{ \__kernel_exp_not:w {#2} \__kernel_exp_not:w \exp_after:wN {#1} }
}
\cs_new_protected:Npn \tl_put_left:NV #1#2
{
- \__kernel_tl_set:Ne #1
+ \__kernel_tl_set:Nx #1
{ \exp_not:V #2 \__kernel_exp_not:w \exp_after:wN {#1} }
}
\cs_new_protected:Npn \tl_put_left:Nv #1#2
{
- \__kernel_tl_set:Ne #1
+ \__kernel_tl_set:Nx #1
{ \exp_not:v {#2} \__kernel_exp_not:w \exp_after:wN {#1} }
}
\cs_new_protected:Npn \tl_put_left:Ne #1#2
{
- \__kernel_tl_set:Ne #1
+ \__kernel_tl_set:Nx #1
{
\__kernel_exp_not:w \tex_expanded:D { {#2} }
\__kernel_exp_not:w \exp_after:wN {#1}
@@ -1579,7 +1579,7 @@
}
\cs_new_protected:Npn \tl_put_left:No #1#2
{
- \__kernel_tl_set:Ne #1
+ \__kernel_tl_set:Nx #1
{
\__kernel_exp_not:w \exp_after:wN {#2}
\__kernel_exp_not:w \exp_after:wN {#1}
@@ -1587,22 +1587,22 @@
}
\cs_new_protected:Npn \tl_gput_left:Nn #1#2
{
- \__kernel_tl_gset:Ne #1
+ \__kernel_tl_gset:Nx #1
{ \__kernel_exp_not:w {#2} \__kernel_exp_not:w \exp_after:wN {#1} }
}
\cs_new_protected:Npn \tl_gput_left:NV #1#2
{
- \__kernel_tl_gset:Ne #1
+ \__kernel_tl_gset:Nx #1
{ \exp_not:V #2 \__kernel_exp_not:w \exp_after:wN {#1} }
}
\cs_new_protected:Npn \tl_gput_left:Nv #1#2
{
- \__kernel_tl_gset:Ne #1
+ \__kernel_tl_gset:Nx #1
{ \exp_not:v {#2} \__kernel_exp_not:w \exp_after:wN {#1} }
}
\cs_new_protected:Npn \tl_gput_left:Ne #1#2
{
- \__kernel_tl_gset:Ne #1
+ \__kernel_tl_gset:Nx #1
{
\__kernel_exp_not:w \tex_expanded:D { {#2} }
\__kernel_exp_not:w \exp_after:wN {#1}
@@ -1610,7 +1610,7 @@
}
\cs_new_protected:Npn \tl_gput_left:No #1#2
{
- \__kernel_tl_gset:Ne #1
+ \__kernel_tl_gset:Nx #1
{
\__kernel_exp_not:w \exp_after:wN {#2}
\__kernel_exp_not:w \exp_after:wN {#1}
@@ -1649,20 +1649,20 @@
% The same on the right.
% \begin{macrocode}
\cs_new_protected:Npn \tl_put_right:Nn #1#2
- { \__kernel_tl_set:Ne #1 { \__kernel_exp_not:w \exp_after:wN { #1 #2 } } }
+ { \__kernel_tl_set:Nx #1 { \__kernel_exp_not:w \exp_after:wN { #1 #2 } } }
\cs_new_protected:Npn \tl_put_right:NV #1#2
{
- \__kernel_tl_set:Ne #1
+ \__kernel_tl_set:Nx #1
{ \__kernel_exp_not:w \exp_after:wN {#1} \exp_not:V #2 }
}
\cs_new_protected:Npn \tl_put_right:Nv #1#2
{
- \__kernel_tl_set:Ne #1
+ \__kernel_tl_set:Nx #1
{ \__kernel_exp_not:w \exp_after:wN {#1} \exp_not:v {#2} }
}
\cs_new_protected:Npn \tl_put_right:Ne #1#2
{
- \__kernel_tl_set:Ne #1
+ \__kernel_tl_set:Nx #1
{
\__kernel_exp_not:w \exp_after:wN {#1}
\__kernel_exp_not:w \tex_expanded:D { {#2} }
@@ -1670,27 +1670,27 @@
}
\cs_new_protected:Npn \tl_put_right:No #1#2
{
- \__kernel_tl_set:Ne #1
+ \__kernel_tl_set:Nx #1
{
\__kernel_exp_not:w \exp_after:wN {#1}
\__kernel_exp_not:w \exp_after:wN {#2}
}
}
\cs_new_protected:Npn \tl_gput_right:Nn #1#2
- { \__kernel_tl_gset:Ne #1 { \__kernel_exp_not:w \exp_after:wN { #1 #2 } } }
+ { \__kernel_tl_gset:Nx #1 { \__kernel_exp_not:w \exp_after:wN { #1 #2 } } }
\cs_new_protected:Npn \tl_gput_right:NV #1#2
{
- \__kernel_tl_gset:Ne #1
+ \__kernel_tl_gset:Nx #1
{ \__kernel_exp_not:w \exp_after:wN {#1} \exp_not:V #2 }
}
\cs_new_protected:Npn \tl_gput_right:Nv #1#2
{
- \__kernel_tl_gset:Ne #1
+ \__kernel_tl_gset:Nx #1
{ \__kernel_exp_not:w \exp_after:wN {#1} \exp_not:v {#2} }
}
\cs_new_protected:Npn \tl_gput_right:Ne #1#2
{
- \__kernel_tl_gset:Ne #1
+ \__kernel_tl_gset:Nx #1
{
\__kernel_exp_not:w \exp_after:wN {#1}
\__kernel_exp_not:w \tex_expanded:D { {#2} }
@@ -1698,7 +1698,7 @@
}
\cs_new_protected:Npn \tl_gput_right:No #1#2
{
- \__kernel_tl_gset:Ne #1
+ \__kernel_tl_gset:Nx #1
{
\__kernel_exp_not:w \exp_after:wN {#1}
\__kernel_exp_not:w \exp_after:wN {#2}
@@ -2041,13 +2041,13 @@
% the \meta{tl~var} by \meta{token list}.
% \begin{macrocode}
\cs_new_protected:Npn \tl_replace_once:Nnn
- { \@@_replace:NnNNNnn \q_@@_mark ? \@@_replace_wrap:w \__kernel_tl_set:Ne }
+ { \@@_replace:NnNNNnn \q_@@_mark ? \@@_replace_wrap:w \__kernel_tl_set:Nx }
\cs_new_protected:Npn \tl_greplace_once:Nnn
- { \@@_replace:NnNNNnn \q_@@_mark ? \@@_replace_wrap:w \__kernel_tl_gset:Ne }
+ { \@@_replace:NnNNNnn \q_@@_mark ? \@@_replace_wrap:w \__kernel_tl_gset:Nx }
\cs_new_protected:Npn \tl_replace_all:Nnn
- { \@@_replace:NnNNNnn \q_@@_mark ? \@@_replace_next:w \__kernel_tl_set:Ne }
+ { \@@_replace:NnNNNnn \q_@@_mark ? \@@_replace_next:w \__kernel_tl_set:Nx }
\cs_new_protected:Npn \tl_greplace_all:Nnn
- { \@@_replace:NnNNNnn \q_@@_mark ? \@@_replace_next:w \__kernel_tl_gset:Ne }
+ { \@@_replace:NnNNNnn \q_@@_mark ? \@@_replace_next:w \__kernel_tl_gset:Nx }
\cs_generate_variant:Nn \tl_replace_once:Nnn
{ NnV , Nne , NV , Ne , Nee , c , cnV , cne , cV , ce , cee }
\cs_generate_variant:Nn \tl_replace_once:Nnn
@@ -2904,9 +2904,9 @@
{ \@@_trim_spaces:nn { \@@_trim_mark: #1 } { \exp_args:No #2 } }
\cs_generate_variant:Nn \tl_trim_spaces_apply:nN { o }
\cs_new_protected:Npn \tl_trim_spaces:N #1
- { \__kernel_tl_set:Ne #1 { \exp_args:No \tl_trim_spaces:n {#1} } }
+ { \__kernel_tl_set:Nx #1 { \exp_args:No \tl_trim_spaces:n {#1} } }
\cs_new_protected:Npn \tl_gtrim_spaces:N #1
- { \__kernel_tl_gset:Ne #1 { \exp_args:No \tl_trim_spaces:n {#1} } }
+ { \__kernel_tl_gset:Nx #1 { \exp_args:No \tl_trim_spaces:n {#1} } }
\cs_generate_variant:Nn \tl_trim_spaces:N { c }
\cs_generate_variant:Nn \tl_gtrim_spaces:N { c }
% \end{macrocode}
@@ -3208,17 +3208,22 @@
% \begin{macro}[EXP]
% {
% \@@_if_head_is_N_type_auxi:w ,
-% \@@_if_head_is_N_type_auxii:nn ,
-% \@@_if_head_is_N_type_auxiii:n
+% \@@_if_head_is_N_type_auxii:n ,
% }
% A token list can be empty, can start with an explicit space
% character (catcode 10 and charcode 32), can start with a begin-group
% token (catcode 1), or start with an \texttt{N}-type argument. In
-% the first two cases, the line involving \cs{@@_if_head_is_N_type_auxi:w}
-% produces~|f| (and otherwise nothing). In the third case
-% (begin-group token), the lines involving \cs{token_to_str:N} produce a
-% single closing brace. The category code test is thus true exactly
-% in the fourth case, which is what we want. One cannot optimize by
+% the first two cases, and when |#1~| starts with |{}~|,
+% \cs{@@_if_head_is_N_type_auxi:w} receives an empty argument hence
+% produces |f| and removes everything before the first
+% \cs{scan_stop:}. In the third case (except when |#1~| starts with
+% |{}~|), the second auxiliary removes the first copy of~|#1| that was
+% used for the space test, then expands \cs{token_to_str:N} which hits
+% the leading begin-group token, leaving a single closing brace to be
+% compared with \cs{scan_stop:}. In the last case,
+% \cs{token_to_str:N} does not change the brace balance so that only
+% \cs{scan_stop:} \cs{scan_stop:} remain, making the character code
+% test true. One cannot optimize by
% moving one of the \cs{scan_stop:} to the beginning: if |#1| contains
% primitive conditionals, all of its occurrences must be dealt with before
% the \cs{if:w} tries to skip the \texttt{true} branch of the
@@ -3227,7 +3232,7 @@
\prg_new_conditional:Npnn \tl_if_head_is_N_type:n #1 { p , T , F , TF }
{
\if:w
- \if_false: { \fi: \@@_if_head_is_N_type_auxi:w \prg_do_nothing: #1 ~ }
+ \if_false: { \fi: \@@_if_head_is_N_type_auxi:w #1 ~ }
{ \exp_after:wN { \token_to_str:N #1 } }
\scan_stop: \scan_stop:
\prg_return_true:
@@ -3237,7 +3242,7 @@
}
\exp_args:Nno \use:n { \cs_new:Npn \@@_if_head_is_N_type_auxi:w #1 ~ }
{
- \tl_if_empty:oTF { #1 }
+ \tl_if_empty:nTF {#1}
{ f \exp_after:wN \use_none:nn }
{ \exp_after:wN \@@_if_head_is_N_type_auxii:n }
\exp_after:wN { \if_false: } \fi:
@@ -3481,9 +3486,9 @@
% which stops the \texttt{f}-expansion.
% \begin{macrocode}
\cs_new_protected:Npn \tl_reverse:N #1
- { \__kernel_tl_set:Ne #1 { \exp_args:No \tl_reverse:n { #1 } } }
+ { \__kernel_tl_set:Nx #1 { \exp_args:No \tl_reverse:n { #1 } } }
\cs_new_protected:Npn \tl_greverse:N #1
- { \__kernel_tl_gset:Ne #1 { \exp_args:No \tl_reverse:n { #1 } } }
+ { \__kernel_tl_gset:Nx #1 { \exp_args:No \tl_reverse:n { #1 } } }
\cs_generate_variant:Nn \tl_reverse:N { c }
\cs_generate_variant:Nn \tl_greverse:N { c }
% \end{macrocode}