\chapter{Running AnaGram}


\section{Overview}

AnaGram's main window is a small
\index{\agwindow{Control Panel}}\agwindow{Control Panel}
with menus, a toolbar, a status indicator, and a simple search
facility.  Its default position is at the upper right of your screen.
AnaGram's two basic commands,
\index{Analyze Grammar}\agmenu{Analyze Grammar}
and
\index{Build Parser}\agmenu{Build Parser},
are available from the \agmenu{Action} menu of the \agwindow{Control
Panel}.

% XXX remove the stuff about time; nowadays it's all instantaneous
The commands take as input a syntax file containing the specifications
of your grammar.  \agmenu{Build Parser} creates a parser file, in C or
C++, and a header file.  \agmenu{Analyze Grammar} does not write any
\index{Output files}\index{File}output files, and therefore takes a
little less time than \agmenu{Build Parser} to run.  Normally you
would use \agmenu{Build Parser} when you are ready to start compiling
and testing your parser.  You would use \agmenu{Analyze Grammar} while
you are working on the grammar itself.

% XXX s/build/create/
Both of these commands cause AnaGram to build a number of tables
describing your grammar.  These tables, accessible from the
\agmenu{Browse} menu, will interest you mainly when you are debugging
your grammar.  These tables and their use are described in Chapters 6
and 7.  An alphabetic listing of the tables with summaries of their
content may be found in Appendix C.

The primary purpose of AnaGram's user interface is to enable you to
inspect the grammar tables, and to use the \agwindow{Grammar Trace}
and \agwindow{File Trace} facilities to study, at any level of detail
you wish, how your parser analyzes any sequence of input characters or
tokens.

AnaGram is documented with an extensive, hypertext \agwindow{Online
Help} system in addition to this User's Guide.  Supplementary
documentation in browser-readable format can be found in the
\agfile{html} directory distributed with AnaGram.


\section{Executables}
\index{Executables}

% XXX s/make files/makefiles/
% (better do a global search and replace)

\index{Make files}\index{\agfile{ag.exe}}\index{\agfile{agcl.exe}}
AnaGram has two executables: one interactive, \agfile{ag.exe}, and
one, \agfile{agcl.exe}, for use in make files.

\index{Command line}
If you provide \agfile{ag.exe} with a syntax file name on the command
line, AnaGram will load the file and do either \agmenu{Analyze
Grammar} or \agmenu{Build Parser}, depending on the setting of the
\index{\agoption{Autobuild}}\agoption{Autobuild} option.

The command line version, \agfile{agcl.exe}, builds a parser for the
syntax file specified on the command line.  Warning and error messages
from \agfile{agcl.exe} are directed to \agcode{stdout}.

\index{File extension}\index{syn}\index{.syn}
The default extension for syntax files appearing on the command line
is \agfile{.syn}.


\section{Input Files}
\index{Input Files}\index{Files}\index{File}

Input files for AnaGram are called syntax files and usually have the
\index{File extension}\index{syn}\index{.syn}
extension \agfile{.syn}.
\index{Syntax file}\index{File}
Syntax files are written in a variant
of
\index{Backus-Naur form}Backus-Naur form,
and may include reduction procedures written in C or C++ as well as
other embedded C or C++ code.  The general theory of syntax files is
given in Chapter 4.  The rules for writing syntax files are given in
Chapter 8.

When you run AnaGram and analyze a grammar, the syntax file you have
chosen will appear in the \agmenu{Browse} menu under the heading
\agmenu{Syntax File} followed by the file name.  It will also appear
in a window on your screen unless you have turned the
\index{Show Syntax}\agoption{Show Syntax} option off.


\section{Output Files}
\index{Output Files}\index{Files}\index{File}

% XXX s/parser file/source file/
When you choose the \agmenu{Build Parser} command, AnaGram builds two
output files: a header file and a parser file.  Normally these files
have the same name as your syntax file and the \index{File
extension}extensions \agfile{.h} and \agfile{.c}, respectively.  You
may change the names or the extensions by use of the
\index{File name}\index{Header file name}\agparam{header file name}
and
\index{File name}\index{Parser file name}\agparam{parser file name}
\index{Configuration parameters}configuration parameters
(see Appendix A).  If you are using C++, you will probably wish to set
% XXX s/in your configuration file/accordingly/
the \agparam{parser file name} parameter in your configuration file.
Include the following line in your configuration file or section:

% This is really part of the preceding paragraph and latex won't
% space it accordingly even if you don't have any line breaks in
% between. This looks unsightly at first glance but it makes things
% clearer when actually reading.
\vskip -1.25ex

% This was 1 inch, but wp2latex must have made that up out of thin air
\begin{indentingcode}{0.4in}
parser file name = "\#.cpp"
\end{indentingcode}

The \index{Header file}\index{File}header file contains typedef
statements and macro definitions which are needed by the parser and
which you may need to use in other modules to interface your parser to
the rest of your program.

