(eplain.info)Macro arguments

---

Next: Converting to characters Prev: Iteration Up: Programming definitions

---

Enter node , (file) or (file)node

7.4 Macro arguments
===================

It is occasionally useful to redefine a macro that takes arguments to do
nothing. Eplain defines '\gobble', '\gobbletwo', and '\gobblethree' to
swallow one, two, and three arguments, respectively.

   For example, if you want to produce a "short" table of contents--one
that includes only chapters, say--the easiest thing to do is read the
entire '.toc' file (Note: Contents), and just ignore the commands that
produce section or subsection entries. To be specific:

     \let\tocchapterentry = \shorttocchapter
     \let\tocsectionentry = \gobbletwo
     \let\tocsubsectionentry = \gobbletwo
     \readtocfile

(Of course, this assumes you only have chapters, sections, and
subsections in your document.)

   In addition, Eplain defines '\eattoken' to swallow the single
following token, using '\let'. Thus, '\gobble' followed by '{...}'
ignores the entire brace-enclosed text. '\eattoken' followed by the same
ignores only the opening left brace.

   Eplain defines a macro '\identity' which takes one argument and
expands to that argument. This may be useful if you want to provide a
function for the user to redefine, but don't need to do anything by
default. (For example, the default definition of '\eqconstruct' (Note:
Formatting equation references) is '\identity'.)

   You may also want to read an optional argument. The established
convention is that optional arguments are put in square brackets, so
that is the syntax Eplain recognizes. Eplain ignores space tokens before
and after optional arguments, via '\futurenonspacelet'.

   You test for an optional argument by using '\@getoptionalarg'. It
takes one argument, a control sequence to expand after reading the
argument, if present. If an optional argument is present, the control
sequence '\@optionalarg' expands to it; otherwise, '\@optionalarg' is
'\empty'. You must therefore have the category code of '@' set to 11
(letter). Here is an example:

     \catcode`@=\letter
     \def\cmd{\@getoptionalarg\finishcmd}
     \def\finishcmd{%
       \ifx\@optionalarg\empty
         % No optional argument present.
       \else
         % One was present.
       \fi
     }

   It's possible to define macros that appear to accept optional
arguments intermixed with mandatory arguments in any imaginable way. For
example:

     \makeatletter
     % \mo{m}[o]
     \def\mo#1{\def\mo@arg{#1}\@getoptionalarg\fin@mo}
     \def\fin@mo{\vskip1pc
       ARG:    \mo@arg       \par
       OPTARG: \@optionalarg \par
     }
     % \mom{m}[o]{m}
     \def\mom#1{\def\mom@arg{#1}\@getoptionalarg\fin@mom}
     \def\fin@mom#1{\vskip1pc
       ARG1:   \mom@arg      \par
       OPTARG: \@optionalarg \par
       ARG2:   #1\par
     }
     % \omo[o]{m}[o]
     \def\omo{\@getoptionalarg\fin@omo}
     \def\fin@omo#1{\let\omo@optarg\@optionalarg
                    \def\omo@arg{#1}\@getoptionalarg\@fin@omo}
     \def\@fin@omo{\vskip1pc
       OPTARG1: \omo@optarg   \par
       ARG:     \omo@arg      \par
       OPTARG2: \@optionalarg \par
     }
     \makeatother

   If an optional argument contains another optional argument, the inner
one will need to be enclosed in braces, so TeX does not mistake the end
of the first for the end of the second.