summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3clist.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3clist.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3clist.dtx153
1 files changed, 74 insertions, 79 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3clist.dtx b/Master/texmf-dist/source/latex/l3kernel/l3clist.dtx
index ed70ce187a6..d7a063b7aae 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3clist.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3clist.dtx
@@ -9,7 +9,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.
@@ -23,7 +23,7 @@
% for those people who are interested.
%
%<*driver>
-\documentclass[full]{l3doc}
+\documentclass[full,kernel]{l3doc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
@@ -43,7 +43,7 @@
% }^^A
% }
%
-% \date{Released 2017/11/14}
+% \date{Released 2017/12/05}
%
% \maketitle
%
@@ -384,7 +384,6 @@
% each iteration. The \meta{items} are returned from left to right.
% The function \cs{clist_map_inline:Nn} is in general more efficient
% than \cs{clist_map_function:NN}.
-% One mapping may be nested inside another.
% \end{function}
%
% \begin{function}[updated = 2012-06-29]
@@ -395,21 +394,19 @@
% Applies \meta{inline function} to every \meta{item} stored
% within the \meta{comma list}. The \meta{inline function} should
% consist of code which receives 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]
% {\clist_map_variable:NNn, \clist_map_variable:cNn, \clist_map_variable:nNn}
% \begin{syntax}
-% \cs{clist_map_variable:NNn} \meta{comma list} \meta{tl~var.} \Arg{function using tl~var.}
+% \cs{clist_map_variable:NNn} \meta{comma list} \meta{variable} \Arg{code}
% \end{syntax}
-% Stores each entry in the \meta{comma list} in turn in the
-% \meta{tl~var.}\ and applies the \meta{function using tl~var.}
-% The \meta{function} usually consists of code making use of
-% the \meta{tl~var.}, but this is not enforced. One variable
-% mapping can be nested inside another. The \meta{items}
-% are returned from left to right.
+% Stores each \meta{item} of the \meta{comma 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.
+% The \meta{items} are returned from left to right.
% \end{function}
%
% \begin{function}[rEXP, updated = 2012-06-29]{\clist_map_break:}
@@ -432,8 +429,8 @@
% Use outside of a |\clist_map_...| 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}
@@ -441,17 +438,17 @@
%
% \begin{function}[updated = 2012-06-29, rEXP]{\clist_map_break:n}
% \begin{syntax}
-% \cs{clist_map_break:n} \Arg{tokens}
+% \cs{clist_map_break:n} \Arg{code}
% \end{syntax}
% Used to terminate a |\clist_map_...| function before all
% entries in the \meta{comma list} 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}
% \clist_map_inline:Nn \l_my_clist
% {
% \str_if_eq:nnTF { #1 } { bingo }
-% { \clist_map_break:n { <tokens> } }
+% { \clist_map_break:n { <code> } }
% {
% % Do something useful
% }
@@ -460,8 +457,8 @@
% Use outside of a |\clist_map_...| 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}
@@ -736,7 +733,7 @@
% \end{macrocode}
% \end{variable}
%
-% \begin{macro}[aux]{\@@_tmp:w}
+% \begin{macro}{\@@_tmp:w}
% A temporary function for various purposes.
% \begin{macrocode}
\cs_new_protected:Npn \@@_tmp:w { }
@@ -832,9 +829,9 @@
% \clist_gset_from_seq:Nc, \clist_gset_from_seq:cc
% }
% \UnitTested
-% \begin{macro}[aux]{\@@_set_from_seq:NNNN}
-% \begin{macro}[aux]{\@@_wrap_item:n}
-% \begin{macro}[aux]{\@@_set_from_seq:w}
+% \begin{macro}{\@@_set_from_seq:NNNN}
+% \begin{macro}{\@@_wrap_item:n}
+% \begin{macro}{\@@_set_from_seq:w}
% Setting a comma list from a comma-separated list is done using a simple
% mapping. We wrap most items with \cs{exp_not:n}, and a comma. Items which
% contain a comma or a space are surrounded by an extra set of braces. The
@@ -879,7 +876,7 @@
% \UnitTested
% \begin{macro}{\clist_gconcat:NNN, \clist_gconcat:ccc}
% \UnitTested
-% \begin{macro}[aux]{\@@_concat:NNNN}
+% \begin{macro}{\@@_concat:NNNN}
% Concatenating comma lists is not quite as easy as it seems, as
% there needs to be the correct addition of a comma to the output. So
% a little work to do.
@@ -916,8 +913,8 @@
%
% \subsection{Removing spaces around items}
%
-% \begin{macro}[int,EXP]{\@@_trim_spaces_generic:nw}
-% \begin{macro}[aux]{\@@_trim_spaces_generic:nn}
+% \begin{macro}[EXP]{\@@_trim_spaces_generic:nw}
+% \begin{macro}{\@@_trim_spaces_generic:nn}
% \begin{syntax}
% \cs{@@_trim_spaces_generic:nw} \Arg{code} \cs{q_mark} \meta{item} |,|
% \end{syntax}
@@ -941,8 +938,8 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[int,rEXP]{\@@_trim_spaces:n}
-% \begin{macro}[aux]{\@@_trim_spaces:nn}
+% \begin{macro}[rEXP]{\@@_trim_spaces:n}
+% \begin{macro}{\@@_trim_spaces:nn}
% The first argument of \cs{@@_trim_spaces:nn} is initially empty,
% and later a comma, namely, as soon as we have added an item to the
% resulting list. The auxiliary tests for the end of the list,
@@ -1017,7 +1014,7 @@
% \clist_gput_left:co, \clist_gput_left:cx
% }
% \UnitTested
-% \begin{macro}[aux]{\@@_put_left:NNNn}
+% \begin{macro}{\@@_put_left:NNNn}
% Comma lists cannot hold empty values: there are therefore a couple
% of sanity checks to avoid accumulating commas.
% \begin{macrocode}
@@ -1055,7 +1052,7 @@
% \clist_gput_right:co, \clist_gput_right:cx
% }
% \UnitTested
-% \begin{macro}[aux]{\@@_put_right:NNNn}
+% \begin{macro}{\@@_put_right:NNNn}
% \begin{macrocode}
\cs_new_protected:Npn \clist_put_right:Nn
{ \@@_put_right:NNNn \clist_concat:NNN \clist_set:Nn }
@@ -1079,7 +1076,7 @@
%
% \begin{macro}{\clist_get:NN, \clist_get:cN}
% \UnitTested
-% \begin{macro}[aux]{\@@_get:wN}
+% \begin{macro}{\@@_get:wN}
% Getting an item from the left of a comma list is pretty easy: just
% trim off the first item using the comma.
% \begin{macrocode}
@@ -1102,7 +1099,7 @@
% \UnitTested
% \begin{macro}{\clist_gpop:NN, \clist_gpop:cN}
% \UnitTested
-% \begin{macro}[aux]
+% \begin{macro}
% {\@@_pop:NNN, \@@_pop:wwNNN, \@@_pop:wN}
% An empty clist leads to \cs{q_no_value}, otherwise grab until the
% first comma and assign to the variable. The second argument of
@@ -1146,7 +1143,7 @@
% \begin{macro}[TF]{\clist_get:NN, \clist_get:cN}
% \begin{macro}[TF]{\clist_pop:NN, \clist_pop:cN}
% \begin{macro}[TF]{\clist_gpop:NN, \clist_gpop:cN}
-% \begin{macro}[aux]{\@@_pop_TF:NNN}
+% \begin{macro}{\@@_pop_TF:NNN}
% The same, as branching code: very similar to the above.
% \begin{macrocode}
\prg_new_protected_conditional:Npnn \clist_get:NN #1#2 { T , F , TF }
@@ -1231,7 +1228,7 @@
% \UnitTested
% \begin{macro}{\clist_gremove_duplicates:N, \clist_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 \clist_remove_duplicates:N
@@ -1259,9 +1256,9 @@
% \UnitTested
% \begin{macro}{\clist_gremove_all:Nn, \clist_gremove_all:cn}
% \UnitTested
-% \begin{macro}[aux]{\@@_remove_all:NNn}
-% \begin{macro}[aux]{\@@_remove_all:w}
-% \begin{macro}[aux]{\@@_remove_all:}
+% \begin{macro}{\@@_remove_all:NNn}
+% \begin{macro}{\@@_remove_all:w}
+% \begin{macro}{\@@_remove_all:}
% The method used here is very similar to \cs{tl_replace_all:Nnn}.
% Build a function delimited by the \meta{item} that should be removed,
% surrounded with commas, and call that function followed by
@@ -1342,7 +1339,7 @@
% \end{macro}
%
% \begin{macro}[EXP]{\clist_reverse:n}
-% \begin{macro}[aux, EXP]{\@@_reverse:wwNww, \@@_reverse_end:ww}
+% \begin{macro}[EXP]{\@@_reverse:wwNww, \@@_reverse_end:ww}
% The reversed token list is built one item at a time, and stored
% between \cs{q_stop} and \cs{q_mark}, in the form of |?| followed by
% zero or more instances of \enquote{\meta{item}\texttt{,}}. We start from a comma
@@ -1396,8 +1393,8 @@
% \end{macro}
%
% \begin{macro}[EXP, pTF]{\clist_if_empty:n}
-% \begin{macro}[aux, EXP]{\@@_if_empty_n:w}
-% \begin{macro}[aux, EXP]{\@@_if_empty_n:wNw}
+% \begin{macro}[EXP]{\@@_if_empty_n:w}
+% \begin{macro}[EXP]{\@@_if_empty_n:wNw}
% As usual, we insert a token (here |?|) before grabbing
% any argument: this avoids losing braces. The argument
% of \cs{tl_if_empty:oTF} is empty if |#1| is |?| followed
@@ -1434,7 +1431,7 @@
% \clist_if_in:cn, \clist_if_in:cV, \clist_if_in:co,
% \clist_if_in:nn, \clist_if_in:nV, \clist_if_in:no
% }
-% \begin{macro}[aux]{\@@_if_in_return:nn}
+% \begin{macro}{\@@_if_in_return:nn}
% \UnitTested
% See description of the \cs{tl_if_in:Nn} function for details.
% We simply surround the comma list, and the item, with commas.
@@ -1472,7 +1469,7 @@
%
% \begin{macro}{\clist_map_function:NN, \clist_map_function:cN}
% \UnitTested
-% \begin{macro}[aux]{\@@_map_function:Nw}
+% \begin{macro}{\@@_map_function:Nw}
% If the variable is empty, the mapping is skipped (otherwise,
% that comma-list would be seen as consisting of one empty item).
% Then loop over the comma-list, grabbing one comma-delimited
@@ -1502,8 +1499,8 @@
%
% \begin{macro}{\clist_map_function:nN}
% \UnitTested
-% \begin{macro}[aux]{\@@_map_function_n:Nn}
-% \begin{macro}[aux]{\@@_map_unbrace:Nw}
+% \begin{macro}{\@@_map_function_n:Nn}
+% \begin{macro}{\@@_map_unbrace:Nw}
% The \texttt{n}-type mapping function is a bit more awkward,
% since spaces must be trimmed from each item.
% Space trimming is again based on \cs{@@_trim_spaces_generic:nw}.
@@ -1575,7 +1572,7 @@
% \begin{macro}{\clist_map_variable:NNn, \clist_map_variable:cNn}
% \UnitTested
% \begin{macro}{\clist_map_variable:nNn}
-% \begin{macro}[aux]{\@@_map_variable:Nnw}
+% \begin{macro}{\@@_map_variable:Nnw}
% As for other comma-list mappings, filter out the case of
% an empty list. Same approach as \cs{clist_map_function:Nn},
% additionally we store each item in the given variable.
@@ -1622,8 +1619,8 @@
% \end{macro}
%
% \begin{macro}{\clist_count:N, \clist_count:c, \clist_count:n}
-% \begin{macro}[aux]{\@@_count:n}
-% \begin{macro}[aux]{\@@_count:w}
+% \begin{macro}{\@@_count:n}
+% \begin{macro}{\@@_count:w}
% Counting the items in a comma list is done using the same approach as for
% other token count functions: turn each entry into a \texttt{+1} then use
% integer evaluation to actually do the mathematics.
@@ -1665,7 +1662,7 @@
% \subsection{Using comma lists}
%
% \begin{macro}[EXP]{\clist_use:Nnnn, \clist_use:cnnn}
-% \begin{macro}[EXP, aux]
+% \begin{macro}[EXP]
% {\@@_use:wwn, \@@_use:nwwwwnwn, \@@_use:nwwn}
% \begin{macro}[EXP]{\clist_use:Nn, \clist_use:cn}
% First check that the variable exists. Then count the items in the
@@ -1732,8 +1729,8 @@
% \subsection{Using a single item}
%
% \begin{macro}{\clist_item:Nn, \clist_item:cn}
-% \begin{macro}[aux]{\@@_item:nnnN, \@@_item:ffoN, \@@_item:ffnN}
-% \begin{macro}[aux]{\@@_item_N_loop:nw}
+% \begin{macro}{\@@_item:nnnN, \@@_item:ffoN, \@@_item:ffnN}
+% \begin{macro}{\@@_item_N_loop:nw}
% To avoid needing to test the end of the list at each step,
% we first compute the \meta{length} of the list. If the item number
% is~$0$, less than $-\meta{length}$, or more than $\meta{length}$,
@@ -1779,7 +1776,7 @@
% \end{macro}
%
% \begin{macro}{\clist_item:nn}
-% \begin{macro}[aux]{
+% \begin{macro}{
% \@@_item_n:nw,
% \@@_item_n_loop:nw,
% \@@_item_n_end:n,
@@ -1825,40 +1822,38 @@
%
% \subsection{Viewing comma lists}
%
-% \begin{macro}{\clist_show:N, \clist_show:c}
-% \begin{macro}{\clist_show:n}
-% Apply the general \cs{__msg_show_variable:NNNnn}. In the case
-% of an \texttt{n}-type comma-list, we must do things by hand,
-% using the same message \texttt{show-clist} as for an
-% \texttt{N}-type comma-list but with an empty name (first
-% argument).
+% \begin{macro}{\clist_show:N, \clist_show:c, \clist_log:N, \clist_log:c, \@@_show:NN}
+% Apply the general \cs{__kernel_check_defined:NT} and
+% \cs{msg_show:nnnnnn}.
% \begin{macrocode}
-\cs_new_protected:Npn \clist_show:N #1
- {
- \__msg_show_variable:NNNnn #1
- \clist_if_exist:NTF \clist_if_empty:NTF { clist }
- { \clist_map_function:NN #1 \__msg_show_item:n }
- }
-\cs_new_protected:Npn \clist_show:n #1
+\cs_new_protected:Npn \clist_show:N { \@@_show:NN \msg_show:nnxxxx }
+\cs_generate_variant:Nn \clist_show:N { c }
+\cs_new_protected:Npn \clist_log:N { \@@_show:NN \msg_log:nnxxxx }
+\cs_generate_variant:Nn \clist_log:N { c }
+\cs_new_protected:Npn \@@_show:NN #1#2
{
- \__msg_show_pre:nnxxxx { LaTeX / kernel } { show-clist }
- { } { \clist_if_empty:nF {#1} { ? } } { } { }
- \__msg_show_wrap:n
- { \clist_map_function:nN {#1} \__msg_show_item:n }
+ \__kernel_check_defined:NT #2
+ {
+ #1 { LaTeX/kernel } { show-clist }
+ { \token_to_str:N #2 }
+ { \clist_map_function:NN #2 \msg_show_item:n }
+ { } { }
+ }
}
-\cs_generate_variant:Nn \clist_show:N { c }
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\clist_log:N, \clist_log:c, \clist_log:n}
-% Redirect output of \cs{clist_show:N} and \cs{clist_show:n} to the log.
+% \begin{macro}{\clist_show:n, \clist_log:n, \@@_show:Nn}
+% A variant of the above: no existence check, empty first argument for
+% the message.
% \begin{macrocode}
-\cs_new_protected:Npn \clist_log:N
- { \__msg_log_next: \clist_show:N }
-\cs_new_protected:Npn \clist_log:n
- { \__msg_log_next: \clist_show:n }
-\cs_generate_variant:Nn \clist_log:N { c }
+\cs_new_protected:Npn \clist_show:n { \@@_show:Nn \msg_show:nnxxxx }
+\cs_new_protected:Npn \clist_log:n { \@@_show:Nn \msg_log:nnxxxx }
+\cs_new_protected:Npn \@@_show:Nn #1#2
+ {
+ #1 { LaTeX/kernel } { show-clist }
+ { } { \clist_map_function:nN {#2} \msg_show_item:n } { } { }
+ }
% \end{macrocode}
% \end{macro}
%