The etoolbox Package

An e-TeX Toolbox for Class and Package Authors

Philipp Lehman, Joseph Wright Version v2.5k
joseph.wright@morningstar2.co.uk 2020/10/05

Contents
1 Introduction 1 3 Author Commands 6
1.1 About . . . . . . . . . . . 1 3.1 Definitions . . . . . . . . . 6
1.2 License . . . . . . . . . . . 1 3.2 Expansion Control . . . . 10
3.3 Hook Management . . . . 10
3.4 Patching . . . . . . . . . . 13
2 User Commands 2 3.5 Boolean Flags . . . . . . . 14
2.1 Definitions . . . . . . . . . 2 3.6 Generic Tests . . . . . . . 17
2.2 Patching . . . . . . . . . . 2 3.7 List Processing . . . . . . 28
2.3 Protection . . . . . . . . . 3 3.8 Miscellaneous Tools . . . 32
2.4 Lengths and Counters . . 3
4 Reporting issues 32
2.5 Document Hooks . . . . . 3
2.6 Environment Hooks . . . 5 5 Revision History 33

1 Introduction
1.1 About etoolbox
The etoolbox package is a toolbox of programming tools geared primarily towards
LaTeX class and package authors. It provides LaTeX frontends to some of the new
primitives provided by e-TeX as well as some generic tools which are not related to
e-TeX but match the profile of this package.

1.2 License
Copyright © 2007–2011 Philipp Lehman, 2015–2020 Joseph Wright. Permission is
granted to copy, distribute and/or modify this software under the terms of the LaTeX
Project Public License, version 1.3c or later.1

1
http://www.latex-project.org/lppl/

1
 2 User Commands
The tools in this section are geared towards regular users as well as class and pack-
age authors.

2.1 Definitions
\newrobustcmd{hcommandi}[hargumentsi][hoptarg defaulti]{hreplacement texti}
\newrobustcmd*{hcommandi}[hargumentsi][hoptarg defaulti]{hreplacement texti}

The syntax and behavior of this command is similar to \newcommand except that the
newly defined hcommandi will be robust. The behavior of this command differs from
the \DeclareRobustCommand command from the LaTeX kernel in that it issues an
error rather than just an informational message if the hcommandi is already defined.
Since it uses e-TeX’s low-level protection mechanism rather than the corresponding
higher-level LaTeX facilities, it does not require an additional macro to implement
the ‘robustness’.

\renewrobustcmd{hcommandi}[hargumentsi][hoptarg defaulti]{hreplacement texti}

\renewrobustcmd*{hcommandi}[hargumentsi][hoptarg defaulti]{hreplacement texti}

The syntax and behavior of this command is similar to \renewcommand except that
the redefined hcommandi will be robust.

\providerobustcmd{hcommandi}[hargumentsi][hoptarg defaulti]{hreplacement texti}

\providerobustcmd*{hcommandi}[hargumentsi][hoptarg defaulti]{hreplacement texti}

The syntax and behavior of this command is similar to \providecommand except that
the newly defined hcommandi will be robust. Note that this command will provide
a robust definition of the hcommandi only if it is undefined. It will not make an
already defined hcommandi robust.

2.2 Patching
\robustify{hcommandi}

Redefines a hcommandi defined with \newcommand such that it is robust, without

altering its parameters, its prefixes, or its replacement text. If the hcommandi has
been defined with \DeclareRobustCommand, this will be detected automatically and
LaTeX’s high-level protection mechanism will be replaced by the corresponding low-
level e-TeX feature.

2
 2.3 Protection
\protecting{hcodei}
This command applies LaTeX’s protection mechanism, which normally requires pre-
fixing each fragile command with \protect, to an entire chunk of arbitrary hcodei.
Its behavior depends on the current state of \protect. Note that the braces around
the hcodei are mandatory even if it is a single token.

2.4 Length and Counter Assignments

The tools in this section are replacements for \setcounter and \setlength which
support arithmetic expressions.
\defcounter{hcounteri}{hinteger expressioni}
Assigns a value to a LaTeX hcounteri previously initialized with \newcounter. This
command is similar in concept and syntax to \setcounter except for two major
differences. 1) The second argument may be an hinteger expressioni which will be
processed with \numexpr. The hinteger expressioni may be any arbitrary code which
is valid in this context. The value assigned to the hcounteri will be the result of
that calculation. 2) In contrast to \setcounter, the assignment is local by de-
fault but \defcounter may be prefixed with \global. The functional equivalent
of \setcounter would be \global\defcounter.
\deflength{hlengthi}{hglue expressioni}
Assigns a value to a hlengthi register previously initialized with \newlength. This
command is similar in concept and syntax to \setlength except that the second
argument may be a hglue expressioni which will be processed with \glueexpr. The
hglue expressioni may be any arbitrary code which is valid in this context. The value
assigned to the hlengthi register will be the result of that calculation. The assignment
is local by default but \deflength may be prefixed with \global. This command
may be used as a drop-in replacement for \setlength.

2.5 Additional Document Hooks

LaTeX provides two hooks which defer the execution of code either to the beginning
or to the end of the document body. Any \AtBeginDocument code is executed to-
wards the beginning of the document body, after the main aux file has been read
for the first time. Any \AtEndDocument code is executed at the end of the document
body, before the main aux file is read for the second time. The hooks introduced here
are similar in concept but defer the execution of their hcodei argument to slightly dif-
ferent locations. The hcodei may be arbitrary TeX code. Parameter characters in the
hcodei argument are permissible and need not be doubled.

3
 \AfterPreamble{hcodei}

This hook is a variant of \AtBeginDocument which may be used in both the pream-
ble and the document body. When used in the preamble, it behaves exactely like
\AtBeginDocument. When used in the document body, it immediately executes its
hcodei argument. \AtBeginDocument would issue an error in this case. This hook is
useful to defer code which needs to write to the main aux file.

\AtEndPreamble{hcodei}

This hook differs from \AtBeginDocument in that the hcodei is executed right at the
end of the preamble, before the main aux file (as written on the previous LaTeX
pass) is read and prior to any \AtBeginDocument code. Note that it is not possible
to write to the aux file at this point.

\AfterEndPreamble{hcodei}

This hook differs from \AtBeginDocument in that the hcodei is executed at the very
end of \begin{document}, after any \AtBeginDocument code. Note that commands
whose scope has been restricted to the preamble with \@onlypreamble are no longer
available when this hook is executed.

\AfterEndDocument{hcodei}

This hook differs from \AtEndDocument in that the hcodei is executed at the very
end of the document, after the main aux file (as written on the current LaTeX pass)
has been read and after any \AtEndDocument code.

In a way, \AtBeginDocument code is part neither of the preamble nor the docu-
ment body but located in-between them since it gets executed in the middle of the
initialization sequence performed prior to typesetting. It is sometimes desirable to
move code to the end of the preamble because all requested packages have been
loaded at this point. \AtBeginDocument code, however, is executed too late if it
is required in the aux file. In contrast to that, \AtEndPreamble code is part of the
preamble; \AfterEndPreamble code is part of the document body and may contain
printable text to be typeset at the very beginning of the document. To sum that up,
LaTeX will perform the following tasks ‘inside’ \begin{document}:

• Execute any \AtEndPreamble code

• Start initialization for document body (page layout, default fonts, etc.)
• Load the main aux file written on the previous LaTeX pass
• Open the main aux file for writing on the current pass
• Continue initialization for document body

4
 • Execute any \AtBeginDocument code
