PowerAda Unit Browser

From OC Systems Wiki!
Jump to: navigation, search


One of the most powerful features of PowerAda is the Unit browser. The browser supports viewing the source for compilation units in the library, posing queries about the contents of these units, and using the results of these queries to browse other units. You can click F1 to get context-sensitive help from any window.

From the powerada main window, click on the Browse Unit button to bring up a Unit Selection Dialog.

Unit Selection Dialog

The Unit Selection Dialog provides a list of compilation units in the library which you may browse. It consists of five areas:

Units List
A list of units which may be browsed. This list initially contains all units in the library, but may be reduced by using a Filter, described below. Double-clicking mouse button one on a unit in the list opens a Unit Browser Window on that unit.
Unit Kind
A pair of buttons are provided to indicate whether you wish to browse the body or specification of the selected unit. The initial default is to browse the body. If the selected unit has only a specification or only a body (as in the case of a subunit), the setting of these buttons is ignored.
Filter
A type-in box in which wildcard string which may be provided to reduce the contents of the list to the set of unit names matching the wildcard. To apply a filter, enter a string and click the Filter button at the bottom of the dialog. The character '*' matches a sequence of zero or more characters, and '?' matches any one character. For example, the string "posix*" will change the Unit List to contain only those units starting with the letters "posix". To show all units in the list again, specify the filter string "*".
Selected Unit
The name of the unit to be browsed. This will be shown when an item is selected from the list. Or you may type in a unit name directly. Click Browse to open the Unit Browser Window on that unit.
Buttons
The following buttons are provided on the button bar:
  • Browse - opens a Unit Browser Window on the unit shown in the Selected Unit pane;
  • Filter - applies the string in the Filter type-in box to the list of all units;
  • Cancel - closes the Unit Selection Dialog; and
  • Help - invokes the Help browser showing some information about this dialog.

Unit Browser Window

The Browser window consists of a menu bar and a Source Pane. The menu bar presents a number viewing options and queries, which are described below. In addition, clicking mouse button three (usually the rightmost mouse button) in the source pane shows a popup menu giving a number of the more common operations, also described below. If you are using the PowerAda browser from within the debugger, this popup menu will contain some useful debugger operations as well.

Several of the queries take as input the current Ada element. To highlight the Ada element which will be operated upon by a query, hold down the shift button and click mouse button one (the leftmost one). For more information on elements, see "About Elements".

adbg 09.gif

The Source Window Popup Menu

The source window popup menu provides a convenient way to access the most commonly used functions in the browser. Click MB3 (the right mouse button) to use this menu.

Find
Pops up the Find Dialog, with which the user can identify occurrences of a specific text string or Ada syntactic construct. Toggle buttons control whether text searches wrap at the end of the file, and whether or not they are case-sensitive.
Find Next
Searches forward for the next occurrence of the string or construct most recently indicated in the Find Dialog
Goto Line
Prompts for a line number. Enter a line number and click Ok or hit return, and the specified line of the current unit's source will be centered in the source window.
Definition Of
Opens a browser window and shows the Definition of the selected element.
Derivation Of
Shows the Derivation of the selected type in a Class Browser.

File Menu

Preferences...
Initiates the preferences dialog
Clone Window...
Creates a new browser window with the exact same contents as the current window. Browsing in these windows can proceed independently. See how this relates to the Previous View menu item described below.
Edit File...
Invokes the editor on the unit currently displayed in the source window. If the source for this unit is found where it was compiled from, that file is edited. If not, a temporary copy is made of the source in the library, and that file is edited. The default editor is vi. You may specify an alternate editor (such as Ada-sensitive xemacs) using the Preferences dialog in the File Menu.
Send to PowerAda...
Invokes PowerAda on the unit currently displayed in the source window. The source for the unit will be displayed in a source browser view in PowerAda.
Browse Units...
Brings up the Unit Selection Dialog through which other units may be browsed.
Close Window
Closes the current window. This effect may also be achieved using the Motif action decoration in the upper left corner of the window frame. Note that this does not quit powerada or adbg.
Quit Debugger
Prompts to exit the debugger. This is identical to the Quit button in the File Menu.

