Definitions

The Definitions dialog can be used to list all of the existing definitions for a symbol, and also to locate and edit the source code for a selected definition. The definitions include all functions, methods of generic functions (including class accessors), macros, variables, constants, standard classes, and structure classes that are named by the symbol. The dialog may also be used to remove individual methods from the Lisp environment.

This dialog is displayed by the Search | Find Definition command. It is also displayed by the Find Definition or Find Applicable Methods commands on the shortcut (right button) menus in certain windows.

Above is the Definitions window listing the definitions of the symbol doodler. We have loaded the final tutorial project file (gui-builder-tutorial/final/interface-builder-tutorial.lpr), and both a function and a class named doodler have been found.

To use the dialog, invoke the Search | Find Definition command. If a symbol was selected at the time, it will be placed into the Symbol text widget at the upper left of the dialog (it says "doodler" in the picture). If this is not the symbol whose definitions you want to list, then type or paste the desired symbol into the Symbol widget. As you type each character, if you have named a symbol that has any definitions, then a bit of information will appear in a static-text widget just beneath the symbol widget, such as the parameter list of a function. Pressing the Find/Open button at the upper right will then list all definitions for the symbol in the "found definitions" widget at the bottom of the dialog. (The button is labeled Find before searching and Open after a search is complete. The illustration is after a search, so the button is labeled Open.)

Once some found definitions have been listed, the Find button becomes an Open button; pressing it will edit the source code for the currently selected definition if the location of the source code is known. The source code location will be known for any definitions that were compiled, evaluated, or loaded in the current lisp session. (When a fasl file is loaded, the dialog assumes that the source code is located in a corresponding file with a .cl extension.) If the editor is already editing the file that contains the definition, then the definition will be shown in the existing editor buffer that contains it.

The Find/Open button is the dialog's default-button when it says Find as well as when it says Open. Therefore, the main Enter key may be pressed to list a symbol's definitions when there are no definitions currently listed, and may be pressed again to edit a selected definition. The button will say Open whenever any found definitions are currently listed, and will say Find otherwise. Typing into the Symbol widget or invoking the Search | Find Definition command again always clears the list of found definitions and changes the button to say Find.

Note that if you have the Common Graphics/IDE source code installed in your Allegro directory, then you can use the Definitions dialog to find all CG/IDE definitions by first calling the function load-cg-source-file-info. (If you attempt to locate a CG or IDE definition without first calling this function, a dialog will appear that offers to call the function for you. After calling the function, you will need to do the Find Definitions command again to locate the source code.)

The Applicable Methods Filter

The Applicable Methods Filter is an editable-text widget that may contain a list of applicable arguments to filter out found methods that are not of interest. If this widget does contain such a list of argument values, then any found methods that are not applicable to those arguments are excluded from the list of found definitions. This widget is available only when the All check-box is unchecked, since checking the All check-box overrides the applicable arguments widget and shows all found definitions. The All check-box itself is available only when methods have been found.

Typically the applicable arguments widget is filled in automatically. This happens whenever the Find Definitions command is invoked from the Trace Dialog's main outline widget or from a Debug Window backtrace pane. In each of these panes, the selected value denotes a function call that has occurred, including the arguments that were passed. Invoking the Definitions dialog in one of these panes places the list of the function call's arguments into the applicable arguments widget of the Definitions dialog, so that the dialog will list only the methods that might have been invoked by the selected function call (though all non-method definitions for a symbol are always listed).

You may also type in a list of applicable arguments explicitly. To do so, first uncheck the All check-box if it is checked. (This check-box causes all methods to be listed whenever it is checked, and the applicable arguments widget is available for typing or pasting only when All is unchecked.) Then in the applicable arguments widget, type an expression that will produce the desired list of applicable arguments when evaluated, and press the main Enter key to evaluate the expression and list the definitions that exclude any non-applicable methods. The expression entered is always evaluated because it is impossible to literally type most argument values. (It's an exception that pressing Enter while the keyboard focus is in this widget will always evaluate the expression there (if newly entered) and then do a Find, even if the Find/Open button currently says Open.)

If the Methods text widget is not roomy enough to easily enter this expression, you may click the ellipsis button (just to the right of the editable-text widget) to enter the expression into a modal dialog containing a multi-line-editable-text widget instead.

When a found method is selected, the Remove Selected Method button may be pressed to remove the method from the Lisp environment. This can be handy, for example, when you edit a method and change one of the classes that it specializes on, or change an :after method into an :around method. In these cases, the earlier method with the original specializers and qualifiers will still exist in the Lisp environment along with the new version, and this can affect the behavior of your application. By listing all of the methods in this dialog, you can see which ones still exist and easily remove the obsolete methods.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.