m15Description

  R E V I S E D    P R E L I M I N A R Y    S P E C I F I C A T I O N

					   Due 2:00 AM, Friday, 02 October 2015
					   
CPSC 323   Homework #2   A TeX-like Macro Processor

(60 points) The basic function of the macro processor

  m15 [file]*

is to copy to the standard output the contents of the file(s) specified on the
command line (or the standard input when no files are specified).  However,
as the input is read, certain strings of characters (which specify macro
expansion) are replaced by other strings of characters according to macro
instructions contained in the input.  Aside: m15 belongs to the same family
of software as the C preprocessor, shell and makefile variable expansion, and
the TeX text formatting system.

Some macros are built in.  New macros are defined using the \def macro

  \def{NAME}{VALUE}

which is replaced by the empty string.  Here NAME is a nonempty alphanumeric
string and VALUE is a brace-balanced string (i.e., the number of left braces is
greater than or equal to the number of right braces in every prefix and equal
in the entire string).

Thereafter, strings of the form \NAME{ARG}, where ARG is a brace-balanced
string, are replaced by the string VALUE, with each occurrence of the character
# replaced by the string ARG.

A previously defined macro can be undefined with the \undef macro

  \undef{NAME}

which is replaced by the empty string.

Text can be included conditionally with the \ifdef macro

  \ifdef{NAME}{THEN}{ELSE}

which is replaced by the brace-balanced string THEN if NAME is a defined macro
and by the brace-balanced string ELSE otherwise; and with the \if macro:

  \if{VALUE}{THEN}{ELSE}

which is replaced by the brace-balanced string THEN if VALUE is a nonempty
string and by the brace-balanced string ELSE otherwise.

The \include macro

  \include{PATH}

is replaced by the contents of the file PATH (whose name must be brace-
balanced).

The \expandafter macro

  \expandafter{BEFORE}{AFTER}

is replaced by the string BEFORE followed by the output from running m15
(recursively) on the string AFTER, using and modifying the current list of
defined macros.

After each substitution "copying" resumes at the START of the replacement
string.  Note that brace-balanced arguments are not processed until they are
expanded.

To allow comments in the input, the character % causes m15 to ignore it and all
subsequent characters up to the first non-blank, non-tab character following
the next newline or the end of the current file, whichever comes first.  This
convention applies only when reading characters from the file(s) specified on
the command line (or the standard input if none is specified) or from an
\include-d file, but not when calling m15 recursively while expanding the
\expandafter macro.

The \ character can also be used to "escape" a following \, #, %, {, or }
so that it is not treated as a special character.  The effect of the \ is
preserved until it is about to be output, at which point it is suppressed
and the \, #, %, {, or } is output instead.

i.e., in effect the \ is ignored and the following character is treated as a
non-special character thereafter.  That is, in effect the pair of characters
is treated as a macro with no arguments until it is expanded and output.

When m15 detects errors, either

* parsing errors (e.g., NAME is not a nonempty alphanumeric string or \NAME is
  not immediately followed by {ARG}, where ARG is a brace-balanced string) or

* semantic errors (e.g., NAME is not the name of a macro or there is an attempt
  to redefine a macro or undefine a nonexistent macro),

it writes a one-line message to stderr and exits.

m15 need not detect cyclical macro definitions or \include macro instructions;
infinite \expandafter loops; or attempts to define a macro with the same name
as that of a built-in macro.