General Information

	Eli: Translator Construction Made Easy
	Global Index
	Frequently Asked Questions
	Typical Eli Usage Errors

Tutorials

	Quick Reference Card
	Guide For new Eli Users
	Release Notes of Eli
	Tutorial on Name Analysis
	Tutorial on Scope Graphs
	Tutorial on Type Analysis
	Typical Eli Usage Errors

Reference Manuals

	User Interface
	Eli products and parameters
	LIDO Reference Manual
	Typical Eli Usage Errors

Libraries

	Eli library routines
	Specification Module Library

Translation Tasks

	Lexical analysis specification
	Syntactic Analysis Manual
	Computation in Trees

Tools

	LIGA Control Language
	Debugging Information for LIDO
	Graphical ORder TOol

FunnelWeb User's Manual

	Pattern-based Text Generator
	Property Definition Language
	Operator Identification Language
	Tree Grammar Specification Language
	Command Line Processing
	COLA Options Reference Manual

Generating Unparsing Code

Monitoring a Processor's Execution

Administration

System Administration Guide

Execution Monitoring Reference

Information

This chapter briefly describes the type of information that Noosa can provide about the execution of your program and how to go about getting it.

Input Text Display

Usually the initial input to an Eli-generated program is specified on the command-line of the processor (see Command Line Processing) and subsequent input (if any) is given by the input text itself (perhaps via include directives or similar mechanisms).

Noosa displays the input text as seen by your program in the top part of the main window. (The current Noosa system does not fully support the monitoring of programs when their input is standard input.) The input text is shown exactly as your program sees it. In particular, it appears as one contiguous piece of text rather than (say) a set of files included into other files. Note also that when the program stops, the input text displayed is the text that has been seen by the program at that point. Text encountered later on (perhaps by later include directives) will be displayed when it is encountered.

In various settings Noosa will display input text coordinates (e.g., when you ask to see the lexical tokens recognised). There are two formats used to display coordinates:

12,3
9,1-12,80

In the transcript window coordinates or coordinate ranges will be underlined. Clicking the left mouse button on a displayed coordinate (or range) causes Noosa to highlight the coordinate (or range) in the input text. This enables you to conveniently match Noosa output to input text.

As mentioned above, the input to your program may come from more than one text file. The coordinates used by Noosa are cumulative in that they reflect the overall input text, not the individual text files. To find out from which file a location comes, select the location in the input text window and execute the Describe coord command from the Examine menu (also available on the right button in the main windows).

Messages

Eli-generated programs take text as input, analyse that text, and perhaps produce some text as output. During analysis, messages may be produced for a variety of reasons. Eli provides a module to help generate messages (see Error of Library Reference Manual).

If your program generates any messages they will be displayed in the transcript window. The coordinate of the message will be shown with the severity and the message text.

String Table

Most Eli-generated programs need to manipulate text strings. To avoid the overhead of copying strings around during execution, a string table can be used. Eli has a module that implements a string table allowing integers to be used to represent strings (see Storage of Library Reference Manual).

Noosa allows you to see the contents of the string table using the Strings command from the Examine menu. Each string in the table will be displayed with its index. The String command can be used to display a single particular string. Select the numeric string index with the mouse then execute String. This mode of use is particularly useful if the string index has already been displayed by Noosa in some other setting (e.g., as the intrinsic attribute of a token).

Lexical Structure

Eli-generated programs that perform lexical analysis can do so using the support of an automatically-generated lexical analyser (see Lexical Analysis). Noosa lets you examine the behaviour of the generated analyser on your program's input text.

Your program will generate a stream of tokens. Selecting an input text coordinate (or range of coordinates) in the input text window and executing the Token command from the Examine menu will cause Noosa to display the tokens recognised that overlap that coordinate (or range).

