Make \prg_break_point:Nn public

Also \prg_map_break:Nn Other aspects of this code still to be addressed: likely to make them internal to each module
latex3 · Mar 26, 2018 · 71aa488 · 71aa488
1 parent 330889a
commit 71aa488
Show file tree

Hide file tree

Showing 23 changed files with 132 additions and 92 deletions.
diff --git a/l3kernel/l3basics.dtx b/l3kernel/l3basics.dtx
@@ -3536,7 +3536,7 @@
 %<@@=prg>
 %    \end{macrocode}
 %
-% \begin{macro}[EXP]{\@@_break_point:Nn, \@@_map_break:Nn}
+% \begin{macro}[EXP]{\prg_break_point:Nn, \prg_map_break:Nn}
 %   In inline mappings, the nesting level must be reset
 %   at the end of the mapping, even when the user decides
 %   to break out. This is done by putting the code that
@@ -3546,14 +3546,14 @@
 %   before the user's code (if any).  There is a check that we close the
 %   correct loop, otherwise we continue breaking.
 %    \begin{macrocode}
-\cs_new_eq:NN \@@_break_point:Nn \use_ii:nn
-\cs_new:Npn \@@_map_break:Nn #1#2#3 \@@_break_point:Nn #4#5
+\cs_new_eq:NN \prg_break_point:Nn \use_ii:nn
+\cs_new:Npn \prg_map_break:Nn #1#2#3 \prg_break_point:Nn #4#5
   {
     #5
     \if_meaning:w #1 #4
       \exp_after:wN \use_iii:nnn
     \fi:
-    \@@_map_break:Nn #1 {#2}
+    \prg_map_break:Nn #1 {#2}
   }
 %    \end{macrocode}
 % \end{macro}

diff --git a/l3kernel/l3candidates.dtx b/l3kernel/l3candidates.dtx
@@ -2123,7 +2123,7 @@
   {
     \exp_last_unbraced:Nno \@@_map_tokens:nwwn {#2} #1
       \@@_pair:wn \q_recursion_tail \s_@@ { }
-    \__prg_break_point:Nn \prop_map_break: { }
+    \prg_break_point:Nn \prop_map_break: { }
   }
 \cs_new:Npn \@@_map_tokens:nwwn #1#2 \@@_pair:wn #3 \s_@@ #4
   {

diff --git a/l3kernel/l3clist.dtx b/l3kernel/l3clist.dtx
@@ -1472,7 +1472,7 @@
       {
         \exp_last_unbraced:NNo \@@_map_function:Nw #2 #1
           , \q_recursion_tail ,
-        \__prg_break_point:Nn \clist_map_break: { }
+        \prg_break_point:Nn \clist_map_break: { }
       }
   }
 \cs_new:Npn \@@_map_function:Nw #1#2 ,
@@ -1503,7 +1503,7 @@
   {
     \@@_trim_spaces_generic:nw { \@@_map_function_n:Nn #2 }
     \q_mark #1, \q_recursion_tail,
-    \__prg_break_point:Nn \clist_map_break: { }
+    \prg_break_point:Nn \clist_map_break: { }
   }
 \cs_new:Npn \@@_map_function_n:Nn #1 #2
   {
@@ -1544,7 +1544,7 @@
         \exp_last_unbraced:Nco \@@_map_function:Nw
           { __prg_map_ \int_use:N \g__prg_map_int :w }
           #1 , \q_recursion_tail ,
-        \__prg_break_point:Nn \clist_map_break:
+        \prg_break_point:Nn \clist_map_break:
           { \int_gdecr:N \g__prg_map_int }
       }
   }
@@ -1576,7 +1576,7 @@
           { \@@_map_variable:Nnw #2 {#3} }
           #1
           , \q_recursion_tail , \q_recursion_stop
-        \__prg_break_point:Nn \clist_map_break: { }
+        \prg_break_point:Nn \clist_map_break: { }
       }
   }
 \cs_new_protected:Npn \clist_map_variable:nNn #1
