Debian Codegraph @

texmf-dist/source/latex/sauerj/optparams.dtx

raw
1 % \iffalse meta-comment
2 % Line endings: UNIX
3 % Tab size: 4
4 %
5 % Copyright 2004 Jonathan Sauer
6 %
7 % This work may be distributed and/or modified under the
8 % conditions of the LaTeX Project Public License, either version 1.3
9 % of this license or (at your option) any later version.
10 % The latest version of this license is in
11 %
12 % http://www.latex-project.org/lppl.txt
13 %
14 % and version 1.3 or later is part of all distributions of LaTeX
15 % version 2003/12/01 or later.
16 %
17 % This work has the LPPL maintenance status "maintained".
18 %
19 % The Current Maintainer of this work is Jonathan Sauer
20 % (<[email protected]>).
21 %
22 % This work consists of the files optparams.dtx and optparams.ins
23 % and the derived file optparams.sty.
24 %
25 % \fi
26 %
27 % \iffalse
28 %
29 %<*driver>
30 \documentclass{ltxdoc}
31 \usepackage{optparams}
32 \EnableCrossrefs
33 \CodelineIndex
34 \RecordChanges
35 % Modification of verbatim for tabs in listings
36 \makeatletter
37 {\catcode`\ =\active%
38 \catcode`\^^I=\active%
39 \gdef\@vobeyspaces{%
40 \catcode`\ \active\let \@xobeysp%
41 \catcode`\^^I\active\def^^I{~~}%
42 }}%
43 \makeatother
44 \begin{document}
45 \DocInput{\jobname.dtx}
46 \end{document}
47 %</driver>
48 %
49 %<package>\NeedsTeXFormat{LaTeX2e}
50 %<package>\ProvidesPackage{optparams}
51 %<package> [2004/08/14 v0.9 multiple optional parameters in macros]
52 %
53 % \fi
54 %
55 % \CheckSum{12}
56 % \CharacterTable
57 % {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
58 % 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
59 % Digits \0\1\2\3\4\5\6\7\8\9
60 % Exclamation \! Double quote \" Hash (number) \#
61 % Dollar \$ Percent \% Ampersand \&
62 % Acute accent \' Left paren \( Right paren \)
63 % Asterisk \* Plus \+ Comma \,
64 % Minus \- Point \. Solidus \/
65 % Colon \: Semicolon \; Less than \<
66 % Equals \= Greater than \> Question mark \?
67 % Commercial at \@ Left bracket \[ Backslash \\
68 % Right bracket \] Circumflex \^ Underscore \_
69 % Grave accent \` Left brace \{ Vertical bar \|
70 % Right brace \} Tilde \~}
71 %
72 % \DoNotIndex{\@ifnextchar,\@nil,\def,\newcommand}
73 %
74 % \GetFileInfo{\jobname.sty}
75 %
76 % \title{The \textsf{optparams} package\thanks{This document
77 % corresponds to \textsf{\filename}~\fileversion, dated \filedate. The
78 % package is based on David Kastrup's macros for `Around the Bend
79 % 21'.}}
80 %
81 % \author{Jonathan Sauer \\ \texttt{[email protected]}}
82 %
83 % \date{\filedate}
84 %
85 % \maketitle
86 %
87 % \begin{abstract}
88 % This file describes the \textsf{optparams} package that provides a
89 % small macro for creating macros with multiple optional parameters.
90 %
91 % \end{abstract}
92 %
93 % \tableofcontents
94 %
95 %
96 %
97 % \section{Introduction}
98 %
99 % The \LaTeX\ macro |\newcommand| is used to define macros that may
100 % have one optional parameter (the first one). However, there is no
101 % easy way of defining macros having several optional parameters. This
102 % package provides the macro |\optparams| to simplify the creation of
103 % macros with multiple optional parameters (or optional parameters
104 % only).
105 %
106 %
107 %
108 % \section{Examples}
109 %
110 % \subsection{Example one}
111 %
112 % \begin{verbatim}
113 % \long\def\test@[#1][#2][#3][#4]{%
114 % (#1) (#2) (#3) (#4)
115 % }
116 %
117 % \newcommand{\test}{%
118 % \optparams{\test@}{[one][two][three][four]}%
119 % }
120 % \end{verbatim}
121 % You have now defined a macro |\test| that takes up to four optional
122 % parameters (|#1| to |#4|). You can call this macro as:
123 %
124 % \begin{itemize}
125 % \item |\test[this]|, resulting in |(this) (two) (three) (four)|.
126 %
127 % \item |\test[this][is]|, resulting in |(this) (is) (three) (four)|.
128 %
129 % \item |\test[this][is][a]|, resulting in |(this) (is) (a) (four)|.
130 %
131 % \item |\test[this][is][a][test]|, resulting in |(this) (is) (a) (test)|.
132 %
133 % \end{itemize}
134 % You see that the default parameters defined in |\test| are replaced
135 % one by one by the parameters given when |\test| is called.
136 %
137 %
138 %
139 % \subsection{Example two}
140 %
141 % \begin{verbatim}
142 % \long\def\test@[#1][#2][#3][#4]#5{%
143 % (#1) (#2) (#3) (#4) !#5!
144 % }
145 %
146 % \newcommand{\test}{%
147 % \optparams{\test@}{[one][two][three][four]}%
148 % }
149 % \end{verbatim}
150 % You have now defined a macro |\test| that takes up to four optional
151 % parameters (|#1| to |#4|) and one mandatory parameter (|#5)|. You
152 % can call this macro as:
153 %
154 % \begin{itemize}
155 % \item |\test[this]{foo}|, resulting in
156 % |(this) (two) (three) (four) !foo!|.
157 %
158 % \item |\test[this][is]{foo}|, resulting in
159 % |(this) (is) (three) (four) !foo!|.
160 %
161 % \item |\test[this][is][a]{foo}|, resulting in
162 % |(this) (is) (a) (four) !foo!|.
163 %
164 % \item |\test[this][is][a][test]{foo}|, resulting in
165 % |(this) (is) (a) (test) !foo!|.
166 %
167 % \end{itemize}
168 %
169 %
170 %
171 % \section{Description of the macros}
172 %
173 % \DescribeMacro{\optparams} Usage: |\optparams| \marg{macro}
174 % \marg{default parameters}.
175 %
176 % This macro reads any optional parameters from the input and finally
177 % calls your macro with the optional parameters as well as the
178 % remaining default parameters.
179 %
180 % Each default parameter must have the form |[|\meta{value}|]|. As all
181 % default parameters are passed as one parameter to |\optparams|, they
182 % must be enclosed in braces (|{|\meta{default parameters}|}|).
183 %
184 % The macro that is finally called must have as many optional
185 % parameters as have been defined in the call of |\optparams|; their
186 % form must be |[|\meta{parameter}|]|, where \meta{parameter} is a
187 % number beginning with one and ending with nine.\footnote{This is a
188 % general restriction of \TeX: A macro cannot have more than nine
189 % parameters.} The parameter numbers must be numbered consecutively,
190 % i.e. |[#1][#2][#3]| instead of |[#1][#2][#4]|.
191 %
192 % Because of this special way of declaring macro parameters, you
193 % cannot use |\newcommand| but have to use the \TeX\ primitiv |\def|.
194 % As |\def|, contrary to |\newcommand|, does not warn you when you
195 % overwrite an already existing macro, you first should define the
196 % macro as a dummy using |\newcommand| and then correctly using
197 % |\def|, i.e.:
198 %
199 % \begin{verbatim}
200 % \newcommand{\test@}{}
201 % \long\def\test@[#1][#2][#3][#4]{%
202 % <macro>
203 % }
204 % \end{verbatim}
205 % This way you do not accidentally overwrite an existing macro.
206 %
207 % What does the |\long| do? In \TeX, in order to quicker capture
208 % errors such as missing right braces |}|, parameters of macros
209 % defined using |\def| cannot contain a |\par|, or \TeX\ will complain
210 % (`runaway argument?'). This makes it easier for the user to spot
211 % mistakes, as in that case \TeX\ will stop processing immediately at
212 % the end of the current paragraph and not continue until i.e. the end
213 % of the file before realizing that a macro parameter has not been
214 % closed via |}|.
215 %
216 % But there is a way to make the usage of |\par| as a macro parameter
217 % possible: Using |\long| in front of the |\def|. In \LaTeX,
218 % |\newcommand| defines macros as |\long| by default, and its variant
219 % |\newcommand*| defines macros restricted to `short' parameters. So
220 % as demonstrated in the examples, you should either use |\newcommand|
221 % and |\long\def| together or |\newcommand*| and |\def| in order to
222 % make your macros behave correctly.
223 %
224 %
225 %
226 % \section{Notes}
227 %
228 % \begin{itemize}
229 % \item If you use the notation used in the examples above,
230 % \meta{macroname} for the main macro and
231 % \meta{macroname}|@| for the macro finally called by
232 % |\optparams|, and if you define these macros not in a
233 % package or class, but in your document preamble, you have
234 % to enclose the definitions in |\makeatletter| \ldots\
235 % |\makeatother|, otherwise you cannot use |@| in macro
236 % names.
237 %
238 % \item If you define a macro having only optional parameters (as
239 % in the first example above), you have to make sure the
240 % macro is not called in a context where a |[| follows not
241 % as a parameter, but simply as an opening bracket, i.e.
242 % |\test[foo] [as a side note| \ldots, where the call of
243 % |\test| should have only |[foo]| as its only
244 % parameter. In this case |\optparams| will think that
245 % another optional parameter follows, resulting in chaos.
246 %
247 % To prevent this from happening, insert a |\relax| after
248 % the last optional parameter of the macro call, i.e.
249 % |\test[foo]\relax [as a side note| \ldots\ Then
250 % |\optparams| will stop looking for more optional
251 % parameters.
252 %
253 % \end{itemize}
254 %
255 % \StopEventually{}
256 %
257 %
258 %
259 % \section{Implementation}
260 %
261 % \subsection{Main macros}
262 %
263 % \begin{macro}{\optparams}
264 %
265 % Calls |#1| using a variable number of parameters. Default parameters
266 % are provided in |#2| in the form |[|\meta{param one}|]| |[|\meta{param
267 % two}|]| \ldots
268 %
269 % \begin{macrocode}
270 \newcommand{\optparams}[2]{%
271 \optparams@{#1}{}{#2}%
272 }
273 % \end{macrocode}
274 % \end{macro}
275 %
276 %
277 %
278 % \subsection{Internal macros}
279 %
280 % \begin{macro}{\optparams@}
281 %
282 % Checks if the next character from the input is a |[|. If true calls
283 % |\optparams@@|, as there are still optional parameters left. Otherwise
284 % calls \meta{macro} with \meta{parameters read} and \meta{remaining
285 % default parameters}.
286 %
287 % Usage: |\optparams@| \marg{macro} \marg{parameters read}
288 % \marg{remaining default parameters}.
289 %
290 % \begin{macrocode}
291 \def\optparams@#1#2#3{%
292 \@ifnextchar[{%
293 \optparams@@{#1}{#2}#3\@nil%
294 }{%
295 #1#2#3%
296 }%
297 }
298 % \end{macrocode}
299 % \end{macro}
300 %
301 %
302 % \begin{macro}{\optparams@@}
303 %
304 % Reads the next optional parameter from the input (as |#5| or
305 % \meta{new parameter}). Then gobbles up the corresponding default
306 % parameter (as |#3| or \meta{default for parameter read}, appends the
307 % parameter read to \meta{parameters read} and calls |\optparams@|
308 % again to check for more optional parameters.
309 %
310 % Usage: |\optparams@@| \marg{macro} \marg{parameters read}
311 % \marg{default for parameter read} \marg{remaining default
312 % parameters} \marg{new parameter}.
313 %
314 % \begin{macrocode}
315 \def\optparams@@#1#2[#3]#4\@nil[#5]{%
316 \optparams@{#1}{#2[#5]}{#4}%
317 }
318 % \end{macrocode}
319 % \end{macro}
320 %
321 % Now this is quite a coincidence: Thirteen lines of code, and this
322 % package was begun on Friday, 13th \ldots
323 %
324 % \Finale
325 % \PrintChanges
326 % \PrintIndex
327 \endinput