%%% ====================================================================
%%% @LaTeX-doc-source-file{
%%%   filename  = "patchcmd.dtx",
%%%   version   = "1.03",
%%%   date      = "2000/07/31",
%%%   time      = "08:40:39 EDT",
%%%   author    = "Michael J Downes",
%%%   email     = "mjd@ams.org",
%%%   abstract  = "Provides a way to add material at beginning or end of
%%%                a macro's existing definition.",
%%%   checksum  = "23183 222 932 7411",
%%%   docstring = "The checksum field, produced by Robert Solovay's
%%%                checksum utility, gives CRC-16 checksum, lines,
%%%                words, and characters.",
%%%  }
%%% ====================================================================
% \iffalse
%<*driver>
\NeedsTeXFormat{LaTeX2e}
\documentclass{amsdtx}
\begin{document}
\title{The \pkg{patchcmd} package}
\author{Michael~J. Downes}
\date{Version \fileversion, \filedate}
\hDocInput{patchcmd.dtx}
\end{document}
%</driver>
% \fi
%
% \maketitle
% \section{Introduction}
%
%    The \pkg{patchcmd} package provides a command \cn{patchcommand} that
%    can be used to add material at the beginning and/or end of the
%    replacement text of an existing macro. It works for macros with any
%    number of normal arguments (0--9), including macros that were
%    defined with \cn{DeclareRobustCommand}. However, it does not work
%    for macros that use \cs{futurelet}, for example ones defined to
%    have starred forms or optional arguments. In addition, it does not
%    work for macros that have delimited arguments.
%
%    This package is the result of some discussion initiated by Peter
%    Wilson in the newsgroup \fn{comp.text.tex} in June 2000 and
%    continued with Peter and Heiko Oberdiek.
%\begin{verbatim}
%Subject: Re: Adding stuff at end of a macro
%References:
%        <3ojiks8in1f5s575eta5rg7ncoc98mpi8f@4ax.com>
%        <39492C50.A962193B@boeing.com>
%        <pcitvabqk2.fsf@thor.ams.org>
%\end{verbatim}
%
% \StopEventually{}
%
% \section{Implementation}
%    Standard declaration of package name and date.
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{patchcmd}[2000/07/31 v1.03]
%% Copyright 2000 Michael John Downes
%% This file has no restrictions on its use, distribution, or sale.
%    \end{macrocode}
%
%    For debugging.
%    \begin{macrocode}

