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