[latex3-commits] [git/LaTeX3-latex3-latex3] master: Document the code of \peek_regex:nTF and \peek_regex_remove:nTF (999382981)

[Joseph Wright]

Repository : https://github.com/latex3/latex3
On branch  : master
Link       : https://github.com/latex3/latex3/commit/9993829811ce2851b3208b43eb7403c092756565

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

commit 9993829811ce2851b3208b43eb7403c092756565
Author: Bruno Le Floch <blflatex at gmail.com>
Date:   Tue Jul 21 12:37:24 2020 +0200

    Document the code of \peek_regex:nTF and \peek_regex_remove:nTF


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

9993829811ce2851b3208b43eb7403c092756565
 l3kernel/l3regex.dtx | 60 ++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 49 insertions(+), 11 deletions(-)

diff --git a/l3kernel/l3regex.dtx b/l3kernel/l3regex.dtx
index 06ea8c3d5..50aec9a53 100644
--- a/l3kernel/l3regex.dtx
+++ b/l3kernel/l3regex.dtx
@@ -6365,7 +6365,17 @@
 % \end{variable}
 %
 % \begin{macro}[TF]{\peek_regex:n, \peek_regex:N, \peek_regex_remove:n, \peek_regex_remove:N}
-% \begin{macro}{\@@_peek:nnTF, \@@_peek_end:, \@@_peek_end_aux:N, \@@_peek_remove_end:n}
+%   The |T| and |F| functions just call the corresponding |TF| function.
+%   The four |TF| functions differ along two axes: whether to remove the
+%   token or not, distinguished by using \cs{@@_peek_end:} or
+%   \cs{@@_peek_remove_end:n} (the latter case needs an argument, as we
+%   will see), and whether the regex has to be compiled or is already in
+%   an |N|-type variable, distinguished by calling \cs{@@_build_aux:Nn}
+%   or \cs{@@_build_aux:NN}.  The first argument of these functions is
+%   \cs{c_false_bool} to indicate that there should be no implicit
+%   insertion of a wildcard at the start of the pattern: otherwise the
+%   code would keep looking further into the input stream until matching
+%   the regex.
 %    \begin{macrocode}
 \cs_new_protected:Npn \peek_regex:nTF #1
   {
@@ -6401,6 +6411,22 @@
   { \peek_regex_remove:NTF #1 {#2} { } }
 \cs_new_protected:Npn \peek_regex_remove:NF #1
   { \peek_regex_remove:NTF #1 { } }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_peek:nnTF}
+%   Store the user's true/false codes (plus \cs{group_end:}) into two
+%   token lists.  Then build the automaton with |#2|, without submatch
+%   tracking, and aiming for a single match.  Then start matching by
+%   setting up a few variables like for any regex matching like
+%   \cs{regex_match:nnTF}, with the addition of \cs{l_@@_reinsert_tl}
+%   that keeps track of the tokens seen, to reinsert them at the
+%   end.  Instead of \cs{tl_analysis_map_inline:nn} on the input, we
+%   call \cs{peek_analysis_map_inline:n} to go through tokens in the
+%   input stream.  Since \cs{@@_match_one_token:nnN} calls
+%   \cs{@@_maplike_break:} we need to catch that and break the
+%   \cs{peek_analysis_map_inline:n} loop instead.
+%    \begin{macrocode}
 \cs_new_protected:Npn \@@_peek:nnTF #1#2#3#4
   {
     \group_begin:
@@ -6422,27 +6448,39 @@
             { \peek_analysis_map_break:n {#1} }
         }
   }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{ \@@_peek_end:, \@@_peek_remove_end:n, \@@_peek_reinsert:N}
+%   Once the regex matches (or permanently fails to match) we call
+%   \cs{@@_peek_end:}, or \cs{@@_peek_remove_end:n} with argument the
+%   last token seen (or rather tokens that \texttt{o}-expand and
+%   \texttt{x}-expand to it).  For \cs{peek_regex:nTF} we reinsert
+%   tokens seen by calling \cs{@@_peek_reinsert:N} regardless of the
+%   result of the match.  For \cs{peek_regex_remove:nTF} we reinsert the
+%   tokens seen only if the match failed; otherwise we just reinsert the
+%   tokens~|#1|, with one expansion.
+%    \begin{macrocode}
 \cs_new_protected:Npn \@@_peek_end:
   {
     \bool_if:NTF \g_@@_success_bool
-      { \@@_peek_end_aux:N \l_@@_peek_true_tl }
-      { \@@_peek_end_aux:N \l_@@_peek_false_tl }
-  }
-\cs_new_protected:Npn \@@_peek_end_aux:N #1
-  {
-    \tl_build_end:N \l_@@_reinsert_tl
-    \exp_after:wN #1
-    \exp:w \l_@@_reinsert_tl \exp_end:
+      { \@@_peek_reinsert:N \l_@@_peek_true_tl }
+      { \@@_peek_reinsert:N \l_@@_peek_false_tl }
   }
 \cs_new_protected:Npn \@@_peek_remove_end:n #1
   {
     \bool_if:NTF \g_@@_success_bool
       { \exp_after:wN \l_@@_peek_true_tl #1 }
-      { \@@_peek_end_aux:N \l_@@_peek_false_tl }
+      { \@@_peek_reinsert:N \l_@@_peek_false_tl }
+  }
+\cs_new_protected:Npn \@@_peek_reinsert:N #1
+  {
+    \tl_build_end:N \l_@@_reinsert_tl
+    \exp_after:wN #1
+    \exp:w \l_@@_reinsert_tl \exp_end:
   }
 %    \end{macrocode}
 % \end{macro}
-% \end{macro}
 %
 % \subsection{Messages}
 %