This file describes the syntax for @-introduced control sequences.  If
you haven't read the README and Differences files yet, do so; otherwise
this file won't make a whole lot of sense.

Something a little like BNF is used here; in particular, {W} represents
exactly one space or tab; {W+} is one or more such; {W*} is zero or
more such; and {W?} is zero or one such.

Trailing newlines are always explicitly represented.

It is also assumed you are familiar with the standard /lib/cpp
preprocessor.

The controls that can be introduced with an @ sign are as follows.
Note that you must explicitly enable them for @ signs to be recognized.

	@include{W*}"filename"
	@include{W*}<filename>

Include the named file in place of the input text from the @ sign to
the closing delimiter.  The difference between "" and <> is that ""
files are searched for first in the directory the input file was found
in; the two forms are otherwise identical (for example, if -I. was
given then they are equivalent).

	@define{W+}name{W?}...replacement text...@
	@define{W+}name(...args...)...replacement text...@

This defines the named macro, much as #define would.  However, the end
of the macro is marked not by an unbackslashed newline but by a single
@ sign.  @ signs can appear in the replacement text, but they must be
doubled.  The definition terminates with the last character before the
first @ sign that is not immediately followed by another @ sign.  The
trailing @ sign is eaten; the character after it is part of the normal
input stream.

	@undef{W+}name

Removes any definition the named macro may have.  The character
terminating the name (which therefore must be non-alphanumeric and not
a $ or _) is part of the normal input stream.

	@redefine

This is exactly the same as @define, except that its usage suppresses
any warning about "...., line ...: .... redefined".

	@ifdef{W+}name
	@ifndef{W+}name

These behave much the same as their #-sign cousins, except for a note
similar to @undef above: the character which terminates the name is
part of the input stream.

	@if{W+}(expression)

This is the same as #if except that the expression must be contained in
parentheses (so that the preprocessor knows for sure when it's read it
all).

	@else

This behaves just like #else, except for the note that the character
after the "else" is part of the normal input stream.

	@elif{W+}(expression)

This is #elif what @if is to #if, an "else if" facility.  The notes for
"if" apply here as well.

	@endif

Behaves like #endif, with the usual note about the character that
terminates the macro name being part of the input stream.  In fact, you
can use @endif to end an if that began with #if and vice versa - the
preprocessor does not distinguish between the two kinds of if.

	@set{W+}name{W+}(expression)

This is sort of an evaluated definition.  The expression is evaluated
and the name is defined as the result (converted to a string in
decimal).  This facility allows the usage of macros as variables in the
preprocessor.

	@while{W+}(expression)

This begins a looping construct.  The text from just after the closing
parenthesis on the expression until the matching @endwhile is
repeatedly scanned until the expression evaluates to zero.  The
expression is evaluted before scanning the text each time through;
thus, for example, the body may be scanned zero times.  The body may
contain anything, including definitions or re-definitions of macros.
Most usefully, it can be something like

printf("...." @set i (0) @while (i<20) ,array[i] @set i (i+1) @endwhile );

Note the placement of the comma inside the while loop....be careful.
It is also very easy to forget to increment the loop variable, which
will of course throw the preprocessor into an infinite loop.

The loop need not be as simplistic as this; for example

@set DEBUG_LEVEL (0)
@while (!defined(FOO))
@include "some-file"
@set DEBUG_LEVEL (DEBUG_LEVEL+1)
@endwhile

which keeps incrementing DEBUG_LEVEL until the file defines FOO.

	@endwhile

This terminates the @while construction.  See @while for details.  I
have gone to some trouble to ensure that correct line numbers are
emitted when while loops are involved, even when the @while and
@endwhile are in different files, at different include nesting levels,
etc.

	@dump

This is a debugging aid.  It produces a dump of all macros and their
replacement texts on stderr (NOT the normal preprocessor output
stream).  This dump is intended for human-readability, but will be
pretty useless unless you know the preprocessor fairly well.

	@debug{W+}<c>

The <c> represents the first non-whitespace, non-newline character
after the @debug.  If this character is '1', 'y', or 'Y', debugging is
turned on.  This enables certain messages depending on compile-time
options.  These messages change with what problems have been happening
recently, so I can hardly provide a list here - especially since it
would be out of date by the time you read this.  You will have to read
the source.  (Which isn't so bad, considering that the messages
themselves are so cryptic as to be useless unless you have to debug the
preprocessor.)

	@eval{W+}(expression)

This provides access to the mechanism used by @set, @if, etc to
evaluate expressions.  The expression is evaluated and the resulting
number is converted to decimal.  The resulting string is pushed back
into the input.

	Anything else

Anything else following an @ sign is an error unless the preprocessor
is currently inside a false #if (or @if), in which case anything goes.
