summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-12-06 23:56:06 +0000
committerKarl Berry <karl@freefriends.org>2017-12-06 23:56:06 +0000
commitcc862e582aa0dd7c0dee16bb5475394338a07641 (patch)
treeb03dbc5b6657d47f5c61b8fcc26f04a564ad6afd /Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
parent7ffad570b11726b0ca150867d23878fc1a949865 (diff)
l3 (7dec17)
git-svn-id: svn://tug.org/texlive/trunk@46003 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3seq.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3seq.dtx151
1 files changed, 73 insertions, 78 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx b/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
index 694f7d4c2ee..75f1273c32e 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3seq.dtx
@@ -7,7 +7,7 @@
% license or (at your option) any later version. The latest version
% of this license is in the file
%
-% http://www.latex-project.org/lppl.txt
+% https://www.latex-project.org/lppl.txt
%
% This file is part of the "l3kernel bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
@@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver>
-\documentclass[full]{l3doc}
+\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
@@ -41,7 +41,7 @@
% }^^A
% }
%
-% \date{Released 2017/11/14}
+% \date{Released 2017/12/05}
%
% \maketitle
%
@@ -303,10 +303,10 @@
% If the \meta{sequence} is empty, leaves the \meta{false code} in the
% input stream. The value of the \meta{token list variable} is
% not defined in this case and should not be relied upon. If the
-% \meta{sequence} is non-empty, stores the left-most item from a
+% \meta{sequence} is non-empty, stores the left-most item from the
% \meta{sequence}
-% in the \meta{token list variable} without removing it from a
-% \meta{sequence}.
+% in the \meta{token list variable} without removing it from the
+% \meta{sequence}, then leaves the \meta{true code} in the input stream.
% The \meta{token list variable} is assigned locally.
% \end{function}
%
@@ -318,10 +318,10 @@
% If the \meta{sequence} is empty, leaves the \meta{false code} in the
% input stream. The value of the \meta{token list variable} is
% not defined in this case and should not be relied upon. If the
-% \meta{sequence} is non-empty, stores the right-most item from a
+% \meta{sequence} is non-empty, stores the right-most item from the
% \meta{sequence}
-% in the \meta{token list variable} without removing it from a
-% \meta{sequence}.
+% in the \meta{token list variable} without removing it from the
+% \meta{sequence}, then leaves the \meta{true code} in the input stream.
% The \meta{token list variable} is assigned locally.
% \end{function}
%
@@ -333,10 +333,10 @@
% If the \meta{sequence} is empty, leaves the \meta{false code} in the
% input stream. The value of the \meta{token list variable} is
% not defined in this case and should not be relied upon. If the
-% \meta{sequence} is non-empty, pops the left-most item from a
+% \meta{sequence} is non-empty, pops the left-most item from the
% \meta{sequence}
-% in the \meta{token list variable}, \emph{i.e.}~removes the item from a
-% \meta{sequence}.
+% in the \meta{token list variable}, \emph{i.e.}~removes the item from the
+% \meta{sequence}, then leaves the \meta{true code} in the input stream.
% Both the \meta{sequence} and the \meta{token list variable} are assigned
% locally.
% \end{function}
@@ -349,9 +349,9 @@
% If the \meta{sequence} is empty, leaves the \meta{false code} in the
% input stream. The value of the \meta{token list variable} is
% not defined in this case and should not be relied upon. If the
-% \meta{sequence} is non-empty, pops the left-most item from a \meta{sequence}
-% in the \meta{token list variable}, \emph{i.e.}~removes the item from a
-% \meta{sequence}.
+% \meta{sequence} is non-empty, pops the left-most item from the \meta{sequence}
+% in the \meta{token list variable}, \emph{i.e.}~removes the item from the
+% \meta{sequence}, then leaves the \meta{true code} in the input stream.
% The \meta{sequence} is modified globally, while the \meta{token list variable}
% is assigned locally.
% \end{function}
@@ -364,9 +364,9 @@
% If the \meta{sequence} is empty, leaves the \meta{false code} in the
% input stream. The value of the \meta{token list variable} is
% not defined in this case and should not be relied upon. If the
-% \meta{sequence} is non-empty, pops the right-most item from a \meta{sequence}
-% in the \meta{token list variable}, \emph{i.e.}~removes the item from a
-% \meta{sequence}.
+% \meta{sequence} is non-empty, pops the right-most item from the \meta{sequence}
+% in the \meta{token list variable}, \emph{i.e.}~removes the item from the
+% \meta{sequence}, then leaves the \meta{true code} in the input stream.
% Both the \meta{sequence} and the \meta{token list variable} are assigned
% locally.
% \end{function}
@@ -379,9 +379,10 @@
% If the \meta{sequence} is empty, leaves the \meta{false code} in the
% input stream. The value of the \meta{token list variable} is
% not defined in this case and should not be relied upon. If the
-% \meta{sequence} is non-empty, pops the right-most item from a \meta{sequence}
-% in the \meta{token list variable}, \emph{i.e.}~removes the item from a
-% \meta{sequence}. The \meta{sequence} is modified globally, while the
+% \meta{sequence} is non-empty, pops the right-most item from the \meta{sequence}
+% in the \meta{token list variable}, \emph{i.e.}~removes the item from the
+% \meta{sequence}, then leaves the \meta{true code} in the input stream.
+% The \meta{sequence} is modified globally, while the
% \meta{token list variable} is assigned locally.
% \end{function}
%
@@ -479,7 +480,6 @@
% The function \cs{seq_map_inline:Nn} is faster than
% \cs{seq_map_function:NN} for sequences with more than about~$10$
% items.
-% One mapping may be nested inside another.
% \end{function}
%
% \begin{function}[updated = 2012-06-29]
@@ -490,8 +490,7 @@
% Applies \meta{inline function} to every \meta{item} stored
% within the \meta{sequence}. The \meta{inline function} should
% consist of code which will receive the \meta{item} as |#1|.
-% One in line mapping can be nested inside another. The \meta{items}
-% are returned from left to right.
+% The \meta{items} are returned from left to right.
% \end{function}
%
% \begin{function}[updated = 2012-06-29]
@@ -500,15 +499,13 @@
% \seq_map_variable:cNn, \seq_map_variable:ccn
% }
% \begin{syntax}
-% \cs{seq_map_variable:NNn} \meta{sequence} \meta{tl~var.} \Arg{function using tl~var.}
+% \cs{seq_map_variable:NNn} \meta{sequence} \meta{variable} \Arg{code}
% \end{syntax}
-% Stores each entry in the \meta{sequence} in turn in the
-% \meta{tl~var.}\ and applies the \meta{function using tl~var.}
-% The \meta{function} will usually consist of code making use of
-% the \meta{tl~var.}, but this is not enforced. The assignments to
-% \meta{tl~var.} are local, and one variable
-% mapping can be nested inside another. The \meta{items}
-% are returned from left to right.
+% Stores each \meta{item} of the \meta{sequence} 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. The
+% \meta{items} are returned from left to right.
% \end{function}
%
% \begin{function}[rEXP, updated = 2012-06-29]{\seq_map_break:}
@@ -531,8 +528,8 @@
% Use outside of a \cs[no-index]{seq_map_\ldots} scenario leads to low
% level \TeX{} errors.
% \begin{texnote}
-% When the mapping is broken, additional tokens may be inserted by the
-% internal macro \cs{__prg_break_point:Nn} before further items are taken
+% When the mapping is broken, additional tokens may be inserted
+% before further items are taken
% from the input stream. This depends on the design of the mapping
% function.
% \end{texnote}
@@ -540,17 +537,17 @@
%
% \begin{function}[rEXP, updated = 2012-06-29]{\seq_map_break:n}
% \begin{syntax}
-% \cs{seq_map_break:n} \Arg{tokens}
+% \cs{seq_map_break:n} \Arg{code}
% \end{syntax}
% Used to terminate a \cs[no-index]{seq_map_\ldots} function before all
% entries in the \meta{sequence} have been processed, inserting
-% the \meta{tokens} after the mapping has ended. This
+% the \meta{code} after the mapping has ended. This
% normally takes place within a conditional statement, for example
% \begin{verbatim}
% \seq_map_inline:Nn \l_my_seq
% {
% \str_if_eq:nnTF { #1 } { bingo }
-% { \seq_map_break:n { <tokens> } }
+% { \seq_map_break:n { <code> } }
% {
% % Do something useful
% }
@@ -559,8 +556,8 @@
% Use outside of a \cs[no-index]{seq_map_\ldots} scenario leads to low
% level \TeX{} errors.
% \begin{texnote}
-% When the mapping is broken, additional tokens may be inserted by the
-% internal macro \cs{__prg_break_point:Nn} before the \meta{tokens} are
+% 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}
@@ -922,7 +919,7 @@
% The variable is defined in the \pkg{l3quark} module, loaded later.
% \end{variable}
%
-% \begin{macro}[int]{\@@_item:n}
+% \begin{macro}{\@@_item:n}
% The delimiter is always defined, but when used incorrectly simply
% removes its argument and hits an undefined control sequence to
% raise an error.
@@ -943,7 +940,7 @@
% \end{macrocode}
% \end{variable}
%
-% \begin{macro}[aux]{\@@_tmp:w}
+% \begin{macro}{\@@_tmp:w}
% Scratch function for internal use.
% \begin{macrocode}
\cs_new_eq:NN \@@_tmp:w ?
@@ -1073,8 +1070,8 @@
% \seq_set_split:Nnn , \seq_set_split:NnV ,
% \seq_gset_split:Nnn, \seq_gset_split:NnV
% }
-% \begin{macro}[aux]{\@@_set_split:NNnn}
-% \begin{macro}[aux]
+% \begin{macro}{\@@_set_split:NNnn}
+% \begin{macro}
% {
% \@@_set_split_auxi:w, \@@_set_split_auxii:w,
% \@@_set_split_end:
@@ -1185,7 +1182,7 @@
% \seq_gput_left:cn, \seq_gput_left:cV, \seq_gput_left:cv,
% \seq_gput_left:co, \seq_gput_left:cx
% }
-% \begin{macro}[aux,EXP]{\@@_put_left_aux:w}
+% \begin{macro}[EXP]{\@@_put_left_aux:w}
% When adding to the left of a sequence, remove \cs{s_@@}. This is
% done by \cs{@@_put_left_aux:w}, which also stops
% \texttt{f}-expansion.
@@ -1248,7 +1245,7 @@
%
% \subsection{Modifying sequences}
%
-% \begin{macro}[aux]{\@@_wrap_item:n}
+% \begin{macro}{\@@_wrap_item:n}
% This function converts its argument to a proper sequence item
% in an \texttt{x}-expansion context.
% \begin{macrocode}
@@ -1267,7 +1264,7 @@
% \UnitTested
% \begin{macro}{\seq_gremove_duplicates:N, \seq_gremove_duplicates:c}
% \UnitTested
-% \begin{macro}[aux]{\@@_remove_duplicates:NN}
+% \begin{macro}{\@@_remove_duplicates:NN}
% Removing duplicates means making a new list then copying it.
% \begin{macrocode}
\cs_new_protected:Npn \seq_remove_duplicates:N
@@ -1295,7 +1292,7 @@
% \UnitTested
% \begin{macro}{\seq_gremove_all:Nn, \seq_gremove_all:cn}
% \UnitTested
-% \begin{macro}[aux]{\@@_remove_all_aux:NNn}
+% \begin{macro}{\@@_remove_all_aux:NNn}
% The idea of the code here is to avoid a relatively expensive addition of
% items one at a time to an intermediate sequence.
% The approach taken is therefore similar to
@@ -1343,8 +1340,8 @@
%
% \begin{macro}
% {\seq_reverse:N, \seq_reverse:c, \seq_greverse:N, \seq_greverse:c}
-% \begin{macro}[aux]{\@@_reverse:NN}
-% \begin{macro}[aux, EXP]{\@@_reverse_item:nwn}
+% \begin{macro}{\@@_reverse:NN}
+% \begin{macro}[EXP]{\@@_reverse_item:nwn}
% Previously, \cs{seq_reverse:N} was coded by collecting the items
% in reverse order after an \cs{exp_stop_f:} marker.
% \begin{verbatim}
@@ -1431,7 +1428,7 @@
% \seq_if_in:cn, \seq_if_in:cV, \seq_if_in:cv, \seq_if_in:co, \seq_if_in:cx
% }
% \UnitTested
-% \begin{macro}[aux]{\@@_if_in:}
+% \begin{macro}{\@@_if_in:}
% The approach here is to define \cs{@@_item:n} to compare its
% argument with the test sequence. If the two items are equal, the
% mapping is terminated and \cs{group_end:} \cs{prg_return_true:}
@@ -1472,7 +1469,7 @@
%
% \subsection{Recovering data from sequences}
%
-% \begin{macro}[int]{\@@_pop:NNNN, \@@_pop_TF:NNNN}
+% \begin{macro}{\@@_pop:NNNN, \@@_pop_TF:NNNN}
% The two \texttt{pop} functions share their emptiness tests. We also
% use a common emptiness test for all branching \texttt{get} and
% \texttt{pop} functions.
@@ -1500,7 +1497,7 @@
%
% \begin{macro}{\seq_get_left:NN, \seq_get_left:cN}
% \UnitTested
-% \begin{macro}[aux]{\@@_get_left:wnw}
+% \begin{macro}{\@@_get_left:wnw}
% Getting an item from the left of a sequence is pretty easy: just
% trim off the first item after \cs{@@_item:n} at the start. We
% append a \cs{q_no_value} item to cover the case of an empty sequence
@@ -1524,7 +1521,7 @@
% \UnitTested
% \begin{macro}{\seq_gpop_left:NN, \seq_gpop_left:cN}
% \UnitTested
-% \begin{macro}[aux]{\@@_pop_left:NNN, \@@_pop_left:wnwNNN}
+% \begin{macro}{\@@_pop_left:NNN, \@@_pop_left:wnwNNN}
% The approach to popping an item is pretty similar to that to get
% an item, with the only difference being that the sequence itself has
% to be redefined. This makes it more sensible to use an auxiliary
@@ -1551,7 +1548,7 @@
%
% \begin{macro}{\seq_get_right:NN, \seq_get_right:cN}
% \UnitTested
-% \begin{macro}[aux]{\@@_get_right_loop:nn}
+% \begin{macro}{\@@_get_right_loop:nn}
% First remove \cs{s_@@} and prepend \cs{q_no_value}, then take two
% arguments at a time. Before the right-hand end of the sequence,
% this is a brace group followed by \cs{@@_item:n}, both removed by
@@ -1584,7 +1581,7 @@
% \UnitTested
% \begin{macro}{\seq_gpop_right:NN, \seq_gpop_right:cN}
% \UnitTested
-% \begin{macro}[aux]{\@@_pop_right:NNN, \@@_pop_right_loop:nn}
+% \begin{macro}{\@@_pop_right:NNN, \@@_pop_right_loop:nn}
% The approach to popping from the right is a bit more involved, but does
% use some of the same ideas as getting from the right. What is needed is a
% \enquote{flexible length} way to set a token list variable. This is
@@ -1684,7 +1681,7 @@
% \end{macro}
%
% \begin{macro}{\seq_item:Nn, \seq_item:cn}
-% \begin{macro}[aux]{\@@_item:wNn, \@@_item:nN, \@@_item:nnn}
+% \begin{macro}{\@@_item:wNn, \@@_item:nN, \@@_item:nnn}
% 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 the stop code |{ ? \__prg_break: } { }| is used by the auxiliary,
@@ -1738,7 +1735,7 @@
%
% \begin{macro}{\seq_map_function:NN, \seq_map_function:cN}
% \UnitTested
-% \begin{macro}[aux,rEXP]{\@@_map_function:NNn}
+% \begin{macro}[rEXP]{\@@_map_function:NNn}
% The idea here is to apply the code of |#2| to each item in the
% sequence without altering the definition of \cs{@@_item:n}. This
% is done as by noting that every odd token in the sequence must be
@@ -1766,9 +1763,9 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[int]{\@@_push_item_def:n, \@@_push_item_def:x}
-% \begin{macro}[aux]{\@@_push_item_def:}
-% \begin{macro}[int]{\@@_pop_item_def:}
+% \begin{macro}{\@@_push_item_def:n, \@@_push_item_def:x}
+% \begin{macro}{\@@_push_item_def:}
+% \begin{macro}{\@@_pop_item_def:}
% The definition of \cs{@@_item:n} needs to be saved and restored at
% various points within the mapping and manipulation code. That is handled
% here: as always, this approach uses global assignments.
@@ -1842,7 +1839,7 @@
% \end{macro}
%
% \begin{macro}{\seq_count:N, \seq_count:c}
-% \begin{macro}[aux]{\@@_count:n}
+% \begin{macro}{\@@_count:n}
% Counting the items in a sequence is done using the same approach as for
% other count functions: turn each entry into a \texttt{+1} then use
% integer evaluation to actually do the mathematics.
@@ -1864,7 +1861,7 @@
% \subsection{Using sequences}
%
% \begin{macro}[EXP]{\seq_use:Nnnn, \seq_use:cnnn}
-% \begin{macro}[EXP, aux]
+% \begin{macro}[EXP]
% {\@@_use:NNnNnn, \@@_use_setup:w, \@@_use:nwwwwnwn, \@@_use:nwwn}
% \begin{macro}[EXP]{\seq_use:Nn, \seq_use:cn}
% See \cs{clist_use:Nnnn} for a general explanation. The main
@@ -1992,26 +1989,24 @@
%
% \subsection{Viewing sequences}
%
-% \begin{macro}{\seq_show:N, \seq_show:c}
+% \begin{macro}{\seq_show:N, \seq_show:c, \seq_log:N, \seq_log:c, \@@_show:NN}
% \UnitTested
-% Apply the general \cs{__msg_show_variable:NNNnn}.
+% Apply the general \cs{msg_show:nnnnnn}.
% \begin{macrocode}
-\cs_new_protected:Npn \seq_show:N #1
- {
- \__msg_show_variable:NNNnn #1
- \seq_if_exist:NTF \seq_if_empty:NTF { seq }
- { \seq_map_function:NN #1 \__msg_show_item:n }
- }
+\cs_new_protected:Npn \seq_show:N { \@@_show:NN \msg_show:nnxxxx }
\cs_generate_variant:Nn \seq_show:N { c }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\seq_log:N, \seq_log:c}
-% Redirect output of \cs{seq_show:N} to the log.
-% \begin{macrocode}
-\cs_new_protected:Npn \seq_log:N
- { \__msg_log_next: \seq_show:N }
+\cs_new_protected:Npn \seq_log:N { \@@_show:NN \msg_log:nnxxxx }
\cs_generate_variant:Nn \seq_log:N { c }
+\cs_new_protected:Npn \@@_show:NN #1#2
+ {
+ \__kernel_check_defined:NT #2
+ {
+ #1 { LaTeX/kernel } { show-seq }
+ { \token_to_str:N #2 }
+ { \seq_map_function:NN #2 \msg_show_item:n }
+ { } { }
+ }
+ }
% \end{macrocode}
% \end{macro}
%