Debian Codegraph @

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

raw
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