• Complete initialization for document body
• Disable all \@onlypreamble commands
• Execute any \AfterEndPreamble code

Inside \end{document}, LaTeX will perform the following tasks:

• Execute any \AtEndDocument code

• Perform a final \clearpage operation
• Close the main aux file for writing
• Load the main aux file written on the current LaTeX pass
• Perform final tests and issue warnings, if applicable
• Execute any \AfterEndDocument code

Any \AtEndDocument code may be considered as being part of the document body
insofar as it is still possible to perform typesetting tasks and write to the main aux
file when it gets executed. \AfterEndDocument code is not part of the document
body. This hook is useful to evaluate the data in the aux file at the very end of a
LaTeX pass.

2.6 Environment Hooks

The tools in this section provide hooks for arbitrary environments. Note that they
will not modify the definition of the henvironmenti. They hook into the \begin
and \end commands instead. Redefining the henvironmenti will not clear the corre-
sponding hooks. The hcodei may be arbitrary TeX code. Parameter characters in the
hcodei argument are permissible and need not be doubled.

\AtBeginEnvironment{henvironmenti}{hcodei}

Appends arbitrary hcodei to a hook executed by the \begin command at the begin-
ning of a given henvironmenti, immediately before \henvironmenti, inside the group
opened by \begin.

\AtEndEnvironment{henvironmenti}{hcodei}

Appends arbitrary hcodei to a hook executed by the \end command at the end
of a given henvironmenti, immediately before \endhenvironmenti, inside the group
opened by \begin.

5
\BeforeBeginEnvironment{henvironmenti}{hcodei}
Appends arbitrary hcodei to a hook executed at a very early point by the \begin
command, before the group holding the environment is opened.
\AfterEndEnvironment{henvironmenti}{hcodei}
Appends arbitrary hcodei to a hook executed at a very late point by the \end com-
mand, after the group holding the environment has been closed.

3 Author Commands
The tools in this section are geared towards class and package authors.

3.1 Definitions
3.1.1 Macro Definitions
The tools in this section are simple but frequently required shorthands which extend
the scope of the \@namedef and \@nameuse macros from the LaTeX kernel.

\csdef{hcsnamei}hargumentsi{hreplacement texti}
Similar to the TeX primitive \def except that it takes a control sequence name as its
first argument. This command is robust and corresponds to \@namedef.
\csgdef{hcsnamei}hargumentsi{hreplacement texti}
Similar to the TeX primitive \gdef except that it takes a control sequence name as
its first argument. This command is robust.
\csedef{hcsnamei}hargumentsi{hreplacement texti}
Similar to the TeX primitive \edef except that it takes a control sequence name as
its first argument. This command is robust.
\csxdef{hcsnamei}hargumentsi{hreplacement texti}
Similar to the TeX primitive \xdef except that it takes a control sequence name as
its first argument. This command is robust.
\protected@csedef{hcsnamei}hargumentsi{hreplacement texti}
Similar to \csedef except that LaTeX’s protection mechanism is temporarily en-
abled. To put it in other words: this command is similar to the LaTeX kernel com-
mand \protected@edef except that it takes a control sequence name as its first
argument. This command is robust.

6
\protected@csxdef{hcsnamei}hargumentsi{hreplacement texti}

Similar to \csxdef except that LaTeX’s protection mechanism is temporarily en-

abled. To put it in other words: this command is similar to the LaTeX kernel com-
mand \protected@xdef except that it takes a control sequence name as its first
argument. This command is robust.

\cslet{hcsnamei}{hcommandi}

Similar to the TeX primitive \let except that the first argument is a control sequence
name. If hcommandi is undefined, hcsnamei will be undefined as well after the
assignment. This command is robust and may be prefixed with \global.

\letcs{hcommandi}{hcsnamei}

Similar to the TeX primitive \let except that the second argument is a control se-
quence name. If hcsnamei is undefined, the hcommandi will be undefined as well
after the assignment. This command is robust and may be prefixed with \global.

\csletcs{hcsnamei}{hcsnamei}

Similar to the TeX primitive \let except that both arguments are control sequence
names. If the second hcsnamei is undefined, the first hcsnamei will be undefined
as well after the assignment. This command is robust and may be prefixed with
\global.

\csuse{hcsnamei}

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

\undefhcommandi

Clears a hcommandi such that e-TeX’s \ifdefined and \ifcsname tests will consider
it as undefined. This command is robust and may be prefixed with \global.

\gundefhcommandi

Similar to \undef but acts globally.

\csundef{hcsnamei}

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

7
 \csgundef{hcsnamei}
Similar to \csundef but acts globally.
\csmeaning{hcsnamei}
Similar to the TeX primitive \meaning but takes a control sequence name as its
argument. If the control sequence is undefined, this command will not implicitly
assign a meaning of \relax to it.
\csshow{hcsnamei}
Similar to the TeX primitive \show but takes a control sequence name as its argu-
ment. If the control sequence is undefined, this command will not implicitly assign
a meaning of \relax to it. This command is robust.

3.1.2 Arithmetic Definitions

The tools in this section permit calculations using macros rather than length registers
and counters.
\numdefhcommandi{hinteger expressioni}
Similar to \edef except that the hinteger expressioni is processed with \numexpr.
The hinteger expressioni may be any arbitrary code which is valid in this context. The
replacement text assigned to the hcommandi will be the result of that calculation. If
the hcommandi is undefined, it will be initialized to 0 before the hinteger expressioni
is processed.
\numgdefhcommandi{hinteger expressioni}
Similar to \numdef except that the assignment is global.
\csnumdef{hcsnamei}{hinteger expressioni}
Similar to \numdef except that it takes a control sequence name as its first argument.
\csnumgdef{hcsnamei}{hinteger expressioni}
Similar to \numgdef except that it takes a control sequence name as its first argu-
ment.
\dimdefhcommandi{hdimen expressioni}
Similar to \edef except that the hdimen expressioni is processed with \dimexpr. The
hdimen expressioni may be any arbitrary code which is valid in this context. The
replacement text assigned to the hcommandi will be the result of that calculation. If
the hcommandi is undefined, it will be initialized to 0pt before the hdimen expressioni
is processed.

8
 \dimgdefhcommandi{hdimen expressioni}

Similar to \dimdef except that the assignment is global.

\csdimdef{hcsnamei}{hdimen expressioni}

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

\csdimgdef{hcsnamei}{hdimen expressioni}

Similar to \dimgdef except that it takes a control sequence name as its first argu-
ment.

\gluedefhcommandi{hglue expressioni}

Similar to \edef except that the hglue expressioni is processed with \glueexpr. The
hglue expressioni may be any arbitrary code which is valid in this context. The re-
placement text assigned to the hcommandi will be the result of that calculation. If
the hcommandi is undefined, it will be initialized to 0pt plus 0pt minus 0pt be-
fore the hglue expressioni is processed.

\gluegdefhcommandi{hglue expressioni}

Similar to \gluedef except that the assignment is global.

\csgluedef{hcsnamei}{hglue expressioni}

Similar to \gluedef except that it takes a control sequence name as its first argu-
ment.

\csgluegdef{hcsnamei}{hglue expressioni}

Similar to \gluegdef except that it takes a control sequence name as its first argu-
ment.

\mudefhcommandi{hmuglue expressioni}

Similar to \edef except that the hmuglue expressioni is processed with \muexpr. The
hmuglue expressioni may be any arbitrary code which is valid in this context. The re-
placement text assigned to the hcommandi will be the result of that calculation. If the
hcommandi is undefined, it will be initialized to 0mu before the hmuglue expressioni
is processed.

