[latex3-commits] [latex3/latex3] tl-build-access: Add \tl_build_suspend:N and _resume:N (d588687ee)

Wed Oct 25 13:44:28 CEST 2023

Repository : https://github.com/latex3/latex3
On branch  : tl-build-access
Link       : https://github.com/latex3/latex3/commit/d588687eed5e2bd8f7559eccebbddd3be2ec0d26

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

commit d588687eed5e2bd8f7559eccebbddd3be2ec0d26
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Wed Oct 25 12:28:24 2023 +0100

    Add \tl_build_suspend:N and _resume:N


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

d588687eed5e2bd8f7559eccebbddd3be2ec0d26
 l3experimental/l3draw/l3draw-softpath.dtx |  9 ++---
 l3kernel/CHANGELOG.md                     |  1 +
 l3kernel/l3regex.dtx                      |  4 ++-
 l3kernel/l3tl-build.dtx                   | 56 +++++++++++++++++++++++++++++++
 l3kernel/testfiles/m3tl-build001.lvt      | 18 ++++++++++
 l3kernel/testfiles/m3tl-build001.tlg      | 10 ++++++
 6 files changed, 91 insertions(+), 7 deletions(-)

diff --git a/l3experimental/l3draw/l3draw-softpath.dtx b/l3experimental/l3draw/l3draw-softpath.dtx
index 20ba86f33..0afc8fb13 100644
--- a/l3experimental/l3draw/l3draw-softpath.dtx
+++ b/l3experimental/l3draw/l3draw-softpath.dtx
@@ -109,12 +109,9 @@
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_softpath_use:
   {
-    \tl_build_gend:N \g_@@_softpath_main_tl
-    \tl_set_eq:NN \l_@@_softpath_tmp_tl \g_@@_softpath_main_tl
-    \l_@@_softpath_tmp_tl
-    \tl_build_gbegin:N \g_@@_softpath_main_tl
-    \exp_args:NNV \tl_build_gput_right:Nn
-      \g_@@_softpath_main_tl \l_@@_softpath_tmp_tl
+    \tl_build_gsuspend:N \g_@@_softpath_main_tl
+    \g_@@_softpath_main_tl
+    \tl_build_gresume:N \g_@@_softpath_main_tl
   }
 \cs_new_protected:Npn \@@_softpath_clear:
   {
diff --git a/l3kernel/CHANGELOG.md b/l3kernel/CHANGELOG.md
index de7c82eb6..d42af1e6c 100644
--- a/l3kernel/CHANGELOG.md
+++ b/l3kernel/CHANGELOG.md
@@ -10,6 +10,7 @@ this project uses date-based 'snapshot' version identifiers.
 ### Added
 - `\text_titlecase_all:n(n)`
 - `\token_to_catcode:N`
+- `\tl_build_(g)suspend:N` and `\tl_build_(g)resume:N`
 
 ### Changed
 - Refine action of `\text_titlecase_first:n(n)` to be focussed strictly on
diff --git a/l3kernel/l3regex.dtx b/l3kernel/l3regex.dtx
index 77645de29..b558710f4 100644
--- a/l3kernel/l3regex.dtx
+++ b/l3kernel/l3regex.dtx
@@ -5354,7 +5354,9 @@
     \int_set:Nn \l_@@_curr_pos_int
       { \l_@@_start_pos_int - 1 }
     \int_set_eq:NN \l_@@_curr_char_int \l_@@_last_char_success_int
-    \tl_build_get:NN \l_@@_matched_analysis_tl \l_@@_internal_a_tl
+    \tl_build_suspend:N \l_@@_matched_analysis_tl
+    \tl_set_eq:NN \l_@@_internal_a_tl \l_@@_matched_analysis_tl
+    \tl_build_resume:N \l_@@_matched_analysis_tl
     \exp_args:NNf \@@_match_once_init_aux:
     \tl_map_inline:nn
       { \exp_after:wN \l_@@_internal_a_tl \l_@@_curr_analysis_tl }
diff --git a/l3kernel/l3tl-build.dtx b/l3kernel/l3tl-build.dtx
index b8c0e2056..a83d33e1c 100644
--- a/l3kernel/l3tl-build.dtx
+++ b/l3kernel/l3tl-build.dtx
@@ -106,6 +106,27 @@
 %   \texttt{tl} functions.
 % \end{function}
 %
+% \begin{function}[added = 2023-10-25]
+%   {
+%    \tl_build_suspend:N, \tl_build_gsuspend:N,
+%    \tl_build_resume:N,  \tl_build_gresume:N
+%   }
+%   \begin{syntax}
+%     \cs{tl_build_suspend:N} \meta{tl~var}
+%     ...
+%     \cs{tl_build_resume:N} \meta{tl~var}
+%   \end{syntax}
+%   Suspends accumulation of tokens to the \cs{tl~var} such that it may be
+%   accessed normally. In contrast to \cs{tl_build_end:N}, the \texttt{suspend}
+%   function leaves the internal structures in place, which allows the
+%   rapid \texttt{resume} approach. The \texttt{suspend}/\texttt{resume}
+%   pair should therefore be used together: suspending accumulation then
+%   starting again with \cs{tl_build_begin:N} may result in unpredictable
+%   outcomes. Due to the lack of clean-up, \cs{tl_build_suspend:N} is faster
+%   than \cs{tl_build_end:N} and therefore is useful when needing to access
+%   a partial token list that will continue to be accumulated.
+% \end{function}
+%
 % \end{documentation}
 %
 % \begin{implementation}
@@ -294,6 +315,41 @@
 % \end{macro}
 % \end{macro}
 %
+% \begin{macro}{\tl_build_suspend:N, \tl_build_gsuspend:N}
+% \begin{macro}{\@@_build_suspend:NN}
+%   Save the current data: we have to go low-level here as the suspension needs
+%   to be fast and easy to clean up.
+%    \begin{macrocode}
+\cs_new_protected:Npn \tl_build_suspend:N #1
+  { \@@_build_suspend:NN #1 \cs_set_nopar:Npe }
+\cs_new_protected:Npn \tl_build_gsuspend:N #1
+  { \@@_build_suspend:NN #1 \cs_gset_nopar:Npe }
+\cs_new_protected:Npn \@@_build_suspend:NN #1#2
+  {
+    \exp_args:Nc #2 { \cs_to_str:N #1 ~ suspended } { \exp_not:V #1 }
+    \@@_build_get:NNN #2 #1 #1
+  }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\tl_build_resume:N, \tl_build_gresume:N}
+% \begin{macro}{\@@_build_resume:NN}
+%   Put the data back and clean up.
+%    \begin{macrocode}
+\cs_new_protected:Npn \tl_build_resume:N #1
+  { \@@_build_resume:NN #1 \cs_set_eq:NN }
+\cs_new_protected:Npn \tl_build_gresume:N #1
+  { \@@_build_resume:NN #1 \cs_gset_eq:NN }
+\cs_new_protected:Npn \@@_build_resume:NN #1#2
+  {
+    \exp_args:NNc #2 #1 { \cs_to_str:N #1 ~ suspended }
+    \exp_args:Nc #2 { \cs_to_str:N #1 ~ suspended } \tex_undefined:D
+  }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
 % \begin{macro}{\@@_build_get:NNN}
 % \begin{macro}{\@@_build_get:w, \@@_build_get_end:w}
 %   The idea is to expand the \meta{tl~var} then the \meta{next~tl} and
diff --git a/l3kernel/testfiles/m3tl-build001.lvt b/l3kernel/testfiles/m3tl-build001.lvt
index 0e4e36dde..206b07bc3 100644
--- a/l3kernel/testfiles/m3tl-build001.lvt
+++ b/l3kernel/testfiles/m3tl-build001.lvt
@@ -58,4 +58,22 @@
     \tl_build_gend:N \l_tmpa_tl
   }
 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\TEST { Interrupting~accumulation }
+  {
+    \tl_build_begin:N \l_tmpa_tl
+    \tl_build_put_right:Nn \l_tmpa_tl { # }
+    \tl_build_put_right:Nn \l_tmpa_tl { AB }
+    \tl_build_put_right:Nn \l_tmpa_tl { \par }
+    \tl_build_put_left:Ne \l_tmpa_tl { \iow_char:N \\ }
+    \tl_build_suspend:N \l_tmpa_tl
+    \tl_show:N \l_tmpa_tl
+    \tl_build_resume:N \l_tmpa_tl
+    \tl_build_put_right:Nn \l_tmpa_tl { \c_space_tl }
+    \tl_build_put_right:Nn \l_tmpa_tl { ## }
+    \tl_build_put_left:Nn \l_tmpa_tl { \foo }
+    \tl_build_end:N \l_tmpa_tl
+    \tl_show:N \l_tmpa_tl
+  }
+
 \END
diff --git a/l3kernel/testfiles/m3tl-build001.tlg b/l3kernel/testfiles/m3tl-build001.tlg
index 4549271c8..04553edc2 100644
--- a/l3kernel/testfiles/m3tl-build001.tlg
+++ b/l3kernel/testfiles/m3tl-build001.tlg
@@ -83,3 +83,13 @@ l. ...  }
 This is a coding error.
 Global assignment to a local variable '\l_tmpa_tl'.
 ============================================================
+============================================================
+TEST 3: Interrupting accumulation
+============================================================
+> \l_tmpa_tl=\##AB\par .
+<recently read> }
+l. ...  }
+> \l_tmpa_tl=\foo \##AB\par \c_space_tl ####.
+<recently read> }
+l. ...  }
+============================================================



