summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-12-11 22:32:04 +0000
committerKarl Berry <karl@freefriends.org>2011-12-11 22:32:04 +0000
commit3cc0c51eddc31f37b82f651016191bf3575f3aac (patch)
tree85e3f4cfbe245c416571020e0eb1136193596550 /Master/texmf-dist/source/latex/l3kernel/l3tl.dtx
parentc56f30c6154e55286a21f438d5ed545a5169f13b (diff)
l3kernel 3036 (11dec11)
git-svn-id: svn://tug.org/texlive/trunk@24822 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3tl.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3tl.dtx483
1 files changed, 192 insertions, 291 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx b/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx
index 59ca4930274..1b029fc3611 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx
@@ -35,7 +35,7 @@
%
%<*driver|package>
\RequirePackage{l3names}
-\GetIdInfo$Id: l3tl.dtx 2929 2011-10-22 13:00:20Z bruno $
+\GetIdInfo$Id: l3tl.dtx 3034 2011-12-07 11:40:25Z bruno $
{L3 Experimental token lists}
%</driver|package>
%<*driver>
@@ -124,7 +124,7 @@
% \meta{token list}.
% \end{function}
%
-% \begin{function}{\tl_clear:N, \tl_clear:c}
+% \begin{function}{\tl_clear:N, \tl_clear:c, \tl_gclear:N, \tl_gclear:c}
% \begin{syntax}
% \cs{tl_clear:N} \meta{tl~var}
% \end{syntax}
@@ -132,52 +132,26 @@
% the current \TeX{} group.
% \end{function}
%
-% \begin{function}{\tl_gclear:N, \tl_gclear:c}
-% \begin{syntax}
-% \cs{tl_gclear:N} \meta{tl~var}
-% \end{syntax}
-% Clears all entries from the \meta{tl~var} globally.
-% \end{function}
-%
-% \begin{function}{\tl_clear_new:N, \tl_clear_new:c}
+% \begin{function}
+% {\tl_clear_new:N, \tl_clear_new:c, \tl_gclear_new:N, \tl_gclear_new:c}
% \begin{syntax}
% \cs{tl_clear_new:N} \meta{tl~var}
% \end{syntax}
-% If the \meta{tl~var} already exists, clears it within the scope
-% of the current \TeX{} group. If the \meta{tl~var} is not defined,
-% it will be created (using \cs{tl_new:N}). Thus the sequence is
-% guaranteed to be available and clear within the current \TeX{}
-% group. The \meta{tl~var} will exist globally, but the content
-% outside of the current \TeX{} group is not specified.
-% \end{function}
-%
-% \begin{function}{\tl_gclear_new:N, \tl_gclear_new:c}
-% \begin{syntax}
-% \cs{tl_gclear_new:N} \meta{tl~var}
-% \end{syntax}
-% If the \meta{tl~var} already exists, clears it globally. If the
-% \meta{tl~var} is not defined, it will be created (using
-% \cs{tl_new:N}). Thus the sequence is guaranteed to be available
-% and globally clear.
-% \end{function}
-%
-% \begin{function}{\tl_set_eq:NN, \tl_set_eq:cN, \tl_set_eq:Nc, \tl_set_eq:cc}
-% \begin{syntax}
-% \cs{tl_set_eq:NN} \meta{tl~var1} \meta{tl~var2}
-% \end{syntax}
-% Sets the content of \meta{tl~var1} equal to that of
-% \meta{tl~var2}. This assignment is restricted to the current
-% \TeX{} group level.
+% Ensures that the \meta{tl~var} exists globally by applying
+% \cs{tl_new:N} if necessary, then applies \cs{tl_(g)clear:N} to leave
+% the \meta{tl~var} empty.
% \end{function}
%
% \begin{function}
-% {\tl_gset_eq:NN, \tl_gset_eq:cN, \tl_gset_eq:Nc, \tl_gset_eq:cc}
+% {
+% \tl_set_eq:NN, \tl_set_eq:cN, \tl_set_eq:Nc, \tl_set_eq:cc,
+% \tl_gset_eq:NN, \tl_gset_eq:cN, \tl_gset_eq:Nc, \tl_gset_eq:cc
+% }
% \begin{syntax}
-% \cs{tl_gset_eq:NN} \meta{tl~var1} \meta{tl~var2}
+% \cs{tl_set_eq:NN} \meta{tl~var1} \meta{tl~var2}
% \end{syntax}
% Sets the content of \meta{tl~var1} equal to that of
-% \meta{tl~var2}. This assignment is global and so is not
-% limited by the current \TeX{} group level.
+% \meta{tl~var2}.
% \end{function}
%
% \section{Adding data to token list variables}
@@ -185,113 +159,71 @@
% \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:NV, \tl_set:Nv, \tl_set:co, \tl_set:cf, \tl_set:cx
-% }
-% \begin{syntax}
-% \cs{tl_set:Nn} \meta{tl~var} \Arg{tokens}
-% \end{syntax}
-% Sets \meta{tl~var} to contain \meta{tokens},
-% removing any previous content from the variable. This assignment
-% is restricted to the current \TeX{} group.
-% \end{function}
-%
-% \begin{function}
-% {
+% \tl_set:cn, \tl_set:NV, \tl_set:Nv, \tl_set:co, \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:cn, \tl_gset:cV, \tl_gset:cv,
% \tl_gset:co, \tl_gset:cf, \tl_gset:cx
% }
-% \begin{syntax}
-% \cs{tl_gset:Nn} \meta{tl~var} \Arg{tokens}
-% \end{syntax}
-% Sets \meta{tl~var} to contain \meta{tokens},
-% removing any previous content from the variable. This assignment
-% is global and is not limited to the current \TeX{} group level.
-% \end{function}
-%
-% \begin{function}
-% {
-% \tl_put_left:Nn, \tl_put_left:NV, \tl_put_left:No, \tl_put_left:Nx,
-% \tl_put_left:cn, \tl_put_left:cV, \tl_put_left:co, \tl_put_left:cx
-% }
% \begin{syntax}
-% \cs{tl_put_left:Nn} \meta{tl~var} \Arg{tokens}
+% \cs{tl_set:Nn} \meta{tl~var} \Arg{tokens}
% \end{syntax}
-% Appends \meta{tokens} to the left side of the current content of
-% \meta{tl~var}. This modification is restricted to the
-% current \TeX{} group level.
+% Sets \meta{tl~var} to contain \meta{tokens},
+% removing any previous content from the variable.
% \end{function}
%
% \begin{function}
% {
+% \tl_put_left:Nn, \tl_put_left:NV, \tl_put_left:No, \tl_put_left:Nx,
+% \tl_put_left:cn, \tl_put_left:cV, \tl_put_left:co, \tl_put_left:cx,
% \tl_gput_left:Nn, \tl_gput_left:NV, \tl_gput_left:No, \tl_gput_left:Nx,
% \tl_gput_left:cn, \tl_gput_left:cV, \tl_gput_left:co, \tl_gput_left:cx
+
% }
% \begin{syntax}
-% \cs{tl_gput_left:Nn} \meta{tl~var} \Arg{tokens}
+% \cs{tl_put_left:Nn} \meta{tl~var} \Arg{tokens}
% \end{syntax}
-% Globally appends \meta{tokens} to the left side of the current
-% content of \meta{tl~var}. This modification is not
-% limited by \TeX{} grouping.
+% Appends \meta{tokens} to the left side of the current content of
+% \meta{tl~var}.
% \end{function}
%
% \begin{function}
% {
% \tl_put_right:Nn, \tl_put_right:NV, \tl_put_right:No, \tl_put_right:Nx,
-% \tl_put_right:cn, \tl_put_right:cV, \tl_put_right:co, \tl_put_right:cx
-% }
-% \begin{syntax}
-% \cs{tl_put_right:Nn} \meta{tl~var} \Arg{tokens}
-% \end{syntax}
-% Appends \meta{tokens} to the right side of the current content of
-% \meta{tl~var}. This modification is restricted to the
-% current \TeX{} group level.
-% \end{function}
-%
-% \begin{function}
-% {
+% \tl_put_right:cn, \tl_put_right:cV, \tl_put_right:co, \tl_put_right:cx,
% \tl_gput_right:Nn, \tl_gput_right:NV, \tl_gput_right:No,
% \tl_gput_right:Nx,
% \tl_gput_right:cn, \tl_gput_right:cV, \tl_gput_right:co,
% \tl_gput_right:cx
% }
% \begin{syntax}
-% \cs{tl_gput_right:Nn} \meta{tl~var} \Arg{tokens}
+% \cs{tl_put_right:Nn} \meta{tl~var} \Arg{tokens}
% \end{syntax}
-% Globally appends \meta{tokens} to the right side of the current
-% content of \meta{tl~var}. This modification is not
-% limited by \TeX{} grouping.
+% Appends \meta{tokens} to the right side of the current content of
+% \meta{tl~var}.
% \end{function}
%
% \section{Modifying token list variables}
%
% \begin{function}[updated = 2011-08-11]
-% {\tl_replace_once:Nnn, \tl_replace_once:cnn}
+% {
+% \tl_replace_once:Nnn, \tl_replace_once:cnn,
+% \tl_greplace_once:Nnn, \tl_greplace_once:cnn
+% }
% \begin{syntax}
% \cs{tl_replace_once:Nnn} \meta{tl~var} \Arg{old tokens} \Arg{new tokens}
% \end{syntax}
% Replaces the first (leftmost) occurrence of \meta{old tokens} in the
% \meta{tl~var} with \meta{new tokens}. \meta{Old tokens}
% cannot contain |{|, |}| or |#|
-% (assuming normal \TeX{} category codes). The assignment is
-% restricted to the current \TeX{} group.
-% \end{function}
-%
-% \begin{function}[updated = 2011-08-11]
-% {\tl_greplace_once:Nnn, \tl_greplace_once:cnn}
-% \begin{syntax}
-% \cs{tl_greplace_once:Nnn} \meta{tl~var} \Arg{old tokens} \Arg{new tokens}
-% \end{syntax}
-% Replaces the first (leftmost) occurrence of \meta{old tokens} in the
-% \meta{tl~var} with \meta{new tokens}. \meta{Old tokens}
-% cannot contain |{|, |}| or |#|
-% (assuming normal \TeX{} category codes). The assignment is
-% applied globally.
+% (assuming normal \TeX{} category codes).
% \end{function}
%
% \begin{function}[updated = 2011-08-11]
-% {\tl_replace_all:Nnn, \tl_replace_all:cnn}
+% {
+% \tl_replace_all:Nnn, \tl_replace_all:cnn,
+% \tl_greplace_all:Nnn, \tl_greplace_all:cnn
+% }
% \begin{syntax}
% \cs{tl_replace_all:Nnn} \meta{tl~var} \Arg{old tokens} \Arg{new tokens}
% \end{syntax}
@@ -306,43 +238,23 @@
% \end{function}
%
% \begin{function}[updated = 2011-08-11]
-% {\tl_greplace_all:Nnn, \tl_greplace_all:cnn}
-% \begin{syntax}
-% \cs{tl_greplace_all:Nnn} \meta{tl~var} \Arg{old tokens} \Arg{new tokens}
-% \end{syntax}
-% Replaces all occurrences of \meta{old tokens} in the
-% \meta{tl~var} with \meta{new tokens}. \meta{Old tokens}
-% cannot contain |{|, |}| or |#|
-% (assuming normal \TeX{} category codes). As this function
-% operates from left to right, the pattern \meta{old tokens}
-% may remain after the replacement (see \cs{tl_remove_all:Nn}
-% for an example). The assignment is applied globally.
-% \end{function}
-%
-% \begin{function}[updated = 2011-08-11]
-% {\tl_remove_once:Nn, \tl_remove_once:cn}
+% {
+% \tl_remove_once:Nn, \tl_remove_once:cn,
+% \tl_gremove_once:Nn, \tl_gremove_once:cn
+% }
% \begin{syntax}
% \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
-% |#| (assuming normal \TeX{} category codes). The assignment is
-% restricted to the current \TeX{} group.
+% |#| (assuming normal \TeX{} category codes).
% \end{function}
%
% \begin{function}[updated = 2011-08-11]
-% {\tl_gremove_once:Nn, \tl_gremove_once:cn}
-% \begin{syntax}
-% \cs{tl_gremove_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
-% |#| (assuming normal \TeX{} category codes). The assignment is
-% applied globally.
-% \end{function}
-%
-% \begin{function}[updated = 2011-08-11]
-% {\tl_remove_all:Nn, \tl_remove_all:cn}
+% {
+% \tl_remove_all:Nn, \tl_remove_all:cn,
+% \tl_gremove_all:Nn, \tl_gremove_all:cn
+% }
% \begin{syntax}
% \cs{tl_remove_all:Nn} \meta{tl~var} \Arg{tokens}
% \end{syntax}
@@ -356,58 +268,28 @@
% \cs{tl_remove_all:Nn} \cs{l_tmpa_tl} |{bc}|
% \end{quote}
% will result in \cs{l_tmpa_tl} containing \texttt{abcd}.
-% The assignment is restricted to the current \TeX{} group.
-% \end{function}
-%
-% \begin{function}[updated = 2011-08-11]
-% {\tl_gremove_all:Nn, \tl_gremove_all:cn}
-% \begin{syntax}
-% \cs{tl_gremove_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
-% |#| (assuming normal \TeX{} category codes). As this function
-% operates from left to right, the pattern \meta{tokens}
-% may remain after the removal (see \cs{tl_remove_all:Nn}
-% for an example). The assignment is
-% applied globally.
% \end{function}
%
% \section{Reassigning token list category codes}
%
-% \begin{function}[updated = 2011-08-11]
+% \begin{function}[updated = 2011-11-20]
% {
-% \tl_set_rescan:Nnn, \tl_set_rescan:Nno, \tl_set_rescan:Nnx,
-% \tl_set_rescan:cnn, \tl_set_rescan:cno, \tl_set_rescan:cnx,
+% \tl_set_rescan:Nnn, \tl_set_rescan:Nno, \tl_set_rescan:Nnx,
+% \tl_set_rescan:cnn, \tl_set_rescan:cno, \tl_set_rescan:cnx,
+% \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{syntax}
% \cs{tl_set_rescan:Nnn} \meta{tl~var} \Arg{setup} \Arg{tokens}
% \end{syntax}
% Sets \meta{tl~var} to contain \meta{tokens},
-% applying the category code r\'egime specified in the
+% applying the category code r{\'e}gime specified in the
% \meta{setup} before carrying out the assignment. This allows the
% \meta{tl~var} to contain material with category codes
-% other than those that apply when \meta{tokens} are absorbed. The
-% assignment is local to the current \TeX{} group. See also
+% other than those that apply when \meta{tokens} are absorbed. See also
% \cs{tl_rescan:nn}.
% \end{function}
%
-% \begin{function}[updated = 2011-08-11]
-% {
-% \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{syntax}
-% \cs{tl_gset_rescan:Nnn} \meta{tl~var} \Arg{setup} \Arg{tokens}
-% \end{syntax}
-% Sets \meta{tl~var} to contain \meta{tokens},
-% applying the category code r\'egime specified in the
-% \meta{setup} before carrying out the assignment. This allows the
-% \meta{tl~var} to contain material with category codes
-% other than those that apply when \meta{tokens} are absorbed. The
-% assignment is global. See also \cs{tl_rescan:nn}.
-% \end{function}
-%
% \begin{function}[updated = 2011-08-11]{\tl_rescan:nn}
% \begin{syntax}
% \cs{tl_rescan:nn} \Arg{setup} \Arg{tokens}
@@ -728,7 +610,8 @@
% See also \cs{tl_reverse:N}.
% \end{function}
%
-% \begin{function}[updated = 2011-08-13]{\tl_reverse:N, \tl_reverse:c}
+% \begin{function}[updated = 2011-11-22]
+% {\tl_reverse:N, \tl_reverse:c, \tl_greverse:N, \tl_greverse:c}
% \begin{syntax}
% \cs{tl_reverse:N} \Arg{tl~var}
% \end{syntax}
@@ -738,8 +621,7 @@
% This process will preserve unprotected spaces within the
% \meta{token list variable}. Braced token groups are copied without
% reversing the order of tokens, but keep the outer set of braces.
-% The reversal is local to the current
-% \TeX{} group. See also \cs{tl_reverse:n}.
+% See also \cs{tl_reverse:n}.
% \end{function}
%
% \begin{function}[added = 2011-08-13, EXP]{\tl_reverse_items:n}
@@ -773,21 +655,18 @@
% \end{texnote}
% \end{function}
%
-% \begin{function}[added = 2011-07-09]{\tl_trim_spaces:N, \tl_trim_spaces:c}
+% \begin{function}[added = 2011-07-09]
+% {
+% \tl_trim_spaces:N, \tl_trim_spaces:c,
+% \tl_gtrim_spaces:N, \tl_gtrim_spaces:c
+% }
% \begin{syntax}
% \cs{tl_trim_spaces:N} \meta{tl~var}
% \end{syntax}
% Removes any leading and trailing explicit space characters
-% from the content of the \meta{tl~var} within the current \TeX{} group.
-% \end{function}
-%
-% \begin{function}[added = 2011-07-09]{\tl_gtrim_spaces:N, \tl_gtrim_spaces:c}
-% \begin{syntax}
-% \cs{tl_gtrim_spaces:N} \meta{tl~var}
-% \end{syntax}
-% Removes any leading and trailing explicit space characters
-% from the content of the \meta{tl~var} globally.
+% from the content of the \meta{tl~var}.
% \end{function}
+
%
% \section{The first token from a token list}
%
@@ -1076,6 +955,19 @@
% \end{texnote}
% \end{function}
%
+% \begin{function}[added = 2011-11-21, EXP]
+% {\tl_item:nn, \tl_item:Nn, \tl_item:cn}
+% \begin{syntax}
+% \cs{tl_item:nn} \Arg{token list} \Arg{integer expression}
+% \end{syntax}
+% Indexing items in the \meta{token list} from $0$ on the left, this
+% function will evaluate the \meta{integer expression} and leave the
+% appropriate item from the \meta{token list} in the input stream.
+% If the \meta{integer expression} is negative, indexing occurs from
+% the right of the sequence, starting at $-1$ for the right-most item.
+% If the index is out of bounds, then thr function expands to nothing.
+% \end{function}
+%
% \section{Internal functions}
%
% \begin{variable}{\q_tl_act_mark,\q_tl_act_stop}
@@ -1138,6 +1030,14 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{variable}{\c_empty_tl}
+% Never full. We need to define that constant early
+% for \cs{tl_new:N} to work properly.
+% \begin{macrocode}
+\tl_const:Nn \c_empty_tl { }
+% \end{macrocode}
+% \end{variable}
+%
% \begin{macro}{\tl_clear:N, \tl_clear:c}
% \begin{macro}{\tl_gclear:N, \tl_gclear:c}
% Clearing a token list variable means setting it to an empty value.
@@ -1336,13 +1236,13 @@
%
% \begin{macro}
% {
-% \tl_set_rescan:Nnn, \tl_set_rescan:Nno,
-% \tl_set_rescan:cnn, \tl_set_rescan:cno
+% \tl_set_rescan:Nnn, \tl_set_rescan:Nno, \tl_set_rescan:Nnx,
+% \tl_set_rescan:cnn, \tl_set_rescan:cno, \tl_set_rescan:cnx
% }
% \begin{macro}
% {
-% \tl_gset_rescan:Nnn, \tl_gset_rescan:Nno,
-% \tl_gset_rescan:cnn, \tl_gset_rescan:cno
+% \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}[aux]{\tl_set_rescan_aux:NNnn}
% \begin{macro}[aux]{\tl_rescan_aux:w}
@@ -1385,9 +1285,9 @@
\c_tl_rescan_marker_tl
{ \tl_set:Nn \exp_not:N \l_tl_rescan_tl {##1} }
}
-\cs_generate_variant:Nn \tl_set_rescan:Nnn { Nno }
-\cs_generate_variant:Nn \tl_set_rescan:Nnn { c , cno }
-\cs_generate_variant:Nn \tl_gset_rescan:Nnn { Nno }
+\cs_generate_variant:Nn \tl_set_rescan:Nnn { Nno , Nnx }
+\cs_generate_variant:Nn \tl_set_rescan:Nnn { c , cno , cnx }
+\cs_generate_variant:Nn \tl_gset_rescan:Nnn { Nno , Nnx }
\cs_generate_variant:Nn \tl_gset_rescan:Nnn { c , cno }
% \end{macrocode}
% \end{macro}
@@ -1395,34 +1295,6 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\tl_set_rescan:Nnx, \tl_set_rescan:cnx}
-% \begin{macro}{\tl_gset_rescan:Nnx, \tl_gset_rescan:cnx}
-% \begin{macro}[aux]{\tl_set_rescan_aux:NNnx}
-% With \texttt{x}-type expansion the \tn{everyeof} method
-% does apply and the code is simple.
-% \begin{macrocode}
-\cs_new_protected_nopar:Npn \tl_set_rescan:Nnx
- { \tl_set_rescan_aux:NNnx \tl_set:Nn }
-\cs_new_protected_nopar:Npn \tl_gset_rescan:Nnx
- { \tl_set_rescan_aux:NNnx \tl_gset:Nn }
-\cs_new_protected_nopar:Npn \tl_set_rescan_aux:NNnx #1#2#3#4
- {
- \group_begin:
- \etex_everyeof:D { \exp_not:N }
- \tex_endlinechar:D \c_minus_one
- \tex_newlinechar:D \c_minus_one
- #3
- \tl_set:Nx \l_tl_rescan_tl { \etex_scantokens:D {#4} }
- \exp_args:NNNo \group_end:
- #1 #2 \l_tl_rescan_tl
- }
-\cs_generate_variant:Nn \tl_set_rescan:Nnx { c }
-\cs_generate_variant:Nn \tl_gset_rescan:Nnx { c }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
% \begin{macro}{\tl_rescan:nn}
% The same idea is also applied to in line token lists.
% \begin{macrocode}
@@ -1783,21 +1655,22 @@
%
% \begin{macro}{\tl_map_function:nN}
% \begin{macro}{\tl_map_function:NN, \tl_map_function:cN}
-% \begin{macro}[aux]{\tl_map_function_aux:NN}
+% \begin{macro}[aux]{\tl_map_function_aux: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 will be read immediately and the loop terminated.
% \begin{macrocode}
\cs_new:Npn \tl_map_function:nN #1#2
- { \tl_map_function_aux:Nn #2 #1 \q_recursion_tail \q_recursion_stop }
-\cs_new_nopar:Npn \tl_map_function:NN #1#2
{
- \exp_after:wN \tl_map_function_aux:Nn
- \exp_after:wN #2 #1 \q_recursion_tail \q_recursion_stop
+ \tl_map_function_aux:Nn #2 #1
+ \q_recursion_tail
+ \prg_break_point:n { }
}
+\cs_new_nopar:Npn \tl_map_function:NN
+ { \exp_args:No \tl_map_function:nN }
\cs_new:Npn \tl_map_function_aux:Nn #1#2
{
- \quark_if_recursion_tail_stop:n {#2}
+ \quark_if_recursion_tail_break:n {#2}
#1 {#2} \tl_map_function_aux:Nn #1
}
\cs_generate_variant:Nn \tl_map_function:NN { c }
@@ -1808,57 +1681,49 @@
%
% \begin{macro}{\tl_map_inline:nn}
% \begin{macro}{\tl_map_inline:Nn, \tl_map_inline:cn}
-% \begin{macro}[aux]{\tl_map_inline_aux:n}
-% \begin{variable}{\g_tl_inline_level_int}
% The inline functions are straight forward by now. We use a little
-% trick with the counter \cs{g_tl_inline_level_int} to make
-% them nestable. We can also make use of \cs{tl_map_function:Nn}
-% from before. (\cs{g_tl_inline_level_int} is defined in \pkg{l3int}
-% for order-of-loading reasons.)
+% trick with the counter \cs{g_prg_map_int} to make
+% them nestable. We can also make use of \cs{tl_map_function_aux:Nn}
+% from before.
% \begin{macrocode}
\cs_new_protected:Npn \tl_map_inline:nn #1#2
{
- \int_gincr:N \g_tl_inline_level_int
- \cs_gset:cpn { tl_map_inline_ \int_use:N \g_tl_inline_level_int :n }
+ \int_gincr:N \g_prg_map_int
+ \cs_gset:cpn { tl_map_inline_ \int_use:N \g_prg_map_int :n }
##1 {#2}
\exp_args:Nc \tl_map_function_aux:Nn
- { tl_map_inline_ \int_use:N \g_tl_inline_level_int :n }
- #1 \q_recursion_tail \q_recursion_stop
- \int_gdecr:N \g_tl_inline_level_int
- }
-\cs_new_protected:Npn \tl_map_inline:Nn #1#2
- {
- \int_gincr:N \g_tl_inline_level_int
- \cs_gset:cpn { tl_map_inline_ \int_use:N \g_tl_inline_level_int :n }
- ##1 {#2}
- \exp_last_unbraced:NcV \tl_map_function_aux:Nn
- { tl_map_inline_ \int_use:N \g_tl_inline_level_int :n }
- #1 \q_recursion_tail\q_recursion_stop
- \int_gdecr:N \g_tl_inline_level_int
+ { tl_map_inline_ \int_use:N \g_prg_map_int :n }
+ #1 \q_recursion_tail
+ \prg_break_point:n { \int_gdecr:N \g_prg_map_int }
}
+\cs_new_protected:Npn \tl_map_inline:Nn
+ { \exp_args:No \tl_map_inline:nn }
\cs_generate_variant:Nn \tl_map_inline:Nn { c }
% \end{macrocode}
-% \end{variable}
-% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\tl_map_variable:nNn}
% \begin{macro}{\tl_map_variable:NNn, \tl_map_variable:cNn}
-% \begin{macro}[aux]{\tl_map_variable_aux:NnN}
+% \begin{macro}[aux]{\tl_map_variable_aux:Nnn}
% \cs{tl_map_variable:nNn} \meta{token list} \meta{temp} \meta{action}
% assigns
% \meta{temp} to each element and executes \meta{action}.
% \begin{macrocode}
\cs_new_protected:Npn \tl_map_variable:nNn #1#2#3
- { \tl_map_variable_aux:Nnn #2 {#3} #1 \q_recursion_tail \q_recursion_stop }
+ {
+ \tl_map_variable_aux:Nnn #2 {#3} #1
+ \q_recursion_tail
+ \prg_break_point:n { }
+ }
\cs_new_protected_nopar:Npn \tl_map_variable:NNn
{ \exp_args:No \tl_map_variable:nNn }
\cs_new_protected:Npn \tl_map_variable_aux:Nnn #1#2#3
{
\tl_set:Nn #1 {#3}
- \quark_if_recursion_tail_stop:N #1
- #2 \tl_map_variable_aux:Nnn #1 {#2}
+ \quark_if_recursion_tail_break:N #1
+ \use:n {#2}
+ \tl_map_variable_aux:Nnn #1 {#2}
}
\cs_generate_variant:Nn \tl_map_variable:NNn { c }
% \end{macrocode}
@@ -1867,11 +1732,14 @@
% \end{macro}
%
% \begin{macro}{\tl_map_break:}
-% The break statement.
+% \begin{macro}{\tl_map_break:n}
+% The break statements are simply copies.
% \begin{macrocode}
-\cs_new_eq:NN \tl_map_break: \use_none_delimit_by_q_recursion_stop:w
+\cs_new_eq:NN \tl_map_break: \prg_map_break:
+\cs_new_eq:NN \tl_map_break:n \prg_map_break:n
% \end{macrocode}
% \end{macro}
+% \end{macro}
%
% \subsection{Using token lists}
%
@@ -1896,15 +1764,12 @@
% error here. No such luck for ones equal to \cs{scan_stop:} so
% instead a test is made and if there is an issue an error is forced.
% \begin{macrocode}
-\cs_new_eq:NN \tl_use:N \prg_do_nothing:
-\cs_new_nopar:Npn \tl_use:c #1
+\cs_new_nopar:Npn \tl_use:N #1
{
- \if_cs_exist:w #1 \cs_end:
- \cs:w #1 \exp_after:wN \cs_end:
- \else:
- \msg_expandable_error:n { Undefined~variable~name~'#1'! }
- \fi:
+ \cs_if_exist:NTF #1 {#1}
+ { \msg_expandable_kernel_error:nnn { kernel } { bad-var } {#1} }
}
+\cs_generate_variant:Nn \tl_use:N { c }
% \end{macrocode}
% \end{macro}
%
@@ -1929,7 +1794,7 @@
\int_eval:n
{ 0 \tl_map_function:NN #1 \tl_length_aux:n }
}
-\cs_new:Npn \tl_length_aux:n #1 { + 1 }
+\cs_new:Npn \tl_length_aux:n #1 { + \c_one }
\cs_generate_variant:Nn \tl_length:n { V , o }
\cs_generate_variant:Nn \tl_length:N { c }
% \end{macrocode}
@@ -1938,21 +1803,30 @@
% \end{macro}
%
% \begin{macro}{\tl_reverse_items:n}
-% \begin{macro}[aux]{\tl_reverse_items_aux:nN}
+% \begin{macro}[aux]{\tl_reverse_items_aux:nwNwn}
+% \begin{macro}[aux]{\tl_reverse_items_aux:wn}
% Reversal of a token list is done by taking one item at a time
% and putting it after \cs{q_recursion_stop}.
% \begin{macrocode}
\cs_new:Npn \tl_reverse_items:n #1
- { \tl_reverse_items_aux:nw #1 \q_recursion_tail \q_recursion_stop }
-\cs_new:Npn \tl_reverse_items_aux:nw #1 #2 \q_recursion_stop
{
- \quark_if_recursion_tail_stop_do:nn {#1} { \use_none:n }
- \tl_reverse_items_aux:nw #2 \q_recursion_stop
- {#1}
+ \tl_reverse_items_aux:nwNwn #1 ?
+ \q_mark \tl_reverse_items_aux:nwNwn
+ \q_mark \tl_reverse_items_aux:wn
+ \q_stop { }
}
+\cs_new:Npn \tl_reverse_items_aux:nwNwn #1 #2 \q_mark #3 #4 \q_stop #5
+ {
+ #3 #2
+ \q_mark \tl_reverse_items_aux:nwNwn
+ \q_mark \tl_reverse_items_aux:wn
+ \q_stop { {#1} #5 }
+ }
+\cs_new:Npn \tl_reverse_items_aux:wn #1 \q_stop #2 { \use_none:nn #2 }
% \end{macrocode}
% \end{macro}
% \end{macro}
+% \end{macro}
%
% \begin{macro}{\tl_trim_spaces:n}
% \begin{macro}
@@ -2260,23 +2134,19 @@
% then this test will be \meta{true}. It is \meta{false} if the token
% list is empty, if the first token is an implicit space token,
% such as \cs{c_space_token}, or any token other than an explicit space.
+% The slightly convoluted approach with \tn{romannumeral} ensures that
+% each expansion step gives a balanced token list.
% \begin{macrocode}
\prg_new_conditional:Npnn \tl_if_head_space:n #1 { p , T , F , TF }
{
- \if_int_compare:w
- \pdftex_strcmp:D
- { }
- { \tl_if_head_space_aux:w \prg_do_nothing: #1 ? ~ }
- = \c_zero
- \prg_return_true:
- \else:
- \prg_return_false:
- \fi:
+ \tex_romannumeral:D \if_false: { \fi:
+ \tl_if_head_space_aux:w ? #1 ? ~ }
}
-\cs_new:Npn \tl_if_head_space_aux:w #1 ~ %
+\cs_new:Npn \tl_if_head_space_aux:w #1 ~
{
- \exp_not:o {#1}
- \if_false: { \fi: }
+ \tl_if_empty:oTF { \use_none:n #1 }
+ { \exp_after:wN \c_zero \exp_after:wN \prg_return_true: }
+ { \exp_after:wN \c_zero \exp_after:wN \prg_return_false: }
\exp_after:wN \use_none:n \exp_after:wN { \if_false: } \fi:
}
% \end{macrocode}
@@ -2325,13 +2195,6 @@
% \end{macrocode}
% \end{variable}
%
-% \begin{variable}{\c_empty_tl}
-% Never full.
-% \begin{macrocode}
-\tl_const:Nn \c_empty_tl { }
-% \end{macrocode}
-% \end{variable}
-%
% \begin{variable}{\c_space_tl}
% A space as a token list (as opposed to as a character).
% \begin{macrocode}
@@ -2584,13 +2447,16 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\tl_reverse:N, \tl_reverse:c}
-% This reverses the list, leaving |{}| in front, which in turn
-% is removed by the \tn{unexpanded} primitive.
+% \begin{macro}{\tl_reverse:N, \tl_reverse:c, \tl_greverse:N, \tl_greverse:c}
+% This reverses the list, leaving \cs{exp_stop_f:} in front,
+% which stops the \texttt{f}-expansion.
% \begin{macrocode}
\cs_new_protected_nopar:Npn \tl_reverse:N #1
- { \tl_set:No #1 { \etex_unexpanded:D \tl_reverse:o { #1 { } } } }
-\cs_generate_variant:Nn \tl_reverse:N { c }
+ { \tl_set:Nf #1 { \tl_reverse:o { #1 \exp_stop_f: } } }
+\cs_new_protected_nopar:Npn \tl_greverse:N #1
+ { \tl_gset:Nf #1 { \tl_reverse:o { #1 \exp_stop_f: } } }
+\cs_generate_variant:Nn \tl_reverse:N { c }
+\cs_generate_variant:Nn \tl_greverse:N { c }
% \end{macrocode}
% \end{macro}
%
@@ -2685,6 +2551,41 @@
% \end{macro}
% \end{macro}
%
+% \begin{macro}{\tl_item:nn, \tl_item:Nn, \tl_item:cn}
+% \begin{macro}[aux]{\tl_item_aux: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
+% nothing at all.
+% \begin{macrocode}
+\cs_new:Npn \tl_item:nn #1#2
+ {
+ \exp_args:Nf \tl_item_aux:nn
+ {
+ \int_eval:n
+ {
+ \int_compare:nNnT {#2} < \c_zero
+ { \tl_length:n {#1} + }
+ #2
+ }
+ }
+ #1
+ \q_recursion_tail
+ \prg_break_point:n { }
+ }
+\cs_new_nopar:Npn \tl_item_aux:nn #1#2
+ {
+ \quark_if_recursion_tail_break:n {#2}
+ \int_compare:nNnTF {#1} = \c_zero
+ { \tl_map_break:n {#2} }
+ { \exp_args:Nf \tl_item_aux:nn { \int_eval:n { #1 - 1 } } }
+ }
+\cs_new_nopar:Npn \tl_item:Nn { \exp_args:No \tl_item:nn }
+\cs_generate_variant:Nn \tl_item:Nn { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
% \subsection{Deprecated functions}
%
% \begin{macro}{\tl_new:Nn, \tl_new:cn, \tl_new:Nx}