\mugdefhcommandi{hmuglue expressioni}

Similar to \mudef except that the assignment is global.

9
 \csmudef{hcsnamei}{hmuglue expressioni}

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

\csmugdef{hcsnamei}{hmuglue expressioni}

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

3.2 Expansion Control

The tools in this section are useful to control expansion in an \edef or a similar
context.

\expandoncehcommandi

This command expands a hcommandi once and prevents further expansion of the
replacement text. This command is expandable.

\csexpandonce{hcsnamei}

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

3.3 Hook Management

The tools in this section are intended for hook management. A hhooki in this context
is a plain macro without any parameters and prefixes which is used to collect code
to be executed later. These tools may also be useful to patch simple macros by ap-
pending code to their replacement text. For more complex patching operations, see
section 3.4. All commands in this section will initialize the hhooki if it is undefined.

3.3.1 Appending to a Hook

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

\apptohhooki{hcodei}

This command appends arbitrary hcodei to a hhooki. If the hcodei contains any pa-
rameter characters, they need not be doubled. This command is robust.

\gapptohhooki{hcodei}

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

10
 \eapptohhooki{hcodei}

This command appends arbitrary hcodei to a hhooki. The hcodei is expanded at

definition-time. Only the new hcodei is expanded, the current replacement text of
the hhooki is not. This command is robust.

\xapptohhooki{hcodei}

Similar to \eappto except that the assignment is global.

\protected@eapptohhooki{hcodei}

Similar to \eappto except that LaTeX’s protection mechanism is temporarily en-

abled.

\protected@xapptohhooki{hcodei}

Similar to \xappto except that LaTeX’s protection mechanism is temporarily en-

abled.

\csappto{hcsnamei}{hcodei}

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

\csgappto{hcsnamei}{hcodei}

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

\cseappto{hcsnamei}{hcodei}

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

\csxappto{hcsnamei}{hcodei}

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

\protected@cseapptohhooki{hcodei}

Similar to \protected@eappto except that it takes a control sequence name as its

first argument.

\protected@csxapptohhooki{hcodei}

Similar to \protected@xappto except that it takes a control sequence name as its

first argument.

11
 3.3.2 Prepending to a Hook
The tools in this section ‘prepend’ arbitrary code to a hook, i. e., the code is inserted
at the beginning of the hook rather than being added at the end.

\pretohhooki{hcodei}
Similar to \appto except that the hcodei is prepended.
\gpretohhooki{hcodei}
Similar to \preto except that the assignment is global.
\epretohhooki{hcodei}
Similar to \eappto except that the hcodei is prepended.
\xpretohhooki{hcodei}
Similar to \epreto except that the assignment is global.
\protected@epretohhooki{hcodei}
Similar to \epreto except that LaTeX’s protection mechanism is temporarily en-
abled.
\protected@xpretohhooki{hcodei}
Similar to \xpreto except that LaTeX’s protection mechanism is temporarily en-
abled.
\cspreto{hcsnamei}{hcodei}
Similar to \preto except that it takes a control sequence name as its first argument.
\csgpreto{hcsnamei}{hcodei}
Similar to \gpreto except that it takes a control sequence name as its first argument.
\csepreto{hcsnamei}{hcodei}
Similar to \epreto except that it takes a control sequence name as its first argument.
\csxpreto{hcsnamei}{hcodei}
Similar to \xpreto except that it takes a control sequence name as its first argument.
\protected@csepretohhooki{hcodei}
Similar to \protected@epreto except that it takes a control sequence name as its
first argument.

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

3.4 Patching
The tools in this section are useful to hook into or modify existing code. All com-
mands presented here preserve the parameters and the prefixes of the patched
hcommandi. Note that \outer commands may not be patched. Also note that the
commands in this section will not automatically issue any error messages if patching
fails. Instead, they take a hfailurei argument which should provide suitable fallback
code or an error message. Issuing \tracingpatches in the preamble will cause the
commands to write debugging information to the transcript file.

\patchcmd[hprefixi]{hcommandi}{hsearchi}{hreplacei}{hsuccessi}{hfailurei}
This command extracts the replacement text of a hcommandi, replaces hsearchi with
hreplacei, and reassembles the hcommandi. The pattern match is category code ag-
nostic and matches the first occurence of the hsearchi pattern in the replacement
text of the hcommandi to be patched. Note that the patching process involves deto-
kenizing the replacement text of the hcommandi and retokenizing it under the cur-
rent category code regime after patching. The category code of the @ sign is tem-
porarily set to 11. If the replacement text of the hcommandi 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 hcommandi to be patched, the parameter characters need not be doubled.
If an optional hprefixi is specified, it replaces the prefixes of the hcommandi. An
empty hprefixi argument strips all prefixes from the hcommandi. The assignment is
local. This command implicitly performs the equivalent of an \ifpatchable test
prior to patching. If this test succeeds, the command applies the patch and exe-
cutes hsuccessi. If the test fails, it executes hfailurei without modifying the original
hcommandi. This command is robust.
\ifpatchable{hcommandi}{hsearchi}{htruei}{hfalsei}
This command executes htruei if the hcommandi may be patched with \patchcmd
and if the hsearchi pattern is found in its replacement text, and hfalsei otherwise.
This command is robust.
\ifpatchable*{hcommandi}{htruei}{hfalsei}
Similar to \ifpatchable except that the starred variant does not require a search
pattern. Use this version to check if a command may be patched with \apptocmd
and \pretocmd.

13
 \apptocmd{hcommandi}{hcodei}{hsuccessi}{hfailurei}

This command appends hcodei to the replacement text of a hcommandi. If the

hcommandi is a parameterless macro, it behaves like \appto from section 3.3.1.
In contrast to \appto, \apptocmd may also be used to patch commands with param-
eters. In this case, it will detokenize the replacement text of the hcommandi, apply
the patch, and retokenize it under the current category code regime. The category
code of the @ sign is temporarily set to 11. The hcodei may refer to the parameters
of the hcommandi. The assignment is local. If patching succeeds, this command exe-
cutes hsuccessi. If patching fails, it executes hfailurei without modifying the original
hcommandi. This command is robust.

\pretocmd{hcommandi}{hcodei}{hsuccessi}{hfailurei}

This command is similar to \apptocmd except that the hcodei is inserted at the begin-
ning of the replacement text of the hcommandi. If the hcommandi is a parameterless
macro, it behaves like \preto from section 3.3.1. In contrast to \preto, \pretocmd
may also be used to patch commands with parameters. In this case, it will detokenize
the replacement text of the hcommandi, apply the patch, and retokenize it under the
current category code regime. The category code of the @ sign is temporarily set
to 11. The hcodei may refer to the parameters of the hcommandi. The assignment
is local. If patching succeeds, this command executes hsuccessi. If patching fails,
it executes hfailurei without modifying the original hcommandi. This command is
robust.

\tracingpatches Enables tracing for all patching commands, including \ifpatchable. The debug-
ging information will be written to the transcript file. This is useful if the reason
why a patch is not applied or \ifpatchable yields hfalsei is not obvious. This com-
mand must be issued in the preamble.

3.5 Boolean Flags

This package provides two interfaces to boolean flags which are completely inde-
pendent of each other. The tools in section 3.5.1 are a LaTeX frontend to \newif.
Those in section 3.5.2 use a different mechanism.

3.5.1 TeX Flags

