Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright
4 %<*driver>
5 \documentclass{ltxdoc}
6 \usepackage{doc}
7 \usepackage{multidef-save}
8 \usepackage{dsfont}
9
10 \def\sty#1{\textsf{#1.sty}}
11 \def\pack#1{\textsf{#1}}
12 \def\ttt#1{\texttt{#1}}
13
14 %%%\AtBeginDocument{\CodelineIndex\EnableCrossrefs}
15 %%%\AtEndDocument{\PrintIndex}
16 \begin{document}
17 \def\docdate{2016/04/20}
18 \def\filedate{2016/04/20}
19 \def\fileversion{1.10}
20 \DocInput{multidef.dtx}
21 \end{document}
22 %</driver>
23 %
24 % \fi
25 %
26 %
27 % \changes{1.00}{2016/03/14}{Initial release}
28 % \changes{1.10}{2016/04/20}{Added def. of robust commands}
29 %
30 %
31 % \CheckSum{329}
32 %% \CharacterTable
33 %% {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
34 %% 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
35 %% Digits \0\1\2\3\4\5\6\7\8\9
36 %% Exclamation \! Double quote \" Hash (number) \#
37 %% Dollar \$ Percent \% Ampersand \&
38 %% Acute accent \' Left paren \( Right paren \)
39 %% Asterisk \* Plus \+ Comma \,
40 %% Minus \- Point \. Solidus \/
41 %% Colon \: Semicolon \; Less than \<
42 %% Equals \= Greater than \> Question mark \?
43 %% Commercial at \@ Left bracket \[ Backslash \\
44 %% Right bracket \] Circumflex \^ Underscore \_
45 %% Grave accent \` Left brace \{ Vertical bar \|
46 %% Right brace \} Tilde \~}
47 %%
48 %
49 % \title{\pack{multidef}: quick definition \\
50 % of multiple similar \LaTeX\ macros}
51 % \author{Nicolas Markey}
52 % \date{\docdate}
53 % \maketitle
54 % \StopEventually{}
55 %
56 % \begin{abstract}
57 % \pack{multidef} provides a succinct way of defining series of macros having
58 % similar definitions. While this can be achieved quite easily with a little of
59 % \TeX\ programming, I~found no package offering a command similar to
60 % the \cs{multidef} command defined in the present package.
61 % \end{abstract}
62 %
63 %
64 % \section{Usage}
65 %
66 % The command \cs{multidef} can be used to quickly define several
67 % similar macros. For~instance:
68 %\begin{verbatim}
69 %\multidef{\textit{#1}}{apple,banana,strb->strawberry}
70 %\end{verbatim}
71 % \multidef{\textit{#1}}{apple,banana,strb->strawberry}
72 % After this single line, you can use commands \cs{apple}, \cs{banana} and
73 % \cs{strb} to write their names in italics: \apple, \banana, and \strb.
74 %
75 %
76 % The package has several features, such as
77 % \begin{itemize}
78 % \item adding prefix\slash suffix to all command names;
79 % \item raising errors and\slash or warnings if some commands are already
80 % defined;
81 % \item allowing commands with arguments.
82 % \end{itemize}
83 %
84 % For example, after writing
85 %\begin{verbatim}
86 %\multidef[arg=1]{\ensuremath{\mathsf{#1}(##1)}}{fst->first,lst->last}
87 %\end{verbatim}
88 % \multidef[arg=1]{\ensuremath{\mathsf{#1}(##1)}}{fst->first,lst->last}
89 % so that you can write \verb+\fst{w}+ to write \fst{w}.
90 %
91 % \section{Examples}
92 %
93 % I very often use the \cs{mathcal} command to get
94 % calligraphic-font letters in math mode. With \pack{multidef} I now
95 % simply write
96 %\begin{verbatim}
97 %\multidef[prefix=cal]{\ensuremath{\mathcal{#1}}}{A-Z}
98 %\end{verbatim}
99 % \multidef[prefix=cal]{\ensuremath{\mathcal{#1}}}{A-Z}
100 % and write \cs{calG} to write~\calG. Here \texttt{A-Z} is a shorthand for the
101 % 26 letters of the basic Latin alphabet.
102 %
103 % \medskip
104 % In~the same way, I can define
105 % \let\mathbb\mathds
106 % \makeatletter
107 % \def\optbb#1{\@ifnextchar+
108 % {\ensuremath{\mathbb{#1}_{\geq 0}}\@gobble}%
109 % {\@ifnextchar*{\ensuremath{\mathbb{#1}_{>0}}\@gobble}%
110 % {\ensuremath{\mathbb{#1}}}}}%
111 % \makeatother
112 % \multidef[prefix=bb]{\optbb{#1}}{A-Z,one->1}%
113 %\begin{verbatim}
114 %\usepackage{dsfonts}
115 %\let\mathbb\mathds
116 %\makeatletter
117 %\newcommand\optbb[1]{%
118 % \@ifnextchar+{\ensuremath{\mathbb{#1}_{\geq 0}}\@gobble}
119 % {\@ifnextchar*{\ensuremath{\mathbb{#1}_{>0}}\@gobble}
120 % {\ensuremath{\mathbb{#1}}}}}
121 %\makeatother
122 %\multidef[prefix=bb]{\optbb{#1}}{A-Z,one->1}
123 %\end{verbatim}
124 % and then \cs{bbR+} writes \bbR+, while \verb+$\bbone_{S}$+ outputs $\bbone_S$.
125 %
126 % \medskip
127 % As a last example, we can use \pack{multidef} to redefine all \cs{...name}
128 % (e.g. \cs{refname}, \cs{partname},~...) commands succinctly. For this,
129 % we~would deactivate the error and warning mechanisms, as we know we are
130 % redefining those macros:
131 %\begin{verbatim}
132 %\multidef[noerr,nowarn,suffix=name]{#1}{ref->R\'ef\'erences,
133 % part->Partie, appendix->Annexe,...}
134 %\end{verbatim}
135 %\multidef[noerr,nowarn,suffix=name]{#1}{ref->R\'ef\'erences,
136 % part->Partie, appendix->Annexe}
137 % Then \cs{refname} contains '\refname'.
138 %
139 % \section{The code}
140 %
141 % \begin{macrocode}
142 \NeedsTeXFormat{LaTeX2e}[1994/12/01]
143 \ProvidesPackage{multidef}[2016/04/20 v1.10 definition of multiple commands]
144 % \end{macrocode}
145 %
146 % We begin with importing package \pack{trimspaces}, or to define its command
147 % \cs{trim@spaces}, in order to trim unwanted spaces in arguments:
148 %\begin{macro}{\trim@spaces}
149 % \begin{macrocode}
150 \IfFileExists{trimspaces.sty}
151 {\RequirePackage{trimspaces}}
152 {}
153 %% borrowing code from trimspaces, if package was not found.
154 \catcode`\Q=3
155 \@ifundefined{trim@spaces}
156 {\PackageWarning{multidef}
157 {Package trimspaces.sty not found.^^JDefining \noexpand\trim@spaces myself}
158 \newcommand\trim@spaces[1]{%
159 \romannumeral-`\q\trim@trim@\noexpand#1Q Q%
160 }
161 \long\def\trim@trim@#1 Q{\trim@trim@@#1Q}
162 \long\def\trim@trim@@#1Q#2{#1}}
163 {}
164 \catcode`\Q=11
165 %%
166 % \end{macrocode}
167 %\end{macro}
168 %
169 % We use \pack{xkeyval} to handle package and command options. The package has
170 % two options, \ttt{noerr} and~\ttt{nowarn}. The former tells
171 % \pack{multidef} not to raise an error when redefining a command (default to
172 % true). The latter tells not to raise a warning (defaults to false). Thus the
173 % default behaviour is to only raise a warning when redefining a command.
174 % Notice that the keys \ttt{noerr} and \ttt{nowarn} are also available as
175 % arguments of the \cs{multidef} command, to change the selected behaviour
176 % locally.
177 %\begin{macro}{noerr}
178 %\begin{macro}{nowarn}
179 % \begin{macrocode}
180 \RequirePackage{xkeyval}
181 \define@boolkeys{mdef}{noerr,nowarn}[true]
182 \DeclareOptionX{noerr}[true]{\setkeys{mdef}{noerr=#1}}
183 \DeclareOptionX{nowarn}[true]{\setkeys{mdef}{nowarn=#1}}
184 \ExecuteOptionsX{noerr=false,nowarn=false}
185 \ProcessOptionsX
186 \ifKV@mdef@noerr
187 \presetkeys{mdef}{noerr=true}{}
188 \else
189 \presetkeys{mdef}{noerr=false}{}
190 \fi
191 \ifKV@mdef@nowarn
192 \presetkeys{mdef}{nowarn=true}{}
193 \else
194 \presetkeys{mdef}{nowarn=false}{}
195 \fi
196 % \end{macrocode}
197 %\end{macro}
198 %\end{macro}
199 % We have five main other keys to be used by the \cs{multidef} command:
200 % \begin{itemize}
201 % \item \ttt{prefix} and \ttt{suffix} define the prefix and suffix to be
202 % used in the name of the command. These keys have equivalent shorthands
203 % \ttt{p} and \ttt{s}.
204 % \item \ttt{arg} (and the equivalent \ttt{args}) can be used to define the
205 % number of arguments of the series of commands to be defined.
206 % \item \ttt{long} and \ttt{global} can be used to define \cs{long} and
207 % \cs{global} macros,
208 % \item \ttt{robust} can be used to define robust commands.
209 % \end{itemize}
210 %\begin{macro}{prefix}
211 %\begin{macro}{suffix}
212 %\begin{macro}{arg}
213 %\begin{macro}{long}
214 %\begin{macro}{global}
215 %\begin{macro}{robust}
216 % \begin{macrocode}
217 \define@key{mdef}{prefix}{\def\@mdprefix{#1}}
218 \define@key{mdef}{p}{\def\@mdprefix{#1}}
219 \define@key{mdef}{suffix}{\def\@mdsuffix{#1}}
220 \define@key{mdef}{s}{\def\@mdsuffix{#1}}
221 \define@key{mdef}{arg}{\def\@mdargs{#1}}
222 \define@key{mdef}{args}{\def\@mdargs{#1}}
223 \define@boolkeys{mdef}{long,global,robust}[true]
224 \presetkeys{mdef}
225 {p=,s=,prefix=,suffix=,long=false,global=false,robust=false,
226 arg=0,args=0}{}
227 % \end{macrocode}
228 %\end{macro}
229 %\end{macro}
230 %\end{macro}
231 %\end{macro}
232 %\end{macro}
233 %\end{macro}
234 %
235 %
236 % We define shorthands for defining series of commands indexed by letters of
237 % the alphabet. Can be useful sometimes...
238 %\begin{macro}{\@mdef@az}
239 %\begin{macro}{\@mdef@AZ}
240 %\begin{macro}{\@mdef@alphabet}
241 %\begin{macro}{\@mdef@Alphabet}
242 % \begin{macrocode}
243 \def\@mdef@az{a-z}
244 \def\@mdef@AZ{A-Z}
245 \def\@mdef@alphabet{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}
246 \def\@mdef@Alphabet{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}
247 % \end{macrocode}
248 %\end{macro}
249 %\end{macro}
250 %\end{macro}
251 %\end{macro}
252 %
253 % We now define \cs{multidef}: it~will first deal with option keys, store the
254 % definition of the commands being defined, and then call its friend
255 % \cs{@mdef}, whose role is to deal with each entry in the comma-separated
256 % list.
257 %\begin{macro}{\multidef}
258 % \begin{macrocode}
259 \newcommand\multidef[3][]{%
260 \setkeys{mdef}{#1}%
261 \def\@mdef@com##1{#2}%
262 \@mdef#3,\@end}
263 % \end{macrocode}
264 %\end{macro}
265 %
266 % Command \cs{@mdef} takes the first item in the comma-separated list,
267 % and first checks if it is a shorthand \ttt{a-z} or \ttt{A-Z}.
268 % If not, it~calls \cs{@@mdef} on the first item, and \cs{@mdef} on
269 % the remainder of the list.
270 %\begin{macro}{\@mdef}
271 % \begin{macrocode}
272 \def\@mdef #1,#2\@end{%
273 \edef\@mdef@arg{\trim@spaces{#1}}%
274 \ifx\@mdef@arg\@mdef@az
275 \expandafter\@mdef \@mdef@alphabet,\@end
276 \else
277 \ifx\@mdef@arg\@mdef@AZ
278 \expandafter\@mdef \@mdef@Alphabet,\@end
279 \else
280 \expandafter\@@mdef\@mdef@arg->->->\@end
281 \fi
282 \fi
283 \def\@mdef@arg{#2}%
284 \ifx\@mdef@arg\@empty\else\@mdef #2\@end\fi}
285 % \end{macrocode}
286 %\end{macro}
287 %
288 % Now, command \cs{@@mdef} checks if the command name already exists, and
289 % issues errors and warning if needed. It~also calls \cs{@@@mdef} with two
290 % arguments: the first one is the string to be used in the name of the
291 % command, the second one is the string to be used in the definition.
292 % The~latter might be the empty string in case both strings are supposed to be
293 % the same.
294 %\begin{macro}{\@@mdef}
295 %\begin{macro}{\@mdef@redeftok}
296 %\begin{macro}{\@mdef@comma}
297 %\begin{macro}{\@mdef@finalwarn}
298 % \begin{macrocode}
299 \newtoks\@mdef@redeftok
300 \def\@mdef@comma{}
301 \def\@@mdef#1->#2->#3\@end{%
302 \@ifundefined{\@mdprefix#1\@mdsuffix}
303 {\@@@mdef{#1}{#2}}
304 {\ifKV@mdef@nowarn\else
305 \edef\@mdef@redef{\the\@mdef@redeftok\@mdef@comma
306 \@backslashchar\@mdprefix#1\@mdsuffix}
307 \def\@mdef@comma{, }
308 \global\@mdef@redeftok=\expandafter{\@mdef@redef}
309 \fi
310 \ifKV@mdef@noerr
311 \@@@mdef{#1}{#2}%
312 \ifKV@mdef@nowarn\else
313 \PackageWarning{multidef}
314 {command \expandafter\noexpand\csname\@mdprefix#1\@mdsuffix\endcsname
315 redefined}
316 \fi
317 \else
318 \PackageError{multidef}
319 {command \expandafter\noexpand\csname\@mdprefix#1\@mdsuffix\endcsname
320 already defined}\@ehc
321 \fi
322 \ifKV@mdef@nowarn\else
323 \@ifundefined{@mdwarnonce}
324 {\def\@mdwarnonce{}%
325 \@mdef@finalwarn}
326 {}
327 \fi}
328 }
329 \def\@mdef@finalwarn{%
330 \AtEndDocument{\PackageWarningNoLine{multidef}{There were
331 redefined commands (\the\@mdef@redeftok)}}}
332 % \end{macrocode}
333 %\end{macro}
334 %\end{macro}
335 %\end{macro}
336 %\end{macro}
337 %
338 % Finally, \cs{@@@mdef} calls \cs{@mdef@def} or \cs{@mdef@robdef} (if option
339 % \ttt{robust} was passed) with the appropriate arguments. This is where the
340 % commands are really defined. The definitions of \cs{@mdef@def} and
341 % \cs{@mdef@robdef} use \cs{@yargd@f}, following the definition of
342 % \cs{newcommand} and \cs{DeclareRobustCommand} in \LaTeX.
343 %\begin{macro}{\@@@mdef}
344 %\begin{macro}{\@mdef@def}
345 %\begin{macro}{\@mdef@robdef}
346 % \begin{macrocode}
347 \def\@@@mdef#1#2{\def\@arg@{#2}%
348 \ifx\@arg@\@empty
349 \ifKV@mdef@robust
350 \expandafter\def\expandafter\@mdef@cmdname
351 \expandafter{\csname\@mdprefix#1\@mdsuffix\endcsname}%
352 \expandafter\@mdef@robdef\@mdef@cmdname{#1}%
353 \else
354 \@mdef@def{#1}{#1}%
355 \fi
356 \else
357 \ifKV@mdef@robust
358 \expandafter\def\expandafter\@mdef@cmdname
359 \expandafter{\csname\@mdprefix#1\@mdsuffix\endcsname}
360 \expandafter\@mdef@robdef\@mdef@cmdname{#2}%
361 \else
362 \@mdef@def{#1}{#2}%
363 \fi
364 \fi}
365 \def\@mdef@def#1#2{%
366 \let\reserved@b\@gobble
367 \ifKV@mdef@global\let\@mdglobal\global\else\let\@mdglobal\relax\fi
368 \ifKV@mdef@long\let\@mdlong\long\else\let\@mdlong\relax\fi
369 \def\l@ngrel@x{\@mdlong\@mdglobal}
370 \expandafter\expandafter\expandafter\@yargd@f\expandafter\@mdargs\csname
371 \@mdprefix#1\@mdsuffix\expandafter\endcsname\expandafter{\@mdef@com{#2}}
372 }
373 \def\@mdef@robdef#1#2{%
374 \edef\reserved@a{\string#1}%
375 \def\reserved@b{#1}%
376 \edef\reserved@b{\expandafter\strip@prefix\meaning\reserved@b}%
377 \global\edef#1{%
378 \ifx\reserved@a\reserved@b
379 \noexpand\x@protect
380 \noexpand#1%
381 \fi
382 \noexpand\protect
383 \expandafter\noexpand\csname
384 \expandafter\@gobble\string#1 \endcsname
385 }%
386 \let\reserved@b\@gobble
387 \ifKV@mdef@global\let\@mdglobal\global\else\let\@mdglobal\relax\fi
388 \ifKV@mdef@long\let\@mdlong\long\else\let\@mdlong\relax\fi
389 \def\l@ngrel@x{\@mdlong\@mdglobal}
390 \expandafter\expandafter\expandafter\@yargd@f\expandafter\@mdargs\csname
391 \expandafter\@gobble\string#1 \expandafter\endcsname
392 \expandafter{\@mdef@com{#2}}
393 }
394 % \end{macrocode}
395 %\end{macro}
396 %\end{macro}
397 %\end{macro}
398 % \Finale
399 \endinput