summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/macroswap
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-08-18 23:32:33 +0000
committerKarl Berry <karl@freefriends.org>2013-08-18 23:32:33 +0000
commitf917dbdfae2021d592989828a2993fa2b4a78aae (patch)
tree6587f88a395e0b7e8e7a7f60ec39c8a690a4a5db /Master/texmf-dist/source/latex/macroswap
parent008b1c4fc694eb541c50db9f3d406607e269d2fc (diff)
macroswap (18aug13)
git-svn-id: svn://tug.org/texlive/trunk@31462 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/macroswap')
-rw-r--r--Master/texmf-dist/source/latex/macroswap/macroswap.dtx214
-rw-r--r--Master/texmf-dist/source/latex/macroswap/macroswap.ins53
2 files changed, 267 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/macroswap/macroswap.dtx b/Master/texmf-dist/source/latex/macroswap/macroswap.dtx
new file mode 100644
index 00000000000..c0fd61c4db1
--- /dev/null
+++ b/Master/texmf-dist/source/latex/macroswap/macroswap.dtx
@@ -0,0 +1,214 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2013 by Robert J Lee
+%
+% This file may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either
+% version 1.2 of this license or (at your option) any later
+% version. The latest version of this license is in:
+%
+% http://www.latex-project.org/lppl.txt
+%
+% and version 1.2 or later is part of all distributions of
+% LaTeX version 1999/12/01 or later.
+%
+% \fi
+%
+% \iffalse
+% <package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+% <package>\ProvidesPackage{macroswap}
+% <package> [2013/09/16 v1.0 dtx macro swapper]
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{macroswap}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\begin{document}
+ \DocInput{macroswap.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \CharacterTable
+% {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
+% 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
+% Digits \0\1\2\3\4\5\6\7\8\9
+% Exclamation \! Double quote \" Hash (number) \#
+% Dollar \$ Percent \% Ampersand \&
+% Acute accent \' Left paren \( Right paren \)
+% Asterisk \* Plus \+ Comma \,
+% Minus \- Point \. Solidus \/
+% Colon \: Semicolon \; Less than \<
+% Equals \= Greater than \> Question mark \?
+% Commercial at \@ Left bracket \[ Backslash \\
+% Right bracket \] Circumflex \^ Underscore \_
+% Grave accent \` Left brace \{ Vertical bar \|
+% Right brace \} Tilde \~}
+%
+% \CheckSum{54}
+%
+% \changes{v1.0}{2013/09/18}{Initial version}
+%
+% \GetFileInfo{macroswap.sty}
+%
+% \DoNotIndex{\let, \edef, \xdef, \relax, \newcommand}
+% \DoNotIndex{\csname, \endcsname}
+% \DoNotIndex{\makeatletter, \makeatother}
+%
+% \title{The Macroswap Package\thanks{This document corresponds to \textsf{Macroswap}~\fileversion, dated \filedate.}}
+% \author{Robert J Lee \\ latex@rjlee.homelinux.org}
+%
+% \maketitle
+%
+% \begin{abstract}
+%
+% This package provides macros to allow the user to redefine a pair of
+% macros so that the token lists they expand to will be swapped.
+%
+% \end{abstract}
+%
+% \section{Introduction}
+%
+% This package was written to allaw a simple, readable syntax for
+% swapping the values within macros, used as program variables.
+%
+%
+% \section*{Usage}
+%
+% \DescribeMacro{\macroswap}
+%
+% The |\macroswap| macro allows you to temporarily swap two macro
+% definitions; for example:
+%
+% \begin{verbatim}
+% \newcommand{\myfirst}{1}
+% \newcommand{\myend}{2}
+% \begingroup
+% \macroswap{myfirst}{myend}
+% \myfirst\myend % prints ``21''
+% \endgroup
+% \myfirst\myend % prints ``12'' (swapped defininions were local)
+% \end{verbatim}
+%
+% This local swap is often unwanted, and can use up TeX's stack memory.
+% So you may prefer the global version:
+%
+% \DescribeMacro{\gmacroswap}
+%
+% The |\gmacroswap| macro allows you to globally swap two macro
+% definitions; for example:
+%
+% \begin{verbatim}
+% \newcommand{\myfirst}{1}
+% \newcommand{\myend}{2}
+% \begingroup
+% \gmacroswap{myfirst}{myend}
+% \myfirst\myend % prints ``21''
+% \endgroup
+% \myfirst\myend % prints ``21'' (swapped defininions are global)
+% \end{verbatim}
+%
+% \section*{Usage with arrayjobx}
+%
+% To globally swap two elements of an array declared with the |arrayjobx|
+% package, you need to arrange to swap the macros used by that
+% package. This is not part of the public interface and may change at
+% any time; unfortunately, it does not seem possible to do this with
+% only the public interface, especially if you do not want to expand
+% the tokens in the array.
+%
+% Assuming arrayjobx version~1.04~(labelled ``05/03/2010''), it is
+% only necessary to swap the values of the underlying macros using the
+% following syntax:
+%
+% \begin{verbatim}
+% \newarray{arr}
+% \readarray{arr}{A&C&B}
+% \gmacroswap{arr2\string~}{arr3\string~}
+% \arr(1)\par % prints ``A''
+% \arr(2)\par % prints ``B''
+% \arr(3)\par % prints ``C''
+% \end{verbatim}
+%
+%
+% \section*{Implementation}
+%\StopEventually{\PrintChanges \pagebreak[4] \PrintIndex}
+%
+% First we make the @ symbol a letter so wo can use it internally
+% \begin{macrocode}
+\makeatletter
+% \end{macrocode}
+%
+% \begin{macro}{\gmacroswap}
+% given the name of two macros, swap their definitions.
+% Produces no output.
+% This version is global.
+% \begin{macrocode}
+\newcommand{\gmacroswap}[2]{%
+% \end{macrocode}
+% NB: we don't use ifcsname, because there's no guarantee that |#1| or
+% |#2| will be a single token
+% |macro@swap@left| and |macro@swap@right| are the contents of the
+% passed-in macro names. The |edef| would normally fully expand its
+% parameter but the |csexpandonce| prevents the full expansion and
+% returns only the token list that we want.
+% \begin{macrocode}
+ \edef\macro@swap@left{\csexpandonce{#1}}%
+ \edef\macro@swap@right{\csexpandonce{#2}}%
+% \end{macrocode}
+% Having taken a copy of the passed-in macro, we then reassign it to
+% the values in our tokens, which we get using |expandonce| to strip
+% off our temporary macro names. Again, |xdef| would normally expand
+% its macros as well as being a global assignment; however, the
+% |expandonce| prevents the full expansion.
+%
+% |expandafter| is used to evaluate the |csname|\dots|\endcsname|
+% become the |xdef|, as |xdef| will only redefine its first parameter.
+% \begin{macrocode}
+ \expandafter\xdef\csname#2\endcsname{\expandonce{\macro@swap@left}}%
+ \expandafter\xdef\csname#1\endcsname{\expandonce{\macro@swap@right}}%
+% \end{macrocode}
+%
+% Finally, we throw away our temporary macros:
+% \begin{macrocode}
+ \let\macroswap@left\relax%
+ \let\macroswap@right\relax%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\macroswap}
+% given the name of two macros, swap their definitions.
+% Produces no output.
+% This version is local.
+% \begin{macrocode}
+\newcommand{\macroswap}[2]{%
+% \end{macrocode}
+% NB: we don't use ifcsname, because there's no guarantee that |#1| or |#2| will be a single token
+% \begin{macrocode}
+ \edef\macro@swap@left{\csexpandonce{#1}}%
+ \edef\macro@swap@right{\csexpandonce{#2}}%
+% \end{macrocode}
+% The only difference here is the use of |edef| instead of |xdef|,
+% which expands its second argument and overwrites its first argument
+% locally, so the original values will be restored at the end of the
+% current group or environment.
+% \begin{macrocode}
+ \expandafter\edef\csname#2\endcsname{\expandonce{\macro@swap@left}}%
+ \expandafter\edef\csname#1\endcsname{\expandonce{\macro@swap@right}}%
+ \let\macroswap@left\relax%
+ \let\macroswap@right\relax%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% Leave @ as another character
+% \begin{macrocode}
+\makeatother
+% \end{macrocode}
+%
+% That is all
+% \Finale
+\endinput
diff --git a/Master/texmf-dist/source/latex/macroswap/macroswap.ins b/Master/texmf-dist/source/latex/macroswap/macroswap.ins
new file mode 100644
index 00000000000..3e8915e1a81
--- /dev/null
+++ b/Master/texmf-dist/source/latex/macroswap/macroswap.ins
@@ -0,0 +1,53 @@
+%%
+%% Copyright (C) 2013 by Robert J Lee
+%%
+%% This file may be distributed and/or modified under the
+%% conditions of the LaTeX Project Public License, either
+%% version 1.2 of this license or (at your option) any later
+%% version. The latest version of this license is in:
+%%
+%% http://www.latex-project.org/lppl.txt
+%%
+%% and version 1.2 or later is part of all distributions of
+%% LaTeX version 1999/12/01 or later.
+%
+\input docstrip.tex
+\keepsilent
+\usedir{tex/latex/macroswap}
+\preamble
+
+This is a generated file.
+
+Copyright (C) 2013 by Robert J Lee
+
+This file may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either
+version 1.2 of this license or (at your option) any later
+version. The latest version of this license is in:
+
+ http://www.latex-project.org/lppl.txt
+
+and version 1.2 or later is part of all distributions of
+LaTeX version 1999/12/01 or later.
+
+\endpreamble
+
+\generate{\file{macroswap.sty}{\from{macroswap.dtx}{package}}}
+
+\obeyspaces
+
+\Msg{****************************************************}
+\Msg{* *}
+\Msg{* To finish the installation you have to move the *}
+\Msg{* following file into a directory searched by TeX: *}
+\Msg{* *}
+\Msg{* macroswap.sty *}
+\Msg{* *}
+\Msg{* To produce the documentation run the file *}
+\Msg{* macroswap.dtx through LaTeX. *}
+\Msg{* *}
+\Msg{* Happy TeXing! *}
+\Msg{* *}
+\Msg{****************************************************}
+
+\endbatchfile