Since the tools in this section are based on \newif internally, they may be used
to test and alter the state of flags previously defined with \newif. They are also
compatible with the boolean tests of the ifthen package and may serve as a LaTeX
interface for querying TeX primitives such as \ifmmode. The \newif approach re-
quires a total of three macros per flag.

14
 \newbool{hnamei}
Defines a new boolean flag called hnamei. If the flag has already been defined, this
command issues an error. The initial state of newly defined flags is false. This
command is robust.
\providebool{hnamei}
Defines a new boolean flag called hnamei unless it has already been defined. This
command is robust.
\booltrue{hnamei}
Sets the boolean flag hnamei to true. This command is robust and may be prefixed
with \global. It will issue an error if the flag is undefined.
\boolfalse{hnamei}
Sets the boolean flag hnamei to false. This command is robust and may be prefixed
with \global. It will issue an error if the flag is undefined.
\setbool{hnamei}{hvaluei}
Sets the boolean flag hnamei to hvaluei which may be either true or false. This
command is robust and may be prefixed with \global. It will issue an error if the
flag is undefined.
\ifbool{hnamei}{htruei}{hfalsei}
Expands to htruei if the state of the boolean flag hnamei is true, and to hfalsei
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, i. e., any test
normally employed like this:
\iftest true\else false\fi

This includes all flags defined with \newif as well as TeX primitives such as \ifmmode.
The \if prefix is omitted when using the flag or the primitive in the expression. For
example:
\ifmytest true\else false\fi
\ifmmode true\else false\fi

becomes
\ifbool{mytest}{true}{false}
\ifbool{mmode}{true}{false}

15
 \notbool{hnamei}{hnot truei}{hnot falsei}

Similar to \ifbool but negates the test.

3.5.2 LaTeX Flags

In contrast to the flags from section 3.5.1, the tools in this section require only one
macro per flag. They also use a separate namespace to avoid name clashes with
regular macros.

\newtoggle{hnamei}

Defines a new boolean flag called hnamei. If the flag has already been defined, this
command issues an error. The initial state of newly defined flags is false. This
command is robust.

\providetoggle{hnamei}

Defines a new boolean flag called hnamei unless it has already been defined. This
command is robust.

\toggletrue{hnamei}

Sets the boolean flag hnamei to true. This command is robust and may be prefixed
with \global. It will issue an error if the flag is undefined.

\togglefalse{hnamei}

Sets the boolean flag hnamei to false. This command is robust and may be prefixed
with \global. It will issue an error if the flag is undefined.

\settoggle{hnamei}{hvaluei}

Sets the boolean flag hnamei to hvaluei which may be either true or false. This
command is robust and may be prefixed with \global. It will issue an error if the
flag is undefined.

\iftoggle{hnamei}{htruei}{hfalsei}

Expands to htruei if the state of the boolean flag hnamei is true, and to hfalsei
otherwise. If the flag is undefined, this command issues an error.

16
 \nottoggle{hnamei}{hnot truei}{hnot falsei}

Similar to \iftoggle but negates the test.

3.6 Generic Tests

3.6.1 Macro Tests
\ifdef{hcontrol sequencei}{htruei}{hfalsei}

Expands to htruei if the hcontrol sequencei is defined, and to hfalsei otherwise. Note
that control sequences will be considered as defined even if their meaning is \relax.
This command is a LaTeX wrapper for the e-TeX primitive \ifdefined.

\ifcsdef{hcsnamei}{htruei}{hfalsei}

Similar to \ifdef except that it takes a control sequence name as its first argument.
This command is a LaTeX wrapper for the e-TeX primitive \ifcsname.

\ifundef{hcontrol sequencei}{htruei}{hfalsei}

Expands to htruei if the hcontrol sequencei is undefined, and to hfalsei otherwise.

Apart from reversing the logic of the test, this command also differs from \ifdef in
that commands will be considered as undefined if their meaning is \relax.

\ifcsundef{hcsnamei}{htruei}{hfalsei}

Similar to \ifundef except that it takes a control sequence name as its first argu-
ment. This command may be used as a drop-in replacement for the \@ifundefined
test in the LaTeX kernel.

\ifdefmacro{hcontrol sequencei}{htruei}{hfalsei}

Expands to htruei if the hcontrol sequencei is defined and is a macro, and to hfalsei
otherwise.

\ifcsmacro{hcsnamei}{htruei}{hfalsei}

Similar to \ifdefmacro except that it takes a control sequence name as its first
argument.

\ifdefparam{hcontrol sequencei}{htruei}{hfalsei}

Expands to htruei if the hcontrol sequencei is defined and is a macro with one or more
parameters, and to hfalsei otherwise.

17
 \ifcsparam{hcsnamei}{htruei}{hfalsei}

Similar to \ifdefparam except that it takes a control sequence name as its first
argument.

\ifdefprefix{hcontrol sequencei}{htruei}{hfalsei}

Expands to htruei if the hcontrol sequencei is defined and is a macro prefixed with
\long and/or \protected, and to hfalsei otherwise. Note that \outer macros may
not be tested.

\ifcsprefix{hcsnamei}{htruei}{hfalsei}

Similar to \ifdefprefix except that it takes a control sequence name as its first
argument.

\ifdefprotected{hcontrol sequencei}{htruei}{hfalsei}

Expands to htruei if the hcontrol sequencei is defined and is a macro prefixed with
\protected, and to hfalsei otherwise.

\ifcsprotected{hcsnamei}{htruei}{hfalsei}

Similar to \ifdefprotected except that it takes a control sequence name as its first
argument.

\ifdefltxprotect{hcontrol sequencei}{htruei}{hfalsei}

Executes htruei if the hcontrol sequencei is defined and is a LaTeX protection shell,
and hfalsei otherwise. This command is robust. It will detect commands which have
been defined with \DeclareRobustCommand or by way of a similar technique.

\ifcsltxprotect{hcsnamei}{htruei}{hfalsei}

Similar to \ifdefltxprotect except that it takes a control sequence name as its

first argument.

\ifdefempty{hcontrol sequencei}{htruei}{hfalsei}

Expands to htruei if the hcontrol sequencei is defined and is a parameterless macro

whose replacement text is empty, and to hfalsei otherwise. In contrast to \ifx, this
test ignores the prefixes of the hcommandi.

\ifcsempty{hcsnamei}{htruei}{hfalsei}

Similar to \ifdefempty except that it takes a control sequence name as its first
argument.

18
 \ifdefvoid{hcontrol sequencei}{htruei}{hfalsei}

Expands to htruei if the hcontrol sequencei is undefined, or is a control sequence

whose meaning is \relax, or is a parameterless macro whose replacement text is
empty, and to hfalsei otherwise.

\ifcsvoid{hcsnamei}{htruei}{hfalsei}

Similar to \ifdefvoid except that it takes a control sequence name as its first argu-
ment.

\ifdefequal{hcontrol sequencei}{hcontrol sequencei}{htruei}{hfalsei}

Compares two control sequences and expands to htruei if they are equal in the sense
of \ifx, and to hfalsei otherwise. In contrast to \ifx, this test will also yield hfalsei
if both control sequences are undefined or have a meaning of \relax.

\ifcsequal{hcsnamei}{hcsnamei}{htruei}{hfalsei}

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

\ifdefstring{hcommandi}{hstringi}{htruei}{hfalsei}

Compares the replacement text of a hcommandi to a hstringi and executes htruei

