Mercurial > ~dholland > hg > ag > index.cgi
view doc/manual/winsum.tex @ 2:4b08ee1ecb99
Adjust install notes to clarify that Wine applies only to the Windows build.
(Thanks to Perry Metzger for test-driving.)
author | David A. Holland |
---|---|
date | Sun, 26 Apr 2009 17:58:26 -0400 |
parents | 13d2b8934445 |
children |
line wrap: on
line source
\chapter{Alphabetic Listing of Windows} \index{Windows} The following paragraphs summarize the windows AnaGram provides. More detailed descriptions may be found in Chapters 5, 6 and 7. In addition to these windows AnaGram always provides a window to allow you to inspect your syntax file. It is always listed in the \agmenu{Browse} menu. \index{Trace}\index{Auxiliary Trace}\index{Window} \paragraph{Auxiliary Trace.} \agwindow{Auxiliary Trace} windows may be accessed through the \agmenu{Auxiliary Windows} popup menu for most windows which display parser state information. The \agwindow{Auxiliary Trace} is a prebuilt \agwindow{Grammar Trace} showing one of perhaps many ways to get to the state identified by the cursor bar in the active window. When obtained from the \agwindow{Parser Stack} pane of the \agwindow{File Trace} or \agwindow{Grammar Trace}, the \agwindow{Auxiliary Trace} is simply a copy of the current status of the trace so you can explore alternatives while still retaining the status of the original trace for reference. \index{Window}\index{Character Map} \paragraph{Character Map.} The \agwindow{Character Map} table shows you the mapping of input characters to token numbers. The \agcode{ag{\us}tcv} table in your parser is based on the information in this table. \index{Character Sets}\index{Window} \paragraph{Character Sets.} This table lists all of the distinct character sets which you defined, implicitly or explicitly, in your grammar. Each line in the table describes one such set. \index{Window}\index{Configuration Parameters} \paragraph{Configuration Parameters.} The \agwindow{Configuration Parameters} window lists the configuration parameters 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. This window does not include the color settings for the screen, which are controlled separately by the \agwindow{Set Colors} window. % XXX should expand that to say it doesn't include the user interface % preferences, because it's not just colors but fonts and other things. \index{Trace}\index{Window}\index{Conflict Trace} \paragraph{Conflict Trace.} You may select a \agwindow{Conflict Trace} window from the \agmenu{Auxiliary Windows} menu of either a \agwindow{Conflicts} or \agwindow{Resolved Conflicts} window. The \agwindow{Conflict Trace} is a ready-made \agwindow{Grammar Trace} which shows you one of perhaps many ways to get to the state which has the conflict you selected. The use of this window is explained more fully in Chapter 7. \index{Conflicts}\index{Window} \paragraph{Conflicts.} The \agwindow{Conflicts} window lists the conflicts which AnaGram found in your grammar. The table identifies the parser states in which it found conflicts, the reducing tokens for which it had more than one option, and the marked rules which characterize each such option. If AnaGram was able to resolve a conflict by using \index{Precedence declarations}\agparam{precedence} or \index{Sticky declaration}\agparam{sticky} declarations, the conflict will be listed in the \index{Resolved Conflicts}\index{Window}\agwindow{Resolved Conflicts} window instead. % XXX that should be ``Conflicts window'', not ``menu'', right? The \agmenu{Auxiliary Windows} menu for the Conflicts menu includes a number of options specially designed to help in identifying the source of conflicts. These are the \agwindow{Conflict Trace}, the \agwindow{Reduction Trace}, the \agwindow{Expansion Chain}, the \agwindow{Rule Derivation} and the \agwindow{Token Derivation} windows. The use of these windows is explained more fully in Chapter 7. \paragraph{Control Panel.} The \agwindow{Control Panel} is the main AnaGram window. It contains pull down menus to provide access to AnaGram functionality. In addition there is a panel of buttons to invoke the most frequently used AnaGram functions. A text box can be used to enter text to search for. Next to the text box are buttons that implement forward and reverse searching. Searching is always in the most recently active AnaGram window. \index{Trace}\index{Window}\index{Error Trace} \paragraph{Error Trace.} If you (1) turn on the \index{Error trace}\index{Configuration switches}\agparam{error trace} configuration switch for your grammar, (2) build a parser from your grammar, (3) run the parser and encounter a syntax error, your parser will checkpoint the parser stack to a file. If you then run AnaGram again and analyze the grammar, AnaGram will read the checkpoint file and prepare a pre-built \agwindow{Grammar Trace} (see below) which shows how your parser got to the state where it encountered the error. % XXX get rid of ``(see below)'', or maybe change it to ``window'' \index{Expansion Chain}\index{Window} \paragraph{Expansion Chain.} The \agwindow{Expansion Chain} window is available in the \agmenu{Auxiliary Windows} menu from any window that contains expansion rules. Its purpose is to show how a particular expansion rule in a particular state derives from a characteristic rule for that state. The first rule in the window is a characteristic rule for the given state. Each subsequent rule is produced by the marked token in the preceding rule. The last rule is the rule selected by the cursor bar in the parent window. \index{Expansion Rules}\index{Window} \paragraph{Expansion Rules.} The \agwindow{Expansion Rules} window is available in the \agmenu{Auxiliary Windows} menu from any window that identifies tokens. It displays a complete left expansion of the selected token if the token is nonterminal. That is, it is a list of rules that begins with all the rules produced by the token followed by all the rules produced by the first token of any rule in the list. % XXX ...clear as mud. \index{Trace}\index{Window}\index{File Trace} \paragraph{File Trace.} Select the \agwindow{File Trace} window from the \agmenu{Action} menu. The \agwindow{File Trace} window lets you see precisely how your grammar parses a test file. You can see the contents of the parse stack at any point in the parse. You can watch the parse progress at any level of detail you choose. If you wish, you may back up and try again. When AnaGram runs the \agwindow{File Trace} it also builds a \index{Trace Coverage}\index{Coverage}\agwindow{Trace Coverage} table. Note that AnaGram normally uses a number of short-cut parsing actions. To make the parse look like a textbook parse, set the \index{Traditional engine}\index{Configuration switches} \agparam{traditional engine} configuration parameter in your syntax file. \index{Trace}\index{Window}\index{Grammar Trace} \paragraph{Grammar Trace.} The \agwindow{Grammar Trace} facility of AnaGram allows you to examine the workings of your parser in detail. Using the various options associated with this window you can set up a representation of the parser state stack and parser state as they might appear in the course of execution of your parser. You can then examine the possible inputs and the changes to the state and the state stack caused by any input you choose. You can select input options interactively and see how the parser stack changes. You can back up and try other options. You can also enter text directly in the text entry field. By selecting an \agwindow{Auxiliary Trace} from the popup menu in the \agwindow{Parser Stack} pane, you can compare the results of different sequences of input starting at the same point. You may bypass AnaGram's parser optimization by setting the \index{Traditional engine}\index{Configuration switches} \agparam{traditional engine} configuration switch in your syntax file. When AnaGram runs the \agwindow{Grammar Trace} it also builds a \agwindow{Trace Coverage} table or updates the existing one if one already exists. The use of the \agwindow{Grammar Trace} is described in detail in Chapter 5. \index{Help}\index{Help Topics}\index{Window} \paragraph{Help Topics.} The \agwindow{Help Topics} window is an alphabetical list of all the help topics in AnaGram's help file. Some help topics can be accessed by more than one key word, so there are actually a few more entries in this table than there are help topics. There is an entry for the \agwindow{Help Topics} window in the \agmenu{Help} menu. \index{Keyword Anomalies}\index{Window} \paragraph{Keyword Anomalies.} This window is available only if your grammar has keyword anomalies. Each entry in the \agwindow{Keyword Anomalies} window consists of two lines. The first line identifies the parser state in which the anomaly occurs and the offending keyword. The second line identifies the grammar rule which the keyword may erroneously reduce. \index{Trace}\index{Window}\index{Keyword Anomaly Trace} \paragraph{Keyword Anomaly Trace.} The \agwindow{Keyword Anomaly Trace} window is a prebuilt \agwindow{Grammar Trace} accessible through the \agmenu{Auxiliary Windows} menu from the \index{Keyword Anomalies}\index{Window}\agwindow{Keyword Anomalies} window. This trace shows one of perhaps many ways to get to the state which has the keyword anomaly selected in the \agwindow{Keyword Anomalies} window. \index{Keywords} \index{Window} \paragraph{Keywords.} A \agwindow{Keywords} window is accessible from the \agmenu{Auxiliary Windows} popup menu of any window that identifies parser states. It displays all the keywords the parser will recognize in that state, regardless of whether they are used as shift or as reducing tokens. \index{Partition Sets}\index{Window} \paragraph{Partition Sets.} In the \agmenu{Browse} menu, \agwindow{Partition Sets} lists all the partition sets that cover the character universe. In an \agmenu{Auxiliary Windows} menu, \agwindow{Partition Sets} shows the partition sets that cover the character set identified in the parent window. \index{Window}\index{Previous States} \paragraph{Previous States.} A \agwindow{Previous States} window can be accessed via the \agmenu{Auxiliary Windows} menu from any window which identifies parser states. It shows the defining rules for all the states which jump to the specified state. \index{Window}\index{Productions} \paragraph{Productions.} The \agwindow{Productions} window can be accessed using the \agmenu{Auxiliary Windows} menu from any window that identifies tokens. If the selected token is a nonterminal, the \agwindow{Productions} window will display all the grammar rules it produces. \index{Reduction Procedures}\index{Window} \paragraph{Reduction Procedures.} The \agwindow{Reduction Procedures} window lists all of the reduction procedures you have defined in your grammar. Each line of the table gives the C/C++ function prototype. When this window is active, the syntax file window is synchronized with the cursor to show you the text of the reduction procedure. \index{Window}\index{Reduction States} \paragraph{Reduction States.} A \agwindow{Reduction States} window can be accessed via the \agmenu{Auxiliary Windows} popup menu from most windows which display marked rules with a specified state. In this case, if the highlighted rule is complete, that is, there is at is no marked token, the \agwindow{Reduction States} window will show you all the possible states the parser could go to on reducing the rule. % XXX ``is at is no''? % XXX s/on reducing/upon reducing/ \index{Reduction Trace}\index{Trace}\index{Window} \paragraph{Reduction Trace.} A \agwindow{Reduction Trace} window can be requested using the \agmenu{Auxiliary Windows} popup menu from a \agwindow{Conflicts} window or a \agwindow{Resolved Conflicts} window. The \agwindow{Reduction Trace} is coordinated with the \agwindow{Conflict Trace} window, so that the \agwindow{Reduction Trace} shows the result of reducing the selected rule in the \agwindow{Conflict Trace} window. \index{Resolved Conflicts}\index{Window} \paragraph{Resolved Conflicts.} AnaGram creates the \agwindow{Resolved Conflicts} window only when the grammar it is analyzing has conflicts and when some of those conflicts have been resolved by precedence rules or by use of the \agparam{sticky} directive. In this case, it will list, in the \agwindow{Resolved Conflicts} window, the conflicts that were resolved and the way in which they were resolved. Rules which your parser will observe are marked with asterisks. Those which your parser will ignore will not be so marked. Any unresolved conflicts will be listed in the \agwindow{Conflicts} window. \index{Rule Context}\index{Window} \paragraph{Rule Context.} A \agwindow{Rule Context} window can be requested using the \agmenu{Auxiliary Windows} menu from any window that identifies grammar rules. It shows the usage of all tokens that produce the selected rule. \index{Rule Coverage}\index{Window}\index{Coverage} \paragraph{Rule Coverage.} If you have enabled the \index{Rule coverage}\index{Configuration switches}\agparam{rule coverage} configuration switch, your parser will have the capability of counting the number of times each rule in the grammar is reduced during execution of your parser. The \agwindow{Rule Coverage} option on the \agmenu{Browse} menu will be enabled so you can select a rule count file. % XXX s/execution of your parser/execution/ % XXX s/have the capability of counting/will be able to count/ % XXX s/menu, from the/menu of the/ ? \index{Rule Derivation}\index{Window} \paragraph{Rule Derivation.} You may select a \agwindow{Rule Derivation} from the \agmenu{Auxiliary Windows} menu, from the \agwindow{Conflicts} window, the \agwindow{Resolved Conflicts} window, or the \agwindow{Keyword Anomalies} window. The purpose of this window is to show how a particular conflict or ambiguity arises in your grammar. AnaGram develops this window in conjunction with the \agwindow{Token Derivation} window which you may also select. Position the cursor bar on a \index{Completed rule}\index{Rule}\agterm{completed rule}, that is, one with no marked token. If you don't, AnaGram will scan down the table for the next completed rule. The \agwindow{Rule Derivation} and the \agwindow{Token Derivation} show you two sequences of productions, both deriving from one original rule, which demonstrate how the conflict arises. One sequence of productions, the \agwindow{Rule Derivation}, shows how the completed rule derives from the original rule. The other sequence of productions, the \agwindow{Token Derivation}, shows how the reducing token derives from the original rule. These derivations are discussed in greater detail in Chapter 7. \index{Set Elements}\index{Window} \paragraph{Set Elements.} The \agwindow{Set Elements} window can be accessed through the \agmenu{Auxiliary Windows} menu in a window that identifies a character set, a partition set, or a terminal token. The \agwindow{Set Elements} window shows the numeric code and screen representation for each element of the set. In the case of a terminal token, the character set displayed is the character set corresponding to the terminal token. If you select \agwindow{Set Elements} in a window that identifies tokens, and the selected token is nonterminal, AnaGram will simply beep. \index{State Definition}\index{Window} \paragraph{State Definition.} The \agwindow{State Definition} window can be accessed through the \agmenu{Auxiliary Windows} menu in any window that identifies a state but does not provide its characteristic rules. The format is the same as that in the \agwindow{State Definition Table}, except that it is limited to a single state. \index{State Definition Table}\index{Window} \paragraph{State Definition Table.} The \agwindow{State Definition Table} lists, for each parser state, all of the characteristic rules which define that state. The rules are displayed with the marked token in a distinctive font. \index{Rule}\index{Completed rule}\index{Rule}If there is no marked token, the rule is complete. Otherwise, the marked token found to continue the match. % XXX ``the marked token found to continue the match''? % (yes, this is how it is in the wordperfect version) % it also said ``with a the marked token'' but I fixed that. Each line contains the state number, the rule number, and finally the rule itself. The state number field is blank if it is the same as the state number on the previous line. The cursor bar is synched with the syntax file to show the grammar rule in context. \index{State Expansion}\index{Window} \paragraph{State Expansion.} The \agwindow{State Expansion} window may be accessed using the \agmenu{Auxiliary Windows} menu from any window that identifies a state. It shows the complete set of expansion rules for the state, consisting of the union of the set of characteristic rules and the sets of expansion rules for the token to the right of the mark in each characteristic rule. The \agwindow{State Expansion} window shows all possible legal input to your parser in the given state. % XXX \index{Show statistics} ? \paragraph{Statistical Summary.} While your grammar is being analyzed, a \agwindow{Statistical Summary} window pops up to show the progress of the analysis. Unless you have turned off the \agparam{show statistics} switch on the \agmenu{Options} menu, this window will remain on-screen for 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 the \agparam{show statistics} switch disabled, the appearance of this window on your monitor may be exceedingly brief - you may just see a flash. % XXX or nothing at all. If the window is turned off or you have closed it, you can get it from the \agmenu{Browse} menu. \index{Symbol Table}\index{Window} \paragraph{Symbol Table.} The \agwindow{Symbol Table} lists all the symbols you used in your grammar. Symbols may be used, of course, to identify tokens, definitions, or virtual productions or to provide alternative names for tokens. 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 a set expression or virtual production, it is followed by an equal sign and the expression or virtual production. \index{Token Derivation}\index{Window} \paragraph{Token Derivation.} See \agwindow{Rule Derivation}. \index{Token Table}\index{Window} \paragraph{Token Table.} The \agwindow{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 \agparam{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. \index{Token Usage}\index{Window} \paragraph{Token Usage.} You may access a \agwindow{Token Usage} window from the \agmenu{Auxiliary Windows} menu of any window that identifies a token. It shows all grammar rules which use the token. In each rule the marked token, if any, will follow the selected token, so that further \agwindow{Auxiliary Windows} menu choices will refer to the marked token rather than the selected token. \index{Trace Coverage}\index{Window}\index{Coverage} \paragraph{Trace Coverage.} When you run a \agwindow{File Trace}, AnaGram automatically counts the number of times each rule in your grammar is reduced. You may inspect these counts using the \agwindow{Trace Coverage} window. Unless you have set the \agparam{rule coverage} switch, certain optimizations in AnaGram's tables will cause some null productions and rules consisting of a single token to not be counted. \index{Warnings}\index{Window} \paragraph{Warnings.} If while analyzing your syntax file, AnaGram finds something suspicious, it issues a warning, regardless of the severity of the problem. The \agwindow{Warnings} window will pop up automatically when the analysis has been completed. If the warning is for a \index{Errors}syntax error in your input file, you will have to fix it, because AnaGram cannot successfully interpret your syntax file. Otherwise, no matter how serious the warnings may be, AnaGram will create a parser if it is instructed to do so. Thus if you decide the warnings are of no consequence, you may choose to ignore them. Note that AnaGram will resolve \index{Conflicts}shift-reduce conflicts by choosing the shift action. It will resolve \index{Conflicts}reduce-reduce conflicts by choosing the rule that occurred first in the grammar. If you have syntax errors, AnaGram will synchronize the cursor in the syntax file window with the cursor in the warning window so that as you move through the warning messages, the cursor in the syntax file window will move to the point of the error.