summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-09-16 22:35:41 +0000
committerKarl Berry <karl@freefriends.org>2011-09-16 22:35:41 +0000
commit6d95b4a2c1bbdaea1a3802c822808f476ac5703b (patch)
tree1abf9117bf53f2de53fbcc62c352acc92780365b /Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
parentb7f762397f5df2d732326713423e31e1bf91b903 (diff)
l3kernel 2828 (15sep11)
git-svn-id: svn://tug.org/texlive/trunk@23983 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3prg.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3prg.dtx346
1 files changed, 173 insertions, 173 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx b/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
index dfed4100ac0..b57e130efd2 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
@@ -9,7 +9,7 @@
%%
%% http://www.latex-project.org/lppl.txt
%%
-%% This file is part of the "expl3 bundle" (The Work in LPPL)
+%% This file is part of the "l3kernel bundle" (The Work in LPPL)
%% and all files in that bundle must be distributed together.
%%
%% The released version of this bundle is available from CTAN.
@@ -35,7 +35,7 @@
%
%<*driver|package>
\RequirePackage{l3names}
-\GetIdInfo$Id: l3prg.dtx 2720 2011-09-05 08:12:39Z bruno $
+\GetIdInfo$Id: l3prg.dtx 2827 2011-09-15 19:37:32Z joseph $
{L3 Experimental control structures}
%</driver|package>
%<*driver>
@@ -97,34 +97,35 @@
% \prg_new_conditional:Nnn, \prg_set_conditional:Nnn
% }
% \begin{syntax}
-% \cs{prg_set_conditional:Npnn} \cs{\meta{name}:\meta{arg spec}}
-% ~~\meta{parameters} \Arg{conditions} \Arg{code}
-% \cs{prg_set_conditional:Nnn} \cs{\meta{name}:\meta{arg spec}}
-% ~~\Arg{conditions} \Arg{code}
+% \cs{prg_set_conditional:Npnn} \cs{\meta{name}:\meta{arg spec}} \meta{parameters} \Arg{conditions} \Arg{code} \\
+% \cs{prg_set_conditional:Nnn} \cs{\meta{name}:\meta{arg spec}} \Arg{conditions} \Arg{code}
% \end{syntax}
% These functions creates a family of conditionals using the same
% \Arg{code} to perform the test created. The \texttt{new} version will
% check for existing definitions (\emph{cf.}~\cs{cs_new:Npn}) whereas
% the \texttt{set} version will not (\emph{cf.}~\cs{cs_set:Npn}). The
-% conditionals created are depended on the comma-separated list of
+% conditionals created are dependent on the comma-separated list of
% \meta{conditions}, which should be one or more of \texttt{p},
-% \texttt{T}, \texttt{F} and \texttt{TF}. The conditionals are then
-% defined in the obvious way as:
+% \texttt{T}, \texttt{F} and \texttt{TF}.
+% \end{function}
+%
+% The conditionals are defined by \cs{prg_new_conditional:Npnn} and friends
+% as:
% \begin{itemize}
-% \item \cs{\meta{name}_p:\meta{arg spec}}, a predicate function
+% \item \cs{\meta{name}_p:\meta{arg spec}} --- a predicate function
% which will supply either a logical \texttt{true} or
% logical \texttt{false}. This function is intended for use
% in cases where one or more logical tests are combined to
% lead to a final outcome.
-% \item \cs{\meta{name}:\meta{arg spec}T}, a function with one
+% \item \cs{\meta{name}:\meta{arg spec}T} --- a function with one
% more argument than the original \meta{arg spec} demands. The
% \meta{true branch} code in this additional argument will be
% left on the input stream only if the test is \texttt{true}.
-% \item \cs{\meta{name}:\meta{arg spec}F}, a function with one
+% \item \cs{\meta{name}:\meta{arg spec}F} --- a function with one
% more argument than the original \meta{arg spec} demands. The
% \meta{false branch} code in this additional argument will be
% left on the input stream only if the test is \texttt{false}.
-% \item \cs{\meta{name}:\meta{arg spec}TF} , a function with two
+% \item \cs{\meta{name}:\meta{arg spec}TF} --- a function with two
% more argument than the original \meta{arg spec} demands. The
% \meta{true branch} code in the first additional argument will
% be left on the input stream if the test is \texttt{true}, while
@@ -164,7 +165,6 @@
% returning the state. There must be a return statement for each
% branch, failing to do so will result in an error if that branch is
% executed.
-% \end{function}
%
% \begin{function}
% {
@@ -173,8 +173,7 @@
% }
% \begin{syntax}
% \cs{prg_set_protected_conditional:Npnn}
-% ~~\cs{\meta{name}:\meta{arg spec}} \meta{parameters}
-% ~~\meta{conditions} \Arg{code}
+% ~~\cs{\meta{name}:\meta{arg spec}} \meta{parameters} \meta{conditions} \Arg{code} \\
% \cs{prg_set_protected_conditional:Nnn}
% ~~\cs{\meta{name}:\meta{arg spec}} \meta{conditions} \Arg{code}
% \end{syntax}
@@ -184,18 +183,21 @@
% the \texttt{set} version will not (\emph{cf.}~\cs{cs_set:Npn}). The
% conditionals created are depended on the comma-separated list of
% \meta{conditions}, which should be one or more of \texttt{T},
-% \texttt{F} and \texttt{TF}. The conditionals are then defined in the
-% obvious way as:
+% \texttt{F} and \texttt{TF}.
+% \end{function}
+%
+% The conditionals are defined by \cs{prg_new_protected_conditional:Npnn}
+% and friends as:
% \begin{itemize}
-% \item \cs{\meta{name}:\meta{arg spec}T}, a function with one
+% \item \cs{\meta{name}:\meta{arg spec}T} --- a function with one
% more argument than the original \meta{arg spec} demands. The
% \meta{true branch} code in this additional argument will be
% left on the input stream only if the test is \texttt{true}.
-% \item \cs{\meta{name}:\meta{arg spec}F}, a function with one
+% \item \cs{\meta{name}:\meta{arg spec}F} --- a function with one
% more argument than the original \meta{arg spec} demands. The
% \meta{false branch} code in this additional argument will be
% left on the input stream only if the test is \texttt{false}.
-% \item \cs{\meta{name}:\meta{arg spec}TF} , a function with two
+% \item \cs{\meta{name}:\meta{arg spec}TF} --- a function with two
% more argument than the original \meta{arg spec} demands. The
% \meta{true branch} code in the first additional argument will
% be left on the input stream if the test is \texttt{true}, while
@@ -212,23 +214,20 @@
% the test. \cs{prg_set_protected_conditional:Npn} will generate
% a family of protected conditional functions, and so \meta{code}
% does not need to be expandable. All of the functions are created
-% globally.
-%\end{function}
-%
+% globally.%
% \begin{function}{\prg_new_eq_conditional:NN, \prg_set_eq_conditional:NN}
% \begin{syntax}
-% \cs{prg_new_eq_conditional:NN}
-% ~~\cs{\meta{name1}:\meta{arg spec1}} \cs{\meta{name2}:\meta{arg spec2}}
+% \cs{prg_new_eq_conditional:NN} \cs{\meta{name1}:\meta{arg spec1}} \cs{\meta{name2}:\meta{arg spec2}}
% \end{syntax}
% These will set the definitions of the functions
-% \begin{itemize}
+% \begin{itemize}\parskip=0pt
% \item \cs{\meta{name1}_p:\meta{arg spec1}}
% \item \cs{\meta{name1}:\meta{arg spec1}T}
% \item \cs{\meta{name1}:\meta{arg spec1}F}
% \item \cs{\meta{name1}:\meta{arg spec1}TF}
% \end{itemize}
% equal to those for
-% \begin{itemize}
+% \begin{itemize}\parskip=0pt
% \item \cs{\meta{name2}_p:\meta{arg spec2}}
% \item \cs{\meta{name2}:\meta{arg spec2}T}
% \item \cs{\meta{name2}:\meta{arg spec2}F}
@@ -398,8 +397,7 @@
% \begin{function}[EXP,pTF]{\bool_if:n}
% \begin{syntax}
% \cs{bool_if_p:n} \Arg{boolean expression}
-% \cs{bool_if:nTF} \Arg{boolean expression} \Arg{true code}
-% ~~\Arg{false code}
+% \cs{bool_if:nTF} \Arg{boolean expression} \Arg{true code} \Arg{false code}
% \end{syntax}
% Tests the current truth of \meta{boolean expression}, and
% continues expansion based on this result. The
@@ -451,7 +449,7 @@
%
% Loops using either boolean expressions or stored boolean values.
%
-% \begin{function}[EXP]{\bool_until_do:Nn, \bool_until_do:cn}
+% \begin{function}[rEXP]{\bool_until_do:Nn, \bool_until_do:cn}
% \begin{syntax}
% \cs{bool_until_do:Nn} \Arg{boolean} \Arg{code}
% \end{syntax}
@@ -462,7 +460,7 @@
% until the \meta{boolean} is \texttt{true}.
% \end{function}
%
-% \begin{function}[EXP]{\bool_while_do:Nn, \bool_while_do:cn}
+% \begin{function}[rEXP]{\bool_while_do:Nn, \bool_while_do:cn}
% \begin{syntax}
% \cs{bool_while_do:Nn} \Arg{boolean} \Arg{code}
% \end{syntax}
@@ -473,7 +471,7 @@
% until the \meta{boolean} is \texttt{false}.
% \end{function}
%
-% \begin{function}[EXP]{\bool_until_do:nn}
+% \begin{function}[rEXP]{\bool_until_do:nn}
% \begin{syntax}
% \cs{bool_until_do:nn} \Arg{boolean expression} \Arg{code}
% \end{syntax}
@@ -485,7 +483,7 @@
% then loop until the \meta{boolean expression} is \texttt{true}.
% \end{function}
%
-% \begin{function}[EXP]{\bool_while_do:nn}
+% \begin{function}[rEXP]{\bool_while_do:nn}
% \begin{syntax}
% \cs{bool_while_do:nn} \Arg{boolean expression} \Arg{code}
% \end{syntax}
@@ -502,16 +500,15 @@
% For cases where a number of cases need to be considered a family of
% case-selecting functions are available.
%
-% \begin{function}[EXP]{\prg_case_int:nnn}
+% \begin{function}[updated = 2011-07-06, EXP]{\prg_case_int:nnn}
% \begin{syntax}
-% \cs{prg_case_int:nnn}
-% ~~\Arg{test integer expression}
-% ~~|{|
-% ~~~~\Arg{intexpr case1} \Arg{code case1}
-% ~~~~\Arg{intexpr case2} \Arg{code case2}
-% ~~~~\ldots
-% ~~~~\Arg{intexpr case$_n$} \Arg{code case$_n$}
-% ~~|}|
+% \cs{prg_case_int:nnn} \Arg{test integer expression} \\
+% ~~|{| \\
+% ~~~~\Arg{intexpr case1} \Arg{code case1} \\
+% ~~~~\Arg{intexpr case2} \Arg{code case2} \\
+% ~~~~\ldots \\
+% ~~~~\Arg{intexpr case$_n$} \Arg{code case$_n$} \\
+% ~~|}| \\
% ~~\Arg{else case}
% \end{syntax}
% This function evaluates the \meta{test integer expression} and
@@ -519,7 +516,10 @@
% \meta{integer expression cases}. If the two are equal then the
% associated \meta{code} is left in the input stream. If none of
% the tests are \texttt{true} then the \texttt{else code} will be
-% left in the input stream. For example
+% left in the input stream.
+% \end{function}
+%
+% As an example of \cs{prg_case_int:nnn}:
% \begin{verbatim}
% \prg_case_int:nnn
% { 2 * 5 }
@@ -531,18 +531,16 @@
% { No idea! }
% \end{verbatim}
% will leave \enquote{\texttt{Medium}} in the input stream.
-% \end{function}
%
-% \begin{function}[EXP]{\prg_case_dim:nnn}
+% \begin{function}[updated = 2011-07-06, EXP]{\prg_case_dim:nnn}
% \begin{syntax}
-% \cs{prg_case_dim:nnn}
-% ~~\Arg{test dimension expression}
-% ~~|{|
-% ~~~~\Arg{dimexpr case1} \Arg{code case1}
-% ~~~~\Arg{dimexpr case2} \Arg{code case2}
-% ~~~~\ldots
-% ~~~~\Arg{dimexpr case$_n$} \Arg{code case$_n$}
-% ~~|}|
+% \cs{prg_case_dim:nnn} \Arg{test dimension expression} \\
+% ~~|{| \\
+% ~~~~\Arg{dimexpr case1} \Arg{code case1} \\
+% ~~~~\Arg{dimexpr case2} \Arg{code case2} \\
+% ~~~~\ldots \\
+% ~~~~\Arg{dimexpr case$_n$} \Arg{code case$_n$} \\
+% ~~|}| \\
% ~~\Arg{else case}
% \end{syntax}
% This function evaluates the \meta{test dimension expression} and
@@ -553,17 +551,16 @@
% left in the input stream.
% \end{function}
%
-% \begin{function}[EXP]
+% \begin{function}[updated = 2011-08-12, EXP]
% {\prg_case_str:nnn, \prg_case_str:onn, \prg_case_str:xxn}
% \begin{syntax}
-% \cs{prg_case_str:nnn}
-% ~~\Arg{test string}
-% ~~|{|
-% ~~~~\Arg{string case1} \Arg{code case1}
-% ~~~~\Arg{string case2} \Arg{code case2}
-% ~~~~\ldots
-% ~~~~\Arg{string case$_n$} \Arg{code case$_n$}
-% ~~|}|
+% \cs{prg_case_str:nnn} \Arg{test string} \\
+% ~~|{| \\
+% ~~~~\Arg{string case1} \Arg{code case1} \\
+% ~~~~\Arg{string case2} \Arg{code case2} \\
+% ~~~~\ldots \\
+% ~~~~\Arg{string case$_n$} \Arg{code case$_n$} \\
+% ~~|}| \\
% ~~\Arg{else case}
% \end{syntax}
% This function compares the \meta{test string} in turn with each
@@ -575,16 +572,16 @@
% in the same way as the underlying \cs{str_if_eq:xxTF} test.
% \end{function}
%
-% \begin{function}[EXP]{\prg_case_tl:Nnn, \prg_case_tl:cnn}
+% \begin{function}[updated = 2011-07-06, EXP]
+% {\prg_case_tl:Nnn, \prg_case_tl:cnn}
% \begin{syntax}
-% \cs{prg_case_tl:Nnn}
-% ~~\meta{test token list variable}
-% ~~"{"
-% ~~~~\meta{token list variable case1} \Arg{code case1}
-% ~~~~\meta{token list variable case2} \Arg{code case2}
-% ~~~~\ldots
-% ~~~~\meta{token list variable case$_n$} \Arg{code case$_n$}
-% ~~"}"
+% \cs{prg_case_tl:Nnn} \meta{test token list variable} \\
+% ~~"{" \\
+% ~~~~\meta{token list variable case1} \Arg{code case1} \\
+% ~~~~\meta{token list variable case2} \Arg{code case2} \\
+% ~~~~\ldots \\
+% ~~~~\meta{token list variable case$_n$} \Arg{code case$_n$} \\
+% ~~"}" \\
% ~~\Arg{else case}
% \end{syntax}
% This function compares the \meta{test token list variable} in turn
@@ -598,7 +595,7 @@
%
% \section{Producing $n$ copies}
%
-% \begin{function}[EXP]{\prg_replicate:nn}
+% \begin{function}[updated = 2011-07-04, EXP]{\prg_replicate:nn}
% \begin{syntax}
% \cs{prg_replicate:nn} \Arg{integer expression} \Arg{tokens}
% \end{syntax}
@@ -608,10 +605,9 @@
% nesting. It yields its result after two expansion steps.
% \end{function}
%
-% \begin{function}[EXP]{\prg_stepwise_function:nnnN}
+% \begin{function}[updated = 2011-09-06,rEXP]{\prg_stepwise_function:nnnN}
% \begin{syntax}
-% \cs{prg_stepwise_function:nnnN} \Arg{initial value} \Arg{step}
-% ~~\Arg{final value} \meta{function}
+% \cs{prg_stepwise_function:nnnN} \Arg{initial value} \Arg{step} \Arg{final value} \meta{function}
% \end{syntax}
% This function first evaluates the \meta{initial value}, \meta{step}
% and \meta{final value}, all of which should be integer expressions.
@@ -620,23 +616,22 @@
% (using \meta{step} between each \meta{value}). Thus \meta{function}
% should absorb one numerical argument. For example
% \begin{verbatim}
-% \cs_set_nopar:Npn \my_func:n #1 { I~saw~#1 \\ }
+% \cs_set_nopar:Npn \my_func:n #1 { [I~saw~#1] \quad }
% \prg_stepwise_function:nnnN { 1 } { 5 } { 1 } \my_func:n
% \end{verbatim}
% would print
% \begin{quote}
-% I saw 1 \\
-% I saw 2 \\
-% I saw 3 \\
-% I saw 4 \\
-% I saw 5 \\
+% [I saw 1] \quad
+% [I saw 2] \quad
+% [I saw 3] \quad
+% [I saw 4] \quad
+% [I saw 5] \quad
% \end{quote}
% \end{function}
%
-% \begin{function}{\prg_stepwise_inline:nnnn}
+% \begin{function}[updated = 2011-09-06]{\prg_stepwise_inline:nnnn}
% \begin{syntax}
-% \cs{prg_stepwise_inline:nnnn} \Arg{initial value} \Arg{step}
-% ~~\Arg{final value} \Arg{code}
+% \cs{prg_stepwise_inline:nnnn} \Arg{initial value} \Arg{step} \Arg{final value} \Arg{code}
% \end{syntax}
% This function first evaluates the \meta{initial value}, \meta{step}
% and \meta{final value}, all of which should be integer expressions.
@@ -646,10 +641,10 @@
% should define a function of one argument (|#1|).
% \end{function}
%
-% \begin{function}{\prg_stepwise_variable:nnnNn}
+% \begin{function}[updated = 2011-09-06]{\prg_stepwise_variable:nnnNn}
% \begin{syntax}
-% \cs{prg_stepwise_variable:nnnNn} \Arg{initial value} \Arg{step}
-% ~~\Arg{final value} \meta{tl~var} \Arg{code}
+% \cs{prg_stepwise_variable:nnnNn} \\
+% ~~\Arg{initial value} \Arg{step} \Arg{final value} \meta{tl~var} \Arg{code}
% \end{syntax}
% This function first evaluates the \meta{initial value}, \meta{step}
% and \meta{final value}, all of which should be integer expressions.
@@ -676,7 +671,7 @@
% Detects if \TeX{} is currently in inner mode.
% \end{function}
%
-% \begin{function}[EXP,TF]{\mode_if_math:}
+% \begin{function}[updated = 2011-09-05, EXP,pTF]{\mode_if_math:}
% \begin{syntax}
% \cs{mode_if_math:TF} \Arg{true code} \Arg{false code}
% \end{syntax}
@@ -693,7 +688,8 @@
%
% \section{Internal programming functions}
%
-% \begin{function}[EXP]{\group_align_safe_begin:, \group_align_safe_end:}
+% \begin{function}[updated = 2011-08-11, EXP]
+% {\group_align_safe_begin:, \group_align_safe_end:}
% \begin{syntax}
% \cs{group_align_safe_begin:}
% \ldots
@@ -703,22 +699,32 @@
% 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
-% \cs{tex_halign:D}. This is necessary to allow grabbing of tokens
+% \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} will result in a forbidden
-% comparison of the internal \cs{endtemplate} token, yielding a
+% 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}
%
-% \begin{function}{\scan_align_safe_stop:}
+% \begin{function}[updated = 2011-09-06]{\scan_align_safe_stop:}
% \begin{syntax}
% \cs{scan_align_safe_stop:}
% \end{syntax}
-% This function gets \TeX{} on the right track inside an alignment
-% cell but without destroying any kerning.
+% Stops \TeX{}'s scanner looking for expandable control sequences at
+% the beginning of an alignment cell. This function is required, for
+% example, to obtain the expected output when testing \cs{mode_if_math:TF}
+% at the start of a math array cell: placing
+% \cs{scan_align_safe_stop:} before \cs{mode_if_math:TF} will give the
+% correct result. This function does not destroy any kerning if used in
+% other locations, but \emph{does} render functions non-expandable.
+% \begin{texnote}
+% This is a protected version of \cs{prg_do_nothing:}, which therefore
+% stops \TeX{}'s scanner in the circumstances described without producing
+% any affect on the output.
+% \end{texnote}
% \end{function}
%
% \begin{function}[EXP]{\prg_variable_get_scope:N}
@@ -736,7 +742,7 @@
% Returns the type of \meta{variable} (\texttt{tl}, \texttt{int},
% \emph{etc.})
% \end{function}
-%
+%
% \section{Experimental programmings functions}
%
% \begin{function}{\prg_quicksort:n}
@@ -751,7 +757,7 @@
% \end{function}
%
% \begin{function}{
-% \prg_quicksort_function:n |
+% \prg_quicksort_function:n ,
% \prg_quicksort_compare:nnTF
% }
% \begin{syntax}
@@ -762,7 +768,7 @@
% |\prg_quicksort:n|. As an example we could define
% \begin{quote}
% |\cs_set_nopar:Npn\prg_quicksort_function:n #1{{#1}}|\\
-% |\cs_set_nopar:Npn\prg_quicksort_compare:nnTF #1#2#3#4 {\int_compare:nNnTF{#1}>{#2}}|
+% |\cs_set_nopar:Npn\prg_quicksort_compare:nnTF #1#2 {\int_compare:nNnTF{#1}>{#2}}|
% \end{quote}
% Then the function call
% \begin{quote}
@@ -1565,7 +1571,6 @@
\cs_new_nopar:Npn \prg_replicate_first_aux:N #1
{ \cs:w prg_replicate_first_ #1 :n \prg_replicate_aux:N }
% \end{macrocode}
-% \end{macro}
% Then comes all the functions that do the hard work of inserting all
% the copies.
% \begin{macrocode}
@@ -1608,6 +1613,7 @@
% \end{macro}
% \end{macro}
% \end{macro}
+% \end{macro}
%
% \begin{macro}{\prg_stepwise_function:nnnN}
% \begin{macro}[aux]
@@ -1616,12 +1622,16 @@
% of the steps. After that, do the function for the start value
% then step and loop around.
% \begin{macrocode}
-\cs_new:Npn \prg_stepwise_function:nnnN #1#2
+\cs_new:Npn \prg_stepwise_function:nnnN #1#2#3#4
{
- \int_compare:nNnTF {#2} > { 0 }
- { \exp_args:Nf \prg_stepwise_function_incr:nnnN }
- { \exp_args:Nf \prg_stepwise_function_decr:nnnN }
- { \int_eval:n {#1} } {#2}
+ \int_compare:nNnTF {#2} = \c_zero
+ { \msg_expandable_error:n { Zero~step~size~for~stepwise~function. } }
+ {
+ \int_compare:nNnTF {#2} > \c_zero
+ { \exp_args:Nf \prg_stepwise_function_incr:nnnN }
+ { \exp_args:Nf \prg_stepwise_function_decr:nnnN }
+ { \int_eval:n {#1} } {#2} {#3} #4
+ }
}
\cs_new:Npn \prg_stepwise_function_incr:nnnN #1#2#3#4
{
@@ -1634,7 +1644,7 @@
}
\cs_new:Npn \prg_stepwise_function_decr:nnnN #1#2#3#4
{
- \int_compare:nNnF {#1} < {#3}
+ \int_compare:nNnF {#1} < {#3}
{
#4 {#1}
\exp_args:Nf \prg_stepwise_function_decr:nnnN
@@ -1645,67 +1655,48 @@
% \end{macro}
% \end{macro}
%
-%\begin{macro}[aux]{\g_prg_stepwise_level_int}
-% For nesting, the usual approach of using a counter.
+% \begin{macro}[aux]{\g_prg_stepwise_level_int}
+% For nesting, the usual approach of using a counter.
% \begin{macrocode}
\int_new:N \g_prg_stepwise_level_int
% \end{macrocode}
-%\end{macro}
+% \end{macro}
%
-%\begin{macro}{\prg_stepwise_inline:nnnn}
-%\begin{macro}[aux]
-% {\prg_stepwise_inline_incr:Nnnn, \prg_stepwise_inline_decr:Nnnn}
-% The approach here is similar but with a global integer required
-% to make the nesting safe (as seen in other in line functions).
+% \begin{macro}{\prg_stepwise_inline:nnnn}
+% \begin{macro}{\prg_stepwise_variable:nnnNn}
+% \UnitTested
+% \begin{macro}[aux]{\prg_stepwise_aux:NNnnnn}
+% 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{prg_stepwise_function:nnnN}.
% \begin{macrocode}
-\cs_new_protected:Npn \prg_stepwise_inline:nnnn #1#2#3#4
+\cs_new_protected:Npn \prg_stepwise_inline:nnnn
{
- \int_gincr:N \g_prg_stepwise_level_int
- \cs_gset_nopar:cpn
+ \exp_args:NNc \prg_stepwise_aux:NNnnnn
+ \cs_gset_nopar:Npn
{ g_prg_stepwise_ \int_use:N \g_prg_stepwise_level_int :n }
- ##1 {#4}
- \int_compare:nNnTF {#2} > { 0 }
- { \exp_args:Ncf \prg_stepwise_inline_incr:Nnnn }
- { \exp_args:Ncf \prg_stepwise_inline_decr:Nnnn }
- { g_prg_stepwise_ \int_use:N \g_prg_stepwise_level_int :n }
- { \int_eval:n {#1} } {#2} {#3}
- \int_gdecr:N \g_prg_stepwise_level_int
}
-\cs_new_protected:Npn \prg_stepwise_inline_incr:Nnnn #1#2#3#4
+\cs_new_protected:Npn \prg_stepwise_variable:nnnNn #1#2#3#4#5
{
- \int_compare:nNnF {#2} > {#4}
+ \exp_args:NNc \prg_stepwise_aux:NNnnnn
+ \cs_gset_nopar:Npx
+ { g_prg_stepwise_ \int_use:N \g_prg_stepwise_level_int :n }
+ {#1}{#2}{#3}
{
- #1 {#2}
- \exp_args:NNf \prg_stepwise_inline_incr:Nnnn #1
- { \int_eval:n { #2 + #3 } } {#3} {#4}
+ \tl_set:Nn \exp_not:N #4 {##1}
+ \exp_not:n {#5}
}
}
-\cs_new_protected:Npn \prg_stepwise_inline_decr:Nnnn #1#2#3#4
+\cs_new_protected:Npn \prg_stepwise_aux:NNnnnn #1#2#3#4#5#6
{
- \int_compare:nNnF {#2} < {#4}
- {
- #1 {#2}
- \exp_args:NNf \prg_stepwise_inline_decr:Nnnn #1
- { \int_eval:n { #2 + #3 } } {#3} {#4}
- }
+ #1 #2 ##1 {#6}
+ \int_gincr:N \g_prg_stepwise_level_int
+ \prg_stepwise_function:nnnN {#3}{#4}{#5} #2
+ \int_gdecr:N \g_prg_stepwise_level_int
}
% \end{macrocode}
% \end{macro}
% \end{macro}
-%
-% \begin{macro}{\prg_stepwise_variable:nnnNn}
-% \UnitTested
-% A wrapper for the above.
-% \begin{macrocode}
-\cs_new_protected:Npn \prg_stepwise_variable:nnnNn #1#2#3#4#5
- {
- \prg_stepwise_inline:nnnn {#1} {#2} {#3}
- {
- \tl_set:Nn #4 {##1}
- #5
- }
- }
-% \end{macrocode}
% \end{macro}
%
% \subsection{Detecting \TeX{}'s mode}
@@ -1744,14 +1735,12 @@
%
% \begin{macro}[pTF]{\mode_if_math:}
% \UnitTested
-% For testing math mode: without \cs{scan_align_safe_stop:}
-% things go wrong in alignments.
+% For testing math mode. At the beginning of an alignment cell,
+% the programmer should insert \cs{scan_align_safe_stop:} before
+% the test.
% \begin{macrocode}
\prg_new_conditional:Npnn \mode_if_math: { p , T , F , TF }
- {
- \scan_align_safe_stop:
- \if_mode_math: \prg_return_true: \else: \prg_return_false: \fi:
- }
+ { \if_mode_math: \prg_return_true: \else: \prg_return_false: \fi: }
% \end{macrocode}
% \end{macro}
%
@@ -1760,12 +1749,12 @@
% \begin{macro}[int]{\group_align_safe_begin:, \group_align_safe_end:}
% \TeX{}'s alignment structures present many problems. As Knuth says
% himself in \emph{\TeX : The Program}: \enquote{It's sort of a miracle
-% whenever \cs{halign} or \cs{valign} work, [\ldots]} One problem relates
+% whenever \tn{halign} or \tn{valign} work, [\ldots]} One problem relates
% to commands that internally issues a |\cr| but also peek ahead for
% the next character for use in, say, an optional argument. If the
% next token happens to be a |&| with category code~4 we will get some
% sort of weird error message because the underlying
-% |\tex_futurelet:D| will store the token at the end of the alignment
+% \tn{futurelet} will store the token at the end of the alignment
% template. This could be a |&|$_4$ giving a message like
% |! Misplaced \cr.| or even worse: it could be the |\endtemplate|
% token causing even more trouble! To solve this we have to open a
@@ -1788,30 +1777,39 @@
% \begin{macro}[int]{\scan_align_safe_stop:}
% When \TeX{} is in the beginning of an align cell (right after the
% |\cr|) it is in a somewhat strange mode as it is looking ahead to
-% find an |\tex_omit:D| or |\tex_noalign:D| and hasn't looked at the
-% preamble yet. Thus an |\tex_ifmmode:D| test will always fail unless
+% find an \tn{omit} or \tn{noalign} and hasn't looked at the
+% preamble yet. Thus an \tn{ifmmode} test will always fail unless
% we insert |\scan_stop:| to stop \TeX{}'s scanning ahead. On the other
% hand we don't want to insert a |\scan_stop:| every time as that will
% destroy kerning between letters\footnote{Unless we enforce an extra
-% pass with an appropriate value of \cs{pretolerance}.}
+% pass with an appropriate value of \tn{pretolerance}.}
% Unfortunately there is no way to detect if we're in the beginning of
% an alignment cell as they have different characteristics depending
% on column number, \emph{etc.} However we \emph{can} detect if we're in an
% alignment cell by checking the current group type and we can also
% check if the previous node was a character or ligature. What is done
% here is that |\scan_stop:| is only inserted if an only
-% if a)~we're in the
-% outer part of an alignment cell and b)~the last node \emph{wasn't} a
-% char node or a ligature node.
+% if a)~we're in the outer part of an alignment cell and b)~the last node
+% \emph{wasn't} a char node or a ligature node. Thus an older definition
+% here was
+% \begin{verbatim}
+% \cs_new_nopar:Npn \scan_align_safe_stop:
+% {
+% \int_compare:nNnT \etex_currentgrouptype:D = \c_six
+% {
+% \int_compare:nNnF \etex_lastnodetype:D = \c_zero
+% {
+% \int_compare:nNnF \etex_lastnodetype:D = \c_seven
+% { \scan_stop: }
+% }
+% }
+% }
+% \end{verbatim}
+% However, this is not truly expandable, as there are places where the
+% \cs{scan_stop:} ends up in the result. A simpler alternative, which
+% can be used selectively, is therefore defined.
% \begin{macrocode}
-\cs_new_nopar:Npn \scan_align_safe_stop:
- {
- \int_compare:nNnT \etex_currentgrouptype:D = \c_six
- {
- \int_compare:nNnF \etex_lastnodetype:D = \c_zero
- { \int_compare:nNnF \etex_lastnodetype:D = \c_seven { \scan_stop: } }
- }
- }
+\cs_new_protected_nopar:Npn \scan_align_safe_stop: { }
% \end{macrocode}
% \end{macro}
%
@@ -1862,7 +1860,7 @@
% \end{macro}
% \end{macro}
% \end{macro}
-%
+%
% \subsection{Experimental programmings functions}
%
%
@@ -2012,8 +2010,10 @@
% As we have restructured the structured variables, these are no
% longer needed.
% \begin{macrocode}
+%<*deprecated>
\cs_new_protected:Npn \prg_new_map_functions:Nn #1#2 { \deprecated }
\cs_new_protected:Npn \prg_set_map_functions:Nn #1#2 { \deprecated }
+%</deprecated>
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -2024,4 +2024,4 @@
%
% \end{implementation}
%
-% \PrintIndex \ No newline at end of file
+% \PrintIndex