if they are equal, and hfalsei otherwise. Neither the hcommandi nor the hstringi is
expanded in the test and the comparison is category code agnostic. Control sequence
tokens in the hstringi argument will be detokenized and treated as strings. This
command is robust. Note that it will only consider the replacement text of the
hcommandi. For example, this test

\long\edef\mymacro#1#2{\string&}
\ifdefstring{\mymacro}{&}{true}{false}

would yield htruei. The prefix and the parameters of \mymacro as well as the cate-
gory codes in the replacement text are ignored.

\ifcsstring{hcsnamei}{hstringi}{htruei}{hfalsei}

Similar to \ifdefstring except that it takes a control sequence name as its first
argument.

\ifdefstrequal{hcommandi}{hcommandi}{htruei}{hfalsei}

Performs a category code agnostic string comparison of the replacement text of two
commands. This command is similar to \ifdefstring except that both arguments
to be compared are macros. This command is robust.

19
\ifcsstrequal{hcsnamei}{hcsnamei}{htruei}{hfalsei}

Similar to \ifdefstrequal except that it takes control sequence names as argu-

ments.

3.6.2 Counter and Length Tests

\ifdefcounter{hcontrol sequencei}{htruei}{hfalsei}

Expands to htruei if the hcontrol sequencei is a TeX \count register allocated with
\newcount, and to hfalsei otherwise.

\ifcscounter{hcsnamei}{htruei}{hfalsei}

Similar to \ifdefcounter except that it takes a control sequence name as its first
argument.

\ifltxcounter{hnamei}{htruei}{hfalsei}

Expands to htruei if hnamei is a LaTeX counter allocated with \newcounter, and to

hfalsei otherwise.

\ifdeflength{hcontrol sequencei}{htruei}{hfalsei}

Expands to htruei if the hcontrol sequencei is a TeX \skip register allocated with
\newskip or \newlength, and to hfalsei otherwise.

\ifcslength{hcsnamei}{htruei}{hfalsei}

Similar to \ifdeflength except that it takes a control sequence name as its first
argument.

\ifdefdimen{hcontrol sequencei}{htruei}{hfalsei}

Expands to htruei if the hcontrol sequencei is a TeX \dimen register allocated with
\newdimen, and to hfalsei otherwise.

\ifcsdimen{hcsnamei}{htruei}{hfalsei}

Similar to \ifdefdimen except that it takes a control sequence name as its first
argument.

20
 3.6.3 String Tests
\ifstrequal{hstringi}{hstringi}{htruei}{hfalsei}
Compares two strings and executes htruei if they are equal, and hfalsei otherwise.
The strings are not expanded in the test and the comparison is category code agnos-
tic. Control sequence tokens in any of the hstringi arguments will be detokenized
and treated as strings. This command is robust.
\ifstrempty{hstringi}{htruei}{hfalsei}
Expands to htruei if the hstringi is empty, and to hfalsei otherwise. The hstringi is not
expanded in the test.
\ifblank{hstringi}{htruei}{hfalsei}
Expands to htruei if the hstringi is blank (empty or spaces), and to hfalsei otherwise.
The hstringi is not expanded in the test.
\notblank{hstringi}{hnot truei}{hnot falsei}
Similar to \ifblank but negates the test.

3.6.4 Arithmetic Tests

\ifnumcomp{hinteger expressioni}{hrelationi}{hinteger expressioni}{htruei}{hfalsei}
Compares two integer expressions according to hrelationi and expands to htruei or
hfalsei depending on the result. The hrelationi may be <, >, or =. Both integer
expressions will be processed with \numexpr. An hinteger expressioni may be any
arbitrary code which is valid in this context. All arithmetic expressions may contain
spaces. Here are some examples:
\ifnumcomp{3}{>}{6}{true}{false}
\ifnumcomp{(7 + 5) / 2}{=}{6}{true}{false}
\ifnumcomp{(7+5) / 4}{>}{3*(12-10)}{true}{false}
\newcounter{countA}
\setcounter{countA}{6}
\newcounter{countB}
\setcounter{countB}{5}
\ifnumcomp{\value{countA} * \value{countB}/2}{=}{15}{true}{false}
\ifnumcomp{6/2}{=}{5/2}{true}{false}

Technically, this command is a LaTeX wrapper for the TeX primitive \ifnum, incorpo-
rating \numexpr. Note that \numexpr will round the result of all integer expressions,
i. e., both expressions will be processed and rounded prior to being compared. In
the last line of the above examples, the result of the second expression is 2.5, which
is rounded to 3, hence \ifnumcomp will expand to htruei.

21
 \ifnumequal{hinteger expressioni}{hinteger expressioni}{htruei}{hfalsei}

Alternative syntax for \ifnumcomp{...}{=}{...}{...}{...}.

\ifnumgreater{hinteger expressioni}{hinteger expressioni}{htruei}{hfalsei}

Alternative syntax for \ifnumcomp{...}{>}{...}{...}{...}.

\ifnumless{hinteger expressioni}{hinteger expressioni}{htruei}{hfalsei}

Alternative syntax for \ifnumcomp{...}{<}{...}{...}{...}.

\ifnumodd{hinteger expressioni}{htruei}{hfalsei}

Evaluates an integer expression and expands to htruei if the result is an odd number,
and to hfalsei otherwise. Technically, this command is a LaTeX wrapper for the TeX
primitive \ifodd, incorporating \numexpr.

\ifdimcomp{hdimen expressioni}{hrelationi}{hdimen expressioni}{htruei}{hfalsei}

Compares two dimen expressions according to hrelationi and expands to htruei or

hfalsei depending on the result. The hrelationi may be <, >, or =. Both dimen expres-
sions will be processed with \dimexpr. A hdimen expressioni may be any arbitrary
code which is valid in this context. All arithmetic expressions may contain spaces.
Here are some examples:

\ifdimcomp{1cm}{=}{28.45274pt}{true}{false}
\ifdimcomp{(7pt + 5pt) / 2}{<}{2pt}{true}{false}
\ifdimcomp{(3.725pt + 0.025pt) * 2}{<}{7pt}{true}{false}
\newlength{\lengthA}
\setlength{\lengthA}{7.25pt}
\newlength{\lengthB}
\setlength{\lengthB}{4.75pt}
\ifdimcomp{(\lengthA + \lengthB) / 2}{>}{2.75pt * 2}{true}{false}
\ifdimcomp{(\lengthA + \lengthB) / 2}{>}{25pt / 6}{true}{false}

Technically, this command is a LaTeX wrapper for the TeX primitive \ifdim, incor-
porating \dimexpr. Since both \ifdimcomp and \ifnumcomp are expandable, they
may also be nested:

\ifnumcomp{\ifdimcomp{5pt+5pt}{=}{10pt}{1}{0}}{>}{0}{true}{false}

\ifdimequal{hdimen expressioni}{hdimen expressioni}{htruei}{hfalsei}

Alternative syntax for \ifdimcomp{...}{=}{...}{...}{...}.

22
 \ifdimgreater{hdimen expressioni}{hdimen expressioni}{htruei}{hfalsei}
Alternative syntax for \ifdimcomp{...}{>}{...}{...}{...}.
\ifdimless{hdimen expressioni}{hdimen expressioni}{htruei}{hfalsei}
Alternative syntax for \ifdimcomp{...}{<}{...}{...}{...}.

3.6.5 Boolean Expressions

The commands in this section are replacements for the \ifthenelse command pro-
vided by the ifthen package. They serve the same purpose but differ in syntax,
concept, and implementation. In contrast to \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.