@@ -1598,12 +1598,12 @@
 % \end{macro}
 %
 % \begin{macro}{\clist_map_break:, \clist_map_break:n}
-%   The break statements use the general \cs{__prg_map_break:Nn} mechanism.
+%   The break statements use the general \cs{prg_map_break:Nn} mechanism.
 %    \begin{macrocode}
 \cs_new:Npn \clist_map_break:
-  { \__prg_map_break:Nn \clist_map_break: { } }
+  { \prg_map_break:Nn \clist_map_break: { } }
 \cs_new:Npn \clist_map_break:n
-  { \__prg_map_break:Nn \clist_map_break: }
+  { \prg_map_break:Nn \clist_map_break: }
 %    \end{macrocode}
 % \end{macro}
 %

diff --git a/l3kernel/l3file.dtx b/l3kernel/l3file.dtx
@@ -1430,9 +1430,9 @@
 %   Usual map breaking functions.
 %    \begin{macrocode}
 \cs_new:Npn \ior_map_break:
-  { \__prg_map_break:Nn \ior_map_break: { } }
+  { \prg_map_break:Nn \ior_map_break: { } }
 \cs_new:Npn \ior_map_break:n
-  { \__prg_map_break:Nn \ior_map_break: }
+  { \prg_map_break:Nn \ior_map_break: }
 %    \end{macrocode}
 % \end{macro}
 %
@@ -1461,7 +1461,7 @@
   {
     \cs_gset_protected:Npn #1 ##1 {#4}
     \ior_if_eof:NF #3 { \@@_map_inline_loop:NNN #1#2#3 }
-    \__prg_break_point:Nn \ior_map_break:
+    \prg_break_point:Nn \ior_map_break:
       { \int_gdecr:N \g__prg_map_int }
   }
 \cs_new_protected:Npn \@@_map_inline_loop:NNN #1#2#3

