path: root/Master/texmf-dist/doc/latex/etoolbox/etoolbox.tex

% $Id: etoolbox.tex,v 1.3 2007/10/08 17:42:31 lehman stable $
\documentclass{latexdoc}
\usepackage[latin9]{inputenc}
\usepackage[american]{babel}
\usepackage[strict,style=american]{csquotes}
\MakeAutoQuote{«}{»}
\MakeAutoQuote*{<}{>}

\rcsid{$Id: etoolbox.tex,v 1.3 2007/10/08 17:42:31 lehman stable $}

\titlepage{%
  title={The \sty{etoolbox} package},
  subtitle={An \etex toolbox for class and package authors},
  url={http://www.ctan.org/tex-archive/macros/latex/contrib/etoolbox/},
  author={Philipp Lehman},
  email={plehman@gmx.net},
  revision={\rcsrevision},
  date={\rcstoday}}

\hypersetup{%
  pdftitle={The etoolbox package},
  pdfsubject={An e-TeX toolbox for class and package authors},
  pdfauthor={Philipp Lehman},
  pdfkeywords={tex, etex, latex, class, package}}

\begin{document}

\printtitlepage
\tableofcontents

\section{Introduction}
\label{int}

\subsection{About}

The \sty{etoolbox} package is a toolbox of programming facilities geared primarily towards \latex class and package authors. It provides \latex frontends to some of the new primitives provided by \etex as well as some generic tools which are not related to \etex but match the profile of this package. The package is work in progress. Note that previous versions of this package were released under the name \sty{elatex}.

\subsection{License}

Copyright \textcopyright\ 2007 Philipp Lehman. This package is author"=maintained. 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 software is provided <as is>, without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose.

\subsection[Feedback]{Feedback and contributions}

I started to work on this package when I found myself implementing the same tools and shorthands I had employed in previous \latex packages for yet another package. For the most part, the facilities provided by \sty{etoolbox} address my needs as a package author and future development is likely to be guided by these needs as well. Please note that I will not be able to address any feature requests. However, I am open to contributions by other class and package authors, provided that the contributed code is sufficiently generic, matches the profile of this package, and may be added to the package without requiring significant adaption.

\subsection{Acknowledgments}

The \ltxcmd{ifblank} test of this package is based on code by Donald Arseneau.

\section{User commands}
\label{use}

The facilities in this section are geared towards regular users as well as class and package authors.

\subsection{Definitions}
\label{use:def}

\begin{syntax}

\cmd{newrobustcmd}{command}[arguments][optarg default]{definition}

The syntax and behavior of this command is similar to \ltxcmd{newcommand} except that the newly defined \ltxarg{command} is robust. This command differs from the \ltxcmd{DeclareRobustCommand} command from the \latex kernel in that it issues an error rather than just an informational message if the \ltxarg{command} is already defined. Since it uses \etex's low-level protection mechanism rather than the corresponding high-level \latex facilities, it does not require an additional macro to implement the <robustness>. This command itself is also robust.

\cmd{renewrobustcmd}{command}[arguments][optarg default]{definition}

The syntax and behavior of this command is similar to \ltxcmd{renewcommand} except that the redefined \ltxarg{command} is robust. This command itself is also robust.

\cmd{providerobustcmd}{command}[arguments][optarg default]{definition}

The syntax and behavior of this command is similar to \ltxcmd{providecommand} except that the newly defined \ltxarg{command} is robust. Note that this command only provides a robust definition if the \ltxarg{command} is undefined. It will not make an already defined \ltxarg{command} robust. This command itself is robust.

\subsection{Patching}
\label{use:pat}

\cmd{robustify}{command}

Redefines a \ltxarg{command} such that it is robust without altering its syntax or definition. If the \ltxarg{command} has been defined with \ltxcmd{DeclareRobustCommand}, this will be detected automatically. \latex's high-level protection mechanism is replaced by the corresponding low-level \etex facility in this case. This command is robust and may only be used in the document preamble.

\end{syntax}

\section{Author commands}

The facilities in this section are geared towards class and package authors.

\subsection{Definitions}
\label{aut:def}

The facilities in this section are simple but frequently required shorthands which extend the scope of the \ltxcmd{@namedef} and \ltxcmd{@nameuse} macros from the \latex kernel.

\begin{syntax}

\cmd{csdef}{csname}<arguments>{definition}

Similar to the \tex primitive \ltxcmd{def} except that it takes a control sequence name as its first argument. This command is robust and corresponds to \ltxcmd{@namedef}.

\cmd{csgdef}{csname}<arguments>{definition}

Similar to the \tex primitive \ltxcmd{gdef} except that it takes a control sequence name as its first argument. This command is robust.

\cmd{csedef}{csname}<arguments>{definition}

Similar to the \tex primitive \ltxcmd{edef} except that it takes a control sequence name as its first argument. This command is robust.

\cmd{csxdef}{csname}<arguments>{definition}

Similar to the \tex primitive \ltxcmd{xdef} except that it takes a control sequence name as its first argument. This command is robust.

\cmd{protected@csedef}{csname}<arguments>{definition}

Similar to \ltxcmd{csedef} except that \latex's protection mechanism is temporarily enabled. To put it in other words: this command is similar to the \latex kernel command \ltxcmd{protected@edef} except that it takes a control sequence name as its first argument. This command is robust.

\cmd{protected@csxdef}{csname}<arguments>{definition}

Similar to \ltxcmd{csxdef} except that \latex's protection mechanism is temporarily enabled. To put it in other words: this command is similar to the \latex kernel command \ltxcmd{protected@xdef} except that it takes a control sequence name as its first argument. This command is robust.

\cmd{cslet}{csname}{command}

Similar to the \tex primitive \ltxcmd{let} except that the first argument is a control sequence name. This command is robust and may be prefixed with \ltxcmd{global}.

\cmd{letcs}{command}{csname}

Similar to the \tex primitive \ltxcmd{let} except that the second argument is a control sequence name. This command is robust and may be prefixed with \ltxcmd{global}.

\cmd{csletcs}{csname}{csname}

Similar to the \tex primitive \ltxcmd{let} except that both arguments are control sequence names. This command is robust and may be prefixed with \ltxcmd{global}.

\cmd{csuse}{csname}

Takes a control sequence name as its argument and forms a control sequence token. This command differs from the \ltxcmd{@nameuse} macro from the \latex kernel in that it expands to an empty string if the control sequence is undefined.

\cmd{undef}<command>

Clears the definition of \ltxarg{command} such that \etex's \ltxcmd{ifdefined} and \ltxcmd{ifcsname} tests will consider it as undefined. This command is robust and may be prefixed with \ltxcmd{global}.

\cmd{csundef}{csname}

Similar to \ltxcmd{undef} except that it takes a control sequence name as its argument. This command is robust and may be prefixed with \ltxcmd{global}.

\end{syntax}

\subsection{Arithmetic definitions}
\label{aut:cal}

The facilities in this section permit calculations using macros rather than length registers and counters.

\begin{syntax}

\cmd{numdef}{command}{integer expression}

This command is similar to \ltxcmd{edef} except that the \ltxarg{integer expression} is processed with \ltxcmd{numexpr}. The \ltxarg{integer expression} may be any arbitrary code which is valid in this context. The definition assigned to \ltxarg{command} will be the result of that calculation. If the \ltxarg{command} is undefined, it will be initialized to <\texttt{0}> before the \ltxarg{integer expression} is processed.

\cmd{numgdef}{command}{integer expression}

Similar to \ltxcmd{numdef} except that the assignment is global.

\cmd{csnumdef}{csname}{integer expression}

Similar to \ltxcmd{numdef} except that it takes a control sequence name as its first argument.

\cmd{csnumgdef}{csname}{integer expression}

Similar to \ltxcmd{numgdef} except that it takes a control sequence name as its first argument.

\cmd{dimdef}{command}{dimen expression}

This command is similar to \ltxcmd{edef} except that the \ltxarg{dimen expression} is processed with \ltxcmd{dimexpr}. The \ltxarg{dimen expression} may be any arbitrary code which is valid in this context. The definition assigned to \ltxarg{command} will be the result of that calculation. If the \ltxarg{command} is undefined, it will be initialized to <\texttt{0pt}> before the \ltxarg{dimen expression} is processed.

\cmd{dimgdef}{command}{dimen expression}

Similar to \ltxcmd{dimdef} except that the assignment is global.

\cmd{csdimdef}{csname}{dimen expression}

Similar to \ltxcmd{dimdef} except that it takes a control sequence name as its first argument.

\cmd{csdimgdef}{csname}{dimen expression}

Similar to \ltxcmd{dimgdef} except that it takes a control sequence name as its first argument.

\cmd{gluedef}{command}{glue expression}

This command is similar to \ltxcmd{edef} except that the \ltxarg{glue expression} is processed with \ltxcmd{glueexpr}. The \ltxarg{glue expression} may be any arbitrary code which is valid in this context. The definition assigned to \ltxarg{command} will be the result of that calculation. If the \ltxarg{command} is undefined, it will be initialized to <\texttt{0pt plus 0pt minus 0pt}> before the \ltxarg{glue expression} is processed.

\cmd{gluegdef}{command}{glue expression}

Similar to \ltxcmd{gluedef} except that the assignment is global.

\cmd{csgluedef}{csname}{glue expression}

Similar to \ltxcmd{gluedef} except that it takes a control sequence name as its first argument.

\cmd{csgluegdef}{csname}{glue expression}

Similar to \ltxcmd{gluegdef} except that it takes a control sequence name as its first argument.

\cmd{mudef}{command}{muglue expression}

This command is similar to \ltxcmd{edef} except that the \ltxarg{muglue expression} is processed with \ltxcmd{muexpr}. The \ltxarg{muglue expression} may be any arbitrary code which is valid in this context. The definition assigned to \ltxarg{command} will be the result of that calculation. If the \ltxarg{command} is undefined, it will be initialized to <\texttt{0mu}> before the \ltxarg{muglue expression} is processed.

\cmd{mugdef}{command}{muglue expression}

Similar to \ltxcmd{mudef} except that the assignment is global.

\cmd{csmudef}{csname}{muglue expression}

Similar to \ltxcmd{mudef} except that it takes a control sequence name as its first argument.

\cmd{csmugdef}{csname}{muglue expression}

Similar to \ltxcmd{mugdef} except that it takes a control sequence name as its first argument.

\end{syntax}

\subsection{Expansion control}

The facilities in this section are useful to control expansion in an \ltxcmd{edef} or a similar context.

\begin{syntax}

\cmd{expandonce}{command}

This command expands \ltxarg{command} once and prevents further expansion of the replacement text.

\cmd{csexpandonce}{csname}

Similar to \ltxcmd{expandonce} except that it takes a control sequence name as its argument.

\cmd{protecting}{code}

This command applies \latex's protection mechanism, which normally requires prefixing each fragile command with \ltxcmd{protect}, to an entire chunk of arbitrary \ltxarg{code} or text. Its behavior depends on the current state of \ltxcmd{protect}. Note that the braces around \ltxarg{code} are mandatory even if it is a single token.

\end{syntax}

\subsection{Hook management}
\label{aut:hok}

The facilities in this section are intended for hook management. A <hook> in this context is a plain macro without any arguments and prefixes which is used to collect code to be executed later. These facilities may also be useful to patch simple macros by appending code to them. For more complex patching operations, see section \ref{aut:pat}. All commands in this section will initialize the hook if it is undefined.

\subsubsection{Appending code to a hook}
\label{aut:hok:app}

The facilities in this section append arbitrary code to a hook.

\begin{syntax}

\cmd{appto}{command}{code}

This command appends arbitrary \ltxarg{code} to a \ltxarg{command}. If the \ltxarg{code} contains any parameter characters, they need not be doubled. This command is robust.

\cmd{gappto}{command}{code}

Similar to \ltxcmd{appto} except that the assignment is global. This command may be used as a drop-in replacement for the \ltxcmd{g@addto@macro} command in the \latex kernel.

\cmd{eappto}{command}{code}

This command appends arbitrary \ltxarg{code} to a \ltxarg{command}. The \ltxarg{code} is expanded at definition"=time. Only the new \ltxarg{code} is expanded, the current definition of \ltxarg{command} is not. This command is robust.

\cmd{xappto}{command}{code}

Similar to \ltxcmd{eappto} except that the assignment is global.

\cmd{protected@eappto}{command}{code}

Similar to \ltxcmd{eappto} except that \latex's protection mechanism is temporarily enabled.

\cmd{protected@xappto}{command}{code}

Similar to \ltxcmd{xappto} except that \latex's protection mechanism is temporarily enabled.

\cmd{csappto}{csname}{code}

Similar to \ltxcmd{appto} except that it takes a control sequence name as its first argument.

\cmd{csgappto}{csname}{code}

Similar to \ltxcmd{gappto} except that it takes a control sequence name as its first argument.

\cmd{cseappto}{csname}{code}

Similar to \ltxcmd{eappto} except that it takes a control sequence name as its first argument.

\cmd{csxappto}{csname}{code}

Similar to \ltxcmd{xappto} except that it takes a control sequence name as its first argument.

\cmd{protected@cseappto}{command}{code}

Similar to \ltxcmd{protected@eappto} except that it takes a control sequence name as its first argument.

\cmd{protected@csxappto}{command}{code}

Similar to \ltxcmd{protected@xappto} except that it takes a control sequence name as its first argument.

\end{syntax}

\subsubsection{Prepending code to a hook}
\label{aut:hok:pre}

The facilities in this section <prepend> arbitrary code to a hook, \ie the code is inserted at the beginning of the hook rather than being added at the end.

\begin{syntax}

\cmd{preto}{command}{code}

Similar to \ltxcmd{appto} except that the \ltxarg{code} is prepended.

\cmd{gpreto}{command}{code}

Similar to \ltxcmd{preto} except that the assignment is global.

\cmd{epreto}{command}{code}

Similar to \ltxcmd{eappto} except that the \ltxarg{code} is prepended.

\cmd{xpreto}{command}{code}

Similar to \ltxcmd{epreto} except that the assignment is global.

\cmd{protected@epreto}{command}{code}

Similar to \ltxcmd{epreto} except that \latex's protection mechanism is temporarily enabled.

\cmd{protected@xpreto}{command}{code}

Similar to \ltxcmd{xpreto} except that \latex's protection mechanism is temporarily enabled.

\cmd{cspreto}{csname}{code}

Similar to \ltxcmd{preto} except that it takes a control sequence name as its first argument.

\cmd{csgpreto}{csname}{code}

Similar to \ltxcmd{gpreto} except that it takes a control sequence name as its first argument.

\cmd{csepreto}{csname}{code}

Similar to \ltxcmd{epreto} except that it takes a control sequence name as its first argument.

\cmd{csxpreto}{csname}{code}

Similar to \ltxcmd{xpreto} except that it takes a control sequence name as its first argument.

\cmd{protected@csepreto}{command}{code}

Similar to \ltxcmd{protected@epreto} except that it takes a control sequence name as its first argument.

\cmd{protected@csxpreto}{command}{code}

Similar to \ltxcmd{protected@xpreto} except that it takes a control sequence name as its first argument.

\end{syntax}

\subsection[Predefined hooks]{Predefined all-purpose hooks}
\label{aut:pre}

\latex provides two hooks which defer the execution of code either to the beginning or the end of the document body. The \ltxcmd{AtBeginDocument} code is executed at the beginning of the document body, \emph{after} the main \file{aux} file has been read for the first time. The \ltxcmd{AtEndDocument} code is executed at the end of the document body, \emph{before} the main \file{aux} file is read for the second time. The hooks introduced here are similar in concept but defer the execution of their \ltxarg{code} argument to slightly different locations. The \ltxarg{code} may be arbitrary \tex code. Macro parameter characters in the \ltxarg{code} argument need not be doubled.

\begin{syntax}

\cmd{AtEndPreamble}{code}

This hook differs from \ltxcmd{AtBeginDocument} in that the \ltxarg{code} is executed right at the end of the preamble, before the main \file{aux} file (as written during the previous \latex pass) is read and prior to any \ltxcmd{AtBeginDocument} code. It is sometimes desirable to defer code to the end of the preamble because all requested packages have been loaded at this point. Code deferred with \ltxcmd{AtBeginDocument}, however, is executed too late if it is required in the \file{aux} file.

\cmd{AfterEndDocument}{code}

This hook differs from \ltxcmd{AtEndDocument} in that the \ltxarg{code} is executed at the very end of the document, after the main \file{aux} file (as written during the current \latex pass) has been read and after any \ltxcmd{AtEndDocument} code. This hook is useful if a package needs to evaluate any data in the \file{aux} file at the end of a \latex run.

\cmd{AfterPreamble}{code}

This hook is a variant of \ltxcmd{AtBeginDocument} which may also be used in the document body. When used in the document preamble, it behaves exactely like \ltxcmd{AtBeginDocument}. When used in the document body, it immediately executes its \ltxarg{code} argument (\ltxcmd{AtBeginDocument} issues an error in this case).

\end{syntax}

\subsection{Patching}
\label{aut:pat}

The facilities in this section are useful to hook into or modify existing code. All commands presented here preserve the number of arguments and the prefixes of the patched \ltxarg{command}. Note that the patching process involves detokenizing the \ltxarg{command} and retokenizing it under the current category code regime after patching. The category code of <@> is temporarily set to 11. If the definition of the \ltxarg{command} includes any tokens with non"=standard category codes, the respective category codes must be adjusted prior to patching. If the code to be replaced or inserted refers to the parameters of the \ltxarg{command} to be patched, the parameter characters need not be doubled when invoking one of the commands below. Note that \ltxcmd{outer} commands may not be patched.

\begin{syntax}

\cmd{patchcmd}[prefix]{command}{search}{replace}{success}{failure}

This command extracts the definition of a \ltxarg{command}, replaces \ltxarg{search} with \ltxarg{replace}, and reassembles the \ltxarg{command}. The pattern match is category code agnostic and matches the first occurence of the \ltxarg{search} string in the definition of the \ltxarg{command} to be patched. If an optional \ltxarg{prefix} is specified, it replaces the prefixes of the \ltxarg{command}. An empty \ltxarg{prefix} strips all prefixes from the \ltxarg{command}. This command executes \ltxarg{success} if patching succeeds, and \ltxarg{failure} otherwise. It is robust and may only be used in the document preamble. The assignment is local.

\cmd{ifpatchable}{command}{search}{true}{false}

This command executes \ltxarg{true} if the \ltxarg{command} is defined and the \ltxarg{search} pattern is found in its definition, and \ltxarg{false} otherwise. This command is robust and may only be used in the document preamble.

\cmd{apptocmd}{command}{code}

This command appends \ltxarg{code} to the definition of \ltxarg{command}. In contrast to the \ltxcmd{appto} command from section \ref{aut:hok:app}, this one may be used to patch a \ltxarg{command} which takes an arbitrary number of arguments. The \ltxarg{code} may refer to the parameters of the \ltxarg{command} in this case. This command is robust and may only be used in the document preamble. The assignment is local.

\cmd{pretocmd}{command}{code}

This command is similar to \ltxcmd{apptocmd} except that the \ltxarg{code} is <prepended>, \ie inserted at the beginning of the definition of \ltxarg{command}. In contrast to the \ltxcmd{preto} command from section \ref{aut:hok:app}, this one may be used to patch a \ltxarg{command} which takes an arbitrary number of arguments. The \ltxarg{code} may refer to the parameters of the \ltxarg{command} in this case. This command is robust and may only be used in the document preamble. The assignment is local.

\end{syntax}

\subsection{Generic tests}
\label{aut:tst}

\begin{syntax}

\cmd{ifdef}{command}{true}{false}

A \latex wrapper for the \etex primitive \ltxcmd{ifdefined}. This command expands to \ltxarg{true} if the \ltxarg{command} is defined, and to \ltxarg{false} otherwise. Note that the \ltxarg{command} is considered as defined even if its meaning is \ltxcmd{relax}.

\cmd{ifundef}{command}{true}{false}

Expands to \ltxarg{true} if the \ltxarg{command} is undefined, and to \ltxarg{false} otherwise. Apart from reversing the logic of the test, this command also differs from \ltxcmd{ifdef} in that the \ltxarg{command} is considered as undefined if its meaning is \ltxcmd{relax}.

\cmd{ifcsdef}{csname}{true}{false}

A \latex wrapper for the \etex primitive \ltxcmd{ifcsname}. This command expands to \ltxarg{true} if \ltxarg{csname} is defined, and to \ltxarg{false} otherwise. Note that \ltxarg{csname} is considered as defined even if its meaning is \ltxcmd{relax}.

\cmd{ifcsundef}{csname}{true}{false}

Expands to \ltxarg{true} if \ltxarg{csname} is undefined, and to \ltxarg{false} otherwise. Apart from reversing the logic of the test, this command also differs from \ltxcmd{ifcsdef} in that the \ltxarg{csname} is considered as undefined if its meaning is \ltxcmd{relax}. This command may be used as a drop-in replacement for the \ltxcmd{@ifundefined} test in the \latex kernel.

\cmd{ifdefvoid}{command}{true}{false}

Expands to \ltxarg{true} if \ltxarg{command} is undefined, its meaning is \ltxcmd{relax}, or its definition is empty, and to \ltxarg{false} otherwise. 

\cmd{ifcsvoid}{csname}{true}{false}

Similar to \ltxcmd{ifdefvoid} except that it takes a control sequence name as its first argument.

\cmd{ifdefequal}{command}{command}{true}{false}

Compares the definitions of two commands and expands to \ltxarg{true} if they are equal, and to \ltxarg{false} otherwise. In contrast to the \tex primitive \ltxcmd{ifx}, this test will also yield \ltxarg{false} if both commands are undefined or have a meaning of \ltxcmd{relax}.

\cmd{ifcsequal}{csname}{csname}{true}{false}

Similar to \ltxcmd{ifdefequal} except that it takes control sequence names as arguments.

\cmd{ifstrequal}{string}{string}{true}{false}

Compares two strings and executes \ltxarg{true} if they are equal, and \ltxarg{false} otherwise. The strings are not expanded in the test and the comparison is category code agnostic. Control sequence tokens in any of the \ltxarg{string} arguments will be detokenized and treated as strings. This command is robust.

\cmd{ifblank}{string}{true}{false}

Expands to \ltxarg{true} if the \ltxarg{string} is blank (empty or spaces), and to \ltxarg{false} otherwise. The \ltxarg{string} is not expanded in the test.

\end{syntax}

\subsection{Boolean switches}
\label{aut: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 \ltxcmd{newif}. Those in section \ref{aut:bo1:swi} use a different mechanism.

\subsubsection{Backwards-compatible switches}
\label{aut:bo1:bol}

Since the facilities in this section are based on \ltxcmd{newif} internally, they may be used to test and alter the state of switches previously defined with \ltxcmd{newif}. They are also compatible with the boolean tests of the \sty{ifthen} package. The \ltxcmd{newif} approach requires a total of three macros per switch.

\begin{syntax}

\cmd{newbool}{name}

Defines a new boolean switch called \ltxarg{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.

\cmd{providebool}{name}

Defines a new boolean switch called \ltxarg{name} unless it has already been defined. This command is robust.

\cmd{booltrue}{name}

Sets the boolean switch \ltxarg{name} to \texttt{true}. This command is robust and may be prefixed with \ltxcmd{global}. It will issue an error if the switch is undefined.

\cmd{boolfalse}{name}

Sets the boolean switch \ltxarg{name} to \texttt{false}. This command is robust and may be prefixed with \ltxcmd{global}. It will issue an error if the switch is undefined.

\cmd{ifbool}{name}{true}{false}

Expands to \ltxarg{true} if the state of the boolean switch \ltxarg{name} is \texttt{true}, and to \ltxarg{false} otherwise. If the switch is undefined, this command issues an error.

\cmd{notbool}{name}{not true}{not false}

Similar to \ltxcmd{ifbool} but reverses the logic of the test.

\end{syntax}

\subsubsection{Pure \latex switches}
\label{aut:bo1:swi}

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{syntax}

\cmd{newtoggle}{name}

Defines a new boolean switch called \ltxarg{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.

\cmd{providetoggle}{name}

Defines a new boolean switch called \ltxarg{name} unless it has already been defined. This command is robust.

\cmd{toggletrue}{name}

Sets the boolean switch \ltxarg{name} to \texttt{true}. This command is robust and may be prefixed with \ltxcmd{global}. It will issue an error if the switch is undefined.

\cmd{togglefalse}{name}

Sets the boolean switch \ltxarg{name} to \texttt{false}. This command is robust and may be prefixed with \ltxcmd{global}. It will issue an error if the switch is undefined.

\cmd{iftoggle}{name}{true}{false}

Expands to \ltxarg{true} if the state of the boolean switch \ltxarg{name} is \texttt{true}, and to \ltxarg{false} otherwise. If the switch is undefined, this command issues an error.

\cmd{nottoggle}{name}{not true}{not false}

Similar to \ltxcmd{iftoggle} but reverses the logic of the test.

\end{syntax}

\subsection{List processing}
\label{aut:lst}

\subsubsection{User input}
\label{aut:lst:inp}

The facilities in this section are primarily designed to handle user input. When building lists internally, using the facilities in section \ref{aut:lst:int} is preferable.

\begin{syntax}

\cmd{DeclareListParser}{command}{separator}

This command defines a list parser similar to the \ltxcmd{docsvlist} command below, which is defined with <\verb|\DeclareListParser{\docsvlist}{,}|>. Note that the list parsers are sensitive to the category code of the \ltxarg{separator}.

\cmd{docsvlist}{item, item, ...}

This command loops over a comma"=separated list and executes the auxiliary command \ltxcmd{do} for every item in the list, passing the item as an argument. In contrast to the \ltxcmd{@for} loop in the \latex kernel, \ltxcmd{docsvlist} is expandable. With a suitable definition of \ltxcmd{do}, lists may be processed inside an \ltxcmd{edef} or a comparable context. You may use \ltxcmd{listbreak} in the definition of \ltxcmd{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 \ltxenv{itemize} environment:

\begin{lstlisting}[style=latex]{}
\begin{itemize}
  \renewcommand*{\do}[1]{\item #1}
  \docsvlist{item1, item2, {item3a, item3b}, item4}
\end{itemize}
\end{lstlisting}
%
Here is another example:

\begin{lstlisting}[style=latex]{}
\renewcommand*{\do}[1]{* #1\MessageBreak}
\PackageInfo{mypackage}{%
  Example list:\MessageBreak
  \docsvlist{item1, item2, {item3a, item3b}, item4}}
\end{lstlisting}
%
In this example, the list is written to the log file as part of an informational message. The list processing takes place during the \ltxcmd{write} operation.

\end{syntax}

\subsubsection{Internal lists}
\label{aut:lst:int}

The facilities in this section handle internal lists of data. An <internal list> in this context is a plain macro without any arguments and prefixes which is employed to collect data. These lists use a special character as internal list separator. When processing user input in a list format, see the facilities in section \ref{aut:lst:inp}.

\begin{syntax}

\cmd{listadd}{listmacro}{item}

This command appends an \ltxarg{item} to a \ltxarg{listmacro}.

\cmd{listgadd}{listmacro}{item}

Similar to \ltxcmd{listadd} except that the assignment is global.

\cmd{listeadd}{listmacro}{item}

Similar to \ltxcmd{listadd} except that the \ltxarg{item} is expanded at definition"=time. Only the new \ltxarg{item} is expanded, the current definition of the list is not. This command is robust.

\cmd{listxadd}{listmacro}{item}

Similar to \ltxcmd{listeadd} except that the assignment is global.

\cmd{listcsadd}{listcsname}{item}

Similar to \ltxcmd{listadd} except that it takes a control sequence name as its first argument.

\cmd{listcsgadd}{listcsname}{item}

Similar to \ltxcmd{listcsadd} except that the assignment is global.

\cmd{listcseadd}{listcsname}{item}

Similar to \ltxcmd{listeadd} except that it takes a control sequence name as its first argument.

\cmd{listcsxadd}{listcsname}{item}

Similar to \ltxcmd{listcseadd} except that the assignment is global.

\cmd{dolistloop}{listmacro}

This command loops over all items in a \ltxarg{listmacro} and executes the auxiliary command \ltxcmd{do} for every item in the list, passing the item as an argument. The list loop itself is expandable. You may use \ltxcmd{listbreak} in the definition of \ltxcmd{do} to stop processing and discard the remaining items in the list. Here is a usage example which prints an internal list called \ltxcmd{mylist} as an \ltxenv{itemize} environment:

\begin{lstlisting}[style=latex]{}
\begin{itemize}
  \renewcommand*{\do}[1]{\item #1}
  \dolistloop{\mylist}
\end{itemize}
\end{lstlisting}

\cmd{dolistcsloop}{listcsname}

Similar to \ltxcmd{dolistloop} except that it takes a control sequence name as its argument.

\cmd{ifinlist}{item}{listmacro}

This command checks if an \ltxarg{item} is included in a \ltxarg{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, e.g. the identifiers used in the argument of \ltxcmd{label} and \ltxcmd{ref}. When dealing with printable text, it may be preferable to use \ltxcmd{dolistloop} to check if an item is in the list as follows:

\begin{lstlisting}[style=latex]{}
\renewcommand*{\do}[1]{%
  \ifstrequal{#1}{<<item>>}
    {item found!\listbreak}
    {}}
\dolistloop{\mylist}

\end{lstlisting}

\cmd{xifinlist}{item}{listmacro}

Similar to \ltxcmd{ifinlist} except that the \ltxarg{item} is expanded prior to performing the test.

\cmd{ifinlistcs}{item}{listcsname}

Similar to \ltxcmd{ifinlist} except that it takes a control sequence name as its second argument.

\cmd{xifinlistcs}{item}{listcsname}

Similar to \ltxcmd{xifinlist} except that it takes a control sequence name as its second argument.

\end{syntax}

\subsection{Miscellaneous tools}
\label{aut:msc}

\begin{syntax}

\cmd{rmntonum}{numeral}

The \tex primitive \ltxcmd{romannumeral} converts an integer to a Roman numeral but \tex or \latex provide no command which goes the opposite way. The \ltxcmd{rmntonum} command is such a macro which converts a Roman numeral to an integer. The parsing of the numeral is case"=insensitive. Since \ltxcmd{rmntonum} is expandable, it may be used in counter assignments, \ltxcmd{ifnum} comparisons, or in an \ltxcmd{edef}. For example:

\begin{lstlisting}[style=latex]{}
\setcounter{counter}{\rmntonum{CXVI}}
\ifnum\rmntonum{mcmxcviii}<2000 ...
\end{lstlisting}
%
Any invalid tokens in the \ltxarg{numeral} argument are silently ignored and have a numeric value of zero. Also note that \ltxcmd{rmntonum} will not check the numeral for formal validity. For example, both <v> and <vx> would yield <5>.

\end{syntax}

\section{Revision history}

\begin{changelog}

\begin{release}{1.3}{2007-10-08}

\item Renamed package from \sty{elatex} to \sty{etoolbox}\see{int}
\item Renamed \ltxcmd{newswitch} to \ltxcmd{newtoggle} (name clash)\see{aut:bo1:swi}
\item Renamed \ltxcmd{provideswitch} to \ltxcmd{providetoggle} (consistency)\see{aut:bo1:swi}
\item Renamed \ltxcmd{switchtrue} to \ltxcmd{toggletrue} (consistency)\see{aut:bo1:swi}
\item Renamed \ltxcmd{switchfalse} to \ltxcmd{togglefalse} (consistency)\see{aut:bo1:swi}
\item Renamed \ltxcmd{ifswitch} to \ltxcmd{iftoggle} (consistency)\see{aut:bo1:swi}
\item Renamed \ltxcmd{notswitch} to \ltxcmd{nottoggle} (consistency)\see{aut:bo1:swi}
\item Added \ltxcmd{undef}\see{aut:def}
\item Added \ltxcmd{csundef}\see{aut:def}
\item Added \ltxcmd{AtEndPreamble}\see{aut:pre}
\item Added \ltxcmd{AfterEndDocument}\see{aut:pre}
\item Added \ltxcmd{AfterPreamble}\see{aut:pre}
\item Added \ltxcmd{ifdefvoid}\see{aut:tst}
\item Added \ltxcmd{ifcsvoid}\see{aut:tst}
\item Added \ltxcmd{ifdefequal}\see{aut:tst}
\item Added \ltxcmd{ifcsequal}\see{aut:tst}
\item Added \ltxcmd{ifstrequal}\see{aut:tst}
\item Added \ltxcmd{listadd}\see{aut:lst:int}
\item Added \ltxcmd{listeadd}\see{aut:lst:int}
\item Added \ltxcmd{listgadd}\see{aut:lst:int}
\item Added \ltxcmd{listxadd}\see{aut:lst:int}
\item Added \ltxcmd{listcsadd}\see{aut:lst:int}
\item Added \ltxcmd{listcseadd}\see{aut:lst:int}
\item Added \ltxcmd{listcsgadd}\see{aut:lst:int}
\item Added \ltxcmd{listcsxadd}\see{aut:lst:int}
\item Added \ltxcmd{ifinlist}\see{aut:lst:int}
\item Added \ltxcmd{xifinlist}\see{aut:lst:int}
\item Added \ltxcmd{ifinlistcs}\see{aut:lst:int}
\item Added \ltxcmd{xifinlistcs}\see{aut:lst:int}
\item Added \ltxcmd{dolistloop}\see{aut:lst:int}
\item Added \ltxcmd{dolistcsloop}\see{aut:lst:int}

\end{release}

\begin{release}{1.2}{2007-07-13}

\item Renamed \ltxcmd{patchcommand} to \ltxcmd{patchcmd} (name clash)\see{aut:pat}
\item Renamed \ltxcmd{apptocommand} to \ltxcmd{apptocmd} (consistency)\see{aut:pat}
\item Renamed \ltxcmd{pretocommand} to \ltxcmd{pretocmd} (consistency)\see{aut:pat}
\item Added \ltxcmd{newbool}\see{aut:bo1:bol}
\item Added \ltxcmd{providebool}\see{aut:bo1:bol}
\item Added \ltxcmd{booltrue}\see{aut:bo1:bol}
\item Added \ltxcmd{boolfalse}\see{aut:bo1:bol}
\item Added \ltxcmd{ifbool}\see{aut:bo1:bol}
\item Added \ltxcmd{notbool}\see{aut:bo1:bol}
\item Added \ltxcmd{newswitch}\see{aut:bo1:swi}
\item Added \ltxcmd{provideswitch}\see{aut:bo1:swi}
\item Added \ltxcmd{switchtrue}\see{aut:bo1:swi}
\item Added \ltxcmd{switchfalse}\see{aut:bo1:swi}
\item Added \ltxcmd{ifswitch}\see{aut:bo1:swi}
\item Added \ltxcmd{notswitch}\see{aut:bo1:swi}
\item Added \ltxcmd{DeclareListParser}\see{aut:lst:inp}
\item Added \ltxcmd{docsvlist}\see{aut:lst:inp}
\item Added \ltxcmd{rmntonum}\see{aut:msc}

\end{release}

\begin{release}{1.1}{2007-05-28}

\item Added \ltxcmd{protected@csedef}\see{aut:def}
\item Added \ltxcmd{protected@csxdef}\see{aut:def}
\item Added \ltxcmd{gluedef}\see{aut:cal}
\item Added \ltxcmd{gluegdef}\see{aut:cal}
\item Added \ltxcmd{csgluedef}\see{aut:cal}
\item Added \ltxcmd{csgluegdef}\see{aut:cal}
\item Added \ltxcmd{mudef}\see{aut:cal}
\item Added \ltxcmd{mugdef}\see{aut:cal}
\item Added \ltxcmd{csmudef}\see{aut:cal}
\item Added \ltxcmd{csmugdef}\see{aut:cal}
\item Added \ltxcmd{protected@eappto}\see{aut:hok:app}
\item Added \ltxcmd{protected@xappto}\see{aut:hok:app}
\item Added \ltxcmd{protected@cseappto}\see{aut:hok:app}
\item Added \ltxcmd{protected@csxappto}\see{aut:hok:app}
\item Added \ltxcmd{protected@epreto}\see{aut:hok:pre}
\item Added \ltxcmd{protected@xpreto}\see{aut:hok:pre}
\item Added \ltxcmd{protected@csepreto}\see{aut:hok:pre}
\item Added \ltxcmd{protected@csxpreto}\see{aut:hok:pre}
\item Fixed bug in \ltxcmd{newrobustcmd}\see{use:def}
\item Fixed bug in \ltxcmd{renewrobustcmd}\see{use:def}
\item Fixed bug in \ltxcmd{providerobustcmd}\see{use:def}

\end{release}

\begin{release}{1.0}{2007-05-07}

\item Initial public release

\end{release}

\end{changelog}

\end{document}