find-name name constraint context

Find-name creates a dialog box used to browse declarations of Ada constructs. Browsing is controlled by name, context, and constraint parameters.

The name consists of one or more identifiers, operator symbols, or wildcard designators (the question-mark character `?') separated by dots. If the structural selection of the buffer from which find-name is invoked uniquely identifies a name, the name parameter is initialized accordingly; otherwise, it is set to the wildcard (?).

The constraints restrict browsing according to sort and kind. The sorts are: procedure, function, type, exception, task, entry, and package. Ada 95 has the additional sort protected. The kinds are: specification, definition, generic, and stub. Constraints are indicated by a set of radio buttons associated with the find-name dialog box. The initial value of the constraints depends on the context from which the find-name command was invoked. For example, within an expression, only function calls are permitted, not procedures, entries, etc. Accordingly, the radio buttons are initialized to match only functions.

The context is a location in an Ada compilation unit. The context determines a set of active with-clauses, use-clauses, and rename-declarations according to the scope rules of Ada. These influence the database search as follows: (a) with-clauses control visibility of non-local names; (b) use-clauses control prefixes considered for completing the given name, and (c) rename declarations control aliasing. The context is initially determined by the location of the structural selection at which find-name was invoked. Three radio buttons are provided to control the degree to which with-clauses, use-clauses, and rename declarations of the context influence the search. These radio buttons are initialized to On. The exact effect of these buttons is described below.

Execution of find-name initializes the name, constraint, and context parameters and performs the database search. The number of matches is printed and a list of matches is displayed in a list widget of the dialog box. The different matches listed can be highlighted by clicking on them. The format of the list of matches is controlled by the nameMatchFormat resource.

The Open button opens the file associated with the highlighted match and positions the structural selection on the matched entity. By default, the file is opened in TEXT mode. Command coerce-buffer can be used to convert the browsed file to buffer of syntactic category compilation. The default mode for opening browsed files is controlled by the toggle-browse-as-TEXT command.

Clicking on the Next button is equivalent to clicking on the next name in the list and clicking on Open. Similarly, clicking on the Previous button is equivalent to clicking on the previous name in the list and clicking on Open. If there is no next or previous name, an error message is printed. Clicking again then cycles around the list. The Next and Previous buttons are bound to the next-name and previous-name commands.

Clicking on the Start button is equivalent to first clicking on the Find button, then clicking on the Open button, except that the dialog box is popped down. Clicking on the Cancel button pops down the dialog box without any action. Striking Return is equivalent to clicking on the Start button.

The name can be changed by text editing the name field in the dialog box. The constraints can be changed by clicking on appropriate radio buttons. Clicking the Match All button sets the constraint and context buttons so that a subsequent search will match as many items as possible. For example, to see all entries in the database, the user would enter the wildcard character ? in the name field, then click first on Match All, then Find. After any such change, the database match can be re-established by clicking on the Find button.

The name and the context can both be reset by clicking Select on a name in some compilation unit and then clicking on the Refresh button.

The command is parser-initiating.

Rather than adhering strictly to the scope and visibility rules of Ada, Ada-ASSURED uses various approximations that are designed to support effective browsing both during and after code development.

When the With context button is on, a search for a partially-qualified name is constrained by the with-clauses in effect at the current context; i.e., names of packages for which there are no with-clause present are not considered as possible prefixes for the given partially-qualified name. In contrast, when the With context button is off, the database search for a partially-qualified name considers all possible prefix completions of the name—without regard to the with-clauses and use-clauses present. The actual with-clauses of a user's program are also ignored when a search key is either fully-qualified or contains a wildcard prefix.

When the Use context button is on, the use-clauses are employed to generate the possible prefix expansions of a name. When off, the use-clauses are ignored, i.e., treated as if they were not present.

When the Renames context button is on, the renaming clauses are taken into account when doing the database search. When off, they are treated as if they were not present.

Note that all names local to a given compilation unit are retrievable from anywhere within the unit, regardless of the scope and visibility rules of Ada.

The database retrieval matching algorithm is illustrated by the following example. Assume that packages m1, m2, m3, and m4 each contains a procedure p, and consider searching the database from the context of the statement placeholder in the following code:

with m1, m2, m3;
use m1;
procedure p is
    package r renames m3;
    use r;
begin
    <statement>
end;

First, assume the with context, use context, and renames context buttons are all on. Then searching for p will retrieve m1.p, m3.p (i.e., r.p), and the local p. Procedure m2.p is not retrieved because there are no use-clauses for m2. Procedure m4.p is not retrieved because there is no with-clause for m4. Searching for ?.p will retrieve m1.p, m2.p, m3.p, and m4.p, but not the local p. Searching for r.p will retrieve only m3.p.

Now suppose the with context button is turned off. Then searching for p will retrieve all five instances of p.