diff --git a/l3kernel/l3fp-logic.dtx b/l3kernel/l3fp-logic.dtx
@@ -478,7 +478,7 @@
   {
     #1 #2 ##1 {#6}
     \fp_step_function:nnnN {#3} {#4} {#5} #2
-    \__prg_break_point:Nn \scan_stop: { \int_gdecr:N \g__prg_map_int }
+    \prg_break_point:Nn \scan_stop: { \int_gdecr:N \g__prg_map_int }
   }
 %    \end{macrocode}
 % \end{macro}

diff --git a/l3kernel/l3int.dtx b/l3kernel/l3int.dtx
@@ -1835,7 +1835,7 @@
 %   The approach here is to build a function, with a global integer
 %   required to make the nesting safe (as seen in other in line
 %   functions), and map that function using \cs{int_step_function:nnnN}.
-%   We put a \cs{__prg_break_point:Nn} so that \texttt{map_break}
+%   We put a \cs{prg_break_point:Nn} so that \texttt{map_break}
 %   functions from other modules correctly decrement \cs{g__prg_map_int}
 %   before looking for their own break point.  The first argument is
 %   \cs{scan_stop:}, so that no breaking function recognizes this break
@@ -1864,7 +1864,7 @@
   {
     #1 #2 ##1 {#6}
     \int_step_function:nnnN {#3} {#4} {#5} #2
-    \__prg_break_point:Nn \scan_stop: { \int_gdecr:N \g__prg_map_int }
+    \prg_break_point:Nn \scan_stop: { \int_gdecr:N \g__prg_map_int }
   }
 %    \end{macrocode}
 % \end{macro}

diff --git a/l3kernel/l3prg.dtx b/l3kernel/l3prg.dtx
@@ -654,6 +654,41 @@
 %   branches according to the result.
 % \end{function}
 %
+% \section{Nestable recursions and mappings}
+%
+% There are a number of places where recursion or mapping constructs are used in
+% \pkg{expl3}. At a low-level, these typically require insertion of tokens
+% at the end of the content to allow \enquote{clean up}. To support such
+% mappings in a nestable form, the following functions are provided.
+%
+% \begin{function}[EXP, added = 2018-03-26]{\prg_break_point:Nn}
+%   \begin{syntax}
+%     \cs{prg_break_point:Nn} \cs[no-index]{\meta{type}_map_break:} \Arg{code}
+%   \end{syntax}
+%   Used to mark the end of a recursion or mapping: the functions
+%   \cs[no-index]{\meta{type}_map_break:} and
+%   \cs[no-index]{\meta{type}_map_break:n} use this to break out of the loop
+%   (see \cs{prg_map_break:Nn} for how to set these up).
+%   After the loop ends, the \meta{code} is inserted into the input stream. This
+%   occurs even if the break functions are \emph{not} applied:
+%   \cs{prg_break_point:Nn} is functionally-equivalent in these cases
+%   to \cs{use_ii:nn}.
+% \end{function}
+%
+% \begin{function}[EXP, added = 2018-03-26]{\prg_map_break:Nn}
+%   \begin{syntax}
+%     \cs{prg_map_break:Nn} \cs[no-index]{\meta{type}_map_break:} \Arg{user code}
+%     \ldots{}
+%     \cs{prg_break_point:Nn} \cs[no-index]{\meta{type}_map_break:} \Arg{ending code}
+%   \end{syntax}
+%   Breaks a recursion in mapping contexts, inserting in the input
+%   stream the \meta{user code} after the \meta{ending code} for the
+%   loop.  The function breaks loops, inserting their \meta{ending
+%   code}, until reaching a loop with the same \meta{type} as its
+%   first argument.  This \cs[no-index]{\meta{type}_map_break:} argument is
+%   simply used as a recognizable marker for the \meta{type}.
+% \end{function}
+%
 % \section{Internal programming functions}
 %
 % \begin{function}[updated = 2011-08-11, EXP]
@@ -677,33 +712,6 @@
 %   within the same function.
 % \end{function}
 %
-% \begin{function}[EXP]{\__prg_break_point:Nn}
-%   \begin{syntax}
-%     \cs{__prg_break_point:Nn} \cs[no-index]{\meta{type}_map_break:} \Arg{code}
-%   \end{syntax}
-%   Used to mark the end of a recursion or mapping: the functions
-%   \cs[no-index]{\meta{type}_map_break:} and \cs[no-index]{\meta{type}_map_break:n} use
-%   this to break out of the loop. After the loop ends, the
-%   \meta{code} is inserted into the input stream. This occurs even
-%   if the break functions are \emph{not} applied:
-%   \cs{__prg_break_point:Nn} is functionally-equivalent in these cases
-%   to \cs{use_ii:nn}.
-% \end{function}
-%
-% \begin{function}[EXP]{\__prg_map_break:Nn}
-%   \begin{syntax}
-%     \cs{__prg_map_break:Nn} \cs[no-index]{\meta{type}_map_break:} \Arg{user code}
-%     \ldots{}
-%     \cs{__prg_break_point:Nn} \cs[no-index]{\meta{type}_map_break:} \Arg{ending code}
-%   \end{syntax}
-%   Breaks a recursion in mapping contexts, inserting in the input
-%   stream the \meta{user code} after the \meta{ending code} for the
-%   loop.  The function breaks loops, inserting their \meta{ending
-%     code}, until reaching a loop with the same \meta{type} as its
-%   first argument.  This \cs[no-index]{\meta{type}_map_break:} argument is simply
-%   used as a recognizable marker for the \meta{type}.
-% \end{function}
-%
 % \begin{variable}{\g__prg_map_int}
 %   This integer is used by non-expandable mapping functions to track
 %   the level of nesting in force.  The functions \cs{__prg_map_1:w},
@@ -1539,8 +1547,8 @@
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{macro}{\@@_break_point:Nn}
-% \begin{macro}{\@@_map_break:Nn}
+% \begin{macro}{\prg_break_point:Nn}
+% \begin{macro}{\prg_map_break:Nn}
 %   These are defined in \pkg{l3basics}, as they are needed
 %   \enquote{early}. This is just a reminder that is the case!
 % \end{macro}
@@ -1553,6 +1561,18 @@
 % \end{macro}
 % \end{macro}
 %
+% \subsection{Deprecated functions}
+%
+% \begin{macro}[deprecated = 2019-12-31]{\@@_break_point:Nn}
+% \begin{macro}[deprecated = 2019-12-31]{\@@_map_break:Nn}
+%   Made public, but used by a few third-parties.
+%    \begin{macrocode}
+\cs_new:Npn \@@_break_point:Nn { \prg_break_point:Nn }
+\cs_new:Npn \@@_map_break:Nn { \prg_map_break:Nn }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
 %    \begin{macrocode}
 %</initex|package>
 %    \end{macrocode}

diff --git a/l3kernel/l3prop.dtx b/l3kernel/l3prop.dtx
@@ -1117,7 +1117,7 @@
   {
     \exp_last_unbraced:NNo \@@_map_function:Nwwn #2 #1
       \@@_pair:wn \q_recursion_tail \s_@@ { }
-    \__prg_break_point:Nn \prop_map_break: { }
+    \prg_break_point:Nn \prop_map_break: { }
   }
 \cs_new:Npn \@@_map_function:Nwwn #1#2 \@@_pair:wn #3 \s_@@ #4
   {
@@ -1149,7 +1149,7 @@
     \int_gincr:N \g__prg_map_int
     \cs_gset_protected:Npn \@@_pair:wn ##1 \s_@@ ##2 {#2}
     #1
-    \__prg_break_point:Nn \prop_map_break:
+    \prg_break_point:Nn \prop_map_break:
       {
         \int_gdecr:N \g__prg_map_int
         \cs_gset_eq:Nc \@@_pair:wn
@@ -1162,12 +1162,12 @@
 %
 % \begin{macro}[tested = m3prop003]{\prop_map_break:}
 % \begin{macro}[tested = m3prop003]{\prop_map_break:n}
-%   The break statements are based on the general \cs{__prg_map_break:Nn}.
+%   The break statements are based on the general \cs{prg_map_break:Nn}.
 %    \begin{macrocode}
 \cs_new:Npn \prop_map_break:
-  { \__prg_map_break:Nn \prop_map_break: { } }
+  { \prg_map_break:Nn \prop_map_break: { } }
 \cs_new:Npn \prop_map_break:n
-  { \__prg_map_break:Nn \prop_map_break: }
+  { \prg_map_break:Nn \prop_map_break: }
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}

diff --git a/l3kernel/l3seq.dtx b/l3kernel/l3seq.dtx
@@ -1705,14 +1705,14 @@
 % \UnitTested
 % \begin{macro}{\seq_map_break:n}
 % \UnitTested
-%   To break a function, the special token \cs{__prg_break_point:Nn} is
+%   To break a function, the special token \cs{prg_break_point:Nn} is
 %   used to find the end of the code. Any ending code is then inserted
 %   before the return value of \cs{seq_map_break:n} is inserted.
 %    \begin{macrocode}
 \cs_new:Npn \seq_map_break:
-  { \__prg_map_break:Nn \seq_map_break: { } }
+  { \prg_map_break:Nn \seq_map_break: { } }
 \cs_new:Npn \seq_map_break:n
-  { \__prg_map_break:Nn \seq_map_break: }
+  { \prg_map_break:Nn \seq_map_break: }
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
@@ -1734,7 +1734,7 @@
     \exp_after:wN #2
     #1
     { ? \seq_map_break: } { }
-    \__prg_break_point:Nn \seq_map_break: { }
+    \prg_break_point:Nn \seq_map_break: { }
   }
 \cs_new:Npn \@@_map_function:NNn #1#2#3
   {
@@ -1791,7 +1791,7 @@
   {
     \@@_push_item_def:n {#2}
     #1
-    \__prg_break_point:Nn \seq_map_break: { \@@_pop_item_def: }
+    \prg_break_point:Nn \seq_map_break: { \@@_pop_item_def: }
   }
 \cs_generate_variant:Nn \seq_map_inline:Nn { c }
 %    \end{macrocode}
@@ -1815,7 +1815,7 @@
         \exp_not:n {#3}
       }
     #1
-    \__prg_break_point:Nn \seq_map_break: { \@@_pop_item_def: }
+    \prg_break_point:Nn \seq_map_break: { \@@_pop_item_def: }
   }
 \cs_generate_variant:Nn \seq_map_variable:NNn {     Nc }
 \cs_generate_variant:Nn \seq_map_variable:NNn { c , cc }

diff --git a/l3kernel/l3skip.dtx b/l3kernel/l3skip.dtx
@@ -1611,7 +1611,7 @@
 %   The approach here is to build a function, with a global integer
 %   required to make the nesting safe (as seen in other in line
 %   functions), and map that function using \cs{dim_step_function:nnnN}.
-%   We put a \cs{__prg_break_point:Nn} so that \texttt{map_break}
+%   We put a \cs{prg_break_point:Nn} so that \texttt{map_break}
 %   functions from other modules correctly decrement \cs{g__prg_map_int}
 %   before looking for their own break point.  The first argument is
 %   \cs{scan_stop:}, so that no breaking function recognizes this break
@@ -1640,7 +1640,7 @@
   {
     #1 #2 ##1 {#6}
     \dim_step_function:nnnN {#3} {#4} {#5} #2
-    \__prg_break_point:Nn \scan_stop: { \int_gdecr:N \g__prg_map_int }
+    \prg_break_point:Nn \scan_stop: { \int_gdecr:N \g__prg_map_int }
   }
 %    \end{macrocode}
 % \end{macro}

diff --git a/l3kernel/l3str.dtx b/l3kernel/l3str.dtx
@@ -1329,7 +1329,7 @@
     \exp_after:wN \@@_map_function:Nn \exp_after:wN #2
       \etex_detokenize:D {#1}
       \q_recursion_tail ? ~
-    \__prg_break_point:Nn \str_map_break: { }
+    \prg_break_point:Nn \str_map_break: { }
   }
 \cs_new:Npn \str_map_function:NN
   { \exp_args:No \str_map_function:nN }
@@ -1355,7 +1355,7 @@
         \@@_to_other_fast:n {#1}
       }
       \q_recursion_tail
-    \__prg_break_point:Nn \str_map_break: { \int_gdecr:N \g__prg_map_int }
+    \prg_break_point:Nn \str_map_break: { \int_gdecr:N \g__prg_map_int }
   }
 \cs_new_protected:Npn \str_map_inline:Nn
   { \exp_args:No \str_map_inline:nn }
@@ -1374,7 +1374,7 @@
         \@@_to_other_fast:n {#1}
       }
       \q_recursion_tail
-    \__prg_break_point:Nn \str_map_break: { }
+    \prg_break_point:Nn \str_map_break: { }
   }
 \cs_new_protected:Npn \str_map_variable:NNn
   { \exp_args:No \str_map_variable:nNn }
@@ -1387,9 +1387,9 @@
   }
 \cs_generate_variant:Nn \str_map_variable:NNn { c }
 \cs_new:Npn \str_map_break:
-  { \__prg_map_break:Nn \str_map_break: { } }
+  { \prg_map_break:Nn \str_map_break: { } }
 \cs_new:Npn \str_map_break:n
-  { \__prg_map_break:Nn \str_map_break: }
+  { \prg_map_break:Nn \str_map_break: }
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}

diff --git a/l3kernel/l3tl-analysis.dtx b/l3kernel/l3tl-analysis.dtx
@@ -931,7 +931,7 @@
     \exp_after:wN #1
       \g_@@_result_tl
       \s__tl { ? \tl_map_break: } \s__tl
-    \__prg_break_point:Nn \tl_map_break: { \int_gdecr:N \g__prg_map_int }
+    \prg_break_point:Nn \tl_map_break: { \int_gdecr:N \g__prg_map_int }
   }
 %    \end{macrocode}
 % \end{macro}