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