diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/xpatch/xpatch.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/xpatch/xpatch.dtx | 614 |
1 files changed, 614 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/xpatch/xpatch.dtx b/Master/texmf-dist/source/latex/xpatch/xpatch.dtx new file mode 100644 index 00000000000..4f2d2e22f32 --- /dev/null +++ b/Master/texmf-dist/source/latex/xpatch/xpatch.dtx @@ -0,0 +1,614 @@ +% \iffalse meta-comment +% +%% File: xpatch.dtx (C) Copyright 2012 Enrico Gregorio +%% +%% It may be distributed and/or modified under the conditions of the +%% LaTeX Project Public License (LPPL), either version 1.3c of this +%% license or (at your option) any later version. The latest version +%% of this license is in the file +%% +%% http://www.latex-project.org/lppl.txt +%% +%% This file is part of the "xpatch bundle" (The Work in LPPL) +%% and all files in that bundle must be distributed together. +%% +%% The released version of this bundle is available from CTAN. +%% +% +%<*driver|package> +\RequirePackage{expl3} +%</driver|package> +%<*driver> +\expandafter\def\csname ver@thumbpdf.sty\endcsname{} +\documentclass[a4paper,full]{l3doc} +\usepackage{bookmark} +%</driver> +%<*driver|package> +\GetIdInfo$Id: xpatch.dtx 0.2 2012-01-23 12:00:00Z Enrico $ + {Extending etoolbox patching commands} +%</driver|package> +%<*driver> +\begin{document} + \DocInput{\jobname.dtx} +\end{document} +%</driver> +% \fi +% +% \title{^^A +% The \textsf{xpatch} package\\ Extending \textsf{etoolbox} patching +% commands^^A +% \thanks{This file describes version \ExplFileVersion, +% last revised \ExplFileDate.}^^A +% } +% +% \author{^^A +% Enrico Gregorio\thanks +% {^^A +% E-mail: +% Enrico DOT Gregorio AT univr DOT it^^A +% }^^A +% } +% +% \date{Released \ExplFileDate} +% +% \maketitle +% +% \begin{documentation} +% +% \section{Introduction} +% +% The well known \pkg{etoolbox} package provides a bunch of functions +% for patching existing commands; in particular |\patchcmd|, +% |\pretocmd| and |\apptocmd| that do a wonderful job, but suffer from +% a limitation: if some package has defined +%\begin{verbatim} +% \newcommand{\xyz}[1][x]{-#1!} +%\end{verbatim} +% where |\xyz| has an optional argument, then |\patchcmd| and siblings +% cannot be used to modify the workings of |\xyz|. The same happens +% when a command has been defined with |\DeclareRobustCommand|. +% +% The reason for this is \TeX{}nichal or, better, \LaTeX{}nichal. When +% \LaTeX{} performs the above definition, the expansion of |\xyz| will +% be +%\begin{verbatim} +% \@protected@testopt \xyz \\xyz {x} +%\end{verbatim} +% where |\@protected@testopt| is a macro that essentially checks +% whether we are in a ``protected'' context, so that expansion should +% not be performed all the way (in moving arguments or write +% operations), or not; in the former case it issues a protected +% version of |\xyz|, while in the latter case it expands the macro +% |\\xyz| that is a \emph{single} command (yes, with a backslash in +% its name) which contains the real definition; a way to access this +% definition is to issue the command +%\begin{verbatim} +% \expandafter\show\csname\string\xyz\endcsname +%\end{verbatim} +% which will print in the log file the message +%\begin{verbatim} +% > \\xyz=\long macro: +% [#1]->-#1!. +%\end{verbatim} +% As usual, after |->| we see the definition. In order to use +% |\patchcmd| to change the exclamation mark into a hyphen one must do +%\begin{verbatim} +% \expandafter\patchcmd\csname\string\xyz\endcsname{!}{-}{}{} +%\end{verbatim} +% (see the documentation of \pkg{etoolbox} for details about the +% arguments). +% +% A similar situation happens if |\xyz| has been defined by +%\begin{verbatim} +% \DeclareRobustCommand{\xyz}{something} +%\end{verbatim} +% A |\show\xyz| would show the cryptic +%\begin{verbatim} +% > \xyz=macro: +% ->\protect \xyz . +%\end{verbatim} +% and only a close look reveals the clever trick used by the \LaTeX{} +% team: the |\protect| is not applied to |\xyz|, but to the macro +% \verb*?\xyz ? which has a space at the end of its name! And this +% macro is the one that contains the real definition. Indeed, +%\begin{verbatim} +% \expandafter\show\csname xyz\space\endcsname +%\end{verbatim} +% produces the message +%\begin{verbatim} +% > \xyz =\long macro: +% ->something. +%\end{verbatim} +% In this case, in order to apply |\patchcmd| we must say +%\begin{verbatim} +% \expandafter\patchcmd\csname xyz\space\endcsname{s}{S}{}{} +%\end{verbatim} +% If the macro with |\DeclareRobustCommand| is defined to have an +% optional argument, say +%\begin{verbatim} +% \DeclareRobustCommand{\xyz}[1][x]{-#1!} +%\end{verbatim} +% one has to combine the two tricks: +%\begin{verbatim} +% \expandafter\patchcmd\csname\string\xyz\space\endcsname{!}{-}{}{} +%\end{verbatim} +% It's hard and error prone to remember all of these tricks, so this +% package comes to the rescue. +% +% \subsection*{Caveat} +% This package is still in a preliminary version, but relevant changes +% to the interface should not be introduced in later versions. A +% ``verbose'' mode is under testing, which will provide at request +% more information about the nature of the command to be patched. +% +% +% \section{Commands} +% +% The commands introduced by this package are +% \begin{itemize} +% \item |\xpatchcmd| +% \item |\xpretocmd| +% \item |\xapptocmd| +% \end{itemize} +% which have the same syntax as the similar commands provided by +% \pkg{etoolbox} and apply to all kind of commands defined by +% \begin{itemize} +% \item the \LaTeX{} kernel macros |\newcommand|, |\renewcommand|, +% |\providecommand|, but also |\newenvironment| and +% |\renewenvironment|; +% \item the \LaTeX{} kernel macro for defining robust commands +% |\DeclareRobustCommand|; +% \item the \pkg{etoolbox} macros |\newrobustcmd|, |\renewrobustcmd|, +% |\providerobustcmd|. +% \end{itemize} +% Notice that patching the definition of the environment |foo| +% requires patching |\foo| or |\endfoo|. +% +% These commands will act as the original ones if the macro to patch +% is not robust or with optional arguments. +% +% Moreover the package defines +% \begin{itemize} +% \item |\xpatchbibmacro| +% \item |\xpretobibmacro| +% \item |\xapptobibmacro| +% \end{itemize} +% that can be used to patch commands defined with \pkg{biblatex}'s +% |\newbibmacro|. Say that we have +%\begin{verbatim} +% \newbibmacro{foo.bar}[2]{#1 and #2} +%\end{verbatim} +% Then, to change |and| into |und|, we can now say +%\begin{verbatim} +% \xpatchbibmacro{foo.bar}{and}{und}{}{} +%\end{verbatim} +% \medskip +% \begin{lrbox}{0} +% \begin{minipage}{\dimexpr\textwidth-2\fboxsep-2\fboxrule\relax} +% \footnotesize +% Patching these macros requires resorting to the \emph{very} cryptic +%\begin{verbatim} +% \expandafter\patchcmd\csname abx@macro@\detokenize{foo.bar}\endcsname +% {and}{und}{}{} +%\end{verbatim} +% that would become an astonishing +%\begin{verbatim} +% \expandafter\patchcmd\csname\expandafter\string\csname +% abx@macro@\detokenize{foo.bar}\endcsname\endcsname +% {and}{und}{}{} +%\end{verbatim} +% if the original definition had been with an optional argument, say +%\begin{verbatim} +% \newbibmacro{foo.bar}[2][x]{#1 and #2} +%\end{verbatim} +% \end{minipage} +% \end{lrbox} +% \noindent\fbox{\usebox{0}} +% +% \medskip +% +% For \pkg{biblatex} users there are also +% \begin{itemize} +% \item |\xpatchbibdriver| +% \item |\xpretobibdriver| +% \item |\xapptobibdriver| +% \end{itemize} +% for patching commands defined with |\DeclareBibliographyDriver|. One +% could use, for patching the driver |foo|, +%\begin{verbatim} +% \makeatletter +% \patchcmd{\blx@bbx@foo}{X}{Y}{success}{failure} +% \preto{\blx@bbx@foo}{P} +% \appto{\blx@bbx@foo}{A} +% \makeatother +%\end{verbatim} +% but having a lighter interface can be handy. Since our macros use +% |\pretocmd| and |\apptocmd| for consistency, remember to always use +% the |{success}| and |{failure}| arguments also with +% |\xpretobibdriver| and |\xapptobibdriver|. +% +% Finally, the package defines the commands +% \begin{itemize} +% \item |\xshowcmd| +% \item |\xshowbibmacro| +% \item |\xshowbibdriver| +% \end{itemize} +% that are the analog of |\show| to see the ``real'' definition of a +% macro, be it defined with optional arguments or as a robust command; +% the |bib| ones are for the corresponding \pkg{biblatex} macros. +% +% +% \section{Using the original commands} +% +% The original |\patchcmd| has still its use: suppose you want to +% modify the default for the optional argument passed to a macro: if +% the original definition is +%\begin{verbatim} +% \newcommand{\xyz}[1][x]{-#1!} +%\end{verbatim} +% then one can say +%\begin{verbatim} +% \patchcmd{\xyz}{{x}}{{y}}{}{} +%\end{verbatim} +% because of the way |\xyz| is defined, as shown before. +% +% +% \section{Syntax} +% +% |\xpatchcmd|\marg{command}\marg{search}\marg{replace}^^A +% \marg{success}\marg{failure}\\ +% |\xpretocmd|\marg{command}\marg{prepend}^^A +% \marg{success}\marg{failure}\\ +% |\xapptocmd|\marg{command}\marg{append}^^A +% \marg{success}\marg{failure}\\[\medskipamount] +% |\xpatchbibmacro|\marg{name}\marg{search}\marg{replace}^^A +% \marg{success}\marg{failure}\\ +% |\xpretobibmacro|\marg{name}\marg{prepend}^^A +% \marg{success}\marg{failure}\\ +% |\xapptobibmacro|\marg{name}\marg{append}^^A +% \marg{success}\marg{failure}\\[\medskipamount] +% |\xpatchbibdriver|\marg{name}\marg{search}\marg{replace}^^A +% \marg{success}\marg{failure}\\ +% |\xpretobibdriver|\marg{name}\marg{prepend}^^A +% \marg{success}\marg{failure}\\ +% |\xapptobibdriver|\marg{name}\marg{append}^^A +% \marg{success}\marg{failure}\\[\medskipamount] +% |\xshowcmd|\marg{command}\\ +% |\xshowbibname|\marg{name}\\ +% |\xshowbibdriver|\marg{name} +% +% \medskip +% +% Here \meta{command} is the command's name (with the backslash), +% while \meta{name} is the string that appears as the argument to +% |\newbibmacro| or |\DeclareBibliographyDriver| respectively; +% \meta{search}, \meta{replace}, \meta{prepend} and \meta{append} are +% the list of tokens that are to be used for the specific tasks; +% \meta{success} and \meta{failure} are token lists to be executed if +% the patching succeeds or fails respectively. I find it useful to use +% |\ddt| as \meta{failure}, so that \TeX{} will stop for the undefined +% control sequence when the patching fails. +% +% It's important to remember that patching commands that have +% |@|-commands in their replacement text must always be performed +% between |\makeatletter| and |\makeatother|. +% +% \section{Limitations and warnings} +% +% Macros defined in devious ways might trick |\xpatchcmd| and +% siblings, although many precautions have been taken in order this +% not to happen. Always check with care. +% +% Remember that one must \emph{never} use the old trick +%\begin{verbatim} +% \let\ORIxyx\xyz +% \renewcommand{\xyz}[1][x]{+\ORIxyz[#1]?} +%\end{verbatim} +% if |\xyz| had been defined with an optional argument. For such +% things it's better to use |\xpatchcmd| and friends or employ the +% \pkg{letltxmacro} package by H.~Oberdiek, that provides +% |\LetLtxMacro| for purposes like this. +% +% Although this package has been written with the experimental \LaTeX3 +% macros, the commands \emph{can't} be used to patch commands defined +% with the \pkg{xparse} interface, in general. +% +% If a command appears to have one optional argument at the user +% level, this doesn't mean it has been defined with |\newcommand| +% directly. One should always check the definitions with |\show| and +% |\xshowcmd| before trying a patch: of course one has to know what a +% command does, in order to patch it. And, when first testing the +% patch, it's best to set |\tracingpatches|. +% +% \section{History} +% +% \begin{itemize} +% \item[Version 0.1] First public release. +% \item[Version 0.2] Added |\...bibdriver| macros; fixed a bug for +% control symbols defined with |\newcommand| and an optional argument. +% \end{itemize} +% +% \end{documentation} +% +% \begin{implementation} +% +% \section{The implementation of \pkg{xpatch}} +% +% \iffalse +%<*package> +% \fi +% +% +% \begin{macrocode} +\ProvidesExplPackage + {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription} +% \end{macrocode} +% +% A check to make sure that \pkg{expl3} is not too old +% \begin{macrocode} +\@ifpackagelater { expl3 } { 2011/10/09 } + { } + { + \PackageError { xpatch } { Support~package~l3kernel~too~old. } + { + Please~install~an~up~to~date~version~of~l3kernel~ + using~your~TeX~package~manager~or~from~CTAN.\\ \\ + Loading~xpatch~will~abort! + } + \tex_endinput:D + } +% \end{macrocode} +% +% The \pkg{xparse} and \pkg{etoolbox} packages are required. +% \begin{macrocode} +\RequirePackage{xparse,etoolbox} +% \end{macrocode} +% +% \subsection{Utilities, variables and constants} +% +% Generate a variant of |\tl_if_in:NnT| to get the expanded second +% argument. +% \begin{macrocode} +\cs_generate_variant:Nn \tl_if_in:NnT { Nx } +% \end{macrocode} +% A boolean for the testing of robust commands. +% \begin{macrocode} +\bool_new:N \l_xpatch_protect_bool +% \end{macrocode} +% The constant |\c_backslash_str| is defined in |l3str| that's not +% loaded at the moment, so we save a bit of memory not loading it. +% \begin{macrocode} +\cs_if_exist:NF \c_backslash_str + { \tl_const:Nx \c_backslash_str { \cs_to_str:N \\ } } +% \end{macrocode} +% A ``bizarre'' token list that's quite improbable to find in the +% replacement text of a macro. +% \begin{macrocode} +\tl_const:Nx \c_xpatch_bizarre_tl + { \tl_to_str:n { **)-(**/**]-[** } } +% \end{macrocode} +% +% \subsection{The main functions} +% +% The main function takes as first argument one of |\patchcmd|, +% |\pretocmd| or |\apptocmd|; the second argument is the command we +% want to patch. +% +% Some technical remarks. Suppose we have the following definitions: +%\begin{verbatim} +% \DeclareRobustCommand{\xaa}[1]{xaa (DeclareRobustCommand-noopt)} +% \DeclareRobustCommand{\xab}[1][x]{xab (DeclareRobustCommand-opt)} +% \newcommand{\xac}[1][]{xac (newcommand-opt)} +% \newrobustcmd\xad[1][]{xad (newrobustcmd-opt)} +% \DeclareRobustCommand{\1}[1]{1 (DeclareRobustCommand-noopt)} +% \DeclareRobustCommand{\2}[1][]{2 (DeclareRobustCommand-opt)} +% \newcommand{\3}[1][]{3 (newcommand-opt)} +% \newrobustcmd\4[1][]{4 (newrobustcmd-opt)} +%\end{verbatim} +% Then the first level expansions are, respectively, +%\begin{verbatim*} +%+\protect \xaa + +%+\protect \xab + +%+\@protected@testopt \xac \\xac {}+ +%+\@testopt \\xad {}+ +%+\x@protect \1\protect \1 + +%+\x@protect \2\protect \2 + +%+\@protected@testopt \3\\3 {}+ +%+\@testopt \\4 {}+ +%\end{verbatim*} +% where the |+| is used to delimit the expansions and show the +% spaces. Remember that |\show| always adds a space after a control +% word, but not after a control symbol such as |\1|. However, in lines +% 5~and~6, \verb*?\1 ? is not a control symbol any more. So we have to +% take care of |\protect|, |\x@protect|, |\@protected@testopt| and +% |\@testopt|. But it's not simply sufficient to check for the +% presence of such a token at the start of the replacement text, or +% we'll be confused by macros such as |\linebreak|, whose replacement +% text starts with |\@testopt|. So we'll check also for the presence of +% the subsequent tokens, that depend on the macro's name. We add a +% perhaps useless ``random'' string at the beginning, as we'd like to +% ensure that the matches are exactly at the start of the replacement +% text. +% \begin{macrocode} +\cs_new:Npn \xpatch_main:NN #1 #2 + { +% \end{macrocode} +% We initialize the boolean to false. +% \begin{macrocode} + \bool_set_false:N \l_xpatch_protect_bool +% \end{macrocode} +% First of all we store the command-to-patch name. +% \begin{macrocode} + \tl_set:Nx \l_xpatch_name_tl { \cs_to_str:N #2 } +% \end{macrocode} +% We store the replacement text of the command-to-patch, but adding +% the bizarre token list in front of it which consists of all category +% 12 characters, just to be sure that the matches are at the +% beginning.\footnote{This part will be reimplemented as soon as +% \pkg{l3regex} stabilizes.} +% \begin{macrocode} + \tl_set:Nx \l_xpatch_repl_tl + { \c_xpatch_bizarre_tl \token_get_replacement_spec:N #2 } +% \end{macrocode} +% We look whether the token list contains the bizarre list followed by +% |\protect| and the same name (with two spaces) which happens if |#2| +% is a control sequence defined by |\DeclareRobustCommand|, so we add +% a space to the command name. +% \begin{macrocode} + \tl_if_in:NxT \l_xpatch_repl_tl + { + \c_xpatch_bizarre_tl + \token_to_str:N \protect \c_space_tl + \c_backslash_str \l_xpatch_name_tl \c_space_tl \c_space_tl + } + { + \bool_set_true:N \l_xpatch_protect_bool + \tl_put_right:Nn \l_xpatch_name_tl { \c_space_tl } + } +% \end{macrocode} +% We look whether the token list contains the bizarre list followed by +% |\x@protect| which happens if |#2| is a control symbol defined by +% |\DeclareRobustCommand|, so we add a space to the command name. +% \begin{macrocode} + \tl_if_in:NxT \l_xpatch_repl_tl + { + \c_xpatch_bizarre_tl + \token_to_str:N \x@protect \c_space_tl + \c_backslash_str \l_xpatch_name_tl \c_backslash_str + } + { + \bool_set_true:N \l_xpatch_protect_bool + \tl_put_right:Nn \l_xpatch_name_tl { \c_space_tl } + } +% \end{macrocode} +% In both the preceding cases we have to do another check, so we set a +% boolean to true. +% +% We look whether the token list contains the bizarre list followed by +% |\@protected@testopt| which happens if |#2| is a control word with an +% optional argument (from |\newcommand|). +% \begin{macrocode} + \tl_if_in:NxT \l_xpatch_repl_tl + { + \c_xpatch_bizarre_tl + \token_to_str:N \@protected@testopt \c_space_tl + \c_backslash_str \l_xpatch_name_tl + \c_space_tl \c_backslash_str \c_backslash_str + } + { + \tl_put_left:Nn \l_xpatch_name_tl { \c_backslash_str } + } +% We look whether the token list contains the bizarre list followed by +% |\@protected@testopt| which happens if |#2| is a control symbol with an +% optional argument (from |\newcommand|). +% \begin{macrocode} + \tl_if_in:NxT \l_xpatch_repl_tl + { + \c_xpatch_bizarre_tl + \token_to_str:N \@protected@testopt \c_space_tl + \c_backslash_str \l_xpatch_name_tl + \c_backslash_str \c_backslash_str + } + { + \tl_put_left:Nn \l_xpatch_name_tl { \c_backslash_str } + } +% \end{macrocode} +% We look whether the token list contains the bizarre list followed by +% |\@testopt| which happens if |#2| is a command with an optional +% argument (from |\newrobustcmd|). +% \begin{macrocode} + \tl_if_in:NxT \l_xpatch_repl_tl + { + \c_xpatch_bizarre_tl + \token_to_str:N \@testopt \c_space_tl + \c_backslash_str \c_backslash_str \l_xpatch_name_tl + } + { + \tl_put_left:Nn \l_xpatch_name_tl { \c_backslash_str } + } +% \end{macrocode} +% In both the preceding cases, we add a backslash in front of the +% command's name. +% +% If the command-to-patch was defined by |\DeclareRobustCommand| we +% have to do another test, to check whether it has an optional +% argument and, in this case, we add a backslash in front of the name. +% We replicate the test for |\@protected@testopt|. +% \begin{macrocode} + \bool_if:NT \l_xpatch_protect_bool + { + \tl_set:Nx \l_xpatch_repl_tl + { \c_xpatch_bizarre_tl + \exp_after:wN \token_get_replacement_spec:N + \cs:w \l_xpatch_name_tl \cs_end: } + \tl_if_in:NxT \l_xpatch_repl_tl + { + \c_xpatch_bizarre_tl + \token_to_str:N \@protected@testopt \c_space_tl + \c_backslash_str \l_xpatch_name_tl + \c_space_tl \c_backslash_str \c_backslash_str + } + { + \tl_put_left:Nn \l_xpatch_name_tl { \c_backslash_str } + } + } +% \end{macrocode} +% Finally, we pass the real command-to-patch name to the patching +% macro. +% \begin{macrocode} + \exp_after:wN #1 \cs:w \l_xpatch_name_tl \cs_end: +% \end{macrocode} +% That's the last operation! +% \begin{macrocode} + } +% \end{macrocode} +% +% \subsection{User level commands} +% +% The user level commands. +% \begin{macrocode} +\NewDocumentCommand{\xpatchcmd}{}{ \xpatch_main:NN \patchcmd } +\NewDocumentCommand{\xpretocmd}{}{ \xpatch_main:NN \pretocmd } +\NewDocumentCommand{\xapptocmd}{}{ \xpatch_main:NN \apptocmd } +\NewDocumentCommand{\xshowcmd} {}{ \xpatch_main:NN \show } +% \end{macrocode} +% +% We generate a variant of |\xpatch_main:NN| to accept a macro's name +% as its second argument. +% \begin{macrocode} +\cs_generate_variant:Nn \xpatch_main:NN { Nc } +% \end{macrocode} +% +% Now we can define the patching macros for |\newbibmacro| defined +% commands. In case one uses a wrong name, it will remain in the hash +% space, but it shouldn't be a problem: |\tracingpatches| must be used +% when testing, and it will warn about an undefined macro or one +% equivalent to |\relax|. +% \begin{macrocode} +\NewDocumentCommand{\xpatchbibmacro} { m } + { \xpatch_main:Nc \patchcmd { abx@macro@ \tl_to_str:n {#1} } } +\NewDocumentCommand{\xpretobibmacro} { m } + { \xpatch_main:Nc \pretocmd { abx@macro@ \tl_to_str:n {#1} } } +\NewDocumentCommand{\xapptobibmacro} { m } + { \xpatch_main:Nc \apptocmd { abx@macro@ \tl_to_str:n {#1} } } +\NewDocumentCommand{\xshowbibmacro} { m } + { \xpatch_main:Nc \show { abx@macro@ \tl_to_str:n {#1} } } +% \end{macrocode} +% Finally, the patching macros for \pkg{biblatex} drivers that don't +% need the overhead of |\xpatch_main:NN|. +% \begin{macrocode} +\NewDocumentCommand{\xpatchbibdriver} { m } + { \exp_args:Nc \patchcmd {blx@bbx@#1} } +\NewDocumentCommand{\xpretobibdriver} { m } + { \exp_args:Nc \pretocmd {blx@bbx@#1} } +\NewDocumentCommand{\xapptobibdriver} { m } + { \exp_args:Nc \apptocmd {blx@bbx@#1} } +\NewDocumentCommand{\xshowbibdriver} { m } + { \exp_args:Nc \show {blx@bbx@#1} } +% \end{macrocode} +% \iffalse +%</package> +% \fi +% \end{implementation} +% +% \PrintIndex |