| 1 |
% \iffalse meta-comment |
| 2 |
% |
| 3 |
% Copyright (C) 2013 by Robert J Lee |
| 4 |
% |
| 5 |
% This file may be distributed and/or modified under the |
| 6 |
% conditions of the LaTeX Project Public License, either |
| 7 |
% version 1.2 of this license or (at your option) any later |
| 8 |
% version. The latest version of this license is in: |
| 9 |
% |
| 10 |
% http://www.latex-project.org/lppl.txt |
| 11 |
% |
| 12 |
% and version 1.2 or later is part of all distributions of |
| 13 |
% LaTeX version 1999/12/01 or later. |
| 14 |
% |
| 15 |
% \fi |
| 16 |
% |
| 17 |
% \iffalse |
| 18 |
% <package>\NeedsTeXFormat{LaTeX2e}[1999/12/01] |
| 19 |
% <package>\ProvidesPackage{macroswap} |
| 20 |
% <package> [2013/08/21 v1.1 dtx macro swapper] |
| 21 |
% |
| 22 |
%<*driver> |
| 23 |
\documentclass{ltxdoc} |
| 24 |
\usepackage{macroswap} |
| 25 |
\EnableCrossrefs |
| 26 |
\CodelineIndex |
| 27 |
\RecordChanges |
| 28 |
\begin{document} |
| 29 |
\DocInput{macroswap.dtx} |
| 30 |
\end{document} |
| 31 |
%</driver> |
| 32 |
% \fi |
| 33 |
% |
| 34 |
% \CharacterTable |
| 35 |
% {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 |
| 36 |
% 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 |
| 37 |
% Digits \0\1\2\3\4\5\6\7\8\9 |
| 38 |
% Exclamation \! Double quote \" Hash (number) \# |
| 39 |
% Dollar \$ Percent \% Ampersand \& |
| 40 |
% Acute accent \' Left paren \( Right paren \) |
| 41 |
% Asterisk \* Plus \+ Comma \, |
| 42 |
% Minus \- Point \. Solidus \/ |
| 43 |
% Colon \: Semicolon \; Less than \< |
| 44 |
% Equals \= Greater than \> Question mark \? |
| 45 |
% Commercial at \@ Left bracket \[ Backslash \\ |
| 46 |
% Right bracket \] Circumflex \^ Underscore \_ |
| 47 |
% Grave accent \` Left brace \{ Vertical bar \| |
| 48 |
% Right brace \} Tilde \~} |
| 49 |
% |
| 50 |
% \CheckSum{62} |
| 51 |
% |
| 52 |
% \changes{v1.0}{2013/08/18}{Initial version} |
| 53 |
% \changes{v1.1}{2013/08/20}{Correct month in version date, remove |
| 54 |
% (unstated) dependency on \texttt{etoolbox} package, support swapping |
| 55 |
% macros that expect parameters, improved error reporting (thanks to |
| 56 |
% Christian Tellechea, Ulrich Diez and Dan)} |
| 57 |
% |
| 58 |
% \GetFileInfo{macroswap.sty} |
| 59 |
% |
| 60 |
% \DoNotIndex{\let, \edef, \xdef, \relax, \newcommand} |
| 61 |
% \DoNotIndex{\csname, \endcsname} |
| 62 |
% |
| 63 |
% \title{The Macroswap Package\thanks{This document corresponds to \textsf{Macroswap}~\fileversion, dated \filedate.}} |
| 64 |
% \author{Robert J Lee \\ [email protected]} |
| 65 |
% |
| 66 |
% \maketitle |
| 67 |
% |
| 68 |
% \begin{abstract} |
| 69 |
% |
| 70 |
% This package provides macros to allow the user to redefine a pair of |
| 71 |
% macros so that the token lists they expand to will be swapped. |
| 72 |
% |
| 73 |
% \end{abstract} |
| 74 |
% |
| 75 |
% \section{Introduction} |
| 76 |
% |
| 77 |
% This package was written to allaw a simple, readable syntax for |
| 78 |
% swapping the values within macros, used as program variables. |
| 79 |
% |
| 80 |
% |
| 81 |
% \section*{Usage} |
| 82 |
% |
| 83 |
% \DescribeMacro{\macroswap} |
| 84 |
% |
| 85 |
% The |\macroswap| macro allows you to temporarily swap two macro |
| 86 |
% definitions; for example: |
| 87 |
% |
| 88 |
% \begin{verbatim} |
| 89 |
% \newcommand{\myfirst}{1} |
| 90 |
% \newcommand{\myend}{2} |
| 91 |
% \begingroup |
| 92 |
% \macroswap{myfirst}{myend} |
| 93 |
% \myfirst\myend % prints ``21'' |
| 94 |
% \endgroup |
| 95 |
% \myfirst\myend % prints ``12'' (swapped defininions were local) |
| 96 |
% \end{verbatim} |
| 97 |
% |
| 98 |
% This local swap is often unwanted, and can use up TeX's stack memory. |
| 99 |
% So you may prefer the global version: |
| 100 |
% |
| 101 |
% \DescribeMacro{\gmacroswap} |
| 102 |
% |
| 103 |
% The |\gmacroswap| macro allows you to globally swap two macro |
| 104 |
% definitions; for example: |
| 105 |
% |
| 106 |
% \begin{verbatim} |
| 107 |
% \newcommand{\myfirst}{1} |
| 108 |
% \newcommand{\myend}{2} |
| 109 |
% \begingroup |
| 110 |
% \gmacroswap{myfirst}{myend} |
| 111 |
% \myfirst\myend % prints ``21'' |
| 112 |
% \endgroup |
| 113 |
% \myfirst\myend % prints ``21'' (swapped defininions are global) |
| 114 |
% \end{verbatim} |
| 115 |
% |
| 116 |
% \section*{Usage with arrayjobx} |
| 117 |
% |
| 118 |
% To globally swap two elements of an array declared with the |arrayjobx| |
| 119 |
% package, you need to arrange to swap the macros used by that |
| 120 |
% package. This is not part of the public interface and may change at |
| 121 |
% any time; unfortunately, it does not seem possible to do this with |
| 122 |
% only the public interface, especially if you do not want to expand |
| 123 |
% the tokens in the array. |
| 124 |
% |
| 125 |
% Assuming arrayjobx version~1.04~(labelled ``05/03/2010''), it is |
| 126 |
% only necessary to swap the values of the underlying macros using the |
| 127 |
% following syntax: |
| 128 |
% |
| 129 |
% \begin{verbatim} |
| 130 |
% \newarray{arr} |
| 131 |
% \readarray{arr}{A&C&B} |
| 132 |
% \gmacroswap{arr2\string~}{arr3\string~} |
| 133 |
% \arr(1)\par % prints ``A'' |
| 134 |
% \arr(2)\par % prints ``B'' |
| 135 |
% \arr(3)\par % prints ``C'' |
| 136 |
% \end{verbatim} |
| 137 |
% |
| 138 |
% |
| 139 |
% \section*{Implementation} |
| 140 |
%\StopEventually{\PrintChanges \pagebreak[4] \PrintIndex} |
| 141 |
% |
| 142 |
% \begin{macro}{\gmacroswap} |
| 143 |
% Given the name of two macros, swap their definitions. |
| 144 |
% Produces no output. |
| 145 |
% This version uses plain |\let| to produce a local assignment. |
| 146 |
% \begin{macrocode} |
| 147 |
\newcommand{\macroswap}[2]{% |
| 148 |
% \end{macrocode} |
| 149 |
% NB: there's no guarantee that |#1| or |#2| will be a single token. |
| 150 |
% |
| 151 |
% First verify that they expand to a single macro name: |
| 152 |
% \begin{macrocode} |
| 153 |
\expandafter\ifcsname#1\endcsname% |
| 154 |
\else% |
| 155 |
\PackageError{macrocode}{Two macro names are required for macroswap % |
| 156 |
(got ``#1'' and ``#2'')}{% |
| 157 |
Two macro names are required, but the first parameter does not % |
| 158 |
expand to a defined macro name. Macros have not been swapped.}% |
| 159 |
\fi% |
| 160 |
\expandafter\ifcsname#2\endcsname% |
| 161 |
\else% |
| 162 |
\PackageError{macrocode}{Two macro names are required for macroswap % |
| 163 |
(got ``#1'' and ``#2'')}{% |
| 164 |
Two macro names are required, but the second parameter does not % |
| 165 |
expand to a defined macro name. Macros have not been swapped.}% |
| 166 |
\fi% |
| 167 |
% \end{macrocode} |
| 168 |
% First we use a temporary variable, |macroswap@temp|, to hold the value of the first macro. |
| 169 |
% |
| 170 |
% |\expandafter| is used to evaluate the |\csname|\dots|\endcsname| |
| 171 |
% become the |\let|, as |\let| will only redefine its first parameter. |
| 172 |
% \begin{macrocode} |
| 173 |
\expandafter\let\expandafter\macroswap@temp\csname#1\endcsname% |
| 174 |
% \end{macrocode} |
| 175 |
% |
| 176 |
% Next, the same method is used to reassign each passed-in macro. |
| 177 |
% |
| 178 |
% \begin{macrocode} |
| 179 |
\expandafter\let\csname#1\expandafter\endcsname\csname#2\endcsname% |
| 180 |
\expandafter\let\csname#2\endcsname\macroswap@temp% |
| 181 |
% \end{macrocode} |
| 182 |
% Finally, we throw away our temporary macro: |
| 183 |
% \begin{macrocode} |
| 184 |
\let\macroswap@temp\relax% |
| 185 |
} |
| 186 |
% \end{macrocode} |
| 187 |
% \end{macro} |
| 188 |
% |
| 189 |
% \begin{macro}{\macroswap} |
| 190 |
% Given the name of two macros, swap their definitions. |
| 191 |
% Produces no output. |
| 192 |
% |
| 193 |
% This version is global; the only difference here is that |\global| |
| 194 |
% is used to modify |\let| to applied globally. |
| 195 |
% \begin{macrocode} |
| 196 |
\newcommand{\gmacroswap}[2]{% |
| 197 |
\expandafter\let\expandafter\macroswap@temp\csname#1\endcsname% |
| 198 |
% \end{macrocode} |
| 199 |
% NB: |\expandafter| is used before |\global| so that the |let| becomes global... |
| 200 |
% \begin{macrocode} |
| 201 |
\expandafter\global\expandafter\let\csname#1\expandafter\endcsname\csname#2\endcsname% |
| 202 |
\expandafter\global\expandafter\let\csname#2\endcsname\macroswap@temp% |
| 203 |
\let\macroswap@temp\relax% |
| 204 |
} |
| 205 |
% \end{macrocode} |
| 206 |
% \end{macro} |
| 207 |
% |
| 208 |
% That is all |
| 209 |
% \Finale |
| 210 |
\endinput |