diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3tl.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3tl.dtx | 238 |
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} % |