Accept Action

The accept action is one of the four actions of a
traditional ©parsing engineª. The accept action is
performed when the ©parserª has succeeded in identifying
the goal, or ©grammar tokenª for the ©grammarª.  When
the parser executes the accept action, it sets the ©exit_flagª
field in the ©parser control blockª to AG_SUCCESS_CODE and returns
to the calling program. The accept action is thus the last action of
the parsing engine and occurs only once for each successful execution
of the parser.

If the grammar token has a non-void value, you may
obtain its value by calling the ©parser value functionª
whose name is given by <parser name>_value, that is,
by appending "_value" to the ©parser nameª.
##

Parser Value Function, Return Value

The value assigned to the ©grammar tokenª in your parser
may be retrieved by calling the parser value function after
the parser has finished. The name of this function is given
by <©parser nameª>_value. The return type of the function
is the type assigned to the grammar token.

If you have set the ©reentrant parserª switch, the parser
value function takes a pointer to the ©parser control blockª
as its sole argument. Otherwise, it takes no arguments. The
value function is not defined if the grammar token has type "void".
##

AG_PLACEMENT_DELETE_REQUIRED

When the ©wrapperª option is specified, the wrapper
template class that AnaGram defines uses a "placement
new" operator to construct the wrapper object on the
©parser value stackª. The MSVC++ 6.0 compiler requires,
in this situation, that a corresponding "placement
delete" operator be defined. Other C++ compilers,
notably MSVC++ 5.0, generate an error message if
they encounter the definition of a "placement delete"
operator.

Accordingly, AG_PLACEMENT_DELETE_REQUIRED is used to determine
whther a "placement delete" operator should be defined.

AG_PLACEMENT_DELETE_REQUIRED is defined to be 1 if you are using MSVC++
6.0 or greater, 0 otherwise. You can override the automatic definition of
AG_PLACEMENT_DELETE_REQUIRED by defining it in the ©C prologueª section
of your grammar. Set it to a non-zero value to force the "placement
delete" definition, zero to skip the definition.

##

ag_tcv

ag_tcv is an array AnaGram includes in your ©parserª.
Your parser uses ag_tcv to translate external codes to
the internal token numbers that AnaGram uses. It uses
the actual input code to index the ag_tcv array to
fetch a ©token numberª. The token number is then used
to identify the input token.
##

Allow macros

"Allow macros" is a ©configuration switchª which
defaults to on. When it is set, i.e., on, ©reduction
procedureªs will be implemented as macros if they are
sufficiently simple. This makes your ©parserª somewhat
more compact but makes it somewhat more difficult to
debug. It's a good idea to turn this switch off for
debugging.
##

Analyze Grammar

The Analyze Grammar command will scan and
analyze your ©syntax fileª, and create a number of
tables summarizing your grammar.

Analyze Grammar does not create any ©output filesª.
To create a ©parserª, use the ©Build Parserª command.
You would probably use Analyze Grammar, rather than Build Parser, during
initial development of your ©grammarª.

You can use ©File Traceª and ©Grammar Traceª as soon as you have
analyzed your grammar. It is not necessary to build a parser first.
##

Attribute Statement

Attribute statements are used in ©configuration
sectionsª of your ©syntax fileª to specify certain
properties for ©tokenªs, ©character setªs, or other
units of your grammar. The attribute statements
available are:
	©disregardª
	©distinguish keywordsª
	©enumª
	©extend pcbª
	©hiddenª
	©leftª
	©lexemeª
	©nonassocª
	©rename macroª
	©reserve keywordsª
	©rightª
	©stickyª
	©subgrammarª
	©wrapperª
##

Auto init

Auto init is a ©configuration switchª which defaults to
on. It controls the initialization of any ©parserª that
it is not ©event drivenª. When it is set to on, your
parser is automatically initialized every time it is
called. This is the situation you will normally use. On
occasion, however, it is desirable to call a parser
several times without reinitializing it. In this case,
you may set the auto init parameter to off and then
call the ©initializerª yourself whenever it is
appropriate.
##

Auto resynch

"Auto resynch" is a ©configuration switchª which
defaults to off. You may use it to specify ©automatic
resynchronizationª as an ©error recoveryª mechanism.

Setting the "auto resynch" switch causes AnaGram to
include an automatic ©resynchronizationª procedure in
your ©parserª. The resynchronization procedure will be
invoked when your parser encounters a ©syntax errorª
and will skip over input until it finds input
characters or ©tokensª consistent with its state at the
time of the error.

An alternate technique, ©error token resynchronizationª,
uses an ©error tokenª which you include in your grammar.
##

Automatic Resynchronization

Automatic ©resynchronizationª is one of several ©error
recoveryª options available as part of parsers built by
AnaGram. You enable automatic resynchronization by
setting the ©auto resynchª ©configuration switchª. If
your parser includes automatic resynchronization it will
incorporate a heuristic procedure which will skip over
input tokens until it finds a token which makes sense
with respect to one or another of the ©productionªs
active at the time of the ©syntax errorª.

The purpose of the resynchronization procedure is to
provide a simple way for your parser to proceed in the
event of syntax errors so that it can find more than one
syntax error on a given pass. The resynchronization
procedure uses a heuristic based on your own syntax.
AnaGram itself uses this technique to resynchronize
after syntax errors in its input.

A disadvantage to using this resynchronization technique
is that the resynchronization procedure turns off all
©reduction procedureªs. Because of the error, a number
of reduction procedures, which normally would be
executed, will be skipped. The parameters for any
reduction procedures that might be called later would be
suspect and could cause serious problems. It seems more
prudent simply to shut them down.

If you use the automatic resynchronization procedure,
you must also specify an ©eof tokenª so that the
synchronizer doesn't inadvertently skip over the end of
file.

An alternative technique for resynchronization is called
©error token resynchronizationª.
##

Auxiliary Trace

An Auxiliary Trace is a pre-built grammar trace which
you may select from the ©Auxiliary Windowsª popup menu for
most windows which display parser state information.
The Auxiliary Trace provides a path to the state
specified in the highlighted line of the primary window.

When obtained
from the Parser Stack pane of the ©File Traceª or ©Grammar Traceª, the
Auxiliary Trace is simply a copy of the current status of these
traces so you can explore your alternatives while still retaining the
status of the original trace for reference.
##

Auxiliary Windows

From most AnaGram windows you can pop up an Auxiliary Windows
menu by clicking the right mouse button or by pressing Shift F10.
Auxiliary Windows may
have Auxiliary Windows of their own.

 Windows with a cursor bar (highlighted line):
The windows available in the Auxiliary Windows menu depend on the
grammar elements identified by the cursor bar in the parent window. If
the cursor bar identifies a ©parser stateª, there will be windows that
describe the state. If the cursor bar identifies a ©grammar ruleª,
there will be windows that describe the rule. If the cursor bar
identifies a ©tokenª, there will be windows that describe the token. In
the case of a ©marked ruleª, token windows will describe the marked
token, if any. In some cases, specialized pre-built grammar traces
such as the ©Conflict Traceª or ©Auxiliary Traceª are on the menu.

 Help windows:
For Help windows, the Auxiliary Windows menu will show all the
available links to other ©Help topicsª from this window. ©Using Helpª
is always available.
##

Backtrack

If your ©parserª does not continue after encountering a
©syntax errorª, you can speed it up and make it a
little smaller by turning off the backtrack
©configuration switchª. If backtrack is on, AnaGram
configures your parser so that in case of syntax error
it can undo any ©default reductionsª it might have made
as a consequence of the erroneous input. The purpose of
such an undo function is to identify the proper ©error
frameª and to maximize the probability of being able to
recover gracefully.
##

Empty Recursion

This warning message tells you that the recursive step of the
specified ©recursive ruleª can be completely matched by ©zero
lengthª tokens, i.e., by nothing at all.
The result is potentially an infinite loop in the generated ©parserª.
The specified rule is an expansion rule of the specified token.

Because of the possibility of encountering an infinite loop while parsing,
AnaGram turns off its ©keyword anomalyª analysis if empty recursion is
found. The ©File Traceª function is also disabled for the same reason.

The ©circular definitionª of a token has the same effect as an
empty recursion, in that no additional input is required to match
the recursive rule.

##
Keyword Anomaly analysis aborted: empty recursion

The ©keyword anomalyª analysis has been turned off, since the presence of
©recursive ruleªs with ©empty recursionª can cause infinite loops in the analysis.

##

Keyword Anomaly analysis aborted: circular definition

The ©keyword anomalyª analysis has been turned off, since the presence of
a ©circular definitionª can cause infinite loops in the analysis.

##

File Trace disabled: empty recursion

Because of the presence of ©recursive ruleªs with  ©empty recursionª in this grammar and
the infinite loops that can ensue, the ©File Traceª function has been
disabled.

##

File Trace disabled: circular definition

Because of the presence of a ©circular definitionª in this grammar and
the infinite loops that can ensue, the ©File Traceª function has been
disabled.

##



Both Error Token Resynch and Auto Resynch Specified



This ©warningª message indicates that your ©grammarª
defines an ©error tokenª and also requests ©automatic
resynchronizationª. AnaGram will ignore the request
for automatic resynchronization and will provide ©error
token resynchronizationª. If you named a token "error"
but do not wish ©error token resynchronizationª, you can
either rename "error", or, in a ©configuration
sectionª, you may explicitly specify the error token to
be something you don't otherwise use in your grammar:
	[ error token = not used ]
##

Bottom Margin

"Bottom margin" is an ©obsolete configuration parameterª.
##

Bright Background

"Bright background" is a ©configuration switchª which
was used in the DOS version of AnaGram. It is no longer
used, but is still recognized for the sake of upward
compatibility with old ©configuration fileªs.
##

Build Parser

You use the Build Parser command to create a ©parserª based on your
©grammarª. The parser is a C file consisting of the ©embedded Cª (which
may include C++) code in your ©syntax fileª, your ©reduction
procedureªs, a number of tables derived from your grammar
specification, and a ©parsing engineª customized to your requirements.

If you only wish to investigate your grammar and do not
wish to create ©output filesª, use the ©Analyze
Grammarª command.
##

Build <file name>

This item on the ©Action Menuª is available when you have analyzed a
©grammarª but you have not yet built it. It builds the grammar
without reloading the ©syntax fileª from the disk.
##

Cannot Make Wrapper for Default Token Type

This ©warningª message occurs when AnaGram finds a token type that has
been previously defined as the ©default token typeª
listed in a ©wrapperª statement. If a wrapper is needed for a
particular type, you must specify the ©data typeª explicitly
for each relevant ©tokenª.

As a result, a wrapper class has not been created for the specified token type.
##

Token with Wrapper cannot be Default Token Type

This ©warningª message indicates that an attempt has been made
to specify a class that has previously been listed in a ©wrapperª
statement as the ©default token typeª.
If a wrapper is needed for a particular type, you must specify the
©data typeª explicitly for each relevant ©tokenª.

As a result, the default token type has not been set.
##

Case Sensitive

"Case sensitive" is a ©configuration switchª which
defaults to on. When it is on, it instructs AnaGram to
build a parser for which all input is case sensitive.
When it is off, the AnaGram builds a parser which
ignores case for all input.

If the ©iso latin 1ª configuration switch is turned
off, case conversion will be limited to characters
in the normal ascii range. When it is on, case
conversion will be done for all iso latin 1 characters.

If you have other requirements for case conversion,
you may provide your own definition in your ©embedded cª for the
©CONVERT_CASEª macro which is invoked to perform case
conversion on input characters.

Note that the value of an input token is unaffected
by the case sensitive switch. When case sensitive is
off, 'a' and 'A' will be treated as the same input
token by the parser, but the ©token valueªs will
nevertheless be different.
##

C Prologue

If you include a block of ©embedded Cª code at the very
beginning of your syntax file, it is called the "C
prologue". It will be copied to your ©parser fileª
before any of the code generated by AnaGram. You can
use the C prologue to ensure that copyright notices,
#include directives, or type definitions, for example,
occur at the very beginning of your parser file.

If you specify a C or C++ type of your own definition,
you must provide a definition in the C prologue.
##

CHANGE_REDUCTION

CHANGE_REDUCTION(t) is a macro which AnaGram defines in
your ©parser fileª if your ©parserª uses ©semantically
determined productionsª. In your ©reduction procedureª,
when you need to change the ©reduction tokenª you can
easily do so by calling CHANGE_REDUCTION with the name
of the desired token as the argument. If the token name
has embedded spaces, replace the embedded spaces with
underline characters.
##

Character Constant

You may represent single characters in your ©grammarª by
using character constants. The rules for character
constants are the same as in C. The escape sequences
are as follows:
	\a		alert (bell) character
	\b		backspace
	\f		formfeed
	\n		newline
	\r		carriage return
	\t		horizontal tab
	\v		vertical tab
	\\		backslash
	\?		question mark
	\'		single quote
	\"		double quote
	\ooo	octal number
	\xhh	hexadecimal number

 AnaGram treats a single
character as a ©character setª
which contains only the specified character. Therefore you
can use a character constant in a ©set expressionª.
##

Character Map

The Character Map table shows you the mapping of input
characters to ©token numbersª. The ©ag_tcvª table in
your parser is based on the information in this table.

The fields in this table are:
	character code
	display character, if any (what Windows displays for this code)
	©partition set numberª
	©token numberª
	©token representationª

The display character will be what Windows displays for the character
code in the Data Tables font you have chosen.
##

Character Range

A "character range" is a simple way to specify a
©character setª. There are two ways to represent a
character range in an AnaGram ©syntax fileª.

The first way is like a ©character constantª: 'a-z'.

The second way allows somewhat greater freedom:
	'a'..'z'
	'a'..255
	^Z..037
	-1..0xff
Here you use two arbitrary ©character representationsª
separated by two dots. If the two characters are out of
order, AnaGram will reverse the order, but will give
you a ©warningª.

More complex ©character setsª may be specified by using
©unionª, ©differenceª, ©intersectionª, or ©complementª
operators.
##

Character Representation

In an AnaGram ©syntax fileª you may represent a
character literally with a ©character constantª or
numerically using decimal, octal or hexadecimal
representations following the conventions for C. Thus
'A', 65, 0101, and 0x41 all represent the same
character. Control characters can be represented using
the '^' character and either an upper or lower case
letter. Thus ^j and ^J are acceptable representations
of the ascii newline code. The rules for character
constants are identical to those in C, and the same
escape sequences are recognized.
##

Character Set

In AnaGram grammars you can conveniently specify whole
sets of characters at a time. This avoids
needless repetition and complexity.

Sets of characters may be defined in an AnaGram ©syntax
fileª in any of a number of ways. A single character is
taken to represent a character set consisting of a
single element. (See ©character representationª.) You
can also specify a set consisting of a range of
characters (see ©character rangeª) and perform the
familiar set operations, union, intersection, difference
and complement.

All the sets you define in your syntax file are
summarized in the ©Character Setsª window.

The ©unionª of two character sets, represented by a '+',
contains all characters that are in one or another of
the two sets. Thus, 'A-Z' + 'a-z' represents the set of
all upper and lower case letters.

The ©intersectionª of two character sets, represented
by a '&', contains all characters that are in both
sets. Thus, suppose you have the ©definitionsª
	letter = 'A-Z' + 'a-z'
	hex digit = '0-9' + 'A-F' + 'a-f'
Then (letter & hex digit) contains precisely upper and
lower case a to f.

The ©differenceª of two character sets, represented by
a '-', contains all characters that are in the first
set but not in the second set. Thus, using the same
definitions as above, (letter - hex digit) contains
precisely upper and lower case g to z.

The ©complementª of a character set, represented by a
preceding '~', represents all characters in the
©character universeª which are not in the given set.
Suppose you have defined a set, ©eofª, which consists of
the characters which represent end of file. Then, in
your grammar where you wish to accept an arbitrary
character, what you really want is anything but an end
of file character. You can define it thus:
	anything = ~eof
##

Character Sets

This window lists all of the distinct ©character setªs
which you defined, implicitly or explicitly, in your
©grammarª. Each line in the table describes one such
set.

The description takes the form of the internal set
number and the defining ©expressionª. The ©Auxiliary
Windowsª menu will allow you to see the ©Partition
Setsª which cover the character set, and the ©Set
Elementsª which it comprises, as well as the ©Token Usageª.
##

Character Universe, Universe

The character universe, or set of all expected input
characters to your parser, is defined as all characters
in the range given by a particular lower bound and a
particular upper bound, as described below.

The character universe is used for two things in
AnaGram. The first use is for calculating the
©complementª of a character set. The second use is in
the input processing of your parser. Input characters
will be used to index a ©token conversionª table to
convert character codes to token numbers. The length of
this table will be given by the size of the character
universe. If you have set the ©test rangeª
©configuration switchª you parser will verify that the
input character is within the range of the conversion
table. Otherwise, the character code will not be
checked for validity. In this case, an out-of-range
character will lead to undefined behavior.

If you have not used any characters with negative codes
in your grammar, the lower bound is zero. Otherwise, it
is the most negative such character.

If the highest character code you have used is less
than or equal to 255, the upper bound will be 255.

If you have used a character code greater than 255, the
upper bound will be the largest such code which appears
in your syntax file.
##

Characteristic Rule

Each ©parser stateª is characterized by a particular
set of ©grammar rulesª, and for each such rule, a
marked token which is the next ©tokenª expected. The
combination of a grammar rule and its marked token is often
called a ©marked ruleª. A marked rule which
characterizes a state is called a "characteristic
rule". In the course of doing ©grammar analysisª,
AnaGram determines the characteristic rules for each
©parser stateª. After analyzing your grammar, you may
inspect the ©State Definition Tableª to see the
characteristic rules for any state in your parser.
##

Characteristic Token

Every state in a ©parserª, except state 0, can be
characterized by the one, unique ©tokenª which causes a
jump to that state. That token is called the
©characteristic tokenª of the state, because to get to
that ©parser stateª you must have just seen precisely
that token in the input. Note that several states could
have the same characteristic token.

When you have a list of states, such as is given by the
©parser state stackª, it is equivalent to a list of
characteristic tokens. This list of tokens is the list
of tokens that have been recognized so far by the
parser.
##

Circular Definition

If the ©expansion ruleªs for a ©tokenª contain a ©grammar ruleª that
consists only of the token itself, the definition of the
token is circular. A circular definition is an extreme
case of ©empty recursionª.

As in cases of empty recursion, the generated parser may contain
infinite loops. When such a condition is detected, therefore,
©keyword anomalyª analysis the ©File Traceª option are disabled.

##

column

"column" is an integer field in your ©parser control
blockª used for keeping track of the column number of
the current character in your input. Line and column
numbers are tracked only if the ©lines and columnsª
©configuration switchª has been set.
##

Command Line

If you provide the name of a syntax file on the
command line when you start AnaGram, it will open
the file and run either ©Analyze Grammarª or ©Build
Parserª depending on the setting of the ©Autobuildª
switch.
##

Command Line Version, agcl.exe

The command line version of AnaGram, agcl.exe, can be
used in make files. It takes the name of a single syntax
file on the command
line. Error and ©warningª messages are written to stdout.

Normally you would only use the command line version once you
have finished developing your ©parserª and are integrating
it with the rest of your program.

The command line version of AnaGram is not included with
trial copies.
##

Comment

You may incorporate comments in your syntax file using
either of two conventions. The first is the normal C
convention for comments which begin with "/*" and end
with "*/". Such comments may be of arbitrary length. By
setting or resetting the ©nest commentsª switch, you
may control whether they may be nested or not.

The second convention for comments is the C++ comment
convention. In this case the comment begins with "//"
and ends with a newline.

When writing a ©grammarª, you may wish to allow a user
to comment his input freely without your having to
explicitly allow for comments in your grammar. You may
accomplish this by using the ©disregardª statement.
##

Compile Command

"Compile command" is a ©configuration parameterª which
takes a string value. This parameter was used in the
DOS version of AnaGram, but is ignored in the Windows
version.
##

Complement

In set theory, the complement of a set, S, is the set
of all elements of the ©universeª which are not members
of the set S.

In AnaGram, the complement operator for ©character
setsª is given by '~' and has higher precedence than
©differenceª, ©intersectionª, or ©unionª.

In AnaGram, the most useful complement is that of the
end of file character set. For ordinary ascii files it
is often convenient to read the entire file into
memory, append a zero byte to the end, and define the
end of file set thus:
	eof = 0 + ^Z.
Then, ~©eofª represents all legitimate input characters.

You can then use set differences to specify certain
useful sets without tedious enumeration. For example, a
comment that is to be terminated by the end of line
then consists of characters from the set
	comment char = ~'\n' & ~eof
This set could also be written
	comment char = ~('\n' + eof)
##

Completed Rule

A "completed rule" is a ©characteristic ruleª which has no ©marked
tokenª.  In other words, it has been completely matched and will be
reduced by the next input.

If there is more than one completed rule in a state,
the decision as to which to reduce is made based on the
next input token. If there is only one completed rule
in a state, it will be reduced by default unless the
©default reductionsª switch has been reset, i.e.,
turned off.
##

Configuration File

If it can find them, AnaGram reads two configuration
files to set up ©configuration parameterªs. At program
initialization, it will first attempt to read a
configuration file in the directory that contains
the AnaGram executable file you are running. Then it
will read a configuration file in your working
directory. Both files should have the name
"AnaGram.cfg" if they exist. Neither is necessary.

If a parameter is specified in both files, the
specification in the file from the working directory
takes precedence.

The effect of this two stage process is to allow you to
set your standard preferences in the principal
directory, with specific overrides in your working
directories.

The values for configuration parameters in ©syntax
filesª override those read from configuration files.

AnaGram does not save configuration parameters in
the Windows registry, nor does it provide any
mechanism for setting or changing the values of
configuration parameters within AnaGram itself.
##

Configuration Parameter

Configuration parameters may be specified either in
©configuration filesª or in your ©syntax fileª. In your
syntax files, configuration parameters are specified,
one per line, in a ©configuration sectionª.

AnaGram ignores case when identifying a configuration
parameter, so that "ALLOW MACROS", "Allow Macros", and
"allow macros" are all equivalent forms.

There may be any number of configuration sections in a
©syntax fileª. Any parameter may be specified any
number of times. Since AnaGram maintains only one value
in storage for these parameters, whenever it refers to
one it will see the most recently specified value.
Every configuration parameter has a default value which
has been chosen to correspond to a standard if it
exists, customary usage if such can be determined, or
otherwise to the most likely usage.

Before executing an Analyze Grammar or Build Parser command, AnaGram
resets configuration parameters to their initial values, as
determined by the built in defaults and the configuration files read
at program initialization.

The ©Configuration Parameters Windowª shows the current settings of all
of the configuration parameters. When this window is active you may
press ©F1ª or click with the ©help cursorª to pop up a help window
describing the parameter under the cursor bar.

There are several varieties of configuration
parameters. Some simply set or reset a condition. These
need simply be stated to set the condition or negated
with the tilde (~) to reset the condition. Thus
	[ nest comments ]
causes AnaGram to allow nested comments, and
	[ ~nest comments ]
causes AnaGram to disallow nested comments.

If you prefer you may explicitly specify a switch value as on or off:
	[ nest comments = on]

 A second kind
of configuration parameter takes a value
which is the name of a token. Thus
	[ grammar token = c grammar]
specifies that the token, c grammar, is the ©grammar
tokenª which is to be analyzed.

A third variety of configuration parameter takes a
value which is a C data type. Thus
	[ default token type = unsigned char *]
signifies that the ©semantic valueª of a token, unless
otherwise specified is a pointer to an unsigned char.

A fourth variety of configuration parameter takes a
string value to set some ascii string used by AnaGram.
Thus
	[ header file name = "widget.h" ]
signifies that the header file created by AnaGram
should be called "widget.h".

In string-valued parameters used to specify the names
of output files or the name of your parser, you may use
the '#' character to indicate the name of your syntax
file: When the string is actually used, AnaGram will
substitute the syntax file name for the '#'.

In string-valued parameters used to specify the names
of functions or variables that AnaGram generates, you
may use '$' to specify the name of your parser. When
the string is actually used, AnaGram will substitute
the name of your parser for the '$'.

In the "©enum constant nameª" configuration parameter
you may use '%' to specify where a token name is to be
substituted.

The final variety of configuration parameter takes a
numeric value. The value may be decimal, octal
or hexadecimal, following the C conventions, and may
have an optional sign. Thus
	[parser stack size = 50]
tells AnaGram to allocate space for at least fifty stack entries
when it creates your parser.
##

Configuration Parameters Window

The Configuration Parameters window lists the
©configuration parameterªs AnaGram accepts with their
current values, as set by the ©configuration filesª it
has read and by the most recent ©syntax fileª it has
analyzed. Configuration parameters cannot be changed
from within AnaGram.
##

Configuration Section

A configuration section is one of the main divisions of
your ©syntax fileª. It begins with a left square
bracket on a fresh line. It then contains definitions
of ©configuration parameterªs, ©configuration switchª
settings and ©attribute statementªs. These
specifications must each start on a new line. The
configuration section is closed with a right bracket.
Any further component of your syntax file, other than a
©commentª, must start on a fresh line.

There can be any number of configuration sections in a
syntax file.
##

Configuration Switch

A configuration switch is a ©configuration parameterª
which can take on only the two values true and false,
or on and off. You set a configuration switch, or turn
it on, by simply naming it in your ©configuration fileª
or in a ©configuration sectionª of your ©syntax fileª.
You turn it off, or "reset" it, by use of the tilde:
"~nest comments", for example, resets, or turns off,
the ©nest commentsª switch. If you prefer, you may
assign the value "on" to set the switch, or "off" to
reset it. For example:
	nest comments = on
##

Conflict

"Conflicts" arise during the ©grammar analysisª when
AnaGram cannot determine how to treat a given input
token. There are two sorts of conflicts: ©shift-reduce
conflictsª and ©reduce-reduce conflictsª. Conflicts may
arise either because the grammar is inherently
ambiguous, or simply because the grammar analyzer
cannot look far enough ahead to resolve the conflict.
In the latter case, it is often possible to rewrite the
grammar in such a way as to eliminate the conflict. In
particular, ©null productionsª are a common source of
conflicts.

When AnaGram analyzes your grammar, it lists all
unresolved conflicts in the ©Conflictsª window. A number
of ©Auxiliary Windowsª available from the Conflicts window
provide help in identifying the source of the conflict.

There are a number of ways to deal with conflicts. If
you understand the conflict well, you may simply choose
to ignore it. When AnaGram encounters a shift-reduce
conflict while building parse tables it resolves it by
choosing the ©shift actionª. When AnaGram encounters a
reduce-reduce conflict while building parse tables, it
resolves it by selecting the ©grammar ruleª which
occurred first in the grammar.

A second way to deal with conflicts is to set ©operator
precedenceª parameters. If you set these parameters,
AnaGram will use them preferentially to resolve
conflicts. Any conflicts so resolved will be listed in
the ©Resolved Conflictsª window.

A third way to resolve a conflict is to declare some
tokens as ©stickyª. This is particularly useful for
©productionªs whose sole purpose is to skip over
uninteresting input.

A fourth way to resolve conflicts is to declare a token
to be a ©subgrammarª. When you do this, AnaGram does
not look beyond the definition of the subgrammar token
itself for reducing tokens. This is not a particularly
selective way to resolve conflicts and should be used
only when the subgrammar token is naturally defined
only by internal criteria. The tokens identified by
lexical scanners are prime examples of this genre.