The following information is displayed for each token: input text coordinate range, numeric token code used internally by the analyser, length in characters, the intrinsic attribute value of the token, the input text (lexeme) matched by the token, and, for non-literal tokens, the name of the non-literal as specified in your type-`gla' specifications (see Specifications of Lexical Analysis).

Phrase Structure

Programs that need to determine the phrase structure of their input can do so within Eli using automatically-generated parsers (see Syntactic Analysis).

The Noosa Phrase command (in the Examine menu) lets you look at the phrase structure that is recognised by your parser. Selecting an input text coordinate in the input text window and executing Phrase will produce a list of all the production instances recognised by your program that overlap the selected coordinate.

The instances are listed from most general to most specific, so the first one is always the root production of the grammar. Each production instance is displayed with the input text coordinate range for that instance. On the right-hand side of each production the symbol corresponding to the left-hand side of the following production is highlighted. (Note that in some cases chain production elimination is performed by Eli-generated parsers. This may mean that the highlighted symbol on the right-hand side of a production instance is not the same symbol as the left-hand side of the next production instance.)

Examination of the phrase structure with Noosa will work if you are using either the PGS or COLA parser generating systems available within Eli (see parser of Products and Parameters Reference Manual).

Trees and Attribute Values

If your processor contains attribution, Eli will automatically construct an abstract tree for the input text. Noosa has facilities for examining this tree and any other trees computed by your processor.

Tree display can be enabled using the Trees item in the Windows menu. Windows containing the selected trees will appear next time the program is run. There are four options in the Trees menu: Just Source, Separate Computed, Source and Computed, and Incremental. Any combination of these options can be used.

The first three options draw trees in a traditional tree manner with the root at the top and children under their parents. The Incremental option draws the root at the left and children to the right of their parents. The former style always uses a nice layout but always draws the whole the tree (but see below); the latter initially just draws the root of the tree but allows nodes to be selectively expanded (see the online help for details).

The Just Source option causes the source tree built by your processor's parser to be displayed. The Separate Computed option will cause each computed tree to be displayed in a separate window as soon as they are complete. This option is most suitable if you have a few largish computed trees. The Source and Computed option shows the entire tree (including computed trees joined at the appropriate places) so it is more suitable if you have many smaller computed trees. Finally, the Incremental display allows access to the entire tree that has been computed so far.

The tree displays can be saved as Postscript via the Tree menu. You can elect to save just the visible portion of the tree or the whole tree.

In any of the tree displays it is possible to select nodes with the left button. The abstract grammar production derived at that node will be displayed in the transcript window and the input text extent of the node will be highlighted in the input text window.

Also, the right button can be used on a symbol (rule name) to display a menu listing the attributes (attributes and terminal values) of that occurrence of the symbol (rule). Each attribute or terminal has a pull right menu with which you can indicate whether you want to see its value (with optional stopping of execution) or ignore it (the default). Using this facility you can check that your attribution is working correctly. Note that values will only be displayed when they are next calculated, so you will need to run the program again after selecting some values for display.

Note: The current version of Noosa is not able to deal properly with chain attributes. Chain attributes will show up in the attribute menu as a pair of regular attributes with _pre and _post appended to the attribute name. It is possible to select these attributes for display. However, in the current system, not all will be displayed because of limitations in the generated processor code.

Noosa has a simple mechanism for displaying the values of attributes in the transcript window. Values are displayed preceded by their type name. If a value can be browsed (or "opened") it will be underlined and browsing is performed by clicking on the value with the left button.

Eli currently has support to allow the following types of value to be browsed.

Tree nodes (Node, NODEPTR)

Clicking on a tree node value causes your abstract tree display(s) (if any) to highlight that node. A NODEPTR value is a run-time pointer to a tree node. Clicking on one of these values will select the corresponding node in a tree display if it is there.

PTG nodes (PTGNode)

Opening a PTG node causes the system to run the function PTGOutFile on the node and display the resulting output in the transcript window. Note that due to side-effects in PTG functions or redirected output, the text displayed may not be same as the text finally output by your processor.

Environments (Environment)

Opening an environment produces in the transcript a list of the name-key pairs in that environment. If the environment is nested within another environment then the parent environment is printed so that it can be browsed as well.

Bindings (Binding)

Opening a binding will produce the identifier that is bound (IdnOf), the key to which it has been bound (KeyOf), and the environment containing the binding (EnvOf).

Definition table keys (DefTableKey)

Opening a definition table key will produce a list of the current properties of that key and the values of those properties.

OIL types and typesets (tOilType, tOilTypeSet)

These types are used for operator identification. Opening an OIL type shows the type name (a definition table key). Opening an OIL typeset shows the elements of the set and their associated costs.

Tree parser nodes (TPNode)

Opening a tree parser node will produce the node name and a list of its children.

Breakpoints and events

Noosa follows the progress of your program using events. When a significant thing happens during execution the program will generate an event to signal that fact to the monitoring system. Event instances have parameters which allow them to provide arbitrary information to the monitoring system.

Breakpoints in the Noosa system are conceptually similar to breakpoints in source-level debuggers, but operate at the level of events rather than source code locations, functions or variables. They are implemented by attaching handlers to event types.

The Handlers command in the Windows menu creates a dialog window through which you can enter handlers for the different types of events that your program may produce during execution. A list of relevant event types is displayed and handlers can be entered, edited, deleted etc. (See the Help menu in the Handlers dialog for more information.) Handlers can also be saved to files and autoloaded, see See User Initialisation.

Handlers are expressed using the Tool Command Language (Tcl). (A complete description of TCL is beyond the scope of this manual. See the Tcl online manual pages or any book on Tcl/Tk for details.) Handlers can contain arbitrary Tcl code and may refer to the event parameters as Tcl variables. To cause execution to stop as the result of handler execution, have the handler call the Tcl n_break command.

For example, the following handler causes execution to stop if the string printf is stored into the string table. This handler would be attached to the string_stored event.

if {$string == "printf"} {
    n_break
}

There is no requirement that a handler actually cause execution to stop. It may just display information and allow execution to continue. Within a handler, the builtin Noosa command n_say may be used to display information in the Noosa transcript window.

For example, the following handler causes the lexeme of every token on line three of the input to be displayed. This handler would be attached to the token event type thereby making the linebeg and lexeme parameters available.

if {$linebeg == 3} {
    n_say "lexeme is $lexeme\n"
}

All Eli-generated programs prepared for monitoring automatically generate a single event instance of type init at the beginning of execution, and one of type finit at the end of execution. This can be useful if you want to collect some information using handlers during execution and display a summary at the end using a handler on the finit event type.

Frequency Profiles

Frequency profiles provide information about the frequency of events generated by your program. When execution stops, a summary of events generated up to that point will be produced. The summary contains the name of each event type generated and the count of the number of times events of that type were generated by a particular component of the program.

Frequency profiles are enabled and disabled by the Frequency profile checkbutton in the Profile menu. By default they are disabled. The Zero frequencies command can be used to set all of the frequencies to zero. This can be useful if you only want to collect frequencies from a particular point during the execution.

Time Profiles

Time profiles provide information about the CPU time spent in components of your program. For each component the CPU time in seconds is given with the percentage of total CPU time due to that component.

Time profiles are enabled and disabled by the Time profile command in the Profile menu. By default they are disabled. The Reset times command can be used to set all of the times to zero.

Time profiles are obtained by generating an enter event each time execution enters the code for a component, and a leave event when execution leaves again. Consequently, time is only allocated to components which have appropriate monitoring support. Currently, the main components within Eli have this support, but not all components do. Also, due to the short running time of most Eli-generated programs on test input, the times reported in a time profile are likely to vary considerably from run to run due to the granularity of the timing mechanisms. Consequently, time profiles should only be relied on when using large inputs or running time is larger for some other reason.

Tracing Events

Sometimes it is useful to see the event stream generated by your program. The Event trace command in the Profile menu provides this capability. When tracing is enabled Noosa will display the event type and parameters of every event generated by the program until it stops.

The Set event filter command allows subsets of events to be selected using a regular expression. A dialog box allows you to set a new expression or clear an old one. Executing the Set event filter command will cause subsequent tracing to display an event only if the event information matches the regular expression. The default regular expression is .* meaning all events are displayed.