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