diff options
author | Karl Berry <karl@freefriends.org> | 2010-04-10 21:54:22 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2010-04-10 21:54:22 +0000 |
commit | f5059243c2428b73d75e86f6917ce21b28f153df (patch) | |
tree | e35165ec392be3e1abe0e5d4b8e53201ce67360c /Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex | |
parent | bc334ef804891be0815c78c3701442ec292d4493 (diff) |
etoolbox 1.9 (10apr10)
git-svn-id: svn://tug.org/texlive/trunk@17791 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex | 439 |
1 files changed, 362 insertions, 77 deletions
diff --git a/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex b/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex index b433d9ea2e7..93bee323ddc 100644 --- a/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex +++ b/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex @@ -1,4 +1,4 @@ -% $Id: etoolbox.tex,v 1.8 2009/08/06 16:50:04 lehman stable $ +% $Id: etoolbox.tex,v 1.9 2010/04/10 19:11:49 lehman stable $ \documentclass{ltxdockit} \usepackage[latin9]{inputenc} \usepackage[american]{babel} @@ -8,7 +8,7 @@ \MakeAutoQuote*{<}{>} \MakeShortVerb{\|} -\rcsid{$Id: etoolbox.tex,v 1.8 2009/08/06 16:50:04 lehman stable $} +\rcsid{$Id: etoolbox.tex,v 1.9 2010/04/10 19:11:49 lehman stable $} \titlepage{% title={The \sty{etoolbox} package}, @@ -43,7 +43,7 @@ This package requires \etex. \tex distributions have been shipping \etex binarie \subsection{License} -Copyright \textcopyright\ 2007--2009 Philipp Lehman. Permission is granted to copy, distribute and\slash or modify this software under the terms of the \lppl, version 1.3.\fnurl{http://www.ctan.org/tex-archive/macros/latex/base/lppl.txt} This package is author"=maintained. +Copyright \textcopyright\ 2007--2010 Philipp Lehman. Permission is granted to copy, distribute and\slash or modify this software under the terms of the \lppl, version 1.3.\fnurl{http://www.ctan.org/tex-archive/macros/latex/base/lppl.txt} This package is author"=maintained. \subsection{Feedback} @@ -212,19 +212,19 @@ Similar to \cmd{csxdef} except that \latex's protection mechanism is temporarily \cmditem{cslet}{csname}{command} -Similar to the \tex primitive \cmd{let} except that the first argument is a control sequence name. This command is robust and may be prefixed with \cs{global}. +Similar to the \tex primitive \cmd{let} except that the first argument is a control sequence name. If \prm{command} is undefined, \prm{csname} will be undefined as well after the assignment. This command is robust and may be prefixed with \cs{global}. \cmditem{letcs}{command}{csname} -Similar to the \tex primitive \cmd{let} except that the second argument is a control sequence name. This command is robust and may be prefixed with \cs{global}. +Similar to the \tex primitive \cmd{let} except that the second argument is a control sequence name. If \prm{csname} is undefined, the \prm{command} will be undefined as well after the assignment. This command is robust and may be prefixed with \cs{global}. \cmditem{csletcs}{csname}{csname} -Similar to the \tex primitive \cmd{let} except that both arguments are control sequence names. This command is robust and may be prefixed with \cs{global}. +Similar to the \tex primitive \cmd{let} except that both arguments are control sequence names. If the second \prm{csname} is undefined, the first \prm{csname} will be undefined as well after the assignment. This command is robust and may be prefixed with \cs{global}. \cmditem{csuse}{csname} -Takes a control sequence name as its argument and forms a control sequence token. This command differs from the \cmd{@nameuse} macro from the \latex kernel in that it expands to an empty string if the control sequence is undefined. +Takes a control sequence name as its argument and forms a control sequence token. This command differs from the \cmd{@nameuse} macro in the \latex kernel in that it expands to an empty string if the control sequence is undefined. \cmditem{undef}<command> @@ -478,10 +478,107 @@ Enables tracing for all patching commands, including \cmd{ifpatchable}. The debu \end{ltxsyntax} +\subsection{Boolean flags} +\label{aut:bol} + +This package provides two interfaces to boolean flags which are completely independent of each other. The facilities in section \ref{aut:bo1:bol} are a \latex frontend to \cmd{newif}. Those in section \ref{aut:bo1:tgl} use a different mechanism. + +\subsubsection{\tex flags} +\label{aut:bo1:bol} + +Since the facilities in this section are based on \cmd{newif} internally, they may be used to test and alter the state of flags previously defined with \cmd{newif}. They are also compatible with the boolean tests of the \sty{ifthen} package and may serve as a \latex interface for querying \tex primitives such as \cmd{ifmmode}. The \cmd{newif} approach requires a total of three macros per flag. + +\begin{ltxsyntax} + +\cmditem{newbool}{name} + +Defines a new boolean flag called \prm{name}. If the flag has already been defined, this command issues an error. The initial state of newly defined flags is \texttt{false}. This command is robust. + +\cmditem{providebool}{name} + +Defines a new boolean flag called \prm{name} unless it has already been defined. This command is robust. + +\cmditem{booltrue}{name} + +Sets the boolean flag \prm{name} to \texttt{true}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the flag is undefined. + +\cmditem{boolfalse}{name} + +Sets the boolean flag \prm{name} to \texttt{false}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the flag is undefined. + +\cmditem{setbool}{name}{value} + +Sets the boolean flag \prm{name} to \prm{value} which may be either \texttt{true} or \texttt{false}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the flag is undefined. + +\cmditem{ifbool}{name}{true}{false} + +Expands to \prm{true} if the state of the boolean flag \prm{name} is \texttt{true}, and to \prm{false} otherwise. If the flag is undefined, this command issues an error. This command may be used to perform any boolean test based on plain \tex syntax, \ie any test normally employed like this: + +\begin{ltxcode} +<<\iftest>> true<<\else>> false<<\fi>> +\end{ltxcode} + +This includes all flags defined with \cmd{newif} as well as \tex primitives such as \cmd{ifmmode}. The \cmd{if} prefix is omitted when using the flag or the primitive in the expression. For example: + +\begin{ltxcode} +<<\ifmytest>> true\else false\fi +<<\ifmmode>> true\else false\fi +\end{ltxcode} +% +becomes + +\begin{ltxcode} +\ifbool{<<mytest>>}{true}{false} +\ifbool{<<mmode>>}{true}{false} +\end{ltxcode} + +\cmditem{notbool}{name}{not true}{not false} + +Similar to \cmd{ifbool} but negates the test. + +\end{ltxsyntax} + +\subsubsection{\latex flags} +\label{aut:bo1:tgl} + +In contrast to the flags from section \ref{aut:bo1:bol}, the facilities in this section require only one macro per flag. They also use a separate namespace to avoid name clashes with regular macros. + +\begin{ltxsyntax} + +\cmditem{newtoggle}{name} + +Defines a new boolean flag called \prm{name}. If the flag has already been defined, this command issues an error. The initial state of newly defined flags is \texttt{false}. This command is robust. + +\cmditem{providetoggle}{name} + +Defines a new boolean flag called \prm{name} unless it has already been defined. This command is robust. + +\cmditem{toggletrue}{name} + +Sets the boolean flag \prm{name} to \texttt{true}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the flag is undefined. + +\cmditem{togglefalse}{name} + +Sets the boolean flag \prm{name} to \texttt{false}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the flag is undefined. + +\cmditem{settoggle}{name}{value} + +Sets the boolean flag \prm{name} to \prm{value} which may be either \texttt{true} or \texttt{false}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the flag is undefined. + +\cmditem{iftoggle}{name}{true}{false} + +Expands to \prm{true} if the state of the boolean flag \prm{name} is \texttt{true}, and to \prm{false} otherwise. If the flag is undefined, this command issues an error. + +\cmditem{nottoggle}{name}{not true}{not false} + +Similar to \cmd{iftoggle} but negates the test. + +\end{ltxsyntax} + \subsection{Generic tests} \label{aut:tst} -\subsubsection{Control sequence tests} +\subsubsection{Macro tests} \label{aut:tst:def} \begin{ltxsyntax} @@ -600,6 +697,10 @@ Expands to \prm{true} if the \prm{string} is empty, and to \prm{false} otherwise Expands to \prm{true} if the \prm{string} is blank (empty or spaces), and to \prm{false} otherwise. The \prm{string} is not expanded in the test. +\cmditem{notblank}{string}{not true}{not false} + +Similar to \cmd{ifblank} but negates the test. + \end{ltxsyntax} \subsubsection{Arithmetic tests} @@ -607,9 +708,9 @@ Expands to \prm{true} if the \prm{string} is blank (empty or spaces), and to \pr \begin{ltxsyntax} -\cmditem{ifnumcomp}{integer expression}{comparison}{integer expression}{true}{false} +\cmditem{ifnumcomp}{integer expression}{relation}{integer expression}{true}{false} -Compares two integer expressions according to \prm{comparison} and expands to \prm{true} or \prm{false} depending on the result. The \prm{comparison} may be |<|, |>|, or |=|. Both integer expressions will be processed with \cmd{numexpr}. An \prm{integer expression} may be any arbitrary code which is valid in this context. All arithmetic expressions may contain spaces. Here are some examples: +Compares two integer expressions according to \prm{relation} and expands to \prm{true} or \prm{false} depending on the result. The \prm{relation} may be |<|, |>|, or |=|. Both integer expressions will be processed with \cmd{numexpr}. An \prm{integer expression} may be any arbitrary code which is valid in this context. All arithmetic expressions may contain spaces. Here are some examples: \begin{ltxcode} \ifnumcomp{<<3>>}{<<>>>}{<<6>>}{true}{<<false>>} @@ -637,9 +738,13 @@ Alternative syntax for |\ifnumcomp{...}{>}{...}{...}{...}|. Alternative syntax for |\ifnumcomp{...}{<}{...}{...}{...}|. -\cmditem{ifdimcomp}{dimen expression}{comparison}{dimen expression}{true}{false} +\cmditem{ifnumodd}{integer expression}{true}{false} + +Evaluates an integer expression and expands to \prm{true} if the result is an odd number, and to \prm{false} otherwise. Technically, this command is a \latex wrapper for the \tex primitive \cmd{ifodd}, incorporating \cmd{numexpr}. + +\cmditem{ifdimcomp}{dimen expression}{relation}{dimen expression}{true}{false} -Compares two dimen expressions according to \prm{comparison} and expands to \prm{true} or \prm{false} depending on the result. The \prm{comparison} may be |<|, |>|, or |=|. Both dimen expressions will be processed with \cmd{dimexpr}. A \prm{dimen expression} may be any arbitrary code which is valid in this context. All arithmetic expressions may contain spaces. Here are some examples: +Compares two dimen expressions according to \prm{relation} and expands to \prm{true} or \prm{false} depending on the result. The \prm{relation} may be |<|, |>|, or |=|. Both dimen expressions will be processed with \cmd{dimexpr}. A \prm{dimen expression} may be any arbitrary code which is valid in this context. All arithmetic expressions may contain spaces. Here are some examples: \begin{ltxcode} \ifdimcomp{<<1cm>>}{<<=>>}{<<28.45274pt>>}{<<true>>}{false} @@ -673,84 +778,249 @@ Alternative syntax for |\ifdimcomp{...}{<}{...}{...}{...}|. \end{ltxsyntax} -\subsection{Boolean switches} -\label{aut:bol} +\subsubsection{Boolean expressions} +\label{aut:tst:bol} -This package provides two interfaces to boolean switches which are completely independent of each other. The facilities in section \ref{aut:bo1:bol} are a \latex frontend to \cmd{newif}. Those in section \ref{aut:bo1:swi} use a different mechanism. +The commands in this section are replacements for the \cmd{ifthenelse} command provided by the \sty{ifthen} package. They serve the same purpose but differ in syntax, concept, and implementation. In contrast to \cmd{ifthenelse}, they do not provide any tests of their own but serve as a frontend to other tests. Any test which satisfies certain syntactical requirements may be used in a boolean expression. -\subsubsection{\tex switches} -\label{aut:bo1:bol} +\begin{ltxsyntax} -Since the facilities in this section are based on \cmd{newif} internally, they may be used to test and alter the state of switches previously defined with \cmd{newif}. They are also compatible with the boolean tests of the \sty{ifthen} package. The \cmd{newif} approach requires a total of three macros per switch. +\cmditem{ifboolexpr}{expression}{true}{false} -\begin{ltxsyntax} +Evaluates the \prm{expression} and executes \prm{true} if it is true, and \prm{false} otherwise. The \prm{expression} is evaluated sequentially from left to right. The following elements, discussed in more detail below, are available in the \prm{expression}: the test operators \texttt{togl}, \texttt{bool}, \texttt{test}; the logical operators \texttt{not}, \texttt{and}, \texttt{or}; and the subexpression delimiter \texttt{(...)}. Spaces, tabs, and line endings may be used freely to arrange the \prm{expression} visually. Blank lines are not permissible in the \prm{expression}. This command is robust. -\cmditem{newbool}{name} +\cmditem{ifboolexpe}{expression}{true}{false} -Defines a new boolean switch called \prm{name}. If the switch has already been defined, this command issues an error. The initial state of newly defined switches is \texttt{false}. This command is robust. +An expandable version of \cmd{ifboolexpr} which may be processed in an expansion-only context, \eg in an \cmd{edef} or in a \cmd{write} operation. Note that all tests used in the \prm{expression} must be expandable, even if \cmd{ifboolexpe} is not located in an expansion-only context. -\cmditem{providebool}{name} +\cmditem{whileboolexpr}{expression}{code} -Defines a new boolean switch called \prm{name} unless it has already been defined. This command is robust. +Evaluates the \prm{expression} like \cmd{ifboolexpr} and repeatedly executes the \prm{code} while the expression is true. The \prm{code} may be any valid \tex or \latex code. This command is robust. -\cmditem{booltrue}{name} +\cmditem{unlessboolexpr}{expression}{code} -Sets the boolean switch \prm{name} to \texttt{true}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the switch is undefined. +Similar to \cmd{whileboolexpr} but negates the \prm{expression}, \ie it keeps executing the \prm{code} repeatedly unless the expression is true. This command is robust. -\cmditem{boolfalse}{name} +\end{ltxsyntax} +% +The following test operators are available in the \prm{expression}: -Sets the boolean switch \prm{name} to \texttt{false}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the switch is undefined. +\begin{marglist} +\appto\marglistfont{\verbatimfont} -\cmditem{setbool}{name}{value} +\item[togl] -Sets the boolean switch \prm{name} to \prm{value} which may be either \texttt{true} or \texttt{false}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the switch is undefined. +Use the \texttt{togl} operator to test the state of a flag defined with \cmd{newtoggle}. For example: -\cmditem{ifbool}{name}{true}{false} +\begin{ltxcode} +<<\iftoggle{mytoggle}>>{true}{false} +\end{ltxcode} +% +becomes + +\begin{ltxcode} +\ifboolexpr{ <<togl>> {<<mytoggle>>} }{true}{false} +\end{ltxcode} +% +The \texttt{togl} operator may be used with both \cmd{ifboolexpr} and \cmd{ifboolexpe}. -Expands to \prm{true} if the state of the boolean switch \prm{name} is \texttt{true}, and to \prm{false} otherwise. If the switch is undefined, this command issues an error. +\item[bool] -\cmditem{notbool}{name}{not true}{not false} +Use the \texttt{bool} operator to perform a boolean test based on plain \tex syntax, \ie any test normally employed like this: -Similar to \cmd{ifbool} but reverses the logic of the test. +\begin{ltxcode} +<<\iftest>> true<<\else>> false<<\fi>> +\end{ltxcode} +% +This includes all flags defined with \cmd{newif} as well as \tex primitives such as \cmd{ifmmode}. The \cmd{if} prefix is omitted when using the flag or the primitive in the expression. For example: -\end{ltxsyntax} +\begin{ltxcode} +<<\ifmmode>> true\else false\fi +<<\ifmytest>> true\else false\fi +\end{ltxcode} +% +becomes -\subsubsection{\latex switches} -\label{aut:bo1:swi} +\begin{ltxcode} +\ifboolexpr{ <<bool>> {<<mmode>>} }{true}{false} +\ifboolexpr{ <<bool>> {<<mytest>>} }{true}{false} +\end{ltxcode} +% +This also works with flags defined with \cmd{newbool} (see \secref{aut:bo1:bol}). In this case -In contrast to the switches from section \ref{aut:bo1:bol}, the facilities in this section require only one macro per switch. They also use a separate namespace to avoid name clashes with regular macros. +\begin{ltxcode} +<<\ifbool{mybool}>>{true}{false} +\end{ltxcode} +% +becomes -\begin{ltxsyntax} +\begin{ltxcode} +\ifboolexpr{ <<bool>> {<<mybool>>} }{true}{false} +\end{ltxcode} +% +The \texttt{bool} operator may be used with both \cmd{ifboolexpr} and \cmd{ifboolexpe}. -\cmditem{newtoggle}{name} +\item[test] -Defines a new boolean switch called \prm{name}. If the switch has already been defined, this command issues an error. The initial state of newly defined switches is \texttt{false}. This command is robust. +Use the \texttt{test} operator to perform a test based on \latex syntax, \ie any test normally employed like this: -\cmditem{providetoggle}{name} +\begin{ltxcode} +<<\iftest>>{<<true>>}{<<false>>} +\end{ltxcode} +% +This applies to all macros based on \latex syntax, \ie the macro must take a \prm{true} and a \prm{false} argument and these must be the final arguments. For example: -Defines a new boolean switch called \prm{name} unless it has already been defined. This command is robust. +\begin{ltxcode} +<<\ifdef>>{\somemacro}<<{true}{false}>> +<<\ifdimless>>{\textwidth}{365pt}<<{true}{false}>> +<<\ifnumcomp>>{\value{somecounter}}{>}{3}<<{true}{false}>> +\end{ltxcode} -\cmditem{toggletrue}{name} +When using such tests in the \prm{expression}, their \prm{true} and \prm{false} arguments are omitted. For example: -Sets the boolean switch \prm{name} to \texttt{true}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the switch is undefined. +\begin{ltxcode} +<<\ifcsdef{mymacro}>>{true}{false} +\end{ltxcode} +% +becomes -\cmditem{togglefalse}{name} +\begin{ltxcode} +\ifboolexpr{ <<test>> {<<\ifcsdef{mymacro}>>} }{true}{false} +\end{ltxcode} +% +and -Sets the boolean switch \prm{name} to \texttt{false}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the switch is undefined. +\begin{ltxcode} +<<\ifnumcomp{\value{mycounter}}{>}{3}>>{true}{false} +\end{ltxcode} +% +becomes -\cmditem{settoggle}{name}{value} +\begin{ltxcode} +\ifboolexpr{ + <<test>> {<<\ifnumcomp{\value{mycounter}}{>}{3}>>} +} +{true} +{false} +\end{ltxcode} +% +The \texttt{test} operator may be used with \cmd{ifboolexpr} without any restrictions. It may also be used with \cmd{ifboolexpe}, provided that the test is expandable. Some of the generic tests in \secref{aut:tst} are robust and may not be used with \cmd{ifboolexpe}, even if \cmd{ifboolexpe} is not located in an expansion-only context. Use \cmd{ifboolexpr} instead if the test is not expandable. -Sets the boolean switch \prm{name} to \prm{value} which may be either \texttt{true} or \texttt{false}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the switch is undefined. +\end{marglist} -\cmditem{iftoggle}{name}{true}{false} +Since \cmd{ifboolexpr} and \cmd{ifboolexpe} imply processing overhead, there is generally no benefit in employing them for a single test. The stand-alone tests in \secref{aut:tst} are more efficient than \texttt{test}, \cmd{ifbool} from \secref{aut:bo1:bol} is more efficient than \texttt{bool}, and \cmd{iftoggle} from \secref{aut:bo1:tgl} is more efficient than \texttt{togl}. The point of \cmd{ifboolexpr} and \cmd{ifboolexpe} is that they support logical operators and subexpressions. The following logical operators are available in the \prm{expression}: -Expands to \prm{true} if the state of the boolean switch \prm{name} is \texttt{true}, and to \prm{false} otherwise. If the switch is undefined, this command issues an error. +\begin{marglist} +\appto\marglistfont{\verbatimfont} -\cmditem{nottoggle}{name}{not true}{not false} +\item[not] -Similar to \cmd{iftoggle} but reverses the logic of the test. +The \texttt{not} operator negates the truth value of the immediately following element. You may prefix \texttt{togl}, \texttt{bool}, \texttt{test}, and subexpressions with \texttt{not}. For example: -\end{ltxsyntax} +\begin{ltxcode} +\ifboolexpr{ + <<not>> bool {mybool} +} +{true} +{false} +\end{ltxcode} +% +will yield \prm{true} if \texttt{mybool} is false and \prm{false} if \texttt{mybool} is true, and + +\begin{ltxcode} +\ifboolexpr{ + <<not (>> bool {boolA} and bool {boolB} <<)>> +} +{true} +{false} +\end{ltxcode} +% +will yield \prm{true} if both \texttt{boolA} and \texttt{boolB} are false. + +\item[and] + +The \texttt{and} operator expresses a conjunction (both \emph{a} and \emph{b}). The \prm{expression} is true if all elements joined with \texttt{and} are true. For example: + +\begin{ltxcode} +\ifboolexpr{ + bool {boolA} <<and>> bool {boolB} +} +{true} +{false} +\end{ltxcode} +% +will yield \prm{true} if both \texttt{bool} tests are true. The \texttt{nand} operator (negated \texttt{and}, \ie not both) is not provided as such but may be expressed by using \texttt{and} in a negated subexpression. For example: + +\begin{ltxcode} +bool {boolA} <<nand>> bool {boolB} +\end{ltxcode} +% +may be written as + +\begin{ltxcode} +<<not>> <<(>> bool {boolA} <<and>> bool {boolB} <<)>> +\end{ltxcode} + +\item[or] + +The \texttt{or} operator expresses a non-exclusive disjunction (either \emph{a} or \emph{b} or both). The \prm{expression} is true if at least one of the elements joined with \texttt{or} is true. For example: + +\begin{ltxcode} +\ifboolexpr{ + togl {toglA} <<or>> togl {toglB} +} +{true} +{false} +\end{ltxcode} +% +will yield \prm{true} if either \texttt{togl} test or both tests are true. The \texttt{nor} operator (negated non-exclusive disjunction, \ie neither \emph{a} nor \emph{b} nor both) is not provided as such but may be expressed by using \texttt{or} in a negated subexpression. For example: + +\begin{ltxcode} +bool {boolA} <<nor>> bool {boolB} +\end{ltxcode} +% +may be written as + +\begin{ltxcode} +<<not>> <<(>> bool {boolA} <<or>> bool {boolB} <<)>> +\end{ltxcode} + +\item[(...)] + +The parentheses delimit a subexpression in the \prm{expression}. The subexpression is evaluated and the result of this evaluation is treated as a single truth value in the enclosing expression. Subexpressions may be nested. For example, the expression: + +\begin{ltxcode} + <<(>> bool {boolA} or bool {boolB} <<)>> + and + <<(>> bool {boolC} or bool {boolD} <<)>> +\end{ltxcode} +% +is true if both subexpressions are true, \ie if at least one of \texttt{boolA}/\texttt{boolB} and at least one of \texttt{boolC}/\texttt{boolD} is true. Note that subexpressions are generally not required if all elements are joined with \texttt{and} or with \texttt{or}. For example, the expressions + +\begin{ltxcode} +bool {boolA} <<and>> bool {boolB} <<and>> {boolC} <<and>> bool {boolD} +bool {boolA} <<or>> bool {boolB} <<or>> {boolC} <<or>> bool {boolD} +\end{ltxcode} +% +will yield the expected results: the first one is true if all elements are true; the second one is true if at least one element is true. However, when combining \texttt{and} and \texttt{or}, it is advisable to always group the elements in subexpressions in order to avoid potential misconceptions which may arise from differences between the semantics of formal boolean expressions and the semantics of natural languages. For example, the following expression + +\begin{ltxcode} +bool {<<bagel>>} <<and>> bool {<<ham>>} <<or>> bool {<<cheese>>} +\end{ltxcode} +% +is always true if \texttt{cheese} is true since the \texttt{or} operator will take the result of the \texttt{and} evaluation as input. In contrast to the meaning of this expression when pronounced in English, it is not processed like this + +\begin{ltxcode} +bool {<<bagel>>} <<and>> <<(>> bool {<<ham>>} <<or>> bool {<<cheese>>} <<)>> +\end{ltxcode} +% +but evaluated strictly from left to right: + +\begin{ltxcode} +<<(>> bool {<<bagel>>} <<and>> bool {<<ham>>} <<)>> <<or>> bool {<<cheese>>} +\end{ltxcode} + +\end{marglist} \subsection{List processing} \label{aut:lst} @@ -758,7 +1028,7 @@ Similar to \cmd{iftoggle} but reverses the logic of the test. \subsubsection{User input} \label{aut:lst:inp} -The facilities in this section are primarily designed to handle user input. When building lists for internal use by a package, using the facilities in section \ref{aut:lst:int} is preferable. +The facilities in this section are primarily designed to handle user input. When building lists for internal use by a package, using the facilities in section \ref{aut:lst:int} may be preferable as they allow testing if an element is in a list. \begin{ltxsyntax} @@ -774,7 +1044,7 @@ Note that the list parsers are sensitive to the category code of the \prm{separa \cmditem{docsvlist}{item, item, ...} -This command loops over a comma"=separated list and executes the auxiliary command \cmd{do} for every item in the list, passing the item as an argument. In contrast to the \cmd{@for} loop in the \latex kernel, \cmd{docsvlist} is expandable. With a suitable definition of \cmd{do}, lists may be processed inside an \cmd{edef} or a comparable context. You may use \cmd{listbreak} at the end of the replacement text of \cmd{do} to stop processing and discard the remaining items in the list. Whitespace after list separators is ignored. If an item contains a comma or starts with a space, it must be wrapped in curly braces. The braces will be removed as the list is processed. Here is a usage example which prints a comma"=separated list as an \env{itemize} environment: +This command loops over a comma"=separated list and executes the auxiliary command \cmd{do} for every item in the list, passing the item as an argument. In contrast to the \cmd{@for} loop in the \latex kernel, \cmd{docsvlist} is expandable. With a suitable definition of \cmd{do}, lists may be processed in an \cmd{edef} or a comparable context. You may use \cmd{listbreak} at the end of the replacement text of \cmd{do} to stop processing and discard the remaining items in the list. Whitespace after list separators is ignored. If an item contains a comma or starts with a space, it must be wrapped in curly braces. The braces will be removed as the list is processed. Here is a usage example which prints a comma"=separated list as an \env{itemize} environment: \begin{ltxcode} \begin{itemize} @@ -805,7 +1075,7 @@ The facilities in this section handle internal lists of data. An <internal list> \cmditem{listadd}{listmacro}{item} -This command appends an \prm{item} to a \prm{listmacro}. +This command appends an \prm{item} to a \prm{listmacro}. A blank \prm{item} is not added to the list. \cmditem{listgadd}{listmacro}{item} @@ -813,7 +1083,7 @@ Similar to \cmd{listadd} except that the assignment is global. \cmditem{listeadd}{listmacro}{item} -Similar to \cmd{listadd} except that the \prm{item} is expanded at definition"=time. Only the new \prm{item} is expanded, the current list is not. +Similar to \cmd{listadd} except that the \prm{item} is expanded at definition"=time. Only the new \prm{item} is expanded, the \prm{listmacro} is not. If the expanded \prm{item} is blank, it is not added to the list. \cmditem{listxadd}{listmacro}{item} @@ -852,7 +1122,7 @@ Similar to \cmd{dolistloop} except that it takes a control sequence name as its \cmditem{ifinlist}{item}{listmacro} -This command checks if an \prm{item} is included in a \prm{listmacro}. Note that this test uses pattern matching based on \tex's argument scanner to check if the search string is included in the list. This means that it is usually faster than looping over all items in the list, but it also implies that the items must not include curly braces which would effectively hide them from the scanner. In other words, this macro is most useful when dealing with lists of plain strings rather than printable data. When dealing with printable text, it may be preferable to use \cmd{dolistloop} to check if an item is in the list as follows: +This command checks if an \prm{item} is included in a \prm{listmacro}. Note that this test uses pattern matching based on \tex's argument scanner to check if the search string is included in the list. This means that it is usually faster than looping over all items in the list, but it also implies that the items must not include curly braces which would effectively hide them from the scanner. In other words, this macro is most useful when dealing with lists of plain strings rather than printable data. When dealing with printable text, it is safer to use \cmd{dolistloop} to check if an item is in the list as follows: \begin{ltxcode} \renewcommand*{\do}[1]{% @@ -883,19 +1153,19 @@ Similar to \cmd{xifinlist} except that it takes a control sequence name as its s \cmditem{rmntonum}{numeral} -The \tex primitive \cmd{romannumeral} converts an integer to a Roman numeral but \tex or \latex provide no command which goes the opposite way. \cmd{rmntonum} fills this gap. It takes a Roman numeral as its argument and converts it to the corresponding integer. Since it is expandable, it may also be used in counter assignments or \cmd{ifnum} comparisons: +The \tex primitive \cmd{romannumeral} converts an integer to a Roman numeral but \tex or \latex provide no command which goes the opposite way. \cmd{rmntonum} fills this gap. It takes a Roman numeral as its argument and converts it to the corresponding integer. Since it is expandable, it may also be used in counter assignments or arithmetic tests: \begin{ltxcode} -\rmntonum{mcmxcv} -\setcounter{counter}{\rmntonum{CXVI}} -\ifnum\rmntonum{mcmxcviii}<2000 ... +<<\rmntonum>>{<<mcmxcv>>} +\setcounter{counter}{<<\rmntonum>>{<<CXVI>>}} +\ifnumless{<<\rmntonum>>{<<mcmxcviii>>}}{2000}{true}{false} \end{ltxcode} % -The \prm{numeral} argument must be a literal string. It will be detokenized prior to parsing. The parsing of the numeral is case"=insensitive and whitespace in the argument is ignored. If there is an invalid token in the argument, \cmd{rmntonum} will expand to~\texttt{-1}; an empty argument will yield an empty string. Note that \cmd{rmntonum} will not check the numeral for formal validity. For example, both \texttt{V} and \texttt{VX} will yield~\texttt{5}. +The \prm{numeral} argument must be a literal string. It will be detokenized prior to parsing. The parsing of the numeral is case"=insensitive and whitespace in the argument is ignored. If there is an invalid token in the argument, \cmd{rmntonum} will expand to~\texttt{-1}; an empty argument will yield an empty string. Note that \cmd{rmntonum} will not check the numeral for formal validity. For example, both \texttt{V} and \texttt{VX} would yield \texttt{5}, \texttt{IC} would yield \texttt{99}, etc. \cmditem{ifrmnum}{string}{true}{false} -Expands to \prm{true} if \prm{string} is a Roman numeral, and to \prm{false} otherwise. The \prm{string} will be detokenized prior to performing the test. The test is case"=insensitive and ignores whitespace in the \prm{string}. Note that \cmd{ifrmnum} will not check the numeral for formal validity. For example, both \texttt{V} and \texttt{VXV} will yield \prm{true}. Strictly speaking, what \cmd{ifrmnum} does is parse the \prm{string} in order to find out if it consists of characters which may form a valid Roman numeral. +Expands to \prm{true} if \prm{string} is a Roman numeral, and to \prm{false} otherwise. The \prm{string} will be detokenized prior to performing the test. The test is case"=insensitive and ignores whitespace in the \prm{string}. Note that \cmd{ifrmnum} will not check the numeral for formal validity. For example, both \texttt{V} and \texttt{VXV} will yield \prm{true}. Strictly speaking, what \cmd{ifrmnum} does is parse the \prm{string} in order to find out if it consists of characters which may form a valid Roman numeral, but it will not check if they really are a valid Roman numeral. \end{ltxsyntax} @@ -905,6 +1175,21 @@ This revision history is a list of changes relevant to users of this package. Ch \begin{changelog} +\begin{release}{1.9}{2010-04-10} + +\item Improved \cmd{letcs}\see{aut:def:def} +\item Improved \cmd{csletcs}\see{aut:def:def} +\item Improved \cmd{listeadd}\see{aut:lst:int} +\item Improved \cmd{listxadd}\see{aut:lst:int} +\item Added \cmd{notblank}\see{aut:tst:str} +\item Added \cmd{ifnumodd}\see{aut:tst:num} +\item Added \cmd{ifboolexpr}\see{aut:tst:bol} +\item Added \cmd{ifboolexpe}\see{aut:tst:bol} +\item Added \cmd{whileboolexpr}\see{aut:tst:bol} +\item Added \cmd{unlessboolexpr}\see{aut:tst:bol} + +\end{release} + \begin{release}{1.8}{2009-08-06} \item Improved \cmd{deflength}\see{use:cal} @@ -952,7 +1237,7 @@ This revision history is a list of changes relevant to users of this package. Ch \item Improved \cmd{ifcsvoid}\see{aut:tst:def} \item Added \cmd{ifstrempty}\see{aut:tst:str} \item Added \cmd{setbool}\see{aut:bo1:bol} -\item Added \cmd{settoggle}\see{aut:bo1:swi} +\item Added \cmd{settoggle}\see{aut:bo1:tgl} \end{release} @@ -978,12 +1263,12 @@ This revision history is a list of changes relevant to users of this package. Ch \begin{release}{1.3}{2007-10-08} \item Renamed package from \sty{elatex} to \sty{etoolbox}\see{int} -\item Renamed \cmd{newswitch} to \cmd{newtoggle} (name clash)\see{aut:bo1:swi} -\item Renamed \cmd{provideswitch} to \cmd{providetoggle} (consistency)\see{aut:bo1:swi} -\item Renamed \cmd{switchtrue} to \cmd{toggletrue} (consistency)\see{aut:bo1:swi} -\item Renamed \cmd{switchfalse} to \cmd{togglefalse} (consistency)\see{aut:bo1:swi} -\item Renamed \cmd{ifswitch} to \cmd{iftoggle} (consistency)\see{aut:bo1:swi} -\item Renamed \cmd{notswitch} to \cmd{nottoggle} (consistency)\see{aut:bo1:swi} +\item Renamed \cmd{newswitch} to \cmd{newtoggle} (name clash)\see{aut:bo1:tgl} +\item Renamed \cmd{provideswitch} to \cmd{providetoggle} (consistency)\see{aut:bo1:tgl} +\item Renamed \cmd{switchtrue} to \cmd{toggletrue} (consistency)\see{aut:bo1:tgl} +\item Renamed \cmd{switchfalse} to \cmd{togglefalse} (consistency)\see{aut:bo1:tgl} +\item Renamed \cmd{ifswitch} to \cmd{iftoggle} (consistency)\see{aut:bo1:tgl} +\item Renamed \cmd{notswitch} to \cmd{nottoggle} (consistency)\see{aut:bo1:tgl} \item Added \cmd{AtEndPreamble}\see{use:pre} \item Added \cmd{AfterEndDocument}\see{use:pre} \item Added \cmd{AfterPreamble}\see{use:pre} @@ -1022,12 +1307,12 @@ This revision history is a list of changes relevant to users of this package. Ch \item Added \cmd{boolfalse}\see{aut:bo1:bol} \item Added \cmd{ifbool}\see{aut:bo1:bol} \item Added \cmd{notbool}\see{aut:bo1:bol} -\item Added \cmd{newswitch}\see{aut:bo1:swi} -\item Added \cmd{provideswitch}\see{aut:bo1:swi} -\item Added \cmd{switchtrue}\see{aut:bo1:swi} -\item Added \cmd{switchfalse}\see{aut:bo1:swi} -\item Added \cmd{ifswitch}\see{aut:bo1:swi} -\item Added \cmd{notswitch}\see{aut:bo1:swi} +\item Added \cmd{newswitch}\see{aut:bo1:tgl} +\item Added \cmd{provideswitch}\see{aut:bo1:tgl} +\item Added \cmd{switchtrue}\see{aut:bo1:tgl} +\item Added \cmd{switchfalse}\see{aut:bo1:tgl} +\item Added \cmd{ifswitch}\see{aut:bo1:tgl} +\item Added \cmd{notswitch}\see{aut:bo1:tgl} \item Added \cmd{DeclareListParser}\see{aut:lst:inp} \item Added \cmd{docsvlist}\see{aut:lst:inp} \item Added \cmd{rmntonum}\see{aut:msc} |