[latex3-commits] [git/LaTeX3-latex3-latex3] main: Implement \clist_map_tokens:nn (see #900) (19def0d99)

[Joseph Wright]

Repository : https://github.com/latex3/latex3
On branch  : main
Link       : https://github.com/latex3/latex3/commit/19def0d99dc4d0ef7a342945a1c6e690f157f2cc

>---------------------------------------------------------------

commit 19def0d99dc4d0ef7a342945a1c6e690f157f2cc
Author: Bruno Le Floch <blflatex at gmail.com>
Date:   Wed May 5 00:31:07 2021 +0200

    Implement \clist_map_tokens:nn (see #900)


>---------------------------------------------------------------

19def0d99dc4d0ef7a342945a1c6e690f157f2cc
 l3kernel/l3candidates.dtx | 61 +++++++++++++++++++++++++++++++++++++++++++++++
 l3kernel/l3clist.dtx      | 20 ++++++++--------
 2 files changed, 71 insertions(+), 10 deletions(-)

diff --git a/l3kernel/l3candidates.dtx b/l3kernel/l3candidates.dtx
index 7e963e4eb..ed740165a 100644
--- a/l3kernel/l3candidates.dtx
+++ b/l3kernel/l3candidates.dtx
@@ -146,6 +146,20 @@
 %   operation is applied.
 % \end{function}
 %
+% \section{Additions to \pkg{l3clist}}
+%
+% \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}
+%
 % \section{Additions to \pkg{l3expan}}
 %
 % \begin{function}[added = 2018-04-04, updated = 2019-02-08]
@@ -876,6 +890,53 @@
 % \end{macro}
 % \end{macro}
 %
+% \subsection{Additions to \pkg{l3clist}}
+%
+%    \begin{macrocode}
+%<@@=clist>
+%    \end{macrocode}
+%
+% \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}
+%   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} \@@_map_unbrace:wn , {#1}
+      }
+    \@@_map_tokens_n:nw {#1} \prg_do_nothing:
+  }
+%    \end{macrocode}
+% \end{macro}
+%
 % \subsection{Additions to \pkg{l3flag}}
 %
 %    \begin{macrocode}
diff --git a/l3kernel/l3clist.dtx b/l3kernel/l3clist.dtx
index ed725d081..545a64d26 100644
--- a/l3kernel/l3clist.dtx
+++ b/l3kernel/l3clist.dtx
@@ -1626,28 +1626,28 @@
 %
 % \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 +1657,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 +1675,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 +1708,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: