summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2015-09-06 23:19:17 +0000
committerKarl Berry <karl@freefriends.org>2015-09-06 23:19:17 +0000
commit3cb4e75696df6c7abebf17fbc606ca86dcdfb520 (patch)
tree729978e0726cdb9d9f34a3d2e249c71a82e07f97 /Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
parent32f50b97c2ae44e93225d1024afab9727fc02e00 (diff)
l3 (6sep15)
git-svn-id: svn://tug.org/texlive/trunk@38305 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.dtx223
1 files changed, 47 insertions, 176 deletions
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>
%<*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|package>
%<*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:
%</package>
% \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}
%</initex|package>
% \end{macrocode}