summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3tl.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3tl.dtx238
1 files changed, 131 insertions, 107 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx b/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx
index 5da866311bb..52ebf4eb95c 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx
@@ -7,7 +7,7 @@
% license or (at your option) any later version. The latest version
% of this license is in the file
%
-% http://www.latex-project.org/lppl.txt
+% https://www.latex-project.org/lppl.txt
%
% This file is part of the "l3kernel bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
@@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
-\documentclass[full]{l3doc}
+\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
@@ -41,7 +41,7 @@
% }^^A
% }
%
-% \date{Released 2017/11/14}
+% \date{Released 2017/12/05}
%
% \maketitle
%
@@ -439,7 +439,7 @@
% \cs{tl_if_novalue:nTF} \Arg{token list} \Arg{true code} \Arg{false code}
% \end{syntax}
% Tests if the \meta{token list} is exactly equal to the special
-% \cs{c_novalue_tl} marker. This function is indented to allow construction
+% \cs{c_novalue_tl} marker. This function is intended to allow construction
% of flexible document interface structures in which missing optional
% arguments are detected.
% \end{function}
@@ -525,8 +525,7 @@
% \end{syntax}
% Applies the \meta{inline function} to every \meta{item} stored within the
% \meta{tl~var}. The \meta{inline function} should consist of code which
-% receives the \meta{item} as |#1|. One in line mapping can be nested
-% inside another. See also \cs{tl_map_function:NN}.
+% receives the \meta{item} as |#1|. See also \cs{tl_map_function:NN}.
% \end{function}
%
% \begin{function}[updated = 2012-06-29]{\tl_map_inline:nn}
@@ -535,31 +534,30 @@
% \end{syntax}
% Applies the \meta{inline function} to every \meta{item} stored within the
% \meta{token list}. The \meta{inline function} should consist of code which
-% receives the \meta{item} as |#1|. One in line mapping can be nested
-% inside another. See also \cs{tl_map_function:nN}.
+% receives the \meta{item} as |#1|. See also \cs{tl_map_function:nN}.
% \end{function}
%
% \begin{function}[updated = 2012-06-29]
% {\tl_map_variable:NNn, \tl_map_variable:cNn}
% \begin{syntax}
-% \cs{tl_map_variable:NNn} \meta{tl~var} \meta{variable} \Arg{function}
+% \cs{tl_map_variable:NNn} \meta{tl~var} \meta{variable} \Arg{code}
% \end{syntax}
-% Applies the \meta{function} to every \meta{item} stored
-% within the \meta{tl~var}. The \meta{function} should consist of code
-% which receives the \meta{item} stored in the \meta{variable}.
-% One variable mapping can be nested inside another. See also
-% \cs{tl_map_inline:Nn}.
+% Stores each \meta{item} of the \meta{tl~var} in turn in the (token
+% list) \meta{variable} and applies the \meta{code}. The \meta{code}
+% will usually make use of the \meta{variable}, but this is not
+% enforced. The assignments to the \meta{variable} are local. See
+% also \cs{tl_map_inline:Nn}.
% \end{function}
%
% \begin{function}[updated = 2012-06-29]{\tl_map_variable:nNn}
% \begin{syntax}
-% \cs{tl_map_variable:nNn} \Arg{token list} \meta{variable} \Arg{function}
+% \cs{tl_map_variable:nNn} \Arg{token list} \meta{variable} \Arg{code}
% \end{syntax}
-% Applies the \meta{function} to every \meta{item} stored
-% within the \meta{token list}. The \meta{function} should consist of code
-% which receives the \meta{item} stored in the \meta{variable}.
-% One variable mapping can be nested inside another. See also
-% \cs{tl_map_inline:nn}.
+% Stores each \meta{item} of the \meta{token list} in turn in the
+% (token list) \meta{variable} and applies the \meta{code}. The
+% \meta{code} will usually make use of the \meta{variable}, but this
+% is not enforced. The assignments to the \meta{variable} are local.
+% See also \cs{tl_map_inline:nn}.
% \end{function}
%
% \begin{function}[updated = 2012-06-29, rEXP]{\tl_map_break:}
@@ -580,8 +578,8 @@
% Use outside of a \cs[no-index]{tl_map_\ldots} scenario leads to low
% level \TeX{} errors.
% \begin{texnote}
-% When the mapping is broken, additional tokens may be inserted by the
-% internal macro \cs{__prg_break_point:Nn} before the \meta{tokens} are
+% 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.
% \end{texnote}
@@ -589,25 +587,25 @@
%
% \begin{function}[updated = 2012-06-29, rEXP]{\tl_map_break:n}
% \begin{syntax}
-% \cs{tl_map_break:n} \Arg{tokens}
+% \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
-% the \meta{tokens} after the mapping has ended. This
+% the \meta{code} after the mapping has ended. This
% normally takes place within a conditional statement, for example
% \begin{verbatim}
% \tl_map_inline:Nn \l_my_tl
% {
% \str_if_eq:nnT { #1 } { bingo }
-% { \tl_map_break:n { <tokens> } }
+% { \tl_map_break:n { <code> } }
% % Do something useful
% }
% \end{verbatim}
% Use outside of a \cs[no-index]{tl_map_\ldots} scenario leads to low
% level \TeX{} errors.
% \begin{texnote}
-% When the mapping is broken, additional tokens may be inserted by the
-% internal macro \cs{__prg_break_point:Nn} before the \meta{tokens} are
+% When the mapping is broken, additional tokens may be inserted
+% before the \meta{code} is
% inserted into the input stream.
% This depends on the design of the mapping function.
% \end{texnote}
@@ -1133,11 +1131,13 @@
% \begin{macro}{\tl_const:Nn, \tl_const:Nx, \tl_const:cn, \tl_const:cx}
% Constants are also easy to generate.
% \begin{macrocode}
+\__debug_patch:nnNNpn { \__debug_chk_var_scope:NN c #1 } { }
\cs_new_protected:Npn \tl_const:Nn #1#2
{
\__chk_if_free_cs:N #1
\cs_gset_nopar:Npx #1 { \exp_not:n {#2} }
}
+\__debug_patch:nnNNpn { \__debug_chk_var_scope:NN c #1 } { }
\cs_new_protected:Npn \tl_const:Nx #1#2
{
\__chk_if_free_cs:N #1
@@ -1186,13 +1186,13 @@
\tex_ifodd:D \l@expl@enable@debug@bool
\cs_new_protected:Npn \tl_set_eq:NN #1#2
{
- \__debug_chk_var_exist:N #1
+ \__debug_chk_var_local:N #1
\__debug_chk_var_exist:N #2
\cs_set_eq:NN #1 #2
}
\cs_new_protected:Npn \tl_gset_eq:NN #1#2
{
- \__debug_chk_var_exist:N #1
+ \__debug_chk_var_global:N #1
\__debug_chk_var_exist:N #2
\cs_gset_eq:NN #1 #2
}
@@ -1214,7 +1214,6 @@
% \begin{macrocode}
\__debug_patch:nnNNpn
{
- \__debug_chk_var_exist:N #1
\__debug_chk_var_exist:N #2
\__debug_chk_var_exist:N #3
}
@@ -1223,7 +1222,6 @@
{ \tl_set:Nx #1 { \exp_not:o {#2} \exp_not:o {#3} } }
\__debug_patch:nnNNpn
{
- \__debug_chk_var_exist:N #1
\__debug_chk_var_exist:N #2
\__debug_chk_var_exist:N #3
}
@@ -1297,22 +1295,22 @@
% prefixed by a call to \cs{__debug_patch:nnNNpn} which adds an
% existence check to the definition.
% \begin{macrocode}
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_local:N #1 } { }
\cs_new_protected:Npn \tl_set:Nn #1#2
{ \cs_set_nopar:Npx #1 { \exp_not:n {#2} } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_local:N #1 } { }
\cs_new_protected:Npn \tl_set:No #1#2
{ \cs_set_nopar:Npx #1 { \exp_not:o {#2} } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_local:N #1 } { }
\cs_new_protected:Npn \tl_set:Nx #1#2
{ \cs_set_nopar:Npx #1 {#2} }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_global:N #1 } { }
\cs_new_protected:Npn \tl_gset:Nn #1#2
{ \cs_gset_nopar:Npx #1 { \exp_not:n {#2} } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_global:N #1 } { }
\cs_new_protected:Npn \tl_gset:No #1#2
{ \cs_gset_nopar:Npx #1 { \exp_not:o {#2} } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_global:N #1 } { }
\cs_new_protected:Npn \tl_gset:Nx #1#2
{ \cs_gset_nopar:Npx #1 {#2} }
\cs_generate_variant:Nn \tl_set:Nn { NV , Nv , Nf }
@@ -1337,28 +1335,28 @@
% }
% Adding to the left is done directly to gain a little performance.
% \begin{macrocode}
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_local:N #1 } { }
\cs_new_protected:Npn \tl_put_left:Nn #1#2
{ \cs_set_nopar:Npx #1 { \exp_not:n {#2} \exp_not:o #1 } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_local:N #1 } { }
\cs_new_protected:Npn \tl_put_left:NV #1#2
{ \cs_set_nopar:Npx #1 { \exp_not:V #2 \exp_not:o #1 } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_local:N #1 } { }
\cs_new_protected:Npn \tl_put_left:No #1#2
{ \cs_set_nopar:Npx #1 { \exp_not:o {#2} \exp_not:o #1 } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_local:N #1 } { }
\cs_new_protected:Npn \tl_put_left:Nx #1#2
{ \cs_set_nopar:Npx #1 { #2 \exp_not:o #1 } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_global:N #1 } { }
\cs_new_protected:Npn \tl_gput_left:Nn #1#2
{ \cs_gset_nopar:Npx #1 { \exp_not:n {#2} \exp_not:o #1 } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_global:N #1 } { }
\cs_new_protected:Npn \tl_gput_left:NV #1#2
{ \cs_gset_nopar:Npx #1 { \exp_not:V #2 \exp_not:o #1 } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_global:N #1 } { }
\cs_new_protected:Npn \tl_gput_left:No #1#2
{ \cs_gset_nopar:Npx #1 { \exp_not:o {#2} \exp_not:o #1 } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_global:N #1 } { }
\cs_new_protected:Npn \tl_gput_left:Nx #1#2
{ \cs_gset_nopar:Npx #1 { #2 \exp_not:o {#1} } }
\cs_generate_variant:Nn \tl_put_left:Nn { c }
@@ -1387,28 +1385,28 @@
% }
% The same on the right.
% \begin{macrocode}
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_local:N #1 } { }
\cs_new_protected:Npn \tl_put_right:Nn #1#2
{ \cs_set_nopar:Npx #1 { \exp_not:o #1 \exp_not:n {#2} } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_local:N #1 } { }
\cs_new_protected:Npn \tl_put_right:NV #1#2
{ \cs_set_nopar:Npx #1 { \exp_not:o #1 \exp_not:V #2 } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_local:N #1 } { }
\cs_new_protected:Npn \tl_put_right:No #1#2
{ \cs_set_nopar:Npx #1 { \exp_not:o #1 \exp_not:o {#2} } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_local:N #1 } { }
\cs_new_protected:Npn \tl_put_right:Nx #1#2
{ \cs_set_nopar:Npx #1 { \exp_not:o #1 #2 } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_global:N #1 } { }
\cs_new_protected:Npn \tl_gput_right:Nn #1#2
{ \cs_gset_nopar:Npx #1 { \exp_not:o #1 \exp_not:n {#2} } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_global:N #1 } { }
\cs_new_protected:Npn \tl_gput_right:NV #1#2
{ \cs_gset_nopar:Npx #1 { \exp_not:o #1 \exp_not:V #2 } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_global:N #1 } { }
\cs_new_protected:Npn \tl_gput_right:No #1#2
{ \cs_gset_nopar:Npx #1 { \exp_not:o #1 \exp_not:o {#2} } }
-\__debug_patch:nnNNpn { \__debug_chk_var_exist:N #1 } { }
+\__debug_patch:nnNNpn { \__debug_chk_var_global:N #1 } { }
\cs_new_protected:Npn \tl_gput_right:Nx #1#2
{ \cs_gset_nopar:Npx #1 { \exp_not:o {#1} #2 } }
\cs_generate_variant:Nn \tl_put_right:Nn { c }
@@ -1446,8 +1444,8 @@
% \tl_gset_rescan:cnn, \tl_gset_rescan:cno, \tl_gset_rescan:cnx
% }
% \begin{macro}{\tl_rescan:nn}
-% \begin{macro}[aux]{\@@_set_rescan:NNnn, \@@_set_rescan_multi:n}
-% \begin{macro}[aux, EXP]{\@@_rescan:w}
+% \begin{macro}{\@@_set_rescan:NNnn, \@@_set_rescan_multi:n}
+% \begin{macro}[EXP]{\@@_rescan:w}
% These functions use a common auxiliary. After some initial setup
% explained below, and the user setup |#3| (followed by
% \cs{scan_stop:} to be safe), the tokens are rescanned by
@@ -1527,8 +1525,8 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[aux]{\@@_set_rescan:n, \@@_set_rescan:NnTF}
-% \begin{macro}[aux]{\@@_set_rescan_single:nn, \@@_set_rescan_single_aux:nn}
+% \begin{macro}{\@@_set_rescan:n, \@@_set_rescan:NnTF}
+% \begin{macro}{\@@_set_rescan_single:nn, \@@_set_rescan_single_aux:nn}
% This function calls \cs{@@_set_rescan_multiple:n} or
% \cs{@@_set_rescan_single:nn} |{ ' }| depending on whether its
% argument is a single-line fragment of code/data or is made of
@@ -1686,7 +1684,7 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[aux]
+% \begin{macro}
% {
% \@@_replace:NnNNNnn,
% \@@_replace_auxi:NnnNNNnn,
@@ -1892,7 +1890,7 @@
% \subsection{Token list conditionals}
%
% \begin{macro}[pTF]{\tl_if_blank:n, \tl_if_blank:V, \tl_if_blank:o}
-% \begin{macro}[aux]{\@@_if_blank_p:NNw}
+% \begin{macro}{\@@_if_blank_p:NNw}
% \TeX{} skips spaces when reading a non-delimited arguments. Thus,
% a \meta{token list} is blank if and only if \cs{use_none:n}
% \meta{token list} |?| is empty after one expansion. The auxiliary
@@ -1964,7 +1962,7 @@
% \end{macro}
%
% \begin{macro}[pTF,documented-as=\tl_if_empty:nTF]{\tl_if_empty:o}
-% \begin{macro}[EXP,aux]{\@@_if_empty_return:o}
+% \begin{macro}[EXP]{\@@_if_empty_return:o}
% The auxiliary function \cs{@@_if_empty_return:o} is for use
% in various token list conditionals which reduce to testing
% if a given token list is empty after applying a simple function
@@ -2078,7 +2076,7 @@
% \end{macro}
%
% \begin{macro}[TF, EXP]{\tl_if_novalue:n}
-% \begin{macro}[EXP, aux]{\@@_if_novalue:w}
+% \begin{macro}[EXP]{\@@_if_novalue:w}
% Tests for |-NoValue-|: this is similar to \cs{tl_if_in:nn} but set
% up to be expandable and to check the value exactly. The question
% mark prevents the auxiliary from losing braces.
@@ -2115,7 +2113,7 @@
% \end{macro}
%
% \begin{macro}[EXP,pTF]{\tl_if_single:n}
-% \begin{macro}[EXP,pTF,aux]{\@@_if_single:n}
+% \begin{macro}[EXP,pTF]{\@@_if_single:n}
% This test is similar to \cs{tl_if_empty:nTF}. Expanding
% \cs{use_none:nn} |#1| |??| once yields an empty result if |#1| is
% blank, a single~|?| if |#1| has a single item, and otherwise yields
@@ -2148,10 +2146,10 @@
% \end{macro}
%
% \begin{macro}[EXP, noTF]{\tl_case:Nn, \tl_case:cn}
-% \begin{macro}[EXP, aux]{\@@_case:nnTF}
-% \begin{macro}[aux, EXP]{\@@_case:Nw}
-% \begin{macro}[int, EXP]{\__prg_case_end:nw}
-% \begin{macro}[aux, EXP]{\@@_case_end:nw}
+% \begin{macro}[EXP]{\@@_case:nnTF}
+% \begin{macro}[EXP]{\@@_case:Nw}
+% \begin{macro}[EXP]{\__prg_case_end: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.
@@ -2218,7 +2216,7 @@
%
% \begin{macro}{\tl_map_function:nN}
% \begin{macro}{\tl_map_function:NN, \tl_map_function:cN}
-% \begin{macro}[aux]{\@@_map_function:Nn}
+% \begin{macro}{\@@_map_function:Nn}
% Expandable loop macro for token lists. These have the advantage of not
% needing to test if the argument is empty, because if it is, the stop
% marker is read immediately and the loop terminated.
@@ -2268,7 +2266,7 @@
%
% \begin{macro}{\tl_map_variable:nNn}
% \begin{macro}{\tl_map_variable:NNn, \tl_map_variable:cNn}
-% \begin{macro}[aux]{\@@_map_variable:Nnn}
+% \begin{macro}{\@@_map_variable:Nnn}
% \cs{tl_map_variable:nNn} \meta{token list} \meta{temp} \meta{action}
% assigns
% \meta{temp} to each element and executes \meta{action}.
@@ -2345,7 +2343,7 @@
%
% \begin{macro}{\tl_count:n, \tl_count:V, \tl_count:o}
% \begin{macro}{\tl_count:N, \tl_count:c}
-% \begin{macro}[aux]{\@@_count:n}
+% \begin{macro}{\@@_count:n}
% Count number of elements within a token list or token list
% variable. Brace groups within the list are read as a single
% element. Spaces are ignored.
@@ -2371,8 +2369,8 @@
% \end{macro}
%
% \begin{macro}{\tl_reverse_items:n}
-% \begin{macro}[aux]{\@@_reverse_items:nwNwn}
-% \begin{macro}[aux]{\@@_reverse_items:wn}
+% \begin{macro}{\@@_reverse_items:nwNwn}
+% \begin{macro}{\@@_reverse_items:wn}
% Reversal of a token list is done by taking one item at a time
% and putting it after \cs{q_stop}.
% \begin{macrocode}
@@ -2424,8 +2422,8 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[int]{\@@_trim_spaces:nn}
-% \begin{macro}[aux]
+% \begin{macro}{\@@_trim_spaces:nn}
+% \begin{macro}
% {
% \@@_trim_spaces_auxi:w, \@@_trim_spaces_auxii:w,
% \@@_trim_spaces_auxiii:w, \@@_trim_spaces_auxiv:w
@@ -2497,19 +2495,19 @@
% \begin{variable}{\q_@@_act_mark, \q_@@_act_stop}
% The \cs{tl_act} functions may be applied to any token list.
% Hence, we use two private quarks, to allow any token, even quarks,
-% in the token list.^^A in particular critical for future \::e.
+% in the token list.
% Only \cs{q_@@_act_mark} and \cs{q_@@_act_stop} may not appear
% in the token lists manipulated by \cs{@@_act:NNNnn} functions. The quarks
% are effectively defined in \pkg{l3quark}.
% \end{variable}
%
-% \begin{macro}[EXP,int]{\@@_act:NNNnn}
-% \begin{macro}[EXP,aux]{\@@_act_output:n, \@@_act_reverse_output:n}
-% \begin{macro}[EXP,aux]{\@@_act_loop:w}
-% \begin{macro}[EXP,aux]{\@@_act_normal:NwnNNN}
-% \begin{macro}[EXP,aux]{\@@_act_group:nwnNNN}
-% \begin{macro}[EXP,aux]{\@@_act_space:wwnNNN}
-% \begin{macro}[EXP,aux]{\@@_act_end:w}
+% \begin{macro}[EXP]{\@@_act:NNNnn}
+% \begin{macro}[EXP]{\@@_act_output:n, \@@_act_reverse_output:n}
+% \begin{macro}[EXP]{\@@_act_loop:w}
+% \begin{macro}[EXP]{\@@_act_normal:NwnNNN}
+% \begin{macro}[EXP]{\@@_act_group:nwnNNN}
+% \begin{macro}[EXP]{\@@_act_space:wwnNNN}
+% \begin{macro}[EXP]{\@@_act_end:w}
% To help control the expansion, \cs{@@_act:NNNnn} should always
% be proceeded by \cs{exp:w} and ends by producing \cs{exp_end:}
% once the result has been obtained. Then loop over tokens,
@@ -2592,9 +2590,9 @@
% \end{macro}
%
% \begin{macro}[EXP]{\tl_reverse:n, \tl_reverse:o, \tl_reverse:V}
-% \begin{macro}[EXP,aux]{\@@_reverse_normal:nN}
-% \begin{macro}[EXP,aux]{\@@_reverse_group_preserve:nn}
-% \begin{macro}[EXP,aux]{\@@_reverse_space:n}
+% \begin{macro}[EXP]{\@@_reverse_normal:nN}
+% \begin{macro}[EXP]{\@@_reverse_group_preserve:nn}
+% \begin{macro}[EXP]{\@@_reverse_space:n}
% The goal here is to reverse without losing spaces nor braces.
% This is done using the general internal function \cs{@@_act:NNNnn}.
% Spaces and \enquote{normal} tokens are output on the left of the current
@@ -2645,7 +2643,7 @@
% \subsection{The first token from a token list}
%
% \begin{macro}{\tl_head:N, \tl_head:n, \tl_head:V, \tl_head:v, \tl_head:f}
-% \begin{macro}[aux]{\@@_head_auxi:nw, \@@_head_auxii:n}
+% \begin{macro}{\@@_head_auxi:nw, \@@_head_auxii:n}
% \begin{macro}{\tl_head:w}
% \begin{macro}{\tl_tail:N, \tl_tail:n, \tl_tail:V, \tl_tail:v, \tl_tail:f}
% Finding the head of a token list expandably always strips braces, which
@@ -2845,7 +2843,7 @@
% \end{macro}
%
% \begin{macro}[pTF]{\tl_if_head_is_N_type:n}
-% \begin{macro}[EXP,aux]{\@@_if_head_is_N_type:w}
+% \begin{macro}[EXP]{\@@_if_head_is_N_type:w}
% 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
@@ -2904,7 +2902,7 @@
% \end{macro}
%
% \begin{macro}[EXP,pTF]{\tl_if_head_is_space:n}
-% \begin{macro}[EXP,aux]{\@@_if_head_is_space:w}
+% \begin{macro}[EXP]{\@@_if_head_is_space:w}
% The auxiliary's argument is all that is before the first explicit
% space in |?#1?~|. If that is a single~|?| the test yields
% \texttt{true}. Otherwise, that is more than one token, and the test
@@ -2935,7 +2933,7 @@
% \subsection{Using a single item}
%
% \begin{macro}{\tl_item:nn, \tl_item:Nn, \tl_item:cn}
-% \begin{macro}[aux]{\@@_item_aux:nn, \@@_item:nn}
+% \begin{macro}{\@@_item_aux:nn, \@@_item:nn}
% The idea here is to find the offset of the item from the left, then use
% a loop to grab the correct item. If the resulting offset is too large,
% then \cs{quark_if_recursion_tail_stop:n} terminates the loop, and returns
@@ -2970,39 +2968,65 @@
%
% \subsection{Viewing token lists}
%
-% \begin{macro}{\tl_show:N, \tl_show:c}
+% \begin{macro}{\tl_show:N, \tl_show:c, \tl_log:N, \tl_log:c, \@@_show:NN}
% Showing token list variables is done after checking that the
% variable is defined (see \cs{__kernel_register_show:N}).
% \begin{macrocode}
-\cs_new_protected:Npn \tl_show:N #1
+\cs_new_protected:Npn \tl_show:N { \@@_show:NN \tl_show:n }
+\cs_generate_variant:Nn \tl_show:N { c }
+\cs_new_protected:Npn \tl_log:N { \@@_show:NN \tl_log:n }
+\cs_generate_variant:Nn \tl_log:N { c }
+\cs_new_protected:Npn \@@_show:NN #1#2
{
- \__msg_show_variable:NNNnn #1 \tl_if_exist:NTF ? { }
- { > ~ \token_to_str:N #1 = \tl_to_str:N #1 }
+ \__kernel_check_defined:NT #2
+ { \exp_args:Nx #1 { \token_to_str:N #2 = \exp_not:o {#2} } }
}
-\cs_generate_variant:Nn \tl_show:N { c }
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\tl_show:n}
-% The \cs{__msg_show_wrap:n} internal function performs
-% line-wrapping and shows the result
-% using the \cs{etex_showtokens:D} primitive. Since \cs{tl_to_str:n}
-% is expanded within the line-wrapping code, the escape character is
-% always a backslash.
+% \begin{macro}{\tl_show:n, \@@_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
+% \cs{iow_wrap:nnnN} but with a leading |>~| and trailing period, both
+% removed before passing the wrapped text to the \tn{showtokens}
+% primitive. This primitive shows the result with a leading |>~| and
+% trailing period.
+%
+% The token list \cs{l_@@_internal_a_tl} containing the result
+% of all these manipulations is displayed to the terminal using
+% \cs{etex_showtokens:D} and an odd \cs{exp_after:wN} which expand the
+% closing brace to improve the output slightly. The calls to
+% \cs{__iow_with:Nnn} ensure that the \tn{newlinechar} is set to~$10$
+% so that the \cs{iow_newline:} inserted by the line-wrapping code
+% are correctly recognized by \TeX{}, and that \tn{errorcontextlines}
+% is $-1$ to avoid printing irrelevant context.
% \begin{macrocode}
\cs_new_protected:Npn \tl_show:n #1
- { \__msg_show_wrap:n { > ~ \tl_to_str:n {#1} } }
+ { \iow_wrap:nnnN { >~ \tl_to_str:n {#1} . } { } { } \@@_show:n }
+\cs_new_protected:Npn \@@_show:n #1
+ {
+ \tl_set:Nf \l_@@_internal_a_tl { \@@_show:w #1 \q_stop }
+ \__iow_with:Nnn \tex_newlinechar:D { 10 }
+ {
+ \__iow_with:Nnn \tex_errorcontextlines:D { -1 }
+ {
+ \etex_showtokens:D \exp_after:wN \exp_after:wN \exp_after:wN
+ { \exp_after:wN \l_@@_internal_a_tl }
+ }
+ }
+ }
+\cs_new:Npn \@@_show:w #1 > #2 . \q_stop {#2}
% \end{macrocode}
% \end{macro}
+% \end{macro}
%
-% \begin{macro}{\tl_log:N, \tl_log:c, \tl_log:n}
-% Redirect output of \cs{tl_show:N} and \cs{tl_show:n} to the log.
+% \begin{macro}{\tl_log:n}
+% 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
- { \__msg_log_next: \tl_show:N }
-\cs_generate_variant:Nn \tl_log:N { c }
-\cs_new_protected:Npn \tl_log:n
- { \__msg_log_next: \tl_show:n }
+\cs_new_protected:Npn \tl_log:n #1
+ { \iow_wrap:nnnN { > ~ \tl_to_str:n {#1} . } { } { } \iow_log:n }
% \end{macrocode}
% \end{macro}
%