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.dtx183
1 files changed, 50 insertions, 133 deletions
diff --git a/macros/latex/contrib/l3kernel/l3tl.dtx b/macros/latex/contrib/l3kernel/l3tl.dtx
index 1e113ee3b4..67154547b7 100644
--- a/macros/latex/contrib/l3kernel/l3tl.dtx
+++ b/macros/latex/contrib/l3kernel/l3tl.dtx
@@ -43,7 +43,7 @@
% }^^A
% }
%
-% \date{Released 2023-05-22}
+% \date{Released 2023-06-05}
%
% \maketitle
%
@@ -161,12 +161,12 @@
%
% \begin{function}
% {
-% \tl_set:Nn, \tl_set:NV, \tl_set:Nv, \tl_set:No, \tl_set:Nf, \tl_set:Nx,
-% \tl_set:cn, \tl_set:cV, \tl_set:cv, \tl_set:co, \tl_set:cf, \tl_set:cx,
+% \tl_set:Nn, \tl_set:NV, \tl_set:Nv, \tl_set:No, \tl_set:Ne, \tl_set:Nf, \tl_set:Nx,
+% \tl_set:cn, \tl_set:cV, \tl_set:cv, \tl_set:co, \tl_set:ce, \tl_set:cf, \tl_set:cx,
% \tl_gset:Nn, \tl_gset:NV, \tl_gset:Nv,
-% \tl_gset:No, \tl_gset:Nf, \tl_gset:Nx,
+% \tl_gset:No, \tl_gset:Ne, \tl_gset:Nf, \tl_gset:Nx,
% \tl_gset:cn, \tl_gset:cV, \tl_gset:cv,
-% \tl_gset:co, \tl_gset:cf, \tl_gset:cx
+% \tl_gset:co, \tl_gset:ce, \tl_gset:cf, \tl_gset:cx
% }
% \begin{syntax}
% \cs{tl_set:Nn} \meta{tl~var} \Arg{tokens}
@@ -350,30 +350,6 @@
% Token groups (|{|\ldots|}|) are not single tokens.
% \end{function}
%
-% \begin{function}[added = 2013-07-24, EXP, noTF]{\tl_case:Nn, \tl_case:cn}
-% \begin{syntax}
-% \cs{tl_case:NnTF} \meta{test token list variable} \\
-% ~~"{" \\
-% ~~~~\meta{token list variable case_1} \Arg{code case_1} \\
-% ~~~~\meta{token list variable case_2} \Arg{code case_2} \\
-% ~~~~\ldots \\
-% ~~~~\meta{token list variable case_n} \Arg{code case_n} \\
-% ~~"}" \\
-% ~~\Arg{true code}
-% ~~\Arg{false code}
-% \end{syntax}
-% This function compares the \meta{test token list variable} in turn
-% with each of the \meta{token list variable cases}. If the two
-% are equal (as described for \cs{tl_if_eq:NNTF})
-% then the associated \meta{code} is left in the input
-% stream and other cases are discarded. If any of the
-% cases are matched, the \meta{true code} is also inserted into the
-% input stream (after the code for the appropriate case), while if none
-% match then the \meta{false code} is inserted. The function
-% \cs{tl_case:Nn}, which does nothing if there is no match, is also
-% available.
-% \end{function}
-%
% \subsection{Testing the first token}
%
% \begin{function}[updated = 2012-07-09, EXP, pTF]
@@ -462,7 +438,7 @@
%
% \subsection{Using token lists}
%
-% \begin{function}[EXP]{\tl_to_str:n, \tl_to_str:V, \tl_to_str:v}
+% \begin{function}[EXP]{\tl_to_str:n, \tl_to_str:o, \tl_to_str:V, \tl_to_str:v}
% \begin{syntax}
% \cs{tl_to_str:n} \Arg{token list}
% \end{syntax}
@@ -670,7 +646,7 @@
% \end{texnote}
% \end{function}
%
-% \begin{function}[updated = 2015-08-07]{\tl_show:n}
+% \begin{function}[updated = 2015-08-07]{\tl_show:n, \tl_show:x}
% \begin{syntax}
% \cs{tl_show:n} \Arg{token list}
% \end{syntax}
@@ -689,7 +665,7 @@
% \cs{tl_show:N} which displays the result in the terminal.
% \end{function}
%
-% \begin{function}[added = 2014-08-22, updated = 2015-08-07]{\tl_log:n}
+% \begin{function}[added = 2014-08-22, updated = 2015-08-07]{\tl_log:n, \tl_log:x}
% \begin{syntax}
% \cs{tl_log:n} \Arg{token list}
% \end{syntax}
@@ -1097,8 +1073,10 @@
%
% \begin{function}[updated = 2011-08-11]
% {
-% \tl_replace_once:Nnn, \tl_replace_once:cnn,
-% \tl_greplace_once:Nnn, \tl_greplace_once:cnn
+% \tl_replace_once:Nnn, \tl_replace_once:Nxx,
+% \tl_replace_once:cnn, \tl_replace_once:cxx,
+% \tl_greplace_once:Nnn, \tl_greplace_once:Nxx
+% \tl_greplace_once:cnn, \tl_greplace_once:cxx
% }
% \begin{syntax}
% \cs{tl_replace_once:Nnn} \meta{tl~var} \Arg{old tokens} \Arg{new tokens}
@@ -1112,8 +1090,10 @@
%
% \begin{function}[updated = 2011-08-11]
% {
-% \tl_replace_all:Nnn, \tl_replace_all:cnn,
-% \tl_greplace_all:Nnn, \tl_greplace_all:cnn
+% \tl_replace_all:Nnn, \tl_replace_all:Nxx,
+% \tl_replace_all:cnn, \tl_replace_all:cxx
+% \tl_greplace_all:Nnn, \tl_greplace_all:Nxx,
+% \tl_greplace_all:cnn, \tl_greplace_all:cxx
% }
% \begin{syntax}
% \cs{tl_replace_all:Nnn} \meta{tl~var} \Arg{old tokens} \Arg{new tokens}
@@ -1131,8 +1111,10 @@
%
% \begin{function}[updated = 2011-08-11]
% {
-% \tl_remove_once:Nn, \tl_remove_once:cn,
-% \tl_gremove_once:Nn, \tl_gremove_once:cn
+% \tl_remove_once:Nn, \tl_remove_once:Nx,
+% \tl_remove_once:cn, \tl_remove_once:cx,
+% \tl_gremove_once:Nn, \tl_gremove_once:Nx
+% \tl_gremove_once:cn, \tl_gremove_once:cx
% }
% \begin{syntax}
% \cs{tl_remove_once:Nn} \meta{tl~var} \Arg{tokens}
@@ -1145,8 +1127,10 @@
%
% \begin{function}[updated = 2011-08-11]
% {
-% \tl_remove_all:Nn, \tl_remove_all:cn,
-% \tl_gremove_all:Nn, \tl_gremove_all:cn
+% \tl_remove_all:Nn, \tl_remove_all:Nx,
+% \tl_remove_all:cn, \tl_remove_all:cx,
+% \tl_gremove_all:Nn, \tl_gremove_all:Nx
+% \tl_gremove_all:cn, \tl_gremove_all:cx
% }
% \begin{syntax}
% \cs{tl_remove_all:Nn} \meta{tl~var} \Arg{tokens}
@@ -1211,7 +1195,7 @@
% \end{texnote}
% \end{function}
%
-% \begin{function}[updated = 2015-08-11]{\tl_rescan:nn}
+% \begin{function}[updated = 2015-08-11]{\tl_rescan:nn, \tl_rescan:nV}
% \begin{syntax}
% \cs{tl_rescan:nn} \Arg{setup} \Arg{tokens}
% \end{syntax}
@@ -1463,15 +1447,15 @@
%
% \begin{macro}
% {
-% \tl_set:Nn, \tl_set:NV, \tl_set:Nv, \tl_set:No, \tl_set:Nf, \tl_set:Nx,
-% \tl_set:cn, \tl_set:cV, \tl_set:cv, \tl_set:co, \tl_set:cf, \tl_set:cx
+% \tl_set:Nn, \tl_set:NV, \tl_set:Nv, \tl_set:No, \tl_set:Ne, \tl_set:Nf, \tl_set:Nx,
+% \tl_set:cn, \tl_set:cV, \tl_set:cv, \tl_set:co, \tl_set:ce, \tl_set:cf, \tl_set:cx
% }
% \begin{macro}
% {
% \tl_gset:Nn, \tl_gset:NV, \tl_gset:Nv,
-% \tl_gset:No, \tl_gset:Nf, \tl_gset:Nx,
+% \tl_gset:No, \tl_gset:Ne, \tl_gset:Nf, \tl_gset:Nx,
% \tl_gset:cn, \tl_gset:cV, \tl_gset:cv,
-% \tl_gset:co, \tl_gset:cf, \tl_gset:cx
+% \tl_gset:co, \tl_gset:ce, \tl_gset:cf, \tl_gset:cx
% }
% By using \cs{exp_not:n} token list variables can contain |#| tokens,
% which makes the token list registers provided by \TeX{}
@@ -1490,12 +1474,12 @@
{ \__kernel_tl_gset:Nx #1 { \__kernel_exp_not:w \exp_after:wN {#2} } }
\cs_new_protected:Npn \tl_gset:Nx #1#2
{ \__kernel_tl_gset:Nx #1 {#2} }
-\cs_generate_variant:Nn \tl_set:Nn { NV , Nv , Nf }
-\cs_generate_variant:Nn \tl_set:Nn { c, cV , cv , cf }
+\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:Nx { c }
\cs_generate_variant:Nn \tl_set:No { c }
-\cs_generate_variant:Nn \tl_gset:Nn { NV , Nv , Nf }
-\cs_generate_variant:Nn \tl_gset:Nn { c, cV , cv , cf }
+\cs_generate_variant:Nn \tl_gset:Nn { NV , Nv , Ne , Nf }
+\cs_generate_variant:Nn \tl_gset:Nn { c, cV , cv , ce , cf }
\cs_generate_variant:Nn \tl_gset:Nx { c }
\cs_generate_variant:Nn \tl_gset:No { c }
% \end{macrocode}
@@ -1677,7 +1661,7 @@
% \tl_gset_rescan:Nnn, \tl_gset_rescan:Nno, \tl_gset_rescan:Nnx,
% \tl_gset_rescan:cnn, \tl_gset_rescan:cno, \tl_gset_rescan:cnx
% }
-% \begin{macro}{\tl_rescan:nn}
+% \begin{macro}{\tl_rescan:nn, \tl_rescan:nV}
% \begin{macro}{\@@_rescan_aux:}
% \begin{macro}{\@@_set_rescan:NNnn, \@@_set_rescan_multi:nNN}
% \begin{macro}[EXP]{\@@_rescan:NNw}
@@ -1740,6 +1724,7 @@
\exp_after:wN \@@_rescan_aux:
\l_@@_internal_a_tl
}
+\cs_generate_variant:Nn \tl_rescan:nn { nV }
\exp_args:NNo \cs_new_protected:Npn \@@_rescan_aux:
{ \tl_clear:N \l_@@_internal_a_tl }
\cs_new_protected:Npn \tl_set_rescan:Nnn
@@ -1917,10 +1902,10 @@
{ \@@_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:Nx }
-\cs_generate_variant:Nn \tl_replace_once:Nnn { c }
-\cs_generate_variant:Nn \tl_greplace_once:Nnn { c }
-\cs_generate_variant:Nn \tl_replace_all:Nnn { c }
-\cs_generate_variant:Nn \tl_greplace_all:Nnn { c }
+\cs_generate_variant:Nn \tl_replace_once:Nnn { Nxx , c , cxx }
+\cs_generate_variant:Nn \tl_greplace_once:Nnn { Nxx , c , cxx }
+\cs_generate_variant:Nn \tl_replace_all:Nnn { Nxx , c , cxx }
+\cs_generate_variant:Nn \tl_greplace_all:Nnn { Nxx , c , cxx }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -2113,8 +2098,8 @@
{ \tl_replace_once:Nnn #1 {#2} { } }
\cs_new_protected:Npn \tl_gremove_once:Nn #1#2
{ \tl_greplace_once:Nnn #1 {#2} { } }
-\cs_generate_variant:Nn \tl_remove_once:Nn { c }
-\cs_generate_variant:Nn \tl_gremove_once:Nn { c }
+\cs_generate_variant:Nn \tl_remove_once:Nn { Nx , c , cx }
+\cs_generate_variant:Nn \tl_gremove_once:Nn { Nx , c , cx }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -2127,8 +2112,8 @@
{ \tl_replace_all:Nnn #1 {#2} { } }
\cs_new_protected:Npn \tl_gremove_all:Nn #1#2
{ \tl_greplace_all:Nnn #1 {#2} { } }
-\cs_generate_variant:Nn \tl_remove_all:Nn { c }
-\cs_generate_variant:Nn \tl_gremove_all:Nn { c }
+\cs_generate_variant:Nn \tl_remove_all:Nn { Nx , c , cx }
+\cs_generate_variant:Nn \tl_gremove_all:Nn { Nx , c , cx }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -2234,14 +2219,7 @@
% Returns \cs{c_true_bool} if and only if the two token list variables are
% equal.
% \begin{macrocode}
-\prg_new_conditional:Npnn \tl_if_eq:NN #1#2 { p , T , F , TF }
- {
- \if_meaning:w #1 #2
- \prg_return_true:
- \else:
- \prg_return_false:
- \fi:
- }
+\prg_new_eq_conditional:NNn \tl_if_eq:NN \cs_if_eq:NN { p , T , F , TF }
\prg_generate_conditional_variant:Nnn \tl_if_eq:NN
{ Nc , c , cc } { p , TF , T , F }
% \end{macrocode}
@@ -2437,69 +2415,6 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[EXP, noTF]{\tl_case:Nn, \tl_case:cn}
-% \begin{macro}[EXP]{\@@_case:nnTF}
-% \begin{macro}[EXP]{\@@_case:Nw}
-% \begin{macro}[EXP]{\@@_case_end:nw}
-% The aim here is to allow the case statement to be evaluated
-% using a known number of expansion steps (two), and without
-% needing to use an explicit \enquote{end of recursion} marker.
-% That is achieved by using the test input as the final case,
-% as this is always true. The trick is then to tidy up
-% the output such that the appropriate case code plus either
-% the \texttt{true} or \texttt{false} branch code is inserted.
-% \begin{macrocode}
-\cs_new:Npn \tl_case:Nn #1#2
- {
- \exp:w
- \@@_case:NnTF #1 {#2} { } { }
- }
-\cs_new:Npn \tl_case:NnT #1#2#3
- {
- \exp:w
- \@@_case:NnTF #1 {#2} {#3} { }
- }
-\cs_new:Npn \tl_case:NnF #1#2#3
- {
- \exp:w
- \@@_case:NnTF #1 {#2} { } {#3}
- }
-\cs_new:Npn \tl_case:NnTF #1#2
- {
- \exp:w
- \@@_case:NnTF #1 {#2}
- }
-\cs_new:Npn \@@_case:NnTF #1#2#3#4
- { \@@_case:Nw #1 #2 #1 { } \s_@@_mark {#3} \s_@@_mark {#4} \s_@@_stop }
-\cs_new:Npn \@@_case:Nw #1#2#3
- {
- \tl_if_eq:NNTF #1 #2
- { \@@_case_end:nw {#3} }
- { \@@_case:Nw #1 }
- }
-\cs_generate_variant:Nn \tl_case:Nn { c }
-\prg_generate_conditional_variant:Nnn \tl_case:Nn
- { c } { T , F , TF }
-% \end{macrocode}
-% To tidy up the recursion, there are two outcomes. If there was a hit to
-% one of the cases searched for, then |#1| is the code to insert,
-% |#2| is the \emph{next} case to check on and |#3| is all of
-% the rest of the cases code. That means that |#4| is the \texttt{true}
-% branch code, and |#5| tidies up the spare \cs{s_@@_mark} and the
-% \texttt{false} branch. On the other hand, if none of the cases matched
-% then we arrive here using the \enquote{termination} case of comparing
-% the search with itself. That means that |#1| is empty, |#2| is
-% the first \cs{s_@@_mark} and so |#4| is the \texttt{false} code (the
-% \texttt{true} code is mopped up by |#3|).
-% \begin{macrocode}
-\cs_new:Npn \@@_case_end:nw #1#2#3 \s_@@_mark #4#5 \s_@@_stop
- { \exp_end: #1 #4 }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
% \subsection{Mapping over token lists}
%
% \begin{macro}
@@ -2642,10 +2557,10 @@
%
% \subsection{Using token lists}
%
-% \begin{macro}{\tl_to_str:n, \tl_to_str:V, \tl_to_str:v}
+% \begin{macro}{\tl_to_str:n, \tl_to_str:o, \tl_to_str:V, \tl_to_str:v}
% Another name for a primitive: defined in \pkg{l3basics}.
% \begin{macrocode}
-\cs_generate_variant:Nn \tl_to_str:n { V , v }
+\cs_generate_variant:Nn \tl_to_str:n { o , V , v }
% \end{macrocode}
% \end{macro}
%
@@ -3578,7 +3493,7 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\tl_show:n, \@@_show:n}
+% \begin{macro}{\tl_show:n, \tl_show:x, \@@_show:n}
% \begin{macro}[EXP]{\@@_show:w}
% Many |show| functions are based on \cs{tl_show:n}.
% The argument of \cs{tl_show:n} is line-wrapped using
@@ -3598,6 +3513,7 @@
% \begin{macrocode}
\cs_new_protected:Npn \tl_show:n #1
{ \iow_wrap:nnnN { >~ \tl_to_str:n {#1} . } { } { } \@@_show:n }
+\cs_generate_variant:Nn \tl_show:n { x }
\cs_new_protected:Npn \@@_show:n #1
{
\tl_set:Nf \l_@@_internal_a_tl { \@@_show:w #1 \s_@@_stop }
@@ -3615,12 +3531,13 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\tl_log:n}
+% \begin{macro}{\tl_log:n, \tl_log:x}
% Logging is much easier, simply line-wrap. The |>~| and trailing
% period is there to match the output of \cs{tl_show:n}.
% \begin{macrocode}
\cs_new_protected:Npn \tl_log:n #1
{ \iow_wrap:nnnN { > ~ \tl_to_str:n {#1} . } { } { } \iow_log:n }
+\cs_generate_variant:Nn \tl_log:n { x }
% \end{macrocode}
% \end{macro}
%