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.dtx122
1 files changed, 93 insertions, 29 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3clist.dtx b/Master/texmf-dist/source/latex/l3kernel/l3clist.dtx
index 02064b80ea9..3db9365a1ff 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3clist.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3clist.dtx
@@ -44,7 +44,7 @@
% }^^A
% }
%
-% \date{Released 2021-02-18}
+% \date{Released 2021-05-07}
%
% \maketitle
%
@@ -286,7 +286,7 @@
% \end{syntax}
% Removes duplicate items from the \meta{comma list}, leaving the
% left most copy of each item in the \meta{comma list}. The \meta{item}
-% comparison takes place on a token basis, as for \cs{tl_if_eq:nn(TF)}.
+% comparison takes place on a token basis, as for \cs{tl_if_eq:nnTF}.
% \begin{texnote}
% This function iterates through every item in the \meta{comma list} and
% does a comparison with the \meta{items} already checked. It is therefore
@@ -307,7 +307,7 @@
% \end{syntax}
% Removes every occurrence of \meta{item} from the \meta{comma list}.
% The \meta{item} comparison takes place on a token basis, as for
-% \cs{tl_if_eq:nn(TF)}.
+% \cs{tl_if_eq:nnTF}.
% \begin{texnote}
% The function may fail if the \meta{item} contains |{|, |}|, or |#|
% (assuming the usual \TeX{} category codes apply).
@@ -396,7 +396,7 @@
% \end{texnote}
% \end{function}
%
-% \section{Mapping to comma lists}
+% \section{Mapping over comma lists}
%
% The functions described in this section apply a specified function
% to each item of a comma list.
@@ -455,6 +455,18 @@
% \meta{items} are returned from left to right.
% \end{function}
%
+% \begin{function}[rEXP, added = 2021-05-05]
+% {\clist_map_tokens:Nn, \clist_map_tokens:cn, \clist_map_tokens:nn}
+% \begin{syntax}
+% \cs{clist_map_tokens:Nn} \meta{clist~var} \Arg{code}
+% \cs{clist_map_tokens:nn} \Arg{comma list} \Arg{code}
+% \end{syntax}
+% Calls \meta{code} \Arg{item} for every \meta{item} stored in the
+% \meta{comma list}. The \meta{code} receives each \meta{item} as a
+% trailing brace group. If the \meta{code} consists of a single
+% function this is equivalent to \cs{clist_map_function:nN}.
+% \end{function}
+%
% \begin{function}[rEXP, updated = 2012-06-29]{\clist_map_break:}
% \begin{syntax}
% \cs{clist_map_break:}
@@ -703,7 +715,7 @@
%
% \section{Viewing comma lists}
%
-% \begin{function}[updated = 2015-08-03]{\clist_show:N, \clist_show:c}
+% \begin{function}[updated = 2021-04-29]{\clist_show:N, \clist_show:c}
% \begin{syntax}
% \cs{clist_show:N} \meta{comma list}
% \end{syntax}
@@ -717,7 +729,7 @@
% Displays the entries in the comma list in the terminal.
% \end{function}
%
-% \begin{function}[added = 2014-08-22, updated = 2015-08-03]{\clist_log:N, \clist_log:c}
+% \begin{function}[added = 2014-08-22, updated = 2021-04-29]{\clist_log:N, \clist_log:c}
% \begin{syntax}
% \cs{clist_log:N} \meta{comma list}
% \end{syntax}
@@ -1622,32 +1634,32 @@
% \end{macro}
% \end{macro}
%
-% \subsection{Mapping to comma lists}
+% \subsection{Mapping over comma lists}
%
% \begin{macro}{\clist_map_function:NN, \clist_map_function:cN}
% \UnitTested
-% \begin{macro}{\@@_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
% item at a time. The end is marked by \cs{q_@@_recursion_tail}.
-% The auxiliary function \cs{@@_map_function:Nw} is also used
+% The auxiliary function \cs{@@_map_function:nw} is also used
% in \cs{clist_map_inline:Nn}.
% \begin{macrocode}
\cs_new:Npn \clist_map_function:NN #1#2
{
\clist_if_empty:NF #1
{
- \exp_last_unbraced:NNo \@@_map_function:Nw #2 #1
+ \exp_last_unbraced:NNo \@@_map_function:nw #2 #1
, \q_@@_recursion_tail ,
\prg_break_point:Nn \clist_map_break: { }
}
}
-\cs_new:Npn \@@_map_function:Nw #1#2 ,
+\cs_new:Npn \@@_map_function:nw #1#2 ,
{
\@@_if_recursion_tail_break:nN {#2} \clist_map_break:
#1 {#2}
- \@@_map_function:Nw #1
+ \@@_map_function:nw {#1}
}
\cs_generate_variant:Nn \clist_map_function:NN { c }
% \end{macrocode}
@@ -1657,14 +1669,14 @@
% \begin{macro}{\clist_map_function:nN}
% \UnitTested
% \begin{macro}{\@@_map_function_n:Nn}
-% \begin{macro}{\@@_map_unbrace:Nw}
+% \begin{macro}{\@@_map_unbrace:wn}
% 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_next:w}.
% The auxiliary \cs{@@_map_function_n:Nn} receives as arguments the
% function, and the next non-empty item (after space trimming but
% before brace removal). One level of braces is removed by
-% \cs{@@_map_unbrace:Nw}.
+% \cs{@@_map_unbrace:wn}.
% \begin{macrocode}
\cs_new:Npn \clist_map_function:nN #1#2
{
@@ -1675,11 +1687,11 @@
\cs_new:Npn \@@_map_function_n:Nn #1 #2
{
\@@_if_recursion_tail_break:nN {#2} \clist_map_break:
- \@@_map_unbrace:Nw #1 #2,
+ \@@_map_unbrace:wn #2 , #1
\exp_after:wN \@@_map_function_n:Nn \exp_after:wN #1
\exp:w \@@_trim_next:w \prg_do_nothing:
}
-\cs_new:Npn \@@_map_unbrace:Nw #1 #2, { #1 {#2} }
+\cs_new:Npn \@@_map_unbrace:wn #1, #2 { #2 {#1} }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -1708,7 +1720,7 @@
\int_gincr:N \g__kernel_prg_map_int
\cs_gset_protected:cpn
{ @@_map_ \int_use:N \g__kernel_prg_map_int :w } ##1 {#2}
- \exp_last_unbraced:Nco \@@_map_function:Nw
+ \exp_last_unbraced:Nco \@@_map_function:nw
{ @@_map_ \int_use:N \g__kernel_prg_map_int :w }
#1 , \q_@@_recursion_tail ,
\prg_break_point:Nn \clist_map_break:
@@ -1768,6 +1780,49 @@
% \end{macro}
% \end{macro}
%
+% \begin{macro}{\clist_map_tokens:Nn, \clist_map_tokens:cn}
+% \begin{macro}{\@@_map_tokens:nw}
+% Essentially a copy of \cs{clist_map_function:NN} with braces added.
+% \begin{macrocode}
+\cs_new:Npn \clist_map_tokens:Nn #1#2
+ {
+ \clist_if_empty:NF #1
+ {
+ \exp_last_unbraced:Nno \@@_map_function:nw {#2} #1
+ , \q_@@_recursion_tail ,
+ \prg_break_point:Nn \clist_map_break: { }
+ }
+ }
+\cs_generate_variant:Nn \clist_map_tokens:Nn { c }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\clist_map_tokens:nn, \@@_map_tokens_n:nw, \@@_use_ii_i:nn}
+% Similar to \cs{clist_map_function:nN} but with a different way of
+% grabbing items because we cannot use \cs{exp_after:wN} to pass the
+% \meta{code}.
+% \begin{macrocode}
+\cs_new:Npn \clist_map_tokens:nn #1#2
+ {
+ \@@_map_tokens_n:nw {#2}
+ \prg_do_nothing: #1 , \q_@@_recursion_tail ,
+ \prg_break_point:Nn \clist_map_break: { }
+ }
+\cs_new:Npn \@@_map_tokens_n:nw #1#2 ,
+ {
+ \tl_if_empty:oF { \use_none:nn #2 ? }
+ {
+ \exp_args:No \@@_if_recursion_tail_break:nN {#2} \clist_map_break:
+ \tl_trim_spaces_apply:oN {#2} \@@_use_ii_i:nn
+ \@@_map_unbrace:wn , {#1}
+ }
+ \@@_map_tokens_n:nw {#1} \prg_do_nothing:
+ }
+\cs_new:Npn \@@_use_ii_i:nn #1#2 { #2 #1 }
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\clist_map_break:, \clist_map_break:n}
% The break statements use the general \cs{prg_map_break:Nn} mechanism.
% \begin{macrocode}
@@ -2009,21 +2064,30 @@
% \subsection{Viewing comma lists}
%
% \begin{macro}{\clist_show:N, \clist_show:c, \clist_log:N, \clist_log:c, \@@_show:NN}
-% Apply the general \cs{__kernel_chk_defined:NT} and
-% \cs{msg_show:nnnnnn}.
+% Apply the general \cs{__kernel_chk_tl_type:NnnT} with \cs{exp_not:o}
+% |#2| serving as a dummy code to prevent a check performed by this
+% auxiliary.
% \begin{macrocode}
-\cs_new_protected:Npn \clist_show:N { \@@_show:NN \msg_show:nnxxxx }
+\cs_new_protected:Npn \clist_show:N { \@@_show:NN \__kernel_msg_show:nnxxxx }
\cs_generate_variant:Nn \clist_show:N { c }
-\cs_new_protected:Npn \clist_log:N { \@@_show:NN \msg_log:nnxxxx }
+\cs_new_protected:Npn \clist_log:N { \@@_show:NN \__kernel_msg_log:nnxxxx }
\cs_generate_variant:Nn \clist_log:N { c }
\cs_new_protected:Npn \@@_show:NN #1#2
{
- \__kernel_chk_defined:NT #2
+ \__kernel_chk_tl_type:NnnT #2 { clist } { \exp_not:o #2 }
{
- #1 { LaTeX/kernel } { show-clist }
- { \token_to_str:N #2 }
- { \clist_map_function:NN #2 \msg_show_item:n }
- { } { }
+ \int_compare:nNnTF { \clist_count:N #2 }
+ = { \exp_args:No \clist_count:n #2 }
+ {
+ #1 { clist } { show }
+ { \token_to_str:N #2 }
+ { \clist_map_function:NN #2 \msg_show_item:n }
+ { } { }
+ }
+ {
+ \__kernel_msg_error:nnxx { kernel } { non-clist }
+ { \token_to_str:N #2 } { \tl_to_str:N #2 }
+ }
}
}
% \end{macrocode}
@@ -2033,11 +2097,11 @@
% A variant of the above: no existence check, empty first argument for
% the message.
% \begin{macrocode}
-\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 \clist_show:n { \@@_show:Nn \__kernel_msg_show:nnxxxx }
+\cs_new_protected:Npn \clist_log:n { \@@_show:Nn \__kernel_msg_log:nnxxxx }
\cs_new_protected:Npn \@@_show:Nn #1#2
{
- #1 { LaTeX/kernel } { show-clist }
+ #1 { clist } { show }
{ } { \clist_map_function:nN {#2} \msg_show_item:n } { } { }
}
% \end{macrocode}