The \index{Parser file}\index{File}parser file contains the reduction
procedures and embedded C or C++ code that AnaGram finds in your
syntax file, a number of tables which summarize your grammar, and a
parsing engine customized to your requirements.  The
\index{Parsing engine}parsing engine
is written in C.  Care has been taken to assure that it can be
compiled by almost any C/C++ compiler.  The content of the header file
and the parser file is described in Chapter 9.


\section{AnaGram's Help}
\index{Help}\index{Online help}

There are three main ways to access AnaGram's \agwindow{Online Help}:

\begin{itemize}
\item Press F1 for context-sensitive help from most windows and menu
items.
\item Similarly, use the \agwindow{Help Cursor} on the
\agwindow{Control Panel} toolbar (described below) from most windows
and menu items.
\item From the \agmenu{Help} menu on the \agwindow{Control Panel}, you
can bring up a complete list of help topics and choose a topic.
\end{itemize}

You can also get fly-over help for the toolbar buttons on the
\agwindow{Control Panel}.  \agwindow{File} and \agwindow{Grammar
Traces} have a \agmenu{Help} button.

AnaGram's \agwindow{Help} windows 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 \agwindow{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.

% XXX s/that,/that/
Note that, for the \agwindow{Warnings}, \agwindow{Configuration
Parameters} and \agwindow{Help Topics} windows, F1 will give you help
for the item on the highlighted line, whereas the \agwindow{Help
Cursor} allows you to select any line by clicking on it.

AnaGram also has browser-readable documentation of examples, a
glossary, brief descriptions of the \agwindow{File} and
\agwindow{Grammar Traces}, and some further topics in the
\agfile{html} directory distributed with AnaGram.


\section{Control Panel Components}
\index{Control Panel}

\index{Action Menu}\index{Menu}\subsection{Action Menu}
In addition to the basic \agmenu{Analyze Grammar} and \agmenu{Build
Parser} commands, the \agmenu{Action} menu provides some variations on
these commands for your convenience:

\begin{itemize}

\item If a grammar has already been analyzed, but not yet built, there
will also be an extra \agmenu{Build} command with the name of your
syntax file.

\item The \agmenu{Reanalyze} and \agmenu{Rebuild} commands are
initially greyed out.  They become available if the current syntax
file is changed externally by another program.

\item At the bottom of the menu is a list of up to six recently used
syntax files. Clicking on one of these gives the same effect as
\agmenu{Analyze Grammar}, or if the
\index{\agoption{Autobuild}}\agoption{Autobuild} option
is on, the same effect as \agmenu{Build Parser}.

\end{itemize}

Before executing an \agmenu{Analyze Grammar} or \agmenu{Build Parser}
command, AnaGram closes all windows related to the current syntax
file, if any, and resets
\index{Configuration parameters}configuration parameters to their initial
values, as determined by the built in defaults and the configuration
files read at program initialization.

The \agmenu{Action} menu also lets you select a \agmenu{File Trace} or
\agmenu{Grammar Trace}, and if the
\index{error trace}\agparam{error trace}
\index{Configuration parameters}configuration switch is
enabled, an \agmenu{Error Trace}.  The traces are covered in Chapter
5.


\subsection{Browse Menu}
\index{Menu}\index{Browse Menu}

Most of the \agmenu{Browse} menu entries are tables describing your
grammar which become available as soon as you analyze it.  The tables
are described in Chapters 6 and 7.  The tables themselves often have
associated tables available via an
\index{Auxiliary Windows}\agmenu{Auxiliary Windows}
menu which pops up when you right-click on a highlighted
line.

A window showing your syntax file is also available from this window.
Do not overlook the 
% noindex (XXX?)
\agmenu{Configuration Parameters}
entry.  AnaGram has a great many parameters available so you can make
AnaGram behave in a variety of ways and produce parsers with the
features you want.  Configuration parameters are documented in
Appendix A.


\subsection{Options Menu}
\index{Options Menu}\index{Menu}

Items you set from the \agmenu{Options} menu will be saved in the
Windows Registry so they can be restored every time you start AnaGram.

\paragraph{Fonts and Colors.}
\index{Fonts}\index{Colors}
You can set AnaGram's fonts and colors to suit your own tastes.  Make
sure that the \agmenu{Marked Tokens} font is very distinctive so these
tokens show up clearly even if they are only one or two characters
long.  Try an underlined font for them if you like.  Notice also that
the \agwindow{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 \agwindow{File} or \agwindow{Grammar Trace}
can be distinguished from inactive panes.

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.

\paragraph{Autobuild.}
\index{Autobuild}
When \agoption{Autobuild} is checked, selecting a file from the list
of most recently used files on the \agmenu{Action} menu invokes the
\agmenu{Build Parser} command.  Otherwise, the \agmenu{Analyze
Grammar} command is invoked.

\index{Show Statistics}\index{Statistics}
\paragraph{Show Statistics.}
If this entry is checked, AnaGram will leave the \agwindow{Statistical
Summary} window on the screen after it has analyzed your grammar.  If
the entry is not checked or you have closed the window, you can select
it from the \agmenu{Browse} menu.

\paragraph{Show Syntax.}
\index{Show Syntax}\index{Syntax}
If this entry 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
\agmenu{Browse} menu.

\paragraph{Stay On Top.}
\index{Stay On Top}
This entry allows you to specify whether the \agwindow{Control Panel}
stays on top of other AnaGram windows.


\subsection{Windows Menu}
\index{Windows Menu}\index{Menu}

In addition to the list of open (including hidden) windows, this menu
has the customary \agmenu{Cascade}, \agmenu{Close}, \agmenu{Hide} and
\agmenu{Restore Windows} commands.  A \agmenu{Copy} feature lets you
copy the currently active table or \agwindow{Help} topic to the
\index{Copy}\index{Clipboard}clipboard.


\subsection{Help Menu}
\index{Help Menu}\index{Menu}

The \agmenu{Help} menu has \agmenu{Getting Started}, \agmenu{Using
Help}, and \agmenu{What's New} entries, all of which you will probably
want to take a look at when you begin using AnaGram.  In the long
term, you will probably find
\index{Help}\index{Help Topics}\agmenu{Help Topics} to be the most
useful item in this menu.  It provides a complete list of
\agwindow{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 \agwindow{Help Cursor}.  You may want to use
the \agmenu{Search} facility in this window.


\subsection{Control Panel Toolbar}
\index{Control Panel}\index{Toolbar}

The first four toolbar buttons provide quick access to the
\agmenu{Analyze Grammar}, \agmenu{Build Parser}, \agmenu{File Trace}
and \agmenu{Grammar Trace} commands.  Two more buttons bring up the
\agwindow{Warnings} and \agwindow{Conflicts} windows if they have any
entries.

The last button, with a question mark, enables a \agwindow{Help
Cursor}, which is convenient for getting help on warnings,
\agmenu{Browse} tables, menu items, and so on.  Once enabled, the
\agwindow{Help Cursor} can be dragged with the mouse.  A further mouse
click will provide help for the item under the cursor.  Note that
AnaGram also has F1 help which you may find simpler and faster than
the \agwindow{Help Cursor}.


\subsection{Status Indicator}
\index{Status Indicator}\index{Indicator}

The status indicator at the right of the \agwindow{Control Panel} has
six possible states: Ready, Loaded, Error, Parsed, Analyzed, and
Built.  ``Ready'' appears only when no grammar has been selected.
``Loaded'' and ``Parsed'' should be transitory.  If ``Error'' appears,
one or more syntax errors have been found in your grammar and AnaGram
cannot continue its analysis.  Check the Warnings window to determine
the nature of the problem.  ``Analyzed'' means that analysis of the
grammar has been completed.  ``Built'' means the analysis has been
completed and also output files have been written.


\subsection{Search}
\index{Search}

\index{Searching for text}AnaGram has a simple search facility to let
you search for text strings in AnaGram windows.  A text entry field on
the \agwindow{Control Panel} is provided for you to enter text.
Left-clicking on the neighboring \agmenu{Find Next} and \agmenu{Find
Previous} 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.
\index{Case sensitivity}Searches are not case sensitive.


\section{Statistical Summary}
\index{Statistical Summary}\index{Summary}

While your grammar is being analyzed, a \agwindow{Statistical Summary}
window pops up to show you the progress of the analysis.  Unless you
have turned off \agmenu{Show Statistics} on the \agmenu{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 \agmenu{Show
Statistics} turned off, the appearance of this window on your monitor
may be exceedingly brief -- you may just see a flash.

If this window is turned off or you have closed it, you can select it
from the \agmenu{Browse} menu.


\section{Auxiliary Windows Popup Menu}
\index{Auxiliary Windows}\index{Popup Menu}\index{Menu}

For many tables you can get more detailed information keyed to the
highlighted item by right clicking the mouse to pop up the
\agmenu{Auxiliary Windows} menu.

Some auxiliary windows are keyed simply to a state number, a token
number, a rule number, a character set number, or a partition set
number identified by the highlighted item.  Others are keyed to some
combination of these numbers.  If the cursor bar is highlighting a
marked rule, the \index{Marked Token}\index{Token}marked token is the
token to which the auxiliary window is keyed.  The key, whether it is
a state number, token number, or other identifier, is always displayed
on the title bar of the window.

Help windows also have popup \agmenu{Auxiliary Windows} menus.  For a
Help window, the popup menu shows all linked topics in the window.


\section{Keyboard Control}
\index{Keyboard}

AnaGram can be controlled entirely from the keyboard.  In the
\agwindow{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:

% XXX this doesn't look so great
\index{Escape}\index{F8}\index{F10}\index{F10}
\begin{tabular}{rll}
$\bullet$&Escape&Closes any AnaGram window except the Control Panel.\\
$\bullet$&F8&Toggles between an active AnaGram window and the Control Panel.\\
$\bullet$&F10&Accesses the Control Panel menu from any AnaGram Window.\\
$\bullet$&Shift F10&Pops up the Auxiliary Windows menu.\\
\end{tabular}