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