summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3prg.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3prg.dtx149
1 files changed, 54 insertions, 95 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx b/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
index b74c712d0a4..b54376773d6 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
@@ -41,7 +41,7 @@
% }^^A
% }
%
-% \date{Released 2017/05/29}
+% \date{Released 2017/07/15}
%
% \maketitle
%
@@ -85,7 +85,7 @@
% \end{syntax}
% These functions create a family of conditionals using the same
% \Arg{code} to perform the test created. Those conditionals are
-% expandable if \meta{code} is. The \texttt{new} versions will check
+% expandable if \meta{code} is. The \texttt{new} versions check
% for existing definitions and perform assignments globally
% (\emph{cf.}~\cs{cs_new:Npn}) whereas the \texttt{set} versions do no
% check and perform assignments locally (\emph{cf.}~\cs{cs_set:Npn}).
@@ -105,9 +105,9 @@
% \end{syntax}
% These functions create a family of protected conditionals using the
% same \Arg{code} to perform the test created. The \meta{code} does
-% not need to be expandable. The \texttt{new} version will check for
+% not need to be expandable. The \texttt{new} version check for
% existing definitions and perform assignments globally
-% (\emph{cf.}~\cs{cs_new:Npn}) whereas the \texttt{set} version will
+% (\emph{cf.}~\cs{cs_new:Npn}) whereas the \texttt{set} version do
% 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} (not
@@ -174,8 +174,8 @@
% \cs{prg_new_eq_conditional:NNn} \cs[no-index]{\meta{name_1}:\meta{arg spec_1}} \cs[no-index]{\meta{name_2}:\meta{arg spec_2}} \Arg{conditions}
% \end{syntax}
% These functions copy a family of conditionals. The \texttt{new} version
-% will check for existing definitions (\emph{cf.}~\cs{cs_new_eq:NN}) whereas
-% the \texttt{set} version will not (\emph{cf.}~\cs{cs_set_eq:NN}). The
+% checks for existing definitions (\emph{cf.}~\cs{cs_new_eq:NN}) whereas
+% the \texttt{set} version does not (\emph{cf.}~\cs{cs_set_eq:NN}). The
% conditionals copied are depended on the comma-separated list of
% \meta{conditions}, which should be one or more of \texttt{p}, \texttt{T},
% \texttt{F} and \texttt{TF}.
@@ -217,8 +217,8 @@
% both the boolean type and predicate functions.
%
% All conditional |\bool_| functions except assignments are expandable
-% and expect the input to also be fully expandable (which will generally
-% mean being constructed from predicate functions, possibly nested).
+% and expect the input to also be fully expandable (which generally
+% means being constructed from predicate functions and booleans, possibly nested).
%
% \begin{texnote}
% The \texttt{bool} data type is not implemented using the
@@ -234,7 +234,7 @@
% \end{syntax}
% Creates a new \meta{boolean} or raises an error if the
% name is already taken. The declaration is global. The
-% \meta{boolean} will initially be \texttt{false}.
+% \meta{boolean} is initially \texttt{false}.
% \end{function}
%
% \begin{function}
@@ -429,7 +429,7 @@
% \texttt{true} and \texttt{false} if any of them is \texttt{false}.
% Contrarily to the infix operator |&&|, only the \meta{boolean
% expressions} which are needed to determine the result of
-% \cs{bool_lazy_all:nTF} will be evaluated. See also \cs{bool_lazy_and:nnTF}
+% \cs{bool_lazy_all:nTF} are evaluated. See also \cs{bool_lazy_and:nnTF}
% when there are only two \meta{boolean expressions}.
% \end{function}
%
@@ -440,8 +440,8 @@
% \end{syntax}
% Implements the \enquote{And} operation between two boolean
% expressions, hence is \texttt{true} if both are \texttt{true}.
-% Contrarily to the infix operator |&&|, the \meta{boolexpr_2} will
-% only be evaluated if it is needed to determine the result of
+% Contrarily to the infix operator |&&|, the \meta{boolexpr_2} is only
+% evaluated if it is needed to determine the result of
% \cs{bool_lazy_and:nnTF}. See also \cs{bool_lazy_all:nTF} when there are more
% than two \meta{boolean expressions}.
% \end{function}
@@ -456,7 +456,7 @@
% \texttt{true} and \texttt{false} if all of them are \texttt{false}.
% Contrarily to the infix operator \verb"||", only the \meta{boolean
% expressions} which are needed to determine the result of
-% \cs{bool_lazy_any:nTF} will be evaluated. See also \cs{bool_lazy_or:nnTF}
+% \cs{bool_lazy_any:nTF} are evaluated. See also \cs{bool_lazy_or:nnTF}
% when there are only two \meta{boolean expressions}.
% \end{function}
%
@@ -468,7 +468,7 @@
% Implements the \enquote{Or} operation between two boolean
% expressions, hence is \texttt{true} if either one is \texttt{true}.
% Contrarily to the infix operator \verb"||", the \meta{boolexpr_2}
-% will only be evaluated if it is needed to determine the result of
+% is only evaluated if it is needed to determine the result of
% \cs{bool_lazy_or:nnTF}. See also \cs{bool_lazy_any:nTF} when there are more
% than two \meta{boolean expressions}.
% \end{function}
@@ -500,8 +500,8 @@
% \end{syntax}
% Places the \meta{code} in the input stream for \TeX{} to process,
% and then checks the logical value of the \meta{boolean}. If it is
-% \texttt{false} then the \meta{code} will be inserted into the input
-% stream again and the process will loop until the \meta{boolean} is
+% \texttt{false} then the \meta{code} is inserted into the input
+% stream again and the process loops until the \meta{boolean} is
% \texttt{true}.
% \end{function}
%
@@ -511,8 +511,8 @@
% \end{syntax}
% Places the \meta{code} in the input stream for \TeX{} to process,
% and then checks the logical value of the \meta{boolean}. If it is
-% \texttt{true} then the \meta{code} will be inserted into the input
-% stream again and the process will loop until the \meta{boolean} is
+% \texttt{true} then the \meta{code} is inserted into the input
+% stream again and the process loops until the \meta{boolean} is
% \texttt{false}.
% \end{function}
%
@@ -523,7 +523,7 @@
% This function firsts checks the logical value of the \meta{boolean}.
% If it is \texttt{false} the \meta{code} is placed in the input stream
% and expanded. After the completion of the \meta{code} the truth
-% of the \meta{boolean} is re-evaluated. The process will then loop
+% of the \meta{boolean} is re-evaluated. The process then loops
% until the \meta{boolean} is \texttt{true}.
% \end{function}
%
@@ -534,7 +534,7 @@
% This function firsts checks the logical value of the \meta{boolean}.
% If it is \texttt{true} the \meta{code} is placed in the input stream
% and expanded. After the completion of the \meta{code} the truth
-% of the \meta{boolean} is re-evaluated. The process will then loop
+% of the \meta{boolean} is re-evaluated. The process then loops
% until the \meta{boolean} is \texttt{false}.
% \end{function}
%
@@ -545,8 +545,8 @@
% Places the \meta{code} in the input stream for \TeX{} to process,
% and then checks the logical value of the \meta{boolean expression}
% as described for \cs{bool_if:nTF}. If it is \texttt{false} then the
-% \meta{code} will be inserted into the input stream again and the
-% process will loop until the \meta{boolean expression} evaluates to
+% \meta{code} is inserted into the input stream again and the
+% process loops until the \meta{boolean expression} evaluates to
% \texttt{true}.
% \end{function}
%
@@ -557,8 +557,8 @@
% Places the \meta{code} in the input stream for \TeX{} to process,
% and then checks the logical value of the \meta{boolean expression}
% as described for \cs{bool_if:nTF}. If it is \texttt{true} then the
-% \meta{code} will be inserted into the input stream again and the
-% process will loop until the \meta{boolean expression} evaluates to
+% \meta{code} is inserted into the input stream again and the
+% process loops until the \meta{boolean expression} evaluates to
% \texttt{false}.
% \end{function}
%
@@ -570,8 +570,8 @@
% \meta{boolean expression} (as described for \cs{bool_if:nTF}).
% If it is \texttt{false} the \meta{code} is placed in the input stream
% and expanded. After the completion of the \meta{code} the truth
-% of the \meta{boolean expression} is re-evaluated. The process will
-% then loop until the \meta{boolean expression} is \texttt{true}.
+% of the \meta{boolean expression} is re-evaluated. The process
+% then loops until the \meta{boolean expression} is \texttt{true}.
% \end{function}
%
% \begin{function}[rEXP, updated = 2012-07-08]{\bool_while_do:nn}
@@ -582,8 +582,8 @@
% \meta{boolean expression} (as described for \cs{bool_if:nTF}).
% If it is \texttt{true} the \meta{code} is placed in the input stream
% and expanded. After the completion of the \meta{code} the truth
-% of the \meta{boolean expression} is re-evaluated. The process will
-% then loop until the \meta{boolean expression} is \texttt{false}.
+% of the \meta{boolean expression} is re-evaluated. The process
+% then loops until the \meta{boolean expression} is \texttt{false}.
% \end{function}
%
% \section{Producing multiple copies}
@@ -667,7 +667,7 @@
% \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
+% a function such as \cs{peek_after:Nw} would result in a forbidden
% 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
@@ -711,7 +711,7 @@
%
% \begin{function}[EXP]{\__prg_break_point:}
% This copy of \cs{prg_do_nothing:} is used to mark the end of a fast
-% short-term recursions: the function \cs{__prg_break:n} uses this to
+% short-term recursion: the function \cs{__prg_break:n} uses this to
% break out of the loop.
% \end{function}
%
@@ -804,13 +804,20 @@
% }
% \UnitTested
% Setting is already pretty easy.
+% When \texttt{check-declarations} is active, the definitions are patched to
+% make sure the boolean exists. This is needed because booleans are
+% not based on token lists nor on \TeX{} registers.
% \begin{macrocode}
+\__debug_patch:nnNw { \__chk_if_exist_var:N #1 } { }
\cs_new_protected:Npn \bool_set_true:N #1
{ \cs_set_eq:NN #1 \c_true_bool }
+\__debug_patch:nnNw { \__chk_if_exist_var:N #1 } { }
\cs_new_protected:Npn \bool_set_false:N #1
{ \cs_set_eq:NN #1 \c_false_bool }
+\__debug_patch:nnNw { \__chk_if_exist_var:N #1 } { }
\cs_new_protected:Npn \bool_gset_true:N #1
{ \cs_gset_eq:NN #1 \c_true_bool }
+\__debug_patch:nnNw { \__chk_if_exist_var:N #1 } { }
\cs_new_protected:Npn \bool_gset_false:N #1
{ \cs_gset_eq:NN #1 \c_false_bool }
\cs_generate_variant:Nn \bool_set_true:N { c }
@@ -828,16 +835,14 @@
% \bool_gset_eq:Nc, \bool_gset_eq:cc
% }
% \UnitTested
-% The usual copy code.
+% The usual copy code. While it would be cleaner semantically to copy
+% the \cs{cs_set_eq:NN} family of functions, we copy \cs{tl_set_eq:NN}
+% because that has the correct checking code.
% \begin{macrocode}
-\cs_new_eq:NN \bool_set_eq:NN \cs_set_eq:NN
-\cs_new_eq:NN \bool_set_eq:Nc \cs_set_eq:Nc
-\cs_new_eq:NN \bool_set_eq:cN \cs_set_eq:cN
-\cs_new_eq:NN \bool_set_eq:cc \cs_set_eq:cc
-\cs_new_eq:NN \bool_gset_eq:NN \cs_gset_eq:NN
-\cs_new_eq:NN \bool_gset_eq:Nc \cs_gset_eq:Nc
-\cs_new_eq:NN \bool_gset_eq:cN \cs_gset_eq:cN
-\cs_new_eq:NN \bool_gset_eq:cc \cs_gset_eq:cc
+\cs_new_eq:NN \bool_set_eq:NN \tl_set_eq:NN
+\cs_new_eq:NN \bool_gset_eq:NN \tl_gset_eq:NN
+\cs_generate_variant:Nn \bool_set_eq:NN { Nc, cN, cc }
+\cs_generate_variant:Nn \bool_gset_eq:NN { Nc, cN, cc }
% \end{macrocode}
% \end{macro}
%
@@ -845,9 +850,12 @@
% \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}.
+% Again, we include some checking code.
% \begin{macrocode}
+\__debug_patch:nnNw { \__chk_if_exist_var:N #1 } { }
\cs_new_protected:Npn \bool_set:Nn #1#2
{ \tex_chardef:D #1 = \bool_if_p:n {#2} }
+\__debug_patch:nnNw { \__chk_if_exist_var:N #1 } { }
\cs_new_protected:Npn \bool_gset:Nn #1#2
{ \tex_global:D \tex_chardef:D #1 = \bool_if_p:n {#2} }
\cs_generate_variant:Nn \bool_set:Nn { c }
@@ -856,55 +864,6 @@
% \end{macro}
% \end{macro}
%
-% Booleans are not based on token lists but do need checking: this
-% code complements similar material in \pkg{l3tl}.
-% \begin{macrocode}
-%<*package>
-\if_bool:N \l@expl@check@declarations@bool
- \cs_set_protected:Npn \bool_set_true:N #1
- {
- \__chk_if_exist_var:N #1
- \cs_set_eq:NN #1 \c_true_bool
- }
- \cs_set_protected:Npn \bool_set_false:N #1
- {
- \__chk_if_exist_var:N #1
- \cs_set_eq:NN #1 \c_false_bool
- }
- \cs_set_protected:Npn \bool_gset_true:N #1
- {
- \__chk_if_exist_var:N #1
- \cs_gset_eq:NN #1 \c_true_bool
- }
- \cs_set_protected:Npn \bool_gset_false:N #1
- {
- \__chk_if_exist_var:N #1
- \cs_gset_eq:NN #1 \c_false_bool
- }
- \cs_set_protected:Npn \bool_set_eq:NN #1
- {
- \__chk_if_exist_var:N #1
- \cs_set_eq:NN #1
- }
- \cs_set_protected:Npn \bool_gset_eq:NN #1
- {
- \__chk_if_exist_var:N #1
- \cs_gset_eq:NN #1
- }
- \cs_set_protected:Npn \bool_set:Nn #1#2
- {
- \__chk_if_exist_var:N #1
- \tex_chardef:D #1 = \bool_if_p:n {#2}
- }
- \cs_set_protected:Npn \bool_gset:Nn #1#2
- {
- \__chk_if_exist_var:N #1
- \tex_global:D \tex_chardef:D #1 = \bool_if_p:n {#2}
- }
-\fi:
-%</package>
-% \end{macrocode}
-%
% \begin{macro}[pTF]{\bool_if:N, \bool_if:c}
% \UnitTested
% Straight forward here. We could optimize here if we wanted to as
@@ -1052,7 +1011,7 @@
% }
% First issue a \cs{group_align_safe_begin:} as we are using |&&|
% as syntax shorthand for the And operation and we need to hide it for
-% \TeX{}. This will be closed at the end of the expression parsing
+% \TeX{}. This is closed at the end of the expression parsing
% (see |S| below).
%
% Minimal (\enquote{short-circuit}) evaluation of boolean expressions
@@ -1061,14 +1020,14 @@
% parenthesis when \meta{false}|&&| is seen. To avoid having separate
% functions for the two cases, we transform the boolean expression by
% doubling each parenthesis and adding parenthesis around each
-% \verb"||". This ensures that |&&| will bind tighter than \verb"||".
+% \verb"||". This ensures that |&&| binds tighter than \verb"||".
%
% The replacement is done in three passes, for left and right
% parentheses and for \verb"||". At each pass, the part of the
% expression that has been transformed is stored before \cs{q_nil},
% the rest lies until the first \cs{q_mark}, followed by an empty
% brace group. A trailing marker ensures that the auxiliaries'
-% delimited arguments will not run-away. As long as the delimiter
+% delimited arguments do not run-away. As long as the delimiter
% matches inside the expression, material is moved before \cs{q_nil}
% and we continue. Afterwards, the trailing marker is taken as a
% delimiter, |#4| is the next auxiliary, immediately followed by a new
@@ -1098,7 +1057,7 @@
%
% \begin{macro}[EXP, aux]{\@@_if_parse:NNNww}
% After removing extra tokens from the transformation phase, start
-% evaluating. At the end, we will need to finish the special
+% evaluating. At the end, we need to finish the special
% \texttt{align_safe} group before finally
% returning a \cs{c_true_bool} or \cs{c_false_bool} as there might
% otherwise be something left in front in the input stream. For this
@@ -1540,7 +1499,7 @@
% requires two steps of expansion.
%
% This function has one flaw though: Since it constantly passes down
-% ten copies of its previous argument it will severely affect the main
+% ten copies of its previous argument it severely affects the main
% memory once you start demanding hundreds of thousands of copies. Now
% I don't think this is a real limitation for any ordinary use, and if
% necessary, it is possible to write \cs{prg_replicate:nn} |{1000}|
@@ -1665,9 +1624,9 @@
% whenever \tn{halign} or \tn{valign} work, [\ldots]} One problem relates
% to commands that internally issues a \tn{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
+% next token happens to be a |&| with category code~4 we get some
% sort of weird error message because the underlying
-% \tn{futurelet} will store the token at the end of the alignment
+% \tn{futurelet} stores 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 \tn{endtemplate}
% token causing even more trouble! To solve this we have to open a