\ifboolexpr{hexpressioni}{htruei}{hfalsei}
Evaluates the hexpressioni and executes htruei if it is true, and hfalsei otherwise. The
hexpressioni is evaluated sequentially from left to right. The following elements,
discussed in more detail below, are available in the hexpressioni: the test operators
togl, bool, test; the logical operators not, and, or; and the subexpression delimiter
(...). Spaces, tabs, and line endings may be used freely to arrange the hexpressioni
visually. Blank lines are not permissible in the hexpressioni. This command is robust.
\ifboolexpe{hexpressioni}{htruei}{hfalsei}
An expandable version of \ifboolexpr which may be processed in an expansion-
only context, e. g., in an \edef or in a \write operation. Note that all tests used
in the hexpressioni must be expandable, even if \ifboolexpe is not located in an
expansion-only context.
\whileboolexpr{hexpressioni}{hcodei}
Evaluates the hexpressioni like \ifboolexpr and repeatedly executes the hcodei while
the expression is true. The hcodei may be any valid TeX or LaTeX code. This com-
mand is robust.
\unlessboolexpr{hexpressioni}{hcodei}
Similar to \whileboolexpr but negates the hexpressioni, i. e., it keeps executing the
hcodei repeatedly unless the expression is true. This command is robust.

The following test operators are available in the hexpressioni:

togl Use the togl operator to test the state of a flag defined with \newtoggle. For
example:

23
 \iftoggle{mytoggle}{true}{false}

becomes

\ifboolexpr{ togl {mytoggle} }{true}{false}

The togl operator may be used with both \ifboolexpr and \ifboolexpe.

bool Use the bool operator to perform a boolean test based on plain TeX syntax, i. e., any
test normally employed like this:

\iftest true\else false\fi

This includes all flags defined with \newif as well as TeX primitives such as \ifmmode.
The \if prefix is omitted when using the flag or the primitive in the expression. For
example:

\ifmmode true\else false\fi

\ifmytest true\else false\fi

becomes

\ifboolexpr{ bool {mmode} }{true}{false}

\ifboolexpr{ bool {mytest} }{true}{false}

This also works with flags defined with \newbool (see § 3.5.1). In this case

\ifbool{mybool}{true}{false}

becomes

\ifboolexpr{ bool {mybool} }{true}{false}

The bool operator may be used with both \ifboolexpr and \ifboolexpe.

test Use the test operator to perform a test based on LaTeX syntax, i. e., any test nor-
mally employed like this:

\iftest{true}{false}

This applies to all macros based on LaTeX syntax, i. e., the macro must take a htruei
and a hfalsei argument and these must be the final arguments. For example:

24
 \ifdef{\somemacro}{true}{false}
\ifdimless{\textwidth}{365pt}{true}{false}
\ifnumcomp{\value{somecounter}}{>}{3}{true}{false}

When using such tests in the hexpressioni, their htruei and hfalsei arguments are
omitted. For example:
\ifcsdef{mymacro}{true}{false}

becomes
\ifboolexpr{ test {\ifcsdef{mymacro}} }{true}{false}

and
\ifnumcomp{\value{mycounter}}{>}{3}{true}{false}

becomes
\ifboolexpr{
test {\ifnumcomp{\value{mycounter}}{>}{3}}
}
{true}
{false}

The test operator may be used with \ifboolexpr without any restrictions. It may
also be used with \ifboolexpe, provided that the test is expandable. Some of the
generic tests in § 3.6 are robust and may not be used with \ifboolexpe, even if
\ifboolexpe is not located in an expansion-only context. Use \ifboolexpr instead
if the test is not expandable.

Since \ifboolexpr and \ifboolexpe imply processing overhead, there is gener-

ally no benefit in employing them for a single test. The stand-alone tests in § 3.6
are more efficient than test, \ifbool from § 3.5.1 is more efficient than bool, and
\iftoggle from § 3.5.2 is more efficient than togl. The point of \ifboolexpr and
\ifboolexpe is that they support logical operators and subexpressions. The follow-
ing logical operators are available in the hexpressioni:

not The not operator negates the truth value of the immediately following element. You
may prefix togl, bool, test, and subexpressions with not. For example:
\ifboolexpr{
not bool {mybool}
}
{true}
{false}

25
 will yield htruei if mybool is false and hfalsei if mybool is true, and

\ifboolexpr{
not ( bool {boolA} or bool {boolB} )
}
{true}
{false}

will yield htruei if both boolA and boolB are false.

and The and operator expresses a conjunction (both a and b). The hexpressioni is true if
all elements joined with and are true. For example:

\ifboolexpr{
bool {boolA} and bool {boolB}
}
{true}
{false}

will yield htruei if both bool tests are true. The nand operator (negated and, i. e.,
not both) is not provided as such but may be expressed by using and in a negated
subexpression. For example:

bool {boolA} nand bool {boolB}

may be written as

not ( bool {boolA} and bool {boolB} )

or The or operator expresses a non-exclusive disjunction (either a or b or both). The

hexpressioni is true if at least one of the elements joined with or is true. For example:

\ifboolexpr{
togl {toglA} or togl {toglB}
}
{true}
{false}

will yield htruei if either togl test or both tests are true. The nor operator (negated
non-exclusive disjunction, i. e., neither a nor b nor both) is not provided as such but
may be expressed by using or in a negated subexpression. For example:

bool {boolA} nor bool {boolB}

may be written as

26
 not ( bool {boolA} or bool {boolB} )

(...) The parentheses delimit a subexpression in the hexpressioni. 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:

( bool {boolA} or bool {boolB} )

and
( bool {boolC} or bool {boolD} )

is true if both subexpressions are true, i. e., if at least one of boolA/boolB and at
least one of boolC/boolD is true. Subexpressions are generally not required if all
elements are joined with and or with or. For example, the expressions

bool {boolA} and bool {boolB} and {boolC} and bool {boolD}
bool {boolA} or bool {boolB} or {boolC} or bool {boolD}

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 and and 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

bool {coffee} and bool {milk} or bool {sugar}

is always true if sugar is true since the or operator will take the result of the and
evaluation as input. In contrast to the meaning of this expression when pronounced
in English, it is not processed like this

bool {coffee} and ( bool {milk} or bool {sugar} )

but evaluated strictly from left to right:

( bool {coffee} and bool {milk} ) or bool {sugar}

which is probably not what you meant to order.

27
 3.7 List Processing
3.7.1 User Input
The tools in this section are primarily designed to handle user input. When building
lists for internal use by a package, using the tools in section 3.7.2 may be preferable
as they allow testing if an element is in a list.

\DeclareListParser{hcommandi}{hseparatori}
This command defines a list parser similar to the \docsvlist command below,
which is defined like this:
\DeclareListParser{\docsvlist}{,}

Note that the list parsers are sensitive to the category code of the hseparatori.
\DeclareListParser*{hcommandi}{hseparatori}
The starred variant of \DeclareListParser defines a list parser similar to the \forcsvlist
command below, which is defined like this:
\DeclareListParser*{\forcsvlist}{,}

\docsvlist{hitem, item, ...i}

