% \def\fileversion{5.1}\def\filedate{2004/04/29}\def\docdate{2013/11/26} %\iffalse These lines are necessary for the doc and docstrip utilities %<*asciidocu> %%# %%# Author: %%# %%# M. V\"ath martin@mvath.de %%# %%# The author thanks %%# David Kastrup %%# %%# The package may be distributed and/or modified under the conditions of %%# the LaTeX Project Public License (version 1.3c or later). %%############################################################################# %%# %%# The TeX programmer's toolbox; enhanced version. %%# This (La)TeX package provides some macros which are convenient for %%# writing indices, glossaries, or other macros. %%# It contains macros which support %%# %%# - implicit macros - a useful supplement to \index or varindex for %%# writing glossaries or indices %%# - fancy optional arguments %%# - loops over tokenlists and itemlists %%# - searching, splitting, and replacing %%# - controlled expansion %%# - redefinition of macros %%# - concatenated macro names %%# %%############################################################################# %%# %%# This package was tested with plain TeX, LaTeX 2.09, and LaTeX 2e, %%# and it should actually run with all TeX formats. %%# % If you have access to (reasonable new) docstrip TeXfiles, you should run % tex/latex on the file % `toolbox.ins' % to produce the files `toolbox.sty', `toolbox.txt' and `toolbox.tex'. % (In case `toolbox.ins' is lost: You can find its content in the last % few lines of the file you are currently reading between the % lines %<*insfile> and %; % BTW: You should name this file here `toolbox.dtx' before you run tex % on toolbox.ins). % % The file `toolbox.txt' contains a `brief' (but complete) ascii % documentation. If you have additionally access to LaTeX 2e, you may run % latex on the generated file `toolbox.tex' to produce `toolbox.dvi' which % contains a more luxury documentation. % % If you do not have access to the docstrip TeXfiles you may simply % copy/rename this file here into % `toolbox.sty' % to use the package and read the ascii documentation in this file. % The ascii documentation (the content of `toolbox.txt') consists of all % lines in this file which start with %%# (this is the above block and another % (very large) block which follows soon). % % But I do not recommended this, because TeX will need more time to read this % longer file, and because there might be a (very slight) incompatibility if % you use it (namely if you load `toolbox.sty' with some *extremely* strange % catcodes). % I recommend in this case instead to generate the file `toolbox.sty' as % anything between the lines %<*package> and % by hand. % (This is not precisely the file which you get with the docstrip TeXfiles, % but a reasonable good substitute. To speed up loading, you may also % eliminate all lines starting with `% ' in `toolbox.sty'). % For your information: The file `toolbox.tex' produced by the docstrip % TeXfiles is anything between the lines %<*driver> and % % (with a line containing \endinput and two comment lines appended) % % % In any case, you end up with the file `toolbox.sty'. % % If you can generate `toolbox.tex', you will probably want to stop % reading now and instead read the `luxury' documentation in `toolbox.dvi'. % % Otherwise, you have to make due with the following ascii documentation. % % % \fi\catcode\#14\relax\iffalse (This line is needed for the doc utility) % %%# To use toolbox, you have to put `toolbox.sty' in a path where TeX looks %%# for its input files. The TeX documents using toolbox need the %%# following modifications in their header: %%# %%# a) If you use LaTeX2.09, use toolbox as a style option, e.g. %%# \documentstyle[toolbox]{article} %%# or %%# \documentstyle[toolbox,12pt]{article} %%# b) If you use LaTeX2e, put in the preamble the command %%# \usepackage{toolbox} %%# c) If you use some other (non-LaTeX) format, you will probably have to %%# insert a line like %%# \catcode`\@=11\input toolbox.sty\catcode`\@=12\relax %%# %%# The only LaTeX-specific commands used in `toolbox.sty' are: %%# %%# \newcommand (only in the form \newcommand{\command}{} to ensure that %%# \command was not defined before) %%# \ProvidesPackage %%# \typeout %%# %%# The above commands are used only if they are defined. %%# %%# %%# Description of the provided macros: %%# %%# General remark: Many macros could appear in several sections. %%# For example, \toolboxMakeDef and \toolboxSourround might be considered %%# as macros which support redefinitions of macros. However, we put them %%# in different sections which perhaps explain better their nature. %%# %%# Implicit macro definitions %%# -------------------------- %%# What we mean by implicit macro definitions is probably best explained by %%# the following examples which show the intended usage: %%# %%# (In the following examples, we always refer to the \index command. Note %%# that it may be more convenient to use for indices the varindex package in %%# addition - the documentation of varindex (release 2.3 or newer) gives %%# additional hints and examples how these two (essentially independent) %%# approaches can be combined in practice). %%# %%# Assume that you want to write an index for a book which has rather %%# long and complicated \index entries. The first idea that one might have in %%# this connection is to put the various \index commands at the beginning of %%# the document into several macros (one for each \index entry), and to use %%# just these macros in the main text. For example, one might want to write %%# near the beginning of the document commands like %%# \newcommand{\Start}{\index{finish or end}} %%# \newcommand{\End}{\index{finish or end}} %%# and then to use in the main text \Start and \End whenever a reference %%# in the corresponding index to the current place is desired. %%# However, this has two major disadvantages: %%# 1. Unless you are very disciplinary with your macro names, it is easy to %%# forget that \End writes an index entry. So the \End in the main text %%# might be very confusing. %%# 2. You cannot choose short and intuitive macro names for common phrases, %%# because they are usually already reserved by TeX, LaTeX, or some %%# packages. %%# %%# To avoid these problems, one may be very disciplinary and call the %%# involved macros systematically e.g. \GlossaryStart \GlossaryEnd etc. %%# However, this produces terrible long and unreadable macro names in the %%# main text. %%# %%# The implicit macro definitions of "toolbox" provide a more convenient %%# solution. The idea is that you do not use the corresponding macros directly %%# but only implicitly by a call of other macros where your "macro name" is %%# just an argument. %%# Moreover, "toolbox" assists you in writing the corresponding definitions. %%# For example, if you know that you want a set of macros which all expand %%# into something of the form \index{...}, you can give a ``mask'' which %%# contains this form, and you only have to fill in the changing content %%# (similarly as for usual TeX macros with arguments, but the level of %%# abstraction is one step higher). %%# For the above task, you might use the command: %%# %%# \toolboxMakeDef{Glossary}{\index{#1}} %%# %%# The argument `Glossary' serves to distinguish independent definitions %%# (this will become clear later). Its effect visible now is that it %%# determines the name of the following macros which you can use after %%# the above call: %%# %%# \NewGlossary{start-1}{start} %%# \NewGlossary{start-2}{start or beginning} %%# \NewGlossary{end}{finish or end} %%# %%# These command are now similar to the \newcommand definitions explained %%# above. However, there is no name collision with the TeX-internal command %%# \end. Of course, this means that you cannot just write \end in the main %%# text to get the desired index entry. Instead, you have to write the more %%# intuitive commands %%# %%# \Glossary{start-1} %%# \Glossary{start-2} %%# \Glossary{end} %%# %%# (again, the name \Glossary stems from our first call of \toolboxMakeDef). %%# Note that e.g. \Glossary{start-1} expands not only to `start' but %%# actually to \index{start} (because of our first call of \toolboxMakeDef). %%# Note also that you can use symbols like - or numbers which are usually %%# not allowed in TeX macro names. %%# %%# Of course, similarly as for \newcommand, you can also do other things with %%# the macros. For example, %%# %%# \LetGlossary\tempname{end} %%# \NewGlossary*{finish}\tempname %%# %%# will first define \tempname to expand to the same text as \Glossary{end}, %%# and then defines a new entry \Glossary{finish} to expand to the same text %%# as \tempname. Hence, the above new lines make the calls \Glossary{end} and %%# \Glossary{finish} equivalent. %%# %%# At the end of your list of \NewGlossary commands, you might want to put %%# %%# \toolboxFreeDef*{Glossary} %%# %%# The purpose of this command is that \NewGlossary cannot be used anymore %%# (unless, of course, you define it again). So you cannot unintentionally %%# add new entries to your glossary list (but you still can use \Glossary{...} %%# to reference to the already produced entries). %%# Moreover, the above command frees some memory which was needed for %%# \NewGlossary to work. %%# %%# If you additionally want to free the memory used by \Glossary, you can use %%# %%# \toolboxFreeDef{Glossary} %%# %%# (without the `*'). This may be necessary, if you want to call again e.g. %%# %%# \toolboxMakeDef{Glossary}{\emph{#1}\index{#1}} %%# %%# (if you have not freed the memory for \Glossary before this repeated call, %%# TeX will complain that \Glossary is already defined). %%# %%# Of course, it is possible to call \toolboxMakeDef with several different %%# names, for example, for \Glossary, \SymbolList etc. Another application %%# might be to use a different command to mark e.g.\ the main occurrence of %%# some index entry or to output additionally the entry into the running text. %%# We do this in the following example which simultaneously %%# demonstrates that the names can also be constructed in another way: %%# %%# \toolboxMakeDef[Ind]{}{\index{#1}} %%# \toolboxMakeDef[Ind]{Main}{\index{#1|textbf}} %%# \toolboxMakeDef{OutInd}{#1} %%# %%# \IndNew{A}{A is a letter} %%# \IndNewMain{A}{A is a letter} %%# \NewOutInd{A}{\textbf{The letter A}\Ind{A}} %%# %%# After the above commands, you can use \Ind{A}, \IndMain{A}, and %%# \OutInd{A} to produce the corresponding \index entry, the "main" \index %%# entry (with a boldface page number), and the text \textbf{The letter A} %%# with an additional entry into the index, respectively. %%# Of course, it might usually be more convenient to define the \Ind and %%# \IndMain" entries simultaneously, e.g. as follows %%# %%# \toolboxMakeDef[Ind]{}{#1} %%# \toolboxMakeDef[Ind]{Main}{#1} %%# \newcommand{\NewStandardInd}[2]{% %%# \IndNew{#1}{\index{#2}}% %%# \IndNewMain{#1}{\index{#2|textbf}}} %%# %%# \NewStandardInd{A}{A is a letter} %%# %%# This approach has the additional advantage that you can define exceptional %%# cases "by hand" (e.g. if you want that for certain "main" index %%# entries the page number is printed with "\textsl" instead of "\textbf"). %%# Since the motivation for implicit definitions now is hopefully clear, %%# let us now describe in detail which commands are provided by "toolbox" %%# for this purpose. %%# As explained in the example, the main generic macro provided to this %%# purpose is \toolboxMakeDef. Its call syntax is as follows: %%# %%# \toolboxMakeDef[Prefix]{Name}{ReplacementMask} %%# %%# (the argument [Prefix] is optional and by default empty). %%# The above command generates new macros %%# %%# \PrefixNewName %%# \PrefixRenewName %%# \PrefixProvideName %%# \PrefixDefName %%# \PrefixLetName %%# \PrefixName %%# %%# which in turn can be called as follows %%# %%# \PrefixNewName{something}{RememberText} %%# \PrefixRenewName{something}{RememberText} %%# \PrefixProvideName{something}{RememberText} %%# \PrefixDefName{something}{RememberText} %%# \PrefixNewName*{something}{\SomeMacro} %%# \PrefixRenewName*{something}{\SomeMacro} %%# \PrefixProvideName*{something}{\SomeMacro} %%# \PrefixDefName*{something}{\SomeMacro} %%# \PrefixLetName{\SomeMacro}{something} %%# \PrefixName{something} %%# \PrefixName*{something} %%# %%# These calls are in a sense similar to the respective commands %%# %%# \newcommand{\something}{RememberText} %%# \renewcommand{\something}{RememberText} %%# \providecommand{\something}{RememberText} %%# \def\something{RememberText} %%# \newcommand{\something}{}\let\something\SomeMacro %%# \renewcommand{\something}{}\let\something\SomeMacro %%# \@ifundefined\something{\let\something\SomeMacro}{} %%# \let\something\SomeMacro %%# \let\SomeMacro{\something} %%# \something %%# \something (but without error if \something is undefined). %%# %%# with the differences already pointed out before: %%# 1. The macro name actually used is not \something. Instead, it is a name %%# which does not conflict with any existing macro (except one %%# generated previously by another \PrefixNewName, but in this case a %%# descriptive error is reported). For this reason, it is not possible to %%# use this macro directly but only indirectly by the call %%# \PrefixName{something} (or with \PrefixLetName). %%# 2. The replacement text is not `RememberText' but determined by %%# ReplacementMask where every occurrence of #1 in ReplacementMask is %%# replaced by RememberText (recall the examples). If you want to have the %%# plain RememberText, use {#1} as ReplacementMask. %%# %%# Since toolbox 4.2 there is another slight difference: The symbol '#' %%# is treated as usual and not as in a macro definition. %%# %%# \toolboxMakeDef gives an error message if the commands %%# \Prefix... are already defined. If you intentionally want to %%# change a previous definition, you have to call the command %%# %%# \toolboxFreeDef[Prefix]{Name} %%# %%# before. The latter not only lets all of the macros \Prefix... be %%# \undefined, but also frees all other memory internally used by the %%# corresponding call of \toolboxMakeDef %%# (note, however, that the above command does not free the %%# memory allocated before by calls of \PrefixNew... - to free the latter, %%# you have to call subsequently e.g. %%# %%# \PrefixNewName*{...}{\undefined} %%# %%% before). There is also the command %%# %%# \toolboxFreeDef*[Prefix]{Name} %%# %%# which acts similarly as \toolboxFreeDef but which does not undefine the %%# two macros \PrefixName and \PrefixLetName. %%# %%# %%# Fancy optional argument parsing %%# ------------------------------- %%# This section contains macros which are convenient if you e.g. write a %%# package that contains macros which contain a lot of optional arguments %%# and flags (like "*"). %%# Typically, to read such an optional argument or flag, you save %%# the next token with \futurelet and then call a macro which decides what to %%# do with the token read. Thus, a typical use of \futurelet looks like %%# %%# \def\MacroWithOptionalFlag{\futurelet\tokread\myscan} %%# %%# which will define \tokread to be the token *following* the macro %%# \MacroWithOptionalFlag in the token stream and then execute \myscan. %%# In this context, it is not very convenient that you are *forced* %%# to define a macro \myscan: It could be more convenient if you could just %%# write the *content* of \tokread (in braces) into the above definition. %%# You can indeed do this if you replace \futurelet by \toolboxFuturelet: %%# %%# \toolboxFuturelet\token{argument} %%# %%# The call \toolboxFuturelet\token{\command} has precisely the same effect as %%# \futurelet\token\command. The advantage of \toolboxFuturelet is that %%# instead of a single \command one may use also a sequence of commands. %%# Let us consider \MacroWithOptionalFlag as above. Assume that the user %%# has called this macro in the form "\MacroWithOptionalFlag*" where the %%# "*" is a flag which should cause your macro to do something slightly %%# different. On some place in your macro definition you will have recognized %%# (e.g. with \futurelet or \toolboxFuturelet) that a "*" is following %%# in the calling sequence. So you now want to execute your action %%# (whatever \MacroWithOptionalFlag is supposed to do). %%# However, if you do not take special care, after this action, TeX will %%# print a "*", because this is the next token on the token stream: \futurelet %%# does not delete any tokens. So you have to "gobble" this token away. %%# A rude way to do this is by using the macro \gobblenext as the last token %%# in you macro which can be defined by %%# \begin{verbatim} %%# \def\gobblenext#1{}\end{verbatim} %%# However, this has two major drawbacks: %%# %%# 1. This works for "*", but not for "{" or space tokens. %%# For space tokens the situation is even worse, since TeX eats spaces %%# around arguments, so sometimes space tokens might unexpectedly %%# disappear. %%# 2. It is not possible in this way to read another argument following %%# the "*": Recall that \gobblenext must be the *last* token in your %%# macro expansion, i.e. you have "lost control" after this call. %%# %%# The solution to these problems is instead of calling \gobblenext to use %%# \toolboxGobbleNext as the last command in your call: %%# You can pass it an argument which describes the action that %%# you want to do *after* gobbling the next token ("*" in the above example) %%# from the token stream. Thus %%# %%# \toolboxGobbleNext{cmd} %%# %%# erases the token following that command from the token stream and %%# then executes cmd. This is similar to %%# \def\toolboxGobbleNext#1#2{#1} %%# with the difference that #2 is considered as a token and that no spaces %%# are eaten. %%# The effect is that e.g. the call %%# %%# Example: %%# \toolboxGobbleNext{\foo}{{arg} %%# is the same as \foo{arg} (the brace "{" is eaten in this example). %%# As described earlier, the commands "\futurelet" or "\toolboxFuturelet" can %%# be used to check for optional flags. Frequently you will only want %%# to test for one particular flag and decide the next action on this flag. %%# Of course, you can test the token found with \ifx...\f", but this has the %%# disadvantage that some tokens (e.g. \fi) follow your action, which might %%# be bad (recall that e.g. \toolboxGobbleNext must be the last command of %%# your action, i.e. it would in the above examples not gobble the "*" but %%# the "\fi" which is probably not what you want). %%# The simplest solution is to use the command \toolboxIfNextToken which %%# already has the test included. For example, to test for an optional "[", %%# you can simply write %%# %%# \def\MacroWithOptionalBrace{\toolboxIfNextToken[{\yes}{\no}} %%# %%# and then the call "\MacroWithOptionalBrace[...]" will expand to "\yes[...]" %%# while "\MacroWithOptionalBrace x" will expand to "\no x" %%# (note that the brace is not gobbled - if you want the latter, %%# use "\toolboxIfNextGobbling" described below). %%# More precisely, the calling syntax of "\toolboxIfNextToken" is %%# %%# \toolboxIfNextToken{token}{IfPart}{ElsePart} %%# %%# The semantic is the following: %%# If the token following this command is `token', then IfPart is executed, %%# otherwise ElsePart. It is explicitly admissible that `token' is a space. %%# To support further tests, \toolboxToken is \let to the token which follows %%# the command. \toolboxToken is only a temporary token, i.e. %%# it may also be modified by other commands of this package; in particular, %%# you may also freely to modify \toolboxToken. %%# The token \toolboxSpaceToken which is described later may be handy %%# in connection with this command. %%# %%# In contrast to similar LaTeX2e macros much care has been taken %%# that spaces are not eaten. This solves the following problem: %%# %%# Assume that you want to write a macro which should have the calling syntax %%# "\mymacro{arg1}" or "\mymacro{arg1}[arg2]". You will probably implement %%# \mymacro to read the first argument and then to look whether the next %%# token is a "[". If you use the LaTeX2e macro to test for "[", %%# then all spaces until the next non-space token would be gobbled which means %%# that if you would use the LaTeX2e macros for the test, then the call %%# "\mymacro{arg1} Text" would behave like "\mymacro{arg1}Text", %%# i.e. the space is `mysteriously' lost. With the "toolbox" macros this %%# does not happen. The `disadvantage' is that "\mymacro{arg1} [arg2]" %%# is not the same as "\mymacro{arg1}[arg2]" (which is reasonable IMHO). %%# %%# Example: %%# %%# \def\mycmd#1{\toolboxIfNextToken[{\ParseOpt{#1}}{\NoOpt{#1}}} %%# \def\ParseOpt#1[#2]{\OptAtEnd{#1}{#2}} %%# %%# After the above definition, \mycmd{arg} executes \NoOpt{arg} while %%# \mycmd{arg}[optional] executes \OptAtEnd{arg}{optional} %%# We point out once more that in the first call a space following %%# \mycmd{arg} does not vanish (as would be the case if the LaTeX 2e macros %%# would have been used). %%# If \toolboxIfNextToken has found the required token, it does *not* %%# gobble that token from the token stream. Of course, you can do this by %%# yourself using the earlier described macro \toolboxGobbleNext. However, %%# it is simpler to use %%# %%# \toolboxIfNextGobbling{token}{IfPart}{ElsePart} %%# %%# This command is analogous to \toolboxIfNextToken with the difference that %%# in the case that the next token is the desired token, it is gobbled before %%# IfPart is executed. %%# %%# Example: %%# %%# \def\myloop{\toolboxIfNextGobbling*\toolboxTokenLoop\toolboxLoop} %%# %%# This makes \myloop*... behave like \toolboxTokenLoop, and %%# \myloop... (without *) behave like \toolboxLoop. %%# The following macro is one which you may want to use in connection with %%# LaTeX 2e optional arguments: %%# %%# \toolboxIfEmpty{arg}{IfPart}{ElsePart} %%# %%# The argument is not expand; it is only used to decide whether the %%# {IfPart} or the {ElsePart} will be expanded. %%# For further tests there are more involved macros: %%# %%# \toolboxIfx{arg}\macro{IfPart}{ElsePart} %%# %%# This tests via \ifx whether \def\Macro{arg} would give the definition %%# of \macro. %%# %%# \toolboxIfX{arga}{argb}{IfPart}{ElsePart} %%# %%# This tests whether "arga" and "argb" are the same token sequences. %%# If you want to avoid the \else and \fi commands to avoid certain side %%# effects, you can use instead: %%# %%# \toolboxIfElse{ifcmd}{IfPart}{ElsePart} %%# %%# This is rather analogous to "ifcmd" IfPart \else ElsePart \fi %%# but has everything in this line already eliminated from the tokenlist %%# when IfPart resp. ElsePart are expanded. %%# %%# Loops over tokenlists and itemlists %%# ----------------------------------- %%# \toolboxLoop{items}{action} %%# %%# This calls iteratively "action{#1}", where #1 runs over each item in the %%# argument items. Here, an item is either a token or a group braced by {...}. %%# In the latter case, the braces are lost. Spaces in items are ignored %%# (unless they are braced). It is admissible that \action is not a single %%# macro but instead a sequence of tokens. %%# Examples follow below. %%# %%# The counterintuitive order of arguments is explained by the fact that the %%# typical usage is %%# \expandafter\toolboxLoop\expandafter{\MacroExpandingToItems}{action} %%# which for swapped order of arguments could hardly be written. %%# \toolboxLoop is not reentrant i.e. "action" may not expand %%# to something which contains a call to \toolboxLoop. To enable such calls %%# anyway, the command %%# %%# \toolboxLoopName{name}{items}{\action} %%# %%# is provided which is analogous to \toolboxLoop. This is also not reentrant, %%# but in contrast to \toolboxLoop, calls with different `name' arguments can %%# be used independently of each other, i.e. in the `action' part of a %%# \toolboxLoop (or \toolboxLoopName) can be a call to \toolboxLoopName with %%# a *different* `name'. %%# In particular, using a counter in `name' one could easily implement %%# even recursive calls. In this connection, it should be noted that %%# `name' is expanded via \csname ... \endcsname, and so you may use %%# constructs like \the\namecounter there. %%# \toolboxTokenLoop{tokens}{\action} %%# %%# This is similar to \toolboxLoop: The command \action\toolboxToken %%# is executed iteratively where \toolboxToken runs over each token in tokens. %%# The important difference is that \toolboxToken is a token (instead of an %%# item). In particular, \toolboxToken runs through every single token %%# including spaces and braces. %%# The token \toolboxSpaceToken which is described later may be handy %%# in connection with this command. %%# %%# Example: %%# %%# \toolboxTokenLoop{Some text}{\kern0.1em} %%# %%# is the similar to "\kern0.1em S\kern0.1em o\kern0.1em m...", i.e. you %%# get wider spacing between the letters of "Some text" (I do not claim that %%# this is typographically a good idea). %%# %%# Note that you do not have to take special care about the space. %%# With \toolboxLoop, you would have to mask the space e.g. with %%# %%# \toolboxLoop{Some{ }text}{\kern0.1em} or %%# \toolboxLoop{Some\toolboxSpace text}{\kern0.1em} %%# %%# In contrast, \toolboxTokenLoop would behave differently here: %%# %%# \toolboxTokenLoop{Some{ }text}{\kern0.1em} %%# %%# would produce \kern0.1em S...\kern0.1em{\kern0.1em \kern0.1em}... %%# because the braces are simply considered as tokens. %%# \toolboxTokenLoop is not reentrant. Analogously to \toolboxLoopName, %%# independent versions can be generated by %%# %%# \toolboxTokenName{name}{tokens}{\action} %%# %%# Controlled expansion %%# -------------------- %%# There are some occasions when you want more control over the expansion. %%# E.g. you might want to concatenate the contents of two macros to a %%# further macro or you want to expand a macro by one level but no full %%# expansion. Usually you can get this effects with \expandafter, but if %%# you expand several concatenated tokens in this way you either have to %%# write a lot of \expandafter's or you have to define subsidiary macros %%# that help you to \expandafter certain parts of macros. The macros in %%# this section allow you to do this in the most generic way that I could %%# implement. %%# \toolboxDef\macrotodefine{argumentlist} %%# %%# This call is similar to %%# \def\macrotodefine{argumentlist} %%# with two important differences: %%# %%# For \toolboxDef, the argumentlist is expanded precisely by one level. %%# argumentlist may not contain macros with parameters, and spaces on the %%# highest level are ignored. If you want to force a space on a particular %%# place, use the macro \toolboxSpace at this place %%# (which is described later). Contrary to the usual \def, the symbol # is %%# treated as a usual symbol. %%# %%# Example of usage: %%# \toolboxDef\chain{\chain\toolboxSpace\after} %%# This modifies the macro \chain such that a space and the content of the %%# macro \after is appended at the end. %%# \toolboxAppend\macrotodefine{arglist} %%# %%# This is equivalent to \toolboxDef\macrotodefine{\macrotodefine arglist} %%# %%# \toolboxSurround{ContentBefore}{ContentAfter}\macro %%# %%# This redefines \macro such that ContentBefore is put at the beginning %%# and ContentAfter after the definition of \macro. So this is equivalent to %%# \def\macro{ContentBefore * ContentAfter} %%# where * is the old content of \macro. It is required that \macro is a %%# usual macro without any arguments. If you want to patch more complicated %%# macros, use the patch.doc package instead. %%# The order of the arguments may appear strange, but it is convenient if %%# ContentBefore or ContentAfter are macros which should be expanded with %%# \expandafter. %%# There is some subsidiary macro used in the implementation of the above %%# macros which might be useful also in some other situations: %%# %%# \toolboxTokDef{argumentlist}\macrotodefine %%# %%# This call is similar to %%# \def\macrotodefine{argumentlist} %%# with the difference that the symbol # is stored as such. %%# The order of the arguments has been swapped in order to simplify the %%# application of \expandafter to the argumentlist. %%# %%# Searching, splitting, and replacing %%# ---------------------------------- %%# \toolboxSplitAt{argument}{search}{\beforestring}{\afterstring} %%# %%# Here, \beforestring and \afterstring are arbitrary macro names, %%# and search and argument are any sequences of tokens (which are in %%# the following considered as `strings'). %%# %%# This call scans the string `argument' for the first occurrence of `search'. %%# The macros \beforestring and \afterstring are defined correspondingly %%# such that \beforestring expands to the part before the first occurrence, %%# and \afterstring to the part following the first occurrence. %%# If `search' does not occur in `argument', \beforestring is defined to %%# `argument', and \afterstring is \let \undefined. %%# %%# If \beforestring or \afterstring had already been defined before the %%# call, the previous definition is tacitly overridden. %%# It is explicitly allowed that \beforestring and \afterstring are the %%# same names. In this case, the result has the meaning of \afterstring. %%# %%# It is guaranteed that braces {...} are *not* lost in `argument'. %%# However, `search' may not contain any braces, and `argument' may contain %%# only matching pairs of braces. Moreover, occurrences of `search' within a %%# pair of braces in `argument' are not recognized. %%# %%# (The order of the arguments has been chosen in order to simplify the %%# use of \expandafter). %%# %%# There are some restrictions for the strings in search. For example, %%# the symbol '#' is not allowed. %%# %%# In the above call, the arguments may not run over several paragraphs. %%# If you want the latter, you have to use the alternative call %%# %%# \toolboxSplitAt*{argument}{search}{\beforestring}{\afterstring} %%# %%# Example of usage: %%# %%# \def\examplemacro#1{\toolboxSplitAt{#1}{@}\testme\testme %%# \ifx\testme\undefined %%# ... (do this when #1 contains no `@' token) %%# \fi} %%# %%# \toolboxMakeSplit{search}{command} %%# %%# If \toolboxSplitAt should be used several times with the same search %%# string, it is much more effective to use the above call: This call %%# defines a new macro \command (the name is determined by the second argument %%# of \toolboxMakeSplit) which can be called in the form %%# %%# \command{argument}{\beforestring}{\afterstring} %%# %%# and which has the analogous meaning as \toolboxSplitAt (the argument %%# {search} is implicitly fixed and taken from the call of %%# \toolboxMakeSplit). %%# It is explicitly admissible that the above macro \toolboxMakeSplit is %%# used with an already existing command name. In this case, the previous %%# definition of \command is tacitly overridden. %%# %%# The command created by \toolboxMakeSplit does not accept arguments which %%# run over several paragraphs. If you want the latter, you have to create %%# this command by the alternative call %%# %%# \toolboxMakeSplit*{search}{command} %%# %%# The command %%# \toolboxFreeSplit{command} %%# frees the memory used by a previous \toolboxMakeSplit (and lets \command %%# again be undefined). %%# The command %%# \toolboxReplace{search}{replace}\macro %%# replaces in \macro all occurences of {search} by {replace}. %%# The same matches are found as in \toolboxSplitAt. %%# If you need to search for the same text several times, it is faster %%# to use the command %%# \toolboxReplaceSplit{replace}\SplitCmd\macro %%# where \SplitCmd is a command previously generated with \toolboxMakeSplit* %%# according to your search string. (You could also use \toolboxMakeSplit %%# to generate \SplitCmd, but then \macro should not contain any \par's). %%# %%# Redefinition of macros %%# ---------------------- %%# \toolboxMakeHarmless{\macro} %%# %%# The above call redefines \macro such that it expands to an ASCII text %%# containing the previous definition of \macro (i.e. the catcodes of \macro %%# are changed). %%# \toolboxDropBrace\variable %%# %%# drops possible outer braces in \variable. More precisely, %%# if \variable expands to {content}, then \variable is redefined to %%# content (without braces). Otherwise, nothing happens. %%# %%# \toolboxIf\comparison{DefinitionCommand}{\macro}... %%# %%# The above command allows conditional definitions. %%# Here, {DefinitionCommand} is either \def, {\long\def}, \let, or some %%# similar command like the LaTeX \newcommand. If the test %%# \ifx\comparison\macro evaluates positive, then \macro is defined %%# correspondingly. Otherwise, \macro is not changed. %%# %%# Examples: %%# %%# \toolboxIf\undefined\def\macro{....} %%# \toolboxIf\undefined\let\macro... %%# \toolboxIf\undefined{\long\def}\macro{....} %%# \toolboxIf\undefined\newcommand{\macro}{....} %%# %%# are similar to \def\macro{...} resp. \let\macro... resp. %%# \long\def\macro{...} resp. \newcommand{\macro}{...} with the difference %%# that \macro is not changed if it was already defined. %%# In this sense, \toolboxIf is a more flexible variant of \providecommand. %%# %%# \toolboxNewiftrue{name} or \toolboxNewiffalse{name} %%# %%# If the command \ifname was already introduced with \newif, then %%# nothing happens. Otherwise \ifname is introduced similarly to %%# \newif\ifname and set to `true' respectively `false'. %%# In contrast to the corresponding command in TeX or LaTeX 2.09, this macro %%# is not \outer! %%# \toolboxNewifTrue{name} or \toolboxNewifFalse{name} %%# %%# are similar to \toolboxNewiftrue{name} and \toolboxNewiffalse{name}, %%# respectively, with the difference that \ifname is set unconditionally %%# to `true' respectively `false'. %%# %%# Concatenated macro names %%# ------------------------ %%# \toolboxLet\variable{macroname} %%# %%# The above command is analogous to \let\variable\macroname with the %%# difference that macroname can also contain other tokens like numbers %%# (it is obtained via \csname). Some converse to this command is %%# %%# \toolboxWithNr {number}\cmd{macro} %%# %%# which translates into \cmd\macronumber (here, `macro' and `number' %%# are just concatenated and evaluated via \csname). %%# Examples: %%# \toolboxWithNr 1\let{name}\toolboxEmpty %%# This is the same as \let\name1\toolboxEmpty %%# (but such that \name1 is considered as a name, not as \name 1) %%# \toolboxWithNr {10}\def{name}{Foo} %%# This corresponds analogously to \def\name10{Foo}. %%# \toolboxLet \mymacro{name\the\mycount} %%# This is similar to \let\mymacro\namexx where xx is the content %%# of the counter \mycount. %%# %%# Various %%# ------- %%# The following macros have equivalents in most formats (like LaTeX2e). %%# However, we do not want to rely too much on these formats, so we provide %%# our own definitions. %%# The macro %%# \toolboxEmpty %%# expands to nothing (usually, this is the same as \empty). %%# Similarly, the macro %%# \toolboxSpace %%# expands to a space symbol (usually, this is the same as \space). %%# The token %%# \toolboxSpaceToken %%# is \let a space token (usually, this is the same as \@sptoken). %%# This token is convenient in tests of tokens %%# (because it is hard to get a space there which is not eaten by the TeX %%# parser, although sometimes also constructions like %%# \expandafter\ifx\toolboxSpace\token can be used). %%# Also the macros %%# \toolboxFirstOfTwo %%# \toolboxSecondOfTwo %%# are provided which read two arguments and return only the first %%# respectively second argument (usually, this is the same as %%# \@firstoftwo respectively \@secondoftwo). Similarly, %%# \toolboxGobbleArg{argument} %%# just reads its argument and expands to nothing. % This is the end of the ascii documentation % %\fi\catcode\#6\relax % % \iffalse %<*metainfo> % \fi % \def\basename{toolbox} %% \CharacterTable %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z %% Digits \0\1\2\3\4\5\6\7\8\9 %% Exclamation \! Double quote \" Hash (number) \# %% Dollar \$ Percent \% Ampersand \& %% Acute accent \' Left paren \( Right paren \) %% Asterisk \* Plus \+ Comma \, %% Minus \- Point \. Solidus \/ %% Colon \: Semicolon \; Less than \< %% Equals \= Greater than \> Question mark \? %% Commercial at \@ Left bracket \[ Backslash \\ %% Right bracket \] Circumflex \^ Underscore \_ %% Grave accent \` Left brace \{ Vertical bar \| %% Right brace \} Tilde \~} % \CheckSum{736} % \iffalse % \RecordChanges % \fi % \def\mypar{} % \def\ChangesTab{}\let\orichanges\changes % \def\changes#1#2#3{\orichanges{#1}{#2}{#3} % \expandafter\def\expandafter\ChangesTab\expandafter{\ChangesTab % \item[v#1 {\mdseries(\emph{#2})}] {#3.}}} % \newcommand{\cmdcite}[1]{\texttt{\textbackslash#1}} % \newcommand{\bracemeta}[1]{\texttt{\{}\meta{#1}\texttt{\}}} % \newcommand{\cmdmeta}{\textbackslash\meta} % \changes{5.1}{2013/11/26}{Update email, add license. Date/version remains the % same since only commments and documentation are modified} % \changes{5.1}{2004/04/29}{Added \cmdcite{toolboxReplace}, % \cmdcite{toolboxReplaceSplit}. Some corrections in the documentation. % Added some forgotten \cmdcite{long}'s in the code.} % \changes{4.4}{2003/10/07}{Added \cmdcite{toolboxIfEmpty}, % \cmdcite{toolboxIfx}, \cmdcite{toolboxIfX}, \cmdcite{toolboxIfElse}. % Some corrections in the documentation} % \changes{4.3}{2002/09/27}{Major enhancements in documentation: Added lots % of examples and explanation about typical applications. % Bugfix in \cmdcite{toolboxMakeDef}: % \cmdmeta{Prefix}\texttt{Provide}\meta{Name} now behaves like % \cmdcite{providecommand} as documented. The old meaning is now called % \cmdmeta{Prefix}\texttt{Def}\meta{Name}. % Introduced \cmdcite{toolboxGobbleArg}} % \changes{4.2}{2001/09/26}{Treating \texttt{\#} properly now also in % \cmdcite{toolboxMakeDef}} % \changes{4.1}{2001/09/24}{Took more care of treating \texttt{\#} properly % when this symbol occurs in arguments of certain macros (the treatment is % not completely downward compatible; for this reason the major release % number has been changed). For this reason, % also the new macro \cmdcite{toolboxTokDef} is provided. I thank % David Kastrup \texttt{} % for pointing out this problem (and a solution) to me} % \changes{3.3}{2001/08/19}{Eliminated a bug in \cmdcite{toolboxMakeSplit*}} % \changes{3.2}{2001/05/08}{Eliminated a serious bug in \cmdcite{toolboxIf}. % Due to this bugfix, the usage of \cmdcite{toolboxIf} had to be slightly % restricted} % \changes{3.1}{2001/05/06}{Major advantage: \cmdcite{toolboxMakeDef} % implemented.\mypar % Reimplemented \cmdcite{newif} (apparently by mistake, this had been % declared as \cmdcite{outer} in \TeX\ and \LaTeX 2.09 which caused an % error during loading of \texttt{toolbox.sty}). % For this reason, also \cmdcite{toolboxNewifTrue} and % \cmdcite{toolboxNewifFalse} were introduced} % \changes{2.1}{2001/04/30}{Introduced \cmdcite{toolboxIf}, % \cmdcite{toolboxAppend}, and \cmdcite{toolboxSurround}} % \changes{2.0}{2001/04/08}{Many major enhancements and new tools: % Added section (and corresponding macros) % for fancy optional arguments. Made \cmdcite{toolboxLoop} semi-reentrant by % introducing \cmdcite{toolboxLoopName}. % Added \cmdcite{toolboxTokenLoop} and friends. % Added \cmdcite{toolboxSpaceToken}. % Made many macros \cmdcite{long} and added \cmdcite{long} versions % of \cmdcite{toolboxSplitAt} and \cmdcite{toolboxMakeSplit}} % \changes{1.0}{2001/03/29}{First release} % % \iffalse % % The following part is the code needed to compile the documentation. % We do some trickery here, because we want that this file here could be used % for *both*: Compiling the documentation *and* as `toolbox.sty' % (if really required). % Everything between the lines %<*driver> and % % goes to the file `toolbox.tex'. % % \fi \ifcat @a% If this test is positive, then `@' has letter catcode which means % that this file is loaded as a style file (or as described in the % install section of the documentation). \def\TemporaryDummy{} \else\long\def\TemporaryDummy{% % % % \iffalse % %<*driver> \documentclass{ltxdoc} \OnlyDescription%% Comment this out, or %%\AlsoImplementation%% uncomment this line, if you want to see the source. %% If you want an index, uncomment one of the following lines. %% After running latex a first time, you have to use %% makeindex -s gind.ist toolbox %% Then run latex again. %%\CodelineIndex% comment this out if you want an index referring to codelines %%\PageIndex% comment this out if you want an index referring to pages %%\OldMakeindex% uncomment this line, if your MakeIndex is pre-v2.9 \setlength\hfuzz{15pt} \hbadness=7000 \begin{document} \DocInput{toolbox.dtx} \end{document} % %<*metainfo> % \fi } \fi\TemporaryDummy\let\TemporaryDummy\undefined % % \iffalse % Personal macros used for the doc utility: % \fi % \MakeShortVerb{"} % \newcommand{\filecite}[1]{\texttt{#1}} % \newcommand{\nocomment}{} % \newcommand{\myspace}{\texttt{\textvisiblespace}} % \parindent0pt % \title{The \texttt{toolbox} package\thanks % {This package has version number \fileversion{}, last revised \filedate. % The package may be distributed and/or modified under the conditions of the % LaTeX Project Public License, either version 1.3c of this license or (at % your option) any later version. The latest version of this license is in % \texttt{http://www.latex-project.org/lppl.txt}, and version 1.3c or later % is part of all distributions of LaTeX version 2005/12/01 or later.}} % \author{Martin V\"ath\relax %\thanks{\texttt{martin@mvath.de}} %{}\thanks{The author thanks %David Kastrup \texttt{}. %}} % \date{\docdate} % \maketitle\sloppy % \begin{abstract} % The \TeX\ programmer's toolbox; enhanced version. % This package provides some macros which are convenient for writing % indices, glossaries, or other macros. It contains macros which support % \begin{itemize} % \item implicit macros -- a useful supplement to \cmdcite{index} or % \texttt{varindex} for writing glossaries or indices. % \item fancy optional arguments % \item loops over tokenlists and itemlists % \item searching, splitting, and replacing % \item controlled expansion % \item redefinition of macros % \item concatenated macro names % \end{itemize} % \end{abstract} % You may copy this package freely, as long as you distribute only unmodified % and complete versions. % \tableofcontents % \section{Changes} % % \begin{description} % \def\mypar{\par}\ChangesTab % \end{description} % % \section{Installation} % This package was tested with \TeX, \LaTeX 2.09, and \LaTeXe, and it % should actually run with all other \TeX\ formats. % To use \filecite{toolbox}, you have to put the file \filecite{toolbox.sty} % in a path where \TeX\ looks for its input files. The \TeX\ documents using % \filecite{toolbox} need the following modifications in their header: % % \begin{itemize} % \item If you use \LaTeXe, put in the preamble the command % \begin{verbatim} % \usepackage{toolbox}\end{verbatim} % % \item If you use \LaTeX 2.09, use \filecite{toolbox} as a style option, e.g.\ % \begin{verbatim} % \documentstyle[toolbox]{article}\end{verbatim} % or % \begin{verbatim} % \documentstyle[toolbox,12pt]{article}\end{verbatim} % % \item If you use some other (non-\LaTeX) format, you will probably have to % insert a line like % \begin{verbatim} % \catcode`\@=11\input toolbox.sty\catcode`\@=12\relax\end{verbatim} % % \end{itemize} % % The only \LaTeX-specific commands used in \filecite{toolbox.sty} are: % % \begin{itemize} % \item "\newcommand" (used only in the form "\newcommand{"\meta{command}"}{}" % to ensure that \meta{command} was not defined before) % \item "\ProvidesPackage" % \item "\typeout" % \end{itemize} % The above commands are used only if they are defined. % \section{Description of the macros} % % General remark: Many macros could appear in several sections. % For example, "\toolboxMakeDef" and "\toolboxSourround" might be considered % as macros which support redefinitions of macros. However, we put them % in different sections which perhaps explain better their nature. % % \subsection{Implicit macro definitions} % % What we mean by implicit macro definitions is probably best explained by % the following examples which show the intended usage:\par\bigskip % % (In the following examples, we always refer to the "\index" command. Note % that it may be more convenient to use for indices the \filecite{varindex} % package in addition -- the documentation of \filecite{varindex} % (release 2.3 or newer) gives additional hints and examples how these two % (essentially independent) approaches can be combined in practice). % \par\bigskip % % Assume that you want to write an index for a book which has rather % long and complicated "\index" entries. The first idea that one might have in % this connection is to put the various "\index" commands at the beginning of % the document into several macros (one for each "\index" entry), and to use % just these macros in the main text. For example, one might want to write % near the beginning of the document commands like % \begin{verbatim} % \newcommand{\Start}{\index{finish or end}} % \newcommand{\End}{\index{finish or end}}\end{verbatim} % and then to use in the main text "\Start" and "\End" whenever a reference % in the corresponding index to the current place is desired. % However, this has two major disadvantages: % \begin{enumerate} % \item It is easy to forget that "\End" writes an index entry. % So the macro "\End" in the main text might be very confusing. % \item You cannot choose short and intuitive macro names for common phrases, % because they are usually already reserved by \TeX, \LaTeX, or some % packages. For example, "\end" could not be used. % \end{enumerate} % To avoid these problems, one may be very disciplinary and call the % involved macros systematically e.g.\ "\GlossaryStart" "\GlossaryEnd" etc. % However, this produces terrible long and unreadable macro names in the main % text.\par\bigskip % The implicit macro definitions of \filecite{toolbox} provide a more % convenient solution. % The idea is that you do not use the corresponding macros directly but only % implicitly by a call of other macros where your ``macro name'' is just an % argument.\par % Moreover, \filecite{toolbox} assists you in writing the corresponding % definitions. % For example, if you know that you want a set of macros which all expand % into something of the form "\index{...}", you can give a ``mask'' which % contains this form, and you only have to fill in the changing content % (similarly as for usual \TeX\ macros with arguments, but the level of % abstraction is one step higher). % For the above task, you might use the command: % \begin{verbatim} % \toolboxMakeDef{Glossary}{\index{#1}}\end{verbatim} % % The argument "Glossary" serves to distinguish independent definitions % (this will become clear later). Its effect visible now is that it % determines the name of the following macros which you can use after % the above call: % \begin{verbatim} % \NewGlossary{start-1}{start} % \NewGlossary{start-2}{start or beginning} % \NewGlossary{end}{finish or end}\end{verbatim} % % These command are now similar to the "\newcommand" definitions explained % above. However, there is no name collision with the \TeX-internal command % "\end". Of course, this means that you cannot just write "\end" in the main % text to get the desired index entry. Instead, you have to write the more % intuitive commands % \begin{verbatim} % \Glossary{start-1} % \Glossary{start-2} % \Glossary{end}\end{verbatim} % (again, the name "\Glossary" stems from our first call of "\toolboxMakeDef"). % Note that e.g.\ "\Glossary{start-1}" expands not only to "start" but % actually to "\index{start}" (because of our first call of % "\toolboxMakeDef").\par % Note also that you can use symbols like ``-'' or numbers which are % usually not allowed in \TeX\ macro names. % % Of course, similarly as for "\newcommand", you can also do other things with % the macros. For example, % \begin{verbatim} % \LetGlossary\tempname{end} % \NewGlossary*{finish}\tempname\end{verbatim} % % will first define "\tempname" to expand to the same text as "\Glossary{end}", % and then defines a new entry "\Glossary{finish}" to expand to the same text % as "\tempname". Hence, the above two lines make the calls "\Glossary{end}" % and "\Glossary{finish}" equivalent. % % At the end of your list of "\NewGlossary" commands, you might want to put % \begin{verbatim} % \toolboxFreeDef*{Glossary}\end{verbatim} % % The purpose of this command is that "\NewGlossary" cannot be used anymore % (unless, of course, you define it again). So you cannot unintentionally % add new entries to your glossary list (but you still can use "\Glossary{...}" % to reference to the already produced entries). % Moreover, the above command frees some memory which was needed for % "\NewGlossary" to work. % % If you additionally want to free the memory used by "\Glossary", you can use % \begin{verbatim} % \toolboxFreeDef{Glossary}\end{verbatim} % % (without the "*"). This may be necessary, if you want to call again e.g. % \begin{verbatim} % \toolboxMakeDef{Glossary}{\emph{#1}\index{#1}}\end{verbatim} % % (if you have not freed the memory for "\Glossary" before this repeated call, % \TeX\ will complain that "\Glossary" is already defined).\par\smallskip % % Of course, it is possible to call "\toolboxMakeDef" with several different % names, for example, for "\Glossary", "\SymbolList" etc. Another application % might be to use a different command to mark e.g.\ the main occurrence of % some index entry or to output additionally the entry into the running text. % We do this in the following example which simultaneously % demonstrates that the names can also be constructed in another way: % \begin{verbatim} % \toolboxMakeDef[Ind]{}{\index{#1}} % \toolboxMakeDef[Ind]{Main}{\index{#1|textbf}} % \toolboxMakeDef{OutInd}{#1} % % \IndNew{A}{A is a letter} % \IndNewMain{A}{A is a letter} % \NewOutInd{A}{\textbf{The letter A}\Ind{A}}\end{verbatim} % After the above commands, you can use "\Ind{A}", "\IndMain{A}", and % "\OutInd{A}" to produce the corresponding "\index" entry, the ``main'' % "\index" entry (with a fat page number), and the text \textbf{The letter A} % with an additional entry into the index, respectively. % Of course, it might usually be more convenient to define the "\Ind" and % "\IndMain" entries simultaneously, e.g.\ by the commands % \begin{verbatim} % \toolboxMakeDef[Ind]{}{#1} % \toolboxMakeDef[Ind]{Main}{#1} % \newcommand{\NewStandardInd}[2]{% % \IndNew{#1}{\index{#2}}% % \IndNewMain{#1}{\index{#2|textbf}}} % % \NewStandardInd{A}{A is a letter}\end{verbatim} % This approach has the additional advantage that you can define exceptional % cases ``by hand'' (e.g.\ if you want that for certain ``main'' index % entries the page number is printed with "\textsl" instead of "\textbf"). % \bigskip % % Since the motivation for implicit definitions now is hopefully clear, % let us now describe in detail which commands are provided by % \filecite{toolbox} for this purpose. % As explained in the example, the main generic macro provided to this % purpose is \DescribeMacro{\toolboxMakeDef}"\toolboxMakeDef". % Its call syntax is as follows: % \begin{quote} % "\toolboxMakeDef["\meta{Prefix}"]"\bracemeta{Name}\relax %\bracemeta{Replacement mask} % \end{quote} % (the argument "["\meta{Prefix}"]" is optional and by default empty). % The above command generates new macros % % \begin{quote} % \cmdmeta{Prefix}"New"\meta{Name}\\ % \cmdmeta{Prefix}"Renew"\meta{Name}\\ % \cmdmeta{Prefix}"Provide"\meta{Name}\\ % \cmdmeta{Prefix}"Def"\meta{Name}\\ % \cmdmeta{Prefix}"Let"\meta{Name}\\ % \cmdmeta{Prefix}\meta{Name} % \end{quote} % which in turn can be called as follows: % \begin{quote} % \cmdmeta{Prefix}"New"\meta{Name}\bracemeta{something}\relax %\bracemeta{text to remember}\\ % \cmdmeta{Prefix}"Renew"\meta{Name}\bracemeta{something}\relax %\bracemeta{text to remember}\\ % \cmdmeta{Prefix}"Provide"\meta{Name}\bracemeta{something}\relax %\bracemeta{text to remember}\\ % \cmdmeta{Prefix}"Def"\meta{Name}\bracemeta{something}\relax %\bracemeta{text to remember}\\ % \cmdmeta{Prefix}"New"\meta{Name}"*"\bracemeta{something}\relax %{\cmdmeta{SomeMacro}}\\ % \cmdmeta{Prefix}"Renew"\meta{Name}"*"\bracemeta{something}\relax %{\cmdmeta{SomeMacro}}\\ % \cmdmeta{Prefix}"Provide"\meta{Name}"*"\bracemeta{something}\relax %{\cmdmeta{SomeMacro}}\\ % \cmdmeta{Prefix}"Def"\meta{Name}"*"\bracemeta{something}\relax %{\cmdmeta{SomeMacro}}\\ % \cmdmeta{Prefix}"Let"\meta{Name}{\cmdmeta{SomeMacro}}\bracemeta{something}\\ % \cmdmeta{Prefix}\meta{Name}\bracemeta{something}\\ % \cmdmeta{Prefix}\meta{Name}"*"\bracemeta{something} % \end{quote} % These calls are in a sense similar to the respective commands % \begin{quote} % "\newcommand{"\cmdmeta{something}"}"\bracemeta{text to remember}\\ % "\renewcommand{"\cmdmeta{something}"}"\bracemeta{text to remember}\\ % "\providecommand{"\cmdmeta{something}"}"\bracemeta{text to remember}\\ % "\def"\cmdmeta{something}\bracemeta{text to remember}\\ % "\newcommand{"\cmdmeta{something}"}{}"\relax %"\let"\cmdmeta{something}\cmdmeta{SomeMacro}\\ % "\renewcommand{"\cmdmeta{something}"}{}"\relax %"\let"\cmdmeta{something}\cmdmeta{SomeMacro}\\ % "\@ifundefined"\bracemeta{something}"{\let"\relax %\cmdmeta{something}\cmdmeta{SomeMacro}"}{}"\\ % "\let"\cmdmeta{something}\cmdmeta{SomeMacro}\\ % "\let"\cmdmeta{SomeMacro}{\cmdmeta{something}}\\ % \cmdmeta{something}\\ % \cmdmeta{something} (but without error if \cmdmeta{something} is undefined) % \end{quote} % with the differences already pointed out before: % \begin{enumerate} % \item The macro name actually used is not \cmdmeta{something}. % Instead, it is a name which does not conflict with any existing macro % (except one generated previously by another \cmdmeta{Prefix}New\meta{Name}, % but in this case a descriptive error is reported).\par % For this reason, it is not possible to use this macro directly but only % indirectly by the call \cmdmeta{Prefix}\meta{Name}\bracemeta{something} % (or with \cmdmeta{Prefix}Let\meta{Name}). % \item The replacement text is not \meta{text to remember} but determined by % \meta{Replacement Mask} where every occurrence of "#1" in % \meta{Replacement Mask} is replaced by \meta{text to remember} % (recall the examples). If you want to have the plain % \meta{text to remember}, use "{#1}" as \meta{Replacement Mask}. % \end{enumerate} % Since \filecite{toolbox~4.2} there is another slight difference: % The symbol "#" is treated as usual and not as in a macro definition.\par % % "\toolboxMakeDef" gives an error message if the commands % \cmdmeta{Prefix}"..." are already defined. If you intentionally want to % change a previous definition, you have to call the command % % \begin{quote} % \DescribeMacro{\toolboxFreeDef} % "\toolboxFreeDef["\meta{Prefix}"]"\bracemeta{Name} % \end{quote} % before. The latter not only lets all of the macros \cmdmeta{Prefix}"..." be % "\undefined", but also frees all other memory internally used by the % corresponding call of "\toolboxMakeDef" % (note, however, that the above command does not free the % memory allocated before by calls of \cmdmeta{Prefix}"New..." -- to free the % latter, you have to call subsequently e.g. % \begin{quote} % \cmdmeta{Prefix}"New"\meta{Name}"*{"$\ldots$"}{\undefined}" % \end{quote} % before). There is also the command % \begin{quote} % "\toolboxFreeDef*["\meta{Prefix}"]"\bracemeta{Name} % \end{quote} % which acts similarly as "\toolboxFreeDef" but which does not undefine the % two macros \cmdmeta{Prefix}\meta{Name} and \cmdmeta{Prefix}"Let"\meta{Name}. % % \subsection{Fancy optional argument parsing} % % This section contains macros which are convenient if you e.g.\ write a % package that contains macros which contain a lot of optional arguments % and flags (like "*"). % Typically, to read such an optional argument or flag, you save % the next token with "\futurelet" and then call a macro which decides what to % do with the token read. Thus, a typical use of "\futurelet" looks like % \begin{verbatim} % \def\MacroWithOptionalFlag{\futurelet\tokread\myscan}\end{verbatim} % which will define "\tokread" to be the token \emph{following} the macro % "\MacroWithOptionalFlag" in the token stream and then execute "\myscan". % In this context, it is not very convenient that you % are \emph{forced} to define a macro "\myscan": It could be more convenient % if you could just write the \emph{content} of "\tokread" (in braces) into % the above definition. You can indeed do this if you replace "\futurelet" % by \DescribeMacro{\toolboxFuturelet}"\toolboxFuturelet": % % \begin{quote} % "\toolboxFuturelet\token"\bracemeta{argument} % \end{quote} % % The call "\toolboxFuturelet\token{\command}" has precisely the same % effect as "\futurelet\token\command". The advantage of "\toolboxFuturelet" % is that instead of a single "\command" one may use also a sequence of % commands.\par % Let us consider "\MacroWithOptionalFlag" as above. Assume that the user % has called this macro in the form "\MacroWithOptionalFlag*" where the % "*" is a flag which should cause your macro to do something slightly % different. On some place in your macro definition you will have recognized % (e.g.\ with "\futurelet" or "\toolboxFuturelet") that a "*" is following % in the calling sequence. So you now want to execute your action % (whatever "\MacroWithOptionalFlag" is supposed to do). % However, if you do not take special care, after this action, \TeX\ will % print a "*", because this is the next token on the token stream: "\futurelet" % does not delete any tokens. So you have to ``gobble'' this token away. % A rude way to do this is by using the macro "\gobblenext" as the last token % in you macro which can be defined by % \begin{verbatim} % \def\gobblenext#1{}\end{verbatim} % However, this has two major drawbacks: % \begin{enumerate} % \item This works for "*", but not for "{" or space tokens. % For space tokens the situation is even worse, since \TeX\ eats spaces around % arguments, so sometimes space tokens might unexpectedly disappear. % \item It is not possible in this way to \emph{read} another argument % following the "*": Recall that "\gobblenext" must be the \emph{last} token % in your macro expansion, i.e.\ you have ``lost control'' after this call. % \end{enumerate} % The solution to these problems is instead of calling "\gobblenext" to use % \DescribeMacro{\toolboxGobbleNext}"\toolboxGobbleNext" as the last command % in your call: You can pass it an argument which describes the action that % you want to do \emph{after} gobbling the next token % ("*" in the above example) from the token stream. Thus % \begin{quote} % "\toolboxGobbleNext"\bracemeta{cmd} % \end{quote} % erases the token following that command from the token stream and % then executes \meta{cmd}. This is similar to % \begin{verbatim} % \def\toolboxGobbleNext#1#2{#1}\end{verbatim} % with the difference that "#2" is considered as a token and that no spaces % are eaten.\par % The effect is that e.g.\ the call % \begin{verbatim} % \toolboxGobbleNext{\foo}{{arg}\end{verbatim} % is the same as "\foo{arg}" (the brace "{" is eaten in this example).\par % As described earlier, the commands "\futurelet" or "\toolboxFuturelet" can % be used to check for optional flags. Frequently you will only want % to test for one particular flag and decide the next action on this flag. % Of course, you can test the token found with "\ifx...\fi" but this has the % disadvantage that some tokens (e.g.\ "\fi") follow your action, which might % be bad (recall that e.g.\ "\toolboxGobbleNext" must be the last command of % your action, i.e.\ it would in the above examples not gobble the "*" but % the "\fi" which is probably not what you want). % The simplest solution is to use the command % \DescribeMacro{\toolboxIfNextToken}"\toolboxIfNextToken" which already % has the test included. For example, to test for an optional "[", you can % simply write % \begin{verbatim} % \def\MacroWithOptionalBrace{\toolboxIfNextToken[{\yes}{\no}}\end{verbatim} % and then the call "\MacroWithOptionalBrace[...]" will expand to "\yes[...]" % while "\MacroWithOptionalBrace x" will expand to "\no x" (note that the % brace is not gobbled---if you want the latter, use "\toolboxIfNextGobbling" % described below).\par % More precisely, the calling syntax of "\toolboxIfNextToken" is % \begin{quote} % \DescribeMacro{\toolboxIfNextToken} % "\toolboxIfNextToken"\bracemeta{token}\bracemeta{if}\bracemeta{else} % \end{quote} % The semantic is the following: If the token following this command is % \meta{token}, then \meta{if} is executed, otherwise \meta{else}. % It is explicitly admissible that \meta{token} is a space. % To support further tests, \DescribeMacro{\toolboxToken}"\toolboxToken" % is "\let" to the token which follows the command. % "\toolboxToken" is only a temporary token, % i.e.\ it may also be modified by other commands of this package; % in particular, you may also freely modify "\toolboxToken".\par % The token "\toolboxSpaceToken" which is described later may be handy % in connection with this command.\par % In contrast to similar \LaTeXe\ macros % much care has been taken that spaces are not eaten. This solves the % following problem:\par % % Assume that you want to write a macro which should have the calling syntax % "\mymacro{arg1}" or "\mymacro{arg1}[arg2]". You will probably implement % "\mymacro" to read the first argument and then to look whether the next % token is a "[". If you use the \LaTeXe\ macro to test for "[", % then all spaces until the next non-space token would be gobbled which means % that if you would use the \LaTeXe\ macros for the test, then the call % "\mymacro{arg1}"\myspace"Text" would behave like "\mymacro{arg1}Text", % i.e.\ the space is ``mysteriously'' lost. With the \filecite{toolbox} % macros this does not happen. The ``disadvantage'' is that % "\mymacro{arg1}"\myspace"[arg2]" is not the same as % "\mymacro{arg1}[arg2]" either (which is reasonable IMHO). % % Example: % \begin{verbatim} % \def\mycmd#1{\toolboxIfNextToken[{\ParseOpt{#1}}{\NoOpt{#1}}} % \def\ParseOpt#1[#2]{\OptAtEnd{#1}{#2}}\end{verbatim} % After the above definition, "\mycmd{arg}" executes "\NoOpt{arg}" while % "\mycmd{arg}[optional]" executes "\OptAtEnd{arg}{optional}". % We point out once more that in the first call a space following % "\mycmd{arg}" does not vanish (as would be the case if the \LaTeXe\ macros % would have been used).\par % If "\toolboxIfNextToken" has found the required token, it does \emph{not} % gobble that token from the token stream. Of course, you can do this by % yourself using the earlier described macro "\toolboxGobbleNext". However, % it is simpler to use % \begin{quote} % \DescribeMacro{\toolboxIfNextGobbling} % "\toolboxIfNextGobbling"\bracemeta{token}\bracemeta{if}\bracemeta{else} % \end{quote} % This command is analogous to "\toolboxIfNextToken" with the difference that % in the case that the next token is \meta{token}, it is gobbled before % \meta{if} is executed.\par % % Example: % \begin{verbatim} % \def\my{\toolboxIfNextGobbling*\toolboxTokenLoop\toolboxLoop}\end{verbatim} % This makes "\my*..." behave like "\toolboxTokenLoop..." and % "\my..." (without "*") behave like "\toolboxLoop...".\par % The following macro is one which you may want to use in connection with % \LaTeX2e\ optional arguments: % % \begin{quote} % \DescribeMacro{\toolboxIfEmpty} % "\toolboxIfEmpty"\bracemeta{arg}\bracemeta{if}\bracemeta{else} % \end{quote} % % \meta{arg} is not expand; it is only used to decide whether \meta{if} or % \meta{else} will be expanded.\par % For further tests there are more involved macros: % % \begin{quote} % \DescribeMacro{\toolboxIfx} % "\toolboxIfx"\bracemeta{arg}"\macro"\bracemeta{if}\bracemeta{else} % \end{quote} % This tests via "\ifx" whether "\def\Macro"\bracemeta{arg} would give % the definition of "\macro". % % \begin{quote} % \DescribeMacro{\toolboxIfX} % "\toolboxIfX"\bracemeta{arg 1}\bracemeta{arg 2}\bracemeta{if}\bracemeta{else} % \end{quote} % This tests whether \meta{arg 1} and \meta{arg 2} are the same token % sequences.\par % % If you want to avoid the "\else" and "\fi" commands to avoid certain side % effects, you can use instead: % % \begin{quote} % \DescribeMacro{\toolboxIfElse} % "\toolboxIfElse"\bracemeta{ifcmd}\bracemeta{if}\bracemeta{else} % \end{quote} % This is rather analogous to \meta{ifcmd}\meta{if}"\else"\meta{else}"\fi" % but has everything in this line already eliminated from the tokenlist when % \meta{if} resp.\ \meta{else} are expanded. % \subsection{Loops over tokenlists and itemlists} % % \begin{quote} % \DescribeMacro{\toolboxLoop} % "\toolboxLoop"\bracemeta{items}\bracemeta{action} % \end{quote} % % This calls iteratively \meta{action}"{#1}", where "#1" runs over each item in % \meta{items}. Here, an item is either a token or a group % braced by "{...}". % In the latter case, the braces are lost. Spaces in \meta{items} are ignored % (unless they are braced). It is admissible that \meta{action} is not a single % macro but instead a sequence of tokens.\par % Examples follow below.\par % The counterintuitive order of arguments is explained by the fact that the % typical usage is % \begin{quote} % "\expandafter\toolboxLoop\expandafter{\ExpandingMacro}"\bracemeta{action} % \end{quote} % which for swapped order of arguments could hardly be written.\par % % "\toolboxLoop" is not reentrant, i.e.\ \bracemeta{action} may not expand % to something which contains a call to "\toolboxLoop". To enable such calls % anyway, the command % \begin{quote} % \DescribeMacro{\toolboxLoopName} % "\toolboxLoopName"\bracemeta{name}\bracemeta{items}\bracemeta{action} % \end{quote} % is provided which is analogous to "\toolboxLoopName". This is also % not reentrant, but in contrast to "\toolboxLoop", % calls with different \meta{name} can % be used independently of each other, i.e.\ in the \bracemeta{action} part % of a "\toolboxLoop" (or "\toolboxLoopName") can be a call to % "\toolboxLoopName" with a \emph{different} \meta{name} argument. % In particular, using a counter in \meta{name}, one could easily implement % even recursive calls. In this connection, it should be noted that % \meta{name} is expanded via "\csname ... \endcsname", and so you may use % constructs like "\the\namecounter" there.\par % \begin{quote} % \DescribeMacro{\toolboxTokenLoop} % "\toolboxTokenLoop"\bracemeta{tokens}\bracemeta{action} % \end{quote} % This is similar to "\toolboxLoop": The command \meta{action}"\toolboxToken" % is executed iteratively where "\toolboxToken" runs over each token in % \meta{tokens}. The important difference is that "\toolboxToken" is a token % (instead of an item). In particular, "\toolboxToken" runs through every % single token including spaces and braces.\par % The token "\toolboxSpaceToken" which is described later may be handy % in connection with this command.\par % Example: % \begin{verbatim} % \toolboxTokenLoop{Some text}{\kern0.1em}\end{verbatim} % is the similar to "\kern0.1em S\kern0.1em o\kern0.1em m...", i.e.\ you % get wider spacing between the letters of "Some text" (I do not claim that % this is typographically a good idea).\par % % Note that you do not have to take special care about the space. % With "\toolboxLoop", you would have to mask the space e.g.\ with % % \begin{verbatim} % \toolboxLoop{Some{ }text}{\kern0.1em}\end{verbatim} % or % \begin{verbatim} % \toolboxLoop{Some\toolboxSpace text}{\kern0.1em}\end{verbatim} % In contrast, "\toolboxTokenLoop" would behave differently here: % \begin{verbatim} % \toolboxTokenLoop{Some{ }text}{\kern0.1em}\end{verbatim} % would produce "\kern0.1em S...\kern0.1em{\kern0.1em"\myspace"\kern0.1em}..." % because the braces are simply considered as tokens. % % "\toolboxTokenLoop" is not reentrant. Analogously to "\toolboxLoopName", % independent versions can be generated by % \begin{quote} % \DescribeMacro{\toolboxTokenName} % "\toolboxTokenName"\bracemeta{name}\bracemeta{tokens}\bracemeta{action} % \end{quote} % \subsection{Controlled expansion} % % There are some occasions when you want more control over the expansion. % E.g.\ you might want to concatenate the contents of two macros to a % further macro or you want to expand a macro by one level but no full % expansion. Usually you can get this effects with "\expandafter", but if % you expand several concatenated tokens in this way you either have to % write a lot of "\expandafter"s or you have to define subsidiary macros % that help you to "\expandafter" certain parts of macros. The macros in % this section allow you to do this in the most generic way that I could % implement. % % \begin{quote} % \DescribeMacro{\toolboxDef} % "\toolboxDef\macrotodefine"\bracemeta{argumentlist} % \end{quote} % % This call is similar to % \begin{quote} % "\def\macrotodefine"\bracemeta{argumentlist} % \end{quote} % with two important differences: % % For "\toolboxDef", \meta{argumentlist} is expanded precisely by one level. % \meta{argumentlist} may not contain macros with parameters, and spaces in the % highest level are ignored. If you want to force a space on a particular % place, use the macro \DescribeMacro{\toolboxSpace}"\toolboxSpace" at this % place (which is described later). Contrary to the usual "\def", the % symbol "#" is treated as a usual symbol. % % Example of usage: % \begin{verbatim} % \toolboxDef\chain{\chain\toolboxSpace\after}\end{verbatim} % This modifies the macro "\chain" such that a space and the content of the % macro "\after" is appended at the end. % % \begin{quote} % \DescribeMacro{\toolboxAppend} % "\toolboxAppend\macrotodefine"\bracemeta{argumentlist} % \end{quote} % This is equivalent to % \begin{quote} % "\toolboxDef\macrotodefine{\macrotodefine"\meta{argumentlist}"}" % \end{quote} % \par % The macro % \begin{quote} % \DescribeMacro{\toolboxSurround} % "\toolboxSurround"\bracemeta{content before}\bracemeta{content after}"\macro" % \end{quote} % redefines "\macro" such that \meta{content before} is put at the % beginning and \meta{content after} after the definition of "\macro". % So this is equivalent to % \begin{quote} % "\def\macro{"\meta{content before}\meta{old content of \cmdcite{macro}}\relax %\meta{content after}"}" % \end{quote} % It is required that "\macro" is a usual macro without any arguments. % If you want to patch more complicated macros, use the \filecite{patch.doc} % package instead. % The order of the arguments may appear strange, but it is convenient if % \meta{content before} or \meta{content after} are macros which should be % expanded with "\expandafter". % There is some subsidiary macro used in the implementation of the above % macros which might be useful also in some other situations: % % \begin{quote} % \DescribeMacro{\toolboxTokDef} % "\toolboxTokDef"\bracemeta{argumentlist}"\macrotodefine" % \end{quote} % This call is similar to % \begin{quote} % "\def\macrotodefine"\bracemeta{argumentlist} % \end{quote} % with the difference that the symbol "#" is stored as such. % The order of the arguments has been swapped in order to simplify the % application of "\expandafter" to \meta{argumentlist}. % % \subsection{Searching, splitting, and replacing} % % \begin{quote} % \DescribeMacro{\toolboxSplitAt} % "\toolboxSplitAt"\bracemeta{argument}\bracemeta{search}\relax %"{\beforestring}{\afterstring}" % \end{quote} % % Here, "\beforestring" and "\afterstring" are arbitrary macro names, % and \meta{search} and \meta{argument} are any sequences of tokens (which % are in the following considered as `strings'). % % This call scans \meta{argument} for the first occurrence of \meta{search}. % The macros "\beforestring" and "\afterstring" are defined correspondingly % such that "\beforestring" expands to the part before the first occurrence, % and "\afterstring" to the part following the first occurrence. % If \meta{search} does not occur in \meta{argument}, "\beforestring" is % defined to \meta{argument}, and "\afterstring" is "\let" "\undefined". % % If "\beforestring" or "\afterstring" had already been defined before the % call, the previous definition is tacitly overridden. % It is explicitly allowed that "\beforestring" and "\afterstring" are the % same names. In this case, the result has the meaning of "\afterstring". % % It is guaranteed that braces "{...}" are \emph{not} lost in \meta{argument}. % However, \meta{search} may not contain any braces, and \meta{argument} may % contain only matching pairs of braces. Moreover, occurrences of \meta{search} % within a pair of braces in \meta{argument} are not recognized. % % (The order of the arguments has been chosen in order to simplify the % use of "\expandafter"). % % There are some restrictions for the strings in search. For example, % the symbol "#" is not allowed. % % In the above call, the arguments may not run over several paragraphs. % If you want the latter, you have to use the alternative call % \begin{quote} % "\toolboxSplitAt*"\bracemeta{argument}\bracemeta{search}\relax %"{\beforestring}{\afterstring}" % \end{quote} % % Example of usage: % % \begin{verbatim} % \def\examplemacro#1{\toolboxSplitAt{#1}{@}\testme\testme % \ifx\testme\undefined % ... (do this when #1 contains no `@' token) % \fi}\end{verbatim} % % If "\toolboxSplitAt" should be used several times with the same % \meta{search} string, it is much more efficient to use the following command: % % \begin{quote} % \DescribeMacro{\toolboxMakeSplit} % "\toolboxMakeSplit"\bracemeta{search}"{command}" % \end{quote} % % This call defines a new macro "\command" (the name is determined by the % second argument of "\toolboxMakeSplit") which can be called in the form % % \begin{quote} % "\command"\bracemeta{argument}"{\beforestring}{\afterstring}" % \end{quote} % % and which has the analogous meaning as "\SplitAt" (the argument % \bracemeta{search} is implicitly fixed and taken from the call of % "\toolboxMakeSplit"). % It is explicitly admissible that the above macro "\toolboxMakeSplit" is % used with an already existing command name. In this case, the previous % definition of "\command" is tacitly overridden. % % The command created by "\toolboxMakeSplit" does not accept arguments which % run over several paragraphs. If you want the latter, you have to create % this command by the alternative call % % \begin{quote} % "\toolboxMakeSplit*"\bracemeta{search}"{command}" % \end{quote} % The command % \begin{quote} % "\toolboxFreeSplit"\bracemeta{command} % \end{quote} % frees the memory used by a previous "\toolboxMakeSplit" (and lets "\command" % again be undefined). % The command % \begin{quote} % \DescribeMacro{\toolboxReplace} % "\toolboxReplace"\bracemeta{search}\bracemeta{replace}"\macro" % \end{quote} % replaces in "\macro" all occurences of \meta{search} by \meta{replace}. % The same matches are found as in "\toolboxSplitAt". % If you need to search for the same text several times, it is faster % to use the command % \begin{quote} % \DescribeMacro{\toolboxReplaceSplit} % "\toolboxReplaceSplit"\bracemeta{replace}"\SplitCmd\macro" % \end{quote} % where "\SplitCmd" is a command previously generated with "\toolboxMakeSplit*" % according to your \meta{search} string. (You could also use % "\toolboxMakeSplit" to generate "\SplitCmd", but then "\macro" should not % contain any "\par"s). % \subsection{Redefinition of macros} % % % \begin{quote} % \DescribeMacro{\toolboxMakeHarmless} % "\toolboxMakeHarmless{\macro}" % \end{quote} % % The above call redefines "\macro" such that it expands to an ASCII text % containing the previous definition of "\macro" (i.e.\ the catcodes of % "\macro" are changed). % The call % \begin{quote} % \DescribeMacro{\toolboxDropBrace} % "\toolboxDropBrace{\macro}" % \end{quote} % drops possible outer braces of "\macro". More precisely, % if "\macro" expands to \bracemeta{content}, then "\macro" is redefined % to \meta{content} (without braces). Otherwise, nothing happens. % The command % \begin{quote} % \DescribeMacro{\toolboxIf} % "\toolboxIf"\meta{comparison}\bracemeta{definition commands}\relax %\cmdmeta{macro}$\ldots$ % \end{quote} % allows conditional definitions. Here, \bracemeta{definition command} % is either "\def", "{\long\def}", "\let", or some similar command like % e.g.\ the \LaTeX\ "\newcommand". If the test % "\ifx"\meta{comparison}\cmdmeta{macro} evaluates positive, then % \cmdmeta{macro} is defined correspondingly. Otherwise, \cmdmeta{macro} % is not changed.\par\smallskip % % \textbf{Examples:} % % \begin{verbatim} % \toolboxIf\undefined\def\macro{....} % \toolboxIf\undefined\let\macro... % \toolboxIf\undefined{\long\def}\macro{....} % \toolboxIf\undefined\newcommand{\macro}{....}\end{verbatim} % % are similar to "\def\macro{...}" resp.\ "\let\macro..." % resp.\ "\long\def\macro{...}" resp.\ "\newcommand{\macro}" with the % difference that "\macro" is not changed if it was already defined. % In this sense, "\toolboxIf" is a more flexible variant of "\providecommand". % % The commands % \begin{quote} % \DescribeMacro{\toolboxNewiftrue} % "\toolboxNewiftrue"\bracemeta{name}\\ % \DescribeMacro{\toolboxNewiffalse} % "\toolboxNewiffalse"\bracemeta{name} % \end{quote} % test whether the command "\if"\meta{name} was already introduced with % "\newif"; in this case nothing happens. Otherwise, "\if"\meta{name} is % introduced similarly to "\newif\if"\meta{name} and set to "true" % respectively "false". % In contrast to the corresponding command in \TeX\ or \LaTeX 2.09, this macro % is not "\outer"! % \begin{quote} % \DescribeMacro{\toolboxNewifTrue} % "\toolboxNewifTrue"\bracemeta{name}\\ % \DescribeMacro{\toolboxNewifFalse} % "\toolboxNewifFalse"\bracemeta{name} % \end{quote} % are similar to "\toolboxNewiftrue"\bracemeta{name} and % "\toolboxNewiffalse"\bracemeta{name}, respectively, % with the difference that "\if"\meta{name} is set unconditionally % to "true" respectively "false". % \subsection{Concatenated macro names} % % \begin{quote} % \DescribeMacro{\toolboxLet} % "\toolboxLet\variable"\bracemeta{macroname} % \end{quote} % The above command is analogous to "\let\variable\macroname" with the % difference that \meta{macroname} can also contain other tokens like numbers % (it is obtained via "\csname"). Some converse to this command is % % \begin{quote} % "\toolboxWithNr"\bracemeta{number}"\command"\bracemeta{macro} % \end{quote} % which translates into "\command\macronumber" (here, \meta{macro} and % \meta{number} are just concatenated and evaluated via "\csname"). % Examples: % \begin{verbatim} % \toolboxWithNr 1\let{name}\toolboxEmpty\end{verbatim} % This is the same as "\let\name1\toolboxEmpty" (but such that "\name1" is % considered as a name, not as "\name 1") % \begin{verbatim} % \toolboxWithNr {10}\def{name}{Foo}\end{verbatim} % This corresponds analogously to "\def\name10{Foo}". % \begin{verbatim} % \toolboxLet\mymacro{name\the\mycount}\end{verbatim} % This is similar to "\let\mymacro\namexx" where "xx" is the content % of the counter "\mycount". % \subsection{Various} % % The following macros have equivalents in most formats (like \LaTeXe). % However, we do not want to rely too much on these formats, so we provide % our own definitions. % The macro % \begin{quote} % \DescribeMacro{\toolboxEmpty}"\toolboxEmpty" % \end{quote} % expands to nothing (usually, this is the same as "\empty"). % Similarly, the macro % \begin{quote} % \DescribeMacro{\toolboxSpace}"\toolboxSpace" % \end{quote} % expands to a space symbol (usually, this is the same as "\space"). % The token % \begin{quote} % \DescribeMacro{\toolboxSpaceToken}"\toolboxSpaceToken" % \end{quote} % is "\let" a space token (usually, this is the same as "\@sptoken"). % This token is convenient in tests of tokens % (because it is hard to get a space there which is not eaten by the % \TeX\ parser, although sometimes also constructions like % \begin{verbatim} % \expandafter\ifx\toolboxSpace\token\end{verbatim} % can be used). Also the macros % \begin{quote} % \DescribeMacro{\toolboxFirstOfTwo}"\toolboxFirstOfTwo"\\ % \DescribeMacro{\toolboxSecondOfTwo}"\toolboxSecondOfTwo" % \end{quote} % are provided which read two arguments and return only the first % respectively second argument (usually, this is the same as % "\@firstoftwo" respectively "\@secondoftwo"). Similarly, % \begin{quote} % \DescribeMacro{\toolboxGobbleArg} % "\toolboxGobbleArg"\bracemeta{argument} % \end{quote} % just reads its argument and expands to nothing. % \iffalse % % \fi % \iffalse--------------------------------------------------------------\fi % \StopEventually{\PrintChanges} % \section{Implementation} % % \iffalse-------------------------------------------------------------- % % %<*package> % \fi % \begin{macrocode} %% %% This file was generated by the docstrip utility from toolbox.dtx. %% You may distribute this file only together with the source toolbox.dtx %% (and if possible with toolbox.ins) and only if these files are unmodified. %% %% Author: %% %% M. V\"ath martin@mvath.de %% \ifx\typeout\undefined \def\tbx@tmp{\immediate\write17}\expandafter\tbx@tmp \else \expandafter\typeout \fi{toolbox.sty by M. Vaeth: The TeX Programmer's Toolbox 5.1} %% First, some LaTeX support: %% We inform LaTeX that this is a package, and we test whether we would %% override some existing commands. \ifx\ProvidesPackage\undefined\else \ProvidesPackage{toolbox}[2004/04/29 v5.1] \fi \ifx\newcommand\undefined\else \newcommand{\toolboxMakeDef}{} \newcommand{\toolboxFreeDef}{} \newcommand{\toolboxFuturelet}{} \newcommand{\toolboxGobbleNext}{} \newcommand{\toolboxIfNextToken}{} \newcommand{\toolboxIfNextGobbling}{} \newcommand{\toolboxIfEmpty}{} \newcommand{\toolboxIfx}{} \newcommand{\toolboxIfX}{} \newcommand{\toolboxIfElse}{} \newcommand{\toolboxLoop}{} \newcommand{\toolboxLoopName}{} \newcommand{\toolboxToken}{} \newcommand{\toolboxTokenName}{} \newcommand{\toolboxTokDef}{} \newcommand{\toolboxDef}{} \newcommand{\toolboxAppend}{} \newcommand{\toolboxSplitAt}{} \newcommand{\toolboxMakeSplit}{} \newcommand{\toolboxFreeSplit}{} \newcommand{\toolboxReplace}{} \newcommand{\toolboxReplaceSplit}{} \newcommand{\toolboxMakeHarmless}{} \newcommand{\toolboxDropBrace}{} \newcommand{\toolboxIf}{} \newcommand{\toolboxNewiftrue}{} \newcommand{\toolboxNewiffalse}{} \newcommand{\toolboxLet}{} \newcommand{\toolboxWithNr}{} \newcommand{\toolboxEmpty}{} \newcommand{\toolboxSpace}{} \newcommand{\toolboxSpaceToken}{} \newcommand{\toolboxFirstOfTwo}{} \newcommand{\toolboxSecondOfTwo}{} \newcommand{\toolboxGobbleArg}{} \fi % \end{macrocode} % \subsection{Macros for various purposes} % \begin{macro}{\toolboxSpace}\nocomment % \begin{macrocode} \def\toolboxEmpty{} % \end{macrocode} % \end{macro} % \begin{macro}{\toolboxSpace}\nocomment % \begin{macrocode} \def\toolboxSpace{ } % \end{macrocode} % \end{macro} % \begin{macro}{\toolboxSpaceToken} % We cannot just write % \begin{verbatim*}\let\toolboxSpaceToken= \end{verbatim*} % because then the space would be eaten by \TeX's parser. % Also tries like % \begin{verbatim} % \expandafter\let\expandafter\toolboxSpaceToken\toolboxSpace\end{verbatim} % do not work for similar reasons. In contrast, % \begin{verbatim} % \futurelet\toolboxSpaceToken{ }\end{verbatim} % is possible (because the space is not `really' parsed at this time), % but it would have the side effect that the group "{ }" is executed which % forces a space output. We could artificially `eat' this output in some box. % But we proceed differently by replacing "{ }" in % the above call by an appropriate "\if...\fi". Of course, we have to take % care that the space is not eaten too early. % \begin{macrocode} \expandafter \futurelet\expandafter\toolboxSpaceToken\expandafter \if\toolboxSpace\toolboxEmpty\toolboxEmpty\fi % \end{macrocode} % \end{macro} % \begin{macro}{\toolboxFirstOfTwo}\nocomment % \begin{macrocode} \long\def\toolboxFirstOfTwo#1#2{#1} % \end{macrocode} % \end{macro} % \begin{macro}{\toolboxSecondOfTwo}\nocomment % \begin{macrocode} \long\def\toolboxSecondOfTwo#1#2{#2} % \end{macrocode} % \end{macro} % \begin{macro}{\toolboxGobbleArg} % \begin{macrocode} \long\def\toolboxGobbleArg#1{} % \end{macrocode} % \end{macro} % % \begin{macro}{\tbx@toks} % We need a temporary token list % \begin{macrocode} \toksdef\tbx@toks=0 % \end{macrocode} % \end{macro} % % \subsection{Macros supporting implicit macro definitions} % % \begin{macro}{\toolboxMakeDef}\nocomment % \begin{macrocode} \def\toolboxMakeDef{\tbx@MakeNames\tbx@MakeDef} % \end{macrocode} % \begin{macro}{\tbx@MakeDef} % The macros for "\toolboxMakeDef" are defined with % \begin{quote} % "\tbx@MakeDef\PrefixNewName\PrefixRenewName\PrefixProvideName%"\\ % " \PrefixDefName\PrefixLetName\PrefixName\tbx@e@Prefix@Name%"\\ % " "\bracemeta{Prefix}\bracemeta{Name}\bracemeta{Replacement Mask} % \end{quote} % Note that \meta{Replacement Mask} must be read implicitly, because it % contains "#1" which is usually forbidden. % The macro "\tbx@e@Prefix@Name" is defined as % \begin{quote} % "\tbx@long\def\tbx@e@Name#1"\bracemeta{Replacement Mask} % \end{quote} % The macros generated by % \begin{quote} % "\PrefixNewName"\bracemeta{something}"{"$\ldots$"...}" % \end{quote} % carry the names % \begin{quote} % "\tbx@l@"\meta{Prefix}"@"\meta{Name}"@"\meta{something} % \end{quote} % Observe that the symbol "@" has currently the exceptional letter catcode, % so that there is no danger that the user mangles up the names (unless he % uses "\makeatletter" which he should of course not do, usually). % \makeatletter % \begin{macrocode} \def\tbx@MakeDef#1#2#3#4#5#6#7#8#9{% \tbx@def#1{\toolboxIfNextGobbling*% {\tbx@MakeNew\let{#8}{#9}}{\tbx@MakeNew\def{#8}{#9}}}% \tbx@def#2{\toolboxIfNextGobbling*% {\tbx@MakeRenew\let{#8}{#9}}{\tbx@MakeRenew\def{#8}{#9}}}% \tbx@def#3{\toolboxIfNextGobbling*% {\tbx@MakeProvide\let{#8}{#9}}{\tbx@MakeProvide\def{#8}{#9}}}% \tbx@def#4{\toolboxIfNextGobbling*% {\tbx@MakeForce\let{#8}{#9}}{\tbx@MakeForce\def{#8}{#9}}}% \tbx@def#5##1##2{\expandafter \tbx@MakeLet\csname tbx@l@#8@#9@##2\endcsname##1}% \tbx@def#6{\toolboxIfNextGobbling*% {\tbx@MakeUse\tbx@itemEnd{#8}{#9}}{\tbx@MakeUse\relax{#8}{#9}}}% \long\def#7##1} % \end{macrocode} % \begin{macro}{\tbx@MakeNew} % "\tbx@MakeNew"\bracemeta{mode}\relax %\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}% %\bracemeta{text to remember} % \begin{macrocode} \def\tbx@MakeNew#1#2#3#4{\expandafter \ifx\csname tbx@l@#2@#3@#4\endcsname\relax\else \errmessage{#2New#3: entry #4 already exists}% \fi \tbx@MakeForce{#1}{#2}{#3}{#4}} % \end{macrocode} % \end{macro} % \begin{macro}{\tbx@MakeRenew} % "\tbx@MakeRenew"\bracemeta{mode}\relax %\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}% %\bracemeta{text to remember} % \begin{macrocode} \def\tbx@MakeRenew#1#2#3#4{\expandafter \ifx\csname tbx@l@#2@#3@#4\endcsname\relax \errmessage{#2Renew#3: entry #4 was not defined before}% \fi \tbx@MakeForce{#1}{#2}{#3}{#4}} % \end{macrocode} % \end{macro} % \begin{macro}{\tbx@MakeProvide} % "\tbx@MakeProvide"\bracemeta{mode}\relax %\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}% %\bracemeta{text to remember} % \begin{macrocode} \def\tbx@MakeProvide#1#2#3#4#5{\expandafter \ifx\csname tbx@l@#2@#3@#4\endcsname\relax \tbx@MakeForce{#1}{#2}{#3}{#4}{#5}% \fi} % \end{macrocode} % \end{macro} % \begin{macro}{\tbx@MakeForce} % "\tbx@MakeForce"\bracemeta{mode}\relax %\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something}% %\bracemeta{text to remember} % \begin{macrocode} \long\def\tbx@MakeForce#1#2#3#4#5{% \ifx#1\let \expandafter \let\csname tbx@l@#2@#3@#4\endcsname#5% \else \expandafter \tbx@MakeDoDef\csname tbx@l@#2@#3@#4\expandafter\endcsname \csname tbx@e@#2@#3\endcsname{#5}% \fi} % \end{macrocode} % \begin{macro}{\tbx@MakeDoDef} % \begin{quote} % "\tbx@MakeDoDef"\relax %"\tbx@l@"\meta{Prefix}"@"\meta{Name}"@"\meta{something}"%"\\ %" \tbx@e@"\meta{Prefix}"@"\meta{Name}\bracemeta{text to remember} % \end{quote} % \begin{macrocode} \long\def\tbx@MakeDoDef#1#2#3{\tbx@toks\expandafter{#2{#3}}% \edef#1{\the\tbx@toks}} % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\tbx@MakeLet} % "\tbx@MakeLet"\cmdmeta{Prefix}"@"\meta{Name}"@"\meta{something}\relax %\cmdmeta{something} % \begin{macrocode} \def\tbx@MakeLet#1#2{% \ifx#1\relax \let#2\undefined \else \let#2#1% \fi} % \end{macrocode} % \end{macro} % \begin{macro}{\tbx@MakeUse} % "\tbx@MakeUse"\bracemeta{mode}\relax %\bracemeta{Prefix}\bracemeta{Name}\bracemeta{something} % \begin{macrocode} \def\tbx@MakeUse#1#2#3#4{% \expandafter \ifx\csname tbx@l@#2@#3@#4\endcsname#1% \errmessage{Entry #4 was not defined with #2New#3, #2Provide#3, or #2Def#3}% \fi \csname tbx@l@#2@#3@#4\endcsname} % \end{macrocode} % \end{macro} % \begin{macro}{\tbx@def} % "\tbx@def" is similar to "\def", but existence is tested (via "\relax") % \begin{macrocode} \def\tbx@def#1{% \ifx#1\relax\else \errmessage{\string#1 is already defined}% \fi \def#1} % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\toolboxFreeDef}\nocomment % \begin{macrocode} \def\toolboxFreeDef{\toolboxIfNextGobbling*% {\tbx@MakeNames{\tbx@FreeDef\relax}}{\tbx@MakeNames{\tbx@FreeDef\undefined}}} % \end{macrocode} % \begin{macro}{\tbx@FreeDef} % \begin{quote} % "\tbx@FreeDef"\bracemeta{mode}"\PrefixNewName\PrefixRenewName%"\\ % " \PrefixProvideName\PrefixDefName\PrefixLetName\PrefixName"%\\ % " \tbx@e@Prefix@Name"\bracemeta{Prefix}\bracemeta{Name} % \end{quote} % The last two arguments are not needed, but we must gobble them. % Since a macro can have at most 9 arguments, we must gobble the last one % separately. % \begin{macrocode} \def\tbx@FreeDef#1#2#3#4#5#6#7#8#9{% \let#2\undefined\let#3\undefined\let#4\undefined\let#5\undefined \let#8\undefined \ifx#1\undefined \let#6\undefined\let#7\undefined \fi\toolboxGobbleArg} % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\tbx@MakeNames} % The call % \begin{quote} % "\tbx@MakeNames"\bracemeta{commands}"["\meta{Prefix}"]"\bracemeta{Name} % \end{quote} % (where the "["\meta{Prefix}"]" argument is optional) expands to % \begin{quote} % \meta{commands}"\PrefixNewName\PrefixRenewName\PrefixProvideName%"\\ % " \PrefixLetName\PrefixName\tbx@e@Prefix@Name%"\\ % " "\bracemeta{Prefix}\bracemeta{Name} % \end{quote} % \begin{macrocode} \def\tbx@MakeNames#1{\toolboxIfNextToken[%] {\tbx@MakingNames{#1}}{\tbx@MakingNames{#1}[]}} % \end{macrocode} % \begin{macro}{\tbx@MakingNames} % \begin{macrocode} \def\tbx@MakingNames#1[#2]#3{\expandafter \tbx@ListSwap\expandafter{% \csname#2New#3\expandafter\endcsname \csname#2Renew#3\expandafter\endcsname \csname#2Provide#3\expandafter\endcsname \csname#2Def#3\expandafter\endcsname \csname#2Let#3\expandafter\endcsname \csname#2#3\expandafter\endcsname \csname tbx@e@#2@#3\endcsname{#2}{#3}}{#1}} % \end{macrocode} % \begin{macro}{\tbx@ListSwap}\nocomment % \begin{macrocode} \def\tbx@ListSwap#1#2{#2#1} % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % % \subsection{Macros supporting fancy optional argument parsing} % % \begin{macro}{\toolboxFuturelet} % \begin{macrocode} \long\def\toolboxFuturelet#1#2{\toolboxTokDef{#2}\tbx@tmp\futurelet#1\tbx@tmp} % \end{macrocode} % \end{macro} % \begin{macro}{\toolboxGobbleNext} % \begin{macrocode} \long\def\toolboxGobbleNext#1{\toolboxTokDef{#1}\tbx@tmp \afterassignment\tbx@tmp \let\toolboxToken= }% The space here is important to read spaces properly % \end{macrocode} % \end{macro} % \begin{macro}{\toolboxIfNextToken} % \begin{macrocode} \long\def\toolboxIfNextToken#1#2#3{% \toolboxFuturelet\toolboxToken{% \ifx#1\toolboxToken \expandafter\toolboxFirstOfTwo \else \expandafter\toolboxSecondOfTwo \fi{#2}{#3}}} % \end{macrocode} % \end{macro} % \begin{macro}{\toolboxIfNextGobbling} % \begin{macrocode} \long\def\toolboxIfNextGobbling#1#2#3{% \toolboxIfNextToken{#1}{\toolboxGobbleNext{#2}}{#3}} % \end{macrocode} % \end{macro} % % \subsection{Macros supporting loops over tokenlists and itemlists} % % \begin{macro}{\toolboxLoop} % "\toolboxLoop" just calls "\tbx@item" with the magic names % "\tbx@i" and "\tbx@I". % \begin{macrocode} \long\def\toolboxLoop#1#2{\tbx@item\tbx@i\tbx@I{#1}{#2}} % \end{macrocode} % \end{macro} % \begin{macro}{\toolboxLoopName} % "\toolboxLoopName" calls "\tbx@item" with the magic names "\tbx@i@#1" % and "\tbx@I#@1" % \begin{macrocode} \long\def\toolboxLoopName#1#2#3{\tbx@LoopName{#1}iI\tbx@item{#2}{#3}} % \end{macrocode} % \end{macro} % \begin{macro}{\tbx@LoopName} % \begin{verbatim} % \tbx@LoopName{name}{x}{y}{\exec}\end{verbatim} % is equivalent to % \begin{verbatim} % \exec\tbx@x@name\tbx@y@name\end{verbatim} % \begin{macrocode} \def\tbx@LoopName#1#2#3#4{% \expandafter#4\csname tbx@#2@#1\expandafter\endcsname \csname tbx@#3@#1\endcsname} % \end{macrocode} % \end{macro} % \begin{macro}{\tbx@item} % The call % \begin{quote} % "\tbx@item{\MagicNameA}{\MagicNameB}"\bracemeta{items}\bracemeta{action} % \end{quote} % is the essential part of "\toolboxLoop". It has the same semantic with % the only difference that the names "\MagicNameA" and "\MagicNameB" are used % as temporary macros (they are the reason why "\tbx@item" is not reentrant). % \begin{macrocode} \long\def\tbx@item#1#2#3#4{% \long\def#1##1{% \toolboxTokDef{##1}\toolboxToken \ifx\toolboxToken\tbx@itemEnd \def#2{\let#1\undefined\let#2\undefined}% \else #4{##1}% \fi #2}% \let#2#1% #1#3\tbx@itemEnd} % \end{macrocode} % \begin{macro}{\tbx@itemEnd} % "\tbx@itemEnd" is the magic token used to mark the end of the list in % "\tbx@item". % Of course, we could also use any other macro instead, but this is unique, % even if we compare with "\ifx". Moreover, we want a short macro to % avoid unnecessary redundancy in comparing with "\ifx". % It appears not necessary to make this token change in recursions, because % in each expansion of a list, the newest item will automatically be the % earliest. % \begin{macrocode} \def\tbx@itemEnd{\tbx@itemEnd} % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\toolboxTokenLoop} % "\toolboxTokenLoop" just calls "\tbx@token" with the magic names % "\tbx@t" and "\tbx@T". % \begin{macrocode} \long\def\toolboxTokenLoop#1#2{\tbx@token\tbx@t\tbx@T{#1}{#2}} % \end{macrocode} % \end{macro} % \begin{macro}{\toolboxTokenLoopName} % "\toolboxTokenLoopName" calls "\tbx@token" with the magic names "\tbx@t@#1" % and "\tbx@T#@1" % \begin{macrocode} \long\def\toolboxTokenLoopName#1#2#3{\tbx@LoopName{#1}tT\tbx@token{#2}{#3}} % \end{macrocode} % \end{macro} % \begin{macro}{\tbx@token} % The call % \begin{quote} % "\tbx@token{\MagicNameA}{\MagicNameB}"\bracemeta{items}\bracemeta{action} % \end{quote} % is the essential part of "\toolboxTokenLoop". It has the same semantic with % the only difference that the names "\MagicNameA" and "\MagicNameB" are used % as temporary macros (they are the reason why "\tbx@token" is not reentrant). % \begin{macrocode} \long\def\tbx@token#1#2#3#4{% \def#1{% \ifx\toolboxToken\tbx@tokenEnd \def#2{\let#1\undefined\let#2\undefined}% \else #4\toolboxToken \fi #2}% \def#2{\afterassignment#1\let\toolboxToken= }% #2#3\tbx@tokenEnd} % \end{macrocode} % \begin{macro}{\tbx@tokenEnd} % "\tbx@tokenEnd" is the magic token used to mark the end of the list % for "\tbx@token". % The same remarks as for "\tbx@itemEnd" hold. However, it is not clear % whether we could just use "\tbx@itemEnd" instead, because the scan rules % for "\tbx@token" and "\tbx@item" are somewhat different, and thus it is % not immediately clear whether in some fancy situations such lists (if % called cross-wise) could overlap: I found no example, but I also did not % put too much effort in finding one. In any case, we are on the sure side, % if we just use a different token. % \begin{macrocode} \def\tbx@tokenEnd{\tbx@tokenEnd} % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\toolboxIfEmpty} % \begin{macrocode} \long\def\toolboxIfEmpty#1{\toolboxIfx{#1}\toolboxEmpty} % \end{macrocode} % \end{macro} % \begin{macro}{\toolboxIfX} % \begin{macrocode} \long\def\toolboxIfX#1#2{\toolboxTokDef{#1}\tbx@ifx\toolboxIfx{#2}\tbx@ifx} % \end{macrocode} % \end{macro} % \begin{macro}{\toolboxIfx} % \begin{macrocode} \long\def\toolboxIfx#1#2{\toolboxTokDef{#1}\tbx@tmp \toolboxIfElse{\ifx\tbx@tmp#2}} % \end{macrocode} % \end{macro} % \begin{macro}{\toolboxIfElse} % \begin{macrocode} \long\def\toolboxIfElse#1{#1\expandafter \toolboxFirstOfTwo\else\expandafter\toolboxSecondOfTwo\fi} % \end{macrocode} % \end{macro} % % % \subsection{Macros supporting controlled expansion} % % \begin{macro}{\toolboxTokDef}\nocomment % \begin{macrocode} \long\def\toolboxTokDef#1#2{\tbx@toks{#1}\edef#2{\the\tbx@toks}} % \end{macrocode} % \end{macro} % % \begin{macro}{\toolboxDef} % This is mainly a call of "\toolboxLoopName". It is slightly faster if we % call "\tbx@item" immediately (and then we can also give magic names which do % not clash with any other names). Also for time and memory reasons, we always % assume that the temporary variable % \begin{macro}{\tbx@odeftmp} % "\tbx@odeftmp" % \end{macro} % is "\toolboxEmpty" at the beginning; we reset it to "\toolboxEmpty" at % the end (so that the memory is freed). % \begin{macrocode} \def\toolboxDef#1#2{% \tbx@item\tbx@odefa\tbx@odefb{#2}\tbx@odef \let#1\tbx@odeftmp\let\tbx@odeftmp\toolboxEmpty} \let\tbx@odeftmp\toolboxEmpty % \end{macrocode} % \begin{macro}{\tbx@odef} % \begin{macrocode} \long\def\tbx@odef#1{\expandafter\tbx@odefapp\expandafter{#1}} % \end{macrocode} % \end{macro} % \begin{macro}{\tbx@odefapp} % "\tbx@odefapp" appends its argument to "\tbx@odeftmp". % \begin{macrocode} \long\def\tbx@odefapp#1{\tbx@toks\expandafter{\tbx@odeftmp#1}% \edef\tbx@odeftmp{\the\tbx@toks}} % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\toolboxAppend}\nocomment % \begin{macrocode} \def\toolboxAppend#1#2{\toolboxDef#1{#1#2}} % \end{macrocode} % \end{macro} % % \begin{macro}{\toolboxSurround}\nocomment % \begin{macrocode} \long\def\toolboxSurround#1#2#3{\tbx@toks{#1}% \tbx@toks\expandafter{\the\expandafter\tbx@toks#3#2}% \edef#3{\the\tbx@toks}} % \end{macrocode} % \end{macro} % % % \subsection{Macros supporting searching, splitting, and replacing} % % \begin{macro}{\toolboxMakeSplit}\nocomment % \begin{macrocode} \def\toolboxMakeSplit{% \toolboxIfNextGobbling*\tbx@MakeLong\tbx@MakeShort} % \end{macrocode} % % \begin{macro}{\tbx@Makelong} % \begin{quote} % "\tbx@Makelong"\bracemeta{search}"{cmd}" % \end{quote} % is the same as % \begin{quote} % "\tbx@DoSplitInstance{\cmd}{\tbx@cmd@spt}{\tbx@cmd@rst}" %\bracemeta{search}"\long" % \end{quote} % \begin{macrocode} \long\def\tbx@MakeLong#1#2{% \tbx@SplitNames{#2}% \expandafter \tbx@DoSplitInstance\tbx@splt{#1}\long} % \end{macrocode} % \end{macro} % \begin{macro}{\tbx@MakeShort} % "\tbx@Makeshort" is essentially the same as "\tbx@Makelong" (just that % "\long" is missing, of course). We could have used the same macro with % an additional argument, but it is more convenient for the user if this % macro itself is not "\long" so that new paragraphs in the passed search % string already give an error: It makes no sense to look for new paragraphs % in texts which may not contain new paragraphs. % \begin{macrocode} \def\tbx@MakeShort#1#2{% \tbx@SplitNames{#2}% \expandafter \tbx@DoSplitInstance\tbx@splt{#1}{}} % \end{macrocode} % \end{macro} % % \begin{macro}{\tbx@SplitNames} % The call "\tbx@SplitNames{cmd}" is equivalent to % \begin{verbatim} % \def\tbx@splt{\cmd \tbx@cmd@spt \tbx@cmd@rst}\end{verbatim} % \begin{macrocode} \def\tbx@SplitNames#1{% \expandafter \def\expandafter\tbx@splt\expandafter{\csname#1\expandafter\endcsname \csname tbx@#1@spt\expandafter\endcsname \csname tbx@#1@rst\endcsname}} % \end{macrocode} % \end{macro} % % \begin{macro}{\tbx@DoSplitInstance} % The call % \begin{quote} % "\tbx@DoSplitInstance{\cmd}{\tbx@cmd@spt}{\tbx@cmd@rst}"\bracemeta{search} %\bracemeta{long} % \end{quote} % creates the instance "\cmd" which splits its argument at % \bracemeta{search} (also "\tbx@cmd@spt" and "\tbx@cmd@rst" are created % which are needed for "\cmd" to work). The argument \meta{long} must be % either "\long" or empty, depending whether long definitions are desired.\par % The difficulty in the definition of "\cmd" is to ensure that "{xxx}|{yyy}" % splits into "{xxx}" and "{yyy}" \emph{with} braces (i.e., we have to % find out whether there are braces which are eliminated by \TeX\ as % `argument braces'). Actually, this problem occurs only for the part "{yyy}". % We solve it by appending an "a" to \meta{argument}, i.e., we actually % split the string "{xxx}|{yyy}a". Of course, we have to eliminate the % trailing "a" at the end. % \begin{macrocode} \long\def\tbx@DoSplitInstance#1#2#3#4#5{% #5\def#1##1##2##3{% #2##2##3\toolboxEmpty##1#4#4@tbx@spt% \ifx##3\toolboxEmpty \let##3\undefined \else #3##3##1a@tbx@rst% \fi }% #5\def#2##1##2##3#4##4#4##5@tbx@spt{\expandafter \toolboxTokDef\expandafter{##3}##1\toolboxTokDef{##5}##2}% #5\def#3##1##2#4##3@tbx@rst{\tbx@rememberlasta##3@tbx@dropa% \tbx@defwithoutlasta##1##3@tbx@dropa}} % \end{macrocode} % \begin{macro}{\tbx@rememberlasta} % The call % \begin{quote} % "\tbx@rememberlasta"\meta{arg}"@tbx@dropa" % \end{quote} % (no braces: The magic string "@tbx@dropa" is used to find the end of % \meta{arg}) is only admissible, if the last token in \meta{arg} is an "a". % In this case, \DescribeMacro{\tbx@droplasta}"\tbx@droplasta" is % defined as \meta{arg} without the trailing "a" (but it may happen that % \meta{arg} looses surrounding braces), and the corresponding string with the % trailing "a" (possibly without surrounding braces) is saved into % \DescribeMacro{\tbx@rebuilda}"\tbx@rebuilda". % This macro is used by the instances created % by "\tbx@DoSplitInstance". % \begin{macrocode} \long\def\tbx@rememberlasta#1a@tbx@dropa{\toolboxTokDef{#1}\tbx@droplasta \toolboxTokDef{#1a}\tbx@rebuilda} % \end{macrocode} % \end{macro} % \begin{macro}{\tbx@defwithoutlasta} % The call % \begin{quote} % "\tbx@defwithoutlasta{\afterstring}"\meta{arg}"@tbx@dropa" % \end{quote} % (no braces: The magic string "@tbx@dropa" is used to find the end of % \meta{arg}) is only admissible, if the last token in \meta{arg} is an "a". % If \meta{arg} coincides with "\tbx@rebuilda", % then we know that we did not loose any braces, and we set "\afterstring" % to the content of "\tbx@droplasta"; otherwise we lost braces and thus % have additionally to surround the content of "\afterstring" by braces. % \begin{macrocode} \long\def\tbx@defwithoutlasta#1#2@tbx@dropa{\toolboxTokDef{#2}\tbx@originala \ifx\tbx@originala\tbx@rebuilda % \end{macrocode} % Did we forget braces in "\tbx@rememberlasta"? % \begin{macrocode} \let#1\tbx@droplasta \else \expandafter\toolboxTokDef\expandafter{\expandafter{\tbx@droplasta}}#1% \fi} % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \begin{macro}{\toolboxFreeSplit}\nocomment % \begin{macrocode} \def\toolboxFreeSplit#1{% \tbx@SplitNames{#1}% \expandafter \toolboxLoop\expandafter{\tbx@splt}\tbx@freeSplit} % \end{macrocode} % \begin{macro}{\tbx@freeSplit}\nocomment % \begin{macrocode} \def\tbx@freeSplit#1{\let#1\undefined} % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\toolboxSplitAt} % "\toolboxSplitAt" just calls "tbx@DoSplitInstance" with dummy temporary % variables and then executes the corresponding command. % \begin{macrocode} \def\toolboxSplitAt{\toolboxIfNextGobbling*\tbx@SplitLong\tbx@SplitShort} % \end{macrocode} % \begin{macro}{\tbx@SplitLong}\nocomment % \begin{macrocode} \long\def\tbx@SplitLong#1#2#3#4{% \tbx@DoSplitInstance\tbx@splt\tbx@splta\tbx@spltb{#2}\long \tbx@splt{#1}{#3}{#4}} % \end{macrocode} % \end{macro} % \begin{macro}{\tbx@SplitShort} % We cannot use just an additional argument in "\tbx@SplitLong", because % we really should use a non-"\long" macro to read the arguments. % \begin{macrocode} \def\tbx@SplitShort#1#2#3#4{% \tbx@DoSplitInstance\tbx@splt\tbx@splta\tbx@spltb{#2}{}% \tbx@splt{#1}{#3}{#4}} % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\toolboxReplaceSplit} % "\toolboxReplaceSplit"\bracemeta{replace}"\SplitCmd\macro" % \begin{macrocode} \long\def\toolboxReplaceSplit#1#2#3{% \toolboxTokDef{#1}\tbx@reptext \expandafter \tbx@replace\expandafter{#3}{\let#3\toolboxEmpty}#3#2\tbx@reptext} % \end{macrocode} % \end{macro} % % \begin{macro}{\tbx@replace} % "\tbx@replace\bracemeta{text}\bracemeta{first}\macro\SplitCmd\Reptext" % First executes \meta{first}. % Then appends to "\macro" the content of \bracemeta{text} with the matches % of "\SplitCmd" replaced by the content of "\Reptext". % \begin{macrocode} \long\def\tbx@replace#1#2#3#4#5{#2% #4{#1}\tbx@repla\tbx@replb \toolboxIfElse{\ifx\tbx@replb\undefined}% {\toolboxDef#3{#3\tbx@repla}}% {\toolboxDef#3{#3\tbx@repla#5}% \expandafter\tbx@replace\expandafter{\tbx@replb}{}#3#4#5}} % \end{macrocode} % \end{macro} % % \begin{macro}{\toolboxReplace} % "\toolboxReplace"\bracemeta{search}\bracemeta{replace}"\macro" % just calls "tbx@DoSplitInstance" with dummy temporary variables % and then executes "\toolboxReplaceSplit". % \begin{macrocode} \long\def\toolboxReplace#1#2{% \tbx@DoSplitInstance\tbx@splt\tbx@splta\tbx@spltb{#1}\long \toolboxReplaceSplit{#2}\tbx@splt} % \end{macrocode} % \end{macro} % % \subsection{Macros supporting redefinition of macros} % % \begin{macro}{\toolboxMakeHarmless}\nocomment % \begin{macrocode} \def\toolboxMakeHarmless#1{\edef#1{\tbx@Nearverbatim#1}} % \end{macrocode} % \begin{macro}{\tbx@Nearverbatim}\nocomment % \begin{macrocode} \def\tbx@Nearverbatim{\expandafter\tbx@Meaning\meaning} % \end{macrocode} % \end{macro} % \begin{macro}{\tbx@Meaning}\nocomment % \begin{macrocode} \long\def\tbx@Meaning#1>{} % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\toolboxDropBrace}\nocomment % \begin{macrocode} \def\toolboxDropBrace#1{\expandafter\tbx@ForgetBrace#1@tbx@dropbrace#1} % \end{macrocode} % \end{macro} % \begin{macro}{\tbx@ForgetBrace}\nocomment % \begin{macrocode} \long\def\tbx@ForgetBrace#1@tbx@dropbrace#2{\toolboxTokDef{#1}#2} % \end{macrocode} % \end{macro} % % \begin{macro}{\toolboxIf}\nocomment % \begin{macrocode} \long\def\toolboxIf#1#2#3{% \ifx#1#3\def\tbx@tmp{#2#3}\else\def\tbx@tmp{#2\tbx@tmp}\fi\tbx@tmp} % \end{macrocode} % \end{macro} % % \begin{macro}{\toolboxNewiftrue}\nocomment % \begin{macrocode} \def\toolboxNewiftrue#1{\tbx@newifexec{#1}{\csname#1true\endcsname}} % \end{macrocode} % \end{macro} % \begin{macro}{\toolboxNewiffalse}\nocomment % \begin{macrocode} \def\toolboxNewiffalse#1{\tbx@newifexec{#1}{\csname#1false\endcsname}} % \end{macrocode} % \end{macro} % \begin{macro}{\toolboxNewiftrue}\nocomment % \begin{macrocode} \def\toolboxNewifTrue#1{\tbx@newifexec{#1}{}\csname#1true\endcsname} % \end{macrocode} % \end{macro} % \begin{macro}{\toolboxNewiffalse}\nocomment % \begin{macrocode} \def\toolboxNewifFalse#1{\tbx@newifexec{#1}{}\csname#1false\endcsname} % \end{macrocode} % \end{macro} % \begin{macro}{\tbx@newifexec} % \begin{quote} % "\tbx@newifexec"\bracemeta{name}\bracemeta{initialization} % \end{quote} % If the command "\if"\meta{name} already exists, nothing happens. % Otherwise, the commands \cmdmeta{name}"true" and \cmdmeta{name}"false" are % created (similarly as by the \TeX\ command "\newif"), and afterwards % \meta{initialization} is executed. Here, \meta{initialization} should be % either \cmdmeta{name}"true" or \cmdmeta{name}"false" % which then defines "\if"\meta{name} to the desired default. % (It may also be empty if you do this initialization immediately afterwards). % \meta{initialization} should not contain any potential "\if" tokens.\par % One must be very careful in the implementation of this macro, % because "\if"'s are parsed very strange by \TeX. % However, if an "\if"-command is the first token following our only "\ifx", % we do not run into problems. Moreover, the first parsing until "\fi" does % not see any further "\if", because it is hidden in "\csname" which has not % been expanded by this time. % \begin{macrocode} \def\tbx@newifexec#1#2{\expandafter \ifx\csname if#1\endcsname\relax \expandafter\tbx@newif\csname if#1\endcsname{#1}% #2% \fi} % \end{macrocode} % \begin{macro}{\tbx@newif} % It is rather annoying that D.~E. Knuth has introduced the "\outer" % directive: % The sole purpose of that command is to cause problems and to force people % to think how to get around these problems. It is especially irritating that % the standard command "\newif" was (before \LaTeXe) defined with this % attribute. To work in a normal way, we have to define "\newif" by hand % in a sane way. It is simpler for us, if we do not only pass the name as a % single token but additionally also the full name without "if". % So our simpler "\newif" macro is called as follows: % \begin{quote} % "\tbx@newif"\cmdmeta{ifname}\bracemeta{name} % \end{quote} % This macro does \emph{not} define \cmdmeta{ifname}. But gets automatically % defined after the first call of \cmdmeta{name}"true" or % \cmdmeta{name}"false" which should of course happen immediately afterwards. % \begin{macrocode} \def\tbx@newif#1#2{% \expandafter \def\csname#2true\endcsname{\let#1\iftrue}% \expandafter \def\csname#2false\endcsname{\let#1\iffalse}} % \end{macrocode} % \end{macro} % \end{macro} % % \subsection{Macros supporting concatenated macro names} % % \begin{macro}{\toolboxWithNr}\nocomment % \begin{macrocode} \def\toolboxWithNr#1#2#3{\expandafter#2\csname #3#1\endcsname} % \end{macrocode} % \end{macro} % \begin{macro}{\toolboxLet}\nocomment % \begin{macrocode} \def\toolboxLet#1#2{\expandafter\let\expandafter#1\csname #2\endcsname} % \end{macrocode} % \end{macro} % % \iffalse % % \fi % \Finale\PrintIndex % % % % \iffalse %<*metainfo> % \fi \iffalse ------------------------------------------------------------- % % Just in case that for some reason the file `toolbox.ins' got lost: % The content of this file is between the lines %<*insfile> and %. % %\iffalse % %<*insfile> \def\batchfile{toolbox.ins} \input docstrip.tex \keepsilent \nopreamble \generateFile{toolbox.sty}{f}{\from{toolbox.dtx}{package}} \generateFile{toolbox.txt}{f}{\from{toolbox.dtx}{asciidocu}} \generateFile{toolbox.tex}{f}{\from{toolbox.dtx}{driver}} %%\generateFile{toolbox.ins.dup}{f}{\from{toolbox.dtx}{insfile}} \Msg{***************************************************************} \Msg{*} \Msg{* To finish the installation you have to move the} \Msg{* file 'toolbox.sty' into a directory searched by TeX.} \Msg{*} \Msg{*} \Msg{* Run the file toolbox.tex through LaTeX to produce the} \Msg{* documentation or read the ascii documentation in toolbox.txt} \Msg{*} \Msg{*} \Msg{***************************************************************} \endbatchfile % %<*metainfo> % \fi \fi % \iffalse % % \fi \endinput %%% Local Variables: %%% mode: latex %%% TeX-master: "toolbox.tex" %%% End: