diff options
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3tl.dtx')
-rw-r--r-- | macros/latex/contrib/l3kernel/l3tl.dtx | 141 |
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} |