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