summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3prg.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3prg.dtx168
1 files changed, 110 insertions, 58 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx b/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
index 73a8774db53..74accffcc5c 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
@@ -41,7 +41,7 @@
% }^^A
% }
%
-% \date{Released 2018/03/05}
+% \date{Released 2018-04-30}
%
% \maketitle
%
@@ -654,79 +654,89 @@
% branches according to the result.
% \end{function}
%
-% \section{Internal programming functions}
+% \section{Nestable recursions and mappings}
%
-% \begin{function}[updated = 2011-08-11, EXP]
-% {\group_align_safe_begin:, \group_align_safe_end:}
-% \begin{syntax}
-% \cs{group_align_safe_begin:}
-% \ldots
-% \cs{group_align_safe_end:}
-% \end{syntax}
-% These functions are used to enclose material in a \TeX{} alignment
-% environment within a specially-constructed group. This group is
-% designed in such a way that it does not add brace groups to the
-% output but does act as a group for the |&| token inside
-% \tn{halign}. This is necessary to allow grabbing of tokens
-% for testing purposes, as \TeX{} uses group level to determine the
-% effect of alignment tokens. Without the special grouping, the use of
-% a function such as \cs{peek_after:Nw} would result in a forbidden
-% comparison of the internal \tn{endtemplate} token, yielding a
-% fatal error. Each \cs{group_align_safe_begin:} must be matched by a
-% \cs{group_align_safe_end:}, although this does not have to occur
-% within the same function.
-% \end{function}
+% 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]{\__prg_break_point:Nn}
+% \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}
+% \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
+% \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]{\__prg_map_break:Nn}
+% \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}
+% \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}
+% \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}.
+% code}, until reaching a loop with the same \meta{type} as its
+% first argument. This \cs[no-index]{\meta{type}_map_break:} argument
+% must be defined; it is simply used as a recognizable marker for the \meta{type}.
+%
+% For types with mappings defined in the kernel,
+% \cs[no-index]{\meta{type}_map_break:} and \cs[no-index]{\meta{type}_map_break:n}
+% are defined as \cs{prg_map_break:Nn} \cs[no-index]{\meta{type}_map_break:} |{}|
+% and the same with |{}| omitted.
% \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},
-% \cs{__prg_map_2:w}, \emph{etc.}, labelled by \cs{g__prg_map_int}
-% hold functions to be mapped over various list datatypes in inline
-% and variable mappings.
-% \end{variable}
+% \subsection{Simple mappings}
+%
+% In addition to the more complex mappings above, non-nestable mappings are
+% used in a number of locations and support is provided for these.
%
-% \begin{function}[EXP]{\__prg_break_point:}
+% \begin{function}[EXP, added = 2018-03-27]{\prg_break_point:}
% This copy of \cs{prg_do_nothing:} is used to mark the end of a fast
-% short-term recursion: the function \cs{__prg_break:n} uses this to
+% short-term recursion: the function \cs{prg_break:n} uses this to
% break out of the loop.
% \end{function}
%
-% \begin{function}[EXP]{\__prg_break:, \__prg_break:n}
+% \begin{function}[EXP, added = 2018-03-27]{\prg_break:, \prg_break:n}
% \begin{syntax}
-% \cs{__prg_break:n} \Arg{code} \ldots{} \cs{__prg_break_point:}
+% \cs{prg_break:n} \Arg{code} \ldots{} \cs{prg_break_point:}
% \end{syntax}
% Breaks a recursion which has no \meta{ending code} and which is not
% a user-breakable mapping (see for instance \cs{prop_get:Nn}), and
% inserts the \meta{code} in the input stream.
% \end{function}
%
+% \section{Internal programming functions}
+%
+% \begin{function}[updated = 2011-08-11, EXP]
+% {\group_align_safe_begin:, \group_align_safe_end:}
+% \begin{syntax}
+% \cs{group_align_safe_begin:}
+% \ldots
+% \cs{group_align_safe_end:}
+% \end{syntax}
+% These functions are used to enclose material in a \TeX{} alignment
+% environment within a specially-constructed group. This group is
+% designed in such a way that it does not add brace groups to the
+% output but does act as a group for the |&| token inside
+% \tn{halign}. This is necessary to allow grabbing of tokens
+% for testing purposes, as \TeX{} uses group level to determine the
+% effect of alignment tokens. Without the special grouping, the use of
+% a function such as \cs{peek_after:Nw} would result in a forbidden
+% comparison of the internal \tn{endtemplate} token, yielding a
+% fatal error. Each \cs{group_align_safe_begin:} must be matched by a
+% \cs{group_align_safe_end:}, although this does not have to occur
+% within the same function.
+% \end{function}
+%
% \end{documentation}
%
% \begin{implementation}
@@ -909,7 +919,7 @@
\cs_generate_variant:Nn \bool_log:N { c }
\cs_new_protected:Npn \@@_show:NN #1#2
{
- \__kernel_check_defined:NT #2
+ \__kernel_chk_defined:NT #2
{ \exp_args:Nx #1 { \token_to_str:N #2 = \@@_to_str:n {#2} } }
}
% \end{macrocode}
@@ -1068,19 +1078,19 @@
\cs_new:cpn { @@_(:Nw } #1#2
{
\exp_after:wN \@@_choose:NNN \exp_after:wN #1
- \__int_value:w \@@_get_next:NN \use_i:nnnn
+ \int_value:w \@@_get_next:NN \use_i:nnnn
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_p:Nw}
% If what follows GetNext is neither |!| nor |(|, evaluate the
-% predicate using the primitive \cs{__int_value:w}. The canonical
+% predicate using the primitive \cs{int_value:w}. The canonical
% \texttt{true} and \texttt{false} values have numerical values $1$
% and $0$ respectively. Look for And, Or or Close afterwards.
% \begin{macrocode}
\cs_new:cpn { @@_p:Nw } #1
- { \exp_after:wN \@@_choose:NNN \exp_after:wN #1 \__int_value:w }
+ { \exp_after:wN \@@_choose:NNN \exp_after:wN #1 \int_value:w }
% \end{macrocode}
% \end{macro}
%
@@ -1386,7 +1396,7 @@
{
\exp:w
\exp_after:wN \@@_replicate_first:N
- \__int_value:w \__int_eval:n {#1}
+ \int_value:w \int_eval:n {#1}
\cs_end:
}
\cs_new:Npn \@@_replicate:N #1
@@ -1436,7 +1446,8 @@
\cs_new:cpn { @@_replicate_first_6:n } #1 { \exp_end: #1#1#1#1#1#1 }
\cs_new:cpn { @@_replicate_first_7:n } #1 { \exp_end: #1#1#1#1#1#1#1 }
\cs_new:cpn { @@_replicate_first_8:n } #1 { \exp_end: #1#1#1#1#1#1#1#1 }
-\cs_new:cpn { @@_replicate_first_9:n } #1 { \exp_end: #1#1#1#1#1#1#1#1#1 }
+\cs_new:cpn { @@_replicate_first_9:n } #1
+ { \exp_end: #1#1#1#1#1#1#1#1#1 }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -1522,27 +1533,68 @@
%<@@=prg>
% \end{macrocode}
%
-% \begin{variable}{\g_@@_map_int}
+% \begin{variable}{\g__kernel_prg_map_int}
% A nesting counter for mapping.
% \begin{macrocode}
-\int_new:N \g_@@_map_int
+\int_new:N \g__kernel_prg_map_int
% \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}
% \end{macro}
%
-% \begin{macro}{\@@_break_point:}
-% \begin{macro}{\@@_break:, \@@_break:n}
+% \begin{macro}{\prg_break_point:}
+% \begin{macro}{\prg_break:, \prg_break:n}
% Also done in \pkg{l3basics} as in format mode these are needed within
% \pkg{l3alloc}.
% \end{macro}
% \end{macro}
%
+% \subsection{Deprecated functions}
+%
+% \begin{macro}[deprecated = 2019-12-31]{\@@_break_point:Nn}
+% \begin{macro}[deprecated = 2019-12-31]{\@@_break_point:}
+% \begin{macro}[deprecated = 2019-12-31]{\@@_map_break:Nn}
+% \begin{macro}[deprecated = 2019-12-31]{\@@_break:}
+% \begin{macro}[deprecated = 2019-12-31]{\@@_break:n}
+% Made public, but used by a few third-parties. It's not possible to
+% perfectly support a mixture of \cs{@@_map_break:Nn} and
+% \cs{prg_map_break:Nn} because they use different delimiters. The
+% following code only breaks if someone tries to break from two
+% \enquote{old-style} \cs{@@_map_break:Nn} \ldots{}
+% \cs{@@_break_point:Nn} mappings in one go. Basically, the
+% \cs{@@_map_break:Nn} converts a single \cs{@@_break_point:Nn} to
+% \cs{prg_break_point:Nn}, and that delimiter had better be the right
+% one. Then we call \cs{prg_map_break:Nn} which may end up breaking
+% intermediate looks in the (unbraced) argument |#1|. It is essential
+% to define the |break_point| functions before the corresponding
+% |break| functions: otherwise \cs{debug_on:n} |{deprecation}|
+% \cs{debug_off:n} |{deprecation}| would break when trying to restore
+% the definitions because they would involve deprecated commands whose
+% definition has not yet been restored.
+% \begin{macrocode}
+\__kernel_patch_deprecation:nnNNpn { 2019-12-31 } { \prg_break_point:Nn }
+\cs_new:Npn \@@_break_point:Nn { \prg_break_point:Nn }
+\__kernel_patch_deprecation:nnNNpn { 2019-12-31 } { \prg_break_point: }
+\cs_new:Npn \@@_break_point: { \prg_break_point: }
+\__kernel_patch_deprecation:nnNNpn { 2019-12-31 } { \prg_map_break:Nn }
+\cs_new:Npn \@@_map_break:Nn #1 \@@_break_point:Nn
+ { \prg_map_break:Nn #1 \prg_break_point:Nn }
+\__kernel_patch_deprecation:nnNNpn { 2019-12-31 } { \prg_break: }
+\cs_new:Npn \@@_break: #1 \@@_break_point: { }
+\__kernel_patch_deprecation:nnNNpn { 2019-12-31 } { \prg_break:n }
+\cs_new:Npn \@@_break:n #1#2 \@@_break_point: {#1}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
% \begin{macrocode}
%</initex|package>
% \end{macrocode}