summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2015-10-14 22:32:58 +0000
committerKarl Berry <karl@freefriends.org>2015-10-14 22:32:58 +0000
commit0346eca0b9378bffafb6b32579dd4542b71b57f5 (patch)
treef9a5b79922bd74de6945c98e47f9b1d3009da982 /Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
parent6028cf981b015fefcf1205f6cba193542627ddbf (diff)
l3 (14oct15)
git-svn-id: svn://tug.org/texlive/trunk@38642 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.dtx111
1 files changed, 27 insertions, 84 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx b/Master/texmf-dist/source/latex/l3kernel/l3prg.dtx
index 9acff26f534..1fc47d225b9 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 5983 2015-09-10 18:57:56Z joseph $
+\GetIdInfo$Id: l3prg.dtx 6208 2015-10-09 20:01:54Z joseph $
{L3 Control structures}
%</driver|package>
%<*driver>
@@ -72,9 +72,7 @@
% performs a series of tests, possibly involving assignments and
% calling other functions that do not read further ahead in the input
% stream. After processing the input, a \emph{state} is returned. The
-% typical states returned are \meta{true} and \meta{false} but other
-% states are possible, say an \meta{error} state for erroneous
-% input, \emph{e.g.}, text as input in a function comparing integers.
+% states returned are \meta{true} and \meta{false}.
%
% \LaTeX3 has two forms of conditional flow processing based
% on these states. The first form is predicate functions that turn the
@@ -87,8 +85,12 @@
% input stream based on the result of the testing as in
% \cs{cs_if_free:NTF} which also takes one argument (the |N|) and then
% executes either \texttt{true} or \texttt{false} depending on the
-% result. Important to note here is that the arguments are executed
-% after exiting the underlying |\if...\fi:| structure.
+% result.
+%
+% \begin{texnote}
+% The arguments are executed after exiting the underlying
+% |\if...\fi:| structure.
+% \end{texnote}
%
% \section{Defining a set of conditional functions}
% \label{sec:l3prg:new-conditional-functions}
@@ -140,7 +142,7 @@
% which will supply either a logical \texttt{true} or logical
% \texttt{false}. This function is intended for use in cases where
% one or more logical tests are combined to lead to a final outcome.
-% This function will not work properly for \texttt{protected}
+% This function cannot be defined for \texttt{protected}
% conditionals.
% \item \cs{\meta{name}:\meta{arg spec}T} --- a function with one more
% argument than the original \meta{arg spec} demands. The \meta{true
@@ -192,7 +194,7 @@
% \begin{syntax}
% \cs{prg_new_eq_conditional:NNn} \cs{\meta{name_1}:\meta{arg spec_1}} \cs{\meta{name_2}:\meta{arg spec_2}} \Arg{conditions}
% \end{syntax}
-% These functions copies a family of conditionals. The \texttt{new} version
+% These functions copy a family of conditionals. The \texttt{new} version
% will check for existing definitions (\emph{cf.}~\cs{cs_new:Npn}) whereas
% the \texttt{set} version will not (\emph{cf.}~\cs{cs_set:Npn}). The
% conditionals copied are depended on the comma-separated list of
@@ -208,7 +210,7 @@
% These `return' functions define the logical state of a conditional statement.
% They appear within the code for a conditional
% function generated by \cs{prg_set_conditional:Npnn}, \emph{etc}, to indicate
-% when a true or false branch has been taken.
+% when a true or false branch should be taken.
% While they may appear multiple times each within the code of such conditionals,
% the execution of the conditional must result in the expansion of one of these
% two functions \emph{exactly once}.
@@ -357,22 +359,23 @@
% of predicate functions and boolean variables, return boolean
% \meta{true} or \meta{false}. It supports the logical operations And,
% Or and Not as the well-known infix operators |&&|, \verb"||" and |!|
-% with their usual precedences. In
+% with their usual precedences (namely, |&&| binds more tightly than
+% \verb"||"). In
% addition to this, parentheses can be used to isolate
% sub-expressions. For example,
% \begin{verbatim}
% \int_compare_p:n { 1 = 1 } &&
% (
% \int_compare_p:n { 2 = 3 } ||
-% \int_compare_p:n { 4 = 4 } ||
-% \int_compare_p:n { 1 = \error } % is skipped
+% \int_compare_p:n { 4 <= 4 } ||
+% \str_if_eq_p:nn { abc } { def }
% ) &&
-% ! ( \int_compare_p:n { 2 = 4 } )
+% ! \int_compare_p:n { 2 = 4 }
% \end{verbatim}
-% is a valid boolean expression. Note that minimal evaluation is
-% carried out whenever possible so that whenever a truth value cannot
-% be changed any more, the remaining tests within the current group
-% are skipped.
+% is a valid boolean expression.
+%
+% At present, the infix operators |&&| and \verb"||" perform lazy
+% evaluation as well, but this will change in a future release.
%
% \begin{function}[EXP, pTF, updated = 2012-07-08]{\bool_if:n}
% \begin{syntax}
@@ -384,45 +387,10 @@
% \meta{boolean expression} should consist of a series of predicates
% or boolean variables with the logical relationship between these
% defined using |&&| (\enquote{And}), \verb"||" (\enquote{Or}),
-% |!| (\enquote{Not}) and parentheses. Minimal evaluation is used
-% in the processing, so that once a result is defined there is
-% not further expansion of the tests. For example
-% \begin{verbatim}
-% \bool_if_p:n
-% {
-% \int_compare_p:nNn { 1 } = { 1 }
-% &&
-% (
-% \int_compare_p:nNn { 2 } = { 3 } ||
-% \int_compare_p:nNn { 4 } = { 4 } ||
-% \int_compare_p:nNn { 1 } = { \error } % is skipped
-% )
-% &&
-% ! \int_compare_p:nNn { 2 } = { 4 }
-% }
-% \end{verbatim}
-% will be \texttt{true} and will not evaluate
-% |\int_compare_p:nNn { 1 } = { \error }|. The logical Not applies to
+% |!| (\enquote{Not}) and parentheses. The logical Not applies to
% the next predicate or group.
% \end{function}
%
-% \begin{function}[EXP, updated = 2012-07-08]{\bool_not_p:n}
-% \begin{syntax}
-% \cs{bool_not_p:n} \Arg{boolean expression}
-% \end{syntax}
-% Function version of |!(|\meta{boolean expression}|)| within a boolean
-% expression.
-% \end{function}
-%
-% \begin{function}[EXP, updated = 2012-07-08]{\bool_xor_p:nn}
-% \begin{syntax}
-% \cs{bool_xor_p:nn} \Arg{boolexpr_1} \Arg{boolexpr_2}
-% \end{syntax}
-% Implements an \enquote{exclusive or} operation between two boolean
-% expressions. There is no infix operation for this logical
-% operator.
-% \end{function}
-%
% \section{Logical loops}
%
% Loops using either boolean expressions or stored boolean values.
@@ -568,17 +536,17 @@
%
% \begin{function}[EXP]{\if_predicate:w}
% \begin{syntax}
-% "\if_predicate:w" <predicate> <true code> "\else:" <false code> "\fi:"
+% \cs{if_predicate:w} \meta{predicate} \meta{true code} \cs{else:} \meta{false code} \cs{fi:}
% \end{syntax}
% This function takes a predicate function and
% branches according to the result. (In practice this function would also
-% accept a single boolean variable in place of the <predicate> but to make the
-% coding clearer this should be done through "\if_bool:N".)
+% accept a single boolean variable in place of the \meta{predicate} but to make the
+% coding clearer this should be done through \cs{if_bool:N}.)
% \end{function}
%
% \begin{function}[EXP]{\if_bool:N}
% \begin{syntax}
-% "\if_bool:N" <boolean> <true code> "\else:" <false code> "\fi:"
+% \cs{if_bool:N} \meta{boolean} \meta{true code} \cs{else:} \meta{false code} \cs{fi:}
% \end{syntax}
% This function takes a boolean variable and
% branches according to the result.
@@ -664,7 +632,7 @@
% \section{\pkg{l3prg} implementation}
%
% \TestFiles{m3prg001.lvt,m3prg002.lvt,m3prg003.lvt}
-%%
+%
% \begin{macrocode}
%<*initex|package>
% \end{macrocode}
@@ -1128,7 +1096,7 @@
% \begin{macro}[aux]+\@@_&_1:w+
% \begin{macro}[aux]+\@@_|_0:w+
% Two cases where we simply continue scanning. We must remove the
-% second "&" or \verb"|".
+% second |&| or \verb"|".
% \begin{macrocode}
\cs_new_nopar:cpn { @@_&_1:w } & { \@@_get_next:NN \use_i:nn }
\cs_new_nopar:cpn { @@_|_0:w } | { \@@_get_next:NN \use_i:nn }
@@ -1237,31 +1205,6 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\bool_not_p:n}
-% \UnitTested
-% The Not variant just reverses the outcome of \cs{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
-% the infix notation is easier to use.
-% \begin{macrocode}
-\cs_new:Npn \bool_not_p:n #1 { \bool_if_p:n { ! ( #1 ) } }
-% \end{macrocode}
-% \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}
-\cs_new:Npn \bool_xor_p:nn #1#2
- {
- \int_compare:nNnTF { \bool_if_p:n {#1} } = { \bool_if_p:n {#2} }
- \c_false_bool
- \c_true_bool
- }
-% \end{macrocode}
-% \end{macro}
-%
% \subsection{Logical loops}
%
% \begin{macro}{\bool_while_do:Nn, \bool_while_do:cn}