View Menu

View Previous
Replaces the current view by the previous view. The current view is lost. Each Definition operation generates a new view and pushes it on the stack. The View Previous operation pops the current view off the stack. If one wishes to keep the current view and return to the previous view, choose Clone Window from the File Menu before choosing View Previous.
Outline
Generates a list of all the subprograms in the current unit and displays them in an Outline Pane above the Source Pane.

Source Menu

Visit Selected Item
Opens a browser window and displays the selected element.
Definition Of
Opens a browser window and shows the Definition of the selected element.
Derivation Of
Opens a browser window and shows the Derivation of the selected type in a Class Browser.
Attributes Of
Pops up a dialog showing some information about the current element. The information includes its fully-qualified name, its usage, and, if it is a composite type, some layout information. See "About Elements" for more information.
Local Uses Of
Opens a browser window and shows the local uses of the selected object.
Find
Pops up the Find Dialog, with which the user can identify occurrences of a specific text string or Ada syntactic construct. Toggle buttons control whether text searches wrap at the end of the file, and whether or not they are case-sensitive.
Find Next
Searches forward for the next occurrence of the string or construct most recently indicated in the Find Dialog
Goto Line
Prompts for a line number. Enter a line number and click Ok or hit return, and the specified line of the current unit's source will be centered in the source window.
Unit Information
Displays useful information about the current unit, including unit name, filename, sublibrary, compile timestamp, and compilation options used.
Show Line Numbers
Controls whether or not line numbers are displayed in source pane views.

Help

This displays the PowerAda Browser help page in the help browser.

About Elements

An Ada compilation unit can be broken down into syntactic pieces. We refer each such syntactic piece as an element. All operations in the Query menu of the browser operate upon an element. Usually, your cursor rests on some element. To determine the current element, hold down the shift key and click mouse button one. This will highlight the current element if there is one. If no highlighting occurs, the cursor is not on an element which can be operated upon. If the whole window is selected, chances are that the current element is the entire compilation unit, which generally means you are between more localized elements.

Definition Query

The Definition of an element depends on the element. Generally, it can be thought of as its declaration, but this is not always true. Some specific instances are shown in the table below:

Element Definition
variable reference declaration of the variable
parameter reference specification of the subprogram
(sub)type reference declaration of the (sub)type
subtype declaration declaration of the parent type
subprogram call specification of the subprogram
package body package specification
subprogram body subprogram specification
subunit stub subunit declaration
subunit declaration corresponding subprogram or package specification
package specification package body
subprogram specification subprogram body
generic instantiation expanded generic

Outline Pane

The outline pane is a small list above the Source Pane in the browser window. It displays lines from the corresponding source pane. Clicking on a line in the outline pane moves the cursor to the first line of that subprogram in the source pane, and makes that pane visible.

Note that the contents of the outline pane are not part of the view history that is saved, so information about Local Uses or Find... searches is lost when new information is placed in the outline pane.

Source Pane

This shows the source for the current unit. Generally, this is the source saved in the library and so does not change unless a new source file is compiled into the library. Along the left margin are line numbers. The character after the line number may be one of the following:

: (colon) indicates that the line is part of the current unit

* indicates that the line is NOT part of the current unit

= indicates that a breakpoint may be set on this line (debugger only)

> indicates that a breakpoint has been set on this line (debugger only)

Along the left margin you will see toggle buttons indicating where breakpoints may be set. You can set/clear a breakpoint by clicking on a button.

Holding down mouse button three (the right mouse button) shows a popup menu with some useful operations in it. Most of these operations are also available from the pulldown menus.

Find Dialog

The Find dialog has a type-in area where the user specifies text to search for. The search is forward through the source file. Toggle buttons are provided to indicate whether the search is to be case-insensitive, and whether it should wrap around to the top of the source file if the string is not found between the current location and the bottom.

To start the search, hit return or click Find. If you click Find All instead, the contents Outline Pane will show all lines in which an occurrence of the searched-for string or construct is found.