summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/newcommand/newcommand.tex
blob: 4f4265c23765eb79e5d67ec6d31ce025db7d605a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
\documentclass{ltxdoc}
\usepackage[T1]{fontenc}
\usepackage{tabularx}
\usepackage{syntax}
\usepackage{varioref}
\usepackage{color}
\usepackage{booktabs}
\usepackage{alltt}
\usepackage{textcomp}
\usepackage[bookmarksopen=true]{hyperref}

% Define this document's metadata.
\def\ncfileversion{2.0}
\def\ncfiledate{2010/06/01}

\title{The \textsf{newcommand.py} utility\thanks{\textsf{newcommand.py}
         has version number \ncfileversion, last revised \ncfiledate.}}
\author{\href{mailto:scott+nc@pakin.org}{Scott Pakin} \\
        \href{mailto:scott+nc@pakin.org}{scott+nc@pakin.org}}
\date{\ncfiledate}
\hypersetup{%
  pdftitle={The newcommand.py utility},
  pdfauthor={Scott Pakin <scott+nc@pakin.org>},
  pdfsubject={Creating user-defined macros with more flexible argument
    processing},
  pdfkeywords={LaTeX macros, optional arguments, newcommand, parenthesized
    arguments, starred commands, Python}
}

% Help prevent weird line breaks in URLs
\def\UrlBreaks{}
\def\UrlBigBreaks{\do/}

