% This file was converted by WP2LaTeX version 2.99
% (and modified a lot afterwards)

%\baselineskip=2.00ex
%
%\headtext{\evenpages}{
%\thepage AnaGram User's Guide
%}
%\foottext{\allpages}{
%\strut\hfill \today{}
%}
%\headtext{\oddpages}{
%Chapter 1\hfill Introduction\thepage 
%}
%\vspace{2.55cm}%
%\begin{flushright}
%
%\section{{    Chapter 1
%Introduction to AnaGram}}
%\end{flushright}

\chapter{Introduction to AnaGram}

AnaGram is a software development tool which brings the power of
syntax directed parsing to the C or C++ programmer.  AnaGram provides
a rule-based, non-procedural system for dealing with input to computer
programs.

AnaGram is a completely new LALR parser generator with a powerful
notation for representing context free grammars.  A flexible,
interactive environment combined with powerful debugging capabilities
and language extensions make it easy to incorporate syntax directed
parsing in your programs.  AnaGram makes it possible for you to reap
the benefits of syntax directed parsing on all of your projects, big
and small.

Syntax directed parsing has long been recognized as the most powerful
technique available for interpreting program input.  Up to now, the
tools available to the software developer to support this technique
have been primitive and hard to use, suitable mainly for compilers and
other large projects.  AnaGram was specifically designed to make
syntax directed parsing accessible to the software developer for
everyday use.

Few portions of a program are more prone to errors than the logic that
deciphers the input to the program.  To interpret its input a program
usually needs many flags and switches, many tests, and a lot of
conditional code.  Of necessity such a program has many paths and many
opportunities to go awry.  Such code is hard to write, hard to
document, hard to debug and hard to maintain.

With AnaGram, you can completely separate the analysis of input from
the processing of data.  Instead of writing a detailed procedure for
interpreting input, you write a {\it description} of that input using
an adaptation of 
% noindex
Backus-Naur Form, or BNF.
AnaGram builds for you,
based on your description, a procedure to interpret your input.  All
those tests, all that conditional code, all those flags and switches
vanish.  In a convenient way you can attach, to the procedure, code to
process the data once it is identified in the input stream.  Your
input processing now takes on the aspect of a rule-based,
non-procedural system.

There are many benefits to this approach.  Your program is easier to
understand.  It is easier to debug.  It is easier to extend and
maintain.  A large project can be more easily divided up among the
members of your team.  The description, or grammar, of your input can
serve as solid and reliable documentation.  You will also find that it
becomes much easier to re-use code on other projects, because the data
processing is cleanly separated from the parsing, or input analysis.

These benefits are now available because AnaGram, in addition to
implementing the basic algorithms of an LALR parser generator,
provides powerful new features that make syntax directed parsing a
practical reality.  Here is a summary of some of the more important
features of AnaGram:

\paragraph{Interactive File Trace.}
An online 
% noindex
\agwindow{File Trace} function lets you run test files through your
grammar interactively.  You can see how your parser will interpret
them.  You can see the contents of the parse stack.  You can see the
grammar rules that are partially matched at any stage in the parse.
You can back up the parse to any point and try again.  You can go
through a test file in single step mode, one character at a time, or
simply parse the whole file to see if it has any errors.  While
interpreting your grammar and parsing your file, AnaGram will count
the number of times each grammar rule is matched and give you a report
so you can assess the thoroughness of your testing.

\paragraph{Grammar Trace.}
The
% noindex
\agwindow{Grammar Trace} is another feature which allows you to
inspect the workings of your parser interactively.  It is particularly
suited for dealing with ``what if?'' questions.  You can work through
a parse at whatever level of detail is necessary to see how an error
arises, to see the nature of an ambiguity, or simply to gain
confidence in the way the parser works.  In case of certain types of
errors, AnaGram will provide pre-built grammar traces to illustrate
the problem.

\paragraph{Other Debugging Tools.}
AnaGram provides a number of debugging tools that can help you get
your program up and running on schedule.  In particular, AnaGram has
powerful tools for identifying ambiguities in your grammar.  AnaGram
also has coverage analysis facilities to help you ascertain the
effectiveness of your test suites.

When AnaGram analyzes a grammar, it creates numerous tables describing
various aspects of the grammar.  To facilitate inspection of these
tables, AnaGram has an interactive interface to enable you to find
quickly any problems in your grammar.  An extensive, on-line help
system provides quick online answers to the questions you have about
AnaGram.

\paragraph{No Lexical Scanner Required.}
\index{Lexical scanner}
When you use AnaGram, you seldom have to use a ``lexical scanner'', or
input processor, written in still another programming language, to
``tokenize'' character-based input for your parser.  Instead, you can
specify {\it all} the details of the input stream directly in your
grammar in a natural way.  If those details need to be changed, you
can make all the changes in one place and rebuild your parser without
having to deal with a cumbersome lexical scanner interface.  AnaGram
accomplishes this by providing a notation that allows you to specify
keywords and character sets simply and intuitively.  AnaGram also
provides options for selectively ignoring white space or other
uninteresting characters in your input.

On the other hand, if you already have a lexical scanner, or some
other data source, you can interface it cleanly and simply to a parser
AnaGram generates.  If the nature of your problem requires a lexical
scanner, or multi-stage parsing, you can use AnaGram for each level of
parsing.

\paragraph{Flexible Interfacing.}
AnaGram provides numerous ways for you to interface your parser to the
rest of your program.  Since you can even configure a parser to work
in an event driven mode, you can use AnaGram very effectively to deal
with the new programming styles required by modern window based
operating systems.

AnaGram provides new notation for linking data to your processing
routines.  Symbolic hooks tie syntactic constructs directly to your C
or C++ code.  The processing routines are easier to write and to
modify.  You can also modify your grammar without having to alter your
data processing routines.

\paragraph{Virtual Productions.}
AnaGram provides a powerful, intuitive shorthand notation to help you
to describe many commonly occurring syntactic forms, such as optional
elements, lists, and simple sets of options.

\paragraph{Semantic Control over Syntactic Analysis.}
Extensions to the basic algorithms for developing LALR parsers allow
you to exert semantic control over syntactic processing by using a new
feature called ``semantically determined productions''.

\paragraph{Precise Control over White Space.}
Convenient attribute statements allow you to skip white space and
comments where they are meaningless, but recognize them where it
matters.

\paragraph{Easy Configuration.}
An extensive set of configuration switches and parameters allow you to
configure both AnaGram and the parsers you build to your precise
requirements.  Wherever AnaGram provides options, it also provides
sensible defaults, so that you can ignore most switches and parameters
until you need the capability they control.