Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 %% File: xpatch.dtx (C) Copyright 2012-2020 Enrico Gregorio
4 %%
5 %% It may be distributed and/or modified under the conditions of the
6 %% LaTeX Project Public License (LPPL), either version 1.3c of this
7 %% license or (at your option) any later version. The latest version
8 %% of this license is in the file
9 %%
10 %% http://www.latex-project.org/lppl.txt
11 %%
12 %% This file is part of the "xpatch bundle" (The Work in LPPL)
13 %% and all files in that bundle must be distributed together.
14 %%
15 %% The released version of this bundle is available from CTAN.
16 %%
17 %
18 %<*driver|package>
19 \RequirePackage{expl3}
20 %</driver|package>
21 %<*driver>
22 \expandafter\def\csname [email protected]\endcsname{}
23 \documentclass[a4paper,full]{l3doc}
24 \usepackage{bookmark}
25 %</driver>
26 %<*driver|package>
27 \GetIdInfo$Id: xpatch.dtx 0.3a 2020-03-25 12:00:00Z Enrico $
28 {Extending etoolbox patching commands}
29 %</driver|package>
30 %<*driver>
31 \begin{document}
32 \DocInput{\jobname.dtx}
33 \end{document}
34 %</driver>
35 % \fi
36 % \changes{v0.2}{2012/01/13}{Added \texttt{\char`\\x...bibdriver} macros; fixed a bug for
37 % control symbols defined with \texttt{\char`\\newcommand} and an optional argument.}
38 % \changes{v0.3}{2012/10/01}{Added a bunch of biblatex related commands}
39 % \changes{v0.3a}{2020/03/25}{Changed deprecated function}
40 %
41 % \title{^^A
42 % The \textsf{xpatch} package\\ Extending \textsf{etoolbox} patching
43 % commands^^A
44 % \thanks{This file describes version \ExplFileVersion,
45 % last revised \ExplFileDate.}^^A
46 % }
47 %
48 % \author{^^A
49 % Enrico Gregorio\thanks
50 % {^^A
51 % E-mail:
52 % Enrico DOT Gregorio AT univr DOT it^^A
53 % }^^A
54 % }
55 %
56 % \date{Released \ExplFileDate}
57 %
58 % \maketitle
59 %
60 % \begin{documentation}
61 %
62 % \section{Introduction}
63 %
64 % The well known \pkg{etoolbox} package provides a bunch of functions
65 % for patching existing commands; in particular |\patchcmd|,
66 % |\pretocmd| and |\apptocmd| that do a wonderful job, but suffer from
67 % a limitation: if some package has defined
68 %\begin{verbatim}
69 % \newcommand{\xyz}[1][x]{-#1!}
70 %\end{verbatim}
71 % where |\xyz| has an optional argument, then |\patchcmd| and siblings
72 % cannot be used to modify the workings of |\xyz|. The same happens
73 % when a command has been defined with |\DeclareRobustCommand|.
74 %
75 % The reason for this is \TeX{}nical or, better, \LaTeX{}nical. When
76 % \LaTeX{} performs the above definition, the expansion of |\xyz| will
77 % be
78 %\begin{verbatim}
79 % \@protected@testopt \xyz \\xyz {x}
80 %\end{verbatim}
81 % where |\@protected@testopt| is a macro that essentially checks
82 % whether we are in a ``protected'' context, so that expansion should
83 % not be performed all the way (in moving arguments or write
84 % operations), or not; in the former case it issues a protected
85 % version of |\xyz|, while in the latter case it expands the macro
86 % |\\xyz| that is a \emph{single} command (yes, with a backslash in
87 % its name) which contains the real definition; a way to access this
88 % definition is to issue the command
89 %\begin{verbatim}
90 % \expandafter\show\csname\string\xyz\endcsname
91 %\end{verbatim}
92 % which will print in the log file the message
93 %\begin{verbatim}
94 % > \\xyz=\long macro:
95 % [#1]->-#1!.
96 %\end{verbatim}
97 % As usual, after |->| we see the definition. In order to use
98 % |\patchcmd| to change the exclamation mark into a hyphen one must do
99 %\begin{verbatim}
100 % \expandafter\patchcmd\csname\string\xyz\endcsname{!}{-}{}{}
101 %\end{verbatim}
102 % (see the documentation of \pkg{etoolbox} for details about the
103 % arguments).
104 %
105 % A similar situation happens if |\xyz| has been defined by
106 %\begin{verbatim}
107 % \DeclareRobustCommand{\xyz}{something}
108 %\end{verbatim}
109 % A |\show\xyz| would show the cryptic
110 %\begin{verbatim}
111 % > \xyz=macro:
112 % ->\protect \xyz .
113 %\end{verbatim}
114 % and only a close look reveals the clever trick used by the \LaTeX{}
115 % team: the |\protect| is not applied to |\xyz|, but to the macro
116 % \verb*?\xyz ? which has a space at the end of its name! And this
117 % macro is the one that contains the real definition. Indeed,
118 %\begin{verbatim}
119 % \expandafter\show\csname xyz\space\endcsname
120 %\end{verbatim}
121 % produces the message
122 %\begin{verbatim}
123 % > \xyz =\long macro:
124 % ->something.
125 %\end{verbatim}
126 % In this case, in order to apply |\patchcmd| we must say
127 %\begin{verbatim}
128 % \expandafter\patchcmd\csname xyz\space\endcsname{s}{S}{}{}
129 %\end{verbatim}
130 % If the macro with |\DeclareRobustCommand| is defined to have an
131 % optional argument, say
132 %\begin{verbatim}
133 % \DeclareRobustCommand{\xyz}[1][x]{-#1!}
134 %\end{verbatim}
135 % one has to combine the two tricks:
136 %\begin{verbatim}
137 % \expandafter\patchcmd\csname\string\xyz\space\endcsname{!}{-}{}{}
138 %\end{verbatim}
139 % It's hard and error prone to remember all these tricks, so this
140 % package comes to the rescue.
141 %
142 % \subsection*{Caveat}
143 % This package is still in a preliminary version, but no relevant
144 % changes to the interface should be introduced in later versions. A
145 % different and more powerful implementation is under testing, see the
146 % package \pkg{regexpatch}.
147 %
148 %
149 % \section{Commands}
150 %
151 % The commands introduced by this package are
152 % \begin{itemize}
153 % \item |\xpatchcmd|
154 % \item |\xpretocmd|
155 % \item |\xapptocmd|
156 % \end{itemize}
157 % which have the same syntax as the similar commands provided by
158 % \pkg{etoolbox} and apply to all kind of commands defined by
159 % \begin{itemize}
160 % \item the \LaTeX{} kernel macros |\newcommand|, |\renewcommand|,
161 % |\providecommand|, but also |\newenvironment| and
162 % |\renewenvironment|;
163 % \item the \LaTeX{} kernel macro for defining robust commands
164 % |\DeclareRobustCommand|;
165 % \item the \pkg{etoolbox} macros |\newrobustcmd|, |\renewrobustcmd|,
166 % |\providerobustcmd|.
167 % \end{itemize}
168 % Notice that patching the definition of the environment |foo|
169 % requires patching |\foo| or |\endfoo|.
170 %
171 % These commands will act as the original ones if the macro to patch
172 % is not robust or with optional arguments.
173 %
174 % Moreover the package defines
175 % \begin{itemize}
176 % \item |\xpatchbibmacro|
177 % \item |\xpretobibmacro|
178 % \item |\xapptobibmacro|
179 % \end{itemize}
180 % that can be used to patch commands defined with \pkg{biblatex}'s
181 % |\newbibmacro|. Say that we have
182 %\begin{verbatim}
183 % \newbibmacro{foo.bar}[2]{#1 and #2}
184 %\end{verbatim}
185 % Then, to change |and| into |und|, we can now say
186 %\begin{verbatim}
187 % \xpatchbibmacro{foo.bar}{and}{und}{}{}
188 %\end{verbatim}
189 % \medskip
190 % \begin{lrbox}{0}
191 % \begin{minipage}{\dimexpr\textwidth-2\fboxsep-2\fboxrule\relax}
192 % \footnotesize
193 % Patching these macros requires resorting to the \emph{very} cryptic
194 %\begin{verbatim}
195 % \expandafter\patchcmd\csname abx@macro@\detokenize{foo.bar}\endcsname
196 % {and}{und}{}{}
197 %\end{verbatim}
198 % that would become an astonishing
199 %\begin{verbatim}
200 % \expandafter\patchcmd\csname\expandafter\string\csname
201 % abx@macro@\detokenize{foo.bar}\endcsname\endcsname
202 % {and}{und}{}{}
203 %\end{verbatim}
204 % if the original definition had been with an optional argument, say
205 %\begin{verbatim}
206 % \newbibmacro{foo.bar}[2][x]{#1 and #2}
207 %\end{verbatim}
208 % \end{minipage}
209 % \end{lrbox}
210 % \noindent\fbox{\usebox{0}}
211 %
212 % \medskip
213 %
214 % For \pkg{biblatex} users there are also
215 % \begin{itemize}
216 % \item |\xpatchbibdriver|
217 % \item |\xpretobibdriver|
218 % \item |\xapptobibdriver|
219 % \end{itemize}
220 % for patching commands defined with |\DeclareBibliographyDriver|. One
221 % could use, for patching the driver |foo|,
222 %\begin{verbatim}
223 % \makeatletter
224 % \patchcmd{\blx@bbx@foo}{X}{Y}{<success>}{<failure>}
225 % \preto{\blx@bbx@foo}{P}
226 % \appto{\blx@bbx@foo}{A}
227 % \makeatother
228 %\end{verbatim}
229 % but having a lighter interface can be handy. Since our macros use
230 % |\pretocmd| and |\apptocmd| for consistency, remember to always use
231 % the \marg{success} and \marg{failure} arguments also with
232 % |\xpretobibdriver| and |\xapptobibdriver|.
233 %
234 % Under the same philosophy, one can use the macros
235 % \begin{itemize}
236 % \item |\xpatchfieldformat|,\\ |\xpretofieldformat|,\\ |\xapptofieldformat|,
237 % \item |\xpatchnameformat|,\\ |\xpretonameformat|,\\ |\xapptonameformat|,
238 % \item |\xpatchlistformat|,\\ |\xpretonameformat|,\\ |\xapptonameformat|,
239 % \item |\xpatchindexfieldformat|,\\ |\xpretoindexfieldformat|,\\ |\xapptoindexfieldformat|,
240 % \item |\xpatchindexnameformat|,\\ |\xpretoindexnameformat|,\\ |\xapptoindexnameformat|,
241 % \item |\xpatchindexlistformat|,\\ |\xpretoindexlistformat|,\\ |\xapptoindexlistformat|,
242 % \end{itemize}
243 % for the \pkg{biblatex} internal macro defined respectively with
244 % \begin{flushleft}
245 % |\DeclareFieldFormat|,
246 % |\DeclareNameFormat|,
247 % |\DeclareListFormat|,\\
248 % |\DeclareIndexFieldFormat|,
249 % |\DeclareIndexNameFormat|,
250 % |\DeclareIndexListFormat|.
251 % \end{flushleft}
252 % All the eighteen |\x...format| commands take a first optional argument, with
253 % default value |*|, see later on.
254 %
255 %
256 % Finally, the package defines the commands
257 % \begin{itemize}
258 % \item |\xshowcmd|
259 % \item |\xshowbibmacro|
260 % \item |\xshowbibdriver|
261 % \item |\xshowfieldformat|
262 % \item |\xshownameformat|
263 % \item |\xshowlistformat|
264 % \item |\xshowindexfieldformat|
265 % \item |\xshowindexnameformat|
266 % \item |\xshowindexlistformat|
267 % \end{itemize}
268 % that are the analog of |\show| to see the ``real'' definition of a
269 % macro, be it defined with optional arguments or as a robust command;
270 % the |\xshowbib...| and |\xshow...format| ones are for the
271 % corresponding \pkg{biblatex} macros. The last six have an optional
272 % first argument (default value |*|).
273 %
274 %
275 % \section{Using the original commands}
276 %
277 % The original |\patchcmd| has still its use: suppose you want to
278 % modify the default for the optional argument passed to a macro: if
279 % the original definition is
280 %\begin{verbatim}
281 % \newcommand{\xyz}[1][x]{-#1!}
282 %\end{verbatim}
283 % then one can say
284 %\begin{verbatim}
285 % \patchcmd{\xyz}{{x}}{{y}}{}{}
286 %\end{verbatim}
287 % because of the way |\xyz| is defined, as shown before.
288 %
289 %
290 % \section{Syntax}
291 %
292 % |\xpatchcmd|\marg{command}\marg{search}\marg{replace}^^A
293 % \marg{success}\marg{failure}\\
294 % |\xpretocmd|\marg{command}\marg{prepend}^^A
295 % \marg{success}\marg{failure}\\
296 % |\xapptocmd|\marg{command}\marg{append}^^A
297 % \marg{success}\marg{failure}\\[\medskipamount]
298 % |\xpatchbibmacro|\marg{name}\marg{search}\marg{replace}^^A
299 % \marg{success}\marg{failure}\\
300 % |\xpretobibmacro|\marg{name}\marg{prepend}^^A
301 % \marg{success}\marg{failure}\\
302 % |\xapptobibmacro|\marg{name}\marg{append}^^A
303 % \marg{success}\marg{failure}\\[\medskipamount]
304 % |\xpatchbibdriver|\marg{name}\marg{search}\marg{replace}^^A
305 % \marg{success}\marg{failure}\\
306 % |\xpretobibdriver|\marg{name}\marg{prepend}^^A
307 % \marg{success}\marg{failure}\\
308 % |\xapptobibdriver|\marg{name}\marg{append}^^A
309 % \marg{success}\marg{failure}\\[\medskipamount]
310 % |\xpatchfieldformat|\oarg{entrytype}\marg{name}\marg{search}\marg{replace}^^A
311 % \marg{success}\marg{failure}\\
312 % |\xpretofieldformat|\oarg{entrytype}\marg{name}\marg{prepend}^^A
313 % \marg{success}\marg{failure}\\
314 % |\xapptofieldformat|\oarg{entrytype}\marg{name}\marg{append}^^A
315 % \marg{success}\marg{failure}\\[\medskipamount]
316 % |\xpatchnameformat|\oarg{entrytype}\marg{name}\marg{search}\marg{replace}^^A
317 % \marg{success}\marg{failure}\\
318 % |\xpretonameformat|\oarg{entrytype}\marg{name}\marg{prepend}^^A
319 % \marg{success}\marg{failure}\\
320 % |\xapptonameformat|\oarg{entrytype}\marg{name}\marg{append}^^A
321 % \marg{success}\marg{failure}\\[\medskipamount]
322 % |\xpatchlistformat|\oarg{entrytype}\marg{name}\marg{search}\marg{replace}^^A
323 % \marg{success}\marg{failure}\\
324 % |\xpretolistformat|\oarg{entrytype}\marg{name}\marg{prepend}^^A
325 % \marg{success}\marg{failure}\\
326 % |\xapptolistformat|\oarg{entrytype}\marg{name}\marg{append}^^A
327 % \marg{success}\marg{failure}\\[\medskipamount]
328 % |\xpatchindexfieldformat|\oarg{entrytype}\marg{name}\marg{search}\marg{replace}^^A
329 % \marg{success}\marg{failure}\\
330 % |\xpretoindexfieldformat|\oarg{entrytype}\marg{name}\marg{prepend}^^A
331 % \marg{success}\marg{failure}\\
332 % |\xapptoindexfieldformat|\oarg{entrytype}\marg{name}\marg{append}^^A
333 % \marg{success}\marg{failure}\\[\medskipamount]
334 % |\xpatchindexnameformat|\oarg{entrytype}\marg{name}\marg{search}\marg{replace}^^A
335 % \marg{success}\marg{failure}\\
336 % |\xpretoindexnameformat|\oarg{entrytype}\marg{name}\marg{prepend}^^A
337 % \marg{success}\marg{failure}\\
338 % |\xapptoindexnameformat|\oarg{entrytype}\marg{name}\marg{append}^^A
339 % \marg{success}\marg{failure}\\[\medskipamount]
340 % |\xpatchindexlistformat|\oarg{entrytype}\marg{name}\marg{search}\marg{replace}^^A
341 % \marg{success}\marg{failure}\\
342 % |\xpretoindexlistformat|\oarg{entrytype}\marg{name}\marg{prepend}^^A
343 % \marg{success}\marg{failure}\\
344 % |\xapptoindexlistformat|\oarg{entrytype}\marg{name}\marg{append}^^A
345 % \marg{success}\marg{failure}\\[\medskipamount]
346 % |\xshowcmd|\marg{command}\\
347 % |\xshowbibname|\marg{name}\\
348 % |\xshowbibdriver|\marg{name}\\
349 % |\xshowfieldformat|\oarg{entrytype}\marg{name}\\
350 % |\xshownameformat|\oarg{entrytype}\marg{name}\\
351 % |\xshowlistformat|\oarg{entrytype}\marg{name}\\
352 % |\xshowindexfieldformat|\oarg{entrytype}\marg{name}\\
353 % |\xshowindexnameformat|\oarg{entrytype}\marg{name}\\
354 % |\xshowindexlistformat|\oarg{entrytype}\marg{name}
355 %
356 % \medskip
357 %
358 % \begingroup\emergencystretch=.5\textwidth
359 % Here \meta{command} is the command's name (with the backslash),
360 % while \meta{name} is the string that appears as the argument to
361 % |\newbibmacro|, |\DeclareBibliographyDriver|, |\DeclareFieldFormat|,
362 % |\DeclareNameFormat|, |\DeclareListFormat|, |\DeclareIndexFieldFormat|,
363 % |\DeclareIndexNameFormat| or |\DeclareIndexListFormat| respectively;
364 % \meta{search}, \meta{replace}, \meta{prepend} and \meta{append} are
365 % the list of tokens that are to be used for the specific tasks;
366 % \meta{success} and \meta{failure} are token lists to be executed if
367 % the patching succeeds or fails respectively. I find it useful to use
368 % |\ddt| as \meta{failure}, so that \TeX{} will stop for the undefined
369 % control sequence when the patching fails.\par\endgroup
370 %
371 % All the |\x...format| macros have an optional argument that by
372 % default is |*|.
373 %
374 % It's important to remember that patching commands that have
375 % |@|-commands in their name or replacement text must always be
376 % performed between |\makeatletter| and |\makeatother|.
377 %
378 % \section{Limitations and warnings}
379 %
380 % Macros defined in devious ways might trick |\xpatchcmd| and
381 % siblings, although many precautions have been taken in order this
382 % not to happen. Always check with care.
383 %
384 % Remember that one must \emph{never} use the old trick
385 %\begin{verbatim}
386 % \let\ORIxyx\xyz
387 % \renewcommand{\xyz}[1][x]{+\ORIxyz[#1]?}
388 %\end{verbatim}
389 % if |\xyz| had been defined with an optional argument. For such
390 % things it's better to use |\xpatchcmd| and friends or employ the
391 % \pkg{letltxmacro} package by H.~Oberdiek, that provides
392 % |\LetLtxMacro| for purposes like this one.
393 %
394 % Although this package has been written with the experimental \LaTeX3
395 % macros, the commands \emph{can't} be used to patch commands defined
396 % with the \pkg{xparse} interface, in general.
397 %
398 % If a command appears to have one optional argument at the user
399 % level, this doesn't mean it has been defined with |\newcommand|
400 % directly. One should always check the definitions with |\show| and
401 % |\xshowcmd| before trying a patch: of course one has to know what a
402 % command does, in order to patch it. And, when first testing the
403 % patch, it's best to set |\tracingpatches|.
404 %
405 % \section{History}
406 %
407 % \begin{itemize}
408 % \item[Version 0.1] First public release.
409 % \item[Version 0.2] Added |\x...bibdriver| macros; fixed a bug for
410 % control symbols defined with |\newcommand| and an optional argument.
411 % \item[Version 0.3] Added |\x...format| macros (by kind request of the
412 % \pkg{biblatex} maintainers).
413 % \end{itemize}
414 %
415 % \end{documentation}
416 %
417 % \begin{implementation}
418 %
419 % \section{The implementation of \pkg{xpatch}}
420 %
421 % \iffalse
422 %<*package>
423 % \fi
424 %
425 %
426 % \begin{macrocode}
427 \ProvidesExplPackage
428 {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription}
429 % \end{macrocode}
430 %
431 % A check to make sure that \pkg{expl3} is not too old
432 % \begin{macrocode}
433 \@ifpackagelater { expl3 } { 2011/10/09 }
434 { }
435 {
436 \PackageError { xpatch } { Support~package~l3kernel~too~old. }
437 {
438 Please~install~an~up~to~date~version~of~l3kernel~
439 using~your~TeX~package~manager~or~from~CTAN.\\ \\
440 Loading~xpatch~will~abort!
441 }
442 \tex_endinput:D
443 }
444 % \end{macrocode}
445 %
446 % The \pkg{xparse} and \pkg{etoolbox} packages are required.
447 % \begin{macrocode}
448 \RequirePackage{xparse,etoolbox}
449 % \end{macrocode}
450 %
451 % \subsection{Utilities, variables and constants}
452 %
453 % Generate a variant of |\tl_if_in:NnT| to get the expanded second
454 % argument.
455 % \begin{macrocode}
456 \cs_generate_variant:Nn \tl_if_in:NnT { Nx }
457 % \end{macrocode}
458 % A boolean for the testing of robust commands.
459 % \begin{macrocode}
460 \bool_new:N \l__xpatch_protect_bool
461 % \end{macrocode}
462 % The constant |\c_backslash_str| is defined in |l3str| that's not
463 % loaded at the moment, so we save a bit of memory not loading it.
464 % \begin{macrocode}
465 \cs_if_exist:NF \c_backslash_str
466 { \tl_const:Nx \c_backslash_str { \cs_to_str:N \\ } }
467 % \end{macrocode}
468 % A ``bizarre'' token list that's quite improbable to find in the
469 % replacement text of a macro.
470 % \begin{macrocode}
471 \tl_const:Nx \c__xpatch_bizarre_tl
472 { \tl_to_str:n { **)-(**/**]-[** } }
473 % \end{macrocode}
474 % Internal token lists for storing the various parts of the command to be
475 % patched.
476 % \begin{macrocode}
477 \tl_new:N \l__xpatch_name_tl
478 \tl_new:N \l__xpatch_repl_tl
479 % \end{macrocode}
480 %
481 % \subsection{The main functions}
482 %
483 % The main function takes as first argument one of |\patchcmd|,
484 % |\pretocmd| or |\apptocmd|; the second argument is the command we
485 % want to patch.
486 %
487 % Some technical remarks. Suppose we have the following definitions:
488 %\begin{verbatim}
489 % \DeclareRobustCommand{\xaa}[1]{xaa (DeclareRobustCommand-noopt)}
490 % \DeclareRobustCommand{\xab}[1][x]{xab (DeclareRobustCommand-opt)}
491 % \newcommand{\xac}[1][]{xac (newcommand-opt)}
492 % \newrobustcmd\xad[1][]{xad (newrobustcmd-opt)}
493 % \DeclareRobustCommand{\1}[1]{1 (DeclareRobustCommand-noopt)}
494 % \DeclareRobustCommand{\2}[1][]{2 (DeclareRobustCommand-opt)}
495 % \newcommand{\3}[1][]{3 (newcommand-opt)}
496 % \newrobustcmd\4[1][]{4 (newrobustcmd-opt)}
497 %\end{verbatim}
498 % Then the first level expansions are, respectively,
499 % \iffalse
500 %<*mock>
501 % \fi
502 \begin{verbatim*}
503 +\protect \xaa +
504 +\protect \xab +
505 +\@protected@testopt \xac \\xac {}+
506 +\@testopt \\xad {}+
507 +\x@protect \1\protect \1 +
508 +\x@protect \2\protect \2 +
509 +\@protected@testopt \3\\3 {}+
510 +\@testopt \\4 {}+
511 \end{verbatim*}
512 % \iffalse
513 %</mock>
514 % \fi
515 % where the |+| is used to delimit the expansions and show the
516 % spaces. Remember that |\show| always adds a space after a control
517 % word, but not after a control symbol such as |\1|. However, in lines
518 % 5~and~6, \verb*?\1 ? is not a control symbol any more. So we have to
519 % take care of |\protect|, |\x@protect|, |\@protected@testopt| and
520 % |\@testopt|. But it's not simply sufficient to check for the
521 % presence of such a token at the start of the replacement text, or
522 % we'll be confused by macros such as |\linebreak|, whose replacement
523 % text starts with |\@testopt|. So we'll check also for the presence of
524 % the subsequent tokens, that depend on the macro's name. We add a
525 % perhaps useless ``random'' string at the beginning, as we'd like to
526 % ensure that the matches are exactly at the start of the replacement
527 % text.
528 % \begin{macrocode}
529 \cs_new:Npn \xpatch_main:NN #1 #2
530 {
531 % \end{macrocode}
532 % We initialize the boolean to false.
533 % \begin{macrocode}
534 \bool_set_false:N \l__xpatch_protect_bool
535 % \end{macrocode}
536 % First of all we store the command-to-patch name.
537 % \begin{macrocode}
538 \tl_set:Nx \l__xpatch_name_tl { \cs_to_str:N #2 }
539 % \end{macrocode}
540 % We store the replacement text of the command-to-patch, but adding
541 % the bizarre token list in front of it which consists of all category
542 % 12 characters, just to be sure that the matches are at the
543 % beginning.\footnote{This part will be reimplemented as soon as
544 % \pkg{l3regex} stabilizes.}
545 % \begin{macrocode}
546 \tl_set:Nx \l__xpatch_repl_tl
547 { \c__xpatch_bizarre_tl \cs_replacement_spec:N #2 }
548 % \end{macrocode}
549 % We look whether the token list contains the bizarre list followed by
550 % |\protect| and the same name (with two spaces) which happens if |#2|
551 % is a control sequence defined by |\DeclareRobustCommand|, so we add
552 % a space to the command name.
553 % \begin{macrocode}
554 \tl_if_in:NxT \l__xpatch_repl_tl
555 {
556 \c__xpatch_bizarre_tl
557 \token_to_str:N \protect \c_space_tl
558 \c_backslash_str \l__xpatch_name_tl \c_space_tl \c_space_tl
559 }
560 {
561 \bool_set_true:N \l__xpatch_protect_bool
562 \tl_put_right:Nn \l__xpatch_name_tl { \c_space_tl }
563 }
564 % \end{macrocode}
565 % We look whether the token list contains the bizarre list followed by
566 % |\x@protect| which happens if |#2| is a control symbol defined by
567 % |\DeclareRobustCommand|, so we add a space to the command name.
568 % \begin{macrocode}
569 \tl_if_in:NxT \l__xpatch_repl_tl
570 {
571 \c__xpatch_bizarre_tl
572 \token_to_str:N \x@protect \c_space_tl
573 \c_backslash_str \l__xpatch_name_tl \c_backslash_str
574 }
575 {
576 \bool_set_true:N \l__xpatch_protect_bool
577 \tl_put_right:Nn \l__xpatch_name_tl { \c_space_tl }
578 }
579 % \end{macrocode}
580 % In both the preceding cases we have to do another check, so we set a
581 % boolean to true.
582 %
583 % We look whether the token list contains the bizarre list followed by
584 % |\@protected@testopt| which happens if |#2| is a control word with an
585 % optional argument (from |\newcommand|).
586 % \begin{macrocode}
587 \tl_if_in:NxT \l__xpatch_repl_tl
588 {
589 \c__xpatch_bizarre_tl
590 \token_to_str:N \@protected@testopt \c_space_tl
591 \c_backslash_str \l__xpatch_name_tl
592 \c_space_tl \c_backslash_str \c_backslash_str
593 }
594 {
595 \tl_put_left:Nn \l__xpatch_name_tl { \c_backslash_str }
596 }
597 % \end{macrocode}
598 % We look whether the token list contains the bizarre list followed by
599 % |\@protected@testopt| which happens if |#2| is a control symbol with an
600 % optional argument (from |\newcommand|).
601 % \begin{macrocode}
602 \tl_if_in:NxT \l__xpatch_repl_tl
603 {
604 \c__xpatch_bizarre_tl
605 \token_to_str:N \@protected@testopt \c_space_tl
606 \c_backslash_str \l__xpatch_name_tl
607 \c_backslash_str \c_backslash_str
608 }
609 {
610 \tl_put_left:Nn \l__xpatch_name_tl { \c_backslash_str }
611 }
612 % \end{macrocode}
613 % We look whether the token list contains the bizarre list followed by
614 % |\@testopt| which happens if |#2| is a command with an optional
615 % argument (from |\newrobustcmd|).
616 % \begin{macrocode}
617 \tl_if_in:NxT \l__xpatch_repl_tl
618 {
619 \c__xpatch_bizarre_tl
620 \token_to_str:N \@testopt \c_space_tl
621 \c_backslash_str \c_backslash_str \l__xpatch_name_tl
622 }
623 {
624 \tl_put_left:Nn \l__xpatch_name_tl { \c_backslash_str }
625 }
626 % \end{macrocode}
627 % In both the preceding cases, we add a backslash in front of the
628 % command's name.
629 %
630 % If the command-to-patch was defined by |\DeclareRobustCommand| we
631 % have to do another test, namely checking whether it has an optional
632 % argument and, in this case, adding a backslash in front of the name.
633 % We replicate the test for |\@protected@testopt|.
634 % \begin{macrocode}
635 \bool_if:NT \l__xpatch_protect_bool
636 {
637 \tl_set:Nx \l__xpatch_repl_tl
638 { \c__xpatch_bizarre_tl
639 \exp_after:wN \cs_replacement_spec:N
640 \cs:w \l__xpatch_name_tl \cs_end: }
641 \tl_if_in:NxT \l__xpatch_repl_tl
642 {
643 \c__xpatch_bizarre_tl
644 \token_to_str:N \@protected@testopt \c_space_tl
645 \c_backslash_str \l__xpatch_name_tl
646 \c_space_tl \c_backslash_str \c_backslash_str
647 }
648 {
649 \tl_put_left:Nn \l__xpatch_name_tl { \c_backslash_str }
650 }
651 }
652 % \end{macrocode}
653 % Finally, we pass the real command-to-patch name to the patching
654 % macro.
655 % \begin{macrocode}
656 \exp_after:wN #1 \cs:w \l__xpatch_name_tl \cs_end:
657 % \end{macrocode}
658 % That's the last operation!
659 % \begin{macrocode}
660 }
661 % \end{macrocode}
662 %
663 % \subsection{User level commands}
664 %
665 % The user level commands.
666 % \begin{macrocode}
667 \NewDocumentCommand{\xpatchcmd}{}{ \xpatch_main:NN \patchcmd }
668 \NewDocumentCommand{\xpretocmd}{}{ \xpatch_main:NN \pretocmd }
669 \NewDocumentCommand{\xapptocmd}{}{ \xpatch_main:NN \apptocmd }
670 \NewDocumentCommand{\xshowcmd} {}{ \xpatch_main:NN \show }
671 % \end{macrocode}
672 %
673 % We generate a variant of |\xpatch_main:NN| to accept a macro's name
674 % as its second argument.
675 % \begin{macrocode}
676 \cs_generate_variant:Nn \xpatch_main:NN { Nc }
677 % \end{macrocode}
678 %
679 % Now we can define the patching macros for |\newbibmacro| defined
680 % commands. In case one uses a wrong name, it will remain in the hash
681 % space, but it shouldn't be a problem: |\tracingpatches| must be used
682 % when testing, and it will warn about an undefined macro or one
683 % equivalent to |\relax|.
684 % \begin{macrocode}
685 \NewDocumentCommand{\xpatchbibmacro} { m }
686 { \xpatch_main:Nc \patchcmd { abx@macro@ \tl_to_str:n {#1} } }
687 \NewDocumentCommand{\xpretobibmacro} { m }
688 { \xpatch_main:Nc \pretocmd { abx@macro@ \tl_to_str:n {#1} } }
689 \NewDocumentCommand{\xapptobibmacro} { m }
690 { \xpatch_main:Nc \apptocmd { abx@macro@ \tl_to_str:n {#1} } }
691 \NewDocumentCommand{\xshowbibmacro} { m }
692 { \xpatch_main:Nc \show { abx@macro@ \tl_to_str:n {#1} } }
693 % \end{macrocode}
694 %
695 % The macros for patching commands defined with |\DeclareFieldFormat|;
696 % all that holds for the preceding commands is valid also for the
697 % following groups of similar commands.
698 % \begin{macrocode}
699 \NewDocumentCommand{\xpatchfieldformat} { O{*} m }
700 { \xpatch_main:Nc \patchcmd { abx@ffd@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
701 \NewDocumentCommand{\xpretofieldformat} { O{*} m }
702 { \xpatch_main:Nc \pretocmd { abx@ffd@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
703 \NewDocumentCommand{\xapptofieldformat} { O{*} m }
704 { \xpatch_main:Nc \apptocmd { abx@ffd@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
705 \NewDocumentCommand{\xshowfieldformat} { O{*} m }
706 { \xpatch_main:Nc \show { abx@ffd@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
707 % \end{macrocode}
708 % |\DeclareNameFormat|:
709 % \begin{macrocode}
710 \NewDocumentCommand{\xpatchnameformat} { O{*} m }
711 { \xpatch_main:Nc \patchcmd { abx@nfd@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
712 \NewDocumentCommand{\xpretonameformat} { O{*} m }
713 { \xpatch_main:Nc \pretocmd { abx@nfd@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
714 \NewDocumentCommand{\xapptonameformat} { O{*} m }
715 { \xpatch_main:Nc \apptocmd { abx@nfd@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
716 \NewDocumentCommand{\xshownameformat} { O{*} m }
717 { \xpatch_main:Nc \show { abx@ffd@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
718 % \end{macrocode}
719 % |\DeclareListFormat|:
720 % \begin{macrocode}
721 \NewDocumentCommand{\xpatchlistformat} { O{*} m }
722 { \xpatch_main:Nc \patchcmd { abx@lfd@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
723 \NewDocumentCommand{\xpretolistformat} { O{*} m }
724 { \xpatch_main:Nc \pretocmd { abx@lfd@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
725 \NewDocumentCommand{\xapptolistformat} { O{*} m }
726 { \xpatch_main:Nc \apptocmd { abx@lfd@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
727 \NewDocumentCommand{\xshowlistformat} { O{*} m }
728 { \xpatch_main:Nc \show { abx@lfd@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
729 % \end{macrocode}
730 % |\DeclareIndexFieldFormat|;
731 % \begin{macrocode}
732 \NewDocumentCommand{\xpatchindexfieldformat} { O{*} m }
733 { \xpatch_main:Nc \patchcmd { abx@fid@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
734 \NewDocumentCommand{\xpretoindexfieldformat} { O{*} m }
735 { \xpatch_main:Nc \pretocmd { abx@fid@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
736 \NewDocumentCommand{\xapptoindexfieldformat} { O{*} m }
737 { \xpatch_main:Nc \apptocmd { abx@fid@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
738 \NewDocumentCommand{\xshowindexfieldformat} { O{*} m }
739 { \xpatch_main:Nc \show { abx@fid@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
740 % \end{macrocode}
741 % |\DeclareIndexNameFormat|:
742 % \begin{macrocode}
743 \NewDocumentCommand{\xpatchindexnameformat} { O{*} m }
744 { \xpatch_main:Nc \patchcmd { abx@nid@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
745 \NewDocumentCommand{\xpretoindexnameformat} { O{*} m }
746 { \xpatch_main:Nc \pretocmd { abx@nid@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
747 \NewDocumentCommand{\xapptoindexnameformat} { O{*} m }
748 { \xpatch_main:Nc \apptocmd { abx@nid@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
749 \NewDocumentCommand{\xshowindexnameformat} { O{*} m }
750 { \xpatch_main:Nc \show { abx@nid@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
751 % \end{macrocode}
752 % |\DeclareIndexListFormat|:
753 % \begin{macrocode}
754 \NewDocumentCommand{\xpatchindexlistformat} { O{*} m }
755 { \xpatch_main:Nc \patchcmd { abx@lid@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
756 \NewDocumentCommand{\xpretoindexlistformat} { O{*} m }
757 { \xpatch_main:Nc \pretocmd { abx@lid@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
758 \NewDocumentCommand{\xappindextolistformat} { O{*} m }
759 { \xpatch_main:Nc \apptocmd { abx@lid@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
760 \NewDocumentCommand{\xshowindexlistformat} { O{*} m }
761 { \xpatch_main:Nc \show { abx@lid@ \tl_to_str:n {#1} @ \tl_to_str:n {#2} } }
762 % \end{macrocode}
763 %
764 % Finally, the patching macros for \pkg{biblatex} drivers that don't
765 % need the overhead of |\xpatch_main:NN|.
766 % \begin{macrocode}
767 \NewDocumentCommand{\xpatchbibdriver} { m }
768 { \exp_args:Nc \patchcmd {blx@bbx@#1} }
769 \NewDocumentCommand{\xpretobibdriver} { m }
770 { \exp_args:Nc \pretocmd {blx@bbx@#1} }
771 \NewDocumentCommand{\xapptobibdriver} { m }
772 { \exp_args:Nc \apptocmd {blx@bbx@#1} }
773 \NewDocumentCommand{\xshowbibdriver} { m }
774 { \exp_args:Nc \show {blx@bbx@#1} }
775 % \end{macrocode}
776 % \iffalse
777 %</package>
778 % \fi
779 % \end{implementation}
780 %
781 % \PrintIndex
782 % \PrintChanges