From 3cb4e75696df6c7abebf17fbc606ca86dcdfb520 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 6 Sep 2015 23:19:17 +0000 Subject: l3 (6sep15) git-svn-id: svn://tug.org/texlive/trunk@38305 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/source/latex/l3kernel/l3prg.dtx | 223 +++++----------------- 1 file changed, 47 insertions(+), 176 deletions(-) (limited to 'Master/texmf-dist/source/latex/l3kernel/l3prg.dtx') diff --git a/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx b/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx index 278950c0205..d87e58b27af 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx @@ -37,7 +37,7 @@ \documentclass[full]{l3doc} % %<*driver|package> -\GetIdInfo$Id: l3prg.dtx 5722 2015-07-30 12:54:33Z bruno $ +\GetIdInfo$Id: l3prg.dtx 5891 2015-08-25 08:00:59Z mittelba $ {L3 Control structures} % %<*driver> @@ -308,14 +308,14 @@ % based on this result. % \end{function} % -% \begin{function}[added = 2012-02-09]{\bool_show:N, \bool_show:c} +% \begin{function}[added = 2012-02-09, updated = 2015-08-01]{\bool_show:N, \bool_show:c} % \begin{syntax} % \cs{bool_show:N} \meta{boolean} % \end{syntax} % Displays the logical truth of the \meta{boolean} on the terminal. % \end{function} % -% \begin{function}[added = 2012-02-09, updated = 2012-07-08]{\bool_show:n} +% \begin{function}[added = 2012-02-09, updated = 2015-08-07]{\bool_show:n} % \begin{syntax} % \cs{bool_show:n} \Arg{boolean expression} % \end{syntax} @@ -607,40 +607,6 @@ % within the same function. % \end{function} % -% \begin{function}[updated = 2011-09-06]{\scan_align_safe_stop:} -% \begin{syntax} -% \cs{scan_align_safe_stop:} -% \end{syntax} -% 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} -% \begin{syntax} -% \cs{__prg_variable_get_scope:N} \meta{variable} -% \end{syntax} -% Returns the scope (\texttt{g} for global, blank otherwise) for the -% \meta{variable}. -% \end{function} -% -% \begin{function}[EXP]{\__prg_variable_get_type:N} -% \begin{syntax} -% \cs{__prg_variable_get_type:N} \meta{variable} -% \end{syntax} -% Returns the type of \meta{variable} (\texttt{tl}, \texttt{int}, -% \emph{etc.}) -% \end{function} -% % \begin{function}[EXP]{\__prg_break_point:Nn} % \begin{syntax} % \cs{__prg_break_point:Nn} \cs{\meta{type}_map_break:} \meta{tokens} @@ -708,10 +674,9 @@ % \begin{macro}{\if_bool:N} % \begin{macro}{\if_predicate:w} % Those two primitive \TeX{} conditionals are synonyms. -% They should not be used outside the kernel code. % \begin{macrocode} -\tex_let:D \if_bool:N \tex_ifodd:D -\tex_let:D \if_predicate:w \tex_ifodd:D +\cs_new_eq:NN \if_bool:N \tex_ifodd:D +\cs_new_eq:NN \if_predicate:w \tex_ifodd:D % \end{macrocode} % \end{macro} % \end{macro} @@ -809,8 +774,8 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}{\bool_set:Nn,\bool_set:cn} -% \begin{macro}{\bool_gset:Nn,\bool_gset:cn} +% \begin{macro}{\bool_set:Nn, \bool_set:cn} +% \begin{macro}{\bool_gset:Nn, \bool_gset:cn} % This function evaluates a boolean expression and assigns the first % argument the meaning \cs{c_true_bool} or \cs{c_false_bool}. % \begin{macrocode} @@ -828,7 +793,7 @@ % code complements similar material in \pkg{l3tl}. % \begin{macrocode} %<*package> -\tex_ifodd:D \l@expl@check@declarations@bool +\if_bool:N \l@expl@check@declarations@bool \cs_set_protected:Npn \bool_set_true:N #1 { \__chk_if_exist_var:N #1 @@ -869,7 +834,7 @@ \__chk_if_exist_var:N #1 \tex_global:D \tex_chardef:D #1 = \bool_if_p:n {#2} } -\tex_fi:D +\fi: % % \end{macrocode} % @@ -894,31 +859,23 @@ % \end{macro} % % \begin{macro}{\bool_show:N, \bool_show:c, \bool_show:n} +% \begin{macro}[aux]{\@@_to_str:n} % Show the truth value of the boolean, as \texttt{true} or -% \texttt{false}. We use \cs{__msg_show_variable:n} to get a better -% output; this function requires its argument to start with |>~|. +% \texttt{false}. % \begin{macrocode} \cs_new_protected:Npn \bool_show:N #1 { - \bool_if_exist:NTF #1 - { - \__msg_show_variable:n - { > \token_to_str:N #1 = \bool_if:NTF #1 { true } { false } } - } - { - \__msg_kernel_error:nnx { kernel } { variable-not-defined } - { \token_to_str:N #1 } - } - } -\cs_new_protected:Npn \bool_show:n #1 - { - \bool_if:nTF {#1} - { \__msg_show_variable:n { > ~ true } } - { \__msg_show_variable:n { > ~ false } } + \__msg_show_variable:NNNnn #1 \bool_if_exist:NTF ? { } + { > ~ \token_to_str:N #1 = \@@_to_str:n {#1} } } +\cs_new_protected_nopar:Npn \bool_show:n + { \__msg_show_wrap:Nn \@@_to_str:n } +\cs_new:Npn \@@_to_str:n #1 + { \bool_if:nTF {#1} { true } { false } } \cs_generate_variant:Nn \bool_show:N { c } % \end{macrocode} % \end{macro} +% \end{macro} % % \begin{variable}{\l_tmpa_bool, \l_tmpb_bool, \g_tmpa_bool, \g_tmpb_bool} % A few booleans just if you need them. @@ -1307,9 +1264,9 @@ % % \subsection{Logical loops} % -% \begin{macro}{\bool_while_do:Nn,\bool_while_do:cn} +% \begin{macro}{\bool_while_do:Nn, \bool_while_do:cn} % \UnitTested -% \begin{macro}{\bool_until_do:Nn,\bool_until_do:cn} +% \begin{macro}{\bool_until_do:Nn, \bool_until_do:cn} % \UnitTested % A |while| loop where the boolean is tested before executing the % statement. The \enquote{while} version executes the code as long as the @@ -1326,9 +1283,9 @@ % \end{macro} % \end{macro} % -% \begin{macro}{\bool_do_while:Nn,\bool_do_while:cn} +% \begin{macro}{\bool_do_while:Nn, \bool_do_while:cn} % \UnitTested -% \begin{macro}{\bool_do_until:Nn,\bool_do_until:cn} +% \begin{macro}{\bool_do_until:Nn, \bool_do_until:cn} % \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 @@ -1435,7 +1392,7 @@ % to avoid the last function to insert say, $100$ copies of the original % argument just to gobble them again we define separate functions to % be inserted first. These functions also close the expansion of -% \cs{__int_to_roman:w}, which ensures that \cs{prg_replicate:nn} only +% \cs{exp:w}, which ensures that \cs{prg_replicate:nn} only % requires two steps of expansion. % % This function has one flaw though: Since it constantly passes down @@ -1445,14 +1402,14 @@ % necessary, it is possible to write \cs{prg_replicate:nn} |{1000}| % |{| \cs{prg_replicate:nn} |{1000}| \Arg{code}~|}|. An % alternative approach is to create a string of |m|'s with -% \cs{__int_to_roman:w} which can be done with just four macros but that +% \cs{exp:w} which can be done with just four macros but that % method has its own problems since it can exhaust the string % pool. Also, it is considerably slower than what we use here so the % few extra csnames are well spent I would say. % \begin{macrocode} \cs_new:Npn \prg_replicate:nn #1 { - \__int_to_roman:w + \exp:w \exp_after:wN \@@_replicate_first:N \__int_value:w \__int_eval:w #1 \__int_eval_end: \cs_end: @@ -1492,19 +1449,19 @@ % \begin{macrocode} \cs_new:cpn { @@_replicate_first_-:n } #1 { - \c_zero + \exp_end: \__msg_kernel_expandable_error:nn { kernel } { negative-replication } } -\cs_new:cpn { @@_replicate_first_0:n } #1 { \c_zero } -\cs_new:cpn { @@_replicate_first_1:n } #1 { \c_zero #1 } -\cs_new:cpn { @@_replicate_first_2:n } #1 { \c_zero #1#1 } -\cs_new:cpn { @@_replicate_first_3:n } #1 { \c_zero #1#1#1 } -\cs_new:cpn { @@_replicate_first_4:n } #1 { \c_zero #1#1#1#1 } -\cs_new:cpn { @@_replicate_first_5:n } #1 { \c_zero #1#1#1#1#1 } -\cs_new:cpn { @@_replicate_first_6:n } #1 { \c_zero #1#1#1#1#1#1 } -\cs_new:cpn { @@_replicate_first_7:n } #1 { \c_zero #1#1#1#1#1#1#1 } -\cs_new:cpn { @@_replicate_first_8:n } #1 { \c_zero #1#1#1#1#1#1#1#1 } -\cs_new:cpn { @@_replicate_first_9:n } #1 { \c_zero #1#1#1#1#1#1#1#1#1 } +\cs_new:cpn { @@_replicate_first_0:n } #1 { \exp_end: } +\cs_new:cpn { @@_replicate_first_1:n } #1 { \exp_end: #1 } +\cs_new:cpn { @@_replicate_first_2:n } #1 { \exp_end: #1#1 } +\cs_new:cpn { @@_replicate_first_3:n } #1 { \exp_end: #1#1#1 } +\cs_new:cpn { @@_replicate_first_4:n } #1 { \exp_end: #1#1#1#1 } +\cs_new:cpn { @@_replicate_first_5:n } #1 { \exp_end: #1#1#1#1#1 } +\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 } % \end{macrocode} % \end{macro} % \end{macro} @@ -1519,7 +1476,7 @@ % 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 -% and gobbling the \cs{c_zero} in the input stream. However this +% and gobbling the \cs{exp_end:} in the input stream. However this % requires knowledge of the implementation so we keep things nice % and clean and use the return statements. % \begin{macrocode} @@ -1549,8 +1506,7 @@ % \begin{macro}[pTF]{\mode_if_math:} % \UnitTested % For testing math mode. At the beginning of an alignment cell, -% the programmer should insert \cs{scan_align_safe_stop:} before -% the test. +% this should be used only inside a non-expandable function. % \begin{macrocode} \prg_new_conditional:Npnn \mode_if_math: { p , T , F , TF } { \if_mode_math: \prg_return_true: \else: \prg_return_false: \fi: } @@ -1587,104 +1543,10 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}[int]{\scan_align_safe_stop:} -% When \TeX{} is in the beginning of an align cell (right after the -% \tn{cr} or |&|) it is in a somewhat strange mode as it is looking -% ahead to find an \tn{omit} or \tn{noalign} and hasn't looked at the -% preamble yet. Thus an \tn{ifmmode} test at the start of an array -% cell (where math mode is introduced by the preamble, not in the cell -% itself) will always fail unless we stop \TeX{} from scanning ahead. -% With \eTeX{}'s first version, this required inserting -% \cs{scan_stop:}, but not in all cases (see below). This is no -% longer needed with a newer \eTeX{}, since protected macros are not -% expanded anymore at the beginning of an alignment cell. We can thus -% use an empty protected macro to stop \TeX{}. -% \begin{macrocode} -\cs_new_protected_nopar:Npn \scan_align_safe_stop: { } -% \end{macrocode} -% Let us now explain the earlier version. We don't want to insert -% a \cs{scan_stop:} every time as that will -% destroy kerning between letters\footnote{Unless we enforce an extra -% 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 \cs{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. 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. -% \end{macro} -% % \begin{macrocode} %<@@=prg> % \end{macrocode} % -% \begin{macro}[int]{\@@_variable_get_scope:N} -% \begin{macro}[aux]{\@@_variable_get_scope:w} -% \begin{macro}[int]{\@@_variable_get_type:N} -% \begin{macro}[aux]{\@@_variable_get_type:w} -% Expandable functions to find the type of a variable, and to -% return \texttt{g} if the variable is global. The trick for -% \cs{@@_variable_get_scope:N} is the same as that in -% \cs{__cs_split_function:NN}, but it can be simplified as the -% requirements here are less complex. -% \begin{macrocode} -\group_begin: - \tex_lccode:D `* = `g \scan_stop: - \tex_catcode:D `* = \c_twelve -\tl_to_lowercase:n - { - \group_end: - \cs_new:Npn \@@_variable_get_scope:N #1 - { - \exp_after:wN \exp_after:wN - \exp_after:wN \@@_variable_get_scope:w - \cs_to_str:N #1 \exp_stop_f: \q_stop - } - \cs_new:Npn \@@_variable_get_scope:w #1#2 \q_stop - { \token_if_eq_meaning:NNT * #1 { g } } - } -\group_begin: - \tex_lccode:D `* = `_ \scan_stop: - \tex_catcode:D `* = \c_twelve -\tl_to_lowercase:n - { - \group_end: - \cs_new:Npn \@@_variable_get_type:N #1 - { - \exp_after:wN \@@_variable_get_type:w - \token_to_str:N #1 * a \q_stop - } - \cs_new:Npn \@@_variable_get_type:w #1 * #2#3 \q_stop - { - \token_if_eq_meaning:NNTF a #2 - {#1} - { \@@_variable_get_type:w #2#3 \q_stop } - } - } -% \end{macrocode} -% \end{macro} -% \end{macro} -% \end{macro} -% \end{macro} -% % \begin{variable}{\g_@@_map_int} % A nesting counter for mapping. % \begin{macrocode} @@ -1706,6 +1568,15 @@ % \end{macro} % \end{macro} % +% \subsection{Deprecated functions} +% +% \begin{macro}[int]{\scan_align_safe_stop:} +% Deprecated 2015-08-01 for removal after 2016-12-31. +% \begin{macrocode} +\cs_new_protected_nopar:Npn \scan_align_safe_stop: { } +% \end{macrocode} +% \end{macro} +% % \begin{macrocode} % % \end{macrocode} -- cgit v1.2.3