%%\def\wrs{\immediate\write\sixt@@n}
%    \end{macrocode}
%
%    \begin{macrocode}
\newcommand{\patchcommand}[1]{%
  \expandafter\patchcmd@a\meaning#1??->@\@nil#1%
}
%    \end{macrocode}
%
%    We begin by looking at the meaning string of the given token. We
%    will issue an error message if the token is not a control sequence,
%    if it is an undefined control sequence, or if it is a known control
%    sequence but not a macro.
%    \begin{macrocode}
\long\def\patchcmd@a#1#2#3->#4#5\@nil#6{%
%%  \wrs{\string#6: [#1] [#2] [#3]->[#4]}%
  \ifx @#4\relax \patchcmdError#6#1%
    \expandafter\@gobbletwo % discard the other two arguments
  \else
    \if l#2\toks@{\patchcmd@e{}#6}% l in this position means \long
    \else \toks@{\patchcmd@e*#6}%   not \long
    \fi
%    \end{macrocode}
%    Now \cs{patchcmd@b} will do further analysis to determine what
%    kinds of arguments the macro takes. If it takes $n$ normal
%    arguments, the digit $n$ (0--9) will be added to \cs{toks@}.
%    \begin{macrocode}
    \patchcmd@b #3@#4#5 ? ? ? \@nil#6%
    \expandafter\the\expandafter\toks@
  \fi
}
%    \end{macrocode}
%
%    We handle robust commands by scanning the first two control words
%    in the macro's definition to see if the second one is followed by
%    two spaces. If it is, then arg 7 will be empty. In that case we
%    compare the csname preceding the two spaces to the original
%    argument of \cn{patchcommand}. If they are equal it is nearly certain
%    that this is a robust command in normal \LaTeX{} form. In that case
%    we call \cn{patchcommand} quasi-recursively on the protected control
%    sequence with the extra space at the end of its name.
%    \begin{macrocode}
\def\patchcmd@b#1:#2@#3#4 #5#6 #7 #8\@nil#9{%
%%  \wrs{[#1] [#2] [#3] [#4] [#5] [#6] ARG7=[#7] [#8]}%
  \if \ifx @#7@\expandafter
      \ifx\csname #6\endcsname#9T\else F\fi\else F\fi T%
    \toks@\expandafter{\expandafter\patchcommand\csname #6 \endcsname}%
  \else
    \ifx @#2@% No arguments
      \toks@\expandafter{\the\toks@ 0}%
    \else
      \patchcmd@c 0#2{\string##}0%
    \fi
  \fi
}
%    \end{macrocode}
%
%    The task of \cs{patchcmd@c} is to iterate over \texttt{\#D} pairs,
%    where D is a digit in the range 1--9, until reaching the last one.
%    Whenever we find such a pair, we carry the digit forward for the
%    next recursive call; but we use digit 0 as a marker to terminate
%    the recursion. If any other character interrupts the \texttt{\#D}
%    pattern, it means that this macro has some kind of delimited
%    argument.
%    \begin{macrocode}
\def\patchcmd@c#1#2#3{%
  \if\string###2%      % yes it's a # token
    \ifodd 0#31 % and it's followed by a number
      \if 0#3\patchcmd@d#1\fi % number=0? then we're done
    \else \patchcmd@d D% # not a number: must be a delimited arg
    \fi
  \else \patchcmd@d D% not a # token: must be a delmited arg
  \fi
  \patchcmd@c#3%
}
%    \end{macrocode}
%
%    \begin{macrocode}
\def\patchcmd@d#1{%
  \if D#1%
    \PackageError{patchcmd}{Cannot change a macro that has
      delimited arguments}\@ehd
  \else
    \toks@\expandafter{\the\toks@ #1}%
  \fi
  \begingroup
  \aftergroup\@gobble
  \let\patchcmd@c\endgroup
}
%    \end{macrocode}
%
%    \begin{macrocode}
\def\patchcmd@e#1#2#3#4#5{%
  \begingroup
  \edef\@##1{%
    \@temptokena\noexpand\expandafter{%
      \noexpand#2%
        \ifnum#3>0 {####1}\ifnum#3>1 {####2}\ifnum#3>2 {####3}%
        \ifnum#3>3 {####4}\ifnum#3>4 {####5}\ifnum#3>5 {####6}%
        \ifnum#3>6 {####7}\ifnum#3>7 {####8}\ifnum#3>8 {####9}%
        \fi\fi\fi\fi\fi\fi\fi\fi\fi
      ##1%
    }%
  }
  \@{#5}%
  \edef\@##1{\endgroup
    \noexpand\renewcommand#1\noexpand#2\ifcase#3 \else [#3]\fi
    {##1\the\@temptokena}}%
  \@{#4}%
%%  \show#2%
}
%    \end{macrocode}
%
%    Two possible error messages. Optimized. Second arg is the first
%    letter from the meaning string; it will be ``u'' if and only if the
%    control sequence is undefined.
%    \begin{macrocode}
\long\def\patchcmdError#1#2{%
  \begingroup
  \toks@{Not redefinable}%
  \ifcat\relax\noexpand#1% Is it a control sequence?
    \begingroup
    \let#1=?\ifx ?\relax % Is it "\relax"?
      \endgroup % accept current value of \toks@
    \else \endgroup
%    \end{macrocode}
%
%    This is equivalent to the \cs{@ifundefined} test (true if arg 2 is
%    either undefined or its meaning is \cs{relax}).
%
%    \begin{macrocode}
      \if\ifx\relax#1u\else #2\fi u%
        \toks@{Not defined}%
      \fi
    \fi
  \fi
%    \end{macrocode}
%    Apply \cs{string} preemptively to arg 1 to prevent catastrophic
%    failure if it happens to be \cs{par} (\cs{PackageError} isn't
%    defined as \cs{long} in older versions of \LaTeX{}).
%    \begin{macrocode}
  \edef\@{\endgroup
    \noexpand\PackageError{patchcmd}{%
      \the\toks@: \string#1}\noexpand\@ehd}%
  \@
}
%    \end{macrocode}
%
%    The usual \cs{endinput} to ensure that random garbage at the end of
%    the file doesn't get copied by \fn{docstrip}.
%    \begin{macrocode}
\endinput
%    \end{macrocode}
%
% \CheckSum{183}
% \Finale