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.dtx117
1 files changed, 77 insertions, 40 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx b/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx
index b4ae4118b33..b48cbcd1854 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{l3bootstrap}
-\GetIdInfo$Id: l3tl.dtx 4201 2012-09-05 08:00:54Z joseph $
+\GetIdInfo$Id: l3tl.dtx 4244 2012-09-28 22:46:36Z bruno $
{L3 Token lists}
%</driver|package>
%<*driver>
@@ -352,35 +352,31 @@
%
% \section{Reassigning token list character codes}
%
-% \begin{function}{\tl_to_lowercase:n}
+% \begin{function}[updated = 2012-09-08]{\tl_to_lowercase:n}
% \begin{syntax}
% \cs{tl_to_lowercase:n} \Arg{tokens}
% \end{syntax}
-% Works through all of the \meta{tokens}, replacing each character
+% Works through all of the \meta{tokens}, replacing each character token
% with the lower case equivalent as defined by \cs{char_set_lccode:nn}.
% Characters with no defined lower case character code are left
% unchanged. This process does not alter the category code assigned
% to the \meta{tokens}.
% \begin{texnote}
-% This is the \TeX{} primitive \tn{lowercase} renamed. As a result,
-% its argument \emph{must} be given within braces, and this function
-% takes place on execution and not on expansion.
+% This is a wrapper around the \TeX{} primitive \tn{lowercase}.
% \end{texnote}
% \end{function}
%
-% \begin{function}{\tl_to_uppercase:n}
+% \begin{function}[updated = 2012-09-08]{\tl_to_uppercase:n}
% \begin{syntax}
% \cs{tl_to_uppercase:n} \Arg{tokens}
% \end{syntax}
-% Works through all of the \meta{tokens}, replacing each character
+% Works through all of the \meta{tokens}, replacing each character token
% with the upper case equivalent as defined by \cs{char_set_uccode:nn}.
-% Characters with no defined lower case character code are left
+% Characters with no defined upper case character code are left
% unchanged. This process does not alter the category code assigned
% to the \meta{tokens}.
% \begin{texnote}
-% This is the \TeX{} primitive \tn{uppercase} renamed. As a result,
-% its argument \emph{must} be given within braces, and this function
-% takes place on execution and not on expansion.
+% This is a wrapper around the \TeX{} primitive \tn{uppercase}.
% \end{texnote}
% \end{function}
%
@@ -784,7 +780,7 @@
% Functions which deal with either only the very first item (balanced
% text or single normal token) in a token list, or the remaining tokens.
%
-% \begin{function}[updated = 2012-02-08, EXP]
+% \begin{function}[updated = 2012-09-09, EXP]
% {\tl_head:N, \tl_head:n, \tl_head:V, \tl_head:v, \tl_head:f}
% \begin{syntax}
% \cs{tl_head:n} \Arg{token list}
@@ -809,8 +805,7 @@
% \end{verbatim}
% yields \verb*| ab|.
% A blank \meta{token list} (see \cs{tl_if_blank:nTF}) will result in
-% \cs{tl_head:n} leaving nothing in the input stream. The \meta{token list}
-% should not contain the marker \cs{q_stop}.
+% \cs{tl_head:n} leaving nothing in the input stream.
% \begin{texnote}
% The result is returned within \cs{exp_not:n}, which means that the token
% list will not expand further when appearing in an \texttt{x}-type
@@ -960,24 +955,25 @@
%
% \section{Viewing token lists}
%
-% \begin{function}{\tl_show:N, \tl_show:c}
+% \begin{function}[updated = 2012-09-09]{\tl_show:N, \tl_show:c}
% \begin{syntax}
% \cs{tl_show:N} \meta{tl~var}
% \end{syntax}
% Displays the content of the \meta{tl~var} on the terminal.
% \begin{texnote}
-% \cs{tl_show:N} is the \TeX{} primitive \tn{show}.
+% This is similar to the \TeX{} primitive \tn{show}, wrapped to a
+% fixed number of characters per line.
% \end{texnote}
% \end{function}
%
-% \begin{function}{\tl_show:n}
+% \begin{function}[updated = 2012-09-09]{\tl_show:n}
% \begin{syntax}
% \cs{tl_show:n} \meta{token list}
% \end{syntax}
% Displays the \meta{token list} on the terminal.
% \begin{texnote}
-% \cs{tl_show:n} is the \eTeX{} primitive \tn{showtokens}.
-% Hence its argument \emph{must} be given within braces.
+% This is similar to the \eTeX{} primitive \tn{showtokens}, wrapped
+% to a fixed number of characters per line.
% \end{texnote}
% \end{function}
%
@@ -1428,10 +1424,13 @@
%
% \begin{macro}{\tl_to_lowercase:n}
% \begin{macro}{\tl_to_uppercase:n}
-% Just some names for a few primitives.
+% Just some names for a few primitives: we take care or wrapping the
+% argument in braces.
% \begin{macrocode}
-\cs_new_eq:NN \tl_to_lowercase:n \tex_lowercase:D
-\cs_new_eq:NN \tl_to_uppercase:n \tex_uppercase:D
+\cs_new_protected:Npn \tl_to_lowercase:n #1
+ { \tex_lowercase:D {#1} }
+\cs_new_protected:Npn \tl_to_uppercase:n #1
+ { \tex_uppercase:D {#1} }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -1696,15 +1695,15 @@
% \end{macro}
%
% \begin{macro}[TF]{\tl_if_eq:nn}
-% \begin{variable}{\l_tl_internal_a_tl, \l_tl_internal_b_tl}
+% \begin{variable}{\l_@@_internal_a_tl, \l_@@_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_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
+ \tl_set:Nn \l_@@_internal_a_tl {#1}
+ \tl_set:Nn \l_@@_internal_b_tl {#2}
+ \if_meaning:w \l_@@_internal_a_tl \l_@@_internal_b_tl
\group_end:
\prg_return_true:
\else:
@@ -1712,8 +1711,8 @@
\prg_return_false:
\fi:
}
-\tl_new:N \l_tl_internal_a_tl
-\tl_new:N \l_tl_internal_b_tl
+\tl_new:N \l_@@_internal_a_tl
+\tl_new:N \l_@@_internal_b_tl
% \end{macrocode}
% \end{variable}
% \end{macro}
@@ -2224,18 +2223,42 @@
%
% \subsection{The first token from a token list}
%
-% \begin{macro}{\tl_head:w}
% \begin{macro}{\tl_head:N, \tl_head:n, \tl_head:V, \tl_head:v, \tl_head:f}
+% \begin{macro}[aux]{\@@_head_i:nw, \@@_head_ii:nw}
+% \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 will always strip braces, which
% is fine as this is consistent with for example mapping to a list. The
-% empty brace groups in \cs{tl_head:n} ensure that a blank argument gives an
-% empty result. The result is returned within the \tn{unexpanded} primitive.
+% empty brace groups in \cs{tl_head:n} ensure that a blank argument gives an
+% empty result. The result is returned within the \tn{unexpanded} primitive.
+% The approach here is to use \cs{if_false:} to allow us to use |}| as
+% the closing delimiter: this is the only safe choice, as any other token
+% would not be able to parse it's own code. Using a marker, we can see if
+% what we are grabbing is exactly the marker, or there is anything else to
+% deal with. Is there is, there is a loop. If not, tidy up and leave the
+% item in the output stream. More detail in
+% \url{http://tex.stackexchange.com/a/70168}.
% \begin{macrocode}
-\cs_new:Npn \tl_head:w #1#2 \q_stop {#1}
\cs_new:Npn \tl_head:n #1
- { \etex_unexpanded:D \exp_after:wN { \tl_head:w #1 { } \q_stop } }
+ {
+ \etex_unexpanded:D
+ \if_false: { \fi: \@@_head_i:nw #1 { } \q_stop }
+ }
+\cs_new:Npn \@@_head_i:nw #1#2 \q_stop
+ { \exp_after:wN \@@_head_ii:nw \exp_after:wN { \if_false: } \fi: {#1} }
+\cs_new:Npn \@@_head_ii:nw #1
+ {
+ \exp_after:wN \if_meaning:w \exp_after:wN \q_nil
+ \tl_to_str:n \exp_after:wN { \use_none:n #1 } \q_nil
+ \exp_after:wN \use_i:nn
+ \else:
+ \exp_after:wN \use_ii:nn
+ \fi:
+ {#1}
+ { \if_false: { \fi: \@@_head_i:nw #1 } }
+ }
\cs_generate_variant:Nn \tl_head:n { V , v , f }
+\cs_new:Npn \tl_head:w #1#2 \q_stop {#1}
\cs_new_nopar:Npn \tl_head:N { \exp_args:No \tl_head:n }
% \end{macrocode}
% To corrected leave the tail of a token list, it's important \emph{not} to
@@ -2266,6 +2289,7 @@
% \end{macro}
% \end{macro}
% \end{macro}
+% \end{macro}
%
% \begin{macro}{\str_head:n, \str_tail:n}
% \begin{macro}[aux]{\__str_head:w}
@@ -2514,18 +2538,31 @@
% \subsection{Viewing token lists}
%
% \begin{macro}{\tl_show:N, \tl_show:c}
-% Showing token list variables is done directly: at the moment do not
-% worry if they are defined.
+% 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_show:N #1 }
+\cs_new_protected:Npn \tl_show:N #1
+ {
+ \cs_if_exist:NTF #1
+ { \cs_show:N #1 }
+ {
+ \__msg_kernel_error:nnx { kernel } { variable-not-defined }
+ { \token_to_str:N #1 }
+ }
+ }
\cs_generate_variant:Nn \tl_show:N { c }
% \end{macrocode}
%\end{macro}
%
% \begin{macro}{\tl_show:n}
-% For literal token lists, life is easy.
-% \begin{macrocode}
-\cs_new_eq:NN \tl_show:n \etex_showtokens:D
+% The \cs{__msg_show_variable:n} internal function performs
+% line-wrapping, removes a leading \verb*|> |, then 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{macrocode}
+\cs_new_protected:Npn \tl_show:n #1
+ { \__msg_show_variable:n { > ~ \tl_to_str:n {#1} } }
% \end{macrocode}
%\end{macro}
%