summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/expl3/l3prg.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/expl3/l3prg.dtx')
-rw-r--r--Master/texmf-dist/source/latex/expl3/l3prg.dtx230
1 files changed, 92 insertions, 138 deletions
diff --git a/Master/texmf-dist/source/latex/expl3/l3prg.dtx b/Master/texmf-dist/source/latex/expl3/l3prg.dtx
index a48517c6f12..ad629cd6450 100644
--- a/Master/texmf-dist/source/latex/expl3/l3prg.dtx
+++ b/Master/texmf-dist/source/latex/expl3/l3prg.dtx
@@ -36,7 +36,7 @@
\RequirePackage{l3names}
%</driver|package>
%\fi
-\GetIdInfo$Id: l3prg.dtx 2121 2011-01-07 08:46:09Z joseph $
+\GetIdInfo$Id: l3prg.dtx 2178 2011-03-06 09:03:44Z mittelba $
{L3 Experimental control structures}
%\iffalse
%<*driver>
@@ -223,13 +223,8 @@
% Set <bool1> equal to the value of <bool2>.
% \end{function}
%
-% \begin{function}{%
-% \bool_if_p:N / (EXP) |
-% \bool_if:N / (TF)(EXP) |
-% \bool_if_p:c / (EXP) |
-% \bool_if:c / (TF)(EXP) |
-%
-% }
+% \begin{function}{ \bool_if:N / (pTF) |
+% \bool_if:c / (pTF) }
% \begin{syntax}
% "\bool_if:NTF" <bool> \Arg{true} \Arg{false} \\
% "\bool_if_p:N" <bool>
@@ -289,10 +284,7 @@
% be changed anymore, the remainding tests within the current group
% are skipped.
%
-% \begin{function}{%
-% \bool_if_p:n / (EXP) |
-% \bool_if:n / (TF)(EXP) |
-% }
+% \begin{function}{ \bool_if:n / (pTF) }
% \begin{syntax}
% "\bool_if:nTF" \Arg{boolean expression} \Arg{true}
% \Arg{false}
@@ -444,8 +436,7 @@
%
% \section{Choosing modes}
%
-% \begin{function}{ \mode_if_vertical_p: / (EXP)|
-% \mode_if_vertical: / (TF)(EXP) }
+% \begin{function}{ \mode_if_vertical: / (pTF) }
% \begin{syntax}
% "\mode_if_vertical:TF" \Arg{true code} \Arg{false code}
% \end{syntax}
@@ -453,8 +444,7 @@
% <true code> or <false code> accordingly.
% \end{function}
%
-% \begin{function}{ \mode_if_horizontal_p: / (EXP)|
-% \mode_if_horizontal: / (TF)(EXP) }
+% \begin{function}{ \mode_if_horizontal: / (pTF) }
% \begin{syntax}
% "\mode_if_horizontal:TF" \Arg{true code} \Arg{false code}
% \end{syntax}
@@ -463,9 +453,7 @@
% \end{function}
%
%
-% \begin{function}{
-% \mode_if_inner_p: / (EXP)|
-% \mode_if_inner: / (TF)(EXP) }
+% \begin{function}{ \mode_if_inner: / (pTF) }
% \begin{syntax}
% "\mode_if_inner:TF" \Arg{true code} \Arg{false code}
% \end{syntax}
@@ -473,9 +461,7 @@
% <true code> or <false code> accordingly.
% \end{function}
%
-% \begin{function}{
-% \mode_if_math_p: /(EXP) |
-% \mode_if_math: / (TF)(EXP) }
+% \begin{function}{ \mode_if_math: / (pTF) }
% \begin{syntax}
% "\mode_if_math:TF" \Arg{true code} \Arg{false code}
% \end{syntax}
@@ -672,6 +658,8 @@
%
% \section{\pkg{l3prg} implementation}
%
+% \TestFiles{m3prg001.lvt,m3prg002.lvt,m3prg003.lvt}
+%
% \subsection{Variables}
%
% \begin{function}{ \l_tmpa_bool | \g_tmpa_bool }
@@ -695,7 +683,9 @@
% \end{macrocode}
%
% \begin{macro}{\prg_return_true:}
+% \TestMissing{This function is implicitly tested with all other conditionals!}
% \begin{macro}{\prg_return_false:}
+% \TestMissing{This function is also implicitly tested with all other conditionals!}
% \begin{macro}{
% \prg_set_conditional:Npnn,
% \prg_new_conditional:Npnn,
@@ -720,10 +710,11 @@
% \end{macro}
% \end{macro}
%
+% \newpage ^^A because the previous macro margin block is really big!
% \subsection{Choosing modes}
%
-% \begin{macro}{\mode_if_vertical_p:}
-% \begin{macro}[TF]{\mode_if_vertical:}
+% \begin{macro}[pTF]{\mode_if_vertical:}
+% \UnitTested
% For testing vertical mode. Strikes me here on the bus with David,
% that as long as we are just talking about returning true and
% false states, we can just use the primitive conditionals for this
@@ -732,54 +723,46 @@
% and clean and use the return statements.
% \begin{macrocode}
\prg_set_conditional:Npnn \mode_if_vertical: {p,TF,T,F}{
- \if_mode_vertical:
- \prg_return_true: \else: \prg_return_false: \fi:
+ \if_mode_vertical: \prg_return_true: \else: \prg_return_false: \fi:
}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\mode_if_horizontal_p:}
-% \begin{macro}[TF]{\mode_if_horizontal:}
+% \begin{macro}[pTF]{\mode_if_horizontal:}
+% \UnitTested
% For testing horizontal mode.
% \begin{macrocode}
\prg_set_conditional:Npnn \mode_if_horizontal: {p,TF,T,F}{
- \if_mode_horizontal:
- \prg_return_true: \else: \prg_return_false: \fi:
+ \if_mode_horizontal: \prg_return_true: \else: \prg_return_false: \fi:
}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\mode_if_inner_p:}
-% \begin{macro}[TF]{\mode_if_inner:}
+% \begin{macro}[pTF]{\mode_if_inner:}
+% \UnitTested
% For testing inner mode.
% \begin{macrocode}
\prg_set_conditional:Npnn \mode_if_inner: {p,TF,T,F}{
- \if_mode_inner:
- \prg_return_true: \else: \prg_return_false: \fi:
+ \if_mode_inner: \prg_return_true: \else: \prg_return_false: \fi:
}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\mode_if_math_p:}
-% \begin{macro}[TF]{\mode_if_math:}
+% \begin{macro}[pTF]{\mode_if_math:}
+% \UnitTested
% For testing math mode. Uses the kern-save |\scan_align_safe_stop:|.
% \begin{macrocode}
\prg_set_conditional:Npnn \mode_if_math: {p,TF,T,F}{
- \scan_align_safe_stop: \if_mode_math:
- \prg_return_true: \else: \prg_return_false: \fi:
+ \scan_align_safe_stop: \if_mode_math:
+ \prg_return_true: \else: \prg_return_false: \fi:
}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
% \paragraph{Alignment safe grouping and scanning}
%
%
-% \begin{macro}{\group_align_safe_begin:}
-% \begin{macro}{\group_align_safe_end:}
+% \begin{macro}{\group_align_safe_begin:,\group_align_safe_end:}
% \TeX's alignment structures present many problems. As Knuth says
% himself in \emph{\TeX : The Program}: ``It's sort of a miracle
% whenever |\halign| or |\valign| work, [\ldots]'' One problem relates
@@ -802,7 +785,6 @@
\cs_new_nopar:Npn \group_align_safe_end: {\if_num:w`{=\c_zero}\fi:}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
%
% \begin{macro}{\scan_align_safe_stop:}
@@ -839,6 +821,7 @@
% \subsection{Producing $n$ copies}
%
% \begin{macro}{\prg_replicate:nn}
+% \UnitTested
% \begin{macro}[aux]{\prg_replicate_aux:N,\prg_replicate_first_aux:N}
% This function uses a cascading csname technique by David Kastrup
% (who else :-)
@@ -883,7 +866,7 @@
}
% \end{macrocode}
% \end{macro}
-% \end{macro}
+%
% Then comes all the functions that do the hard work of inserting all
% the copies.
% \begin{macrocode}
@@ -921,11 +904,13 @@
\cs_new:cpn {prg_replicate_first_8:n}#1{\cs_end: #1#1#1#1#1#1#1#1}
\cs_new:cpn {prg_replicate_first_9:n}#1{\cs_end: #1#1#1#1#1#1#1#1#1}
% \end{macrocode}
+% \end{macro}
%
%
%
%
% \begin{macro}{\prg_stepwise_function:nnnN}
+% \UnitTested
% \begin{macro}[aux]{\prg_stepwise_function_incr:nnnN,
% \prg_stepwise_function_decr:nnnN}
% A stepwise function. Firstly we check the direction of the steps
@@ -962,8 +947,9 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\g_prg_inline_level_int}
% \begin{macro}{\prg_stepwise_inline:nnnn}
+% \UnitTested
+% \begin{variable}{\g_prg_inline_level_int}
% \begin{macro}[aux]{\prg_stepwise_inline_decr:nnnn,
% \prg_stepwise_inline_incr:nnnn}
% This function uses the same approach as for instance
@@ -972,7 +958,6 @@
% carries the newly constructed csname. Must make assignments global
% when we maintain our own stack.
% \begin{macrocode}
-\int_new:N\g_prg_inline_level_int
\cs_new_protected:Npn\prg_stepwise_inline:nnnn #1#2#3#4{
\int_gincr:N \g_prg_inline_level_int
\cs_gset_nopar:cpn{prg_stepwise_inline_\int_use:N\g_prg_inline_level_int :n}##1{#4}
@@ -1001,10 +986,11 @@
}
% \end{macrocode}
% \end{macro}
-% \end{macro}
+% \end{variable}
% \end{macro}
%
% \begin{macro}{\prg_stepwise_variable:nnnNn}
+% \UnitTested
% \begin{macro}[aux]{\prg_stepwise_variable_decr:nnnNn,
% \prg_stepwise_variable_incr:nnnNn}
% Almost the same as above. Just store the value in |#4| and execute
@@ -1044,16 +1030,12 @@
% We only define the |N| versions here as the |c| versions can easily
% be constructed with the expansion module.
%
-% \begin{macro}{\bool_new:N}
-% \begin{macro}{\bool_new:c}
-% \begin{macro}{\bool_set_true:N}
-% \begin{macro}{\bool_set_true:c}
-% \begin{macro}{\bool_set_false:N}
-% \begin{macro}{\bool_set_false:c}
-% \begin{macro}{\bool_gset_true:N}
-% \begin{macro}{\bool_gset_true:c}
-% \begin{macro}{\bool_gset_false:N}
-% \begin{macro}{\bool_gset_false:c}
+% \begin{macro}{\bool_new:N,\bool_new:c,
+% \bool_set_true:N,\bool_set_true:c,
+% \bool_set_false:N,\bool_set_false:c,
+% \bool_gset_true:N,\bool_gset_true:c,
+% \bool_gset_false:N,\bool_gset_false:c}
+% \UnitTested
% Defining and setting a boolean is easy.
% \begin{macrocode}
\cs_new_protected_nopar:Npn \bool_new:N #1 { \cs_new_eq:NN #1 \c_false_bool }
@@ -1068,24 +1050,16 @@
\cs_new_protected_nopar:Npn \bool_gset_false:c #1 { \cs_gset_eq:cN {#1} \c_false_bool }
% \end{macrocode}
% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\bool_set_eq:NN}
-% \begin{macro}{\bool_set_eq:Nc}
-% \begin{macro}{\bool_set_eq:cN}
-% \begin{macro}{\bool_set_eq:cc}
-% \begin{macro}{\bool_gset_eq:NN}
-% \begin{macro}{\bool_gset_eq:Nc}
-% \begin{macro}{\bool_gset_eq:cN}
-% \begin{macro}{\bool_gset_eq:cc}
+% \begin{macro}{\bool_set_eq:NN,
+% \bool_set_eq:Nc,
+% \bool_set_eq:cN,
+% \bool_set_eq:cc,
+% \bool_gset_eq:NN,
+% \bool_gset_eq:Nc,
+% \bool_gset_eq:cN,
+% \bool_gset_eq:cc}
+% \UnitTested
% Setting a boolean to another is also pretty easy.
% \begin{macrocode}
\cs_new_eq:NN \bool_set_eq:NN \cs_set_eq:NN
@@ -1098,26 +1072,17 @@
\cs_new_eq:NN \bool_gset_eq:cc \cs_gset_eq:cc
% \end{macrocode}
% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\l_tmpa_bool}
-% \begin{macro}{\g_tmpa_bool}
+% \begin{variable}{\l_tmpa_bool,\g_tmpa_bool}
% A few booleans just if you need them.
% \begin{macrocode}
\bool_new:N \l_tmpa_bool
\bool_new:N \g_tmpa_bool
% \end{macrocode}
-% \end{macro}
-% \end{macro}
+% \end{variable}
%
-% \begin{macro}{\bool_if_p:N,\bool_if_p:c}
-% \begin{macro}[TF]{\bool_if:N,\bool_if:c}
+% \begin{macro}[pTF]{\bool_if:N,\bool_if:c}
+% \UnitTested
% Straight forward here. We could optimize here if we wanted to as
% the boolean can just be input directly.
% \begin{macrocode}
@@ -1130,14 +1095,13 @@
\cs_generate_variant:Nn \bool_if:NF {c}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
%
%
-% \begin{macro}{\bool_while_do:Nn}
-% \begin{macro}{\bool_while_do:cn}
-% \begin{macro}{\bool_until_do:Nn}
-% \begin{macro}{\bool_until_do:cn}
+% \begin{macro}{\bool_while_do:Nn,\bool_while_do:cn,
+% \bool_until_do:Nn,\bool_until_do:cn}
+% \UnitTested
+% \UnitTested
% A "while" loop where the boolean is tested before executing the
% statement. The `while' version executes the code as long as the
% boolean is true; the `until' version executes the code as
@@ -1155,15 +1119,12 @@
}
\cs_generate_variant:Nn \bool_until_do:Nn {c}
% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
+% \end{macro}
%
-% \begin{macro}{\bool_do_while:Nn}
-% \begin{macro}{\bool_do_while:cn}
-% \begin{macro}{\bool_do_until:Nn}
-% \begin{macro}{\bool_do_until:cn}
+% \begin{macro}{\bool_do_while:Nn,\bool_do_while:cn,
+% \bool_do_until:Nn,\bool_do_until:cn}
+% \UnitTested
+% \UnitTested
% A "do-while" loop where the body is performed at least once and the
% boolean is tested after executing the body. Otherwise identical to
% the above functions.
@@ -1180,31 +1141,28 @@
}
\cs_generate_variant:Nn \bool_do_until:Nn {c}
% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
+% \end{macro}
%
%
%
% \subsection{Parsing boolean expressions}
%
-% \begin{macro}{\bool_if_p:n}
-% \begin{macro}[TF]{\bool_if:n}
-% \begin{macro}[aux]{\bool_get_next:N, \bool_cleanup:N, \bool_choose:NN}
-% \begin{macro}[aux]{\bool_!:w}
-% \begin{macro}[aux]{\bool_Not:w}
-% \begin{macro}[aux]{\bool_Not:w}
-% \begin{macro}[aux]{\bool_(:w}
-% \begin{macro}[aux]{\bool_p:w}
-% \begin{macro}[aux]{\bool_8_1:w}
-% \begin{macro}[aux]{\bool_I_1:w}
-% \begin{macro}[aux]{\bool_8_0:w}
-% \begin{macro}[aux]{\bool_I_0:w}
-% \begin{macro}[aux]{\bool_)_0:w}
-% \begin{macro}[aux]{\bool_)_1:w}
-% \begin{macro}[aux]{\bool_S_0:w}
-% \begin{macro}[aux]{\bool_S_1:w}
+% \begin{macro}[pTF]{\bool_if:n}
+% \UnitTested
+% \begin{macro}[aux]{\bool_get_next:N, \bool_cleanup:N, \bool_choose:NN,
+% \bool_!:w,
+% \bool_Not:w,
+% \bool_Not:w,
+% \bool_(:w,
+% \bool_p:w,
+% \bool_8_1:w,
+% \bool_I_1:w,
+% \bool_8_0:w,
+% \bool_I_0:w,
+% \bool_)_0:w,
+% \bool_)_1:w,
+% \bool_S_0:w,
+% \bool_S_1:w}
%
% Evaluating the truth value of a list of predicates is done using
% an input syntax somewhat similar to the one found in other
@@ -1441,20 +1399,6 @@
% \end{macrocode}
% \end{macro}
% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
%
% \begin{macro}[aux]{\bool_eval_skip_to_end:Nw,
% \bool_eval_skip_to_end_aux:Nw,\bool_eval_skip_to_end_auxii:Nw}
@@ -1551,6 +1495,7 @@
% \end{macro}
%
% \begin{macro}{\bool_not_p:n}
+% \UnitTested
% The "not" variant just reverses the outcome of |\bool_if_p:n|. Can
% be optimized but this is nice and simple and according to the
% implementation plan. Not even particularly useful to have it when
@@ -1561,6 +1506,7 @@
% \end{macro}
%
% \begin{macro}{\bool_xor_p:nn}
+% \UnitTested
% Exclusive or. If the boolean expressions have same truth value,
% return false, otherwise return true.
% \begin{macrocode}
@@ -1578,8 +1524,9 @@
}
% \end{macrocode}
%
-% \begin{macro}{\bool_while_do:nn,\bool_until_do:nn}
-% \begin{macro}{\bool_do_while:nn,\bool_do_until:nn}
+% \begin{macro}{\bool_while_do:nn,\bool_do_while:nn}
+% \UnitTested
+% \begin{macro}{\bool_until_do:nn,\bool_do_until:nn}
% \begin{arguments}
% \item Predicate test
% \item Code to execute
@@ -1604,6 +1551,7 @@
% \subsection{Case switch}
%
% \begin{macro}{\prg_case_int:nnn}
+% \UnitTested
% \begin{macro}[aux]{\prg_case_int_aux:nnn}
% This case switch is in reality quite simple. It takes three arguments:
% \begin{enumerate}
@@ -1651,6 +1599,7 @@
% \end{macro}
%
% \begin{macro}{\prg_case_dim:nnn}
+% \UnitTested
% \begin{macro}[aux]{\prg_case_dim_aux:nnn}
% Same as |\prg_case_dim:nnn| except it is for \meta{dim} registers.
% \begin{macrocode}
@@ -1669,6 +1618,7 @@
% \end{macro}
%
% \begin{macro}{\prg_case_str:nnn}
+% \UnitTested
% \begin{macro}[aux]{\prg_case_str_aux:nnn}
% Same as |\prg_case_dim:nnn| except it is for strings.
% \begin{macrocode}
@@ -1687,6 +1637,7 @@
% \end{macro}
%
% \begin{macro}{\prg_case_tl:Nnn}
+% \UnitTested
% \begin{macro}[aux]{\prg_case_tl_aux:NNn}
% Same as |\prg_case_dim:nnn| except it is for token list variables.
% \begin{macrocode}
@@ -1835,6 +1786,7 @@
%
%
% \begin{macro}{\prg_quicksort:n}
+% \UnitTested
% A simple version. Sorts a list of tokens, uses the function
% |\prg_quicksort_compare:nnTF| to compare items, and places the
% function |\prg_quicksort_function:n| in front of each of them.
@@ -1844,7 +1796,9 @@
% \end{macro}
%
% \begin{macro}{\prg_quicksort_function:n}
+% \UnitTested
% \begin{macro}{\prg_quicksort_compare:nnTF}
+% \UnitTested
% \begin{macrocode}
\cs_set:Npn \prg_quicksort_function:n {\ERROR}
\cs_set:Npn \prg_quicksort_compare:nnTF {\ERROR}