diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3prg.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3prg.dtx | 168 |
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} |