Debian Codegraph @

texmf-dist/source/latex/patchcmd/patchcmd.dtx

raw
1 %%% ====================================================================
2 %%% @LaTeX-doc-source-file{
3 %%% filename = "patchcmd.dtx",
4 %%% version = "1.05",
5 %%% date = "2016/06/03",
6 %%% author = "Michael J Downes",
7 %%% abstract = "Provides a way to add material at beginning or end of
8 %%% a macro's existing definition.",
9 %%% }
10 %%% ====================================================================
11 % \iffalse
12 %%% Copyright 2000 Michael John Downes
13 %%%
14 %%% Following Michael's death, his family have requested that his TeX
15 %%% related files are made publicly available under the LPPL license.
16 %%%
17 %%% This file is available under the LaTeX Project Public License version 1
18 %%% or (at your option) any later version.
19 %%% https://latex-project.org/lppl/
20 %%% (LPPL maintenance status: unmaintained)
21 %%%
22 %<*driver>
23 \NeedsTeXFormat{LaTeX2e}
24 \documentclass{amsdtx}
25 \begin{document}
26 \title{The \pkg{patchcmd} package}
27 \author{Michael~J. Downes\thanks{Michael died in 2003}}
28 \date{Version \fileversion, \filedate}
29 \hDocInput{patchcmd.dtx}
30 \end{document}
31 %</driver>
32 % \fi
33 %
34 % \maketitle
35 % \section{Introduction}
36 %
37 % The \pkg{patchcmd} package provides a command \cn{patchcommand} that
38 % can be used to add material at the beginning and/or end of the
39 % replacement text of an existing macro. It works for macros with any
40 % number of normal arguments (0--9), including macros that were
41 % defined with \cn{DeclareRobustCommand}. However, it does not work
42 % for macros that use \cs{futurelet}, for example ones defined to
43 % have starred forms or optional arguments. In addition, it does not
44 % work for macros that have delimited arguments.
45 %
46 % This package is the result of some discussion initiated by Peter
47 % Wilson in the newsgroup \fn{comp.text.tex} in June 2000 and
48 % continued with Peter and Heiko Oberdiek.
49 %\begin{verbatim}
50 %Subject: Re: Adding stuff at end of a macro
51 %References:
52 % <[email protected]>
53 % <[email protected]>
54 % <[email protected]>
55 %\end{verbatim}
56 %
57 % \StopEventually{}
58 %
59 % \section{Implementation}
60 % Standard declaration of package name and date.
61 % \begin{macrocode}
62 \NeedsTeXFormat{LaTeX2e}
63 \ProvidesPackage{patchcmd}[2016/06/03 v1.05]
64 % \end{macrocode}
65 %
66 % For debugging.
67 % \begin{macrocode}
68
69 %%\def\wrs{\immediate\write\sixt@@n}
70 % \end{macrocode}
71 %
72 % \begin{macrocode}
73 \newcommand{\patchcommand}[1]{%
74 \expandafter\patchcmd@a\meaning#1??->@\@nil#1%
75 }
76 % \end{macrocode}
77 %
78 % We begin by looking at the meaning string of the given token. We
79 % will issue an error message if the token is not a control sequence,
80 % if it is an undefined control sequence, or if it is a known control
81 % sequence but not a macro.
82 % \begin{macrocode}
83 \long\def\patchcmd@a#1#2#3->#4#5\@nil#6{%
84 %% \wrs{\string#6: [#1] [#2] [#3]->[#4]}%
85 \ifx @#4\relax \patchcmdError#6#1%
86 \expandafter\@gobbletwo % discard the other two arguments
87 \else
88 \if l#2\toks@{\patchcmd@e{}#6}% l in this position means \long
89 \else \toks@{\patchcmd@e*#6}% not \long
90 \fi
91 % \end{macrocode}
92 % Now \cs{patchcmd@b} will do further analysis to determine what
93 % kinds of arguments the macro takes. If it takes $n$ normal
94 % arguments, the digit $n$ (0--9) will be added to \cs{toks@}.
95 % \begin{macrocode}
96 \patchcmd@b #3@#4#5 ? ? ? \@nil#6%
97 \expandafter\the\expandafter\toks@
98 \fi
99 }
100 % \end{macrocode}
101 %
102 % We handle robust commands by scanning the first two control words
103 % in the macro's definition to see if the second one is followed by
104 % two spaces. If it is, then arg 7 will be empty. In that case we
105 % compare the csname preceding the two spaces to the original
106 % argument of \cn{patchcommand}. If they are equal it is nearly certain
107 % that this is a robust command in normal \LaTeX{} form. In that case
108 % we call \cn{patchcommand} quasi-recursively on the protected control
109 % sequence with the extra space at the end of its name.
110 % \begin{macrocode}
111 \def\patchcmd@b#1:#2@#3#4 #5#6 #7 #8\@nil#9{%
112 %% \wrs{[#1] [#2] [#3] [#4] [#5] [#6] ARG7=[#7] [#8]}%
113 \if \ifx @#7@\expandafter
114 \ifx\csname #6\endcsname#9T\else F\fi\else F\fi T%
115 \toks@\expandafter{\expandafter\patchcommand\csname #6 \endcsname}%
116 \else
117 \ifx @#2@% No arguments
118 \toks@\expandafter{\the\toks@ 0}%
119 \else
120 \patchcmd@c 0#2{\string##}0%
121 \fi
122 \fi
123 }
124 % \end{macrocode}
125 %
126 % The task of \cs{patchcmd@c} is to iterate over \texttt{\#D} pairs,
127 % where D is a digit in the range 1--9, until reaching the last one.
128 % Whenever we find such a pair, we carry the digit forward for the
129 % next recursive call; but we use digit 0 as a marker to terminate
130 % the recursion. If any other character interrupts the \texttt{\#D}
131 % pattern, it means that this macro has some kind of delimited
132 % argument.
133 % \begin{macrocode}
134 \def\patchcmd@c#1#2#3{%
135 \if\string###2% % yes it's a # token
136 \ifodd 0#31 % and it's followed by a number
137 \if 0#3\patchcmd@d#1\fi % number=0? then we're done
138 \else \patchcmd@d D% # not a number: must be a delimited arg
139 \fi
140 \else \patchcmd@d D% not a # token: must be a delmited arg
141 \fi
142 \patchcmd@c#3%
143 }
144 % \end{macrocode}
145 %
146 % \begin{macrocode}
147 \def\patchcmd@d#1{%
148 \if D#1%
149 \PackageError{patchcmd}{Cannot change a macro that has
150 delimited arguments}\@ehd
151 \else
152 \toks@\expandafter{\the\toks@ #1}%
153 \fi
154 \begingroup
155 \aftergroup\@gobble
156 \let\patchcmd@c\endgroup
157 }
158 % \end{macrocode}
159 %
160 % \begin{macrocode}
161 \def\patchcmd@e#1#2#3#4#5{%
162 \begingroup
163 \edef\@##1{%
164 \@temptokena\noexpand\expandafter{%
165 \noexpand#2%
166 \ifnum#3>0 {####1}\ifnum#3>1 {####2}\ifnum#3>2 {####3}%
167 \ifnum#3>3 {####4}\ifnum#3>4 {####5}\ifnum#3>5 {####6}%
168 \ifnum#3>6 {####7}\ifnum#3>7 {####8}\ifnum#3>8 {####9}%
169 \fi\fi\fi\fi\fi\fi\fi\fi\fi
170 ##1%
171 }%
172 }
173 \@{#5}%
174 \edef\@##1{\endgroup
175 \noexpand\renewcommand#1\noexpand#2\ifcase#3 \else [#3]\fi
176 {##1\the\@temptokena}}%
177 \@{#4}%
178 %% \show#2%
179 }
180 % \end{macrocode}
181 %
182 % Two possible error messages. Optimized. Second arg is the first
183 % letter from the meaning string; it will be ``u'' if and only if the
184 % control sequence is undefined.
185 % \begin{macrocode}
186 \long\def\patchcmdError#1#2{%
187 \begingroup
188 \toks@{Not redefinable}%
189 \ifcat\relax\noexpand#1% Is it a control sequence?
190 \begingroup
191 \let#1=?\ifx ?\relax % Is it "\relax"?
192 \endgroup % accept current value of \toks@
193 \else \endgroup
194 % \end{macrocode}
195 %
196 % This is equivalent to the \cs{@ifundefined} test (true if arg 2 is
197 % either undefined or its meaning is \cs{relax}).
198 %
199 % \begin{macrocode}
200 \if\ifx\relax#1u\else #2\fi u%
201 \toks@{Not defined}%
202 \fi
203 \fi
204 \fi
205 % \end{macrocode}
206 % Apply \cs{string} preemptively to arg 1 to prevent catastrophic
207 % failure if it happens to be \cs{par} (\cs{PackageError} isn't
208 % defined as \cs{long} in older versions of \LaTeX{}).
209 % \begin{macrocode}
210 \edef\@{\endgroup
211 \noexpand\PackageError{patchcmd}{%
212 \the\toks@: \string#1}\noexpand\@ehd}%
213 \@
214 }
215 % \end{macrocode}
216 %
217 % The usual \cs{endinput} to ensure that random garbage at the end of
218 % the file doesn't get copied by \fn{docstrip}.
219 % \begin{macrocode}
220 \endinput
221 % \end{macrocode}
222 %
223 % \CheckSum{183}
224 % \Finale