Debian Codegraph @

texmf-dist/doc/latex/etoolbox/etoolbox.tex

raw
1 \documentclass{ltxdockit}[2010/09/26]
2 \usepackage[utf8]{inputenc}
3 \usepackage[american]{babel}
4 \usepackage[strict]{csquotes}
5 \usepackage{shortvrb}
6 \MakeAutoQuote*{<}{>}
7 \MakeShortVerb{\|}
8
9 \titlepage{%
10 title={The \sty{etoolbox} Package},
11 subtitle={An \etex Toolbox for Class and Package Authors},
12 url={http://www.ctan.org/pkg/etoolbox/},
13 author={Philipp Lehman, Joseph Wright},
14 email={[email protected]},
15 revision={v2.5m},
16 date={2025/10/02}}
17
18 \hypersetup{%
19 pdftitle={The etoolbox Package},
20 pdfsubject={An e-TeX Toolbox for Class and Package Authors},
21 pdfauthor={Philipp Lehman, Joseph Wright},
22 pdfkeywords={tex, e-tex, latex, class, package, programming}}
23
24 \begin{document}
25
26 \printtitlepage
27 \tableofcontents
28
29 \section{Introduction}
30 \label{int}
31
32 \subsection[About]{About \sty{etoolbox}}
33
34 The \sty{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 \etex as well as some generic tools which are not related to \etex but match the profile of this package.
35
36 \subsection{License}
37
38 Copyright \textcopyright\ 2007--2011 Philipp Lehman, 2015--2025 Joseph Wright. Permission is granted to copy, distribute and\slash or modify this software under the terms of the \lppl, version 1.3c or later.\fnurl{http://www.latex-project.org/lppl/}
39
40 \section{User Commands}
41 \label{use}
42
43 The tools in this section are geared towards regular users as well as class and package authors.
44
45 \subsection{Definitions}
46 \label{use:def}
47
48 \begin{ltxsyntax}
49
50 \cmditem{newrobustcmd}{command}[arguments][optarg default]{replacement text}
51 \cmditem*{newrobustcmd*}{command}[arguments][optarg default]{replacement text}
52
53 The syntax and behavior of this command is similar to \cmd{newcommand} except that the newly defined \prm{command} will be robust. The behavior of this command differs from the \cmd{DeclareRobustCommand} command from the \latex kernel in that it issues an error rather than just an informational message if the \prm{command} is already defined. Since it uses \etex's low-level protection mechanism rather than the corresponding higher-level \latex facilities, it does not require an additional macro to implement the <robustness>.
54
55 \cmditem{renewrobustcmd}{command}[arguments][optarg default]{replacement text}
56 \cmditem*{renewrobustcmd*}{command}[arguments][optarg default]{replacement text}
57
58 The syntax and behavior of this command is similar to \cmd{renewcommand} except that the redefined \prm{command} will be robust.
59
60 \cmditem{providerobustcmd}{command}[arguments][optarg default]{replacement text}
61 \cmditem*{providerobustcmd*}{command}[arguments][optarg default]{replacement text}
62
63 The syntax and behavior of this command is similar to \cmd{providecommand} except that the newly defined \prm{command} will be robust. Note that this command will provide a robust definition of the \prm{command} only if it is undefined. It will not make an already defined \prm{command} robust.
64
65 \end{ltxsyntax}
66
67 \subsection{Patching}
68 \label{use:pat}
69
70 \begin{ltxsyntax}
71
72 \cmditem{robustify}{command}
73
74 Redefines a \prm{command} defined with \cmd{newcommand} such that it is robust, without altering its parameters, its prefixes, or its replacement text. If the \prm{command} has been defined with \cmd{DeclareRobustCommand}, this will be detected automatically and \latex's high-level protection mechanism will be replaced by the corresponding low-level \etex feature. If the command has been copied using \cmd{let} \emph{before} robustifing, it is possible an error will arise if the copy is used: in this case, a fresh copy should be created, ideally using the \latex kernel command \cmd{DeclareCommandCopy}.
75
76 \end{ltxsyntax}
77
78 \subsection{Protection}
79 \label{use:pro}
80
81 \begin{ltxsyntax}
82
83 \cmditem{protecting}{code}
84
85 This command applies \latex's protection mechanism, which normally requires prefixing each fragile command with \cmd{protect}, to an entire chunk of arbitrary \prm{code}. Its behavior depends on the current state of \cmd{protect}. Note that the braces around the \prm{code} are mandatory even if it is a single token.
86
87 \end{ltxsyntax}
88
89 \subsection[Lengths and Counters]{Length and Counter Assignments}
90 \label{use:cal}
91
92 The tools in this section are replacements for \cmd{setcounter} and \cmd{setlength} which support arithmetic expressions.
93
94 \begin{ltxsyntax}
95
96 \cmditem{defcounter}{counter}{integer expression}
97
98 Assigns a value to a \latex \prm{counter} previously initialized with \cmd{newcounter}. This command is similar in concept and syntax to \cmd{setcounter} except for two major differences. 1) The second argument may be an \prm{integer expression} which will be processed with \cmd{numexpr}. The \prm{integer expression} may be any arbitrary code which is valid in this context. The value assigned to the \prm{counter} will be the result of that calculation. 2) In contrast to \cmd{setcounter}, the assignment is local by default but \cmd{defcounter} may be prefixed with \cs{global}. The functional equivalent of \cmd{setcounter} would be \cs{global}\cmd{defcounter}.
99
100 \cmditem{deflength}{length}{glue expression}
101
102 Assigns a value to a \prm{length} register previously initialized with \cmd{newlength}. This command is similar in concept and syntax to \cmd{setlength} except that the second argument may be a \prm{glue expression} which will be processed with \cmd{glueexpr}. The \prm{glue expression} may be any arbitrary code which is valid in this context. The value assigned to the \prm{length} register will be the result of that calculation. The assignment is local by default but \cmd{deflength} may be prefixed with \cs{global}. This command may be used as a drop-in replacement for \cmd{setlength}.
103
104 \end{ltxsyntax}
105
106 \subsection[Document Hooks]{Additional Document Hooks}
107 \label{use:pre}
108
109 \latex provides two hooks which defer the execution of code either to the beginning or to the end of the document body. Any \cmd{AtBeginDocument} code is executed towards the beginning of the document body, after the main \file{aux} file has been read for the first time. Any \cmd{AtEndDocument} code is executed at the end of the document body, 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 \prm{code} argument to slightly different locations. The \prm{code} may be arbitrary \tex code. Parameter characters in the \prm{code} argument are permissible and need not be doubled.
110
111 \begin{ltxsyntax}
112
113 \cmditem{AfterPreamble}{code}
114
115 This hook is a variant of \cmd{AtBeginDocument} which may be used in both the preamble and the document body. When used in the preamble, it behaves exactely like \cmd{AtBeginDocument}. When used in the document body, it immediately executes its \prm{code} argument. \cmd{AtBeginDocument} would issue an error in this case. This hook is useful to defer code which needs to write to the main \file{aux} file.
116
117 \cmditem{AtEndPreamble}{code}
118
119 This hook differs from \cmd{AtBeginDocument} in that the \prm{code} is executed right at the end of the preamble, before the main \file{aux} file (as written on the previous \latex pass) is read and prior to any \cmd{AtBeginDocument} code. Note that it is not possible to write to the \file{aux} file at this point.
120
121 \cmditem{AfterEndPreamble}{code}
122
123 This hook differs from \cmd{AtBeginDocument} in that the \prm{code} is executed at the very end of |\begin{document}|, after any \cmd{AtBeginDocument} code. Note that commands whose scope has been restricted to the preamble with \cmd{@onlypreamble} are no longer available when this hook is executed.
124
125 \cmditem{AfterEndDocument}{code}
126
127 This hook differs from \cmd{AtEndDocument} in that the \prm{code} is executed at the very end of the document, after the main \file{aux} file (as written on the current \latex pass) has been read and after any \cmd{AtEndDocument} code.
128
129 \end{ltxsyntax}
130
131 In a way, \cmd{AtBeginDocument} code is part neither of the preamble nor the document 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. \cmd{AtBeginDocument} code, however, is executed too late if it is required in the \file{aux} file. In contrast to that, \cmd{AtEndPreamble} code is part of the preamble; \cmd{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}|:
132
133 \begin{itemize}
134 \setlength{\itemsep}{0pt}
135 \item Execute any \cmd{AtEndPreamble} code
136 \item Start initialization for document body (page layout, default fonts, etc.)
137 \item Load the main \file{aux} file written on the previous \latex pass
138 \item Open the main \file{aux} file for writing on the current pass
139 \item Continue initialization for document body
140 \item Execute any \cmd{AtBeginDocument} code
141 \item Complete initialization for document body
142 \item Disable all \cmd{@onlypreamble} commands
143 \item Execute any \cmd{AfterEndPreamble} code
144 \end{itemize}
145 %
146 Inside |\end{document}|, \latex will perform the following tasks:
147
148 \begin{itemize}
149 \setlength{\itemsep}{0pt}
150 \item Execute any \cmd{AtEndDocument} code
151 \item Perform a final \cmd{clearpage} operation
152 \item Close the main \file{aux} file for writing
153 \item Load the main \file{aux} file written on the current \latex pass
154 \item Perform final tests and issue warnings, if applicable
155 \item Execute any \cmd{AfterEndDocument} code
156 \end{itemize}
157 %
158 Any \cmd{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 \file{aux} file when it gets executed. \cmd{AfterEndDocument} code is not part of the document body. This hook is useful to evaluate the data in the \file{aux} file at the very end of a \latex pass.
159
160 \subsection[Environment Hooks]{Environment Hooks}
161 \label{use:env}
162
163 The tools in this section provide hooks for arbitrary environments. Note that they will not modify the definition of the \prm{environment}. They hook into the \cmd{begin} and \cmd{end} commands instead. Redefining the \prm{environment} will not clear the corresponding hooks. The \prm{code} may be arbitrary \tex code. Parameter characters in the \prm{code} argument are permissible and need not be doubled.
164
165 \begin{ltxsyntax}
166
167 \cmditem{AtBeginEnvironment}{environment}{code}
168
169 Appends arbitrary \prm{code} to a hook executed by the \cmd{begin} command at the beginning of a given \prm{environment}, immediately before \cmd{\prm{environment}}, inside the group opened by \cmd{begin}.
170
171 \cmditem{AtEndEnvironment}{environment}{code}
172
173 Appends arbitrary \prm{code} to a hook executed by the \cmd{end} command at the end of a given \prm{environment}, immediately before \cmd{end\prm{environment}}, inside the group opened by \cmd{begin}.
174
175 \cmditem{BeforeBeginEnvironment}{environment}{code}
176
177 Appends arbitrary \prm{code} to a hook executed at a very early point by the \cmd{begin} command, before the group holding the environment is opened.
178
179 \cmditem{AfterEndEnvironment}{environment}{code}
180
181 Appends arbitrary \prm{code} to a hook executed at a very late point by the \cmd{end} command, after the group holding the environment has been closed.
182
183 \end{ltxsyntax}
184
185 \section{Author Commands}
186
187 The tools in this section are geared towards class and package authors.
188
189 \subsection{Definitions}
190
191 \subsubsection{Macro Definitions}
192 \label{aut:def:def}
193
194 The tools in this section are simple but frequently required shorthands which extend the scope of the \cmd{@namedef} and \cmd{@nameuse} macros from the \latex kernel.
195
196 \begin{ltxsyntax}
197
198 \cmditem{csdef}{csname}<arguments>{replacement text}
199
200 Similar to the \tex primitive \cmd{def} except that it takes a control sequence name as its first argument. This command is robust and corresponds to \cmd{@namedef}.
201
202 \cmditem{csgdef}{csname}<arguments>{replacement text}
203
204 Similar to the \tex primitive \cmd{gdef} except that it takes a control sequence name as its first argument. This command is robust.
205
206 \cmditem{csedef}{csname}<arguments>{replacement text}
207
208 Similar to the \tex primitive \cmd{edef} except that it takes a control sequence name as its first argument. This command is robust.
209
210 \cmditem{csxdef}{csname}<arguments>{replacement text}
211
212 Similar to the \tex primitive \cmd{xdef} except that it takes a control sequence name as its first argument. This command is robust.
213
214 \cmditem{protected@csedef}{csname}<arguments>{replacement text}
215
216 Similar to \cmd{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 \cmd{protected@edef} except that it takes a control sequence name as its first argument. This command is robust.
217
218 \cmditem{protected@csxdef}{csname}<arguments>{replacement text}
219
220 Similar to \cmd{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 \cmd{protected@xdef} except that it takes a control sequence name as its first argument. This command is robust.
221
222 \cmditem{cslet}{csname}{command}
223
224 Similar to the \tex primitive \cmd{let} except that the first argument is a control sequence name. If \prm{command} is undefined, \prm{csname} will be undefined as well after the assignment. This command is robust and may be prefixed with \cs{global}.
225
226 \cmditem{letcs}{command}{csname}
227
228 Similar to the \tex primitive \cmd{let} except that the second argument is a control sequence name. If \prm{csname} is undefined, the \prm{command} will be undefined as well after the assignment. This command is robust and may be prefixed with \cs{global}.
229
230 \cmditem{csletcs}{csname}{csname}
231
232 Similar to the \tex primitive \cmd{let} except that both arguments are control sequence names. If the second \prm{csname} is undefined, the first \prm{csname} will be undefined as well after the assignment. This command is robust and may be prefixed with \cs{global}.
233
234 \cmditem{csuse}{csname}
235
236 Takes a control sequence name as its argument and forms a control sequence token. This command differs from the \cmd{@nameuse} macro in the \latex kernel in that it expands to an empty string if the control sequence is undefined.
237
238 \cmditem{undef}<command>
239
240 Clears a \prm{command} such that \etex's \cmd{ifdefined} and \cmd{ifcsname} tests will consider it as undefined. This command is robust and may be prefixed with \cs{global}.
241
242 \cmditem{gundef}<command>
243
244 Similar to \cmd{undef} but acts globally.
245
246 \cmditem{csundef}{csname}
247
248 Similar to \cmd{undef} except that it takes a control sequence name as its argument. This command is robust and may be prefixed with \cs{global}.
249
250 \cmditem{csgundef}{csname}
251
252 Similar to \cmd{csundef} but acts globally.
253
254 \cmditem{csmeaning}{csname}
255
256 Similar to the \tex primitive \cmd{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 \cmd{relax} to it.
257
258 \cmditem{csshow}{csname}
259
260 Similar to the \tex primitive \cmd{show} but takes a control sequence name as its argument. If the control sequence is undefined, this command will not implicitly assign a meaning of \cmd{relax} to it. This command is robust.
261
262 \end{ltxsyntax}
263
264 \subsubsection{Arithmetic Definitions}
265 \label{aut:def:cal}
266
267 The tools in this section permit calculations using macros rather than length registers and counters.
268
269 \begin{ltxsyntax}
270
271 \cmditem{numdef}<command>{integer expression}
272
273 Similar to \cmd{edef} except that the \prm{integer expression} is processed with \cmd{numexpr}. The \prm{integer expression} may be any arbitrary code which is valid in this context. The replacement text assigned to the \prm{command} will be the result of that calculation. If the \prm{command} is undefined, it will be initialized to \texttt{0} before the \prm{integer expression} is processed.
274
275 \cmditem{numgdef}<command>{integer expression}
276
277 Similar to \cmd{numdef} except that the assignment is global.
278
279 \cmditem{csnumdef}{csname}{integer expression}
280
281 Similar to \cmd{numdef} except that it takes a control sequence name as its first argument.
282
283 \cmditem{csnumgdef}{csname}{integer expression}
284
285 Similar to \cmd{numgdef} except that it takes a control sequence name as its first argument.
286
287 \cmditem{dimdef}<command>{dimen expression}
288
289 Similar to \cmd{edef} except that the \prm{dimen expression} is processed with \cmd{dimexpr}. The \prm{dimen expression} may be any arbitrary code which is valid in this context. The replacement text assigned to the \prm{command} will be the result of that calculation. If the \prm{command} is undefined, it will be initialized to \texttt{0pt} before the \prm{dimen expression} is processed.
290
291 \cmditem{dimgdef}<command>{dimen expression}
292
293 Similar to \cmd{dimdef} except that the assignment is global.
294
295 \cmditem{csdimdef}{csname}{dimen expression}
296
297 Similar to \cmd{dimdef} except that it takes a control sequence name as its first argument.
298
299 \cmditem{csdimgdef}{csname}{dimen expression}
300
301 Similar to \cmd{dimgdef} except that it takes a control sequence name as its first argument.
302
303 \cmditem{gluedef}<command>{glue expression}
304
305 Similar to \cmd{edef} except that the \prm{glue expression} is processed with \cmd{glueexpr}. The \prm{glue expression} may be any arbitrary code which is valid in this context. The replacement text assigned to the \prm{command} will be the result of that calculation. If the \prm{command} is undefined, it will be initialized to \texttt{0pt plus 0pt minus 0pt} before the \prm{glue expression} is processed.
306
307 \cmditem{gluegdef}<command>{glue expression}
308
309 Similar to \cmd{gluedef} except that the assignment is global.
310
311 \cmditem{csgluedef}{csname}{glue expression}
312
313 Similar to \cmd{gluedef} except that it takes a control sequence name as its first argument.
314
315 \cmditem{csgluegdef}{csname}{glue expression}
316
317 Similar to \cmd{gluegdef} except that it takes a control sequence name as its first argument.
318
319 \cmditem{mudef}<command>{muglue expression}
320
321 Similar to \cmd{edef} except that the \prm{muglue expression} is processed with \cmd{muexpr}. The \prm{muglue expression} may be any arbitrary code which is valid in this context. The replacement text assigned to the \prm{command} will be the result of that calculation. If the \prm{command} is undefined, it will be initialized to \texttt{0mu} before the \prm{muglue expression} is processed.
322
323 \cmditem{mugdef}<command>{muglue expression}
324
325 Similar to \cmd{mudef} except that the assignment is global.
326
327 \cmditem{csmudef}{csname}{muglue expression}
328
329 Similar to \cmd{mudef} except that it takes a control sequence name as its first argument.
330
331 \cmditem{csmugdef}{csname}{muglue expression}
332
333 Similar to \cmd{mugdef} except that it takes a control sequence name as its first argument.
334
335 \end{ltxsyntax}
336
337 \subsection{Expansion Control}
338 \label{aut:exp}
339
340 The tools in this section are useful to control expansion in an \cmd{edef} or a similar context.
341
342 \begin{ltxsyntax}
343
344 \cmditem{expandonce}<command>
345
346 This command expands a \prm{command} once and prevents further expansion of the replacement text. This command is expandable.
347
348 \cmditem{csexpandonce}{csname}
349
350 Similar to \cmd{expandonce} except that it takes a control sequence name as its argument.
351
352 \end{ltxsyntax}
353
354 \subsection{Hook Management}
355 \label{aut:hok}
356
357 The tools in this section are intended for hook management. A \prm{hook} 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 appending code to their replacement text. For more complex patching operations, see section \ref{aut:pat}. All commands in this section will initialize the \prm{hook} if it is undefined.
358
359 \subsubsection{Appending to a Hook}
360 \label{aut:hok:app}
361
362 The tools in this section append arbitrary code to a hook.
363
364 \begin{ltxsyntax}
365
366 \cmditem{appto}<hook>{code}
367
368 This command appends arbitrary \prm{code} to a \prm{hook}. If the \prm{code} contains any parameter characters, they need not be doubled. This command is robust.
369
370 \cmditem{gappto}<hook>{code}
371
372 Similar to \cmd{appto} except that the assignment is global. This command may be used as a drop-in replacement for the \cmd{g@addto@macro} command in the \latex kernel.
373
374 \cmditem{eappto}<hook>{code}
375
376 This command appends arbitrary \prm{code} to a \prm{hook}. The \prm{code} is expanded at definition"=time. Only the new \prm{code} is expanded, the current replacement text of the \prm{hook} is not. This command is robust.
377
378 \cmditem{xappto}<hook>{code}
379
380 Similar to \cmd{eappto} except that the assignment is global.
381
382 \cmditem{protected@eappto}<hook>{code}
383
384 Similar to \cmd{eappto} except that \latex's protection mechanism is temporarily enabled.
385
386 \cmditem{protected@xappto}<hook>{code}
387
388 Similar to \cmd{xappto} except that \latex's protection mechanism is temporarily enabled.
389
390 \cmditem{csappto}{csname}{code}
391
392 Similar to \cmd{appto} except that it takes a control sequence name as its first argument.
393
394 \cmditem{csgappto}{csname}{code}
395
396 Similar to \cmd{gappto} except that it takes a control sequence name as its first argument.
397
398 \cmditem{cseappto}{csname}{code}
399
400 Similar to \cmd{eappto} except that it takes a control sequence name as its first argument.
401
402 \cmditem{csxappto}{csname}{code}
403
404 Similar to \cmd{xappto} except that it takes a control sequence name as its first argument.
405
406 \cmditem{protected@cseappto}{csname}{code}
407
408 Similar to \cmd{protected@eappto} except that it takes a control sequence name as its first argument.
409
410 \cmditem{protected@csxappto}{csname}{code}
411
412 Similar to \cmd{protected@xappto} except that it takes a control sequence name as its first argument.
413
414 \end{ltxsyntax}
415
416 \subsubsection{Prepending to a Hook}
417 \label{aut:hok:pre}
418
419 The tools 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.
420
421 \begin{ltxsyntax}
422
423 \cmditem{preto}<hook>{code}
424
425 Similar to \cmd{appto} except that the \prm{code} is prepended.
426
427 \cmditem{gpreto}<hook>{code}
428
429 Similar to \cmd{preto} except that the assignment is global.
430
431 \cmditem{epreto}<hook>{code}
432
433 Similar to \cmd{eappto} except that the \prm{code} is prepended.
434
435 \cmditem{xpreto}<hook>{code}
436
437 Similar to \cmd{epreto} except that the assignment is global.
438
439 \cmditem{protected@epreto}<hook>{code}
440
441 Similar to \cmd{epreto} except that \latex's protection mechanism is temporarily enabled.
442
443 \cmditem{protected@xpreto}<hook>{code}
444
445 Similar to \cmd{xpreto} except that \latex's protection mechanism is temporarily enabled.
446
447 \cmditem{cspreto}{csname}{code}
448
449 Similar to \cmd{preto} except that it takes a control sequence name as its first argument.
450
451 \cmditem{csgpreto}{csname}{code}
452
453 Similar to \cmd{gpreto} except that it takes a control sequence name as its first argument.
454
455 \cmditem{csepreto}{csname}{code}
456
457 Similar to \cmd{epreto} except that it takes a control sequence name as its first argument.
458
459 \cmditem{csxpreto}{csname}{code}
460
461 Similar to \cmd{xpreto} except that it takes a control sequence name as its first argument.
462
463 \cmditem{protected@csepreto}{csname}{code}
464
465 Similar to \cmd{protected@epreto} except that it takes a control sequence name as its first argument.
466
467 \cmditem{protected@csxpreto}{csname}{code}
468
469 Similar to \cmd{protected@xpreto} except that it takes a control sequence name as its first argument.
470
471 \end{ltxsyntax}
472
473 \subsection{Patching}
474 \label{aut:pat}
475
476 The tools in this section are useful to hook into or modify existing code. All commands presented here preserve the parameters and the prefixes of the patched \prm{command}. Note that \cs{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 \prm{failure} argument which should provide suitable fallback code or an error message. Issuing \cmd{tracingpatches} in the preamble will cause the commands to write debugging information to the transcript file.
477
478 \begin{ltxsyntax}
479
480 \cmditem{patchcmd}[prefix]{command}{search}{replace}{success}{failure}
481
482 This command extracts the replacement text of a \prm{command}, replaces \prm{search} with \prm{replace}, and reassembles the \prm{command}. The pattern match is category code agnostic and matches the first occurence of the \prm{search} pattern in the replacement text of the \prm{command} to be patched. Note that the patching process involves detokenizing the replacement text of the \prm{command} and retokenizing it under the current category code regime after patching. The category code of the @ sign is temporarily set to 11. If the replacement text of the \prm{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 \prm{command} to be patched, the parameter characters need not be doubled. If an optional \prm{prefix} is specified, it replaces the prefixes of the \prm{command}. An empty \prm{prefix} argument strips all prefixes from the \prm{command}. The assignment is local. This command implicitly performs the equivalent of an \cmd{ifpatchable} test prior to patching. If this test succeeds, the command applies the patch and executes \prm{success}. If the test fails, it executes \prm{failure} without modifying the original \prm{command}. This command is robust.
483
484 \cmditem{ifpatchable}{command}{search}{true}{false}
485
486 This command executes \prm{true} if the \prm{command} may be patched with \cmd{patchcmd} and if the \prm{search} pattern is found in its replacement text, and \prm{false} otherwise. This command is robust.
487
488 \cmditem*{ifpatchable*}{command}{true}{false}
489
490 Similar to \cmd{ifpatchable} except that the starred variant does not require a search pattern. Use this version to check if a command may be patched with \cmd{apptocmd} and \cmd{pretocmd}.
491
492 \cmditem{apptocmd}{command}{code}{success}{failure}
493
494 This command appends \prm{code} to the replacement text of a \prm{command}. If the \prm{command} is a parameterless macro, it behaves like \cmd{appto} from section \ref{aut:hok:app}. In contrast to \cmd{appto}, \cmd{apptocmd} may also be used to patch commands with parameters. In this case, it will detokenize the replacement text of the \prm{command}, apply the patch, and retokenize it under the current category code regime. The category code of the @ sign is temporarily set to 11. The \prm{code} may refer to the parameters of the \prm{command}. The assignment is local. If patching succeeds, this command executes \prm{success}. If patching fails, it executes \prm{failure} without modifying the original \prm{command}. This command is robust.
495
496 \cmditem{pretocmd}{command}{code}{success}{failure}
497
498 This command is similar to \cmd{apptocmd} except that the \prm{code} is inserted at the beginning of the replacement text of the \prm{command}. If the \prm{command} is a parameterless macro, it behaves like \cmd{preto} from section \ref{aut:hok:app}. In contrast to \cmd{preto}, \cmd{pretocmd} may also be used to patch commands with parameters. In this case, it will detokenize the replacement text of the \prm{command}, apply the patch, and retokenize it under the current category code regime. The category code of the @ sign is temporarily set to 11. The \prm{code} may refer to the parameters of the \prm{command}. The assignment is local. If patching succeeds, this command executes \prm{success}. If patching fails, it executes \prm{failure} without modifying the original \prm{command}. This command is robust.
499
500 \csitem{tracingpatches}
501
502 Enables tracing for all patching commands, including \cmd{ifpatchable}. The debugging information will be written to the transcript file. This is useful if the reason why a patch is not applied or \cmd{ifpatchable} yields \prm{false} is not obvious. This command must be issued in the preamble.
503
504 \end{ltxsyntax}
505
506 \subsection{Boolean Flags}
507 \label{aut:bol}
508
509 This package provides two interfaces to boolean flags which are completely independent of each other. The tools in section \ref{aut:bo1:bol} are a \latex frontend to \cmd{newif}. Those in section \ref{aut:bo1:tgl} use a different mechanism.
510
511 \subsubsection{\tex Flags}
512 \label{aut:bo1:bol}
513
514 Since the tools in this section are based on \cmd{newif} internally, they may be used to test and alter the state of flags previously defined with \cmd{newif}. They are also compatible with the boolean tests of the \sty{ifthen} package and may serve as a \latex interface for querying \tex primitives such as \cmd{ifmmode}. The \cmd{newif} approach requires a total of three macros per flag.
515
516 \begin{ltxsyntax}
517
518 \cmditem{newbool}{name}
519
520 Defines a new boolean flag called \prm{name}. If the flag has already been defined, this command issues an error. The initial state of newly defined flags is \texttt{false}. This command is robust.
521
522 \cmditem{providebool}{name}
523
524 Defines a new boolean flag called \prm{name} unless it has already been defined. This command is robust.
525
526 \cmditem{booltrue}{name}
527
528 Sets the boolean flag \prm{name} to \texttt{true}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the flag is undefined.
529
530 \cmditem{boolfalse}{name}
531
532 Sets the boolean flag \prm{name} to \texttt{false}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the flag is undefined.
533
534 \cmditem{setbool}{name}{value}
535
536 Sets the boolean flag \prm{name} to \prm{value} which may be either \texttt{true} or \texttt{false}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the flag is undefined.
537
538 \cmditem{ifbool}{name}{true}{false}
539
540 Expands to \prm{true} if the state of the boolean flag \prm{name} is \texttt{true}, and to \prm{false} otherwise. If the flag is undefined, this command issues an error. This command may be used to perform any boolean test based on plain \tex syntax, \ie any test normally employed like this:
541
542 \begin{ltxcode}
543 <<\iftest>> true<<\else>> false<<\fi>>
544 \end{ltxcode}
545
546 This includes all flags defined with \cmd{newif} as well as \tex primitives such as \cmd{ifmmode}. The \cmd{if} prefix is omitted when using the flag or the primitive in the expression. For example:
547
548 \begin{ltxcode}
549 <<\ifmytest>> true\else false\fi
550 <<\ifmmode>> true\else false\fi
551 \end{ltxcode}
552 %
553 becomes
554
555 \begin{ltxcode}
556 \ifbool{<<mytest>>}{true}{false}
557 \ifbool{<<mmode>>}{true}{false}
558 \end{ltxcode}
559
560 \cmditem{notbool}{name}{not true}{not false}
561
562 Similar to \cmd{ifbool} but negates the test.
563
564 \end{ltxsyntax}
565
566 \subsubsection{\latex Flags}
567 \label{aut:bo1:tgl}
568
569 In contrast to the flags from section \ref{aut:bo1:bol}, the tools in this section require only one macro per flag. They also use a separate namespace to avoid name clashes with regular macros.
570
571 \begin{ltxsyntax}
572
573 \cmditem{newtoggle}{name}
574
575 Defines a new boolean flag called \prm{name}. If the flag has already been defined, this command issues an error. The initial state of newly defined flags is \texttt{false}. This command is robust.
576
577 \cmditem{providetoggle}{name}
578
579 Defines a new boolean flag called \prm{name} unless it has already been defined. This command is robust.
580
581 \cmditem{toggletrue}{name}
582
583 Sets the boolean flag \prm{name} to \texttt{true}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the flag is undefined.
584
585 \cmditem{togglefalse}{name}
586
587 Sets the boolean flag \prm{name} to \texttt{false}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the flag is undefined.
588
589 \cmditem{settoggle}{name}{value}
590
591 Sets the boolean flag \prm{name} to \prm{value} which may be either \texttt{true} or \texttt{false}. This command is robust and may be prefixed with \cs{global}. It will issue an error if the flag is undefined.
592
593 \cmditem{iftoggle}{name}{true}{false}
594
595 Expands to \prm{true} if the state of the boolean flag \prm{name} is \texttt{true}, and to \prm{false} otherwise. If the flag is undefined, this command issues an error.
596
597 \cmditem{nottoggle}{name}{not true}{not false}
598
599 Similar to \cmd{iftoggle} but negates the test.
600
601 \end{ltxsyntax}
602
603 \subsection{Generic Tests}
604 \label{aut:tst}
605
606 \subsubsection{Macro Tests}
607 \label{aut:tst:def}
608
609 \begin{ltxsyntax}
610
611 \cmditem{ifdef}{control sequence}{true}{false}
612
613 Expands to \prm{true} if the \prm{control sequence} is defined, and to \prm{false} otherwise. Note that control sequences will be considered as defined even if their meaning is \cmd{relax}. This command is a \latex wrapper for the \etex primitive \cmd{ifdefined}.
614
615 \cmditem{ifcsdef}{csname}{true}{false}
616
617 Similar to \cmd{ifdef} except that it takes a control sequence name as its first argument. This command is a \latex wrapper for the \etex primitive \cmd{ifcsname}.
618
619 \cmditem{ifundef}{control sequence}{true}{false}
620
621 Expands to \prm{true} if the \prm{control sequence} is undefined, and to \prm{false} otherwise. Apart from reversing the logic of the test, this command also differs from \cmd{ifdef} in that commands will be considered as undefined if their meaning is \cmd{relax}.
622
623 \cmditem{ifcsundef}{csname}{true}{false}
624
625 Similar to \cmd{ifundef} except that it takes a control sequence name as its first argument. This command may be used as a drop-in replacement for the \cmd{@ifundefined} test in the \latex kernel.
626
627 \cmditem{ifdefmacro}{control sequence}{true}{false}
628
629 Expands to \prm{true} if the \prm{control sequence} is defined and is a macro, and to \prm{false} otherwise.
630
631 \cmditem{ifcsmacro}{csname}{true}{false}
632
633 Similar to \cmd{ifdefmacro} except that it takes a control sequence name as its first argument.
634
635 \cmditem{ifdefparam}{control sequence}{true}{false}
636
637 Expands to \prm{true} if the \prm{control sequence} is defined and is a macro with one or more parameters, and to \prm{false} otherwise.
638
639 \cmditem{ifcsparam}{csname}{true}{false}
640
641 Similar to \cmd{ifdefparam} except that it takes a control sequence name as its first argument.
642
643 \cmditem{ifdefprefix}{control sequence}{true}{false}
644
645 Expands to \prm{true} if the \prm{control sequence} is defined and is a macro prefixed with \cs{long} and\slash or \cs{protected}, and to \prm{false} otherwise. Note that \cs{outer} macros may not be tested.
646
647 \cmditem{ifcsprefix}{csname}{true}{false}
648
649 Similar to \cmd{ifdefprefix} except that it takes a control sequence name as its first argument.
650
651 \cmditem{ifdefprotected}{control sequence}{true}{false}
652
653 Expands to \prm{true} if the \prm{control sequence} is defined and is a macro prefixed with \cs{protected}, and to \prm{false} otherwise.
654
655 \cmditem{ifcsprotected}{csname}{true}{false}
656
657 Similar to \cmd{ifdefprotected} except that it takes a control sequence name as its first argument.
658
659 \cmditem{ifdefltxprotect}{control sequence}{true}{false}
660
661 Executes \prm{true} if the \prm{control sequence} is defined and is a \latex protection shell, and \prm{false} otherwise. This command is robust. It will detect commands which have been defined with \cmd{DeclareRobustCommand} or by way of a similar technique.
662
663 \cmditem{ifcsltxprotect}{csname}{true}{false}
664
665 Similar to \cmd{ifdefltxprotect} except that it takes a control sequence name as its first argument.
666
667 \cmditem{ifdefempty}{control sequence}{true}{false}
668
669 Expands to \prm{true} if the \prm{control sequence} is defined and is a parameterless macro whose replacement text is empty, and to \prm{false} otherwise. In contrast to \cmd{ifx}, this test ignores the prefixes of the \prm{command}.
670
671 \cmditem{ifcsempty}{csname}{true}{false}
672
673 Similar to \cmd{ifdefempty} except that it takes a control sequence name as its first argument.
674
675 \cmditem{ifdefvoid}{control sequence}{true}{false}
676
677 Expands to \prm{true} if the \prm{control sequence} is undefined, or is a control sequence whose meaning is \cmd{relax}, or is a parameterless macro whose replacement text is empty, and to \prm{false} otherwise.
678
679 \cmditem{ifcsvoid}{csname}{true}{false}
680
681 Similar to \cmd{ifdefvoid} except that it takes a control sequence name as its first argument.
682
683 \cmditem{ifdefequal}{control sequence}{control sequence}{true}{false}
684
685 Compares two control sequences and expands to \prm{true} if they are equal in the sense of \cmd{ifx}, and to \prm{false} otherwise. In contrast to \cmd{ifx}, this test will also yield \prm{false} if both control sequences are undefined or have a meaning of \cmd{relax}.
686
687 \cmditem{ifcsequal}{csname}{csname}{true}{false}
688
689 Similar to \cmd{ifdefequal} except that it takes control sequence names as arguments.
690
691 \cmditem{ifdefstring}{command}{string}{true}{false}
692
693 Compares the replacement text of a \prm{command} to a \prm{string} and executes \prm{true} if they are equal, and \prm{false} otherwise. Neither the \prm{command} nor the \prm{string} is expanded in the test and the comparison is category code agnostic. Control sequence tokens in the \prm{string} argument will be detokenized and treated as strings. This command is robust. Note that it will only consider the replacement text of the \prm{command}. For example, this test
694
695 \begin{ltxcode}
696 \long\edef\mymacro#1#2{\string&}
697 \ifdefstring{\mymacro}{&}{true}{false}
698 \end{ltxcode}
699 %
700 would yield \prm{true}. The prefix and the parameters of \cmd{mymacro} as well as the category codes in the replacement text are ignored.
701
702 \cmditem{ifcsstring}{csname}{string}{true}{false}
703
704 Similar to \cmd{ifdefstring} except that it takes a control sequence name as its first argument.
705
706 \cmditem{ifdefstrequal}{command}{command}{true}{false}
707
708 Performs a category code agnostic string comparison of the replacement text of two commands. This command is similar to \cmd{ifdefstring} except that both arguments to be compared are macros. This command is robust.
709
710 \cmditem{ifcsstrequal}{csname}{csname}{true}{false}
711
712 Similar to \cmd{ifdefstrequal} except that it takes control sequence names as arguments.
713
714 \end{ltxsyntax}
715
716 \subsubsection{Counter and Length Tests}
717 \label{aut:tst:cnt}
718
719 \begin{ltxsyntax}
720
721 \cmditem{ifdefcounter}{control sequence}{true}{false}
722
723 Expands to \prm{true} if the \prm{control sequence} is a \tex \cmd{count} register allocated with \cmd{newcount}, and to \prm{false} otherwise.
724
725 \cmditem{ifcscounter}{csname}{true}{false}
726
727 Similar to \cmd{ifdefcounter} except that it takes a control sequence name as its first argument.
728
729 \cmditem{ifltxcounter}{name}{true}{false}
730
731 Expands to \prm{true} if \prm{name} is a \latex counter allocated with \cmd{newcounter}, and to \prm{false} otherwise.
732
733 \cmditem{ifdeflength}{control sequence}{true}{false}
734
735 Expands to \prm{true} if the \prm{control sequence} is a \tex \cmd{skip} register allocated with \cmd{newskip} or \cmd{newlength}, and to \prm{false} otherwise.
736
737 \cmditem{ifcslength}{csname}{true}{false}
738
739 Similar to \cmd{ifdeflength} except that it takes a control sequence name as its first argument.
740
741 \cmditem{ifdefdimen}{control sequence}{true}{false}
742
743 Expands to \prm{true} if the \prm{control sequence} is a \tex \cmd{dimen} register allocated with \cmd{newdimen}, and to \prm{false} otherwise.
744
745 \cmditem{ifcsdimen}{csname}{true}{false}
746
747 Similar to \cmd{ifdefdimen} except that it takes a control sequence name as its first argument.
748
749 \end{ltxsyntax}
750
751 \subsubsection{String Tests}
752 \label{aut:tst:str}
753
754 \begin{ltxsyntax}
755
756 \cmditem{ifstrequal}{string}{string}{true}{false}
757
758 Compares two strings and executes \prm{true} if they are equal, and \prm{false} otherwise. The strings are not expanded in the test and the comparison is category code agnostic. Control sequence tokens in any of the \prm{string} arguments will be detokenized and treated as strings. This command is robust.
759
760 \cmditem{ifstrempty}{string}{true}{false}
761
762 Expands to \prm{true} if the \prm{string} is empty, and to \prm{false} otherwise. The \prm{string} is not expanded in the test.
763
764 \cmditem{ifblank}{string}{true}{false}
765
766 Expands to \prm{true} if the \prm{string} is blank (empty or spaces), and to \prm{false} otherwise. The \prm{string} is not expanded in the test.
767
768 \cmditem{notblank}{string}{not true}{not false}
769
770 Similar to \cmd{ifblank} but negates the test.
771
772 \end{ltxsyntax}
773
774 \subsubsection{Arithmetic Tests}
775 \label{aut:tst:num}
776
777 \begin{ltxsyntax}
778
779 \cmditem{ifnumcomp}{integer expression}{relation}{integer expression}{true}{false}
780
781 Compares two integer expressions according to \prm{relation} and expands to \prm{true} or \prm{false} depending on the result. The \prm{relation} may be |<|, |>|, or |=|. Both integer expressions will be processed with \cmd{numexpr}. An \prm{integer expression} may be any arbitrary code which is valid in this context. All arithmetic expressions may contain spaces. Here are some examples:
782
783 \begin{ltxcode}
784 \ifnumcomp{<<3>>}{<<>>>}{<<6>>}{true}{<<false>>}
785 \ifnumcomp{<<(7 + 5) / 2>>}{<<=>>}{<<6>>}{<<true>>}{false}
786 \ifnumcomp{<<(7+5) / 4>>}{<<>>>}{<<3*(12-10)>>}{true}{<<false>>}
787 \newcounter{countA}
788 \setcounter{countA}{<<6>>}
789 \newcounter{countB}
790 \setcounter{countB}{<<5>>}
791 \ifnumcomp{<<\value{countA} * \value{countB}/2}>>{<<=>>}{<<15>>}{<<true>>}{false}
792 \ifnumcomp{<<6/2>>}{<<=>>}{<<5/2>>}{<<true>>}{false}
793 \end{ltxcode}
794 %
795 Technically, this command is a \latex wrapper for the \tex primitive \cmd{ifnum}, incorporating \cmd{numexpr}. Note that \cmd{numexpr} will round the result of all integer expressions, \ie 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 \cmd{ifnumcomp} will expand to \prm{true}.
796
797 \cmditem{ifnumequal}{integer expression}{integer expression}{true}{false}
798
799 Alternative syntax for |\ifnumcomp{...}{=}{...}{...}{...}|.
800
801 \cmditem{ifnumgreater}{integer expression}{integer expression}{true}{false}
802
803 Alternative syntax for |\ifnumcomp{...}{>}{...}{...}{...}|.
804
805 \cmditem{ifnumless}{integer expression}{integer expression}{true}{false}
806
807 Alternative syntax for |\ifnumcomp{...}{<}{...}{...}{...}|.
808
809 \cmditem{ifnumodd}{integer expression}{true}{false}
810
811 Evaluates an integer expression and expands to \prm{true} if the result is an odd number, and to \prm{false} otherwise. Technically, this command is a \latex wrapper for the \tex primitive \cmd{ifodd}, incorporating \cmd{numexpr}.
812
813 \cmditem{ifdimcomp}{dimen expression}{relation}{dimen expression}{true}{false}
814
815 Compares two dimen expressions according to \prm{relation} and expands to \prm{true} or \prm{false} depending on the result. The \prm{relation} may be |<|, |>|, or |=|. Both dimen expressions will be processed with \cmd{dimexpr}. A \prm{dimen expression} may be any arbitrary code which is valid in this context. All arithmetic expressions may contain spaces. Here are some examples:
816
817 \begin{ltxcode}
818 \ifdimcomp{<<1cm>>}{<<=>>}{<<28.45274pt>>}{<<true>>}{false}
819 \ifdimcomp{<<(7pt + 5pt) / 2>>}{<<<>>}{2pt}{true}{<<false>>}
820 \ifdimcomp{<<(3.725pt + 0.025pt) * 2>>}{<<<>>}{<<7pt>>}{true}{<<false>>}
821 \newlength{\lengthA}
822 \setlength{\lengthA}{<<7.25pt>>}
823 \newlength{\lengthB}
824 \setlength{\lengthB}{<<4.75pt>>}
825 \ifdimcomp{<<(\lengthA + \lengthB) / 2>>}{<<>>>}{<<2.75pt * 2>>}{<<true>>}{false}
826 \ifdimcomp{<<(\lengthA + \lengthB) / 2>>}{<<>>>}{<<25pt / 6>>}{<<true>>}{false}
827 \end{ltxcode}
828 %
829 Technically, this command is a \latex wrapper for the \tex primitive \cmd{ifdim}, incorporating \cmd{dimexpr}. Since both \cmd{ifdimcomp} and \cmd{ifnumcomp} are expandable, they may also be nested:
830
831 \begin{ltxcode}
832 <<\ifnumcomp>>{<<\ifdimcomp>>{<<5pt+5pt>>}{<<=>>}{<<10pt>>}{<<1>>}{<<0>>}}{<<>>>}{<<0>>}{<<true>>}{false}
833 \end{ltxcode}
834
835 \cmditem{ifdimequal}{dimen expression}{dimen expression}{true}{false}
836
837 Alternative syntax for |\ifdimcomp{...}{=}{...}{...}{...}|.
838
839 \cmditem{ifdimgreater}{dimen expression}{dimen expression}{true}{false}
840
841 Alternative syntax for |\ifdimcomp{...}{>}{...}{...}{...}|.
842
843 \cmditem{ifdimless}{dimen expression}{dimen expression}{true}{false}
844
845 Alternative syntax for |\ifdimcomp{...}{<}{...}{...}{...}|.
846
847 \end{ltxsyntax}
848
849 \subsubsection{Boolean Expressions}
850 \label{aut:tst:bol}
851
852 The commands in this section are replacements for the \cmd{ifthenelse} command provided by the \sty{ifthen} package. They serve the same purpose but differ in syntax, concept, and implementation. In contrast to \cmd{ifthenelse}, they do not provide any tests of their own but serve as a frontend to other tests. Any test which satisfies certain syntactical requirements may be used in a boolean expression.
853
854 \begin{ltxsyntax}
855
856 \cmditem{ifboolexpr}{expression}{true}{false}
857
858 Evaluates the \prm{expression} and executes \prm{true} if it is true, and \prm{false} otherwise. The \prm{expression} is evaluated sequentially from left to right. The following elements, discussed in more detail below, are available in the \prm{expression}: the test operators \texttt{togl}, \texttt{bool}, \texttt{test}; the logical operators \texttt{not}, \texttt{and}, \texttt{or}; and the subexpression delimiter \texttt{(...)}. Spaces, tabs, and line endings may be used freely to arrange the \prm{expression} visually. Blank lines are not permissible in the \prm{expression}. This command is robust.
859
860 \cmditem{ifboolexpe}{expression}{true}{false}
861
862 An expandable version of \cmd{ifboolexpr} which may be processed in an expansion-only context, \eg in an \cmd{edef} or in a \cmd{write} operation. Note that all tests used in the \prm{expression} must be expandable, even if \cmd{ifboolexpe} is not located in an expansion-only context.
863
864 \cmditem{whileboolexpr}{expression}{code}
865
866 Evaluates the \prm{expression} like \cmd{ifboolexpr} and repeatedly executes the \prm{code} while the expression is true. The \prm{code} may be any valid \tex or \latex code. This command is robust.
867
868 \cmditem{unlessboolexpr}{expression}{code}
869
870 Similar to \cmd{whileboolexpr} but negates the \prm{expression}, \ie it keeps executing the \prm{code} repeatedly unless the expression is true. This command is robust.
871
872 \end{ltxsyntax}
873 %
874 The following test operators are available in the \prm{expression}:
875
876 \begin{marglist}
877 \appto\marglistfont{\verbatimfont}
878
879 \item[togl]
880
881 Use the \texttt{togl} operator to test the state of a flag defined with \cmd{newtoggle}. For example:
882
883 \begin{ltxcode}
884 <<\iftoggle{mytoggle}>>{true}{false}
885 \end{ltxcode}
886 %
887 becomes
888
889 \begin{ltxcode}
890 \ifboolexpr{ <<togl>> {<<mytoggle>>} }{true}{false}
891 \end{ltxcode}
892 %
893 The \texttt{togl} operator may be used with both \cmd{ifboolexpr} and \cmd{ifboolexpe}.
894
895 \item[bool]
896
897 Use the \texttt{bool} operator to perform a boolean test based on plain \tex syntax, \ie any test normally employed like this:
898
899 \begin{ltxcode}
900 <<\iftest>> true<<\else>> false<<\fi>>
901 \end{ltxcode}
902 %
903 This includes all flags defined with \cmd{newif} as well as \tex primitives such as \cmd{ifmmode}. The \cmd{if} prefix is omitted when using the flag or the primitive in the expression. For example:
904
905 \begin{ltxcode}
906 <<\ifmmode>> true\else false\fi
907 <<\ifmytest>> true\else false\fi
908 \end{ltxcode}
909 %
910 becomes
911
912 \begin{ltxcode}
913 \ifboolexpr{ <<bool>> {<<mmode>>} }{true}{false}
914 \ifboolexpr{ <<bool>> {<<mytest>>} }{true}{false}
915 \end{ltxcode}
916 %
917 This also works with flags defined with \cmd{newbool} (see \secref{aut:bo1:bol}). In this case
918
919 \begin{ltxcode}
920 <<\ifbool{mybool}>>{true}{false}
921 \end{ltxcode}
922 %
923 becomes
924
925 \begin{ltxcode}
926 \ifboolexpr{ <<bool>> {<<mybool>>} }{true}{false}
927 \end{ltxcode}
928 %
929 The \texttt{bool} operator may be used with both \cmd{ifboolexpr} and \cmd{ifboolexpe}.
930
931 \item[test]
932
933 Use the \texttt{test} operator to perform a test based on \latex syntax, \ie any test normally employed like this:
934
935 \begin{ltxcode}
936 <<\iftest>>{<<true>>}{<<false>>}
937 \end{ltxcode}
938 %
939 This applies to all macros based on \latex syntax, \ie the macro must take a \prm{true} and a \prm{false} argument and these must be the final arguments. For example:
940
941 \begin{ltxcode}
942 <<\ifdef>>{\somemacro}<<{true}{false}>>
943 <<\ifdimless>>{\textwidth}{365pt}<<{true}{false}>>
944 <<\ifnumcomp>>{\value{somecounter}}{>}{3}<<{true}{false}>>
945 \end{ltxcode}
946
947 When using such tests in the \prm{expression}, their \prm{true} and \prm{false} arguments are omitted. For example:
948
949 \begin{ltxcode}
950 <<\ifcsdef{mymacro}>>{true}{false}
951 \end{ltxcode}
952 %
953 becomes
954
955 \begin{ltxcode}
956 \ifboolexpr{ <<test>> {<<\ifcsdef{mymacro}>>} }{true}{false}
957 \end{ltxcode}
958 %
959 and
960
961 \begin{ltxcode}
962 <<\ifnumcomp{\value{mycounter}}{>}{3}>>{true}{false}
963 \end{ltxcode}
964 %
965 becomes
966
967 \begin{ltxcode}
968 \ifboolexpr{
969 <<test>> {<<\ifnumcomp{\value{mycounter}}{>}{3}>>}
970 }
971 {true}
972 {false}
973 \end{ltxcode}
974 %
975 The \texttt{test} operator may be used with \cmd{ifboolexpr} without any restrictions. It may also be used with \cmd{ifboolexpe}, provided that the test is expandable. Some of the generic tests in \secref{aut:tst} are robust and may not be used with \cmd{ifboolexpe}, even if \cmd{ifboolexpe} is not located in an expansion-only context. Use \cmd{ifboolexpr} instead if the test is not expandable.
976
977 \end{marglist}
978
979 Since \cmd{ifboolexpr} and \cmd{ifboolexpe} imply processing overhead, there is generally no benefit in employing them for a single test. The stand-alone tests in \secref{aut:tst} are more efficient than \texttt{test}, \cmd{ifbool} from \secref{aut:bo1:bol} is more efficient than \texttt{bool}, and \cmd{iftoggle} from \secref{aut:bo1:tgl} is more efficient than \texttt{togl}. The point of \cmd{ifboolexpr} and \cmd{ifboolexpe} is that they support logical operators and subexpressions. The following logical operators are available in the \prm{expression}:
980
981 \begin{marglist}
982 \appto\marglistfont{\verbatimfont}
983
984 \item[not]
985
986 The \texttt{not} operator negates the truth value of the immediately following element. You may prefix \texttt{togl}, \texttt{bool}, \texttt{test}, and subexpressions with \texttt{not}. For example:
987
988 \begin{ltxcode}
989 \ifboolexpr{
990 <<not>> bool {mybool}
991 }
992 {true}
993 {false}
994 \end{ltxcode}
995 %
996 will yield \prm{true} if \texttt{mybool} is false and \prm{false} if \texttt{mybool} is true, and
997
998 \begin{ltxcode}
999 \ifboolexpr{
1000 <<not (>> bool {boolA} or bool {boolB} <<)>>
1001 }
1002 {true}
1003 {false}
1004 \end{ltxcode}
1005 %
1006 will yield \prm{true} if both \texttt{boolA} and \texttt{boolB} are false.
1007
1008 \item[and]
1009
1010 The \texttt{and} operator expresses a conjunction (both \emph{a} and \emph{b}). The \prm{expression} is true if all elements joined with \texttt{and} are true. For example:
1011
1012 \begin{ltxcode}
1013 \ifboolexpr{
1014 bool {boolA} <<and>> bool {boolB}
1015 }
1016 {true}
1017 {false}
1018 \end{ltxcode}
1019 %
1020 will yield \prm{true} if both \texttt{bool} tests are true. The \texttt{nand} operator (negated \texttt{and}, \ie not both) is not provided as such but may be expressed by using \texttt{and} in a negated subexpression. For example:
1021
1022 \begin{ltxcode}
1023 bool {boolA} <<nand>> bool {boolB}
1024 \end{ltxcode}
1025 %
1026 may be written as
1027
1028 \begin{ltxcode}
1029 <<not>> <<(>> bool {boolA} <<and>> bool {boolB} <<)>>
1030 \end{ltxcode}
1031
1032 \item[or]
1033
1034 The \texttt{or} operator expresses a non-exclusive disjunction (either \emph{a} or \emph{b} or both). The \prm{expression} is true if at least one of the elements joined with \texttt{or} is true. For example:
1035
1036 \begin{ltxcode}
1037 \ifboolexpr{
1038 togl {toglA} <<or>> togl {toglB}
1039 }
1040 {true}
1041 {false}
1042 \end{ltxcode}
1043 %
1044 will yield \prm{true} if either \texttt{togl} test or both tests are true. The \texttt{nor} operator (negated non-exclusive disjunction, \ie neither \emph{a} nor \emph{b} nor both) is not provided as such but may be expressed by using \texttt{or} in a negated subexpression. For example:
1045
1046 \begin{ltxcode}
1047 bool {boolA} <<nor>> bool {boolB}
1048 \end{ltxcode}
1049 %
1050 may be written as
1051
1052 \begin{ltxcode}
1053 <<not>> <<(>> bool {boolA} <<or>> bool {boolB} <<)>>
1054 \end{ltxcode}
1055
1056 \item[(...)]
1057
1058 The parentheses delimit a subexpression in the \prm{expression}. The subexpression is evaluated and the result of this evaluation is treated as a single truth value in the enclosing expression. Subexpressions may be nested. For example, the expression:
1059
1060 \begin{ltxcode}
1061 <<(>> bool {boolA} or bool {boolB} <<)>>
1062 and
1063 <<(>> bool {boolC} or bool {boolD} <<)>>
1064 \end{ltxcode}
1065 %
1066 is true if both subexpressions are true, \ie if at least one of \texttt{boolA}/\texttt{boolB} and at least one of \texttt{boolC}/\texttt{boolD} is true. Subexpressions are generally not required if all elements are joined with \texttt{and} or with \texttt{or}. For example, the expressions
1067
1068 \begin{ltxcode}
1069 bool {boolA} <<and>> bool {boolB} <<and>> {boolC} <<and>> bool {boolD}
1070 bool {boolA} <<or>> bool {boolB} <<or>> {boolC} <<or>> bool {boolD}
1071 \end{ltxcode}
1072 %
1073 will yield the expected results: the first one is true if all elements are true; the second one is true if at least one element is true. However, when combining \texttt{and} and \texttt{or}, it is advisable to always group the elements in subexpressions in order to avoid potential misconceptions which may arise from differences between the semantics of formal boolean expressions and the semantics of natural languages. For example, the following expression
1074
1075 \begin{ltxcode}
1076 bool {<<coffee>>} <<and>> bool {<<milk>>} <<or>> bool {<<sugar>>}
1077 \end{ltxcode}
1078 %
1079 is always true if \texttt{sugar} is true since the \texttt{or} operator will take the result of the \texttt{and} evaluation as input. In contrast to the meaning of this expression when pronounced in English, it is not processed like this
1080
1081 \begin{ltxcode}
1082 bool {<<coffee>>} <<and>> <<(>> bool {<<milk>>} <<or>> bool {<<sugar>>} <<)>>
1083 \end{ltxcode}
1084 %
1085 but evaluated strictly from left to right:
1086
1087 \begin{ltxcode}
1088 <<(>> bool {<<coffee>>} <<and>> bool {<<milk>>} <<)>> <<or>> bool {<<sugar>>}
1089 \end{ltxcode}
1090 %
1091 which is probably not what you meant to order.
1092
1093 \end{marglist}
1094
1095 \subsection{List Processing}
1096 \label{aut:lst}
1097
1098 \subsubsection{User Input}
1099 \label{aut:lst:inp}
1100
1101 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 \ref{aut:lst:int} may be preferable as they allow testing if an element is in a list.
1102
1103 \begin{ltxsyntax}
1104
1105 \cmditem{DeclareListParser}{command}{separator}
1106
1107 This command defines a list parser similar to the \cmd{docsvlist} command below, which is defined like this:
1108
1109 \begin{ltxcode}
1110 \DeclareListParser{\docsvlist}{,}
1111 \end{ltxcode}
1112 %
1113 Note that the list parsers are sensitive to the category code of the \prm{separator}.
1114
1115 \cmditem*{DeclareListParser*}{command}{separator}
1116
1117 The starred variant of \cmd{DeclareListParser} defines a list parser similar to the \cmd{forcsvlist} command below, which is defined like this:
1118
1119 \begin{ltxcode}
1120 \DeclareListParser*{\forcsvlist}{,}
1121 \end{ltxcode}
1122
1123 \cmditem{docsvlist}{item, item, ...}
1124
1125 This command loops over a comma"=separated list of items and executes the auxiliary command \cmd{do} for every item in the list, passing the item as an argument. In contrast to the \cmd{@for} loop in the \latex kernel, \cmd{docsvlist} is expandable. With a suitable definition of \cmd{do}, lists may be processed in an \cmd{edef} or a comparable context. You may use \cmd{listbreak} at the end of the replacement text of \cmd{do} to stop processing and discard the remaining items in the list. Whitespace after list separators is ignored. If an item contains a comma or starts with a space, it must be wrapped in curly braces. The braces will be removed as the list is processed. Here is a usage example which prints a comma"=separated list as an \env{itemize} environment:
1126
1127 \begin{ltxcode}
1128 \begin{itemize}
1129 \renewcommand*{\do}[1]{\item #1}
1130 \docsvlist{item1, item2, {item3a, item3b}, item4}
1131 \end{itemize}
1132 \end{ltxcode}
1133 %
1134 Here is another example:
1135
1136 \begin{ltxcode}
1137 \renewcommand*{\do}[1]{* #1\MessageBreak}
1138 \PackageInfo{mypackage}{%
1139 Example list:\MessageBreak
1140 \docsvlist{item1, item2, {item3a, item3b}, item4}}
1141 \end{ltxcode}
1142 %
1143 In this example, the list is written to the log file as part of an informational message. The list processing takes place during the \cmd{write} operation.
1144
1145 \cmditem{forcsvlist}{handler}{item, item, ...}
1146
1147 This command is similar to \cmd{docsvlist} except that \cmd{do} is replaced by a \prm{handler} specified at invocation time. The \prm{handler} 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 \cmd{mylist}:
1148
1149 \begin{ltxcode}
1150 \forcsvlist{\listadd\mylist}{item1, item2, item3}
1151 \end{ltxcode}
1152
1153 \end{ltxsyntax}
1154
1155 \subsubsection{Internal Lists}
1156 \label{aut:lst:int}
1157
1158 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.\footnote{The character \texttt{\string|} with category code 3. Note that you may not typeset a list by saying \cmd{listname}. Use \cmd{show} instead to inspect the list.} When processing user input in list format, see the tools in section \ref{aut:lst:inp}.
1159
1160 \begin{ltxsyntax}
1161
1162 \cmditem{listadd}{listmacro}{item}
1163
1164 This command appends an \prm{item} to a \prm{listmacro}. A blank \prm{item} is not added to the list.
1165
1166 \cmditem{listgadd}{listmacro}{item}
1167
1168 Similar to \cmd{listadd} except that the assignment is global.
1169
1170 \cmditem{listeadd}{listmacro}{item}
1171
1172 Similar to \cmd{listadd} except that the \prm{item} is expanded at definition"=time. Only the new \prm{item} is expanded, the \prm{listmacro} is not. If the expanded \prm{item} is blank, it is not added to the list.
1173
1174 \cmditem{listxadd}{listmacro}{item}
1175
1176 Similar to \cmd{listeadd} except that the assignment is global.
1177
1178 \cmditem{listcsadd}{listcsname}{item}
1179
1180 Similar to \cmd{listadd} except that it takes a control sequence name as its first argument.
1181
1182 \cmditem{listcsgadd}{listcsname}{item}
1183
1184 Similar to \cmd{listcsadd} except that the assignment is global.
1185
1186 \cmditem{listcseadd}{listcsname}{item}
1187
1188 Similar to \cmd{listeadd} except that it takes a control sequence name as its first argument.
1189
1190 \cmditem{listcsxadd}{listcsname}{item}
1191
1192 Similar to \cmd{listcseadd} except that the assignment is global.
1193
1194 \cmditem{listremove}{listmacro}{item}
1195
1196 This command removes an \prm{item} from a \prm{listmacro}. A blank \prm{item} is ignored.
1197
1198 \cmditem{listgremove}{listmacro}{item}
1199
1200 Similar to \cmd{listremove} except that the assignment is global.
1201
1202 \cmditem{listcsremove}{listcsname}{item}
1203
1204 Similar to \cmd{listremove} except that it takes a control sequence name as its first argument.
1205
1206 \cmditem{listcsgremove}{listcsname}{item}
1207
1208 Similar to \cmd{listcsremove} except that the assignment is global.
1209
1210 \cmditem{dolistloop}{listmacro}
1211
1212 This command loops over all items in a \prm{listmacro} and executes the auxiliary command \cmd{do} for every item in the list, passing the item as an argument. The list loop itself is expandable. You may use \cmd{listbreak} at the end of the replacement text of \cmd{do} to stop processing and discard the remaining items in the list. Here is a usage example which prints an internal list called \cmd{mylist} as an \env{itemize} environment:
1213
1214 \begin{ltxcode}
1215 \begin{itemize}
1216 \renewcommand*{\do}[1]{\item #1}
1217 \dolistloop{\mylist}
1218 \end{itemize}
1219 \end{ltxcode}
1220
1221 \cmditem{dolistcsloop}{listcsname}
1222
1223 Similar to \cmd{dolistloop} except that it takes a control sequence name as its argument.
1224
1225 \cmditem{forlistloop}{handler}{listmacro}
1226
1227 This command is similar to \cmd{dolistloop} except that \cmd{do} is replaced by a \prm{handler} specified at invocation time. The \prm{handler} 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 \cmd{mylist} with \cmd{item}, count the items as the list is processed, and append the item count at the end:
1228
1229 \begin{ltxcode}
1230 \newcounter{itemcount}
1231 \begin{itemize}
1232 \forlistloop{\stepcounter{itemcount}\item}{\mylist}
1233 \item Total: \number\value{itemcount} items
1234 \end{itemize}
1235 \end{ltxcode}
1236
1237 \cmditem{forlistcsloop}{handler}{listcsname}
1238
1239 Similar to \cmd{forlistloop} except that it takes a control sequence name as its second argument.
1240
1241 \cmditem{ifinlist}{item}{listmacro}{true}{false}
1242
1243 This command executes \prm{true} if the \prm{item} is included in a \prm{listmacro}, and \prm{false} otherwise. Note that this test uses pattern matching based on \tex's argument scanner to check if the search string is included in the list. This means that it is usually faster than looping over all items in the list, but it also implies that the items must not include curly braces which would effectively hide them from the scanner. In other words, this macro is most useful when dealing with lists of plain strings rather than printable data. When dealing with printable text, it is safer to use \cmd{dolistloop} to check if an item is in the list as follows:
1244
1245 \begin{ltxcode}
1246 \renewcommand*{\do}[1]{%
1247 \ifstrequal{#1}{<<item>>}
1248 {item found!\listbreak}
1249 {}}
1250 \dolistloop{\mylist}
1251 \end{ltxcode}
1252
1253 \cmditem{xifinlist}{item}{listmacro}{true}{false}
1254
1255 Similar to \cmd{ifinlist} except that the \prm{item} is expanded prior to the test.
1256
1257 \cmditem{ifinlistcs}{item}{listcsname}{true}{false}
1258
1259 Similar to \cmd{ifinlist} except that it takes a control sequence name as its second argument.
1260
1261 \cmditem{xifinlistcs}{item}{listcsname}{true}{false}
1262
1263 Similar to \cmd{xifinlist} except that it takes a control sequence name as its second argument.
1264
1265 \end{ltxsyntax}
1266
1267 \subsection{Miscellaneous Tools}
1268 \label{aut:msc}
1269
1270 \begin{ltxsyntax}
1271
1272 \cmditem{rmntonum}{numeral}
1273
1274 The \tex primitive \cmd{romannumeral} converts an integer to a Roman numeral but \tex or \latex provide no command which goes the opposite way. \cmd{rmntonum} fills this gap. It takes a Roman numeral as its argument and converts it to the corresponding integer. Since it is expandable, it may also be used in counter assignments or arithmetic tests:
1275
1276 \begin{ltxcode}
1277 <<\rmntonum>>{<<mcmxcv>>}
1278 \setcounter{counter}{<<\rmntonum>>{<<CXVI>>}}
1279 \ifnumless{<<\rmntonum>>{<<mcmxcviii>>}}{2000}{true}{false}
1280 \end{ltxcode}
1281 %
1282 The \prm{numeral} argument must be a literal string. It will be detokenized prior to parsing. The parsing of the numeral is case"=insensitive and whitespace in the argument is ignored. If there is an invalid token in the argument, \cmd{rmntonum} will expand to~\texttt{-1}; an empty argument will yield an empty string. Note that \cmd{rmntonum} will not check the numeral for formal validity. For example, both \texttt{V} and \texttt{VX} would yield \texttt{5}, \texttt{IC} would yield \texttt{99}, etc.
1283
1284 \cmditem{ifrmnum}{string}{true}{false}
1285
1286 Expands to \prm{true} if \prm{string} is a Roman numeral, and to \prm{false} otherwise. The \prm{string} will be detokenized prior to performing the test. The test is case"=insensitive and ignores whitespace in the \prm{string}. Note that \cmd{ifrmnum} will not check the numeral for formal validity. For example, both \texttt{V} and \texttt{VXV} will yield \prm{true}. Strictly speaking, what \cmd{ifrmnum} does is parse the \prm{string} in order to find out if it consists of characters which may form a valid Roman numeral, but it will not check if they really are a valid Roman numeral.
1287
1288 \end{ltxsyntax}
1289
1290 \section{Reporting issues}
1291
1292 The development code for \sty{etoolbox} is hosted on GitHub: \url{https://github.com/josephwright/etoolbox}. This is the best place to log any issues with the package.
1293
1294 \section{Revision History}
1295
1296 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 \emph{improved} or \emph{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 \emph{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.
1297
1298 \begin{changelog}
1299
1300 \begin{release}{2.5m}{2025-10-02}
1301 \item Track kernel updates
1302 \end{release}
1303
1304 \begin{release}{2.5l}{2025-02-11}
1305 \item Fix handling of \cmd{long} macros linked to \cmd{NewCommandCopy}
1306 \end{release}
1307
1308 \begin{release}{2.5k}{2020-10-05}
1309 \item Internal updates
1310 \end{release}
1311
1312 \begin{release}{2.5j}{2020-08-24}
1313 \item Track \LaTeXe{} kernel changes
1314 \end{release}
1315
1316 \begin{release}{2.5i}{2020-07-13}
1317 \item Track \LaTeXe{} kernel changes
1318 \end{release}
1319
1320 \begin{release}{2.5h}{2019-09-21}
1321 \item Add missing \cmd{gundef}
1322 \end{release}
1323
1324 \begin{release}{2.5g}{2019-09-09}
1325 \item Update patching of \cmd{begin} and \cmd{end} in advance of \LaTeX{}
1326 kernel changes
1327 \end{release}
1328
1329 \begin{release}{2.5f}{2018-08-18}
1330 \item Fix issue with \cmd{ifdefempty}, \cmd{ifcsempty}, \cs{ifdefvoid}
1331 and \cmd{ifcsvoid} when applied to macros expanding to space tokens
1332 \end{release}
1333
1334 \begin{release}{2.5e}{2018-02-11}
1335 \item More work on empty list separator in \cmd{DeclareListParser}
1336 \end{release}
1337
1338 \begin{release}{2.5d}{2018-02-10}
1339 \item Allow for empty list separator in \cmd{DeclareListParser}
1340 \end{release}
1341
1342 \begin{release}{2.5c}{2018-02-06}
1343 \item Fix issue with \cmd{forcsvlist} introduced by v2.5b
1344 \end{release}
1345
1346 \begin{release}{2.5b}{2018-02-04}
1347 \item Preserve braces in some internal steps
1348 \item Internal performance improvements in list processors
1349 \end{release}
1350
1351 \begin{release}{2.5a}{2018-02-03}
1352 \item Internal performance improvements in list processors
1353 \end{release}
1354
1355 \begin{release}{2.5}{2017-11-22}
1356 \item Added \cmd{csgundef}\see{aut:def:def}
1357 \item Added \cmd{gundef}\see{aut:def:def}
1358 \item Allow scanning of macros containing new line characters
1359 \end{release}
1360
1361 \begin{release}{2.4}{2017-01-02}
1362 \item Renamed \cmd{listdel} to \cmd{listremove} (name clash)\see{aut:lst:int}
1363 \item Renamed \cmd{listgdel} to \cmd{listgremove} (name clash)\see{aut:lst:int}
1364 \end{release}
1365
1366 \begin{release}{2.3}{2016-12-26}
1367 \item Added \cmd{listdel}\see{aut:lst:int}
1368 \item Added \cmd{listgdel}\see{aut:lst:int}
1369 \end{release}
1370
1371 \begin{release}{2.2b}{2016-12-01}
1372 \item Fixed \cmd{ifdefltxprotect} for some types of \latex robust commands
1373 \item Remove redundant macro after \cmd{robustify} processing
1374 \end{release}
1375
1376 \begin{release}{2.2a}{2015-08-02}
1377 \item Fixed robustness bug in \cmd{ifblank}/\cmd{notblank}
1378 \end{release}
1379
1380 \begin{release}{2.2}{2015-05-04}
1381 \item Added \cmd{csmeaning}\see{aut:def:def}
1382 \end{release}
1383
1384 \begin{release}{2.1d}{2015-03-19}
1385 \item Fixed issue with \sty{bm} and some classes
1386 \end{release}
1387
1388 \begin{release}{2.1c}{2015-03-15}
1389 \item Fixed space bug in \cmd{ifpatchable}
1390 \item Fixed space bug in \cmd{patchcmd}
1391 \item Fixed space bug in \cmd{robustify}
1392 \end{release}
1393
1394 \begin{release}{2.1b}{2015-03-10}
1395 \item Minor documentation fixes
1396 \end{release}
1397
1398 \begin{release}{2.1a}{2015-03-10}
1399 \item New maintainer: Joseph Wright
1400 \item Skip loading \sty{etex} package with newer \latex kernel releases
1401 \end{release}
1402
1403 \begin{release}{2.1}{2011-01-03}
1404 \item Added \cmd{AtBeginEnvironment}\see{use:env}
1405 \item Added \cmd{AtEndEnvironment}\see{use:env}
1406 \item Added \cmd{BeforeBeginEnvironment}\see{use:env}
1407 \item Added \cmd{AfterEndEnvironment}\see{use:env}
1408 \item Added \cmd{ifdefstrequal}\see{aut:tst:def}
1409 \item Added \cmd{ifcsstrequal}\see{aut:tst:def}
1410 \item Added \cmd{ifdefcounter}\see{aut:tst:cnt}
1411 \item Added \cmd{ifcscounter}\see{aut:tst:cnt}
1412 \item Added \cmd{ifltxcounter}\see{aut:tst:cnt}
1413 \item Added \cmd{ifdeflength}\see{aut:tst:cnt}
1414 \item Added \cmd{ifcslength}\see{aut:tst:cnt}
1415 \item Added \cmd{ifdefdimen}\see{aut:tst:cnt}
1416 \item Added \cmd{ifcsdimen}\see{aut:tst:cnt}
1417 \end{release}
1418
1419 \begin{release}{2.0a}{2010-09-12}
1420 \item Fixed bug in \cmd{patchcmd}, \cmd{apptocmd}, \cmd{pretocmd}\see{aut:pat}
1421 \end{release}
1422
1423 \begin{release}{2.0}{2010-08-21}
1424
1425 \item Added \cmd{csshow}\see{aut:def:def}
1426 \item Added \cmd{DeclareListParser*}\see{aut:lst:inp}
1427 \item Added \cmd{forcsvlist}\see{aut:lst:inp}
1428 \item Added \cmd{forlistloop}\see{aut:lst:int}
1429 \item Added \cmd{forlistcsloop}\see{aut:lst:int}
1430 \item Allow testing \cmd{par} in macro tests\see{aut:tst:def}
1431 \item Fixed some bugs
1432
1433 \end{release}
1434
1435 \begin{release}{1.9}{2010-04-10}
1436
1437 \item Improved \cmd{letcs}\see{aut:def:def}
1438 \item Improved \cmd{csletcs}\see{aut:def:def}
1439 \item Improved \cmd{listeadd}\see{aut:lst:int}
1440 \item Improved \cmd{listxadd}\see{aut:lst:int}
1441 \item Added \cmd{notblank}\see{aut:tst:str}
1442 \item Added \cmd{ifnumodd}\see{aut:tst:num}
1443 \item Added \cmd{ifboolexpr}\see{aut:tst:bol}
1444 \item Added \cmd{ifboolexpe}\see{aut:tst:bol}
1445 \item Added \cmd{whileboolexpr}\see{aut:tst:bol}
1446 \item Added \cmd{unlessboolexpr}\see{aut:tst:bol}
1447
1448 \end{release}
1449
1450 \begin{release}{1.8}{2009-08-06}
1451
1452 \item Improved \cmd{deflength}\see{use:cal}
1453 \item Added \cmd{ifnumcomp}\see{aut:tst:num}
1454 \item Added \cmd{ifnumequal}\see{aut:tst:num}
1455 \item Added \cmd{ifnumgreater}\see{aut:tst:num}
1456 \item Added \cmd{ifnumless}\see{aut:tst:num}
1457 \item Added \cmd{ifdimcomp}\see{aut:tst:num}
1458 \item Added \cmd{ifdimequal}\see{aut:tst:num}
1459 \item Added \cmd{ifdimgreater}\see{aut:tst:num}
1460 \item Added \cmd{ifdimless}\see{aut:tst:num}
1461
1462 \end{release}
1463
1464 \begin{release}{1.7}{2008-06-28}
1465
1466 \item Renamed \cmd{AfterBeginDocument} to \cmd{AfterEndPreamble} (name clash)\see{use:pre}
1467 \item Resolved conflict with \sty{hyperref}
1468 \item Rearranged manual slightly
1469
1470 \end{release}
1471
1472 \begin{release}{1.6}{2008-06-22}
1473
1474 \item Improved \cmd{robustify}\see{use:pat}
1475 \item Improved \cmd{patchcmd} and \cmd{ifpatchable}\see{aut:pat}
1476 \item Modified and improved \cmd{apptocmd}\see{aut:pat}
1477 \item Modified and improved \cmd{pretocmd}\see{aut:pat}
1478 \item Added \cmd{ifpatchable*}\see{aut:pat}
1479 \item Added \cmd{tracingpatches}\see{aut:pat}
1480 \item Added \cmd{AfterBeginDocument}\see{use:pre}
1481 \item Added \cmd{ifdefmacro}\see{aut:tst:def}
1482 \item Added \cmd{ifcsmacro}\see{aut:tst:def}
1483 \item Added \cmd{ifdefprefix}\see{aut:tst:def}
1484 \item Added \cmd{ifcsprefix}\see{aut:tst:def}
1485 \item Added \cmd{ifdefparam}\see{aut:tst:def}
1486 \item Added \cmd{ifcsparam}\see{aut:tst:def}
1487 \item Added \cmd{ifdefprotected}\see{aut:tst:def}
1488 \item Added \cmd{ifcsprotected}\see{aut:tst:def}
1489 \item Added \cmd{ifdefltxprotect}\see{aut:tst:def}
1490 \item Added \cmd{ifcsltxprotect}\see{aut:tst:def}
1491 \item Added \cmd{ifdefempty}\see{aut:tst:def}
1492 \item Added \cmd{ifcsempty}\see{aut:tst:def}
1493 \item Improved \cmd{ifdefvoid}\see{aut:tst:def}
1494 \item Improved \cmd{ifcsvoid}\see{aut:tst:def}
1495 \item Added \cmd{ifstrempty}\see{aut:tst:str}
1496 \item Added \cmd{setbool}\see{aut:bo1:bol}
1497 \item Added \cmd{settoggle}\see{aut:bo1:tgl}
1498
1499 \end{release}
1500
1501 \begin{release}{1.5}{2008-04-26}
1502
1503 \item Added \cmd{defcounter}\see{use:cal}
1504 \item Added \cmd{deflength}\see{use:cal}
1505 \item Added \cmd{ifdefstring}\see{aut:tst:def}
1506 \item Added \cmd{ifcsstring}\see{aut:tst:def}
1507 \item Improved \cmd{rmntonum}\see{aut:msc}
1508 \item Added \cmd{ifrmnum}\see{aut:msc}
1509 \item Added extended \pdf bookmarks to this manual
1510 \item Rearranged manual slightly
1511
1512 \end{release}
1513
1514 \begin{release}{1.4}{2008-01-24}
1515
1516 \item Resolved conflict with \sty{tex4ht}
1517
1518 \end{release}
1519
1520 \begin{release}{1.3}{2007-10-08}
1521
1522 \item Renamed package from \sty{elatex} to \sty{etoolbox}\see{int}
1523 \item Renamed \cmd{newswitch} to \cmd{newtoggle} (name clash)\see{aut:bo1:tgl}
1524 \item Renamed \cmd{provideswitch} to \cmd{providetoggle} (consistency)\see{aut:bo1:tgl}
1525 \item Renamed \cmd{switchtrue} to \cmd{toggletrue} (consistency)\see{aut:bo1:tgl}
1526 \item Renamed \cmd{switchfalse} to \cmd{togglefalse} (consistency)\see{aut:bo1:tgl}
1527 \item Renamed \cmd{ifswitch} to \cmd{iftoggle} (consistency)\see{aut:bo1:tgl}
1528 \item Renamed \cmd{notswitch} to \cmd{nottoggle} (consistency)\see{aut:bo1:tgl}
1529 \item Added \cmd{AtEndPreamble}\see{use:pre}
1530 \item Added \cmd{AfterEndDocument}\see{use:pre}
1531 \item Added \cmd{AfterPreamble}\see{use:pre}
1532 \item Added \cmd{undef}\see{aut:def:def}
1533 \item Added \cmd{csundef}\see{aut:def:def}
1534 \item Added \cmd{ifdefvoid}\see{aut:tst:def}
1535 \item Added \cmd{ifcsvoid}\see{aut:tst:def}
1536 \item Added \cmd{ifdefequal}\see{aut:tst:def}
1537 \item Added \cmd{ifcsequal}\see{aut:tst:def}
1538 \item Added \cmd{ifstrequal}\see{aut:tst:str}
1539 \item Added \cmd{listadd}\see{aut:lst:int}
1540 \item Added \cmd{listeadd}\see{aut:lst:int}
1541 \item Added \cmd{listgadd}\see{aut:lst:int}
1542 \item Added \cmd{listxadd}\see{aut:lst:int}
1543 \item Added \cmd{listcsadd}\see{aut:lst:int}
1544 \item Added \cmd{listcseadd}\see{aut:lst:int}
1545 \item Added \cmd{listcsgadd}\see{aut:lst:int}
1546 \item Added \cmd{listcsxadd}\see{aut:lst:int}
1547 \item Added \cmd{ifinlist}\see{aut:lst:int}
1548 \item Added \cmd{xifinlist}\see{aut:lst:int}
1549 \item Added \cmd{ifinlistcs}\see{aut:lst:int}
1550 \item Added \cmd{xifinlistcs}\see{aut:lst:int}
1551 \item Added \cmd{dolistloop}\see{aut:lst:int}
1552 \item Added \cmd{dolistcsloop}\see{aut:lst:int}
1553
1554 \end{release}
1555
1556 \begin{release}{1.2}{2007-07-13}
1557
1558 \item Renamed \cmd{patchcommand} to \cmd{patchcmd} (name clash)\see{aut:pat}
1559 \item Renamed \cmd{apptocommand} to \cmd{apptocmd} (consistency)\see{aut:pat}
1560 \item Renamed \cmd{pretocommand} to \cmd{pretocmd} (consistency)\see{aut:pat}
1561 \item Added \cmd{newbool}\see{aut:bo1:bol}
1562 \item Added \cmd{providebool}\see{aut:bo1:bol}
1563 \item Added \cmd{booltrue}\see{aut:bo1:bol}
1564 \item Added \cmd{boolfalse}\see{aut:bo1:bol}
1565 \item Added \cmd{ifbool}\see{aut:bo1:bol}
1566 \item Added \cmd{notbool}\see{aut:bo1:bol}
1567 \item Added \cmd{newswitch}\see{aut:bo1:tgl}
1568 \item Added \cmd{provideswitch}\see{aut:bo1:tgl}
1569 \item Added \cmd{switchtrue}\see{aut:bo1:tgl}
1570 \item Added \cmd{switchfalse}\see{aut:bo1:tgl}
1571 \item Added \cmd{ifswitch}\see{aut:bo1:tgl}
1572 \item Added \cmd{notswitch}\see{aut:bo1:tgl}
1573 \item Added \cmd{DeclareListParser}\see{aut:lst:inp}
1574 \item Added \cmd{docsvlist}\see{aut:lst:inp}
1575 \item Added \cmd{rmntonum}\see{aut:msc}
1576
1577 \end{release}
1578
1579 \begin{release}{1.1}{2007-05-28}
1580
1581 \item Added \cmd{protected@csedef}\see{aut:def:def}
1582 \item Added \cmd{protected@csxdef}\see{aut:def:def}
1583 \item Added \cmd{gluedef}\see{aut:def:cal}
1584 \item Added \cmd{gluegdef}\see{aut:def:cal}
1585 \item Added \cmd{csgluedef}\see{aut:def:cal}
1586 \item Added \cmd{csgluegdef}\see{aut:def:cal}
1587 \item Added \cmd{mudef}\see{aut:def:cal}
1588 \item Added \cmd{mugdef}\see{aut:def:cal}
1589 \item Added \cmd{csmudef}\see{aut:def:cal}
1590 \item Added \cmd{csmugdef}\see{aut:def:cal}
1591 \item Added \cmd{protected@eappto}\see{aut:hok:app}
1592 \item Added \cmd{protected@xappto}\see{aut:hok:app}
1593 \item Added \cmd{protected@cseappto}\see{aut:hok:app}
1594 \item Added \cmd{protected@csxappto}\see{aut:hok:app}
1595 \item Added \cmd{protected@epreto}\see{aut:hok:pre}
1596 \item Added \cmd{protected@xpreto}\see{aut:hok:pre}
1597 \item Added \cmd{protected@csepreto}\see{aut:hok:pre}
1598 \item Added \cmd{protected@csxpreto}\see{aut:hok:pre}
1599 \item Fixed bug in \cmd{newrobustcmd}\see{use:def}
1600 \item Fixed bug in \cmd{renewrobustcmd}\see{use:def}
1601 \item Fixed bug in \cmd{providerobustcmd}\see{use:def}
1602
1603 \end{release}
1604
1605 \begin{release}{1.0}{2007-05-07}
1606
1607 \item Initial public release
1608
1609 \end{release}
1610
1611 \end{changelog}
1612
1613 \end{document}