The fifth way to deal with conflicts is to rewrite the
grammar to eliminate them. Many people prefer this
approach since it yields the highest level of
confidence in the resulting program.

Please refer to the AnaGram User's Guide for more information about
dealing with conflicts.
##

Conflicts

If there are ©conflictªs in your grammar which are not
resolved by ©precedence rulesª, they will be listed in
the Conflicts window. The Conflicts window will also be
listed in the ©Browse Menuª. Conflicts which have been
resolved by ©precedence rulesª are listed in the
©Resolved Conflictsª window.

The Conflicts window lists the conflicts, or
ambiguities, which AnaGram found in your grammar. The
table identifies the ©parser statesª in which it found
conflicts, the ©conflict tokenªs for which it had more
than one option, and the ©marked rulesª for each such
option. If one of the rules for a particular conflict
has a ©marked tokenª, the conflict is
a ©shift-reduce conflictª. The marked token is the token
to be shifted. If none of the rules has a marked token the conflict is
a ©reduce-reduce conflictª.

AnaGram provides a number of ©Auxiliary Windowsª to help
you find and fix the source of the conflict. The
©Conflict Traceª window is a pre-built ©Grammar Traceª
window which shows you one of perhaps many ways to
encounter the conflict. The ©Reduction Traceª window
shows the result of reducing a particular ambiguous
rule.

In addition, the ©Rule Derivationª and ©Token
Derivationª windows show you why the conflict token is a
©reducing tokenª. They are particularly useful for
shift-reduce conflicts.

The ©Expansion Chainª window is helpful for understanding
reduce-reduce conflicts.

Other Auxiliary Windows which are often useful are the
©State Definitionª window, the ©Reduction Statesª
window, and the ©Problem Statesª window.

Please refer to the AnaGram User's Guide for more information on how to
deal with conflicts.
##

Conflicts Resolved by Precedence Rules

This ©warningª message indicates that AnaGram has
resolved conflicts in your grammar by using ©precedence
rulesª: guidelines you supplied either by explicit
©precedence declarationsª, by using a ©stickyª
statement or ©distinguish lexemesª statement, or
implicitly by using a ©disregardª statement. These
conflicts are listed in the ©Resolved Conflictsª
window, and are not listed in the ©Conflictsª window.
##

Conflict Token

In any given ©conflictª, there is a ©tokenª for which
an unambiguous ©parser actionª cannot be determined.
This token is called the "conflict token".
##

Conflict Trace

The Conflict Trace is a ready-made ©Grammar Traceª
which shows you one of perhaps many ways to get to the
state which has the ©conflictª selected by the cursor
bar. The Conflict Trace window is an option in the
©Auxiliary Windowsª menu for the ©Conflictsª window and
the ©Resolved Conflictsª window.
##

Const Data

The const data ©configuration switchª controls the use
of CONST qualifiers in generated code. If the switch is
set, all fixed data arrays in the ©parser fileª will be
qualified as CONST, unless the ©old styleª switch is
set. The default setting is ON. Other configuration
switches which control declaration qualifiers in the
parser file are ©near functionsª and ©far tablesª.
##

CONTEXT

"CONTEXT" is a macro which AnaGram defines for you if
you have defined a ©context typeª. It provides access
to the top value of the ©context stackª. Your
©GET_CONTEXTª macro may store the current context by
assigning a value to CONTEXT. Suppose your parser uses
©pointer inputª, and you wish to know the value of the
©pointerª for every production. You could define
GET_CONTEXT thus:
	#define GET_CONTEXT CONTEXT = PCB.pointer

 In ©reduction procedureªs, you may use the CONTEXT
macro to find the context for the rule you are
reducing, that is to say, the value the context
variables had when the first token in the rule was
encountered.
##

Context Stack

It is often convenient, when writing ©reduction
procedureªs, to know the actual context of the ©grammar
ruleª your procedure is reducing. To do this you need
to know the values that certain variables, such as
stack pointers, or input pointers, in your program had
at various stages as your parser matched the rule. You
can accomplish this by maintaining a context stack.

If you wish, AnaGram will keep track, on a stack, of any
context variables you wish. To do so, define a structure
which can hold all the values you need to stack. Use the
©context typeª ©configuration parameterª to tell AnaGram
how to declare the stack. Then define the ©GET_CONTEXTª
macro to gather the appropriate values and store them on
the stack. The ©CONTEXTª macro evaluates to the proper
location into which the GET_CONTEXT macro should store
the context value. AnaGram will invoke the GET_CONTEXT
macro whenever necessary to make sure the right values
are stacked. In a reduction procedure, you can then use
the macro ©RULE_CONTEXTª to find the value of the
context structure as of the beginning of each token in
the rule you are reducing.

If your parser is ©event drivenª, store the context of
the input token in PCB.input_context. The default
version of GET_CONTEXT will stack the context as
appropriate.

If your parser should encounter an error, you may use
©ERROR_CONTEXTª to determine the values of the context
variables at the beginning of the aborted grammar rule.
##

context type

"Context type" is a ©configuration parameterª whose
value is a C type name, possibly as defined by a
typedef statement. By default, "context type" is
undefined. If you define it, AnaGram will set up a
©context stackª in your ©parser control blockª so you
can track the context of ©productionªs.

Each time your parser pushes values onto the state
stack and value stack it will invoke the ©GET_CONTEXTª
macro to store the current context on the context
stack. The macro ©CONTEXTª names the current stack
location. In your GET_CONTEXT macro you can use it as
the destination for the current context. In a
©reduction procedureª, CONTEXT names the context as of
the beginning of the production. Two other macros are
available to inspect the values of the context stack.
In a reduction procedure, you may use ©RULE_CONTEXTª[k]
to determine the value of the context variable as it
was as of the (k+1)th token in the rule. In particular,
RULE_CONTEXT[0] is the value the context variable had
when the first token in the rule was seen.

If you enable the ©error frameª ©configuration switchª,
you may use ©ERROR_CONTEXTª to determine the context of
the production your parser was trying to identify at
the time of the error.
##

CONVERT_CASE

CONVERT_CASE is a user definable macro which AnaGram
invokes to convert the case of input characters when
the ©case sensitiveª switch has been turned off. If
you do not define the macro yourself, AnaGram will
provide a macro which will convert case correctly
for characters in the ASCII character range and
also for ©ISO latin 1ª characters if the corresponding
©configuration switchª is on.

##

Coverage File Name

If you have set the ©rule coverageª ©configuration
switchª to include coverage analysis in your parser,
AnaGram uses the value of the coverage file name
©configuration parameterª to find the results of your
testing. The value of the parameter is a string. The
default value is "#.nrc", where '#' represents the name
of your syntax file.
##

cs

cs is a field in a ©parser control blockª which
contains your ©context stackª. cs will be defined only
if you have defined the ©configuration parameterª
©context typeª.
##

Current Grammar

The Current Grammar is the ©grammarª you presently have
loaded. Its name is displayed on the title bar of
each AnaGram window.

A status field at the right center of the ©Control Panelª
indicates the state of processing that has been
carried out on the grammar.

"Loaded" means that the ©syntax fileª has been read
into memory, but that syntax errors have been found.

"Parsed" means that AnaGram has tried to analyze the
grammar, but got into some kind of difficulty and did
not complete the job. The explanation should be
apparent from the messages in the ©Warningsª window.

"Analyzed" means that a ©grammar analysisª has been
completed, but no ©output filesª have been written.

"Built" means that an analysis has been completed and
output files have been written.
##

Data Type

The ©tokensª in your ©parserª usually have ©semantic
valuesª. The data types for these values will be
determined by the ©default input typeª and ©default
token typeª ©configuration parameterªs unless you
explicitly provide ©token declarationsª in your grammar.
You may also define the data type for any ©nonterminalª
token by preceding the token name with an ordinary C
cast when you write a production. For example:

	(int) integer
		-> '0-9':d						=d-'0';
		-> integer:n, '0-9':d	=10*n + d - '0';

The data type may be any simple C or C++ data type, with
arbitrary indirection and qualification. You may also
use any type you have defined by means of typedef,
struct or class definitions. Template classes may also
be used. If you specify a type of your own definition,
you must provide a definition in the ©C prologueª at the
beginning of your ©syntax fileª.

A token may have the type "void" if its value has no
interest for the parser. Since your parser will not
stack a value for a void token, your parser may run
somewhat faster when tokens are declared as void.
##

Declare pcb

"Declare pcb" is a ©configuration switchª that defaults
to on. If this switch is set when you invoke the ©Build
Parserª command, AnaGram will automatically declare a
©parser control blockª for you, at the beginning of
your parser file. If you have used data types that you
define yourself, the typedef statements need to precede
the parser control block declaration. In this case, you
should turn "declare pcb" off and declare it yourself.

For more information, see the AnaGram User's Guide.
##

Default Input Type

The default input type is a ©configuration parameterª
which determines the ©data typeª for the ©semantic
valueªs of ©terminal tokensª if they are not explicitly
declared. Normally, you would explicitly declare
terminal tokens only when you have set the ©input
valuesª ©configuration switchª. If you do not set the
default input type, it will default to "int".

The default data type for the values of ©nonterminal
tokensª is given by the ©default token typeª
configuration parameter.
##

Default Reduction

"Default reductions" is a ©configuration switchª which
defaults to on.

A "default reduction" is a ©parser actionª which may be
used in your parser in any state which has precisely
one ©completed ruleª.

If a given ©parser stateª has, among its ©characteristic
rulesª, exactly one completed rule, it is usually faster
to reduce it on any input than to check specifically for
correct input before reducing it. The only time this
default reduction causes trouble is in the event of a
©syntax errorª. In this situation you may get an
erroneous reduction. Normally when you are parsing a
file, this is inconsequential because you are not going
to continue semantic action in the presence of error.
But, if you are using your parser to handle real-time
interactive input, you have to be able to continue
semantic processing after notifying your user that he
has entered erroneous input. In this case you would want
default reductions to have been turned off so that
©productionªs are reduced only when there is correct
input.
##

Default reduction value

If a ©grammar ruleª does not have a ©reduction procedureª
the ©semantic valueª of the first token in the rule will
be taken as the semantic value of the token on the left
hand side. If these tokens do not have the same ©data typeª
a ©warningª will be given.
##

Default Token Type

"Default token type" is a ©configuration parameterª
which determines the ©data typeª for the ©semantic
valueª of a ©nonterminal tokenª if no other type is
explicitly specified. It defaults to void. Therefore, if
any ©reduction procedureª returns a value, you must
either explicitly set the type of the ©reduction tokenª
or you must set default token type to an appropriate
value.

The default token type cannot have a ©wrapperª class
defined.

The default data type for the value of a ©terminal
tokenª is given by the ©default input typeª
configuration parameter.
##

Definition, Definition Statement

AnaGram syntax files may contain definition statements
which assign new names to ©character setsª, ©virtual
productionsª, ©keyword stringsª, ©immediate actionsª,
or ©tokensª. Definitions have the form
	name = <character set>
	name = <virtual production>
	name = <keyword string>
	name = <immediate action>
	name = <token name>

For example,
	letter = 'a-z' + 'A-Z'
	statement list = statement?...
	include = "include"

The symbols thus defined may be used anywhere the
expression on the right hand side might be used. Such
definitions, in and of themselves, do not define tokens.
Tokens are defined only by their usage in productions.

##

DELETE_WRAPPERS

If your parser uses ©wrapperªs and exits with an error condition, there
may be objects remaining on the ©parser value stackª. The DELETE_WRAPPERS macro
can be used to delete any remaining objects on the stack.
If you have enabled
©auto resynchª, DELETE_WRAPPERS will be invoked automatically.
##

Diagnose Errors

"Diagnose errors" is a ©configuration switchª which
defaults to on. When this switch is on, AnaGram includes a
function, ag_diagnose(), in your parser which provides simple
syntax error disgnoses. When your parser encounters a
syntax error, this function will be called immediately prior
to the invocation of the ©SYNTAX_ERRORª macro. A pointer to the message will be
stored in the ©error_messageª field of the ©parser control blockª.

If you wish to implement your own ©error diagnosisª, you
should turn this switch off, and include a call to your
own diagnostic procedure in your SYNTAX_ERROR macro.

ag_diagnose() provides three possible error messages,
governed by three macros: ©MISSING_FORMATª, ©UNEXPECTED_FORMATª, and
©UNNAMED_TOKENª. You may override the definitions of
these macros with your own definitions if you wish
to provide diagnostics in another language

If you have set the ©error frameª
switch it will also set the ©error_frame_tokenª field.
The "error_frame_token" is the non-terminal token which
the parser was trying to complete when the error was
encountered.

When the "diagnose errors" switch is set, AnaGram also
includes the a ©token namesª table in the parser which
contains the ascii names of the tokens in the grammar,
including entries for character constants and keywords.

Use the ©token names onlyª switch to limit the table
to explicitly named tokens only.
##

MISSING_FORMAT

MISSING_FORMAT is a macro that is used by the error
diagnositic function created by the ©diagnose errorsª
switch. If you do not define it in your parser,
AnaGram will define it thus:
	#define MISSING_FORMAT "Missing %s"

 This format is used when the diagnostic function can
identify a unique terminal or nonterminal token that
would satisfy the syntactic rules and is named
in the ©token namesª table.
##

UNEXPECTED_FORMAT

UNEXPECTED_FORMAT is a macro that is used by the error
diagnositic function created by the ©diagnose errorsª
switch. If you do not define it in your parser,
AnaGram will define it thus:
	#define UNEXPECTED_FORMAT "Unexpected %s"

 This format is used when the diagnostic function cannot
identify a named, unique terminal or nonterminal token that
would satisfy the syntactic rules and finds an
incorrect token, the name of which can be found
in the ©token namesª table.
##

UNNAMED_TOKEN

UNNAMED_TOKEN is a macro that is used by the error
diagnositic function created by the ©diagnose errorsª
switch. If you do not define it in your parser,
AnaGram will define it thus:
	#define UNNAMED_TOKEN "input"

 This macro is used as argument for the ©UNEXPECTED_FORMATª
macro when the actual, erroneous input cannot be identified.
##

Difference

In set theory, the difference of two sets, A and B, is
defined to be the set of all elements of A that are not
elements of B. In an AnaGram ©syntax fileª, you
represent the difference of two ©character setsª by
using the '-' operator. Thus the difference of A and B
is A - B. The difference operator is ©left
associativeª.
##

Disregard

The purpose of the "disregard" statement is to skip over
uninteresting ©white spaceª and comments in your input
file. It allows you to specify a token that should be
passed over in the input to your parser. The statement
takes the form:
	disregard ws
where "ws" is a token name or character set. Disregard
statements, like other ©attribute statementªs, may be
placed in any ©configuration sectionª.

You may have more than one disregard statement in your
©grammarª. If you do, AnaGram will create a shell
production. For example, suppose you write:
	[ disregard alpha
	   disregard beta ]
AnaGram will proceed as though you had written:
	gamma -> alpha | beta
	[ disregard gamma ]

 It frequently happens that you wish your ©parserª to
disregard blanks or comments, except that ©white spaceª
within names, numbers, strings, and other elementary
constructs is subject to special rules and thus should
not be disregarded blindly. In this case, you can use
the "©lexemeª" statement to declare these constructs off
limits for the disregard statement. Within these
constructs, the disregard statement will be inoperative
and the admissibility of white space is determined
solely by the productions which define these constructs.

Outside those productions which define lexemes, you
should not generally use a token which is supposed to be
disregarded. If you do, your grammar will have
©conflictªs, since the token could satisfy both the
explicit usage, as well as the implicit rules set up by
the disregard statement. Such conflicts, however, are
resolved automatically in favor of your explicit use of
the token. The conflicts will appear in the ©Resolved
Conflictsª window.

If you have "open ended" lexemes in your grammar such
as variable names or numeric constants, your grammar
will detect a conflict if one of these lexemes may
follow another such lexeme immediately. To deal with
these conflicts, you should turn on the "©Distinguish
Lexemesª" configuration switch. It will cause white
space to be required as a separator between the
lexemes.

In order to implement the "disregard" statement AnaGram
will redefine some tokens in your grammar. For example,
'+' may be redefined to consist of a simple plus sign
followed by optional white space:
	'+' -> '+'%, white space?...
The ©percent signª is used to indicate the original,
simple plus without the optional white space attached.
You will probably notice the percent sign appearing in
some windows and traces.
##

distinguish keywords

"distinguish keywords" is an ©attribute statementª
which you may include in a ©configuration sectionª. It
is used to tell AnaGram how to distinguish ©keywordªs
from similar sequences of characters in your input
stream. For example, you may want your parser to
recognize "int" as a keyword when it appears in the
following context:
	int x;
but not when in appears in the middle of such words as
"integral" and "intolerant". The operand of
"distinguish keywords" is a list of character set
©expressionªs separated by commas and enclosed in braces
({ }).

Once AnaGram has read your entire syntax file, it
evaluates all of these character sets and tests each
keyword string against the character sets in the order
in which they were encountered in the program. If all
the characters which constitute a particular keyword
are members of the specified set, the keyword logic is
set up so that it will recognize the keyword only if
the immediately following character is not in the set.

In the example above,
	[distinguish keywords {'a-z'} ]
will do the trick.

The "©stickyª" statement also affects the recognition
of keywords.
##

Distinguish Lexemes

The "distinguish lexemes" ©configuration switchª is
used in conjunction with the "©disregardª" statement
and the "©lexemeª" statement to resolve the
©shift-reduce conflictªs which often crop up when
suppressing white space.

The difficulty with suppressing white space is that you
wish it to be optional in cases like "x+y", where it is
not necessary in order to parse correctly, but you want
to require it in situations such as "mytype x", where
it is necessary to separate otherwise indistinguishable
constructs. If the white space were optional, it would
be necessary to allow for "mytypex", but it would be
impossible to determine if this were to be interpreted as
"mytype x", "mytyp ex", or any of the many other
possibilities.

The distinguish lexemes switch causes AnaGram to make
the white space optional where doing so causes no
ambiguity and makes it mandatory where to make it
optional would lead to ambiguity. In the example given
above, "mytypex" would be treated as a single name, and
another name would have to follow separating white
space.

The default value for distinguish lexemes is OFF. It is
anticipated that this will be changed to ON in future
releases of AnaGram.
##

Duplicate Production

This ©warningª message appears when a ©productionª
appears twice in your ©grammarª. You will have a
number of ©reduce-reduce conflictªs as a consequence.
Eliminate the duplicate, and the conflicts it caused
will go away.
##

Edit Command

"Edit command" is a ©configuration parameterª which
accepts a string value. It is no longer used and is
retained only for file compatiblity with the DOS
version of AnaGram.
##

Embedded C

You may encapsulate pieces of C or C++ code in your ©syntax
fileª more or less arbitrarily. Such pieces of code will
simply be copied to the ©parser fileª in the order in
which they are encountered. Each such piece of code must
be enclosed with braces({}). The left brace must be on a
new line, and nothing except comments may follow the
right brace. AnaGram does not inspect the interior of
such a piece of C code except to identify character
constants, strings, comments and blocks surrounded with
braces so that it does not identify the end of the
embedded C prematurely. Note that AnaGram will use the
status of the ©nest commentsª ©configuration switchª in
effect at the beginning of the embedded C.

AnaGram, of course, can be confused by unterminated
strings, unbalanced brackets, and unterminated comments.
The most likely outcome, in such a situation, is that
AnaGram will encounter an end of file looking for the
end of the embedded C. Should this happen, AnaGram will
identify the beginning of the piece of embedded C which
caused the problem.

If your syntax file begins with a block of embedded C,
called the "©C prologueª", it will be copied to the very
beginning of the parser file, preceding all of AnaGram's
output. You may use such an initial block of embedded C
to guarantee that program title comments, copyright
notices and important definitions are at the very
beginning of your parser file.

The code you include as embedded C, of course, has to
coexist with the code AnaGram generates. In order to
keep the potential for name conflicts to a minimum, all
variables and functions which AnaGram defines begin with
the letters "ag_". You should avoid variable names which
begin with these letters.

If AnaGram finds no embedded C in a syntax file, and you
ask it to build a parser, it will automatically generate
a main program that calls your parser. If you don't want
it to do this, you may turn off the ©main programª
©configuration switchª.
##

Empty Keyword String

This ©warningª appears when you have a keyword string
that contains no characters whatsoever. ©Keyword
stringsª must contain at least one character. If you
wish a null match, use a ©null productionª instead.
##

Enable Mouse

"Enable mouse" is a ©configuration switchª that defaults
to on. It is not used in the Windows version of AnaGram
and has been retained only for file compatibility with
the DOS version.
##

Enum Constant Name

The "enum constant name" ©configuration parameterª
allows you to select the name AnaGram will use for the
set of enumeration constants it defines in the ©parser
headerª file for your ©parserª. The value of "enum
constant name" should be a string containing the '%'
character. AnaGram will substitute each token name in
turn into this template as it creates the list of
enumeration constants. If it finds a '$' character it
will substitute the name of your parser. The default
value of "enum constant name" is "$_%_token".
##

Enumeration Constants

In your ©parser headerª file, AnaGram includes a typedef
enum statement which provides enumeration constants
corresponding to all the named constants in your
grammar. The names of the enumeration constants
themselves are defined by the ©enum constant nameª
©configuration parameterª. These constants are useful
when dealing with ©semantically determined productionsª.
##

Enum

Within a ©configuration sectionª, you may use an "enum"
statement to define numeric values for any number of
tokens just as you define enumeration constants in C.
The syntax is effectively the same as the enum statement
in C:

  [
    enum {
      first = 60,
      second,
      third,
      fourth = 'a',
      fifth,
    }
  ]

is exactly equivalent to
  first = 60
  second = 61
  third = 62
  fourth = 'a'
  fifth = 'b'
##

eof

"eof" is a quasi reserved word in AnaGram, used to
specify an end of file token. You may use another token
as an end of file delimiter by setting the ©Eof Tokenª
©configuration parameterª. eof is not required unless
you use ©automatic resynchronizationª in your ©parserª.

If you have not defined eof or specified an Eof Token
parameter, ©File Traceª may show a syntax error when it
encounters the end of a test file.

There are various ascii values that are commonly used
to represent an end of file. The end of a string in
memory is commonly 0, DOS uses ^Z, Unix uses ^D, and
Unix style stream I/O uses -1. It is often convenient
then to define

	eof = -1 + 0 + ^D + ^Z
##

Eof Token

"Eof token" is a ©configuration parameterª which accepts
a token name as a value. There is no default value.
AnaGram does not need a specification for the eof token
unless you are using its ©automatic resynchronizationª
facility.

If you use the ©automatic resynchronizationª capability
of AnaGram, you must specify explicitly an end of file
token. You can do this either by defining a ©terminal
tokenª in your ©grammarª called eof or by using the "eof
token" parameter to identify some other terminal token
to be used as the end of file marker. You would do this
only if you must use the name "©eofª" for some other
purpose.

Note that "eof" is case sensitive. Neither Eof nor
EOF will qualify as end of file tokens unless you
explicitly specify them using the eof token parameter.
##

Eof Token Not Defined

This ©warningª appears if you have requested either
©error token resynchronizationª or ©automatic
resynchronizationª and you have not defined an ©eof
tokenª. The resynchronization procedure will not work
correctly at end of file.
##

Error Action

The error action is one of the four ©parser actionªs of a
traditional ©parsing engineª. The error action is
performed when the parser has encountered an input
token which is not admissible in the current state.
The further behavior of a traditional parser is
undefined.
##

Error Defining

"Error defining TXXX: <token representation>" is a
©warningª message which appears if errors are encountered
while attempting to evaluate the ©character setª for
the specified ©tokenª. This warning is always generated
in addition to more detailed warnings that are made
when the actual errors are encountered.
##

Error frame

"Error frame" is a ©configuration switchª which defaults
to off. You use this switch to specify the ©error
diagnosisª capabilities of your parser. If this switch
is set and the ©diagnose errorsª switch is set, i.e.,
on, your parser will include a function which will
determine the "context" of any ©syntax errorª, that is,
the token the parser was trying to complete.

To determine the context of an error, your parser will
scan backwards through the ©parser state stackª,
examining ©characteristic rulesª until it finds a state
which can accept a unique ©nonterminalª reduction token
that you have not marked as ©hiddenª. It will then set
PCB.©error_frame_ssxª to the ©parser stack indexª for
that level.
##

ERROR_CONTEXT

ERROR_CONTEXT is a macro AnaGram defines for you. If
your parser encounters a ©syntax errorª, you have
enabled the ©error frameª ©configuration switchª, and
you have defined a ©context typeª, ERROR_CONTEXT will
enable you to access the ©contextª as of when the parser
encountered the beginning of the ©error_frame_tokenª.
##

Error Diagnosis

"Error diagnosis" and ©error recoveryª are the two
aspects of ©error handlingª. If in the ©embedded Cª
portion of your syntax file you define a macro called
©SYNTAX_ERRORª, it will be invoked by the parser when a
©syntax errorª is encountered. If you have set the
©diagnose errorsª ©configuration switchª, the
©error_messageª field of the ©parser control blockª will
contain a pointer to a string containing a diagnostic
message. The diagnostic is of the form "Missing <token
name>" or "Unexpected <token name>".

If you do not define SYNTAX_ERROR it will be
automatically defined so that a message will be written
to stderr.

If the ©lines and columnsª switch has been set you will
have the current line number and column number available
for your diagnostic message.

If you have set the ©error frameª switch as well as the
diagnose errors switch, the variable
PCB.©error_frame_tokenª will identify the ©nonterminal
tokenª the parser was trying to recognize when the
error was encountered.

Of course, if your parser is controlling direct keyboard
input, a diagnosis might be unnecessary. In this case
you might define SYNTAX_ERROR so that it simply beeps at
the user and let it go at that.
##

Error Handling

Rarely is a parser built to read an arbitrary input
file. The normal situation is that the parser is built
to read files that conform to the rules specified in a
grammar, rules that describe a class of input files
rather than all possible input files. If the input file
does not conform to the grammar, the parser will detect
a ©syntax errorª.

There are two aspects to error handling in your parser:
©error diagnosisª and ©error recoveryª. Error diagnosis
consists in informing your user that something
unexpected has happened. Error recovery consists in
either aborting the parse, or getting it started again
in some reasonable manner. AnaGram provides several
options for both error diagnosis and error recovery.

When a syntax error is encountered, first your error
diagnosis option is executed and then your error
recovery option is executed.
##

error_message

error_message is a field in a ©parser control blockª to
which your ©error handlingª procedures may refer. If you
have set the ©diagnose errorsª ©configuration switchª,
on encountering a ©syntax errorª your ©parserª will
create a string containing an appropriate diagnostic
message and store a pointer to it into
PCB.error_message.
##

Error Trace

"Error Trace" is both a ©configuration switchª and the
name of an option in the ©Action Menuª. If the switch
is on, AnaGram adds code to your parser to capture
state information to a file in case of a ©syntax errorª. The Error
Trace option can then read this information and prepare a pre-built
©Grammar Traceª showing you the state of the parser at the time of
the error.

The name of the file is determined by the macro
©AG_TRACE_FILE_NAMEª. AnaGram will provide a default
definition for the macro consisting of the name of
your ©syntax fileª plus the extension ".etr". You
may override this definition by defining AG_TRACE_FILE_NAME
in your ©embedded Cª.

If error trace is enabled, AnaGram will also enable the
Error Trace option on the ©Action Menuª. If you select
Error Trace AnaGram will initialize a ©Grammar Traceª
window from the error trace file you select. The parser
stack of the trace will be as it was when the error
occurred. The last line of the parser stack pane will
show the ©lookahead tokenª that caused the syntax error. You may
then use the Grammar Trace to explore the nature of
the syntax error your parser encountered.

AnaGram will
warn you if the error trace file is older than
the syntax file, since under those conditions, the
error trace file might be invalid.
##

AG_TRACE_FILE_NAME

AG_TRACE_FILE_NAME is a C macro used to determine the
name of the file your parser will write when it
encounters a ©syntax errorª if you have enabled
the ©error traceª ©configuration switchª.

You may define AG_TRACE_FILE_NAME in your ©embedded Cª.
AnaGram provides a default definition given by the
name of your ©syntax fileª with the extension ".etr".
##

Error Recovery

Error recovery is the process of continuing after a
©syntax errorª. AnaGram offers several options. These
are controlled by ©configuration parameterªs and by
your grammar.

If you do not specify any error recovery, your parser
will simply return to the calling program when it
encounters a syntax error. ©PCBª.©exit_flagª will be set
to two, to indicate termination on syntax error.

If you wish your parser to simply ignore the erroneous
token and continue, set PCB.exit_flag to zero in your
©SYNTAX_ERRORª macro. You might use this option if your
parser is dealing directly with keyboard input.

You may wish to use YACC type error handling. To do
this, simply incorporate a token called "error" in your
grammar, or specify some other token as an ©error
tokenª. On syntax error, your parser will back up to
the most recent state where "error" was acceptable
input, treat the bad input as an instance of error, and
then skip all input until it finds an acceptable input
token. At that point it will proceed as though nothing
had happened.

AnaGram also provides an ©automatic resynchronizationª
option, which uses a complex heuristic to compare input
tokens against all stacked states in order to find the
best state from which to continue.
##

Error Token Resynchronization

One of your options for ©error recoveryª after a ©syntax
errorª is a technique similar to that provided in YACC.
You include a terminal token called "error" in your
grammar. (Or, use the ©error tokenª configuration
parameter to specify some other token to serve this
purpose.) When the parser encounters an error in the
input, after invoking the ©SYNTAX_ERRORª macro, it backs
up the ©parser state stackª to the most recent state in
which "error" was an acceptable input. It then shifts to
the new state as though it had seen an actual "error"
token. At this point, it skips over any character in the
input which is not an acceptable input character for
this state. Once it does find an acceptable input
character, it continues processing as though nothing had
happened.
##

error_frame_ssx

error_frame_ssx is a field in a ©parser control blockª
to which your ©error handlingª routines may refer. When
your ©SYNTAX_ERRORª macro is called, if you have set
both the ©diagnose errorsª and ©error frameª
configuration switches, error_frame_ssx will contain the
value of the ©parser stack indexª at the beginning of
the ©error_frame_tokenª. For example, if in a syntax
file, you fail to close a comment, AnaGram will
encounter an illegal end of file in the comment. In this
situation, error_frame_token is the token for a comment,
and error_frame_ssx gives the parser stack depth at the
beginning of the comment.
##

error_frame_token

error_frame_token is a field in a ©parser control blockª
to which your ©error handlingª routines may refer. If
you have set both the ©diagnose errorsª and ©error
frameª ©configuration switchªes, when your
©SYNTAX_ERRORª macro is called, it will contain the
©token numberª of the error_frame_token.
##

error, Error Token

"Error token" is a ©configuration parameterª that takes
a token name for a value. It has no default value. If
you do not specify it, and your grammar has a terminal
token called "error", it will be used as the error
token. If you have an error token defined your parser
will presume that you wish to use the ©error token
resynchronizationª method of ©error recoveryª.
##

Escape Backslashes

"©Escape backslashesª" is a ©configuration switchª that
defaults to off. When turned on, the ©line numbersª switch
will write pathnames with doubled backslashes. The switch
is no longer necessary, since AnaGram now uses forward slashes
in the pathnames in #line directives rather than backslashes.switch.
##

Event Driven

It is often convenient to configure your parser to be
"event driven". In this situation, instead of calling
your parser once to process the entire input, you call
an ©initializerª to initialize the parser, and then you
call the parser once for each input token. Each time you
call it, the parser processes the single input token
until it can do no more.

You can interrogate the ©exit_flagª field of the
©parser control blockª to determine whether the parse is
complete or whether the parser encountered an error.

Event driven parsers are especially convenient for
dealing with terminal input or communications protocols.
##

Event Driven Parser Cannot Use Pointer Input

This ©warningª message appears if you specify pointer
input for your ©parserª and also specify that it should
be event driven. If you are going to use ©pointer
inputª, you should not specify your ©parserª as event
driven.  Conversely, if you really want an ©event
drivenª parser, you cannot specify pointer input.
##

Excessive Recursion

This ©warningª message appears if an internal stack in
AnaGram overflows because of the complexity of an
expression in your ©grammarª. Simplify your grammar by
using ©definitionª statements to name subexpressions.
##

exit_flag

exit_flag is a field in the ©parser control blockª.
When your parser returns, PCB.exit_flag contains an exit
code describing the outcome of the parse.  Mnemonic
values for the exit codes are defined in the parser
header file AnaGram generates. These mnemonics, their
values and their meanings are:
	AG_RUNNING_CODE    				= 0:	Parse is not yet complete
	AG_SUCCESS_CODE        				= 1:  	Parse terminated successfully
	AG_SYNTAX_ERROR_CODE   		= 2:	Syntax error encountered
	AG_REDUCTION_ERROR_CODE 	= 3:	Bad reduction token encountered
	AG_STACK_ERROR_CODE   			= 4: 	Parser stack overflowed
	AG_SEMANTIC_ERROR_CODE 		= 5: 	Semantic error, user defined

 An AnaGram parser checks exit_flag on return
from every ©reduction procedureª. AnaGram will exit with
the flag unchanged if it is non-zero. To halt a parse
from a reduction procedure, then, you need only set the
exit_flag to AG_SEMANTIC_ERROR_CODE, or any other unused value
greater than zero that suits your needs.
##

Expansion, Expansion Rule

In analyzing a ©grammarª, we are often interested in the
full range of input that can be expected at a certain
point. The expansion of a ©tokenª or state shows us
all the expected input. An expansion yields a set of
©marked ruleªs. The ©marked tokenª in each rule
shows us what input to expect.

The set of expansion rules of a (©nonterminalª) token
shows all the expected input that can occur whenever the
token appears in the grammar. The set consists of all
the ©grammar ruleªs produced by the token, plus all the
rules produced by the first token of any rule in the
set. A ©marked tokenª for an expansion rule of a token
is the first element in the rule.

The expansion of a state consists of its ©characteristic
ruleªs plus the expansion rules of the marked token in each
characteristic rule.
##

Expansion Chain

You may select an Expansion Chain window from the
©Auxiliary Windowsª popup menu of most windows that contain
©expansion ruleªs.

The Expansion Chain window is extremely useful for
indicating why a particular ©grammar ruleª is an
©expansion ruleª in a particular state. To see a chain
of productions that produces a desired expansion rule,
select the expansion rule with the cursor bar, press
the right mouse button for the Auxiliary Windows menu, and select
Expansion Chain.

The Expansion Chain window will then present a sequence
of expansion rules, using the same format as the
Expansion Rules window, but subject to the constraint
that each rule is produced by the ©marked tokenª in the previous line.

The first rule in the window is a ©characteristic ruleª
for the given state.  The last rule in the window is
the rule selected by the cursor bar in the window from
which you chose the Expansion Chain. It should be noted
that this expansion is not unique. There may be other
derivations.
##

Expansion Rules

You may select an Expansion Rules window from the
©Auxiliary Windowsª popup menu of most windows which display
©marked rulesª. The Expansion Rules window shows the
complete set of ©expansion ruleªs for the ©marked
tokenª in the highlighted rule.

In other windows, including all trace windows, the
Expansion Rules window shows the expansion of the token
on the highlighted line.
##

F1

Use the F1 key to bring up a context sensitive help window. Because of
various peculiarities of the Windows API, there are a few contexts
where the F1 key does not work; however, generally the ©help cursorª
works where F1 does not and vice versa.

©Helpª windows have hypertext links to related help windows.
In a help window, the right mouse button pops up a menu of
all the links for the window.
##

extend pcb

The "extend pcb" statement is an ©attribute statementª that allows you to
add declarations of your own to the ©parser control blockª. With this
feature, data needed by ©reduction procedureªs can be stored in the pcb
rather than in global or static storage. This capability greatly
facilitates the construction of ©thread safe parsersª.

The extend pcb statement may be used in any configuration section.
The format is as follows:
	extend pcb { <C or C++ declaration>... }

It may, of course, extend over multiple lines and may contain any
C or C++ declarations. AnaGram will append it to the end of the parser
control block declaration in the generated parser ©header fileª.  There may
be any number of extend pcb statements. The extensions are appended to
the pcb in the order in which they occur in the syntax file.

The extend pcb statement is compatible with both C and C++ parsers. Note
that even if you are deriving your own class from the parser control
block, you might want to use the extend pcb to provide virtual function
definitions or other declarations appropriate to a base class.
##

Far Tables

"Far tables" is a ©configuration switchª which defaults
to off. If it is set, when AnaGram builds a ©parserª it
will declare the larger tables it builds as FAR. This
can be a convenience when using some memory models with
8086 architecture.
##

Fatal Syntax Errors

This ©warningª message occurs when AnaGram cannot
complete the ©Analyze Grammarª command on your ©syntax
fileª because of errors in your syntax file.
##

File Trace

You can use the File Trace facility to verify your grammar,
even before you have implemented ©reduction proceduresª or
any other code. Thus you can defer writing procedural code
until you have the grammar working to your specifications.

To run File Trace, select
File Trace from the ©Action Menuª or click on the File Trace button.

Select a test file. When the ©File Trace Windowª appears,
double click at any point in the ©test file paneª, or
click the ©Parse Fileª button to parse the entire file.
AnaGram will parse up to the point you have selected
according to the rules in your ©grammarª. If the test file does not
conform to the rules of the grammar, the parse will halt with a
©syntax errorª. You can then inspect the ©Parser Stack paneª and the
©Rule Stack paneª to get an idea of the nature of the problem.


AnaGram uses different colors to
distinguish the portion of the test file that has
been parsed from the portion that has not been parsed,
so the location of the error should be readily apparent.

Since the syntax error often occurs somewhat downstream
from the actual error, you may need to back the parse up
and approach the error slowly. In the Test File pane,
double click at any point prior to the error to back
the parse up to that point. You can then click on the
©Single Stepª button to perform a single parser action.

You may also use the cursor keys to control the parse.
As long as no error is encountered, the parse is locked
to the blinking cursor. If you cursor past the syntax
error, however, the parse can no longer track the cursor
so the cursor location will differ from the parse location . The
cursor and parse locations will also differ after you single click
at any point other than the current parse location.

When the cursor and the parse location are thus out of synch, the
Single Step button is replaced with a ©Synch Parseª button. You
can click on Synch Parse to get the parse back in synch with the
cursor.

The File Trace option will be greyed out on the ©Action Menuª
if your grammar has ©empty recursionª, since
such a grammar may cause infinite loops in the parser.

Because a File Trace is based on character codes, it will also be greyed out
on the ©Action Menuª if your parser uses ©token inputª rather than
character input.

All parser actions performed by a File Trace update the ©trace
coverageª counts, enabling you to verify the extent to which
your test files exercise your parser.

Normally, AnaGram reads test files in "text" mode,
discarding carriage return characters. If your parser
needs to recognize carriage return characters
explicitly, you should turn the "©test file binaryª"
switch on.
##

File Trace Window

The ©File Traceª window normally consists of three panes:
	The ©Parser Stack paneª
	The ©Test File paneª
	The ©Rule Stack paneª

 If your grammar uses ©semantically determined productionsª,
the ©Reduction Choices paneª will appear when necessary
to allow you to select a ©reduction tokenª. The choice that
you make will be remembered and reused if you should back up
the parse and parse past this point again. The remombered choice
is not made automatically when you use ©Single Stepª. Thus,
if you wish to
change your choice, position the cursor at the location where
the choice must be made and Single Step past the choice.

If you ©reloadª the test file, the choices you have made will
be discarded.

The active pane has
a distinctively colored title panel and cursor bar. You can
use the tab key to tab among the panes. The function of
other keyboard keys depends on which pane is active.

Along the bottom of the File Trace Window is a toolbar with
two status boxes:
	©Parse Locationª
	©Parse Statusª
and five buttons:
	©Single Stepª
	©Parse Fileª
	©Resetª
	©Reloadª
	©Helpª

 If the blinking cursor loses synch with the current
parse location, the Single Step button is replaced with
the ©Synch Parseª button.
##

Grammar Trace Window

The ©Grammar Traceª window normally consists of three panes:
	The ©Parser Stack paneª
	The ©Allowable Input paneª
	The ©Rule Stack paneª

 If your grammar uses ©semantically determined productionsª,
the ©Reduction Choices paneª will appear when necessary
to allow you to select a ©reduction tokenª.

The active pane has
a distinctively colored column header and cursor bar. You
can use the tab key to tab among the panes. The function of other
keyboard keys depends on which pane is active.

Along the bottom of the Grammar Trace Window is a toolbar with
a ©Parse Statusª box, a ©text entryª field
and four buttons:
	©Proceedª
	©Single Stepª
	©Resetª
	©Helpª

 In the ©Parser Stack paneª you can see a
representation of the ©parser state stackª and ©parser stateª as they
might appear in the course of execution of your ©parserª. You can
examine the ©allowable inputª tokens and see the changes to the
state and the state stack caused by any input token you
choose. The ©Rule Stack paneª shows the relationship between the
contents of the parser stack and your ©grammarª. If your grammar
uses ©semantically determined productionsª, you can select the
appropriate ©reduction tokenª from the ©Reduction Choices paneª.

You can enter text characters directly in the ©text entryª
field. This means you can run a Grammar Trace like a ©File Traceª
where the test file is replaced by the characters you type in the
text entry field.  This is a very convenient way to check out your
grammar.
##

Test File, Test File Pane

In the ©File Traceª, the file under test is displayed in the
upper right pane. To parse to a specific point, double
click at that point.

As long as the parse location and the cursor are synchronized,
when you use the cursor keys to
move the cursor, the parse will track the cursor.

If the parse encounters a ©syntax errorª, it will not be able
to go beyond the location of the error. In this situation,
moving the cursor right or down will cause the cursor position to
differ from the parse location. The parse and cursor positions can also
differ if you single click anywhere in the Test File pane.

If the
parse location and the cursor are thus not synchronized, the
©Single Stepª button will be replaced with a ©Synch Parseª
button. Click on the Synch Parse button to get the cursor
and the parse back in synch. Of course, the parse will still
not be able to proceed past a syntax error.

In the default color scheme, parsed text is shown on a lighter
background than is unparsed text.

If your grammar uses ©semantically determined productionªs,
the parse will halt when one is encountered and the ©reduction
choices paneª will be displayed so you may select the appropriate
©reduction tokenª.

At any time you can click on the ©Reset buttonª to reset the parse to
the beginning of the test file. If you modify the test file, you
can click on the ©Reload buttonª to load the modified file and
reset the parse.

Normally, AnaGram reads test files in "text" mode, discarding carriage
return characters. If your parser needs to recognize carriage return
characters explicitly, you should turn the ©test file binaryª
©configuration switchª on.

Sample test files are provided with the FFCALC and FC ©examplesª.
##

Parse Location

The current location of the ©File Traceª parser in the
©test file paneª. The format is <line number>:<column number>.
##

Parse Status

The current state of the ©File Traceª or ©Grammar Traceª parser.

 Ready: The parser is ready for input.
 Running: The parser is processing input.
 Parse Complete: The parser has reached the end of the input. Click
on ©resetª or ©reloadª to restart the parse.
 Syntax error: A syntax error has been encountered. The parser cannot
go any further.
 Unexpected end of file: The parser has reached the end of the actual
input but the grammar still expects more.
 Select reduction token: The parser encountered a ©semantically determined
productionª. Select a ©reduction tokenª from the ©Reduction Choices paneª.
 Selection error: The reduction token selected from the Reduction Choices
pane was not allowable input in the present state. Select another
reduction token.
##

Parse File

Use the Parse File button in the ©File Traceª to parse all the way
to the end of file. The parse will not stop until it encounters a
©syntax errorª, a ©semantically determined productionª, or the end of file.
##

Reset

Use the Reset button in the ©File Traceª or ©Grammar Traceª to reset
the parse to its initial state. This is most convenient when using
a ©Conflict Traceª, ©Error Traceª, or other ©Auxiliary Traceª
since these traces seldom begin at state 0.
##

Reload

The Reload button in the ©File Trace Windowª rereads the test file.
This is convenient if you modify the test file while you are testing
the ©grammarª.
##

Lookahead Token

In an ©LALR-1 parserª the "lookahead token" is the next token to be
processed. For each ©parser stateª there is a list of tokens that
may be seen in this state. For each token there is a corresponding
©parser actionª. The parser scans the list looking for the lookahead
token and then performs the corresponding parser action. If the
lookahead token cannot be found and there is no ©default reductionª,
the parser signals a ©syntax errorª.

In File Trace, and in some circumstances in Grammar Trace, the
lookahead token can be seen on the last line of the
©Parser Stack paneª.
##

GET_CONTEXT

If you have defined a "©context typeª" ©configuration
parameterª, and wish to maximize the performance of your
parser, you should write a GET_CONTEXT macro which
stores the context of the input token directly in
©CONTEXTª, the current stack location. Otherwise, you
can write your ©GET_INPUTª macro so that it stores
context into ©PCBª.©input_contextª. The default
definition for GET_CONTEXT will then copy
PCB.input_context to the ©context stackª at the
appropriate time.
##

GET_INPUT

GET_INPUT is a macro which you should define to control
©parser inputª if your
parser is not ©event drivenª and you are not using
©pointer inputª. If you don't define it, AnaGram will
define it by default to read a single character from
stdin:

	#define GET_INPUT (PCB.input_code = getchar())

 ©PCBª.©input_codeª is an integer field in the ©parser control blockª
which is used to hold the current character code. You
may also want GET_INPUT to set the values of ©input_contextª or
©input_valueª. It may call an input function, or it may execute
in-line code when it is invoked.
##

iso latin 1

The "iso latin 1" ©configuration switchª controls case
conversion on input characters when the ©case sensitiveª
switch is set to off. When "iso latin 1" is set, the
default ©CONVERT_CASEª macro is defined to convert
correctly all characters in the latin 1 character set.
When the switch is off, only characters in the ASCII
range (0-127) are converted.
##

Dragon Book

The "dragon book" is the classic reference on formal parsing:
	Compilers: Principles, Techniques, and Tools
	Aho, Sethi, and Ullman
	Addison-Wesley, 1986.

 It is called the "dragon book" because of its
colorful cover illustration showing a knight in
armour ("data flow analysis") armed with sword
("©LALR parser generatorª") and shield ("syntax
directed translation") at his PC attacking a
bright red dragon ("complexity of compiler design").
##

LALR-1 Parser

An LALR-1 parser is a ©parserª created from a
©grammarª by an ©LALR parser generatorª.
##

LALR Parser Generator

LALR(k) (LookAhead Left-to-right Rightmost derivation)
parser generators are
programs that create parsers algorithmically from
formal grammars. The (k) refers to the number of
lookahead symbols used to make parsing decisions.
Normally, k = 1.

LALR parsers are a subset of the class of
so-called LR parsers. LALR parsers are generally more compact
and less costly to create. These advantages are
obtained at a slight sacrifice in generality. Although
is possible to contrive an LR grammar which has
©conflictªs when analyzed with the LALR algorithm,
such situations rarely occur in practice, and can
be easily resolved by rewriting a few rules.

In the ©dragon bookª, section 4.7, the authors list the following
attractive properties of LR parsing:
 LR parsers can be constructed to recognize virtually
all programming-language constructs for which context-free
grammars can be written.
 The LR parsing method is the most general nonbacktracking
shift-reduce parsing method known, yet it can be implemented as
efficiently as other shift-reduce methods.
 The class of grammars that can be parsed using LR methods is
a superset of the class of grammars that can be parsed with
predictive parsers.
 An LR parser can detect a syntactic error as soon as it is
possible to do so on a left-to-right scan of the input.
##

Getting Started

AnaGram is an ©LALR parser generatorª. Its input is
a ©syntax fileª, which you prepare with an ordinary
programming editor. Its output is a ©parser fileª. which
you can compile with a C or C++ compiler on any platform
and link into your program. To compile on Unix platforms, set
the ©no crª ©configuration switchª.

AnaGram has extensive context-sensitive hypertext
©helpª. In any AnaGram window, press ©F1ª or select an item with the
©Help Cursorª. Further documentation in HTML format, including
documentation of examples, is found in the html subdirectory. AnaGram
also has a comprehensive hard-copy manual, the AnaGram User's Guide.

If you are new to AnaGram, you might begin by reviewing the Help
Topics ©How AnaGram Worksª and ©Program Developmentª, and looking at
An Annotated Example and Summary of AnaGram Notation in the HTML
documentation.

If you are not already familiar with formal parsing techniques, you
may want to read Introduction to Syntax Directed Parsing in the HTML
documentation. Note also the Fahrenheit to Celsius conversion
examples in the examples/fc directory, which comprise a graded
sequence of syntax files illustrating most of the basic
principles of ©syntax directed parsingª in easy steps. Documentation
is in html/fc.html.

AnaGram has many features, many of which are not
commonly found in parser generators:
 the ©configuration sectionª
 ©thread safe parsersª
 C++ support
 the ©disregardª and ©lexemeª statements
 ©event drivenª parsers
 ©character setsª
 ©virtual productionsª
 ©File Traceª, ©Grammar Traceª
 ©automatic resynchronizationª
 ©error token resynchronizationª

To familiarize yourself with the many options available for configuring
your parsers, select ©Configuration Parametersª from the ©Browse Menuª.
Use ©F1ª or the ©Help Cursorª to pop up explanations of the various
parameters.


If you don't find the information you need, please visit the
AnaGram web page at http://www.parsifalsoft.com for further
information and support.

##

How AnaGram Works

AnaGram contains an ©LALR Parser Generatorª which creates a
table driven ©LALR-1 parserª from a ©grammarª written in a variant
of Backus-Naur Form. AnaGram works in two steps. In the
first step, or analysis phase, it reads a ©syntax fileª and
compiles a number of tables describing the grammar. In the
second step, or build phase, it writes two output files:
a ©parser fileª written in C or C++ and a ©header fileª.

Syntax files normally have the extension .syn. The rules for
writing syntax files are given in the AnaGram User's Guide
and in the Summary of AnaGram Notation in the HTML documentation.

The header file contains definitions and declarations, including
the definition of a ©parser control blockª.

The parser file consists of:
 The ©C prologueª, if any.
 Definitions and declarations provided by AnaGram.
 ©Reduction procedureªs.
 a customized ©parsing engineª.
 a ©parse functionª to be called when input is to be parsed.

 The name of the parser file is controlled by the ©parser
file nameª ©configuration parameterª. The name of the
parse function itself is controlled by ©parser nameª. In the
default case, the parser file will have the same name as
the syntax file, with the extension .c. The name of the
parse function is given by the ©parser nameª parameter. It defaults
to the name of the syntax file.
##

Examples

The EXAMPLES directory of the AnaGram distribution disk
contains a number of examples to help you get started.
Documentation for the examples, in HTML format, is located
in the html directory (start at index.html or examples.html).

The traditional Hello, World, in examples/hw, is a good
example for getting familiar with the mechanical
procedures of building both C and C++ parsers from
©syntax fileªs.

The Fahrenheit/Celsius conversion examples in the
examples/fc directory on your AnaGram diskette comprise
a graded sequence of syntax files which illustrate
most of the basic principles of ©syntax directed
parsingª in easy steps. In addition, these examples
demonstrate many features of AnaGram which are not
found in other parser generators:
 the ©configuration sectionª
 ©character setsª
 ©virtual productionsª
 ©error token resynchronizationª
 ©File Traceª
 the ©disregardª and ©lexemeª statements
 ©event drivenª parsers

The Four Function Calculator (examples/ffcalc) is used
traditionally to demonstrate parser generators. If you
are already familiar with ©syntax directed parsingª this
example will give you a good overview of the basics of
AnaGram. An annotated version of this example may be
found in AnaGram's HTML documentation.
The FFCALC example illustrates the use of ©precedence
rulesª to resolve ©conflictsª.

Other examples are available to demonstrate additional
features of AnaGram.

RCALC (examples/rcalc) is a simple four function
calculator which accepts roman numeral input. It
illustrates the following AnaGram features:
 ©pointer inputª
 ©SYNTAX_ERRORª macro
 ©context stackª

DSL (examples/dsl) is a complete DOS script language,
which provides capabilities well in excess of DOS batch
files. DSL is a complete working program, used in the
past to create AnaGram's install program. Some of the
specific features of AnaGram which it illustrates are:
 ©distinguish lexemesª
 ©distinguish keywordsª
 ©far tablesª

MPP is a fully functional macro preprocessor for C or
C++. Included with MPP are two C grammars, either of
which may be incorporated into MPP. MPP uses several
parsers that work together:
 TS.SYN is the primary token scanner parser that
identifies tokens, and handles preprocessor
commands.
 MAS.SYN is used to do macro argument substitution.
 CT.SYN is used to identify tokens that result from
string concatenation during macro argument
substitution.
 EX.SYN is used to evaluate constant expressions in
#if preprocessor statements.

Among the more powerful features of AnaGram that MPP
illustrates are:
 ©semantically determined productionsª
 ©event drivenª parsers
##

Goal, Goal Token, Start Token

The ©grammar tokenª is the token which represents the
"top level" in your grammar. Some people refer to it as
the "goal" or "goal token" and others as the "start
token". Whichever it is called, it is the single token
which describes the complete input to your parser.

The most common way to specify a grammar token is as
follows:
	grammar -> statements?..., eof
This production tells AnaGram that the input to your
parser consists of a (possibly empty) sequence of
statements followed by an end of file token.

There are a number of ways of specifying which token in
your ©syntax fileª represents the top level of your
grammar. You may simply name it "grammar", or you may
tag it with a '$' character when you define it, or you
may set the ©grammar tokenª ©configuration parameterª.

If you should inadvertently tag several tokens with the
'$' character and/or set the grammar token parameter,
it is the last such specification in the file which
wins. Some people develop their grammars bottom up,
gradually adding new levels of complexity. In the
course of development, they may specify a number of
tokens as grammar tokens and forget to remove the old
specifications.

Notice that if you define the token "grammar" anywhere
in your syntax and specify the grammar token otherwise,
"grammar" will not be the grammar token. This is to
keep "grammar" from being a reserved word. If you need
to use it in your syntax for something other than the
whole grammar, you are free to do so.
##

Grammar

Traditionally, a "grammar" is a set of ©productionªs
which taken together specify precisely a set of
acceptable input streams, in terms of an abstract set
of ©terminal tokensª. The set of acceptable input
streams is often called the "language" defined by the
grammar.

In AnaGram, the term "grammar" also includes
©configuration sectionsª as well as the ©definitionsª
of ©character setsª and ©virtual productionsª which
augment the collection of productions. The term is
often used in contrast to the term "©syntax fileª"
which is used to signify the complete AnaGram source
file including reduction procedures and embedded C or
the term "©parserª" which refers to AnaGram's output
file.

A grammar is often called a "syntax", and the rules of
the grammar are often called syntactic rules.
##

Grammar Analysis

The major function of AnaGram is the analysis of
context-free grammars written in a particular variant
of Backus-Naur Form.

The analysis of a grammar proceeds in four stages. In
the first, the input grammar is analyzed and a number
of tables are built which describe all of the
©productionªs and components of the ©grammarª.

In the second stage, AnaGram analyzes all of the
character sets defined in the grammar, and where
necessary, defines auxiliary tokens and productions.

In the third stage, AnaGram identifies all of the
states of the parser and builds the go-to table for the
parser.

In the fourth stage, Anagram identifies ©reduction
tokensª for each completed ©grammar ruleª in each state
and checks for ©conflictªs.

Use the ©Analyze Grammarª command to cause AnaGram to
analyze your grammar.
##

Grammar Is Ambiguous

This ©warningª message appears if your ©grammarª
contains ©conflictªs. AnaGram will resolve ©shift-reduce
conflictsª by selecting the shift option. It will
resolve ©reduce-reduce conflictsª by selecting from the
conflicting ©grammar ruleªs the one which appears first
in the ©syntax fileª.
##

Grammar Rule

A "grammar rule" is the right hand side of a production.
It is a sequence of ©rule elementsª. Each rule element
identifies some token, which can be either a ©terminal
tokenª or ©nonterminal tokenª.

A grammar rule is "matched" by a
corresponding sequence of tokens in the input stream to
the parser. The rule elements in the grammar rule may be
©token nameªs, ©set expressionsª, ©character constantsª,
©immediate actionªs, ©keyword stringsª, or ©virtual
productionsª.

A grammar rule may be followed by an
optional ©reduction procedureª. The ©semantic valuesª of
the tokens that comprise the rule may be passed to the
reduction procedure by using ©parameter assignmentsª.

A grammar rule always makes up the right hand side of a
production. The left hand side of the production
identifies one or more ©nonterminal tokensª, or
©reduction tokensª, to which the rule reduces when
matched. If there is more than one reduction token,
the production is called a ©semantically determined productionª and
there should be a ©reduction procedureª to select
the correct reduction token at run time.
##

Grammar Token

The "grammar token" ©configuration parameterª may be
used to specify the ©goalª, or "start" token for the
syntax analyzer portion of AnaGram. Alternatively, you
could simply call the token "grammar", or you could
append a '$' character to it when you define it.

Each grammar must have a grammar token specified before
it can be analyzed or before a parser can be built. The
grammar token is the single token to which the grammar
finally condenses. When this token is identified by the
parser, the parse is complete.
##

Grammar Trace

AnaGram's Grammar Trace facility lets you examine the workings of your
©parserª in detail. You can use the Grammar Trace as soon as you have
analyzed your ©grammarª, even before you have written any ©reduction
procedureªs or other code. Thus you can defer writing procedural code
until you have the grammar working to your specifications.

Select the ©Grammar Trace Windowª
from the ©Action Menuª or click on the Grammar Trace
button.

In the ©Parser Stack paneª you can see a representation of the
©parser state stackª and ©parser stateª as they might appear in the
course of execution of your ©parserª. The ©Rule Stack paneª shows the
relationship between the contents of the parser stack and your
©grammarª. If your grammar uses ©semantically determined
productionsª, you can select the appropriate ©reduction tokenª from
the ©Reduction Choices paneª.

At any stage, the ©Parser Stackª represents a parse
in progress. It shows the sequence of ©tokenªs that have
been input so far and the states in which they were
seen. When a production is complete and the grammar rule
is reduced, the tokens that make up the rule are removed
from the stack and replaced by the token on the left
side of the production. Initially, the Parser Stack contains
only a ©lookahead lineª.

To explore your grammar, choose ©tokenªs one by one from
the ©Allowable Inputª
pane. This pane shows the tokens allowable at the current state of the
grammar, and the actions that result when the tokens are chosen.

You can also enter text characters directly in the ©text entryª
field. This means you can run a Grammar Trace like a ©File Traceª
where the test file is replaced by the characters you type in the
text entry field.  This is a very convenient way to check out your
grammar. Text entry is, of course, not appropriate for grammars that
expect ©token inputª.

In a ©File Traceª you can advance the parse no matter which pane is
active. In a Grammar Trace there is a question as to whether input is
intended to come from the Allowable Input pane or the text entry
field.  Therefore the parse can only be advanced when one of these
two is active to indicate that it is the source of input.

Specialized prebuilt Grammar Traces such as the ©Conflict Traceª and
the ©Auxiliary Traceª can be selected from ©Auxiliary Windowsª popup
menus where appropriate.

All Grammar Trace activity updates the ©trace coverageª counts.
##

Text Entry

It is sometimes more convenient to enter text in the
text entry box on the ©Grammar Traceª toolbar than to
select individual tokens from the ©Allowable Input paneª.

By entering text you can proceed quickly to a troublesome
state without having to choose each individual token
en route.

After entering text, press Enter or click on the Proceed
button to parse the text. Click on the single step button
to work slowly through the text step by step.
##

header file name

The "header file name" parameter names the ©parser
headerª file that AnaGram will generate when it builds
your parser. This header file can be used with your
parser or with other modules in your program. The
header file contains a number of typedef statements and
an number of macro definitions which are needed in your
parser and may be useful in other modules.

If the value of this parameter contains a '#' character,
AnaGram will substitute the name of your syntax file for
the '#'. The default value of "header file name" is
"#.h".
##

Help, Using Help

There are 3 main ways to access AnaGram Online Help:
 Press F1 for context-sensitive help from most windows and menu items.
 Similarly, use the ©Help Cursorª from most windows and menu items.
 From the Help menu, you can bring up ©Help Topicsª and choose a topic.

You can also get fly-over help for the toolbar buttons on the ©Control
Panelª. File and Grammar Traces have a Help button.

AnaGram's Help windows, unlike most others, remain on-screen until you
dismiss them. This means you can refer to several topics at once. They
have hypertext links to other Help topics. Also, right-clicking
the mouse on a Help window or pressing F1 will pop up an Auxiliary
Windows menu of all linked topics in the window. "Using Help" is always
available from this popup menu.

Note that, for the ©Warningsª, ©Configuration Parameterªs and ©Help
Topicsª windows, F1 will give you help for the item
on the highlighted line, whereas the Help Cursor allows you
to select any line by clicking on it.

AnaGram also has documentation in HTML format, indexed in the index.html
file. This documentation covers Getting Started, examples, and some
further topics mainly condensed from the User's Guide. Hard copy
documentation is in the AnaGram User's Guide, which has the most
detail.
##

Hidden

In a ©configuration sectionª of your grammar you may use
an ©attribute statementª to declare one or more tokens
to be "hidden". Tokens that are "hidden" do not appear
in the ©token namesª table, and thus do not appear in syntax error
diagnoses. When your parser attempts to determine the
©error frameª of a ©syntax errorª, it will disregard the
tokens that have been declared hidden. The hidden
declaration consists simply of the keyword hidden
followed by a list of tokens, separated by commas and
enclosed in braces ({ }):
	[ hidden { widget, wombat, foo, bar } ]

 You would use the "hidden" attribute primarily for
tokens whose name would not mean anything to your users.
##

Immediate Action

Immediate actions are snippets of C code which are to
be executed in the middle of a ©grammar ruleª. Immediate
actions are denoted by a '!' character followed by
either a C expression, terminated by a semicolon; or a
block of C code enclosed in braces. For example, in a
simple desk calculator example one might write the
following:
	transaction
	    -> !printf('#');, expression:x  =printf("%d\n",x);

 Notice that the only apparent difference between an
immediate action and a ©reduction procedureª is that the
immediate action is preceded by '!' instead of '='.
Notice that the immediate action must be followed by a
comma to separate it from the following ©rule elementª.

Immediate actions may also be used in ©definitionªs:
	prompt = !printf('#');

The above example, using this definition would then be:
	transaction
	  -> prompt, expression:x  =printf("%d\n",x);

 You could accomplish the same result by writing a ©null
productionª and a reduction procedure:
  prompt
   ->   =printf('#');

This is exactly how AnaGram implements immediate
actions.
##

Implementation Errors

"Implementation errors" are errors your parser detects
which are not the immediate result of bad input.  When
it encounters an implementation error, your parser will
call a macro which you can define to deal with the
problem in a manner suitable to your needs. If you don't
provide these macros, AnaGram will make default
definitions. There are two macros corresponding to two
implementation errors:
	©PARSER_STACK_OVERFLOWª
	©REDUCTION_TOKEN_ERRORª
##

Inappropriate Value

This ©warningª message appears when the value assigned to
a ©configuration parameterª is not appropriate to that
parameter. Check the definition of the parameter, by
opening the ©Configuration Parameters Windowª,
selecting the parameter and pressing F1.
##

Initializer

For every ©parserª it generates, AnaGram generates an
"initializer" function to call the parser. AnaGram
names the initializer by prefixing the ©parser nameª
with "init_". If your parser is ©event drivenª, you must
call the initializer before you call the parser.

If your parser is not event driven, AnaGram will
normally include a call to the initializer in the
parser. If you wish to be able to call your parser more
than once without its being re-initialized, you may turn
off the ©auto initª ©configuration switchª. When you do
this, you assume responsibility for calling the
initializer. If your parser is event driven, you must
always call the initializer function.

If the ©reentrant parserª switch is set, the initializer takes
a pointer to the ©parser control blockª as its sole argument. Otherwise
it takes no arguments. The initializer returns no value. All
communication is by means of the ©parser control blockª.
##

Input Character

The actual unit of ©parser inputª is usually a
single character. Note that you are not limited to
eight-bit characters. Your parser will use the input
character to index a translation table, ©ag_tcvª, to
determine the ©token numberª for that character. The
©token numberª identifies the actual syntactic token.
The character code itself will be the ©semantic valueª
of the token. Note that AnaGram groups together all
input characters that are syntactically
indistinguishable into a single input token.
##

input_code

input_code is a field in the ©parser control blockª
which contains the current ©input characterª, or, if your
©GET_INPUTª macro supplies ©token numberªs directly, the
token number.

If you write your own ©GET_INPUTª macro, you must make
sure that you store the input character, or token
number, you get into ©PCBª.input_code.
##

INPUT_CODE(t)

If you set both the ©pointer inputª and the ©input
valuesª ©configuration parameterªs, you must provide an
INPUT_CODE macro for your parser. In this situation,
your parser will use the pointer to load the
©input_valueª field of the ©parser control blockª and
uses the INPUT_CODE macro to extract the appropriate
value for the ©input_codeª field. For example, if the
input_value is a structure and the appropriate member
field is called "id" you would write:

	#define INPUT_CODE(t) (t).id
##

input_context

"input_context" is a field which AnaGram adds to the
definition of the ©parser control blockª structure when
you define a ©context typeª ©configuration parameterª.
If you choose, you can write your GET_INPUT macro so
that it stores the context value in ©PCBª.input_context.
The default definition for ©GET_CONTEXTª will then stack
the context value at the appropriate time. You can think
of PCB.input_context as a sort of temporary "parking
place" for the context value.
##

Input Scan Aborted

This ©warningª message appears if AnaGram is unable to
finish scanning your ©syntax fileª because of previous
errors.
##

input values

"Input values" is a ©configuration switchª which
defaults to off. If your ©parser inputª includes
explicit ©token valueªs which are not simply the ascii
values of corresponding ascii input characters, you must
set the "input values" switch to inform AnaGram. Unless
your parser is ©event drivenª or uses ©pointer inputª,
you must also provide your own ©GET_INPUTª macro.

If your parser uses pointer input, you must provide an
©INPUT_CODE(t)ª macro.

The semantic value of an input token is to be stored in the
©input_valueª field of the parser control block.
##

input_value

input_value is a field in the ©parser control blockª
which is used to store the semantic value of the input
token.

If you write your own ©GET_INPUTª macro, and you have
set the ©input valuesª ©configuration switchª, you
should make sure that you store the value of the ©input
characterª or token into ©PCBª.input_value.
##

Internal Error

"AnaGram internal error: ..." is a ©warningª message which
appears if one of AnaGram's internal consistency tests
fails. This message should never appear if AnaGram is
working properly. Usually AnaGram will abort on
encountering an internal error, although under
a small set of circumstances it may continue. Should
this happen, it would be wise to close AnaGram and
restart it.

If you do get an internal error, please note the complete
message identifing the problem and file a bug report,
following the directions posted on the AnaGram web page
at http://www.parsifalsoft.com.
A copy of the relevant
syntax file and a summary of the circumstances surrounding
the problem would be greatly appreciated.
##

Intersection

In set theory, the intersection of two sets, A and B, is
defined to be the set of all elements of A which are
also elements of B. In an AnaGram ©syntax fileª, the
intersection of two ©character setsª is represented with
the '&' operator. The intersection operator has lower
©precedenceª than the ©complementª operator, but higher
precedence than the ©unionª and ©differenceª operators.
The intersection operator is ©left associativeª.
##

Keyboard Support

AnaGram can be controlled entirely from the keyboard. In the Control
Panel, you
can tab to any button and press Enter to select it. In addition to
the conventional
Windows keyboard functions, the following keys have been implemented:
	Escape closes any AnaGram window except the Control Panel.
	F8 toggles between an active AnaGram window and the Control Panel
	F10 accesses the Control Panel menu from any
AnaGram Window.
	Shift F10 pops up the Auxiliary Windows menu
##

Keyword, Keyword String

Keywords are a very important feature of AnaGram. They
provide an easy way to pick up special character
sequences in your input, thereby eliminating the need
for a lot of tedious ©productionªs.

If AnaGram finds, on the right hand side of one of your
©grammarª productions, a string enclosed in double
quotes, such as "IF", it automatically creates from the
string a "keyword" which is incorporated into your
parser. You may have any number of keywords. A keyword
is treated as a single terminal token. Recognition of
keywords is governed by the ©case sensitiveª switch.

Your parser will look for a keyword in its input stream
wherever you have defined this particular keyword to be
legitimate input. It will do whatever lookahead is
necessary in order to pick up the entire keyword. If
several keywords match the input, such as IF and IFF,
it will select the longest match, IFF in this example.

Important points to notice about keywords:
 1) Keywords take precedence over ordinary
characters in the input stream - thus if the character
I and the keyword IF are both legitimate input at some
point, IF will be selected, if present, in preference
to I.
 2) Keywords are not reserved words. Your parser
will only look for a keyword when it is in a state
where that keyword is legitimate input.
 3) Keywords do not participate in character sets
and should not appear in definitions of character sets.
In particular, they are not considered as belonging to
the complement of a character set. Thus
a keyword would not be considered legitimate input
for the production
		next char -> ~( '/' + '*' )

 4) Keywords may appear in virtual productions.

 5) Keywords may be named by means of a definition.

AnaGram will list all the keywords in your grammar in
the ©Keywordsª window. In addition, in numerous
windows where the cursor bar selects a state, the
©Auxiliary Windowsª popup menu will list a Keywords option.
This window will provide a list of the keywords
acceptable in the selected ©parser stateª.

On occasion, a kind of conflict, called a ©keyword
anomalyª may occur. If so, such conflicts will be listed
in the ©Keyword Anomaliesª window. The "©stickyª"
©attribute statementª is useful in dealing with keyword
anomalies.
##

Keyword Anomalies Found

This ©warningª message indicates that AnaGram has found
at least one ©keyword anomalyª in your ©grammarª. Open
the ©Keyword Anomaliesª window to see a list of those
that have been found.
##

Keyword Anomaly

In ©syntax directed parsingª, it is assumed that input
©tokenªs can be uniquely identified. In the case of
©keywordªs, however, there is the possibility that the
individual characters making up the keyword, as well as
the keyword taken as a whole, could constitute
legitimate input under some circumstances. Thus
©keywordsª, though a powerful and useful tool, are not
completely consistent with the assumptions that underlie
©syntax directed parsingª. This can occasionally give
rise to a type of conflict, diagnosed by AnaGram,
called a "keyword anomaly". AnaGram is quite
conservative in its diagnoses, so that many keyword
anomalies it reports are actually innocuous and can be
safely ignored.

Basically, a keyword anomaly is a situation where a
keyword is recognized, causes a reduction, and the
parser arrives in a state where the keyword is not
legal input. If the keyword, seen simply as a sequence
of characters, might have been legal input in the
original state, AnaGram notes the existence of a
keyword anomaly.

If you have a keyword that causes a keyword anomaly and
it is actually a reserved word in your grammar, the
anomaly is by definition innocuous. You should use the
©reserve keywordsª statement to inform AnaGram that the
keyword is reserved and the anomaly need not be
diagnosed.

To help identify and correct any problems associated
with keyword anomalies, AnaGram provides the ©Keyword
Anomaliesª window to identify the anomalies, and the
©Keyword Anomaly Traceª to help you understand a
particular anomaly.
##

Keyword Anomaly Trace

A Keyword Anomaly Trace is a ready made ©grammar traceª
window which you may select from the ©Auxiliary Windowsª
menu of the ©Keyword Anomaliesª window. The anomaly
trace provides a path to a state which illustrates the
©keyword anomalyª. In this state, the keyword is a
reducing token, but after the reduction, it is not
allowable input.
##

Keyword Anomalies

The Keyword Anomalies window is available only if your
grammar has ©keywordª anomalies.

Each entry in the Keyword Anomalies window consists of
two lines. The first line identifies the ©parser stateª
at which the ©keyword anomalyª occurs and the offending
keyword. The second line identifies the ©grammar ruleª
which the keyword may erroneously reduce.

The ©Auxiliary Windowsª menu provides three auxiliary
windows keyed directly to the anomaly to help you
determine the nature of the problem: The ©Keyword
Anomaly Traceª window, the ©Reduction Traceª window, and
the ©Rule Derivationª window. Three other windows provide
supporting information: the ©Reduction Statesª window,
the ©Rule Contextª window and the ©State Definitionª
window.
##

Keywords

The Keywords entry in the ©Browse Menuª pops up a
window which lists all of the keywords defined in your
©grammarª. The ©token numberª is also specified.

A Keywords window is also an option in the ©Auxiliary
Windowsª popup menu for any window which distinguishes
various states of your parser. The Keywords window will
show all of the ©keywordªs which will be recognized in
the state selected by the cursor bar in the parent
window.

The ©Auxiliary Windowsª menu for a Keywords window
provides a ©Token Usageª option which will allow you to
all the uses of a particular keyword in your grammar.
##

left

"left" controls a ©precedence declarationª, indicating
that all of the listed ©rule elementsª are to be
considered ©left associativeª.
##

Left Associative

A binary operator is said to be left associative if
an expression with repeated instances of the operator
is to be evaluated from the left. Thus, for example,
  x = a/b/c

is normally taken to mean x = (a/b)/c The division
operator is said to be left associative.

In ©grammarªs with ©conflictªs, you may use ©precedence
declarationªs to specify that an operator should be left
associative.
##

Lexeme

The "lexeme" ©attribute statementª is used to fine-tune
the "©disregardª" statement. The lexeme statement takes
the form:
    lexeme { T1, T2,....Tn }

where T1,...Tn is a list of ©nonterminalª tokens
separated by commas. Lexeme statements may be placed in
any ©configuration sectionª, and there may be any number
of them.

When you specify that a ©tokenª is to be disregarded,
AnaGram rewrites your ©grammarª so that the token will be
passed over whenever it occurs at the beginning of a
file or following a lexical unit, or "lexeme". If you
have no lexeme statement, then the lexemes in your
grammar are just the terminal tokens.

The lexeme statement allows you to specify that certain
nonterminal tokens are also to be treated as lexemes.
This means that the disregard token will be skipped
following the lexeme, but not between the characters
that constitute the lexeme.

Lexemes correspond to the tokens that a lexical scanner,
if you were using one, would commonly identify and pass
to a parser as single tokens. You don't usually wish to
disregard ©white spaceª within these tokens. For
example, in a grammar for a conventional programming
language where blank characters are to be disregarded,
you might include:
  [
    lexeme {string, character constant, name, number}
  ]

since blank characters must not be overlooked within
strings and constants, and should not be permitted
within names or numbers.

If your grammar allows for situations where successive
lexemes could run together if they were not separated
by space, a name followed by a number, for example, you
may use the "©distinguish lexemesª" ©configuration
switchª to force a separation between the tokens.

White space may be used explicitly within definitions of
lexeme tokens in your grammar if desired, without
causing conflicts. Thus, if you wish to allow embedded
space in variable names, you might write:
  [
    disregard space
    lexeme {variable name}
  ]
  space = ' ' + '\t'
  letter = 'a-z' + 'A-Z'
  digit = '0-9'

  variable name
   -> letter
   -> variable name, letter + digit
   -> variable name, space..., letter + digit
##

line

line is a field in your ©parser control blockª used for
keeping track of the line number of the current
character in your input. Line and column numbers are
tracked only if the ©lines and columnsª ©configuration
switchª has been set.
##

line length

Line length is an ©obsolete configuration parameterª.
##

Line Numbers

"Line numbers" is a ©configuration switchª which
defaults to off. If it is on, the ©Build Parserª
command will put "#line" directives into the generated
C code file so that your compiler diagnostics will
refer to lines in the ©syntax fileª rather than in the
generated C code file. For more information on the
"#line" directive, see Kernighan and Ritchie, second
edition, section A12.6.

If the "line numbers" switch is off, AnaGram will put
comments into your parser file to help you find
reduction procedures and embedded C in your syntax
file.

Prior to AnaGram 2.01, if your C or C++ compiler required that the
backslashes in the pathname in the #line directive be doubled, you
would have used AnaGram's ©escape backslashesª switch to make this
happen. Although you may still use ©escape backslashesª, it should no
longer be necessary because AnaGram now puts forward slashes into #line
pathnames instead of backslashes.

If you wish, you may specify the pathname in the #line
directives explicitly by using the ©Line Numbers Pathª
configuration parameter.

You may also wish to change the "©parser file nameª"
parameter to provide a full path name for your parser
file.
##

Line Numbers Path

"Line Numbers Path" is a ©configuration parameterª
which takes a string value. It defaults to NULL.

When you have set the ©Line Numbersª ©configuration
switchª and Line Numbers Path is not NULL, AnaGram
uses it in the #line directive in place of the full
path name of your ©syntax fileª.

Note that Line Numbers Path should be the complete
pathname for your syntax file.

Line Numbers Path is useful when using AnaGram in cross
platform development. When parsers are to be compiled
and tested on a platform different from that used to run
AnaGram, you may use Line Numbers Path to provide a
pathname on the platform used for compiling and
testing.
##

Lines and Columns

"Lines and columns" is a ©configuration switchª which
defaults to on. When set, i.e., on, it causes the
©Build Parserª command to incorporate code into your
parser which will automatically track the line number
and column number of the input token.

You would normally set the "lines and columns" switch
when you are planning to build a parser which will read
an input file and which will need to diagnose ©syntax
errorsª with some precision.

Your parser will store the line and column numbers in
the ©lineª and ©columnª fields respectively in the
©parser control blockª.

If the input to your parser includes tab characters, you
should either set the ©tab spacingª ©configuration
parameterª appropriately or provide a ©TAB_SPACINGª
macro for your parser.

Your parser will count line and column numbers beginning
with one.
##

Main Program

The "main program" ©configuration switchª determines
what AnaGram does if you invoke the ©Build Parserª
command, but have no ©embedded Cª in your ©syntax
fileª. If the switch is on and you have not specified
©pointer inputª or an ©event drivenª parser, AnaGram
creates a main program which does nothing but call your
©parserª. The "main program" switch defaults to on.

This feature, along with the default definitions for
©GET_INPUTª and ©error handlingª, makes it possible
to write a grammar with no ©embedded Cª or ©reduction
procedureªs whatsoever and still get an executable
program which will read input from stdin and parse it
according to your grammar.
##

Marked Rule

A "marked rule" is a ©grammar ruleª together with a
marked token that indicates how much of the rule has already
been matched. The ©marked tokenª and any tokens following it
indicate the input that should be expected if the
remainder of the rule is to be matched.

When marked rules are displayed in AnaGram windows, the
marked token is represented by a difference in the font. The token may
be in bold face, underlined, italicized, shown with a different point
size, or in a different font altogether. Since AnaGram allows you to
change fonts to suit your own preferences, you should be careful that
the font you choose for the marked tokens allows them to be readily
distinguished from the other tokens in your grammar rules. An
underlined font is often suitable.
##

Max conflicts

The "max conflicts" ©configuration parameterª limits the
number of ©conflictªs AnaGram will record.  Sometimes, a
simple error editing your syntax file can cause hundreds
of conflicts, which you don't need to see in gory
detail. The default value of max conflicts is 50. If you
have a grammar that is in serious trouble and you want
to see more conflicts, you may change max conflicts to
suit your needs.
##

Missing

The ©warningª message Missing <element 1> in <element 2>
indicates that AnaGram expects to see an instance of
syntactic element 1 at the specified location, internal
to an instance of syntactic element 2. AnaGram cannot
reliably continue parsing its input after an error of
this type. Therefore, it limits further analysis of
your grammar to scanning for syntax errors.
##

Missing Production

"Missing production, TXXX: <token name>" is a ©warningª
message which indicates that the specified ©tokenª
appears to be defined recursively, but there is no
initial ©productionª to get the recursion started. If
you get this warning, check your ©grammarª closely.
##

Missing Reduction Procedure

"Missing reduction procedure, RXXX" is a ©warningª
message which appears either when the ©grammar ruleª indicated
specifies a ©parameter assignmentª but does not have a
©reduction procedureª to use it, or when the rule has no reduction
procedure but the value of the token on the left hand side is used in
as an argument for some other reduction procedure and the ©default reduction valueª
does not have the same type as the token on the left hand side.
In this latter case, a reduction procedure may be needed to effect
correct type conversion.

This warning is
provided in case the lack of a reduction procedure is an
oversight.
##

Multiple Definitions

"Multiple definitions for TXXX: <token name>" is a
©warningª message which indicates that the specified
©tokenª has been defined both as a ©character setª and
as a ©nonterminal tokenª. It cannot be both.
##

Near Functions

"Near Functions" is a ©configuration switchª that
defaults to off. It controls the use of the "near"
keyword for static functions in your parser. If your
parser is to run on an 80x86 processor you might wish
to turn it on. Your parser will then be a slight bit
smaller and will run a little bit faster.

If you are going to run your parser on some other
processor or use a C or C++ compiler that does not
support the "near" keyword you should make sure "near
functions" is set to off.
##

Negative Character Code in Pointer Mode

This ©warningª message appears if your ©grammarª defines
negative character codes and uses ©pointer inputª. If
your grammar uses the default definition for ©pointer
typeª it will be reading unsigned characters so that
the parser will never see the negative codes that have
been defined. You may correct the problem by providing
your own definition of pointer type.
##

Nest Comments

"Nest comments" is a ©configuration switchª which
defaults to off. It controls the treatment of ©commentsª
while scanning your ©syntax fileª. It defaults to off,
in accordance with the ANSI standard for C which
disallows ©nested commentsª. Note that AnaGram scans
comments in any ©embedded Cª code as well as in the
grammar specification. You may turn this switch on and
off as many times as necessary in a single file.
##

Nested Comment

As delivered, AnaGram treats C style ©commentsª
according to the ANSI standard: They do not nest. For
those who prefer nested comments, however, the ©nest
commentsª ©configuration switchª allows them to nest.
##

Nesting too deep

This ©warningª message indicates that ©set
expressionªs or ©virtual productionsª are
nested so deeply they have exhausted the available
stack space and AnaGram cannot continue its analysis.

Use a ©definitionª statement to name an intermediate
level.
##

no cr

"no cr" is a ©configuration switchª which
defaults to off. When this switch is set, it will
cause the ©parser fileª and ©header fileª to be
written without carriage returns. This is convenient
if you wish to use the generated parser files in a
Unix environment.
##

No Grammar Token Specified

This ©warningª message appears if your ©grammarª does not
specify a ©grammar tokenª. Edit your ©syntax fileª to
specify one.
##

No Productions in Syntax File

This ©warningª message appears if AnaGram did not find
any ©productionsª at all in your ©syntax fileª. Check
to see you have the right file.
##

No Such Parameter

This ©warningª message appears when AnaGram does not
recognize the name of a ©configuration parameterª you
have tried to set in your ©syntax fileª. Check the
spelling of the parameter you wish to set in the
©Configuration Parameters Windowª.
##

No Terminal Tokens in Expansion

No terminal tokens in expansion of TXXX is a ©warningª
message indicating that there are no terminal tokens
to be found in an expansion of the specified token.
Although there are a few circumstances where this could
be legitimate, it is more likely that there is a missing
rule in the grammar.
##

Not a Character Set

"Not a character set, TXXX: <token name>" is a ©warningª
message which indicates that the specified ©tokenª has
been used both on the left side of a ©productionª and in
a ©character setª expression defining some other token.
AnaGram will use an empty set in place of the
specified token in evaluating the ©character setª. You
will get another warning, ©Error definingª token, when
AnaGram finishes its evaluation of the character set.
##

Nothing Reduces

"Nothing reduces TXXX -> RYYY" is a ©warningª message
which indicates that the ©grammarª does not specify any
input to follow an instance of the indicated ©grammar
ruleª. In all probability, the grammar does not have
any explicit end of file, or ©eof tokenª. If the grammar
does not have any conflicts with ©tokenª T000, then an
explicit end of file indicator is not necessary.
Otherwise you should modify your grammar to require an
explicit end of file.
##

Null Character in String

This ©warningª message appears when AnaGram finds an
explicit null character in a quoted string. If you must
allow for a null in a ©keyword stringª
you will have to rewrite your
©grammar ruleª. For instance, instead of

  widget
    -> "abc\0def"

write

  widget
    -> "abc", 0, "def"
##

nonassoc

"nonassoc" controls a ©precedence declarationª,
indicating that all of the listed ©rule elementsª are
to be considered non-associative.
##

Nonterminal Token, Nonterminal

A nonterminal token is one which is constructed from a
series of other tokens as specified by one or more
©productionªs. Nonterminal tokens are to be
distinguished from ©terminal tokenªs, which are the
basic input units appearing in your input stream.
Terminal tokens most often represent single characters
or a character belonging to a ©character setª such as
'a-z'.
##

Null Production

A "null production" is one that has no tokens on the
right hand side whatsoever. Null ©productionªs
essentially are identified by the first following input
token. Null productions are extremely convenient
syntactic elements when you wish to make some input
optional. For example, suppose that you wish to allow an
optional semicolon at some point in your grammar. You
could write the following pair of productions:
  optional semicolon -> | ';'
Note that a null production can never follow a '|'.

This could also be written on multiple lines thus:
  optional semicolon
    ->
    -> ';'

You can always rewrite your grammar to eliminate null
productions if you wish, but you usually pay a price in
conciseness and clarity. Sometimes, however, it is
necessary to do such a rewrite in order to avoid
©conflictªs, to which null productions are especially
prone. For example suppose you have the following
production:
  foo -> wombat, optional semicolon, widget

You can rewrite this as two productions:
  foo
    -> wombat, widget
    -> wombat, ';', widget

This rewrite specifies exactly the same input language,
but is less prone to conflicts. On the other hand, it
may require significantly more table space in your
parser.

If you have a null production with no ©reduction
procedureª specified, your parser will automatically
assign the value zero to ©reduction tokenª.

Null productions can also be generated by ©virtual
productionsª.

A token that has a null production is a "©zero lengthª"
token.
##

Old Style

"Old Style" is a ©configuration switchª which defaults
to off. It controls the function definitions in the code
AnaGram generates. When "old style" is off, it generates
ANSI style calling sequences with prototypes as
necessary. When "old style" is on, it generates old
style function definitions.
##

Output Files

When you use the ©Build Parserª command, to request
output from AnaGram, it creates two files: a ©parser
fileª and a ©parser headerª file.
##

Page Length

"Page length" is an ©obsolete configuration parameterª.
##

Obsolete Configuration Parameter, Obsolete Configuration Switch

A number of ©configuration parameterªs and ©configuration switchªes
which were used in the DOS version of AnaGram are no longer
used, but are still recognized for the sake of upward
compatibility. These parameters include:
 ©bottom marginª
 ©line lengthª
 ©page lengthª
 ©top marginª
 ©quick referenceª
 ©video modeª

##

Parameter

"Parameter <name> has type void" is a ©warningª message
which appears when a ©parameter assignmentª is attached
to a ©tokenª that has been defined to have the void
©data typeª.
##

Parameter Assignment

In any ©grammar ruleª, the ©semantic valueª of any
©rule elementª may be passed to a ©reduction procedureª
by means of a parameter assignment. Simply follow the
rule element with a colon and a C variable name. The C
variable name can then be used in the reduction
procedure to reference the semantic value of the token
it is attached to. AnaGram will automatically provide
necessary declarations.

Here are some examples of rule elements with parameter
assignments:

  '0-9':d
  integer:n
  expression:x
  declaration : declaration_descriptor

##

Parameter Not Defined

AnaGram does not have a ©configuration parameterª
with the specified name. Please check the spelling.
##

Parameter Takes Integer Value
The specified ©configuration parameterª takes
an integer value only.
##


Parameter Takes String Value

The specified ©configuration parameterª takes
a string value only.
##

Parse Function

To run your parser, you call the parse function.
The name of the parse function is given by
the ©parser nameª ©configuration parameterª and defaults to the
name of your parser file.

If your parser uses ©pointer inputª, you should set the ©pointerª
field of the ©parser control blockª before calling the parser
function.

If your parser is ©event drivenª, you should first call the
©initializerª, and then you should call the parser function
for each input token you

If the ©reentrant parserª switch is set, the parse function takes
a pointer to the ©parser control blockª as its sole argument. Otherwise
it takes no arguments. The parse function returns no value. All
communication is by means of the ©parser control blockª.

To retrieve the value of the ©grammar tokenª, once the parse is complete,
use the ©parser value functionª.
##

Parser

A parser is a program or, more commonly, a procedure within
a program, which scans a sequence of ©input charactersª
or input tokens and accumulates them in an input
buffer or stack as determined by a set of ©productionªs
which constitute a ©grammarª.

When the parser discovers
a sequence of tokens as defined by a ©grammar ruleª, or
right hand side of a production, it "reduces" the
sequence to a single ©reduction tokenª as defined by the
left hand side of the grammar rule. This ©nonterminal
tokenª now replaces the tokens which matched the grammar
rule and the search for matches continues.

If an input
token is encountered which will not yield a match for
any rule, it is considered a ©syntax errorª and some
kind of ©error recoveryª may be required to continue. If
a match, or ©reduce actionª, yields the ©grammar tokenª,
sometimes called the ©goal tokenª or ©start tokenª, the
parser deems its work complete and returns to whatever
procedure may have called it.

The ©Grammar Traceª and ©File Traceª functions in
AnaGram provide a convenient means for understanding the
detailed operation of a syntax directed parser.

©Tokensª may have ©semantic valuesª. If the ©input
valuesª ©configuration switchª is on, your parser will
expect semantic values to be provided by the input
process along with the token identification code. If the
input values switch is off, your parser will take the
ascii value of the input character, that is, the actual
input code, as the value of the character.

When the
parser reduces a production, it can call a ©reduction
procedureª or ©semantic actionª to analyze the values of
the constituent tokens. This reduction procedure can
then return a value which characterizes the reduced
token.
##

Parser Control Block

A "Parser Control Block" is a structure which contains
all of the data necessary to describe the instantaneous
state of a parser. The typedef statement which defines
the structure is included in the ©parser headerª file
for your parser. AnaGram creates the name of the data
type for the structure by appending "_pcb_type" to the
©parser nameª.

You may add your own declarations to the parser control
block by using the ©extend pcbª statement.

If the ©declare pcbª ©configuration switchª is on, its
normal state, AnaGram will declare a parser control
block for you at the beginning of your parser file.
AnaGram will determine the name of the parser control
block by appending "_pcb" to the ©parser nameª. AnaGram
will also define the macro PCB as a short hand notation
for use within the parser. All references to the parser
control block within the code that AnaGram generates
are made using the PCB macro.

If you wish to declare your own parser control block,
you must include the ©parser headerª file for your
parser before your declaration. Then you declare a
control block and define PCB to refer to the control
block you have declared.

Suppose your grammar is called widget. You would then
write the following statements in your ©embedded Cª:
  #include "widget.h"
  widget_pcb_type widget_control_pcb;
  #define PCB widget_control_pcb

Alternatively, you could write the following:
  #include "widget.h"
  widget_pcb_type *widget_control_pcb_pointer;
  #define PCB (*widget_control_pcb)

and then allocate storage for the structure when
necessary.

Some fields of interest in the parser control block are
as follows:
	©input_codeª
	©input_valueª
	©input_contextª
	©pointerª
	©token_numberª
	©reduction_tokenª
	©ssxª
	©snª
	©ssª[©parser stack sizeª]
	©vsª[parser stack size];
	©csª[parser stack size];
	©lineª
	©columnª
	*©error_messageª
	©error_frame_ssxª
	©error_frame_tokenª
##

PCB

"PCB" is a macro AnaGram defines for use in the code it
generates to refer to the ©parser control blockª for
your ©parserª. Normally, AnaGram automatically declares
storage for a parser control block and defines PCB for
you. If you turn off the ©declare PCBª switch, you may
define PCB yourself.
##

PCB_TYPE

If you are writing your parser in C++, you may prefer to derive
a class from the ©parser control blockª rather than use the
©extend pcbª statement. In this case you may define the
PCB_TYPE macro in your syntax file to specify your derived
class.

For instance, you have defined

class MyPcb : public parser_pcb_type {...};

You would then add the following line:

#define PCB_TYPE MyPcb

If you do not define PCB_TYPE, AnaGram will define it as the
type of your parser control block.
##

Parser File

The "parser file" is the C (or C++) file output by AnaGram when
you execute the ©Build Parserª command. It contains all
of the ©embedded Cª from your ©syntax fileª, all of the
©reduction procedureªs defined in your ©grammarª,
syntax tables which represent, in a condensed form, all
of the intricacies of your grammar, and a customized
©parsing engineª. The name of the parser file is given
by the ©parser file nameª ©configuration parameterª. The
name of the ©parserª itself is given by the ©parser
nameª configuration parameter.

If you wish the parser file to be written without carriage
returns, suitable for a Unix environment, set the ©no crª
configuration switch.
##

Parser File Name

"Parser file name" is a ©configuration parameterª which
takes a string value. The default value is "#.c".
AnaGram uses this parameter to generate the name of the
output C file, or ©parser fileª, created by the ©Build
Parserª command.  The '#' character is used in this
string as a wild card to indicate the name of the
current ©syntax fileª. If the first character of the
parser file name string is a '.' character, AnaGram
will substitute the name of the current working
directory for the dot. Thus ".\\#.c" will create the
file name as a complete path. This can sometimes be
important when using the ©line numbersª switch to
enable a debugger to find code in your parser file.

Note that the parser file name is not the same as the
©parser nameª.
##

Parser Generator

A parser generator, such as AnaGram, is a program that
converts a ©grammarª, a rule-based description of the
input to a program, into a conventional, procedural
module called a ©parserª. The parsers AnaGram generates
are simple C modules which can be compiled on almost
any platform. AnaGram parsers are also compatible with
C++.
##

Header File, Parser Header

When you use the command ©Build Parserª to generate
source code for a parser, AnaGram creates two files, a
header file and a C source file. Unless different
paths are specified in the ©parser file nameª and
©header file nameª parameters, both files will be
written to the directory that contains the ©syntax fileª.

The header file contains a number of typedef statements,
including the definition of the ©parser control blockª,
and a number of macro
definitions which may be useful in your parser
or in other modules of your program.

If you do not alter
the ©header file nameª parameter, the
name of the header file will be the same as the name of
your ©syntax fileª and it will have the extension ".h".

If you wish the header file to be written without carriage
returns, suitable for a Unix environment, set the ©no crª
configuration switch.
##

Parser Input

AnaGram ©parserªs may be configured to accept input in any of
three different ways:

 By default, a ©parse functionª gets its input by invoking the
©GET_INPUTª macro each time it is ready for another input token. The
default implementation of GET_INPUT reads ©input characterªs from stdin.  For
most practical problems, you will want to override this definition of
GET_INPUT, storing the current input character in PCB.input_code.

 Alternatively, you may configure a parser to read input from an
array in memory. Set the ©pointer inputª switch and load the
©pointerª field of the parser control block before calling the
parse function. The parser will then run, incrementing the
pointer, until it finishes or encounters an error.

 The third alternative is to set the ©event drivenª switch. The
parser will be configured as a callback routine. Begin by calling
the ©initializerª. Then, for each input character, store the
character in the ©input_codeª field of the parser control block and
call the parse function. Each time
you call the parse function it will continue until it needs more
input.  You can check its status by inspecting the ©exit_flagª in the
parser control block.

The input to your parser may be either text characters or ©tokensª
accumulated by a pre-processor, or ©lexical scannerª. The latter
case is referred to as ©token inputª. If you use a lexical scanner,
you may find it convenient to configure your parser as event driven.

Altlhough lexical scanners are often not necessary
when you use AnaGram, if you do need one you can write it in AnaGram.
##

Parser Name

"Parser Name" is a ©configuration parameterª which
defaults to "#", where "#" represents the name of your
©syntax fileª. AnaGram uses this parameter to name your
©parse functionª. The ©initializerª for your parser will have the
same name preceded by "init_". Note that "©parser file
nameª" is not the same configuration parameter as "parser
name".
##

Parser Stack

Your ©parserª uses a "parser stack" to keep track of the
©grammar rulesª it is trying to match and its progress
in matching them. Normally, there are two separate
stacks defined by AnaGram: ©PCBª.©ssª, the ©parser state
stackª which maintains ©parser stateª numbers, and
PCB.©vsª, the ©parser value stackª which maintains the
©semantic valueªs of tokens that have been identified so
far. If you wish to maintain a stack tracking other
variables you may set the ©context typeª ©configuration
parameterª, and AnaGram will define a third stack,
PCB.©csª. All are indexed by the same stack index,
PCB.©ssxª.

To see how tokens accumulate on the parser stack, run
the ©Grammar Traceª or the ©File Traceª.

Normally, when the return value of a ©reduction procedureª
is stored on the parser value stack, it is stored by
simply coercing the stack pointer to the correct type.
If the return value is a C++ object, this can cause
serious problems. These problems can be avoided by
using the ©wrapperª statement.
##

Parser stack alignment

Parser stack alignment is a ©configuration parameterª whose
value is a C or C++ data type. It defaults to "long". If
any tokens have type "double", it will be automatically set
to double. Thus, you will normally not need to change this
parameter if your parser is to run on a PC or compatible
processor. It provides alignment control for processors
which restrict address for multibyte data access. The
default setting provides for correct operation on 64 bit
processors.

To control byte alignment of the parser stack,
©PCBª.©vsª, AnaGram normally adds a field of the
specified data type to the "union" statement which
defines the data type for the ©parser stackª. This
parameter can be used to deal with byte alignment
problems when a ©parserª is to be run on a processor
with byte alignment restrictions. For instance, if your
©grammarª has ©tokenªs of type "long double" and your
processor requires long double variables to be
properly aligned, you can include the following
statement in a ©configuration sectionª in your grammar
or in your ©configuration fileª:

  parser stack alignment = long double

If the data type specified is "void", no alignment declaration
will be made.
##

Parser Stack Index, Stack Index

The parser stack index, ©PCBª.©ssxª, tracks the depth
of the ©parser state stackª, the ©parser value stackª,
and the ©context stackª if you defined one. The parser
stack index is incremented by ©shift actionsª and
reduced by ©reduce actionsª.
##

Parser Stack Overflow

Your ©parserª uses a ©parser stackª to keep track of the
©grammar rulesª it is trying to match and its progress
in matching them. If your grammar has any ©recursive
ruleªs that are not strictly left recursive, then no
matter how big you make the parser stack, it will be
possible to create a syntactically correct input which
will cause the stack to overflow. As a practical matter,
however, it is usually possible to set the ©parser stack
sizeª to a value large enough so that an overflow is a
freak occurrence. Nevertheless, it is necessary to check
for overflow, and in the case overflow should occur,
your parser has to do something.  What it does is invoke
the ©PARSER_STACK_OVERFLOWª macro. If you don't define
it, AnaGram will define it for you, although not
necessarily to your taste.
##

Recursive rule, Recursion

A ©grammar ruleª is said to be "recursive" if the ©tokenª on the left side
of the rule also appears on the right side of the rule, or
in an ©expansion ruleª of any token on the right side of the rule.

If the token on the left side is the
first token on the right side, the rule is said to be "left recursive".
If it is the last token on the right side, the rule is said to be
"right recursive". Otherwise, the rule is "center recursive".

For example:
  statement list
    -> statement
    -> statement list, statement  // left recursive

  fraction part
    -> digit
    -> fraction part, digit       // right recursive

  expression
    -> factor
    -> expression, '+' + '-', factor

  factor
    -> primary
    -> factor, '*' + '/', primary

  primary
    -> number
    -> name
    -> '(', expression, ')'       // center recursive

Note that if all the tokens in the rule other then the recursive token itself
are ©zero lengthª tokens, it is possible for the
rule to be matched arbitrarily many times without any input whatsoever. In
other words, such a rule creates an infinite loop in the parser. AnaGram can
detect this condition and issues an ©empty recursionª diagnostic if it occurs.

##

PARSER_STACK_OVERFLOW

PARSER_STACK_OVERFLOW is a user definable macro. If you
do not define it, AnaGram will define it so that it
will print a message on stderr and abort the ©parserª in
case of a ©parser stack overflowª.
##

Parser Stack Size

"Parser stack size" is a ©configuration parameterª with
a default value of 128. It is used to define the sizes
of your ©parser stacksª in your ©parser control blockª.
When analyzing your grammar, AnaGram will determine the
minimum amount of stack space required for the deepest
left ©recursionª. To this depth it will add one half the
value of the parser stack size parameter. It will then
set the actual stack size to the larger of this value
and the parser stack size parameter.
##

Parser State, State Number

The essential part of your ©parserª is a group of tables
which describe in detail what to do for each "state" of
the parser.

The states of a parser are determined by sets of
"©characteristic rulesª". The ©State Definition Tableª
shows the characteristic rules for each state of your
parser.

AnaGram numbers the states of a parser as it identifies
them, beginning with zero. In all windows, state numbers
are displayed as three digit numbers prefixed with the
letter 'S'.
##

Parser State Stack, State Stack

The parser state stack is a stack maintained by your
©parserª and which is an integral part of the parsing
process. At any point in the parse of your input
stream, the parser state stack provides a summary of
what has been found so far. The parser state stack is
stored in ©PCBª.©ssª and is indexed by PCB.©ssxª, the
©parser stack indexª.
##

Parser Value Stack, Value Stack

In parallel with the ©parser state stackª, your parser
maintains a "value stack", ©PCBª.©vsª, each entry of
which corresponds to the ©semantic valueª of the token
identified at that state. Since the semantic values of
different tokens might well have different ©data typeªs,
AnaGram gives you the opportunity, in your ©syntax
fileª, to define the data type for any token. AnaGram
then builds a typedef statement creating a data type
which is a union of the all the types you have defined.
AnaGram creates the name for this ©data typeª by
appending "_vs_type" to the ©parser nameª. AnaGram uses
this data type to define the value stack.
##

Parser Action

In a traditional LR parser, there are only four actions: the ©shift
actionª, the ©reduce actionª, the ©accept actionª and the ©error
actionª. AnaGram, in doing its ©grammar analysisª, identifies a
number of special cases, and creates a number of extra actions which
make for faster processing, but which can be represented as
combinations of these primitive actions.

When a shift action is performed, the current state
number is pushed onto the ©parser state stackª and the
new state number is determined by the current state
number and the current input token. Different tokens
cause different new states.

When a reduce action is performed, the length of the
rule being reduced is subtracted from the ©parser stack
indexª and the new state number is read from the top of
the parser state stack. The ©reduction tokenª for the
rule being reduced is then used as an input token.
##

Parsing Engine

A parser consists of three basic components: A set of
syntax tables, a set of ©reduction procedureªs and a
parsing engine. The parsing engine is the body of code
that interprets the parsing table, invokes input
functions, and calls the reduction procedures. The
©Build Parserª command configures a parsing engine
according to the implicit requirements of the syntax
specification and according to the explicit values of
the ©configuration parameterªs.

The parsing engine itself is a simple automaton,
characterized by a set of states and a set of inputs.
The inputs are the tokens of your grammar. Each state
is represented by a list of tokens which are admissible
in that state and for each token a ©parser actionª to perform
and a parameter which further defines the action.

Each state in the grammar, with the exception of state
zero, has a ©characteristic tokenª which must have been
recognized in order to jump to that state. Therefore,
the ©parser state stackª, which is essentially a list
of state numbers, can also be thought of as a list of
token numbers. This is the list of tokens that have
been seen so far in the parse of your input stream.
##

Partition

If you use ©character setsª in your grammar, AnaGram
will compute a "partition" of the ©character universeª.
This partition is a collection of non-overlapping
character sets such that every one of the sets you have
defined can be written as a ©unionª of partition sets.

Each partition set is assigned a unique ©tokenª. If one
of your character sets requires more than one partition
set to represent it, AnaGram will create appropriate
©productionªs and add them to your grammar so your parser
can make the necessary distinctions.

To see how AnaGram has partitioned the character
universe, you may inspect the ©Partition Setsª window
found in the ©Browse Menuª.
##

Partition Set Number

Each ©partitionª set is identified by a unique
reference number called the partition set number.
Partition set numbers are displayed in the form Pxxx.
Partition sets are numbered starting with zero, so the
first set is P000.

To see the elements of a given partition set, call up
the ©Partition Setsª window from the ©Browse Menuª,
then, after selecting a partition set, call up the ©Set
Elementsª window from the ©Auxiliary Windowsª popup menu.
##

Partition Sets

The Partition Sets option in the ©Browse Menuª pops up
a window which shows the complete ©partitionª of the
©character universeª for your parser.

The Partition Sets option in the ©Auxiliary Windowsª popup menu
for the ©Character Setsª window lets you see the
partition sets which cover the specified character set.

Each entry in a Partition Sets window identifies a
token number and a ©partition set numberª. The ©Auxiliary
Windowsª menu provides a ©Set Elementsª entry which
enables you to see precisely which characters belong to
the partition set. It also has a Token Usage entry to show you
what rules the set is used in.
##

PCONTEXT

PCONTEXT is an alternate form of the ©CONTEXTª macro
which takes an explicit argument to specify the
©parser control blockª. PCONTEXT is defined in the ©parser
headerª file.
##

PERROR_CONTEXT

PERROR_CONTEXT is an alternative form of the
©ERROR_CONTEXTª macro. It differs only in that it takes
an argument so you can specify the appropriate
©parser control blockª explicitly. PERROR_CONTEXT is defined in
the ©parser headerª file.
##

pointer

"pointer" is a field which will be included in the
©parser control blockª for your parser if you have set
the ©pointer inputª ©configuration switchª. Your main
program should set PCB.pointer before it calls your
parser. Thereafter, your parser will increment it
appropriately. When you are executing a ©reduction
procedureª or a ©SYNTAX_ERRORª macro PCB.pointer will
always point to the next input character to be read.
##

Pointer input

"Pointer input" is a ©configuration switchª which you
may set to control ©parser inputª. It defaults to off. When you set
pointer input, you tell AnaGram that the input to your parser is in
memory and can be scanned simply by incrementing a pointer. Before
calling your parser you should make sure that ©PCBª.©pointerª is
properly initialized to point to the first character or token in your
input.

Use the ©configuration parameterª "©pointer typeª" to
specify the type of the pointer. The default value of
"pointer type" is "unsigned char *"

There is no particular reason why pointer type should
be limited to variants on char. It could define a
pointer to int or a structure just as well.

If you use pointer input with structures or C++
classes, you should set the ©input valuesª switch and
define an ©INPUT_CODEª(t) macro.

If you are using a 16 bit compiler and your input array
is so large that you need "huge"
pointers, make sure that "pointer type" is properly
defined.
##

Pointer Type

"Pointer Type is a ©configuration parameterª which
defaults to "unsigned char *". When you have specified
©pointer inputª, AnaGram uses the value of pointer type
to declare a pointer field in your ©parser control
blockª.
##

Precedence, Operator Precedence

In expressions of the form a+b*c, the convention is to
perform the multiplication before the addition.
Multiplication is said to take precedence over
addition. In general the rank order in which operations
are to be performed if there are no parentheses forcing
an order of computation is called the precedence of the
operators.

If you have an ambiguous ©grammarª, that is, a grammar
with a number of ©conflictªs, you may use ©precedence
declarationªs to resolve the conflicts and to set
operator precedence.
##

Precedence Declaration

Precedence declarations are ©attribute statementsª which
may be used to resolve ©conflictªs in your grammar by
assigning precedence and associativity to operators.
Precedence declarations must be made inside
©configuration sectionsª. Each declaration consists of
the keyword ©leftª, ©rightª, or ©nonassocª followed by a
list of ©rule elementsª. The rule elements in the list
must be separated by commas and the entire list must be
enclosed in braces ({ }).

Each of the rule elements is assigned the same
precedence level, which is higher than that assigned in
all previous precedence declarations and lower than that
in all subsequent declarations. The rule elements are
defined to be left, right, or nonassociative,
depending on whether the keyword was "left", "right", or
"nonassoc".

All conflicts which are resolved by precedence
declarations are listed in the ©Resolved Conflictsª
window.
##

Precedence Rules

AnaGram can resolve certain types of ©conflictªs in your
grammar by applying precedence rules. There are three
classes of rules available:  explicit ©precedence
declarationsª, the "©stickyª" statement, and the
implicit rule associated with the use of a "©disregardª"
token outside a ©lexemeª.

Whenever AnaGram uses a precedence rule of any kind to
resolve a conflict, it produces a ©warningª message and
lists the conflict in the ©Resolved Conflictsª window.
##

Previous States

The Previous States window can be accessed via the
©Auxiliary Windowsª popup menu from any window that identifies
©parser stateªs. It shows the ©characteristic ruleªs
for all of the states which jump to the presently
selected state.
##

Print File Name

"Print file name" is a configuration parameter which
is not used in the Windows version of AnaGram. It is
retained only for compatibility with pre-existing
©configuration fileªs.
##

Problem States

The Problem States window is essentially a trimmed
version of the ©Reduction Statesª window. It is
available in the ©Auxiliary Windowsª popup menu for the
©Conflictsª and ©Resolved Conflictsª windows.

The Problem States window has the same format as the
Reduction States window, and differs only in that it
shows only those reduction states for which the
©conflict tokenª is acceptable input.
##

Production

Productions are the mechanism you use to describe how
complex input structures are built up out of simpler
ones. Each production has a left hand side and a right
hand side. The right hand side, or ©grammar ruleª, is a
sequence of ©rule elementsª, which may represent either
©terminal tokensª or ©nonterminal tokensª. The left
hand side is a list of ©reduction tokensª. In most
cases there would be only a single reduction token.
Productions with more than one ©tokenª on the left hand
side are called ©semantically determined productionsª.

The "->" symbol is used to separate the left hand side
from the right hand side. If you have several
productions with the same left hand side, you can avoid
rewriting the left hand side either by using '|' or by
using another "->".

A ©null productionª, or empty right hand side, cannot
follow a '|'.

Productions may be written thus:
  name
   -> letter
   -> name, digit

This could also be written
  name -> letter | name, digit

In order to accommodate semantic analysis of the data,
you may attach to any grammar rule a ©reduction
procedureª which will be executed when the rule is
identified. Each token may have a ©semantic valueª. By
using ©parameter assignmentªs, you may provide the
reduction procedure with access to the semantic values of
tokens that comprise the grammar rule. When it finishes, the
reduction procedure may return a value which will be
saved on the ©parser value stackª as the semantic value of the
©reduction tokenª.
##

Productions

The ©Productionªs window is available via the ©Auxiliary
Windowsª popup menu in any window which identifies tokens.
If the token identified by the highlighted line is
©nonterminalª, the Productions window will show the
rules produced by that ©tokenª.
##

PRULE_CONTEXT

PRULE_CONTEXT is an alternative form of the
©RULE_CONTEXTª macro. It differs only in that it takes
an argument so you can specify the appropriate ©parser control blockª
explicitly. PRULE_CONTEXT is defined in
the ©parser headerª file.
##

Quick Reference

"Quick reference" is an ©obsolete configuration switchª.
##

Range Bounds Out of Order

This is a ©warningª message that appears when you have a
©character rangeª of the form 'z-a'. AnaGram interprets
this range as being equal to 'a-z', but provides a
warning in case the unusual order was the result of a
clerical error.
##

Recursive Definition of Char Set

This ©warningª appears when AnaGram discovers a
recursively defined ©character setª. Character sets
cannot be defined recursively.
##

Redefinition

"Redefinition of <name>" is a ©warningª message which
appears when AnaGram discovers a redefinition of a
©symbolª. The new ©definitionª is ignored.
##

Redefinition of Grammar Token

This ©warningª appears when AnaGram encounters a new
definition of the ©grammar tokenª. AnaGram discards the
old definition. The last definition in the syntax file
wins. If you get this warning, check your ©syntax fileª
to make sure you have the grammar token you want.
##

Redefinition of token

"Redefinition of token, TXXX: <name>" is a ©warningª
message which occurs when AnaGram encounters a
©definitionª statement and the specified ©grammar tokenª
has already been seen on the left side of a
©productionª. AnaGram will ignore the definition
statement.
##

Reduce Action, Reduction

The reduce action, or reduction, is one of the four
actions of a traditional ©parsing engineª. The reduce
action is performed when the parser has succeeded in
matching all the elements of a ©grammar ruleª, and the
next input token is not erroneous. Reducing the grammar
rule amounts to subtracting the length of the rule from
the ©parser stack indexª, identifying the ©reduction
tokenª, stacking its ©semantic valueª and then doing a
©shift actionª with the reduction token as though it had
been input directly.
##

Reduce-Reduce Conflict

A grammar has a "reduce-reduce" ©conflictª at some
state if a single token turns out to be a ©reducing
tokenª for more than one ©completed ruleª.
##

Reducing Token

In a ©parser stateª with more than one ©completed ruleª,
your parser must be able to determine which one was
actually found. Therefore, during analysis of your
grammar, AnaGram examines each completed rule in order
to determine all the states the ©parserª will branch to
once the rule is reduced. These states are called the
"reduction states" for the rule. In any window that
displays ©marked ruleªs, these states may be found in
the ©Reduction Statesª window listed in the ©Auxiliary
Windowsª popup menu.

The acceptable input tokens for those states are the
"reducing tokens" for the completed rules in the state
under investigation. If there is a single token which is
a reducing token for more than one rule, then the
grammar is said to have a ©reduce-reduce conflictª at
that state. If in a particular state there is both a
©shift actionª and a ©reduce actionª for the same token
the grammar is said to have a ©shift-reduce conflictª in
that state.

Note that a "reducing token" is not the same as a
"©reduction tokenª".
##

Reduction Choices

"Reduction choices" is a ©configuration switchª which
defaults to off. If it is set, AnaGram will include in
your ©parser fileª a function which will identify the
acceptable choices for ©reduction tokenª in the current
state. This function, of course, is useful only if you
are using ©semantically determined productionsª. The
prototype of this function is:
	int $_reduction_choices(int *);
 where '$' represents the name of your parser. You must
provide an integer array whose length is at least as
long as the maximum number of reduction choices you
might have. The function will fill the array with
the token numbers of those which are acceptable in the
current state and will return a count of the number of
acceptable choices it found.
##

reduction_token

"reduction_token" is a field in your ©parser control
blockª. If your grammar uses ©semantically determined
productionsª, your ©reduction procedureªs need a
mechanism to specify which token the rule is to reduce
to. ©PCBª.reduction_token names the variable which
contains the ©token numberª of the ©reduction tokenª.
Prior to calling your reduction procedure, your parser
will set this field to the token number of the default
©reduction tokenª, i.e., the leftmost syntactically correct token in the
reduction token list for the production being reduced.
If the reduction procedure establishes that a different
reduction token is appropriate, it should store the
appropriate token number in PCB.reduction_token.
##

Reduction Procedures

The Reduction Procedures window lists the C function
prototypes for the ©reduction procedureªs in your grammar.

When this window is active, the ©syntax fileª window, if
visible, is synchronized with it so you can see the body of
the reduction procedure as well as its usage.
##

REDUCTION_TOKEN_ERROR

REDUCTION_TOKEN_ERROR is a user definable macro which your ©parserª
invokes when it encounters an inadmissible reduction
token. This error should occur only if your parser uses
©semantically determined productionsª and your
©reduction procedureª provides an incorrect ©token
numberª. If you do not define it, AnaGram will define
it so that it will print an error message on stderr and
abort the parse.

##

Reduction Procedure, Semantic Action

A "reduction procedure", or "semantic action", is a
function you write which your ©parserª executes when it
has identified the grammar rule to which the reduction
procedure is attached in your grammar.

When your parser has identified a particular ©grammar
ruleª, that is to say, a particular sequence of ©tokensª
that you have specified in your grammar, it "reduces"
the production to the token at the head of the
production, or ©reduction tokenª.

If you choose, you can
specify a "reduction procedure" which your parser will
call so that your program can do semantic analysis on
the production just identified. Your reduction procedure
will be called using, as arguments, the ©semantic
valuesª of tokens on the right side of the production.

Your reduction procedure may, if you choose, return a
value which will become the semantic value of the
reduction token. Since many of the tokens in
©productionªs are there for only syntactic purposes, you
may specify, when you write your grammar, the tokens
whose values are needed as arguments for your reduction
procedure.

To attach a reduction procedure to a grammar rule, just
write it immediately following the rule. There
are two formats for reduction procedures,
depending on the size and complexity of the procedure.

The first form consists of an equal sign followed by a C
expression and a semicolon. When the rule is matched the
expression will be evaluated and its value will be
stacked on the ©parser value stackª as
the value of the reduction token. For example:
    =-a;
    =myProcedure(x, q);

The second form consists of an equal sign followed by a
block of C code enclosed in curly braces. If you wish to
return a value for the reduction token you have to use a
return statement. For example:
    ={
      if (x > y) return x;
      return x+2y;
     }

In both forms of the reduction procedure, ©parameter
assignmentªs may be attached to ©rule elementªs in
order to make their semantic values available to the reduction
procedure. When the reduction procedure is executed,
local variables
will defined with the names specified in the parameter
assignments. The values of these variables
will have been set to the value of the corresponding
token.

If the return value of your reduction procedure is a
C++ object, you may wish to spacify that AnaGram
enclose it in a ©wrapperª so that constructor calls
and destructor calls are made. Otherwise the object
pushed onto and popped from the parser value stack simply by
coercing the stack pointer to the appropriate type.

The reduction procedures in your grammar are summarized
in the ©Reduction Proceduresª window.
##

Reduction States

The Reduction States window can be accessed via the
©Auxiliary Windowsª popup menu from any window which displays
©parser stateª numbers and ©marked ruleªs. If the highlighted
©grammar ruleª has no marked token, the Reduction States window will
show the states the parse could reach by reducing the rule and
processing the resultant ©reduction tokenª.
##

Reduction Token

A ©tokenª which appears on the left hand side of a
©productionª is called a reduction token. It is so
called because when the ©grammar ruleª on the right side
of the production is matched in the input stream, your
©parserª will "reduce" the sequence of tokens which
matches the rule by replacing the sequence of tokens
with the reduction token.

If more than one
reduction token is specified,
the production is called a ©semantically determined productionª
and your ©reduction procedureª
should choose the appropriate reduction token. If it does not, your parser
will use the first token in the list that is syntactically
correct as the default.

The ©CHANGE_REDUCTIONª macro can be used to specify the reduction
token.

Note that a "reduction token" is not the same as a
"©reducing tokenª".
##

Reduction Trace

The Reduction Trace window is available from the
©Conflictsª window and the ©Resolved Conflictsª window.
It can be used in conjunction with the ©Conflict Traceª
to study ©conflictªs. The Reduction Trace represents the
result of taking the reduce option in the conflict state
of the Conflict Trace.
##

Reentrant Parser

"Reentrant parser" is a ©configuration switchª which defaults to off.
If it is on when AnaGram builds a parser AnaGram will generate code that
passes the pointer to the ©parser control blockª via calling sequences,
rather than using static references to the pcb.

You can use the reentrant parser switch to help make ©thread safe
parsersª.

The reentrant parser switch is compatible with both C and C++.

The reentrant parser switch cannot be used in conjunction with
the ©old styleª switch.

When you have enabled the reentrant parser switch, the ©parse functionª,
the ©initializerª function, and the ©parser value functionª
will be defined to take a pointer to the parser control block as
their sole argument.
##

Reload Button

The ©File Traceª window includes a reload button to allow
you to reread your ©test fileª after you have modified
it without having to start a new file trace. After the
file has been reread, the file trace is reset.
##

rename macro

AnaGram uses a number of macros in its generated code.
It is possible, therefore, to run into naming
collisions with other components of your program. The
rename macro ©attribute statementª allows you to change
the name AnaGram uses for a particular macro to avoid
these problems.

For example, in the Microsoft
Foundation Classes, V4.2, there is a class called
"CONTEXT". If you use the ©context stackª option in
AnaGram, your ©parserª will have a macro called
©CONTEXTª. To avoid the name collision, add the
following attribute statement to any configuration
section in your grammar:
	rename macro CONTEXT AG_CONTEXT
Then, simply use "AG_CONTEXT" where you would otherwise
have used "CONTEXT".
##

reserve keywords

"reserve keywords" is an ©attribute statementª which
can be used to specify a list of ©keywordªs that are
reserved and cannot be used except as explicitly
specified in the grammar. In particular this switch
enables AnaGram to avoid issuing meaningless ©keyword
anomalyª warnings.

AnaGram does not automatically presume that keywords
are also reserved words, since in many grammars there
is no need to specify reserved words.

Reserve keywords statements must be made inside
©configuration sectionsª. Each statement consists of
the keyword "reserve keywords" followed by a list of
keyword ©tokensª.  The tokens must be separated by
commas and the list must be enclosed in braces ({ }).
Each keyword listed will then be treated as a reserved
word.
##

Reset Button

The Reset button, found on ©File Traceª and ©Grammar
Traceª windows restores the initial configuration of
the trace. This is especially convenient for ©Conflict
Traceª or other ©Auxiliary Traceªs.
##

Resolved Conflicts

AnaGram creates the Resolved Conflicts window only when
the grammar it is analyzing has ©conflictªs and when
those conflicts have been resolved by ©precedence
declarationªs, by "©stickyª" statements, or in
connection with the explicit use of a token specified in
a ©disregardª statement. The Resolved Conflicts window
shows the conflicts that have been resolved, using the
same format as that of the ©Conflictsª Window. The rule
chosen is marked with an asterisk in the leftmost column
of the window.
##

Resynchronization

"Resynchronization" is the process of getting your
parser back in step with its input after encountering a
©syntax errorª. As such, it is one method of ©error
recoveryª. Of course, you would resynchronize only if it
is necessary to continue after the error. There are
several options available when using AnaGram. You could
use the ©auto resynchª option, which causes AnaGram to
incorporate an automatic resynchronizing procedure into
your parser, or you could use the ©error token
resynchronizationª option, which is similar to the
technique used by YACC programmers.
##

right

"right" controls a ©precedence declarationª, indicating
that all of the listed ©rule elementsª are to be
considered ©right associativeª.
##

Right Associative

A binary operator is said to be right associative if
an expression with repeated instances of the operator
is to be evaluated from the right. Thus, for example,
when '=' is used as an assignment operator
	x = a = b
is normally taken to mean a = b followed by x = a The
assignment operator is said to be right associative.

In ©grammarªs with ©conflictªs, you may use ©precedence
declarationªs to specify that an operator should be
right associative.
##

Rule Context

The Rule Context window can be accessed via the
©Auxiliary Windowsª menu in any window that displays
©grammar ruleªs. AnaGram displays all occurrences in the
©grammarª of all the ©reduction tokenªs for the rule.
##

RULE_CONTEXT

RULE_CONTEXT is a macro you may use if you have defined
a ©context stackª. In any reduction procedure,
RULE_CONTEXT will be a pointer to the context value
stacked before the first token of the rule being
reduced. Since the context stack contains an entry for
each token in the rule, you may inspect the context
value for each token in the rule by subscripting
RULE_CONTEXT. RULE_CONTEXT[k] is the context of the
(k-1)th token in the rule.
##

Rule Coverage

"Rule Coverage" is the name of both a ©configuration
switchª and a window. The configuration switch
defaults to off. If you set it, AnaGram will include
code in your ©parserª to count the number of times your
parser identifies each ©grammar ruleª in your grammar.
To maintain the counts, AnaGram declares, at the
beginning of your parser, an integer array, whose name
is created by appending "_nrc" to your ©parser nameª.
The array contains one counter for each rule you have
defined in your grammar. There are no entries for the
auxiliary rules that AnaGram creates to deal with set
overlaps or ©disregardª statements. In order to identify
positively all the rules that the parser reduces,
AnaGram has to turn off certain optimization features in
your parser. Therefore a parser that has rule coverage
enabled will run slightly slower that one with the
switch off.

In addition, AnaGram creates a pair of functions to
write the counters to a file and to initialize the
counters from a file. The names of these functions are
given by appending "_write_counts" and "_read_counts" to
the name of your parser. The name of the file is given by the
©coverage file nameª paramater which defaults
to the name of your ©syntax fileª but with the extension ".nrc".

If rule coverage is enabled, AnaGram will also enable the
Rule Coverage option on the ©Browse Menuª. If you select
Rule Coverage, AnaGram will initialize a ©Rule Coverageª
window from the rule count file you select.

AnaGram will
warn you if the rule count file is older than
the syntax file, since under those conditions, the
coverage file might be invalid.
##

Rule Derivation, Token Derivation

You can use the Rule Derivation and Token Derivation
windows to understand the nature of ©conflictªs in your
grammar. To create these windows, open the ©Conflictsª
window. Move the cursor bar to a ©completed ruleª, that
is, one which has no marked token. Press the right mouse button to pop
up the ©Auxiliary Windowsª menu. You may then select the Rule
Derivation or the Token Derivation.

The Rule Derivation window and the Token Derivation
window, together, show how a ©conflictª, or ambiguity,
has arisen in your grammar. Both windows contain a
sequence of rules, and both begin with the same rule,
the rule which is the root cause of the conflict.

Each subsequent line in the rule derivation is an
©expansionª of the marked token in
the previous rule. The last rule in the derivation
window is the rule you selected in the Conflicts
window. Thus the rule derivation window shows you how
the rule involved in the conflict derives from the
root.

Each subsequent line in the token derivation window
shows an expansion of the marked token in the previous rule. The first
token of the last rule in the derivation window is the token that
causes the conflict. This is the usage that is inconsistent with other
usages of this token in the conflict state.

The Rule Derivation and Token Derivation windows each
have five auxiliary windows. The ©Rule Contextª window
is keyed to the highlighted rule. the other four
windows, the ©Expansion Rulesª window, the
©Productionsª window, the ©Set Elementsª window and the
©Token Usageª window are keyed to the marked token.
Remember that there is no marked token on the last
line of the Rule Derivation window.
##

Rule Element

A ©grammar ruleª is a list of "rule elements", separated
by commas. Rule elements may be ©token nameªs,
©character setsª, ©keywordªs, ©immediate actionªs, or
©virtual productionsª. When AnaGram encounters a rule
element for which no token presently exists, it creates
one.

Any rule element may be followed by a ©parameter assignmentª
in order to make the ©semantic valueª of
the rule element available to a ©reduction procedureª.
##

Rule Number

AnaGram assigns a unique rule number to each ©grammar
ruleª that you specify in your grammar. Rules are
numbered sequentially as they are encountered in the
©syntax fileª. AnaGram constructs rule 0 itself. Rule
zero has a single ©rule elementª, the ©grammar tokenª,
unless you have an ©disregardª statement in your
grammar. In this case, there will be two elements.

In AnaGram displays, rule numbers are displayed with a
prefixed 'R' and a three digit decimal number.
##

Rule Stack, Rule Stack Pane

The Rule Stack pane appears across the bottom of a ©Grammar
Traceª or ©File Traceª window. It provides an alternate view of the
parser stack for the trace, showing, for each state, rules instead of
the tokens that you see in the ©Parser Stack paneª. Because it is
synched with the syntax file window, the Rule Stack makes it easy to
see the relationship between the trace and your grammar.

For each level of the parser stack, the Rule Stack shows the ©parser
stateª number and all the active rules. The active rules at any
state consist of all the ©expansion ruleªs for the state that are
consistent with the input at all subsequent states.

Except for the last level
of the stack, each rule has a ©marked tokenª, which in the default
configuration is displayed in bold, italic type. The significance of
the marked token is that all tokens in the rule to the left of the
marked token have already been matched in the input, and the input
in subsequent levels is consistent so far with the marked
token. As more input is processed, rules
that are inconsistent with the new input are deleted from the display.

The last level of the stack shows the current state of the parser and
the rules against which the ©lookahead tokenª will be matched. At
this level, there may be rules with no marked tokens. These are
rules which have been matched exactly in the input. If there is
more than one such rule, at the next parser step the parser will use
the lookahead token to determine which rule to reduce.

In the last level of the stack, marked tokens represent the input the
parser expects to see.

The Rule Stack pane is synched with the ©syntax fileª window if it is
visible so that the rule highlighted in the Rule Stack can be seen
in context in the syntax file.
For rules that AnaGram
generated automatically (to implement ©virtual productionsª
or the ©disregardª statement). the cursor bar will move to the
top of the syntax file window.

The Rule Stack pane is also synched with the other panes in the trace.
As you move the cursor bar in the Rule Stack, the cursor bar in the
Parser Stack pane will track the stack level in the Rule Stack. In
a File Trace, text will be highlighted in the ©Test Fileª pane
corresponding to the selected token in the Parser Stack pane. In a
Grammar Trace, the marked token in the highlighted rule will be
highlighted in the ©Allowable Input paneª.

Clicking the right mouse button pops up an ©Auxiliary Windowsª menu to
give you more information about the highlighted rule.
##

Rule Table

The Rule Table lists, in numerical order, all the
©grammar ruleªs defined in your ©grammarª. Each rule is
preceded by the ©nonterminalª tokens which produce it.
If you are not using ©semantically determined
productionªs, then there will be precisely one token
line per rule. The Rule Table is synched to your ©syntax
fileª to show the rule in context.
##

Semantic Value, Token Value

A ©tokenª generally has a "semantic value", or "token
value", as well as the ©token numberª which identifies
it syntactically.  Each instance of the token in the
input stream can have a different value. For example,
you might have a token called "variable name". In one
instance the variable name might be "widget" and in
another, "wombat". Then "widget" and "wombat" would be
the semantic values in the two instances. Another token
might have numeric semantic values.

You can specify the C or C++ ©data typeª of the token value.
The data type of "variable name" could be "char *"
where the value is a pointer to a string holding the name. There
are separate default types for the values of ©terminalª
and ©nonterminalª tokens. In the usual case of ordinary
character input, the value of a terminal token is just
the ascii character code.

The value of a nonterminal token is determined by the ©reduction procedureªs
attached to the rules the token produces. If there is no reduction
procedure, the value of the token is the value of the first token
in the rule.

It should be noted that the stack operations have been
implemented in such a way that a C++ object that belongs
to a class for which the assignment operator has been
overridden will encounter serious problems. This shortcoming
will be addressed in a future version of AnaGram. Note that
there is no problem with using a pointer to any C++ object.
##

Semantically Determined Production

A "semantically determined production" is one which has
more than one ©reduction tokenª specified on the left
side of the ©productionª. You would write such a
production when the reduction tokens are syntactically
indistinguishable. The ©reduction procedureª may then
specify which of the listed reduction tokens the grammar
rule is to reduce to based on semantic considerations.
If there is no reduction procedure, or the reduction
procedure does not specify a reduction token, the parser
will use the first syntactically correct one in the list.

To simplify changing the reduction token, AnaGram
provides a predefined macro, ©CHANGE_REDUCTIONª.

The ©semantic valueªs of all the reduction tokens for a
given semantically determined production must have the
same ©data typeª.

©File Traceª and ©Grammar Traceª have a ©Reduction Choices paneª which
appears when a semantically determined production is invoked and
you need to choose a reduction token.
##

Set Elements

The Set Elements window is available via the ©Auxiliary
Windowsª popup menu from windows which specify character sets,
partition sets or tokens. It displays the actual
characters which make up the set, or which map to the
specified token. For each character, the numeric code as
well as its display symbol is given.
##

Set Expression, Expression

A set expression is an algebraic expression used to
define a ©character setª in terms of individual
characters, ranges of characters, or other sets of
characters as constructed using ©complementsª, ©unionsª,
©intersectionsª, and ©differencesª.
##

Shift Action

The shift action is one of the four actions of a
traditional ©parsing engineª. The shift action is
performed when the input token matches one of the
acceptable input tokens for the current ©parser stateª.
The ©semantic valueª of the token and the current
©state numberª are stacked, the ©parser stack indexª is
incremented and the state number is set to a value
determined by the previous state and the input token.
##

Shift-Reduce Conflict

A "shift-reduce" ©conflictª occurs if in some ©parser
stateª there exists a ©terminal tokenª that should be
shifted, because it is legitimate input for one of the
©grammar ruleªs of the state, but should also be used to
reduce some other rule because it is a ©reducing tokenª
for that rule.
##

sn

sn is a field in a ©parser control blockª to which your
©error handlingª routines and your ©reduction
procedureªs may refer. Its value is the current ©state
numberª of your ©parserª. sn is modified every time
your parser "shifts" (performs a ©shift actionª on) a
token or reduces (performs a ©reduce actionª on) a
©productionª.
##

ss

ss is a field in a ©parser control blockª to which your
©error handlingª and ©reduction procedureªs may refer.
It is the ©state stackª for your ©parserª. Before every
©shift actionª, the current ©state numberª, ©snª, is
stored in PCB.ss[PCB.ssx], where ©ssxª is the ©parser
stack indexª. PCB.ssx is then incremented.
##

ssx

ssx is a field in a ©parser control blockª to which
your ©error handlingª routines and ©reduction
procedureªs may refer. It is the ©parser stack indexª
for your ©parserª. On every ©shift actionª it is
incremented. On every ©reduce actionª the length of
the ©grammar ruleª being reduced is subtracted from
PCB.ssx.
##

State Definition

The State Definition window can be accessed via the
©Auxiliary Windowsª popup menu from any window that specifies
states. It displays the ©characteristic rulesª that
define the state. The rules are displayed with a marked token, which is
the next token needed in the input if the particular ©grammar ruleª is
to be matched. If the rule is a completed rule, no token will be
marked.

Each line contains the state number, blank if it is the
same as the state number of the previous line, the ©rule
numberª, and finally the ©marked ruleª.

The ©State Definition Tableª, found in the ©Browse
Menuª, displays the characteristic rules for all states
in the ©grammarª.
##

State Definition Table

The State Definition Table lists, for each ©parser
stateª, all of the ©characteristic rulesª which define
that state. The rules are displayed with a ©marked tokenª, which is the
next token needed in the input if the particular ©grammar ruleª is to
be matched. If the rule is a completed rule, no token will be
marked.

Each line contains the state number, blank if it is the
same as the state number of the previous line, the ©rule
numberª, and finally the ©marked ruleª.

In the ©Auxiliary Windowsª menu for many states there is
a ©State Definitionª entry which provides the
characteristic rules for the ©parser stateª identified by
the cursor bar.
##

State Expansion

The State Expansion window may be accessed using the
©Auxiliary Windowsª menu from any window that identifies
a particular ©parser stateª. It shows the complete set
of ©expansion ruleªs for the state, consisting of the
union of the set of ©characteristic ruleªs and, for each
characteristic rule, the set of expansion rules for the
marked token. Thus the State
Expansion window shows all possible legal input to your
parser in the given state.
##

Sticky

"Sticky" statements are ©attribute statementªs and may
be used just like a ©precedence declarationª to resolve
©conflictªs. If a ©shift-reduce conflictª occurs in a
state where the ©characteristic tokenª is "sticky", the
shift action will always be chosen.

Sticky statements must be made inside ©configuration
sectionsª. Each statement consists of the keyword
"sticky" followed by a list of ©tokensª. The tokens must
be separated by commas and the list must be enclosed in
braces ({ }). Each token will then be treated as sticky.

All conflicts which are resolved by sticky statements
are listed in the ©Resolved Conflictsª window.
##

subgrammar

Declaring a nonterminal token to be a "subgrammar"
changes the way AnaGram searches for reducing tokens.

Normally, if there is a completed rule in a particular
state, AnaGram investigates all states to which the
parser could jump on reducing the rule. It then
considers all terminal tokens that are acceptable input
in these states to be reducing tokens for the given
rule. If this set of tokens overlaps the set of tokens
for which there are shift actions, or the set of tokens
which reduce a different rule, there is a ©conflictª.

Now consider a particular nonterminal token T and all
the rules it produces, whether directly or indirectly.
What the preceding remarks mean is that in determining
the reducing tokens for any of these rules, AnaGram
considers not only the definition, but also the usage
of T.

There are circumstances when it is inappropriate to
consider the usage of T. The most common example occurs
when building a lexical scanner for a language such as
C. In this case, you can write a complete grammar for a
C token with no difficulty. But if you try to extend it
to a sequence of tokens, you get scores of conflicts.
This situation arises because you specify that any C
token can follow another, when in actual practice, an
identifier, for example, cannot follow another
identifier without some intervening space or
punctuation. While it is theoretically possible to write
a grammar for a sequence of tokens that has no
conflicts, it is not usually pretty.

The subgrammar declaration resolves this problem by
telling AnaGram that when it is looking for reducing
tokens for any rule produced directly or indirectly by a
subgrammar token, it should disregard the usage of the
token and only consider usage internal to the definition
of the subgrammar token, as though the subgrammar token
were the start token of the grammar.

The subgrammar declaration is made in a ©configuration
sectionª and consists of the keyword "subgrammar"
followed by a list of token names separated by
commas and enclosed in braces ({ }). For example:
	subgrammar { name, number}
##

Suspicious Production

This ©warningª message appears when AnaGram finds a
©productionª of the form x -> x. There is probably a
typo somewhere in your ©syntax fileª. This production
causes a ©conflictª in your grammar. AnaGram leaves
this production in your ©grammarª, but if you build a
parser, it will never succeed in recognizing this
production.
##

Switch Takes on/off Values Only

The specified parameter is a ©configuration switchª. The
only values it may be assigned are ON and OFF.

##

Symbol

In writing your ©grammarª you use symbols, or names, to
represent most of your ©tokensª. You may also use
symbols to represent ©character setªs, ©virtual
productionªs, ©immediate actionªs, or ©keywordªs.

A symbol, or name, must begin with a letter or an
underscore. It may then contain any number of these
characters as well as digits and embedded white space
(including comments). For identification purposes all
adjacent white space characters within a symbol name
are considered to be a single blank.

Upper case and lower case letters are considered to be
different.

Examples:
	token name
	token/*embedded comment*/name

 All symbols used in your grammar are listed in
the ©Symbol Tableª window found in the ©Browse Menuª.
##

Symbol Table

The Symbol Table lists all the symbols, or names, you
used in your grammar. ©Symbolªs may be used, of course,
to identify ©tokensª, ©definitionsª, ©virtual
productionsª, ©immediate actionªs, or ©keywordªs.

Each line in this table identifies a single symbol. The
first field is the token number, if any. This is
followed by the name. If the name identifies an
©expressionª or virtual production, it is followed by an
equal sign and the expression or virtual production.
##

Syntax Analysis Aborted

This ©warningª message appears if, because of previous
errors, AnaGram is unable to complete the ©Analyze
Grammarª command on your ©syntax fileª.
##

Syntax Directed Parsing

Syntax directed parsing, or formal parsing, is an
approach to building ©parsersª based on formal language
theory. Given a suitable description of a language,
called a ©grammarª, there are algorithms which can be
used to create parsers for the language automatically.
In this context, the set of all possible inputs to a
program may be considered to constitute a language, and
the rules for formulating the input to the program
constitute the grammar for the language.

The parsers built from a grammar have the advantage
that they can recognize any input that conforms to the
rules, and can reject as erroneous any input that fails
to conform.

Since the program logic necessary to parse input is
often extremely intricate, programs which use formal
parsing are usually much more reliable than those built
by hand. They are also much easier to maintain, since
it is much easier to modify a grammar specification
than it is to modify complex program logic.
##

Syntax Error

When you specify a ©grammarª, you specify a set of
input character or token sequences which your ©parserª
will "recognize". Usually it is possible for there to
be other sequences of input tokens which deviate from
the rules set down by your grammar. Should your parser
find such a sequence in its input which is not
explicitly allowed for in your grammar, it is said to
have found a "syntax error". The general treatment of
syntax errors is called ©error handlingª, of which there
are two distinct aspects: ©error diagnosisª and ©error
recoveryª. AnaGram allows you to make provision for
error handling to fit your needs, but should you not do
so, it will provide simple default error handling.
##

Statements

AnaGram source files, or ©syntax fileªs, consist of
the following types of statements:
	 ©productionªs
	 ©configuration sectionªs
	 ©embedded Cª
	 ©definitionªs
	 ©token declarationªs

 Statements may be in any order. Each statement must
begin on a new line. If a statement cannot be
construed as complete, it may continue onto another
line.

Statements may contain spaces, tabs or comments, but
may not contain blank lines.
##

Syntax File

Input files to AnaGram are called syntax files. The
default extension for syntax files is .syn. A
syntax file contains a "©grammarª" and supporting C or
C++ code.  The file consists of several distinct types
of statements. These are ©token declarationsª,
©productionªs, ©definitionsª, ©embedded Cª, and
©configuration sectionsª. There may be as many of each
as you need, in whatever order you find convenient.

Each such statement begins on a new line.
##

SYNTAX_ERROR

SYNTAX_ERROR is a macro which your parser will invoke
when it encounters a syntax error in its input stream.
If you have set the ©diagnose errorsª ©configuration
switchª, the static variable ©PCBª.©syntax_errorª will
contain a pointer to a diagnostic message when
SYNTAX_ERROR is invoked. If you have also set the
©error frameª switch, ©PCBª.©error_frame_ssxª and
©PCBª.©error_frame_tokenª will also be set
appropriately.
##

Tab Spacing

"tab spacing" is a ©configuration parameterª which
controls the expansion of tabs when AnaGram displays
your source file or test files in the ©File Traceª window.

The value of "tab spacing" is also used to set the
default value of the ©TAB_SPACINGª macro in your parser.

The default value of "tab spacing" is 8. If you prefer
a different value, you should probably include an
appropriate statement in your ©configuration fileª. For
example:

	tab spacing = 2
##

TAB_SPACING

If you have enabled the ©lines and columnsª switch, your
parser needs to know tab spacing in order to increment
the column count when it encounters a tab character. It
is set up to use the value given by the TAB_SPACING
macro. If you do not define TAB_SPACING in your parser,
AnaGram will provide a default definition, setting it to
the value of the ©tab spacingª ©configuration
parameterª.
##

Terminal, Terminal Token

A "terminal token" is a token which does not appear on
the left side of a ©productionª. It represents,
therefore, a basic unit of input to your ©parserª.  If
the input to your parser consists of ascii characters,
you may define terminal tokens explicitly as ascii
characters or as sets of ascii characters. If you have a
lexical scanner, or preprocessor, which produces numeric
codes, you may define the terminal tokens directly in
terms of these numeric codes.
##

Test File Binary

"Test file binary" is a ©configuration switchª which
defaults to off. When it is off, and you select the
©File Traceª option, AnaGram will read your test files
in "text" mode, discarding carriage return characters.
When "test file binary" is on, AnaGram will read test
files in "binary" mode, preserving carriage return
characters.

If your parser needs to recognize carriage return
characters explicitly, you should turn "test file
binary" on.
##

Test File Mask

"Test file mask" is a string-valued ©configuration
parameterª which AnaGram uses to set up the file dialog
for the ©File Traceª command. It defaults to "*.*". If
there is a conventional file name format for the input
to the ©parserª you are developing, you will probably
want to set "test file mask" in a ©configuration
sectionª in your ©syntax fileª so it is easier to pick
out your test files.
##

Test range

"Test range" is a ©configuration switchª which defaults
to on. When it is set, i.e., on, AnaGram will configure
your parser so that it checks input characters to
verify that they are within the range given by the
©character universeª before it indexes the ©token
conversionª table. If range testing is not necessary
for your parser, you may turn test range off and get a
slight improvement in the performance of your parser.
##

Thread Safe Parsers

AnaGram 2.01 incorporates several changes designed to make it
easier to write thread safe parsers.

First, the ©parserªs generated by AnaGram 2.01 no longer use static or global
variables to store temporary data. All nonconstant data have been
moved to the ©parser control blockª.

Second, two new features which make it substantially
easier to build thread safe parsers have been added. The ©reentrant parserª switch
makes the entire parser reentrant, by passing the pointer to the parser control
block as an argument on all function calls. The ©extend pcbª statement allows
you to add your own variable declarations to the ©parser control
blockª so you can avoid references to global or static variables in
your ©reduction procedureªs.

Third, new support has been added for C++ classes, including
the ©wrapperª statement and the ©PCB_TYPEª macro.
##

token_number

token_number is a field in a ©parser control blockª to
which your ©error handlingª procedures and ©reduction
procedureªs may refer. It contains the actual ©token
numberª of the current input token. If you are supplying
token numbers directly, it is the result of using the
actual input character to index the ©token conversionª
array, ag_tcv.
##

Token

Tokens are the units with which your parser works.
There are two kinds of tokens: ©terminal tokensª and
©nonterminal tokensª. These latter are identified by the
parser as sequences of tokens. The grouping of tokens
into more complex tokens is governed by the ©grammar
rulesª, or ©productionªs in your grammar. In your
grammar, tokens are denoted by ©token nameªs, ©virtual
productionsª, explicit ©character representationsª,
©keywordªs, ©immediate actionªs, or ©expressionªs which
yield ©character setsª.
##

Token Conversion

By using ©character setª ©expressionªs, you may in your
©syntax fileª define a number of input characters as
being syntactically equivalent. When your ©parserª gets
an input character, it uses the character code to index
a table called ©ag_tcvª. The value it extracts from this
table is the ©token numberª for the input character. The
actual character code of the input character becomes the
©token valueª.
##

Token Declaration

A token declaration is simply a ©productionª with no
right hand side. Token declarations can be used to
define the ©data typeªs of tokens. To define the data type
of a token, simply put the data type in parentheses
preceding the name of the token. You can use a list of
tokens joined by commas, if you wish.  Thus:
	(char *) variable name, function name
could be used to specify that the ©semantic valueªs of
the tokens "variable name" and "function name" are both
character pointers.

Of course, token types may be specified as part of any
production the token generates, but sometimes, in the
interest of clarity, it is advisable to group all
declarations together.
##

Token Name

All ©nonterminal tokensª that you define in your
©grammarª by means of explicit ©productionªs must have
names by which they may be referenced. Token names are
©symbolsª which represent the token syntactically in
your grammar specification.
##

Token Names

"Token names" is a ©configuration switchª that defaults
to off. If it is set, it causes AnaGram to include in
the ©parser fileª a static array of character strings, indexed by
token number, which provides ascii representations of token
names. The name of this array is given by "<parser name>_token_names",
where <parser name> is the name of the parser function as
given by the value of the ©parser nameª parameter.

AnaGram also defines a macro, ©TOKEN_NAMESª, which evaluates
to the name of the array.

The array contains strings for all grammar tokens which have
been explicitly named in the syntax file as well as tokens
which represent ©keywordªs or single character constants.

The array is useful in creating ©syntax errorª diagnostics.

Prior to version 2.01 of AnaGram, the TOKEN_NAMES array contained
strings only for explicitly named tokens. If this restriction
is required, set the ©token names onlyª switch.

Token names are also included if the ©diagnose errorsª
switch is set.
##

TOKEN_NAMES

"TOKEN_NAMES" is the name of a macro that AnaGram defines to
provide access to a static array of character strings indexed by
token number, which provides ascii representation of token
names. The array is generated if any of the ©token namesª,
©token names onlyª or ©diagnose errorsª switches are ON.

If ©token names onlyª is set, the array contains non-empty
strings only for those tokens which are explicitly named
in the syntax file. Otherwise, the array also contains
strings for tokens which represent keywords or single
character constants.
##


token names only

"Token names only" is a ©configuration switchª that defaults to
off. If it is set, it will cause AnaGram to include in the
parser file a static array containing the names of the tokens
in your grammar. This array will include only those tokens
to which you have assigned names explicitly and will not
include character constants or keywords. "Token names only"
takes precedence over ©token namesª.
##

Token Not Used

"Token not used, TXXX: <token name> is a ©warningª
message which appears if AnaGram finds an unused ©tokenª
in your ©grammarª. Often an unused token is the result
of an oversight of some kind and indicates a problem in
the grammar.
##

Token Number

AnaGram assigns a unique number, called the "token
number" to each token in the grammar, no matter whether
it is a ©terminal tokenª or a ©nonterminal tokenª. Your
parser does all of its analysis of your input stream
using token numbers as its primary material.

You may need to know the values of token numbers that
AnaGram has assigned, either so a lexical scanner can
output correct token numbers, or so a ©reduction
procedureª can correctly resolve a ©semantically
determined productionª.

To help you, AnaGram defines enumeration constants for
each of the named tokens in your grammar. The definition
of these constants is in the ©parser headerª file.
##

Token Representation

Not all of the ©tokensª in your grammar have a ©token
nameª. Some of the tokens may represent ©character setsª
which you spelled out explicitly, ©virtual productionsª,
©immediate actionªs, or ©keywordªs. In its analysis
tables, AnaGram tries to provide a meaningful
representation for tokens whenever it can. Its first
choice is to use the name, if it has one. Otherwise it
will use the set definition or the definition of the
virtual production if one exists. If AnaGram cannot
otherwise represent your token, it will resort to using
the token number which it normally represents using the
letter T followed by a three digit, zero-padded token
number.
##

Token Table

The Token Table lists all the tokens of your grammar.
The first field is the token number. It is followed by a
flag field which is "zl" if the token is a ©nonterminal
tokenª and is ©zero lengthª. If the token is nonterminal
and not zero length, the flag field contains "nt". If
the token is a ©terminal tokenª, the field is blank.

The next field is blank unless the token has been
declared ©stickyª or has had a ©precedenceª level
assigned. If the token is sticky, this field will
contain 's'. If a precedence level has been assigned,
this field will contain the letter 'l', 'r', or 'n' to
indicate associativity followed by the precedence
level. Finally there is the ©data typeª of the ©semantic
valueª of this token and the ©token representationª.
##

Token Usage

The Token Usage table may be accessed via the ©Auxiliary
Windowsª menu from any window that identifies tokens. It
shows all the rules in the grammar that use the token.
##

Top Margin

"Top margin" is an ©obsolete configuration parameterª.
##

Trace Coverage

Trace Coverage is a table which is built whenever you
run ©Grammar Traceª, one of its pre-built versions, or a ©File
Traceª.  You can access it from the ©Browse Menuª. It shows the number
of times each rule in your grammar has been reduced. Unless you have
set the ©Rule Coverageª ©configuration switchª, some ©null productionªs
and some rules that consist of only one element will not be counted
because of speed optimizations in the parser tables.

The Trace Coverage tables are reset to zero when you load a new syntax
file or start AnaGram.
##

Compound Action

Traditionally, ©LALR-1 parserªs use only four simple
©parser actionªs: shift, reduce, accept and error.
AnaGram parsers use a number of compound actions
in order to reduce the size of parse tables and
speed up processing. A single compound action
may replace several simple shift or reduce actions.

The ©Traditional Engineª ©configuration switchª may
be used to force AnaGram to use only the simple
actions.
##

Traditional Engine

"Traditional engine" is a ©configuration switchª that
defaults to off. Traditional ©LALR-1 parserªs use a
©parsing engineª which has only four actions:
 ©shift actionª
 ©reduce actionª
 ©accept actionª
 ©error actionª


AnaGram, in the interest of
faster execution and more compact parse tables,
uses a parsing engine with a number of
short-cut, or ©compound actionªs. The "traditional engine" switch tells
AnaGram not to use the short-cut actions.

You would turn this switch on if you wished to use the ©Grammar Traceª
or ©File Traceª to see how the standard four parser actions work for
a particular combination of grammar and input. Note that to see the
effects of single parser actions, you must use the ©Single Stepª
button. Remember that in the Grammar Trace, when you single step and
the token you have selected causes a reduce action, it will appear
on the ©lookahead lineª of the ©parser stack paneª and will be preselected
in the ©allowable input paneª until it is finally shifted in to
the parser stack.

Normally, you should leave the "traditional engine" switch off, Then
AnaGram will, whenever possible, compress several parsing actions into
one compound action in order to speed execution of the parser.

Unfortunately use of the term "traditional" has sometimes created the
impression that there is a conservative aspect to the operation of
traditional engine parsers. This is not the case. They have the same
effect, but are slower and have much larger tables.
##

Type Redefinition

"Type Redefinition of TXXX: <token name> is a ©warningª
message which appears when AnaGram finds a conflicting
©data typeª definition for a ©tokenª in your ©grammarª.
The new definition will override the previous one. If
you intend to use different type definitions, you should
use extreme caution and check the generated code to
verify that your ©reduction procedureªs are getting the
values you intended.
##

Undefined Symbol

"Undefined symbol: <name>" is a ©warningª message which
appears when AnaGram encounters an undefined ©symbolª
while evaluating a ©character setª expression. The
following warning in the ©Warningsª window identifies
the particular ©tokenª AnaGram was trying to evaluate.
##

Undefined Token

"Undefined token TXXX: <name>" is a ©warningª message
which appears when the indicated ©tokenª has been used
in the ©grammarª, but there is no definition of it as a
©terminal tokenª nor does any ©productionª define it as
a ©nonterminal tokenª.
##

Unexpected

"Unexpected <element 1> in <element 2>" is a ©warningª
message which you may get when AnaGram analyzes your
grammar. It appears when AnaGram unexpectedly encounters an instance of
syntactic element 1 at the specified location in an instance of
syntactic element 2.  AnaGram cannot reliably continue parsing its
input.  Therefore, it limits further analysis to scanning for syntax
errors. If this error is not the result of a prior error, you should
correct your ©syntax fileª.  Remember that this error could result from
something missing just as well as from something extraneous.

If element 1 is ©eofª, it often means that you have
an unbalanced brace or comment delimiter in the code
following the indicated location.
##

Union

The union of two sets is the set of all elements that
are to be found in one or another of the two sets. In an
AnaGram syntax file the union of two ©character setsª A
and B is represented using the plus sign, as in A + B.
The union operator has the same precedence as the
©differenceª operator: lower than that of ©intersectionª
and ©complementª. The union operator is ©left
associativeª.

Watch out! In an AnaGram syntax file 65 + 97 represents
the character set which consists of the lower case 'a'
and upper case 'A'. It does not represent 162, the sum
of 65 and 97.
##

Video mode

"Video mode" is an ©obsolete configuration parameterª.
##

Virtual Production

Virtual productions are a special short hand
representation of ©grammar rulesª which can be used to
indicate a choice of inputs. They are an important
convenience, especially useful when you are first
building a grammar.

Here are some examples of virtual productions:
	name?						// optional name
	name?...					// 0 or more instances of name
	{name | number}			// exactly one name or number
	{name | number}...			// one or more instances of name or number
	[name | number]			// optional choice of name or number
	[name | number]...			// zero or more instances of name or number

 AnaGram rewrites virtual productions, so that when you
look at the syntax tables in AnaGram, there will be
actual ©productionªs replacing the virtual productions.

A virtual production appears as one of the rule
elements in a grammar rule, i.e. as one of the members
of the list on the right side of a production.

The simplest virtual production is the "optional"
token. If x is an arbitrary token, x? can be used to
indicate an optional x.

Related virtual productions are x... and x?...  where
the three dots indicate repetition. x... represents an
arbitrary number of occurrences of x, but at least one.
x?... represents zero or more occurrences of x.

The remaining virtual productions use curly or square
brackets to enclose a sequence of rules. The brackets
may be followed variously by nothing, a string of three
dots, or a slash, to indicate the choices to be made
from the rules. Note that rules may be used, not merely
tokens.

If r1 through rn are a set of ©grammar rulesª, then
	{r1 | r2 | ... | rn}
is a virtual production that allows a choice of exactly
one of the rules. Similarly,
	{r1 | r2 | ... | rn}...
is a virtual production that allows a choice of one or
more of the rules. And, finally,
	{r1 | r2 | ... | rn}/...
is a virtual production that allows a choice of one or
more of the rules subject to the side condition that
rules must alternate, that is, that no rule can follow
itself immediately without the interposition of some
other rule. This is a case that is not particularly
easy to write by hand, but is quite useful in a number
of contexts.

If the above virtual productions are written with []
instead of {}, they all become optional. [] is an
optional choice, []... is zero or more choices, and
[]/... is zero or more alternating choices.

Null productions are not permitted in virtual
productions in those cases where they would cause an
intrinsic ambiguity.

You may use a ©definitionª statement to assign a name to
a virtual production.
##

Void token

"Void token, <token name>, used as parameter" is a
©warningª message which appears if AnaGram encounters a
©data typeª definition declaring a ©tokenª to have type
void when the token has previously been used in a
©parameter assignmentª for a ©reduction procedureª. Your
C or C++ compiler will complain when it tries to compile
the call to the reduction procedure.
##

vs

vs is a field in a ©parser control blockª to which your
©error handlingª procedures and ©reduction procedureªs
may refer. It is the ©parser value stackª for your
parser. The ©semantic valuesª of the ©tokensª identified
by the parser are stored in the value stack.  The value
stack, like the other ©parser stacksª, is indexed by
©PCBª.©ssxª. When you are executing a reduction
procedure, PCB.vs[PCB.ssx] contains the semantic value
of the first token in the grammar rule you are reducing,
PCB.vs[PCB.ssx+1] contains the second, and so forth. The
return value from your reduction procedure will be
stored in turn in PCB.vs[PCB.ssx].

vs is defined to be of type $_vt, where "$" represents
the name of your parser. AnaGram defines $_vt to
be a union of fields of sizes corresponding to all the
different data types declared in your syntax for the
semantic values of your tokens. In order to avoid
restrictions on the use of C++ classes, the fields are
defined as character arrays. On some processors which
have byte alignment restrictions for multibyte data,
you might encounter a bus error. To correct this
problem, set the ©parser stack alignmentª parameter to
an appropriate data type.
##

Warning

If while analyzing your syntax file, AnaGram finds
something suspicious, it is likely to issue a warning.
The Warnings window will pop up automatically when the
analysis has been completed. If the warning is for a
©syntax errorª in your input file, you will have to fix
it, because AnaGram cannot successfully interpret it.
Otherwise, AnaGram will be able to create a ©parserª for
you, if you wish, no matter how serious the warnings may
be.

You can bring up the Help topic associated with a highlighted warning
by pressing F1 or by clicking with a ©Help Cursorª.

If you have syntax errors, AnaGram will synchronize the
cursor in the ©syntax fileª window with the cursor in the
Warnings window so that whenever the Warnings window is
active, the cursor bar in the syntax file window will
identify the location of the error.

##

What's New

Changes in AnaGram 2.40

Most of the changes in AnaGram 2.40 are under the hood - cleanup of
source files, reorganization of the source tree, revision of build and
test procedures, and so forth, in preparation for the open source
release. All of this will, with luck, be invisible to the end user.

Open Source

AnaGram is now ©open sourceª. AnaGram itself
uses the 4-clause BSD ©licenseª; the ©parsing engineª, and thus the output
files, are licensed with the less restrictive zlib ©licenseª. Source
distributions are available from http://www.parsifalsoft.com.

The manual has been re-typeset using LaTeX instead of WordPerfect.
The typographic consistency and formatting has been considerably
improved; unfortunately, the pagination is now completely different,
so page numbers are not portable to the new version.

All the logic dealing with registration, trial copies, serial numbers,
and so forth has been removed.

Unix Support

The Unix build of the ©command line versionª of AnaGram (agcl) is now
supported and available to the public. There is at present no GUI for
the Unix version. The long-term goal is to migrate the AnaGram GUI
away from the closed (and orphaned) IBM Visual Age class library to
something else, probably GTK, so as to support both Windows and Unix.

Improved Functionality

 Examples. The examples have been adjusted to the current dialect of
C++ and are now compilable again. The legacy "classlib" code some
still depend on is being phased out.

Increased Convenience

 File names. File names in the AnaGram distribution and source
tree are no longer limited to 8+3 characters, and quite a few now have
less cryptic names. Additionally, all HTML files are now named ".html",
not ".htm".

 Installed files. The AnaGram.cgb and AnaGram.hlp files found in
older releases of AnaGram no longer exist; their contents are compiled
into the AnaGram executables instead.

Bug Fixes

 Engine compiler error. The ©error_messageª field of the PCB has
been changed to const char * so current C++ compilers will accept the
code generated when ©diagnose errorsª is turned off.

 Multiple output header files. Including more than one AnaGram
output header file at once used to cause some compilers to issue a
warning, because an #ifndef directive was checking the wrong
symbol. This has been corrected.

 Wrappers and error tokens. AnaGram 2.01 generated uncompilable
code if you tried to use the ©wrapperª feature and error token
resynchronization at the same time. This has been corrected.

 More than 256 keywords. Build 8 of AnaGram 2.01 fixed certain
problems with large keyword tables, but in the process introduced
another, which is now fixed.

For changes in the previous versions of AnaGram, see ©What's New in AnaGram 
2.01ª and ©What's New in AnaGram 2.0ª.

##

What's New in AnaGram 2.01

Changes in AnaGram 2.01

Improved Functionality

  Improved support for building ©thread safe parsersª. All
nonconstant parser data previously declared as static variables has been
moved to the ©parser control blockª. When the ©reentrant parserª switch
is set, all references to the parser control block are passed to functions
via calling sequences. The ©extend pcbª switch provides a mechanism to
add user-defined variables to the parser control block.

  Improved support for C++ parsers. The ©wrapperª statement
provides C++ wrapper classes for objects to be stored on the ©parser value stackª.
The ©PCB_TYPEª macro allows you to derive a C++ class from the parser control
block and to access its members from your ©reduction proceduresª.

  Support for the ©ISO Latin 1ª character set. When using
the ©case sensitiveª switch, case conversion is performed for all ISO-Latin-1
characters, not just those in the ASCII range.

  Improved support for error diagnostics. It is now possible for users
to provide their own text for the error messages created by the ©diagnose errorsª
switch. In addition, the ©token namesª table option now includes ascii representation
of individual characters and keywords instead of only named tokens. The ©token names
onlyª switch can be used for compatibility with previous versions of AnaGram

  More precise determination of error context. The tables used by the ©error frameª
option to provide the context of a syntax error have been reworked and now provide
a substantially more precise localization of the error.

Improved error diagnostics in AnaGram

 ©Missing reduction procedureª diagnostic.
In addition to warning that there is a ©parameter assignmentª
without a ©reduction procedureª, this
diagnostic is now provided if the ©default reduction valueª
does not have the same ©data typeª as the ©reduction tokenª.

 ©Command line versionª. Diagnostics have been reformatted so
they can be recognized by the Microsoft Visual C++ IDE.

 Refined ©keyword anomalyª diagnostics. There should
now be fewer false alarms.

Increased Convenience

 ©File Traceª. If your grammar uses ©semantically determined productionsª,
the File Trace feature will now remember the choices you have
made for ©reduction tokenªs, so that you do not have to make
the same choices over and over again as you work with an example.

 File Paths. The file paths in the #line directives created by the ©line numbersª
switch now use forward slashes instead of backslashes.

Changed Defaults

 ©Parser stack alignmentª. Now defaults to long instead of int.
 ©Parser stack sizeª. Now defaults to 128 instead of 32.

Bug Fixes

 Interaction between context tracking and error token. In previous
versions of AnaGram, if the first token in a rule was the ©error tokenª,
the value of ©CONTEXTª was the value that corresponded to the location
of the error. CONTEXT now correctly shows the context at which the
aborted rule began. For instance, in the following example, if a
syntax error is encountered while parsing the expression, the error
rule will skip over remaining characters to the terminating semicolon.
When invoked from handleError(), the CONTEXT macro will return the
context as it was at the beginning of the expression.
        expression statement
          -> expression, ';'
          -> error, ~(eof + ';')?..., ';'        =handleError();

 ©Distinguish lexemesª. Several minor bugs in the implementation of distinguish lexemes have been
corrected.

 Set partition logic. Corrected problems in the interaction between the set ©partitionª logic
and the implementation of the ©disregardª statement.

 Table size. Fixed a data sizing problem which occurred when one particular parse table
had precisely 256 entries.

 Keyword recognition. Fixed a problem that could cause difficulties with ©keywordª
recognition when the ©case sensitiveª switch was turned off.

 Default conflict resolution. With unresolved ©shift-reduce conflictªs, the shift case was
not always being selected. This problem has been corrected.

 Lockup. It was possible to write an erroneous grammar that would cause
AnaGram to lock up. This problem has been corrected.

 Potential bus error. The error diagnostic funtion created by the ©diagnose errorsª
switch, could, under some circumstances, access an uninitialized value
on the ©parser value stackª. This problem has been corrected.

 Internal errors. Fixed a number of minor bugs which could cause ©internal errorªs
while running ©File Traceª.

For changes in the previous version of AnaGram, see ©What's New in AnaGram 2.0ª.
##

What's New in AnaGram 2.0

AnaGram's user interface has been completely revamped to make it more
convenient and easier to use. However, the same tried and true AnaGram
algorithms are still in place to build your parsers. The rules for
syntax files are also unchanged.

The ©File Traceª and ©Grammar Traceª facilities have each had their
windows combined into a single unit, and a ©Rule Stackª synched with
these windows and with your syntax file window has been added. The
Rule Stack is particularly convenient for relating the progress of the
parse to the ©grammar rulesª in your ©syntax fileª.

A ©text entryª field has also been added to the Grammar Trace. This
means you can provide character input to your parser in much the same
way you can with a ©test fileª in File Trace, but with instant control
over the input.

Some further controls have been added to both File and Grammar Traces.
In particular there is a Reset button to reset the trace to its initial
state. This is particularly useful for ©Conflict Traceªs.

AnaGram now has a small ©Control Panelª (default position is at the
upper right of the screen) from which you can conveniently control
operation.  A menu bar provides access to the various commands and
tables. There are toolbar buttons for Analyze Grammar, Build Parser,
File Trace, and so on. The panel also has a data entry field for
entering search keys.

You can set both colors and fonts in AnaGram windows to suit your own
preferences. We suggest you check Help for ©Colorsª or ©Fontsª before
making changes to make sure that all information will still be properly
displayed.

AnaGram's ©Helpª has been updated to provide hypertext-type links. But
you can still keep multiple Help windows on view at once. A popup menu
shows all the links in a window. New topics have been added. Also,
further documentation topics are provided in HTML format in the html
subdirectory.

A ©Help Cursorª on the Control Panel toolbar can be used to get help for
most AnaGram windows, buttons and menu items. F1 can also be used.

On the ©Action Menuª you will find a list of your most recently used
syntax files. Just click on the file of your choice to have AnaGram
analyze it (or build it if ©Autobuildª is on).
##

White Space

In many grammars it is desirable to pass over blanks,
tabs, and similar characters, as well as comments,
collectively termed "white space", as though they were
not there. The "©disregardª" statement in AnaGram may
be optionally used to accomplish this. The "©lexemeª"
statement may be used to exercise fine control over the
scope of the disregard statement.
##

Wrapper

The wrapper ©attribute statementª provides correct handling of C++
objects returned by ©reduction procedureªs.

If you specify a wrapper for a C++ object, then, when a reduction
procedure returns an instance of the object, a copy of the object will
be constructed on the ©parser value stackª and the destructor will be
called when the object is removed from the stack.

Without a wrapper, objects are stored on the value stack simply
by coercing the stack pointer to the appropriate type.
There is no constructor call when the object is stored nor
a destructor call when it is removed from the stack.

Classes which use reference counts or otherwise overload the
assignment operator should always have wrappers in order to
function correctly.

Wrapper statements, like other ©attribute statementsª, must appear in
configuration sections. The syntax is simply
  wrapper { <comma delimited list of data types> }

For example:
  [
    wrapper {CString, CFont}
  ]

You cannot specify a wrapper for the ©default token typeª.

If your parser exits with an error condition, there may be
objects remaining on the stack. The ©DELETE_WRAPPERSª macro
may be used to delete these objects. If you have enabled
©auto resynchª, DELETE_WRAPPERS will be invoked automatically.

The ©AG_PLACEMENT_DELETE_REQUIREDª macro is used to control
definition of a "placement delete" operator in the wrapper
class AnaGram defines.
##

Zero Length

A zero length ©tokenª is a ©reduction tokenª which can
be matched by a void, i.e. by nothing at all. It
represents an optional item, or a sequence of optional
items, in the input. Since the matching process can
involve several levels of reductions, it is most precise
to use the following recursive definition: A zero length
token is one which either has at least one ©null
productionª or has at least one grammar rule defining it
such that all the tokens in the rule are zero length
tokens.

Care should be taken when using ©zero lengthª tokens in
©recursive ruleªs. If all the tokens in the rule other than
the recursive token itself are zero length tokens
the rule will generate an infinite loop in the generated
parser.

The ©Token Tableª identifies zero length tokens because
the use of such tokens sometimes inadvertently causes
©conflictªs.
##

Control Panel

The AnaGram Control Panel appears at the upper right of your monitor
when you start AnaGram. It has a menu bar, command buttons, a button
which enables a ©help cursorª, and a ©status indicatorª. At the lower
left you will see a data entry field for entering ©searchª
keys, with neighboring search forward and search backward buttons.

Notice that the ©Options Menuª has a "Stay On Top" entry which
allows you to specify whether the Control Panel stays on top of
other AnaGram windows.
##

Status Indicator

The status indicator at the right of the AnaGram
Control Panel shows the status of the ©current grammarª:
  Ready
  Loaded
  Error
  Parsed
  Analyzed
  Built

"Ready" appears only when no grammar has been selected.

"Loaded" and "Parsed" are normally transitory.

"Error" means at least one syntax error has been detected
in your grammar and AnaGram cannot continue. Check the
Warnings window to determine the nature of the problem.

"Analyzed" means that a ©grammar analysisª has been
completed, but no ©output filesª have been written.

"Built" means that an analysis has been completed and
output files have been written.
##

Help Cursor

The Help Cursor is accessed via the button with the question mark on
AnaGram's ©Control Panelª. It is convenient for getting help on
©Warningªs, browse tables, menu items and so on.

If you click on the button you enable the Help Cursor, which you can
then drag with the mouse. A further mouse click will provide help
for the item underneath the cursor.

Note further that AnaGram also has F1 help which you may find
simpler and faster than the Help Cursor.
##

Search

AnaGram has a simple search facility to let you search for text strings
in AnaGram windows. A data entry field on the ©Control Panelª is
provided for you to enter text. Left-clicking on the neighboring
buttons lets you search either forward or backward for a line in the
active window which contains at least one instance of the text.

Note that the search begins at the next line after the highlighted line
for forward search; at the line preceding the highlighted line for
backward search.
##

Search Key

To find a text string in an AnaGram window, enter the
string in the Search Key field in the ©Control Panelª
and press Enter.

To find another instance of the string click on the
©Find Nextª button or press F3.

To find a previous instance of the string click on
the ©Find Previousª button or press F4.

In windows that have a cursor bar, a forward search
begins on the line following the cursor and a backward
search begins on the line preceding the cursor.
##

Find Next

The Find Next key, on the ©Control Panelª immediately
to the right of the ©Search Keyª field, locates
the next instance of the search key in the most recently
active AnaGram window. F3 is the keyboard equivalent.
##

Find Previous

The Find Previous key, on the ©Control Panelª immediately
to the right of the ©Find Nextª key, searches
backwards for the search key in the most recently
active AnaGram window. F4 is the keyboard equivalent.
##

Fonts, Set Fonts

The Set Fonts dialog allows you to use the fonts of your choice in
AnaGram windows. You should make sure that the ©marked tokenªs font is
very distinctive so that marked tokens will show up clearly even if
they are only 1 or 2 characters long. Sometimes it is helpful to use an
underlined font for marked tokens.

A Default button at the bottom of the dialog lets you revert to
AnaGram's original fonts if you wish.
##

Colors, Set Colors

The Set Colors dialog allows you change the colors of
AnaGram windows. Notice that in the ©File Traceª the ©test file paneª
requires three different sets of text and background colors. You
should make sure that the backgrounds, at least, can be easily
distinguished from each other so the trace information can be
properly displayed. You also want to take care that an active pane in
a File Trace or Grammar Trace can be distinguished from inactive
panes.

The Default button at the bottom of the dialog lets you revert to
AnaGram's original colors if you wish.

Color changes pertain only to the client areas of AnaGram windows. The
remaining parts of your windows will have the customary colors you have
chosen for your system.
##

Marked Token

Some tables and trace panes display each rule with one token marked to
show how far parsing has progressed in the rule. The marked token is
the next input expected in the input stream. It is shown in a different
font to distinguish it from other tokens in the rule. If no token is
marked, the rule is a ©completed ruleª, i.e. it has been completely
matched and will be reduced by the next input.

You can set the font for marked tokens by choosing Fonts from the
©Options Menuª. You should make sure that the font is very distinctive so
that marked tokens will show up clearly even if they are only 1 or 2
characters long.  Sometimes it is helpful to use an underlined font for
marked tokens.
##

Synch Parse

The Synch Parse button replaces the ©Single Stepª button on the
toolbar of the ©File Trace windowª when, for some reason, the
location of the blinking cursor in the ©test file paneª differs from
the current parse position. This can occur when you single click in
the test file pane or when the parse cannot track the cursor because
of a ©syntax errorª or a ©semantically determined productionª.

Click the synch parse button to resynch the parse with the cursor.
##


Single Step

The Single Step button is one of the control buttons for the ©File
Traceª and ©Grammar Traceª. It advances the parse one ©parser
actionª at a time. In the File Trace, it is replaced with the "©Synch
Parseª" button whenever the blinking cursor loses synch with
the current parse location.

In the Grammar Trace, the Single Step button takes its input from the
Allowable Input pane, the Reduction Choices pane, or the ©text entryª
field, depending on which is active.
##

Proceed

The Proceed button is one of the control buttons for the
©Grammar Traceª. If the ©Reduction Choices paneª or the ©Allowable
Input paneª is active, Proceed parses the highlighted token
until it is shifted in to the ©parser stackª. If the ©text entryª
field is active, Proceed parses all text in the field. If a
©syntax errorª is encountered, the parse stops and all ©reduce
actionªs are undone.

Note that selecting a token in Allowable Input can cause a syntax
error under certain circumstances. This can happen only if the
following conditions are all true:
 the indicated operation is a ©reductionª,
 the reduction token for the rule being reduced has been used in several
different contexts in the grammar
 and the specified token may
follow it in some contexts and not in others.
##

Reduction Choices Pane

The ©File Traceª and ©Grammar Traceª display a Reduction Choices
pane when they need to reduce a ©semantically determined productionª.

The rule to be reduced is highlighted in the ©rule stack paneª.
If the ©syntax fileª window is visible, it shows the rule in
context in your grammar.

The Reduction Choices pane lists all possible ©reduction tokenªs for
the specified rule. The first reduction token that is admissible in
the current context is highlighted and it appears
as the ©lookahead tokenª in the ©parser stack paneª. The text that
comprises the entire rule is highlighted in the ©test file paneª.

Select the desired reduction token before continuing with the parse.

If you select a token and it does not appear as the lookahead token,
it is not syntactically correct in the current context. If you try
to proceed with the parse, you will get a ©selection errorª.
##

Selection Error

The ©Parse Statusª field indicates a "selection error" if you
choose a ©reduction tokenª from the ©Reduction Choices paneª of
a ©File Traceª or ©Grammar Traceª and the selected token is not
syntactically correct in the current context.
##

Parser Stack Pane

The Parser Stack pane, the upper left pane of the ©File Traceª and
©Grammar Traceª windows, displays the ©parser stackª for the current
trace.

Each line corresponds to one level in the parser state stack. It shows
the stack index, the ©parser stateª for that level, and the ©tokenª which
was seen at that state. The last line of the stack, the ©lookahead
lineª, corresponds to the current state of the parser. Since no input
has yet been processed for this state, the token, if any, which
appears at this level is a ©lookahead tokenª.

If you move the cursor in the Parser Stack pane of a File Trace,
the text that makes up the selected token will be
highlighted in the ©Test File paneª. You can back the parse up to
any desired stack level by double clicking at the beginning of the
token text in the Test File pane.

Similarly, if you move the cursor bar in the Parser Stack pane of a
Grammar Trace, the ©Allowable Input paneª will change to display the
allowable tokens in the selected state. The previously
selected token will be highlighted. Then, double click on any token in
the Allowable Input pane to back the parse up and choose a token
a second time.

The ©Rule Stack paneª of the File or Grammar Trace is also synched
to the Parser Stack pane. If the ©syntax fileª window is visible, it
will be synched to show the rule currently selected in the rule
stack pane. Note that rules that have been automatically generated
by the expansion of ©virtual productionsª cannot be synched, so the
top line of the syntax file will be highlighted instead.

In the Grammar Trace, the last line of the Parser Stack may or may not
display a ©lookahead tokenª, depending on the last ©parser actionª
performed. If input was taken from Allowable Input and the last
action was a simple ©reduce actionª, the last input token selected
will be displayed as the lookahead input. But if the last action
performed shifted the token in, the lookahead field will be empty.

If you right-click on a highlighted line in the Parser Stack pane, you will
get a pop-up menu to give you more information. In particular you can
get an ©Auxiliary Traceª starting at the current point in your File or
Grammar Trace, so you can explore various possibilities without losing
your position in the old trace.
##

Exit

Select this entry from the ©Action Menuª to terminate AnaGram.
##

Allowable Input, Allowable Input Pane

The upper right pane of the ©Grammar Traceª window lists the
allowable input tokens for the current state of the ©grammarª.

The tokens in the Allowable Input pane are listed in two groups:
first, the ©terminal tokensª allowable in this state, and
second, the ©nonterminal tokensª. Between these two groups of tokens
is inserted a line which is either an option for a ©default reductionª,
or declares that there is no default action.

Double click, press Enter, or click the ©Proceedª button to
parse the highlighted token. When all parse actions triggered
by the highlighted token have been completed, all panes of the trace
will be redrawn to show the new state of the parser.

Note that selecting a token in Allowable Input can cause a syntax
error under certain circumstances. This can happen only if the
following conditions are all true:
 the indicated operation is a ©reductionª,
 the reduction token for the rule being reduced has been used in several
different contexts in the grammar
 and the specified token may
follow it in some contexts and not in others.

If you wish to see the results of a single parser action, click
on the ©single stepª button. The parser will perform a single
parser action. If the
token you selected was not shifted in, it will now be displayed
as the ©lookahead tokenª on the last line, the ©lookahead lineª in
the ©Parser Stack paneª, and will be preselected in the Allowable
Input pane.

Because AnaGram, by default, uses a number of compound
parser actions, this situation does not arise very often unless you
have set the ©traditional engineª switch or reset the ©default
reductionsª switch. Usually you will want to select the same token to
proceed, but it is not necessary.

The Allowable Input pane also displays
the ©parser actionª associated with a specific token. If it is
not a ©compound actionª, the action and its result are also shown.

The ©parser actionª field for a token may be interpreted as follows: If
this token would cause a shift to a new state, the action field is ">>"
followed by the new state number. If the token would cause a
©reductionª, the action field is "<<" followed by a ©rule numberª to
show the rule reduced.  If the parser action is a compound action, the
action field is blank.  If the token would cause the grammar to be
accepted, the action field is "Accept".


The ©text entryª field at the bottom of the Grammar Trace can be
used as a convenient alternative to the Allowable Input pane. It
accepts characters rather than tokens. Most non-printing characters
such as newline are only available from Allowable Input.
##

Copy

The Copy command on the ©Windows Menuª copies the currently active
table or Help topic to the clipboard.
##

Statistical Summary

While your grammar is being analyzed, a Statistical Summary window
pops up to show you the progress of the analysis. Unless you have
turned off ©Show Statisticsª on the ©Options Menuª, this window will remain
on-screen for your reference. Among other things, it shows you the
number of rules and states in your grammar, and the number of conflicts
and warnings, if any.

Note that if your grammar is small and you have Show Statistics turned
off, the appearance of this window on your monitor may be exceedingly
brief - you may just see a flash.

If the window is turned off or you have closed it, you can get it from
the ©Browse Menuª.
##

Stay On Top

The Stay On Top entry in the ©Options Menuª allows you to specify whether
the ©Control Panelª stays on top of other AnaGram windows.
##

Show Syntax

If this entry in the ©Options Menuª is checked, AnaGram will display the
©syntax fileª when it has analyzed your ©grammarª. If this entry is not checked
or you have closed the syntax file window, you can select the window
from the ©Browse Menuª.
##

Show Statistics

If this entry in the ©Options Menuª is checked, AnaGram will leave the
©Statistical Summaryª on the screen after it has analyzed your ©grammarª. If
this entry is not checked or you have closed the Statistical Summary
window, you can select the window from the ©Browse Menuª.
##

About AnaGram

Select this entry from the ©Help Menuª to find out the version and
serial numbers of your copy of AnaGram, and how to contact Parsifal
Software.
##

Help Topics

Select Help Topics from the ©Help Menuª to get a complete list of AnaGram
Help Topics titles. You can bring up the window for a highlighted topic
by double-clicking with the left mouse button, pressing F1, or using
the ©Help Cursorª.
##

Cascade Windows

Select this entry from the ©Windows Menuª to cascade your open windows
starting at top left of the screen.
##

Close Windows

Select this entry from the ©Windows Menuª to close all open windows
except the ©Control Panelª. You may also close the active window
by pressing the Escape key.
##

Hide Windows

Select this entry from the ©Windows Menuª to hide all open windows
except the ©Control Panelª. Restore them to the screen with ©Restore
Windowsª
##

Restore Windows

Use this command on the ©Windows Menuª to restore to the screen
any windows you have previously hidden with ©Hide Windowsª.
##

Token Input, Preprocessor, Lexical Scanner

AnaGram makes it unnecessary, in most cases, to have a separate
preprocessor to provide the ©tokensª which are fed to your parser.

However in some cases you may want to use a preprocessor, or lexical
scanner, to provide input to your parser. The preprocessor may
or may not be written in AnaGram. If it sends the parser token
numbers, as opposed to character codes, this is referred to as token
input, as opposed to character input. Please refer to the AnaGram
User's Guide for information on identifying the tokens to the parser
and providing their semantic values, if any.

Since a ©File Traceª is based on character codes, it will be greyed out
on the ©Action Menuª if you have token input. For a ©Grammar Traceª,
entering characters in the ©text entryª field is not appropriate and
will simply cause a syntax error.
##

Lookahead Line

The last line of the ©Parser Stack paneª, the "lookahead" line,
will sometimes show a ©lookahead
tokenª, and sometimes not. In a ©File Traceª, you will always see a
lookahead token because it is available from the ©test fileª.

In a ©Grammar Traceª you will usually see a lookahead token only when
you have used the ©Single Stepª button or if there is available
input in the ©text entryª field. In the latter case the token
corresponding to the first character of the input will appear on the
lookahead line.

If you click Single Step after selecting a token from ©Allowable
Inputª and it causes only a simple ©reduce actionª (as opposed to a
shift or a compound action), then, upon completion of the reduction,
the token you selected will appear on the lookahead line and also
will be preselected in Allowable Input.

Usually you would select
this token for the next parse step.  However, if there are other
possible inputs in this state, the parse theoretically could have
arrived at this state by a different sequence of input tokens. Thus,
if you are more interested in the behavior of the parser at this
state than in the response of the parser to a particular sequence of
inputs, it is perfectly valid to select a different input token, and
AnaGram will let you do it.

Note that if you have enabled the ©traditional engineª switch or
disabled the ©default reductionsª switch, the
probability of finding a token which does a simple reduction is
noticeably higher than otherwise.
##

Action Menu

The Action menu begins with the ©Analyze Grammarª and ©Build Parserª
commands. If a grammar has already been analyzed, but not yet built,
there will also be an extra Build command bearing the name of your
syntax file.

There are also ©Reanalyzeª and ©Rebuildª commands which are
initially greyed out. They become available if you change the
current syntax file.

The next section has ©File Traceª and ©Grammar Traceª
commands. If you have enabled the ©Error Traceª
©configuration switchª, this section also shows an
Error Trace command.

The menu ends with an ©Exitª command
and a list of recently used syntax files, if any. Just
click on a syntax file name to have AnaGram analyze it, or
build it if the ©Autobuildª option is on.
##

Browse Menu

Initially, the Browse Menu shows only a single entry:
©Configuration Parametersª which lets you see the
current state of configuration parameters before any
may have been set by your syntax file. Once you have
analyzed a grammar, this menu fills up with many tables
containing information about your grammar. You can also
bring up a window showing your ©syntax fileª from this menu.
If your grammar has generated ©syntax errorªs or warnings, or
contains conflicts, there will be ©Warningªs or ©Conflictªs
entries.
##

Options Menu

From this menu you can select a ©Fontsª or ©Colorsª dialog so you can
set AnaGram's fonts and colors to suit your own tastes. You can set
©Autobuildª if you want AnaGram to automatically build your ©grammarª
when you select a ©syntax fileª from the ©Action Menuª.  You can also
choose whether or not to automatically show the ©Statistical Summaryª
window or your syntax file window when you open a grammar, or make
the ©Control Panelª stay on top of other AnaGram windows.
##

Windows Menu

The Windows menu lets you cascade, close, or hide all AnaGram
windows except the ©Control Panelª, or restore them if they
have been hidden. It also has a list of open windows (even
if hidden) so you can select the one you want. The Copy command will
copy most windows to the clipboard.
##

Help Menu

The Help Menu has the following entries:

©Getting Startedª provides a brief description of AnaGram and
introductory suggestions.

©Help Topicsª brings up a list of all help topics.

©Using Helpª tells you how to use AnaGram's help facilities.

©What's Newª has information on new features of this version of AnaGram.

©About AnaGramª tells you what version of AnaGram you are using, and also
provides contact information for Parsifal Software.
##

Autobuild

When Autobuild (©Options Menuª) is checked, selecting a file
from the list of most recently used files on the ©Action Menuª
invokes the ©Build Parserª command. Otherwise, the ©Analyze
Grammarª command is invoked.
##

Reanalyze, Rebuild

Reanalyze and Rebuild commands on the ©Action Menuª are
initially greyed out.

Reanalyze becomes available if
you have a syntax file currently analyzed or built
in AnaGram and change it while AnaGram is still running.

Rebuild becomes available if
you have a syntax file currently built
and change it while AnaGram is still running.
##

Percent Sign

The percent sign ( % ) is used to mark certain tokens in your grammar
which AnaGram must redefine in order to implement the ©disregardª
statement. If you have used this statement in your grammar, You will
probably notice the percent sign appearing in some windows and traces.

The percent sign indicates the original token, without the optional
white space attached. Early versions of AnaGram used the degree sign
instead, but this character is not generally available in Windows.
##

Program Development

The first step in writing a program is to write a ©grammarª in
AnaGram notation which describes the input the program expects.

The file containing the grammar, called the ©syntax fileª, should
have the extension ".syn". You could also make up a few sample input
files at this time, but it is not necessary to write ©reduction
procedureªs at this stage.

Run AnaGram and use the ©Analyze Grammarª command to create parse
tables. If there are ©syntax errorsª in the grammar at this point,
you will have to correct them before proceeding, but you do not
necessarily have to eliminate ©conflictsª, if there are any, at this
time. There are, however, many aids available to help you with
conflicts. These aids are described in the AnaGram User's Guide, and
somewhat more briefly in the Online Help topics.

Once syntax errors are corrected, you can try out your grammar on the
sample input files using the ©File Traceª facility.
With File Trace, you can see interactively just how your grammar
operates on your test files. You can also use ©Grammar Traceª to
answer "what if" questions concerning input to the grammar. The
Grammar Trace does not use a test file, but rather allows you to make
input choices interactively.

At any time, you can write ©reduction procedureªs to process your
input data as its components are identified in the input stream. Each
procedure is associated with a ©grammar ruleª. The reduction
procedures will be incorporated into your parser when you create it
with the ©Build Parserª command.

By default, unless you specify an input procedure, ©parser inputª
will be read from stdin, using the default ©GET_INPUTª macro.
You will probably wish to redefine GET_INPUT, or configure your
parser to use ©pointer inputª or ©event drivenª input.
##

License, Copyright, Copying, Open Source, Warranty, No Warranty

AnaGram, A System for Syntax Directed Programming

Copyright 1993-2002 Parsifal Software

Copyright 2006, 2007 David A. Holland

All Rights Reserved.

AnaGram itself is released to the public under the traditional 4-clause BSD
license:

   Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions are
   met:

   1. Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

   2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

   3. All advertising materials mentioning features or use of this software
   must display the following acknowledgement:
      This product includes software developed by Parsifal Software,
      Jerome T. Holland, and their contributors.

   4. Neither the name of Parsifal Software nor the name of Jerome T.
   Holland nor the names of their contributors may be used to endorse or
   promote products derived from this software without specific prior written
   permission.

   THIS SOFTWARE IS PROVIDED BY PARSIFAL SOFTWARE,
   JEROME T. HOLLAND, AND CONTRIBUTORS ``AS IS'' AND ANY
   EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
   AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
   IN NO EVENT SHALL PARSIFAL SOFTWARE, JEROME T. 
   HOLLAND, OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
   INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
   CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
   USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
   HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
   WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
   OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   POSSIBILITY OF SUCH DAMAGE.

The AnaGram ©parsing engineª, that is, the code that is emitted by
AnaGram and incorporated into programs developed using AnaGram, uses
this less restrictive zlib-style license:

   This software is provided 'as-is', without any express or implied warranty.
   In no event will the authors be held liable for any damages arising from
   the use of this software.

   Permission is granted to anyone to use this software for any purpose,
   including commercial applications, and to alter it and redistribute it
   freely, subject to the following restrictions:

   1. The origin of this software must not be misrepresented; you must not
   claim that you wrote the original software. If you use this software in a
   product, an acknowledgment in the product documentation would be
   appreciated but is not required.

   2. Altered source versions must be plainly marked as such, and must not
   be misrepresented as being the original software.

   3. This notice may not be removed or altered from any source distribution.

##