diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3tl.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3tl.dtx | 822 |
1 files changed, 416 insertions, 406 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx b/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx index 13625c2542e..bda39b5cf09 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3tl.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2021-10-18} +% \date{Released 2021-11-12} % % \maketitle % @@ -205,159 +205,6 @@ % \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_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 |#| -% (more precisely, explicit character tokens with category code $1$ -% (begin-group) or $2$ (end-group), and tokens with category code $6$). -% \end{function} -% -% \begin{function}[updated = 2011-08-11] -% { -% \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} -% Replaces all occurrences of \meta{old tokens} in the -% \meta{tl~var} with \meta{new tokens}. \meta{Old tokens} -% cannot contain |{|, |}| or |#| -% (more precisely, explicit character tokens with category code $1$ -% (begin-group) or $2$ (end-group), and tokens with category code $6$). -% 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). -% \end{function} -% -% \begin{function}[updated = 2011-08-11] -% { -% \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 |#| -% (more precisely, explicit character tokens with category code $1$ -% (begin-group) or $2$ (end-group), and tokens with category code $6$). -% \end{function} -% -% \begin{function}[updated = 2011-08-11] -% { -% \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} -% Removes all occurrences of \meta{tokens} from the -% \meta{tl~var}. \meta{Tokens} cannot contain |{|, |}| or |#| -% (more precisely, explicit character tokens with category code $1$ -% (begin-group) or $2$ (end-group), and tokens with category code $6$). -% As this function -% operates from left to right, the pattern \meta{tokens} -% may remain after the removal, for instance, -% \begin{quote} -% \cs{tl_set:Nn} \cs{l_tmpa_tl} |{abbccd}| -% \cs{tl_remove_all:Nn} \cs{l_tmpa_tl} |{bc}| -% \end{quote} -% results in \cs{l_tmpa_tl} containing \texttt{abcd}. -% \end{function} -% -% \section{Reassigning token list category codes} -% -% These functions allow the rescanning of tokens: re-apply \TeX{}'s -% tokenization process to apply category codes different from those -% in force when the tokens were absorbed. Whilst this functionality is -% supported, it is often preferable to find alternative approaches -% to achieving outcomes rather than rescanning tokens (for example -% construction of token lists token-by-token with intervening category -% code changes or using \cs{char_generate:nn}). -% -% \begin{function}[updated = 2015-08-11] -% { -% \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\'{e}gime specified in the \meta{setup} before carrying out -% the assignment. (Category codes applied to tokens not explicitly covered -% by the \meta{setup} are those in force at the point of use of -% \cs{tl_set_rescan:Nnn}.) -% This allows the \meta{tl~var} to contain material -% with category codes other than those that apply when \meta{tokens} -% are absorbed. The \meta{setup} is run within a group and may -% contain any valid input, although only changes in category codes, -% such as uses of \cs{cctab_select:N}, -% are relevant. See also \cs{tl_rescan:nn}. -% \begin{texnote} -% The \meta{tokens} are first turned into a string (using -% \cs{tl_to_str:n}). If the string contains one or more characters -% with character code \tn{newlinechar} (set equal to -% \tn{endlinechar} unless that is equal to $32$, before the user -% \meta{setup}), then it is split into lines at these characters, -% then read as if reading multiple lines from a file, ignoring -% spaces (catcode $10$) at the beginning and spaces and tabs -% (character code $32$ or $9$) at the end of every line. -% Otherwise, spaces (and tabs) are retained at both ends of the -% single-line string, as if it appeared in the middle of a line -% read from a file. -% \end{texnote} -% \end{function} -% -% \begin{function}[updated = 2015-08-11]{\tl_rescan:nn} -% \begin{syntax} -% \cs{tl_rescan:nn} \Arg{setup} \Arg{tokens} -% \end{syntax} -% Rescans \meta{tokens} applying the category code r\'{e}gime -% specified in the \meta{setup}, and leaves the resulting tokens in -% the input stream. (Category codes applied to tokens not explicitly covered -% by the \meta{setup} are those in force at the point of use of -% \cs{tl_rescan:nn}.) -% The \meta{setup} is run within a group and may -% contain any valid input, although only changes in category codes, -% such as uses of \cs{cctab_select:N}, -% are relevant. See also \cs{tl_set_rescan:Nnn}, which is more -% robust than using \cs{tl_set:Nn} in the \meta{tokens} argument of -% \cs{tl_rescan:nn}. -% \begin{texnote} -% The \meta{tokens} are first turned into a string (using -% \cs{tl_to_str:n}). If the string contains one or more characters -% with character code \tn{newlinechar} (set equal to -% \tn{endlinechar} unless that is equal to $32$, before the user -% \meta{setup}), then it is split into lines at these characters, -% then read as if reading multiple lines from a file, ignoring -% spaces (catcode $10$) at the beginning and spaces and tabs -% (character code $32$ or $9$) at the end of every line. -% Otherwise, spaces (and tabs) are retained at both ends of the -% single-line string, as if it appeared in the middle of a line -% read from a file. -% -% Contrarily to the \tn{scantokens} primitive, \cs{tl_rescan:nn} -% tokenizes the whole string in the same category code regime rather -% than one token at a time, so that directives such as \tn{verb} -% that rely on changing category codes will not function properly. -% \end{texnote} -% \end{function} -% % \section{Token list conditionals} % % \begin{function}[EXP,pTF, updated = 2019-09-04] @@ -473,7 +320,7 @@ % \cs{tl_if_single_p:N} \meta{tl~var} % \cs{tl_if_single:NTF} \meta{tl~var} \Arg{true code} \Arg{false code} % \end{syntax} -% Tests if the content of the \meta{tl~var} consists of a single item, +% Tests if the content of the \meta{tl~var} consists of a single \meta{item}, % \emph{i.e.}~is a single normal token (neither an explicit space % character nor a begin-group character) or a single brace group, % surrounded by optional spaces on both sides. In other words, such a @@ -485,7 +332,7 @@ % \cs{tl_if_single_p:n} \Arg{token list} % \cs{tl_if_single:nTF} \Arg{token list} \Arg{true code} \Arg{false code} % \end{syntax} -% Tests if the \meta{token list} has exactly one item, \emph{i.e.}~is +% Tests if the \meta{token list} has exactly one \meta{item}, \emph{i.e.}~is % a single normal token (neither an explicit space character nor a % begin-group character) or a single brace group, surrounded by % optional spaces on both sides. In other words, such a token list has @@ -498,7 +345,7 @@ % \cs{tl_if_single_token:nTF} \Arg{token list} \Arg{true code} \Arg{false code} % \end{syntax} % Tests if the token list consists of exactly one token, \emph{i.e.}~is -% either a single space character or a single \enquote{normal} token. +% either a single space character or a single normal token. % Token groups (|{|\ldots|}|) are not single tokens. % \end{function} % @@ -526,152 +373,93 @@ % available. % \end{function} % -% \section{Mapping over token lists} +% \subsection{Testing the first token} % -% All mappings are done at the current group level, \emph{i.e.}~any -% local assignments made by the \meta{function} or \meta{code} discussed -% below remain in effect after the loop. -% -% \begin{function}[updated = 2012-06-29, rEXP] -% {\tl_map_function:NN, \tl_map_function:cN} -% \begin{syntax} -% \cs{tl_map_function:NN} \meta{tl~var} \meta{function} -% \end{syntax} -% Applies \meta{function} to every \meta{item} in the \meta{tl~var}. -% The \meta{function} receives one argument for each iteration. -% This may be a number of tokens if the \meta{item} was stored within -% braces. Hence the \meta{function} should anticipate receiving -% \texttt{n}-type arguments. See also \cs{tl_map_function:nN}. -% \end{function} -% -% \begin{function}[updated = 2012-06-29, rEXP]{\tl_map_function:nN} -% \begin{syntax} -% \cs{tl_map_function:nN} \Arg{token list} \meta{function} -% \end{syntax} -% Applies \meta{function} to every \meta{item} in the \meta{token list}, -% The \meta{function} receives one argument for each iteration. -% This may be a number of tokens if the \meta{item} was stored within -% braces. Hence the \meta{function} should anticipate receiving -% \texttt{n}-type arguments. See also \cs{tl_map_function:NN}. -% \end{function} -% -% \begin{function}[updated = 2012-06-29] -% {\tl_map_inline:Nn, \tl_map_inline:cn} +% \begin{function}[updated = 2012-07-09, EXP, pTF] +% {\tl_if_head_eq_catcode:nN, \tl_if_head_eq_catcode:oN} % \begin{syntax} -% \cs{tl_map_inline:Nn} \meta{tl~var} \Arg{inline function} +% \cs{tl_if_head_eq_catcode_p:nN} \Arg{token list} \meta{test token} +% \cs{tl_if_head_eq_catcode:nNTF} \Arg{token list} \meta{test token} +% ~~\Arg{true code} \Arg{false code} % \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|. See also \cs{tl_map_function:NN}. +% Tests if the first \meta{token} in the \meta{token list} has the +% same category code as the \meta{test token}. In the case where the +% \meta{token list} is empty, the test is always \texttt{false}. % \end{function} % -% \begin{function}[updated = 2012-06-29]{\tl_map_inline:nn} +% \begin{function}[updated = 2012-07-09, EXP, pTF] +% {\tl_if_head_eq_charcode:nN, \tl_if_head_eq_charcode:fN} % \begin{syntax} -% \cs{tl_map_inline:nn} \Arg{token list} \Arg{inline function} +% \cs{tl_if_head_eq_charcode_p:nN} \Arg{token list} \meta{test token} +% \cs{tl_if_head_eq_charcode:nNTF} \Arg{token list} \meta{test token} +% ~~\Arg{true code} \Arg{false code} % \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|. See also \cs{tl_map_function:nN}. +% Tests if the first \meta{token} in the \meta{token list} has the +% same character code as the \meta{test token}. In the case where the +% \meta{token list} is empty, the test is always \texttt{false}. % \end{function} % -% \begin{function}[rEXP, added = 2019-09-02] -% {\tl_map_tokens:Nn, \tl_map_tokens:cn, \tl_map_tokens:nn} +% \begin{function}[updated = 2012-07-09, EXP, pTF]{\tl_if_head_eq_meaning:nN} % \begin{syntax} -% \cs{tl_map_tokens:Nn} \meta{tl~var} \Arg{code} -% \cs{tl_map_tokens:nn} \Arg{tokens} \Arg{code} +% \cs{tl_if_head_eq_meaning_p:nN} \Arg{token list} \meta{test token} +% \cs{tl_if_head_eq_meaning:nNTF} \Arg{token list} \meta{test token} +% ~~\Arg{true code} \Arg{false code} % \end{syntax} -% Analogue of \cs{tl_map_function:NN} which maps several tokens -% instead of a single function. The \meta{code} receives each item in -% the \meta{tl~var} or in \meta{tokens} as a trailing brace group. For -% instance, -% \begin{verbatim} -% \tl_map_tokens:Nn \l_my_tl { \prg_replicate:nn { 2 } } -% \end{verbatim} -% expands to twice each item in the \meta{tl~var}: for each item in -% \cs[no-index]{l_my_tl} the function \cs{prg_replicate:nn} receives |2| and -% \meta{item} as its two arguments. The function -% \cs{tl_map_inline:Nn} is typically faster but is not expandable. +% Tests if the first \meta{token} in the \meta{token list} has the +% same meaning as the \meta{test token}. In the case where +% \meta{token list} is empty, the test is always \texttt{false}. % \end{function} % -% \begin{function}[updated = 2012-06-29] -% {\tl_map_variable:NNn, \tl_map_variable:cNn} +% \begin{function}[added = 2012-07-08, EXP, pTF]{\tl_if_head_is_group:n} % \begin{syntax} -% \cs{tl_map_variable:NNn} \meta{tl~var} \meta{variable} \Arg{code} +% \cs{tl_if_head_is_group_p:n} \Arg{token list} +% \cs{tl_if_head_is_group:nTF} \Arg{token list} \Arg{true code} \Arg{false code} % \end{syntax} -% 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. Its -% value after the loop is the last \meta{item} in the \meta{tl~var}, -% or its original value if the \meta{tl~var} is blank. See also -% \cs{tl_map_inline:Nn}. +% Tests if the first \meta{token} in the \meta{token list} +% is an explicit begin-group character (with category code~$1$ +% and any character code), in other words, if the \meta{token list} +% starts with a brace group. In particular, the test is \texttt{false} +% if the \meta{token list} starts with an implicit token such as +% \cs{c_group_begin_token}, or if it is empty. +% This function is useful to implement actions on token lists on +% a token by token basis. % \end{function} % -% \begin{function}[updated = 2012-06-29]{\tl_map_variable:nNn} +% \begin{function}[added = 2012-07-08, EXP, pTF]{\tl_if_head_is_N_type:n} % \begin{syntax} -% \cs{tl_map_variable:nNn} \Arg{token list} \meta{variable} \Arg{code} +% \cs{tl_if_head_is_N_type_p:n} \Arg{token list} +% \cs{tl_if_head_is_N_type:nTF} \Arg{token list} \Arg{true code} \Arg{false code} % \end{syntax} -% 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. -% Its value after the loop is the last \meta{item} in the -% \meta{tl~var}, or its original value if the \meta{tl~var} is blank. -% See also \cs{tl_map_inline:nn}. +% Tests if the first \meta{token} in the \meta{token list} +% is a normal \texttt{N}-type argument. In other words, +% it is neither an explicit space character +% (explicit token with character code~$32$ and category code~$10$) +% nor an explicit begin-group character +% (with category code~1 and any character code). An empty +% argument yields \texttt{false}, as it does not have a normal +% first token. +% This function is useful to implement actions on token lists on +% a token by token basis. % \end{function} % -% \begin{function}[updated = 2012-06-29, rEXP]{\tl_map_break:} +% \begin{function}[updated = 2012-07-08, EXP, pTF]{\tl_if_head_is_space:n} % \begin{syntax} -% \cs{tl_map_break:} +% \cs{tl_if_head_is_space_p:n} \Arg{token list} +% \cs{tl_if_head_is_space:nTF} \Arg{token list} \Arg{true code} \Arg{false 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. 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: } -% % Do something useful -% } -% \end{verbatim} -% See also \cs{tl_map_break:n}. -% 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 -% before the \meta{tokens} are -% inserted into the input stream. -% This depends on the design of the mapping function. -% \end{texnote} +% Tests if the first \meta{token} in the \meta{token list} +% is an explicit space character +% (explicit token with character code~$12$ and category code~$10$). +% In particular, the test is \texttt{false} if the \meta{token list} +% starts with an implicit token such as \cs{c_space_token}, or if it +% is empty. +% This function is useful to implement actions on token lists on +% a token by token basis. % \end{function} % -% \begin{function}[updated = 2012-06-29, rEXP]{\tl_map_break:n} -% \begin{syntax} -% \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{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 { <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 -% before the \meta{code} is -% inserted into the input stream. -% This depends on the design of the mapping function. -% \end{texnote} -% \end{function} +% \section{Working with token lists as a whole} % -% \section{Using token lists} +% \subsection{Using token lists} % % \begin{function}[EXP]{\tl_to_str:n, \tl_to_str:V} % \begin{syntax} @@ -733,7 +521,7 @@ % a \meta{tl~var} directly without an accessor function. % \end{function} % -% \section{Working with the content of token lists} +% \subsection{Counting and reversing token lists} % % \begin{function}[added = 2012-05-13, EXP] % {\tl_count:n, \tl_count:V, \tl_count:o} @@ -752,7 +540,7 @@ % \begin{syntax} % \cs{tl_count:N} \meta{tl~var} % \end{syntax} -% Counts the number of token groups in the \meta{tl~var} +% Counts the number of \meta{items} in the \meta{tl~var} % and leaves this information in the input stream. Unbraced tokens % count as one element as do each token group (|{|\ldots|}|). This % process ignores any unprotected spaces within the \meta{tl~var}. @@ -867,36 +655,194 @@ % \emph{resets} the content of the variable. % \end{function} % -% \begin{function}[added = 2017-02-06] -% {\tl_sort:Nn, \tl_sort:cn, \tl_gsort:Nn, \tl_gsort:cn} +% \subsection{Viewing token lists} +% +% \begin{function}[updated = 2021-04-29]{\tl_show:N, \tl_show:c} % \begin{syntax} -% \cs{tl_sort:Nn} \meta{tl var} \Arg{comparison code} +% \cs{tl_show:N} \meta{tl~var} % \end{syntax} -% Sorts the items in the \meta{tl var} according to the -% \meta{comparison code}, and assigns the result to -% \meta{tl var}. The details of sorting comparison are -% described in Section~\ref{sec:l3sort:mech}. +% Displays the content of the \meta{tl~var} on the terminal. +% \begin{texnote} +% This is similar to the \TeX{} primitive \tn{show}, wrapped to a +% fixed number of characters per line. +% \end{texnote} % \end{function} % -% \begin{function}[added = 2017-02-06, EXP]{\tl_sort:nN} +% \begin{function}[updated = 2015-08-07]{\tl_show:n} % \begin{syntax} -% \cs{tl_sort:nN} \Arg{token list} \meta{conditional} +% \cs{tl_show:n} \Arg{token list} % \end{syntax} -% Sorts the items in the \meta{token list}, using the -% \meta{conditional} to compare items, and leaves the result in the -% input stream. The \meta{conditional} should have signature |:nnTF|, -% and return \texttt{true} if the two items being compared should be -% left in the same order, and \texttt{false} if the items should be -% swapped. The details of sorting comparison are -% described in Section~\ref{sec:l3sort:mech}. +% Displays the \meta{token list} on the terminal. % \begin{texnote} -% The result is returned within \cs{exp_not:n}, which means that the -% token list does not expand further when appearing in an -% \texttt{x}-type or \texttt{e}-type argument expansion. +% This is similar to the \eTeX{} primitive \tn{showtokens}, wrapped +% to a fixed number of characters per line. +% \end{texnote} +% \end{function} +% +% \begin{function}[added = 2014-08-22, updated = 2021-04-29]{\tl_log:N, \tl_log:c} +% \begin{syntax} +% \cs{tl_log:N} \meta{tl~var} +% \end{syntax} +% Writes the content of the \meta{tl~var} in the log file. See also +% \cs{tl_show:N} which displays the result in the terminal. +% \end{function} +% +% \begin{function}[added = 2014-08-22, updated = 2015-08-07]{\tl_log:n} +% \begin{syntax} +% \cs{tl_log:n} \Arg{token list} +% \end{syntax} +% Writes the \meta{token list} in the log file. See also +% \cs{tl_show:n} which displays the result in the terminal. +% \end{function} +% +% \section{Manipulating items in token lists} +% +% \subsection{Mapping over token lists} +% +% All mappings are done at the current group level, \emph{i.e.}~any +% local assignments made by the \meta{function} or \meta{code} discussed +% below remain in effect after the loop. +% +% \begin{function}[updated = 2012-06-29, rEXP] +% {\tl_map_function:NN, \tl_map_function:cN} +% \begin{syntax} +% \cs{tl_map_function:NN} \meta{tl~var} \meta{function} +% \end{syntax} +% Applies \meta{function} to every \meta{item} in the \meta{tl~var}. +% The \meta{function} receives one argument for each iteration. +% This may be a number of tokens if the \meta{item} was stored within +% braces. Hence the \meta{function} should anticipate receiving +% \texttt{n}-type arguments. See also \cs{tl_map_function:nN}. +% \end{function} +% +% \begin{function}[updated = 2012-06-29, rEXP]{\tl_map_function:nN} +% \begin{syntax} +% \cs{tl_map_function:nN} \Arg{token list} \meta{function} +% \end{syntax} +% Applies \meta{function} to every \meta{item} in the \meta{token list}, +% The \meta{function} receives one argument for each iteration. +% This may be a number of tokens if the \meta{item} was stored within +% braces. Hence the \meta{function} should anticipate receiving +% \texttt{n}-type arguments. See also \cs{tl_map_function:NN}. +% \end{function} +% +% \begin{function}[updated = 2012-06-29] +% {\tl_map_inline:Nn, \tl_map_inline:cn} +% \begin{syntax} +% \cs{tl_map_inline:Nn} \meta{tl~var} \Arg{inline function} +% \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|. See also \cs{tl_map_function:NN}. +% \end{function} +% +% \begin{function}[updated = 2012-06-29]{\tl_map_inline:nn} +% \begin{syntax} +% \cs{tl_map_inline:nn} \Arg{token list} \Arg{inline function} +% \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|. See also \cs{tl_map_function:nN}. +% \end{function} +% +% \begin{function}[rEXP, added = 2019-09-02] +% {\tl_map_tokens:Nn, \tl_map_tokens:cn, \tl_map_tokens:nn} +% \begin{syntax} +% \cs{tl_map_tokens:Nn} \meta{tl~var} \Arg{code} +% \cs{tl_map_tokens:nn} \Arg{tokens} \Arg{code} +% \end{syntax} +% Analogue of \cs{tl_map_function:NN} which maps several tokens +% instead of a single function. The \meta{code} receives each \meta{item} in +% the \meta{tl~var} or in \meta{tokens} as a trailing brace group. For +% instance, +% \begin{verbatim} +% \tl_map_tokens:Nn \l_my_tl { \prg_replicate:nn { 2 } } +% \end{verbatim} +% expands to twice each \meta{item} in the \meta{tl~var}: for each \meta{item} in +% \cs[no-index]{l_my_tl} the function \cs{prg_replicate:nn} receives |2| and +% \meta{item} as its two arguments. The function +% \cs{tl_map_inline:Nn} is typically faster but is not expandable. +% \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{code} +% \end{syntax} +% 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. Its +% value after the loop is the last \meta{item} in the \meta{tl~var}, +% or its original value if the \meta{tl~var} is blank. 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{code} +% \end{syntax} +% 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. +% Its value after the loop is the last \meta{item} in the +% \meta{tl~var}, or its original value if the \meta{tl~var} is blank. +% See also \cs{tl_map_inline:nn}. +% \end{function} +% +% \begin{function}[updated = 2012-06-29, rEXP]{\tl_map_break:} +% \begin{syntax} +% \cs{tl_map_break:} +% \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. 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: } +% % Do something useful +% } +% \end{verbatim} +% See also \cs{tl_map_break:n}. +% 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 +% before the \meta{tokens} are +% inserted into the input stream. +% This depends on the design of the mapping function. % \end{texnote} % \end{function} % -% \section{The first token from a token list} +% \begin{function}[updated = 2012-06-29, rEXP]{\tl_map_break:n} +% \begin{syntax} +% \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{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 { <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 +% before the \meta{code} is +% inserted into the input stream. +% This depends on the design of the mapping function. +% \end{texnote} +% \end{function} +% +% \subsection{Head and tail of token lists} % % Functions which deal with either only the very first item (balanced % text or single normal token) in a token list, or the remaining tokens. @@ -979,89 +925,7 @@ % \end{texnote} % \end{function} % -% \begin{function}[updated = 2012-07-09, EXP, pTF] -% {\tl_if_head_eq_catcode:nN, \tl_if_head_eq_catcode:oN} -% \begin{syntax} -% \cs{tl_if_head_eq_catcode_p:nN} \Arg{token list} \meta{test token} -% \cs{tl_if_head_eq_catcode:nNTF} \Arg{token list} \meta{test token} -% ~~\Arg{true code} \Arg{false code} -% \end{syntax} -% Tests if the first \meta{token} in the \meta{token list} has the -% same category code as the \meta{test token}. In the case where the -% \meta{token list} is empty, the test is always \texttt{false}. -% \end{function} -% -% \begin{function}[updated = 2012-07-09, EXP, pTF] -% {\tl_if_head_eq_charcode:nN, \tl_if_head_eq_charcode:fN} -% \begin{syntax} -% \cs{tl_if_head_eq_charcode_p:nN} \Arg{token list} \meta{test token} -% \cs{tl_if_head_eq_charcode:nNTF} \Arg{token list} \meta{test token} -% ~~\Arg{true code} \Arg{false code} -% \end{syntax} -% Tests if the first \meta{token} in the \meta{token list} has the -% same character code as the \meta{test token}. In the case where the -% \meta{token list} is empty, the test is always \texttt{false}. -% \end{function} -% -% \begin{function}[updated = 2012-07-09, EXP, pTF]{\tl_if_head_eq_meaning:nN} -% \begin{syntax} -% \cs{tl_if_head_eq_meaning_p:nN} \Arg{token list} \meta{test token} -% \cs{tl_if_head_eq_meaning:nNTF} \Arg{token list} \meta{test token} -% ~~\Arg{true code} \Arg{false code} -% \end{syntax} -% Tests if the first \meta{token} in the \meta{token list} has the -% same meaning as the \meta{test token}. In the case where -% \meta{token list} is empty, the test is always \texttt{false}. -% \end{function} -% -% \begin{function}[added = 2012-07-08, EXP, pTF]{\tl_if_head_is_group:n} -% \begin{syntax} -% \cs{tl_if_head_is_group_p:n} \Arg{token list} -% \cs{tl_if_head_is_group:nTF} \Arg{token list} \Arg{true code} \Arg{false code} -% \end{syntax} -% Tests if the first \meta{token} in the \meta{token list} -% is an explicit begin-group character (with category code~$1$ -% and any character code), in other words, if the \meta{token list} -% starts with a brace group. In particular, the test is \texttt{false} -% if the \meta{token list} starts with an implicit token such as -% \cs{c_group_begin_token}, or if it is empty. -% This function is useful to implement actions on token lists on -% a token by token basis. -% \end{function} -% -% \begin{function}[added = 2012-07-08, EXP, pTF]{\tl_if_head_is_N_type:n} -% \begin{syntax} -% \cs{tl_if_head_is_N_type_p:n} \Arg{token list} -% \cs{tl_if_head_is_N_type:nTF} \Arg{token list} \Arg{true code} \Arg{false code} -% \end{syntax} -% Tests if the first \meta{token} in the \meta{token list} -% is a normal \texttt{N}-type argument. In other words, -% it is neither an explicit space character -% (explicit token with character code~$32$ and category code~$10$) -% nor an explicit begin-group character -% (with category code~1 and any character code). An empty -% argument yields \texttt{false}, as it does not have a \enquote{normal} -% first token. -% This function is useful to implement actions on token lists on -% a token by token basis. -% \end{function} -% -% \begin{function}[updated = 2012-07-08, EXP, pTF]{\tl_if_head_is_space:n} -% \begin{syntax} -% \cs{tl_if_head_is_space_p:n} \Arg{token list} -% \cs{tl_if_head_is_space:nTF} \Arg{token list} \Arg{true code} \Arg{false code} -% \end{syntax} -% Tests if the first \meta{token} in the \meta{token list} -% is an explicit space character -% (explicit token with character code~$12$ and category code~$10$). -% In particular, the test is \texttt{false} if the \meta{token list} -% starts with an implicit token such as \cs{c_space_token}, or if it -% is empty. -% This function is useful to implement actions on token lists on -% a token by token basis. -% \end{function} -% -% \section{Using a single item} +% \subsection{Items and ranges in token lists} % % \begin{function}[added = 2014-07-17, EXP] % {\tl_item:nn, \tl_item:Nn, \tl_item:cn} @@ -1172,44 +1036,190 @@ % \end{texnote} % \end{function} % -% \section{Viewing token lists} +% \subsection{Sorting token lists} % -% \begin{function}[updated = 2021-04-29]{\tl_show:N, \tl_show:c} +% \begin{function}[added = 2017-02-06] +% {\tl_sort:Nn, \tl_sort:cn, \tl_gsort:Nn, \tl_gsort:cn} % \begin{syntax} -% \cs{tl_show:N} \meta{tl~var} +% \cs{tl_sort:Nn} \meta{tl var} \Arg{comparison code} % \end{syntax} -% Displays the content of the \meta{tl~var} on the terminal. -% \begin{texnote} -% This is similar to the \TeX{} primitive \tn{show}, wrapped to a -% fixed number of characters per line. -% \end{texnote} +% Sorts the items in the \meta{tl var} according to the +% \meta{comparison code}, and assigns the result to +% \meta{tl var}. The details of sorting comparison are +% described in Section~\ref{sec:l3sort:mech}. % \end{function} % -% \begin{function}[updated = 2015-08-07]{\tl_show:n} +% \begin{function}[added = 2017-02-06, EXP]{\tl_sort:nN} % \begin{syntax} -% \cs{tl_show:n} \Arg{token list} +% \cs{tl_sort:nN} \Arg{token list} \meta{conditional} % \end{syntax} -% Displays the \meta{token list} on the terminal. +% Sorts the items in the \meta{token list}, using the +% \meta{conditional} to compare items, and leaves the result in the +% input stream. The \meta{conditional} should have signature |:nnTF|, +% and return \texttt{true} if the two items being compared should be +% left in the same order, and \texttt{false} if the items should be +% swapped. The details of sorting comparison are +% described in Section~\ref{sec:l3sort:mech}. % \begin{texnote} -% This is similar to the \eTeX{} primitive \tn{showtokens}, wrapped -% to a fixed number of characters per line. +% The result is returned within \cs{exp_not:n}, which means that the +% token list does not expand further when appearing in an +% \texttt{x}-type or \texttt{e}-type argument expansion. % \end{texnote} % \end{function} % -% \begin{function}[added = 2014-08-22, updated = 2021-04-29]{\tl_log:N, \tl_log:c} +% \section{Manipulating tokens in token lists} +% +% \subsection{Replacing tokens} +% +% \begin{function}[updated = 2011-08-11] +% { +% \tl_replace_once:Nnn, \tl_replace_once:cnn, +% \tl_greplace_once:Nnn, \tl_greplace_once:cnn +% } % \begin{syntax} -% \cs{tl_log:N} \meta{tl~var} +% \cs{tl_replace_once:Nnn} \meta{tl~var} \Arg{old tokens} \Arg{new tokens} % \end{syntax} -% Writes the content of the \meta{tl~var} in the log file. See also -% \cs{tl_show:N} which displays the result in the terminal. +% Replaces the first (leftmost) occurrence of \meta{old tokens} in the +% \meta{tl~var} with \meta{new tokens}. \meta{Old tokens} +% cannot contain |{|, |}| or |#| +% (more precisely, explicit character tokens with category code $1$ +% (begin-group) or $2$ (end-group), and tokens with category code $6$). % \end{function} % -% \begin{function}[added = 2014-08-22, updated = 2015-08-07]{\tl_log:n} +% \begin{function}[updated = 2011-08-11] +% { +% \tl_replace_all:Nnn, \tl_replace_all:cnn, +% \tl_greplace_all:Nnn, \tl_greplace_all:cnn +% } % \begin{syntax} -% \cs{tl_log:n} \Arg{token list} +% \cs{tl_replace_all:Nnn} \meta{tl~var} \Arg{old tokens} \Arg{new tokens} % \end{syntax} -% Writes the \meta{token list} in the log file. See also -% \cs{tl_show:n} which displays the result in the terminal. +% Replaces all occurrences of \meta{old tokens} in the +% \meta{tl~var} with \meta{new tokens}. \meta{Old tokens} +% cannot contain |{|, |}| or |#| +% (more precisely, explicit character tokens with category code $1$ +% (begin-group) or $2$ (end-group), and tokens with category code $6$). +% 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). +% \end{function} +% +% \begin{function}[updated = 2011-08-11] +% { +% \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 |#| +% (more precisely, explicit character tokens with category code $1$ +% (begin-group) or $2$ (end-group), and tokens with category code $6$). +% \end{function} +% +% \begin{function}[updated = 2011-08-11] +% { +% \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} +% Removes all occurrences of \meta{tokens} from the +% \meta{tl~var}. \meta{Tokens} cannot contain |{|, |}| or |#| +% (more precisely, explicit character tokens with category code $1$ +% (begin-group) or $2$ (end-group), and tokens with category code $6$). +% As this function +% operates from left to right, the pattern \meta{tokens} +% may remain after the removal, for instance, +% \begin{quote} +% \cs{tl_set:Nn} \cs{l_tmpa_tl} |{abbccd}| +% \cs{tl_remove_all:Nn} \cs{l_tmpa_tl} |{bc}| +% \end{quote} +% results in \cs{l_tmpa_tl} containing \texttt{abcd}. +% \end{function} +% +% \subsection{Reassigning category codes} +% +% These functions allow the rescanning of tokens: re-apply \TeX{}'s +% tokenization process to apply category codes different from those +% in force when the tokens were absorbed. Whilst this functionality is +% supported, it is often preferable to find alternative approaches +% to achieving outcomes rather than rescanning tokens (for example +% construction of token lists token-by-token with intervening category +% code changes or using \cs{char_generate:nn}). +% +% \begin{function}[updated = 2015-08-11] +% { +% \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\'{e}gime specified in the \meta{setup} before carrying out +% the assignment. (Category codes applied to tokens not explicitly covered +% by the \meta{setup} are those in force at the point of use of +% \cs{tl_set_rescan:Nnn}.) +% This allows the \meta{tl~var} to contain material +% with category codes other than those that apply when \meta{tokens} +% are absorbed. The \meta{setup} is run within a group and may +% contain any valid input, although only changes in category codes, +% such as uses of \cs{cctab_select:N}, +% are relevant. See also \cs{tl_rescan:nn}. +% \begin{texnote} +% The \meta{tokens} are first turned into a string (using +% \cs{tl_to_str:n}). If the string contains one or more characters +% with character code \tn{newlinechar} (set equal to +% \tn{endlinechar} unless that is equal to $32$, before the user +% \meta{setup}), then it is split into lines at these characters, +% then read as if reading multiple lines from a file, ignoring +% spaces (catcode $10$) at the beginning and spaces and tabs +% (character code $32$ or $9$) at the end of every line. +% Otherwise, spaces (and tabs) are retained at both ends of the +% single-line string, as if it appeared in the middle of a line +% read from a file. +% \end{texnote} +% \end{function} +% +% \begin{function}[updated = 2015-08-11]{\tl_rescan:nn} +% \begin{syntax} +% \cs{tl_rescan:nn} \Arg{setup} \Arg{tokens} +% \end{syntax} +% Rescans \meta{tokens} applying the category code r\'{e}gime +% specified in the \meta{setup}, and leaves the resulting tokens in +% the input stream. (Category codes applied to tokens not explicitly covered +% by the \meta{setup} are those in force at the point of use of +% \cs{tl_rescan:nn}.) +% The \meta{setup} is run within a group and may +% contain any valid input, although only changes in category codes, +% such as uses of \cs{cctab_select:N}, +% are relevant. See also \cs{tl_set_rescan:Nnn}, which is more +% robust than using \cs{tl_set:Nn} in the \meta{tokens} argument of +% \cs{tl_rescan:nn}. +% \begin{texnote} +% The \meta{tokens} are first turned into a string (using +% \cs{tl_to_str:n}). If the string contains one or more characters +% with character code \tn{newlinechar} (set equal to +% \tn{endlinechar} unless that is equal to $32$, before the user +% \meta{setup}), then it is split into lines at these characters, +% then read as if reading multiple lines from a file, ignoring +% spaces (catcode $10$) at the beginning and spaces and tabs +% (character code $32$ or $9$) at the end of every line. +% Otherwise, spaces (and tabs) are retained at both ends of the +% single-line string, as if it appeared in the middle of a line +% read from a file. +% +% Contrarily to the \tn{scantokens} primitive, \cs{tl_rescan:nn} +% tokenizes the whole string in the same category code regime rather +% than one token at a time, so that directives such as \tn{verb} +% that rely on changing category codes will not function properly. +% \end{texnote} % \end{function} % % \section{Constant token lists} @@ -1442,7 +1452,7 @@ % By using \cs{exp_not:n} token list variables can contain |#| tokens, % which makes the token list registers provided by \TeX{} % more or less redundant. The \cs{tl_set:No} version is done -% \enquote{by hand} as it is used quite a lot. +% by hand as it is used quite a lot. % \begin{macrocode} \cs_new_protected:Npn \tl_set:Nn #1#2 { \__kernel_tl_set:Nx #1 { \__kernel_exp_not:w {#2} } } @@ -2289,7 +2299,7 @@ % The \cs{if_false:} constructions are a faster way to do % \cs{group_align_safe_begin:} and \cs{group_align_safe_end:}. % The \cs{scan_stop:} ensures that \texttt{f}-expanding -% \cs{tl_if_in:nn} does not lead to unbalanced braces. +% \cs{tl_if_in:nnTF} does not lead to unbalanced braces. % \begin{macrocode} \prg_new_protected_conditional:Npnn \tl_if_in:nn #1#2 { T , F , TF } { @@ -2335,7 +2345,7 @@ % \end{macro} % % \begin{macro}[EXP,pTF]{\tl_if_single:N} -% Expand the token list and feed it to \cs{tl_if_single:n}. +% Expand the token list and feed it to \cs{tl_if_single:nTF}. % \begin{macrocode} \cs_new:Npn \tl_if_single_p:N { \exp_args:No \tl_if_single_p:n } \cs_new:Npn \tl_if_single:NT { \exp_args:No \tl_if_single:nT } |