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.dtx160
1 files changed, 107 insertions, 53 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx b/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx
index 1424199ecd6..42e16e29c9e 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-%% File: l3tl.dtx Copyright (C) 1990-2011 The LaTeX3 Project
+%% File: l3tl.dtx Copyright (C) 1990-2012 The LaTeX3 Project
%%
%% It may be distributed and/or modified under the conditions of the
%% LaTeX Project Public License (LPPL), either version 1.3c of this
@@ -35,7 +35,7 @@
%
%<*driver|package>
\RequirePackage{l3names}
-\GetIdInfo$Id: l3tl.dtx 3091 2011-12-25 16:22:59Z bruno $
+\GetIdInfo$Id: l3tl.dtx 3158 2012-01-09 00:47:42Z bruno $
{L3 Experimental token lists}
%</driver|package>
%<*driver>
@@ -596,7 +596,7 @@
% giving an \meta{integer denotation}.
% \end{function}
%
-% \begin{function}[updated = 2011-08-13, EXP]
+% \begin{function}[updated = 2012-01-08, EXP]
% {\tl_reverse:n, \tl_reverse:V, \tl_reverse:o}
% \begin{syntax}
% \cs{tl_reverse:n} \Arg{token list}
@@ -610,9 +610,15 @@
% In situations where performance is important,
% consider \cs{tl_reverse_items:n}.
% See also \cs{tl_reverse:N}.
+% \begin{texnote}
+% The result is returned within the \tn{unexpanded}
+% primitive (\cs{exp_not:n}), which means that the token
+% list will not expand further when appearing in an x-type
+% argument expansion.
+% \end{texnote}
% \end{function}
%
-% \begin{function}[updated = 2011-11-22]
+% \begin{function}[updated = 2012-01-08]
% {\tl_reverse:N, \tl_reverse:c, \tl_greverse:N, \tl_greverse:c}
% \begin{syntax}
% \cs{tl_reverse:N} \Arg{tl~var}
@@ -626,7 +632,7 @@
% See also \cs{tl_reverse:n}.
% \end{function}
%
-% \begin{function}[added = 2011-08-13, EXP]{\tl_reverse_items:n}
+% \begin{function}[added = 2012-01-08, EXP]{\tl_reverse_items:n}
% \begin{syntax}
% \cs{tl_reverse_items:n} \Arg{token list}
% \end{syntax}
@@ -639,6 +645,12 @@
% Items which are initially not braced are copied with braces in
% the result. In cases where preserving spaces is important,
% consider \cs{tl_reverse:n} or \cs{tl_reverse_tokens:n}.
+% \begin{texnote}
+% The result is returned within the \tn{unexpanded}
+% primitive (\cs{exp_not:n}), which means that the token
+% list will not expand further when appearing in an x-type
+% argument expansion.
+% \end{texnote}
% \end{function}
%
% \begin{function}[added = 2011-07-09, updated = 2011-08-13, EXP]
@@ -650,7 +662,7 @@
% from the \meta{token list} and leaves the result in the input
% stream. This process requires two expansions.
% \begin{texnote}
-% The result is return within the \tn{unexpanded}
+% The result is returned within the \tn{unexpanded}
% primitive (\cs{exp_not:n}), which means that the token
% list will not expand further when appearing in an x-type
% argument expansion.
@@ -674,7 +686,7 @@
% Functions which deal with either only the very first token of a
% token list or everything except the first token.
%
-% \begin{function}[updated = 2011-08-09, EXP]
+% \begin{function}[updated = 2012-01-08, EXP]
% {\tl_head:n, \tl_head:V, \tl_head:v, \tl_head:f}
% \begin{syntax}
% \cs{tl_head:n} \Arg{tokens}
@@ -693,6 +705,12 @@
% An empty list of \meta{tokens} or one which consists
% only of space (category code $10$) tokens will result in \cs{tl_head:n}
% leaving nothing in the input stream.
+% \begin{texnote}
+% The result is returned within the \tn{unexpanded}
+% primitive (\cs{exp_not:n}), which means that the token
+% list will not expand further when appearing in an x-type
+% argument expansion.
+% \end{texnote}
% \end{function}
%
% \begin{function}[EXP]{\tl_head:w}
@@ -709,7 +727,7 @@
% is not critical.
% \end{function}
%
-% \begin{function}[updated = 2011-08-09, EXP]
+% \begin{function}[updated = 2012-01-08, EXP]
% {\tl_tail:n, \tl_tail:V, \tl_tail:v, \tl_tail:f}
% \begin{syntax}
% \cs{tl_tail:n} \Arg{tokens}
@@ -728,6 +746,12 @@
% An empty list of \meta{tokens} or one which consists
% only of space (category code $10$) tokens will result in \cs{tl_tail:n}
% leaving nothing in the input stream.
+% \begin{texnote}
+% The result is returned within the \tn{unexpanded}
+% primitive (\cs{exp_not:n}), which means that the token
+% list will not expand further when appearing in an x-type
+% argument expansion.
+% \end{texnote}
% \end{function}
%
% \begin{function}[EXP]{\tl_tail:w}
@@ -911,7 +935,7 @@
%
% \section{Experimental token list functions}
%
-% \begin{function}[added = 2011-08-11, EXP]{\tl_reverse_tokens:n}
+% \begin{function}[added = 2012-01-08, EXP]{\tl_reverse_tokens:n}
% \begin{syntax}
% \cs{tl_reverse_tokens:n} \Arg{tokens}
% \end{syntax}
@@ -923,6 +947,12 @@
% list. For instance, \cs{tl_reverse_tokens:n} |{a~{b()}}|
% leaves |{)(b}~a| in the input stream. This function requires
% two steps of expansion.
+% \begin{texnote}
+% The result is returned within the \tn{unexpanded}
+% primitive (\cs{exp_not:n}), which means that the token
+% list will not expand further when appearing in an x-type
+% argument expansion.
+% \end{texnote}
% \end{function}
%
% \begin{function}[added = 2011-08-11, EXP]{\tl_length_tokens:n}
@@ -937,7 +967,7 @@
% giving an \meta{integer denotation}.
% \end{function}
%
-% \begin{function}[added = 2011-08-13, EXP]
+% \begin{function}[added = 2012-01-08, EXP]
% {\tl_expandable_uppercase:n,\tl_expandable_lowercase:n}
% \begin{syntax}
% \cs{tl_expandable_uppercase:n} \Arg{tokens}
@@ -953,10 +983,14 @@
% \begin{texnote}
% Begin-group and end-group characters are normalized and become
% |{| and |}|, respectively.
+% The result is returned within the \tn{unexpanded}
+% primitive (\cs{exp_not:n}), which means that the token
+% list will not expand further when appearing in an x-type
+% argument expansion.
% \end{texnote}
% \end{function}
%
-% \begin{function}[added = 2011-11-21, EXP]
+% \begin{function}[added = 2011-11-21, updated = 2012-01-08, EXP]
% {\tl_item:nn, \tl_item:Nn, \tl_item:cn}
% \begin{syntax}
% \cs{tl_item:nn} \Arg{token list} \Arg{integer expression}
@@ -965,8 +999,14 @@
% 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.
+% the right of the token list, starting at $-1$ for the right-most item.
% If the index is out of bounds, then thr function expands to nothing.
+% \begin{texnote}
+% The result is returned within the \tn{unexpanded}
+% primitive (\cs{exp_not:n}), which means that the \meta{item}
+% will not expand further when appearing in an x-type
+% argument expansion.
+% \end{texnote}
% \end{function}
%
% \section{Internal functions}
@@ -1313,14 +1353,6 @@
%
% \subsection{Modifying token list variables}
%
-% \begin{variable}{\l_tl_replace_tl}
-% A scratch variable for doing token replacement.
-% \begin{macrocode}
-\tl_new:N \l_tl_replace_tl
-% \end{macrocode}
-% \end{variable}
-%
-%
% \begin{macro}{\tl_replace_all:Nnn, \tl_replace_all:cnn}
% \begin{macro}{\tl_greplace_all:Nnn, \tl_greplace_all:cnn}
% \begin{macro}{\tl_replace_once:Nnn, \tl_replace_once:cnn}
@@ -1578,15 +1610,15 @@
% \end{macro}
%
% \begin{macro}[TF]{\tl_if_eq:nn}
-% \begin{variable}{\l_tl_tmpa_tl, \l_tl_tmpb_tl}
+% \begin{variable}{\l_tl_internal_a_tl, \l_tl_internal_b_tl}
% A simple store and compare routine.
% \begin{macrocode}
\prg_new_protected_conditional:Npnn \tl_if_eq:nn #1#2 { T , F , TF }
{
\group_begin:
- \tl_set:Nn \l_tl_tmpa_tl {#1}
- \tl_set:Nn \l_tl_tmpb_tl {#2}
- \if_meaning:w \l_tl_tmpa_tl \l_tl_tmpb_tl
+ \tl_set:Nn \l_tl_internal_a_tl {#1}
+ \tl_set:Nn \l_tl_internal_b_tl {#2}
+ \if_meaning:w \l_tl_internal_a_tl \l_tl_internal_b_tl
\group_end:
\prg_return_true:
\else:
@@ -1594,8 +1626,8 @@
\prg_return_false:
\fi:
}
-\tl_new:N \l_tl_tmpa_tl
-\tl_new:N \l_tl_tmpb_tl
+\tl_new:N \l_tl_internal_a_tl
+\tl_new:N \l_tl_internal_b_tl
% \end{macrocode}
% \end{variable}
% \end{macro}
@@ -1795,7 +1827,7 @@
% \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}.
+% and putting it after \cs{q_stop}.
% \begin{macrocode}
\cs_new:Npn \tl_reverse_items:n #1
{
@@ -1811,7 +1843,8 @@
\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 }
+\cs_new:Npn \tl_reverse_items_aux:wn #1 \q_stop #2
+ { \exp_not:o { \use_none:nn #2 } }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -1905,15 +1938,16 @@
% \begin{macro}{\tl_tail:w}
% These functions pick up either the head or the tail of a list. The
% empty brace groups in \cs{tl_head:n} and \cs{tl_tail:n} ensure that
-% a blank argument gives an empty result.
+% a blank argument gives an empty result. The result is returned within
+% the \tn{unexpanded} primitive.
% \begin{macrocode}
\cs_new:Npn \tl_head:w #1#2 \q_stop {#1}
\cs_new:Npn \tl_tail:w #1#2 \q_stop {#2}
\cs_new:Npn \tl_head:n #1
- { \tl_head:w #1 { } \q_stop }
+ { \etex_unexpanded:D \exp_after:wN { \tl_head:w #1 { } \q_stop } }
\cs_new:Npn \tl_tail:n #1
- { \tl_tail_aux:w #1 \q_mark { } \q_mark \q_stop }
-\cs_new:Npn \tl_tail_aux:w #1 #2 \q_mark #3 \q_stop { #2 }
+ { \etex_unexpanded:D \tl_tail_aux:w #1 \q_mark { } \q_mark \q_stop }
+\cs_new:Npn \tl_tail_aux:w #1 #2 \q_mark #3 \q_stop { {#2} }
\cs_generate_variant:Nn \tl_head:n { V , v , f }
\cs_generate_variant:Nn \tl_tail:n { V , v , f }
% \end{macrocode}
@@ -2397,14 +2431,18 @@
% upper/lowercasing action stores the information of whether it
% is uppercasing or lowercasing.
% \begin{macrocode}
-\cs_new:Npn \tl_reverse_tokens:n
+\cs_new:Npn \tl_reverse_tokens:n #1
{
- \tex_romannumeral:D
- \tl_act_aux:NNNnn
- \tl_act_reverse_normal:nN
- \tl_act_reverse_group:nn
- \tl_act_reverse_space:n
- { }
+ \etex_unexpanded:D \exp_after:wN
+ {
+ \tex_romannumeral:D
+ \tl_act_aux:NNNnn
+ \tl_act_reverse_normal:nN
+ \tl_act_reverse_group:nn
+ \tl_act_reverse_space:n
+ { }
+ {#1}
+ }
}
\cs_new:Npn \tl_act_reverse_space:n #1
{ \tl_act_reverse_output:n {~} }
@@ -2426,14 +2464,18 @@
% The only difference with \cs{tl_reverse_tokens:n} is that
% we now simply output groups without entering them.
% \begin{macrocode}
-\cs_new:Npn \tl_reverse:n
+\cs_new:Npn \tl_reverse:n #1
{
- \tex_romannumeral:D
- \tl_act_aux:NNNnn
- \tl_act_reverse_normal:nN
- \tl_act_reverse_group_preserve:nn
- \tl_act_reverse_space:n
- { }
+ \etex_unexpanded:D \exp_after:wN
+ {
+ \tex_romannumeral:D
+ \tl_act_aux:NNNnn
+ \tl_act_reverse_normal:nN
+ \tl_act_reverse_group_preserve:nn
+ \tl_act_reverse_space:n
+ { }
+ {#1}
+ }
}
\cs_new:Npn \tl_act_reverse_group_preserve:nn #1 #2
{ \tl_act_reverse_output:n { {#2} } }
@@ -2447,9 +2489,9 @@
% which stops the \texttt{f}-expansion.
% \begin{macrocode}
\cs_new_protected:Npn \tl_reverse:N #1
- { \tl_set:Nf #1 { \tl_reverse:o { #1 \exp_stop_f: } } }
+ { \tl_set:Nx #1 { \exp_args:No \tl_reverse:n { #1 } } }
\cs_new_protected:Npn \tl_greverse:N #1
- { \tl_gset:Nf #1 { \tl_reverse:o { #1 \exp_stop_f: } } }
+ { \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}
@@ -2517,10 +2559,22 @@
% \tn{romannumeral}, which expands fully to give the
% converted group), then output.
% \begin{macrocode}
-\cs_new:Npn \tl_expandable_uppercase:n
- { \tex_romannumeral:D \tl_act_case_aux:nn { \c_tl_act_uppercase_tl } }
-\cs_new:Npn \tl_expandable_lowercase:n
- { \tex_romannumeral:D \tl_act_case_aux:nn { \c_tl_act_lowercase_tl } }
+\cs_new:Npn \tl_expandable_uppercase:n #1
+ {
+ \etex_unexpanded:D \exp_after:wN
+ {
+ \tex_romannumeral:D
+ \tl_act_case_aux:nn { \c_tl_act_uppercase_tl } {#1}
+ }
+ }
+\cs_new:Npn \tl_expandable_lowercase:n #1
+ {
+ \etex_unexpanded:D \exp_after:wN
+ {
+ \tex_romannumeral:D
+ \tl_act_case_aux:nn { \c_tl_act_lowercase_tl } {#1}
+ }
+ }
\cs_new:Npn \tl_act_case_aux:nn
{
\tl_act_aux:NNNnn
@@ -2572,7 +2626,7 @@
{
\quark_if_recursion_tail_break:n {#2}
\int_compare:nNnTF {#1} = \c_zero
- { \tl_map_break:n {#2} }
+ { \tl_map_break:n { \exp_not: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 }