% Define some useful shortcuts.
\newcommand*{\ncpy}{\texttt{newcommand.py}}      % The name of the script
\newcommand*{\usercmd}[1]{\textcolor{blue}{#1}}  % User command entry
\newcommand{\prototype}[1]{{%                    % Prompt and user entry
  \bigskip
  \noindent
  \ttfamily\small\raggedright
  \hangafter=1\hangindent=4em
  ~~~~\% Prototype:~\textcolor{blue}{#1}\strut\par
  \vspace*{-0.5\baselineskip}%
}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}
\maketitle
\sloppy

\begin{abstract}
  \LaTeX's \cs{newcommand} is fairly limited in the way it processes
  optional arguments, but the \TeX\ alternative, a batch of \cs{def}s
  and \cs{futurelet}s, can be overwhelming to the casual \LaTeX\ user.
  \ncpy\ is a Python program that automatically generates
  \LaTeX\ macro definitions for macros that require more powerful
  argument processing than \cs{newcommand} can handle.  \ncpy\ is
  intended for \LaTeX\ advanced beginners (i.e., those who know how to
  use \cs{newcommand} but not internal \LaTeXe\ macros like
  |\@ifnextchar|) and for more advanced users who want to save some
  typing when defining complex macros.
\end{abstract}

\section{Introduction}

\LaTeX's \cs{newcommand} is a rather limited way to define new macros.
Only one argument can be designated as optional, it must be the first
argument, and it must appear within square brackets.  Defining macros
that take multiple optional arguments or in which an optional argument
appears in the middle of the argument list is possible but well beyond
the capabilities of the casual \LaTeX\ user.  It requires using
\TeX\ primitives such as \cs{def} and \cs{futurelet} and/or
\LaTeXe\ internal macros such as \cs{@ifnextchar}.

\ncpy\ is a Python program that reads a specification of an argument
list and automatically produces \LaTeX\ code that processes the
arguments appropriately.  \ncpy\ makes it easy to define
\LaTeX\ macros with more complex parameter parsing than is possible
with \cs{newcommand} alone.  Note that you do need to have Python
installed on your system to run \ncpy.  Python is freely available for
download from \url{http://www.python.org/}.

To define a \LaTeX\ macro, one gives \ncpy\ a macro description
written in a simple specification language.  The description
essentially lists the required and optional arguments and, for each
optional argument, the default value.  The next section of this
document describes the syntax and provides some examples, but for now,
let's look at how one would define the most trivial macro possible,
one that takes no arguments.  Enter the following at your operating
system's prompt:

\begin{alltt}
    \usercmd{newcommand.py "MACRO trivial"}
\end{alltt}

\noindent
(Depending on your system, you may need to prefix that command with
``|python|''.)  The program should output the following \LaTeX\ code
in response:

\begin{verbatim}
    % Prototype: MACRO trivial
    \newcommand{\trivial}{%
      % Put your code here.
    }
\end{verbatim}

\noindent
Alternatively, you can run \ncpy\ interactively, entering macro
descriptions at the ``|% Prototype:|'' prompt:

\prototype{MACRO trivial}
\begin{verbatim}
    \newcommand{\trivial}{%
      % Put your code here.
    }
    % Prototype:
\end{verbatim}

\noindent
Enter your operating system's end-of-file character (Ctrl-D in Unix or
Ctrl-Z in Windows) to exit the program.

While you certainly don't need \ncpy\ to write macros that are as
trivial as \cs{trivial}, the previous discussion shows how to run the
program and the sort of output that you should expect.  There will
always be a ``\texttt{Put your code here}'' comment indicating where
you should fill in the actual macro code.  At that location, all of
the macro's parameters---both optional and required---will be defined
and can be referred to in the ordinary way: |#1|, |#2|, |#3|, etc.


\section{Usage}

As we saw in the previous section, macros are defined by the word
``|MACRO|'' followed by the macro name, with no preceding backslash.
In this section we examine how to specify increasingly sophisticated
argument processing using \ncpy.


\subsection{Required arguments}

Required arguments are entered as~|#1|, |#2|, |#3|, \dots, with no
surrounding braces:

\prototype{MACRO required \#1 \#2 \#3 \#4 \#5}
\begin{verbatim}
    \newcommand{\required}[5]{%
      % Put your code here.
      % You can refer to the arguments as #1 through #5.
    }
\end{verbatim}

Parameters must be numbered in monotonically increasing order,
starting with~|#1|.  Incorrectly ordered parameters will produce an
error message:

\prototype{MACRO required \#1 \#3 \#4}
\begin{verbatim}
                                   ^
    newcommand.py: Expected parameter 2 but saw parameter 3.
\end{verbatim}


\subsection{Optional arguments}

Optional arguments\label{par:optional-args} are written as either
``|OPT[|\meta{param}|=|\linebreak[1]|{|\meta{default}|}]|'' or
``|OPT(|\meta{param}|=|\linebreak[1]|{|\meta{default}|})|''.  In the
former case, square brackets are used to offset the optional argument;
in the latter case, parentheses are used.  \meta{param} is the
parameter number (|#1|, |#2|, |#3|, \dots), and \meta{default} is the
default value for that parameter.  Note that curly braces are required
around \meta{default}.

\prototype{MACRO optional OPT[\#1=\{maybe\}]}
\begin{verbatim}
    \newcommand{\optional}[1][maybe]{%
      % Put your code here.
      % You can refer to the argument as #1.
    }
\end{verbatim}

Up to this point, the examples have been so simple that \ncpy\ is
overkill for entering them.  We can now begin specifying constructs
that \LaTeX's \cs{newcommand} can't handle, such as a parenthesized
optional argument, an optional argument that doesn't appear at the
beginning of the argument list, and multiple optional arguments:

\prototype{MACRO parenthesized OPT(\#1=\{abc\})}
\begin{verbatim}
    \makeatletter
    \newcommand{\parenthesized}{%
      \@ifnextchar({\parenthesized@i}{\parenthesized@i({abc})}%
    }

    \def\parenthesized@i(#1){%
      % Put your code here.
      % You can refer to the argument as #1.
    }
    \makeatother
\end{verbatim}


\prototype{MACRO nonbeginning \#1 OPT[\#2=\{abc\}]}
\begin{verbatim}
    \makeatletter
    \newcommand{\nonbeginning}[1]{%
      \@ifnextchar[{\nonbeginning@i{#1}}{\nonbeginning@i{#1}[{abc}]}%
    }

    \def\nonbeginning@i#1[#2]{%
      % Put your code here.
      % You can refer to the arguments as #1 and #2.
    }
    \makeatother
\end{verbatim}

\prototype{MACRO multiple OPT[\#1=\{abc\}] OPT[\#2=\{def\}]}
\begin{verbatim}
    \makeatletter
    \newcommand{\multiple}[1][abc]{%
      \@ifnextchar[{\multiple@i[{#1}]}{\multiple@i[{#1}][{def}]}%
    }

    \def\multiple@i[#1][#2]{%
      % Put your code here.
      % You can refer to the arguments as #1 and #2.
    }
    \makeatother
\end{verbatim}

The template for optional arguments that was
shown~\vpageref[above]{par:optional-args} stated that optional
arguments contain a ``\meta{param}|={|\meta{default}|}|''
specification.  In fact, optional arguments can contain
\emph{multiple} ``\meta{param}|={|\meta{default}|}|'' specifications,
as long as they are separated by literal text:

\prototype{MACRO multiopt OPT(\#1=\{0\},\#2=\{0\})}
\begin{verbatim}
    \makeatletter
    \newcommand{\multiopt}{%
      \@ifnextchar({\multiopt@i}{\multiopt@i({0},{0})}%
    }

    \def\multiopt@i(#1,#2){%
      % Put your code here.
      % You can refer to the arguments as #1 and #2.
    }
    \makeatother
\end{verbatim}

\noindent
In that example, \cs{multiopt} takes an optional parenthesized
argument.  If omitted, it defaults to |(0,0)|.  If provided, the
argument must be of the form ``|(|\meta{x}|,|\meta{y}|)|''.  In either
case, the comma-separated values within the parentheses are parsed
into~|#1| and~|#2|.  Contrast that with the following:

\prototype{MACRO multiopt OPT(\#1=\{0,0\})}
\begin{verbatim}
    \makeatletter
    \newcommand{\multiopt}{%
      \@ifnextchar({\multiopt@i}{\multiopt@i({0,0})}%
    }

    \def\multiopt@i(#1){%
      % Put your code here.
      % You can refer to the argument as #1.
    }
    \makeatother
\end{verbatim}

The optional argument still defaults to |(0,0)|, but |#1| receives
\emph{all} of the text that lies between the parentheses;
\cs{multiopt} does not parse it into two comma-separated values
in~|#1| and~|#2|, as it did in the previous example.

\bigskip

The \meta{default} text in an |OPT| term can reference any macro
parameter introduced before the |OPT|\@.  Hence, the following defines
a macro that accepts a required argument followed by an optional
argument.  The default value of the optional argument is the value
provided for the required argument:

\prototype{MACRO paramdefault \#1 OPT[\#2=\{\#1\}]}
\begin{verbatim}
    \makeatletter
    \newcommand{\paramdefault}[1]{%
      \@ifnextchar[{\paramdefault@i{#1}}{\paramdefault@i{#1}[{#1}]}%
    }

    \def\paramdefault@i#1[#2]{%
      % Put your code here.
      % You can refer to the arguments as #1 and #2.
    }
    \makeatother
\end{verbatim}


\subsection{Literal text}

In addition to required and optional parameters, it is also possible
to specify text that must appear literally in the macro call.  Merely
specify it within curly braces:

\prototype{MACRO textual \#1 \{ and \} \#2 \{.\}}
\begin{verbatim}
    \makeatletter
    \newcommand{\textual}[1]{%
      \textual@i{#1}%
    }

    \def\textual@i#1 and #2.{%
      % Put your code here.
      % You can refer to the arguments as #1 and #2.
    }
    \makeatother
\end{verbatim}

\noindent
A macro such as \cs{textual} can be called like this:

\begin{verbatim}
    \textual {Milk} and {cookies}.
\end{verbatim}

\noindent
Actually, in that example, because both |Milk| and |cookies| are
delimited on the right by literal text, \TeX\ can figure out how to
split \cs{textual}'s argument into~|#1| and~|#2| even if the curly
braces are omitted:

\begin{verbatim}
    \textual Milk and cookies.
\end{verbatim}

\subsection{Starred macros}

The names of some \LaTeX\ macros can be followed by an optional
``|*|'' to indicate a variation on the normal processing.  For
example, \cs{vspace}, which introduces a given amount of vertical
space, discards the space if it appears at the top of the page.
|\vspace*|, in contrast, typesets the space no matter where it
appears.  \ncpy\ makes it easy for users to define their own starred
commands:

\prototype{MACRO starred * \#1 \#2}
\begin{verbatim}
    \makeatletter
    \newif\ifstarred@star
    \newcommand{\starred}{%
      \@ifstar{\starred@startrue\starred@i*}{\starred@starfalse\starred@i*}%
    }

    \def\starred@i*#1#2{%
      \ifstarred@star
        % Put code for the "*" case here.
      \else
        % Put code for the non-"*" case here.
      \fi
      % Put code common to both cases here (and/or above the \ifstarred@star).
      % You can refer to the arguments as #1 and #2.
    }
    \makeatother
\end{verbatim}

\noindent
Note that unlike the generated code shown up to this point, the code
for starred macros includes \emph{multiple} placeholders for user
code.

The ``|*|'' in a starred macro does not have to immediately follow the
macro name; it can appear anywhere in the macro specification.
However, \ncpy\ currently limits macros to at most one asterisk.

Embedding an asterisk within curly braces causes it to be treated not
as an optional character but as (required) literal text.  Contrast the
preceding example with the following one:

\prototype{MACRO starred \{*\} \#1 \#2}
\begin{verbatim}
    \makeatletter
    \newcommand{\starred}{%
      \starred@i%
    }

    \def\starred@i*#1#2{%
      % Put your code here.
      % You can refer to the arguments as #1 and #2.
    }
    \makeatother
\end{verbatim}

The asterisk in that definition of \cs{starred} must be included in
every macro invocation or \TeX\ will abort with a ``\texttt{Use of
  \string\starred@i doesn't match its definition}'' error.


\subsection{More than nine arguments}

\TeX\ imposes a limit of nine arguments per macro.  Internally,
``|#|'' is expected to be followed by exactly one digit, which means
that ``|#10|'' refers to argument~|#1| followed by the character~|0|.
Fortunately, it's rare that a macro needs more than nine arguments and
rarer still that those arguments are not better specified as a list of
\meta{key}|=|\meta{value} pairs, as supported by the \textsf{keyval}
package and many other \LaTeX\ packages.

If large numbers of arguments are in fact necessary, \ncpy\ does let
you specify them.  The trick that the generated code uses is to split
the macro into multiple macros, each of which takes nine or fewer
arguments and stores the value of each argument in a variable that can
later be accessed.  Because digits are awkward to use in macro names,
\ncpy\ uses roman numerals to name arguments in the case of more than
nine arguments: |\|\meta{name}|@arg@i| for |#1|,
|\|\meta{name}|@arg@ii| for |#2|, |\|\meta{name}|@arg@iii| for |#3|,
|\|\meta{name}|@arg@iv| for |#4|, and so forth.  The following example
takes 14 required arguments and one optional argument (which defaults
to the string ``|etc|''):

\prototype{MACRO manyargs \#1 \#2 \#3 \#4 \#5 \#6 \#7 \#8 \#9 \#10
  \#11 \#12 \#13 \#14 OPT[\#15=\{etc\}]}
\begin{verbatim}
    \makeatletter
    \newcommand{\manyargs}[9]{%
      \def\manyargs@arg@i{#1}%
      \def\manyargs@arg@ii{#2}%
      \def\manyargs@arg@iii{#3}%
      \def\manyargs@arg@iv{#4}%
      \def\manyargs@arg@v{#5}%
      \def\manyargs@arg@vi{#6}%
      \def\manyargs@arg@vii{#7}%
      \def\manyargs@arg@viii{#8}%
      \def\manyargs@arg@ix{#9}%
      \manyargs@i
    }

    \def\manyargs@i#1#2#3#4#5{%
      \def\manyargs@arg@x{#1}%
      \def\manyargs@arg@xi{#2}%
      \def\manyargs@arg@xii{#3}%
      \def\manyargs@arg@xiii{#4}%
      \def\manyargs@arg@xiv{#5}%
      \@ifnextchar[{\manyargs@ii}{\manyargs@ii[{etc}]}%
    }

    \def\manyargs@ii[#1]{%
      \def\manyargs@arg@xv{#1}%
      % Put your code here.
      % You can refer to the arguments as \manyargs@arg@i through \manyargs@arg@xv.
    }
    \makeatother
\end{verbatim}

The current version of \ncpy\ is limited to 4000 arguments, which
should be more than enough for most purposes.


\subsection{Summary}

A macro is defined in \ncpy\ with:

\begin{center}
  \texttt{MACRO} \meta{name} \meta{arguments}
\end{center}

\noindent
in which \meta{name} is the name of the macro, and \meta{arguments} is
zero or more of the following:

\begin{center}
\renewcommand{\arraystretch}{1.1}
\begin{tabularx}{\linewidth}{@{}lXl@{}}
  \toprule
  \multicolumn{1}{@{}c}{Argument} &
  \multicolumn{1}{c}{Meaning} &
  \multicolumn{1}{c@{}}{Example} \\
  \midrule

  |#|\meta{number} & Parameter (required) & |#1| \\
  \marg{text}      & Literal text (required)     & |{+}| \\
  |OPT[#|\meta{number}|=|\marg{text}|]| & Parameter (optional, with default) &
    |OPT[#1={tbp}]| \\
  |OPT(#|\meta{number}|=|\marg{text}|)| & Same as the above, but with
    parentheses instead of brackets & |OPT(#1={tbp})| \\
  |*|              & Literal asterisk (optional) & |*| \\
  \bottomrule
\end{tabularx}
\end{center}

Within an |OPT| argument, |#|\meta{number}|=|\marg{text} can be
repeated any number of times, as long as the various instances are
separated by literal text.


\section{Further examples}

\subsection{Mimicking \LaTeX's \texttt{picture} environment}

The \LaTeX\ |picture| environment takes two, parenthesized,
coordinate-pair arguments, the second pair being optional.  Here's how
to define a macro that takes the same arguments as the |picture|
environment and parses them into $x_1$, $y_1$, $x_2$, and~$y_2$
(i.e.,~|#1|--|#4|):

\prototype{MACRO picturemacro \{(\}\#1\{,\}\#2\{)\} OPT(\#3=\{0\},\#4=\{0\})}
\begin{verbatim}
    \makeatletter
    \newcommand{\picturemacro}{%
      \picturemacro@i%
    }

    \def\picturemacro@i(#1,#2){%
      \@ifnextchar({\picturemacro@ii({#1},{#2})}{\picturemacro@ii({#1},{#2})({0},{0})}%
    }

    \def\picturemacro@ii(#1,#2)(#3,#4){%
      % Put your code here.
      % You can refer to the arguments as #1 through #4.
    }
    \makeatother
\end{verbatim}

The first pair of parentheses and the comma are quoted because they
represent required, literal text.


\subsection{Mimicking \LaTeX's \texttt{\string\parbox} macro}

\LaTeX's \cs{parbox} macro takes three optional arguments and two
required arguments.  Furthermore, the third argument defaults to
whatever value was specified for the first argument.  This is easy to
express in \LaTeX\ with the help of \ncpy:

\prototype{MACRO parboxlike OPT[\#1=\{s\}] OPT[\#2=\{\string\relax\}]
  OPT[\#3=\{\#1\}] \#4 \#5}
\begin{verbatim}
    \makeatletter
    \newcommand{\parboxlike}[1][s]{%
      \@ifnextchar[{\parboxlike@i[{#1}]}{\parboxlike@i[{#1}][{\relax}]}%
    }

    \def\parboxlike@i[#1][#2]{%
      \@ifnextchar[{\parboxlike@ii[{#1}][{#2}]}{\parboxlike@ii[{#1}][{#2}][{#1}]}%
    }

    \def\parboxlike@ii[#1][#2][#3]#4#5{%
      % Put your code here.
      % You can refer to the arguments as #1 through #5.
    }
    \makeatother
\end{verbatim}


\subsection{Dynamically changing argument formats}
\label{sec:dynamic-args}

With a little cleverness, it is possible for a macro to accept one of
two completely different sets of arguments based on the values
provided for earlier arguments.  For example, suppose we want to
define a macro, \cs{differentargs} that can be called as either

\begin{verbatim}
    \differentargs*[optarg]{reqarg}
\end{verbatim}

\noindent
or

\begin{verbatim}
    \differentargs{reqarg}(optarg)
\end{verbatim}

\noindent
That is, the presence of an asterisk determines whether
\cs{differentargs} should expect an optional argument in square
brackets followed by a required argument or to expect a required
argument followed by an optional argument in parentheses.

The trick is to create two helper macros: one for the ``|*|'' case
(\cs{withstar}) and the other for the non-``|*|'' case
(\cs{withoutstar}).  \cs{differentargs} can then invoke one of
\cs{withstar} or \cs{withoutstar} based on whether or not it sees an
asterisk.  The following shows how to use \ncpy\ to define
\cs{differentargs}, \cs{withstar}, and \cs{withoutstar} and how to
edit \cs{differentargs} to invoke its helper macros:

\prototype{MACRO differentargs *}
\begin{verbatim}
    \makeatletter
    \newif\ifdifferentargs@star
    \newcommand{\differentargs}{%
      \@ifstar{\differentargs@startrue\differentargs@i*}
              {\differentargs@starfalse\differentargs@i*}%
    }
\end{verbatim}
\begingroup
\small
\begin{alltt}
    \cs{def}\cs{differentargs@i}*\{%
      \cs{ifdifferentargs@star}
        % Put code for the "*" case here.
        \colorbox{yellow}{\cs{let}\cs{next}=\cs{withstar}}
      \cs{else}
        % Put code for the non-"*" case here.
        \colorbox{yellow}{\cs{let}\cs{next}=\cs{withoutstar}}
      \cs{fi}
      % Put code common to both cases here (and/or above the \cs{ifdifferentargs@star}).
      \colorbox{yellow}{\cs{next}}
    \}
    \cs{makeatother}
\end{alltt}
\endgroup

\prototype{MACRO withstar OPT[\#1=\{starry\}] \#2}
\begin{verbatim}
    \newcommand{\withstar}[2][starry]{%
      % Put your code here.
      % You can refer to the arguments as #1 and #2.
    }
\end{verbatim}

\prototype{MACRO withoutstar \#1 OPT(\#2=\{dark\})}
\begin{verbatim}
    \makeatletter
    \newcommand{\withoutstar}[1]{%
      \@ifnextchar({\withoutstar@i{#1}}{\withoutstar@i{#1}({dark})}%
    }

    \def\withoutstar@i#1(#2){%
      % Put your code here.
      % You can refer to the arguments as #1 and #2.
    }
    \makeatother
\end{verbatim}

Note that we edited \cs{differentargs@i} to let \cs{next} be
equivalent to either \cs{withstar} or \cs{withoutstar} based on
whether an asterisk was encountered.  \cs{next} is evaluated outside
of the \cs{ifdifferentargs@star}\dots\linebreak[0]\cs{fi} control
structure.  This rigmarole is necessary because directly calling
\cs{withstar} or \cs{withoutstar} would cause those macros to see
\cs{ifdifferentargs@star}'s \cs{else} or \cs{fi} as their first
argument when they ought to see the text following the
\cs{differentargs} call.


\section{Grammar}

The following is the formal specification of \ncpy's grammar, written
in a more-or-less top-down manner.  Literal values, shown in a
typewriter font, are case-sensitive.  \meta{letter} refers to a letter
of the (English) alphabet.  \meta{digit} refers to a digit.

\setlength{\grammarindent}{7em}
\begin{grammar}
<decl> ::= \[[ "MACRO" <ident> <arglist> \]]

<ident> ::= \[[ \begin{rep} <letter> \end{rep} \]]

<arglist> ::= \[[ \begin{rep} \\ <arg> \end{rep} \]]

<arg> ::= \[[
              \begin{stack}
                <formal> \\
                <quoted> \\
                <optarg> \\
                "*"
              \end{stack}
          \]]

<formal> ::= \[[ "#" \begin{rep} <digit> \end{rep} \]]

<quoted> ::= \[[ "{" <rawtext> "}" \]]

<rawtext> ::= \[[ \begin{rep} \tok{anything except a "{", "}", or "\#"} \end{rep} \]]

<optarg> ::= \[[ "OPT" <delim> <defvals> <delim> \]]

<delim> ::= \[[ \begin{stack} "[" \\ "]" \\ "(" \\ ")" \end{stack} \]]

<defvals> ::= \[[
                  \begin{rep}
                    <defval> \\
                    \begin{stack}
                      <quoted> \\
                      <rawtext>
                    \end{stack}
                  \end{rep}
              \]]

<defval> ::= \[[ <formal> "=" <quoted> \]]
\end{grammar}


\section{Acknowledgements}

I'd like to say thank you to the following people:

\begin{itemize}
  \item John Aycock for writing the
    \href{http://pages.cpsc.ucalgary.ca/~aycock/spark/}{Scanning,
      Parsing, and Rewriting Kit (SPARK)}---the lexer and parser
    underlying \ncpy---and making it freely available and
    redistributable.

  \item Hendri Adriaens for pointing out a bug in the code generated
    by \ncpy.  Previously, bracketed text within a mandatory argument
    could be mistaken for an optional argument.

  \item Tom Potts for reporting a spurious error message caused by the
    processing of |OPT|.  This bug has now been fixed.  Tom Potts also
    proposed the example used in Section~\ref{sec:dynamic-args} in
    which the starred and unstarred versions of a macro take different
    arguments.
\end{itemize}


\section{Copyright and license}

Copyright~\copyright{} 2010, Scott Pakin

\bigskip

This package may be distributed and/or modified under the conditions
of the \LaTeX{} Project Public License, either version~1.3c of this
license or (at your option) any later version.  The latest version of
this license is in:

\begin{center}
  \url{http://www.latex-project.org/lppl.txt}
\end{center}

\noindent
and version~1.3c or later is part of all distributions of \LaTeX{}
version 2006/05/20 or later.

\end{document}