This command loops over a comma-separated list of items and executes the auxiliary
command \do for every item in the list, passing the item as an argument. In contrast
to the \@for loop in the LaTeX kernel, \docsvlist is expandable. With a suitable
definition of \do, lists may be processed in an \edef or a comparable context. You
may use \listbreak at the end of the replacement text of \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 itemize environment:
\begin{itemize}
\renewcommand*{\do}[1]{\item #1}
\docsvlist{item1, item2, {item3a, item3b}, item4}
\end{itemize}

Here is another example:

\renewcommand*{\do}[1]{* #1\MessageBreak}
\PackageInfo{mypackage}{%
Example list:\MessageBreak
\docsvlist{item1, item2, {item3a, item3b}, item4}}

28
 In this example, the list is written to the log file as part of an informational message.
The list processing takes place during the \write operation.

\forcsvlist{hhandleri}{hitem, item, ...i}

This command is similar to \docsvlist except that \do is replaced by a hhandleri

specified at invocation time. The hhandleri may also be a sequence of commands,
provided that the command given last takes the item as trailing argument. For
example, the following code will convert a comma-separated list of items into an
internal list called \mylist:

\forcsvlist{\listadd\mylist}{item1, item2, item3}

3.7.2 Internal Lists

The tools in this section handle internal lists of data. An ‘internal list’ in this context
is a plain macro without any parameters and prefixes which is employed to collect
data. These lists use a special character as internal list separator.2 When processing
user input in list format, see the tools in section 3.7.1.

\listadd{hlistmacroi}{hitemi}

This command appends an hitemi to a hlistmacroi. A blank hitemi is not added to

the list.

\listgadd{hlistmacroi}{hitemi}

Similar to \listadd except that the assignment is global.

\listeadd{hlistmacroi}{hitemi}

Similar to \listadd except that the hitemi is expanded at definition-time. Only the
new hitemi is expanded, the hlistmacroi is not. If the expanded hitemi is blank, it is
not added to the list.

\listxadd{hlistmacroi}{hitemi}

Similar to \listeadd except that the assignment is global.

\listcsadd{hlistcsnamei}{hitemi}

Similar to \listadd except that it takes a control sequence name as its first argu-
ment.
2
The character | with category code 3. Note that you may not typeset a list by saying \listname.
Use \show instead to inspect the list.

29
 \listcsgadd{hlistcsnamei}{hitemi}

Similar to \listcsadd except that the assignment is global.

\listcseadd{hlistcsnamei}{hitemi}

Similar to \listeadd except that it takes a control sequence name as its first argu-
ment.

\listcsxadd{hlistcsnamei}{hitemi}

Similar to \listcseadd except that the assignment is global.

\listremove{hlistmacroi}{hitemi}

This command removes an hitemi from a hlistmacroi. A blank hitemi is ignored.

\listgremove{hlistmacroi}{hitemi}

Similar to \listremove except that the assignment is global.

\listcsremove{hlistcsnamei}{hitemi}

Similar to \listremove except that it takes a control sequence name as its first
argument.

\listcsgremove{hlistcsnamei}{hitemi}

Similar to \listcsremove except that the assignment is global.

\dolistloop{hlistmacroi}

This command loops over all items in a hlistmacroi and executes the auxiliary com-
mand \do for every item in the list, passing the item as an argument. The list loop
itself is expandable. You may use \listbreak at the end of the replacement text of
\do to stop processing and discard the remaining items in the list. Here is a usage
example which prints an internal list called \mylist as an itemize environment:

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

\dolistcsloop{hlistcsnamei}

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

30
 \forlistloop{hhandleri}{hlistmacroi}

This command is similar to \dolistloop except that \do is replaced by a hhandleri

specified at invocation time. The hhandleri may also be a sequence of commands,
provided that the command given last takes the item as trailing argument. For
example, the following code will prefix all items in the internal list \mylist with
\item, count the items as the list is processed, and append the item count at the
end:

\newcounter{itemcount}
\begin{itemize}
\forlistloop{\stepcounter{itemcount}\item}{\mylist}
\item Total: \number\value{itemcount} items
\end{itemize}

\forlistcsloop{hhandleri}{hlistcsnamei}

Similar to \forlistloop except that it takes a control sequence name as its second
argument.

\ifinlist{hitemi}{hlistmacroi}{htruei}{hfalsei}

This command executes htruei if the hitemi is included in a hlistmacroi, and hfalsei
otherwise. Note that this test uses pattern matching based on TeX’s argument scan-
ner 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 \dolistloop
to check if an item is in the list as follows:

\renewcommand*{\do}[1]{%
\ifstrequal{#1}{item}
{item found!\listbreak}
{}}
\dolistloop{\mylist}

\xifinlist{hitemi}{hlistmacroi}{htruei}{hfalsei}

Similar to \ifinlist except that the hitemi is expanded prior to the test.

\ifinlistcs{hitemi}{hlistcsnamei}{htruei}{hfalsei}

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

31
\xifinlistcs{hitemi}{hlistcsnamei}{htruei}{hfalsei}

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

3.8 Miscellaneous Tools

\rmntonum{hnumerali}

The TeX primitive \romannumeral converts an integer to a Roman numeral but TeX
or LaTeX provide no command which goes the opposite way. \rmntonum fills this
gap. It takes a Roman numeral as its argument and converts it to the correspond-
ing integer. Since it is expandable, it may also be used in counter assignments or
arithmetic tests:

\rmntonum{mcmxcv}
\setcounter{counter}{\rmntonum{CXVI}}
\ifnumless{\rmntonum{mcmxcviii}}{2000}{true}{false}

The hnumerali 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 argu-
ment is ignored. If there is an invalid token in the argument, \rmntonum will expand
to -1; an empty argument will yield an empty string. Note that \rmntonum will not
check the numeral for formal validity. For example, both V and VX would yield 5, IC
would yield 99, etc.

\ifrmnum{hstringi}{htruei}{hfalsei}

Expands to htruei if hstringi is a Roman numeral, and to hfalsei otherwise. The

hstringi will be detokenized prior to performing the test. The test is case-insensi-
tive and ignores whitespace in the hstringi. Note that \ifrmnum will not check the
numeral for formal validity. For example, both V and VXV will yield htruei. Strictly
speaking, what \ifrmnum does is parse the hstringi 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.

4 Reporting issues
The development code for etoolbox is hosted on GitHub: https://github.com/
josephwright/etoolbox. This is the best place to log any issues with the package.

32
5 Revision History
This revision history is a list of changes relevant to users of this package. Changes
of a more technical nature which do not affect the user interface or the behavior
of the package are not included in the list. If an entry in the revision history states
that a feature has been improved or extended, this indicates a syntactically backwards
compatible modification, such as the addition of an optional argument to an existing
command. Entries stating that a feature has been modified demand attention. They
indicate a modification which may require changes to existing documents in some,
hopefully rare, cases. The numbers on the right indicate the relevant section of this
manual.

2.5k 2020-10-05
Internal updates
2.5j 2020-08-24
Track LATEX 2ε kernel changes
2.5i 2020-07-13
Track LATEX 2ε kernel changes
2.5h 2019-09-21
Add missing \gundef
2.5g 2019-09-09
Update patching of \begin and \end in advance of LATEX kernel changes
2.5f 2018-08-18
Fix issue with \ifdefempty, \ifcsempty, \ifdefvoid and \ifcsvoid when
applied to macros expanding to space tokens
2.5e 2018-02-11
More work on empty list separator in \DeclareListParser
2.5d 2018-02-10
Allow for empty list separator in \DeclareListParser
2.5c 2018-02-06
Fix issue with \forcsvlist introduced by v2.5b

33
2.5b 2018-02-04
Preserve braces in some internal steps
Internal performance improvements in list processors
2.5a 2018-02-03
Internal performance improvements in list processors
2.5 2017-11-22
Added \csgundef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.1
Added \gundef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.1
Allow scanning of macros containing new line characters
2.4 2017-01-02
Renamed \listdel to \listremove (name clash) . . . . . . . . . . . . . 3.7.2
Renamed \listgdel to \listgremove (name clash) . . . . . . . . . . . . 3.7.2
2.3 2016-12-26
Added \listdel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Added \listgdel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
2.2b 2016-12-01
Fixed \ifdefltxprotect for some types of LaTeX robust commands
Remove redundant macro after \robustify processing
2.2a 2015-08-02
Fixed robustness bug in \ifblank/\notblank
2.2 2015-05-04
Added \csmeaning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.1
2.1d 2015-03-19
Fixed issue with bm and some classes
2.1c 2015-03-15
Fixed space bug in \ifpatchable
Fixed space bug in \patchcmd
Fixed space bug in \robustify

34
2.1b 2015-03-10
Minor documentation fixes
2.1a 2015-03-10
New maintainer: Joseph Wright
Skip loading etex package with newer LaTeX kernel releases
2.1 2011-01-03
Added \AtBeginEnvironment . . . . . . . . . . . . . . . . . . . . . . . . . 2.6
Added \AtEndEnvironment . . . . . . . . . . . . . . . . . . . . . . . . . . 2.6
Added \BeforeBeginEnvironment . . . . . . . . . . . . . . . . . . . . . . 2.6
Added \AfterEndEnvironment . . . . . . . . . . . . . . . . . . . . . . . . 2.6
Added \ifdefstrequal . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifcsstrequal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifdefcounter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.2
Added \ifcscounter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.2
Added \ifltxcounter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.2
Added \ifdeflength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.2
Added \ifcslength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.2
Added \ifdefdimen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.2
Added \ifcsdimen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.2
2.0a 2010-09-12
Fixed bug in \patchcmd, \apptocmd, \pretocmd . . . . . . . . . . . . . . 3.4
2.0 2010-08-21
Added \csshow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.1
Added \DeclareListParser* . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.1
Added \forcsvlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.1
Added \forlistloop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Added \forlistcsloop . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Allow testing \par in macro tests . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Fixed some bugs

35
1.9 2010-04-10
Improved \letcs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.1
Improved \csletcs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.1
Improved \listeadd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Improved \listxadd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Added \notblank . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.3
Added \ifnumodd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.4
Added \ifboolexpr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.5
Added \ifboolexpe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.5
Added \whileboolexpr . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.5
Added \unlessboolexpr . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.5
1.8 2009-08-06
Improved \deflength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4
Added \ifnumcomp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.4
Added \ifnumequal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.4
Added \ifnumgreater . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.4
Added \ifnumless . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.4
Added \ifdimcomp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.4
Added \ifdimequal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.4
Added \ifdimgreater . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.4
Added \ifdimless . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.4
1.7 2008-06-28
Renamed \AfterBeginDocument to \AfterEndPreamble (name clash) . . 2.5
Resolved conflict with hyperref
Rearranged manual slightly
1.6 2008-06-22
Improved \robustify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2
Improved \patchcmd and \ifpatchable . . . . . . . . . . . . . . . . . . . 3.4
Modified and improved \apptocmd . . . . . . . . . . . . . . . . . . . . . . 3.4
Modified and improved \pretocmd . . . . . . . . . . . . . . . . . . . . . . 3.4
Added \ifpatchable* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4

36
Added \tracingpatches . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4
Added \AfterBeginDocument . . . . . . . . . . . . . . . . . . . . . . . . . 2.5
Added \ifdefmacro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifcsmacro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifdefprefix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifcsprefix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifdefparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifcsparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifdefprotected . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifcsprotected . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifdefltxprotect . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifcsltxprotect . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifdefempty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifcsempty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Improved \ifdefvoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Improved \ifcsvoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifstrempty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.3
Added \setbool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.1
Added \settoggle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.2
1.5 2008-04-26
Added \defcounter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4
Added \deflength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4
Added \ifdefstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifcsstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Improved \rmntonum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.8
Added \ifrmnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.8
Added extended PDF bookmarks to this manual
Rearranged manual slightly
1.4 2008-01-24
Resolved conflict with tex4ht

37
1.3 2007-10-08
Renamed package from elatex to etoolbox . . . . . . . . . . . . . . . . . 1
Renamed \newswitch to \newtoggle (name clash) . . . . . . . . . . . . . 3.5.2
Renamed \provideswitch to \providetoggle (consistency) . . . . . . . 3.5.2
Renamed \switchtrue to \toggletrue (consistency) . . . . . . . . . . . 3.5.2
Renamed \switchfalse to \togglefalse (consistency) . . . . . . . . . . 3.5.2
Renamed \ifswitch to \iftoggle (consistency) . . . . . . . . . . . . . . 3.5.2
Renamed \notswitch to \nottoggle (consistency) . . . . . . . . . . . . . 3.5.2
Added \AtEndPreamble . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.5
Added \AfterEndDocument . . . . . . . . . . . . . . . . . . . . . . . . . . 2.5
Added \AfterPreamble . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.5
Added \undef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.1
Added \csundef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.1
Added \ifdefvoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifcsvoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifdefequal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifcsequal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.1
Added \ifstrequal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6.3
Added \listadd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Added \listeadd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Added \listgadd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Added \listxadd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Added \listcsadd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Added \listcseadd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Added \listcsgadd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Added \listcsxadd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Added \ifinlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Added \xifinlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Added \ifinlistcs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Added \xifinlistcs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Added \dolistloop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2
Added \dolistcsloop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2

38
1.2 2007-07-13
Renamed \patchcommand to \patchcmd (name clash) . . . . . . . . . . . 3.4
Renamed \apptocommand to \apptocmd (consistency) . . . . . . . . . . . 3.4
Renamed \pretocommand to \pretocmd (consistency) . . . . . . . . . . . 3.4
Added \newbool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.1
Added \providebool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.1
Added \booltrue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.1
Added \boolfalse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.1
Added \ifbool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.1
Added \notbool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.1
Added \newswitch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.2
Added \provideswitch . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.2
Added \switchtrue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.2
Added \switchfalse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.2
Added \ifswitch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.2
Added \notswitch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.2
Added \DeclareListParser . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.1
Added \docsvlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.1
Added \rmntonum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.8
1.1 2007-05-28
Added \protected@csedef . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.1
Added \protected@csxdef . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.1
Added \gluedef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.2
Added \gluegdef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.2
Added \csgluedef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.2
Added \csgluegdef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.2
Added \mudef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.2
Added \mugdef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.2
Added \csmudef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.2
Added \csmugdef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.2
Added \protected@eappto . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3.1

39
Added \protected@xappto . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3.1
Added \protected@cseappto . . . . . . . . . . . . . . . . . . . . . . . . . 3.3.1
Added \protected@csxappto . . . . . . . . . . . . . . . . . . . . . . . . . 3.3.1
Added \protected@epreto . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3.2
Added \protected@xpreto . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3.2
Added \protected@csepreto . . . . . . . . . . . . . . . . . . . . . . . . . 3.3.2
Added \protected@csxpreto . . . . . . . . . . . . . . . . . . . . . . . . . 3.3.2
Fixed bug in \newrobustcmd . . . . . . . . . . . . . . . . . . . . . . . . . 2.1
Fixed bug in \renewrobustcmd . . . . . . . . . . . . . . . . . . . . . . . . 2.1
Fixed bug in \providerobustcmd . . . . . . . . . . . . . . . . . . . . . . . 2.1
1.0 2007-05-07
Initial public release

40