Apropos dialog

The Apropos dialog, displayed by clicking Search | Apropos, is a search engine for finding symbols in the running Lisp whose names contain the contiguous characters specified in the String field. Exactly those characters, contiguous and in the specified order must appear in the symbol name. Case only matters when the case mode is sensitive or if a symbol has a mixed case name (which is unusual).

The search can be constrained to just symbols exported from their home package, to just symbols naming functions (actually operators -- functions, generic functions, and macros, that is symbols for which fboundp returns true), to just naming variables (symbols for which boundp returns true), or to just symbols naming classes. The search can also be constrained to symbols accessible in a single specific package, as in the illustration, where only symbols accessible in the top-level package are shown..

The String field

Enter the string (without quotation marks) to be searched for. There are no wildcards. Only symbols whose name contains the exact characters entered in this field, in order and contiguous are displayed. (Thus, in the illustration, only symbols containing "float" are displayed. A symbol named flomat, if there was one, would not appear.)

When you have entered the desired string, click Search or press Enter to display the results. A drop-down list shows previous strings. Changing a string does not update the results display until Search is clicked or Enter is pressed.

A warning dialog appears if no symbols fit the search criteria.

Warnings when no characters or only one character appears in the String field

When the String field is empty, all symbols that fit the other criteria would be included. Displaying so much in a dialog is problematic, and thus doing so is not supported. If you click Search when there is nothing in the String field, a dialog is displayed saying Enter a search string before doing an apropos search. No search is done when no characters are in the String field.

There can also be very many symbols that contain a single specified character. Searching on a single letter is supported but a warning dialog is displayed before the search is done to allow you to confirm your intention. Such a search, if performed, can take an appreciable amount of time.

The Show Exported Symbols Only check box

If checked, only symbols exported from their home package are displayed. In the illustration, this box is not checked and so cg.grid-widget::section-size-float (not exported from the cg.grid-widget package) is shown. Unexported symbols are identified by double colons following the package nickname and by no mark in the Exp column (exported symbols have a mark in the Exp column).

The display is updated immediately if you check or uncheck this checkbox.

The Packages field

Symbols in all packages are shown if the All checkbox is checked. If it is unchecked, as in the illustration, only symbols accessible in the package named in the drop-down list are shown. All symbols whose home package is the package to search are displayed. Other accessible symbols are those exported from a package used by the package to search. Thus, symbols in the common-lisp (nickname cl) package appear whenever the package to search uses the common-lisp package (and most do). There is no way to restrict the search to symbols whose home package is the package to search. There is also no way to restrict the search to more than one package. All or one are the only choices.

The display is not updated automatically if you change from All to a single package or change the single package. Click on the Search button to update the display.

The Show field

If All is selected, all symbols fitting other criteria (contain string, accessible in package) are displayed. If Functions is selected, just those symbols naming functions (or generic functions or macros) are displayed. If Variables is selected just those symbols that have a value are displayed. If Class, just those naming a class. Changing the Show field causes the display to be updated immediately. Note that a single symbol can name a function, a variable and a class.

The results display

The results of a search are displayed in the List View control labeled "Symbols containing [string]". The symbol name appears on the left, then the nickname of the home package, then whether the symbol names a function, whether that function is setf'able, whether the symbol names a variable, whether it names a class, and whether it is exported from its home package, whether it names a compiler macro, and whether it names a symbol macro.

The Function column will display "generic" for a generic function, "function" for a nongeneric function, "macro" for a macro, "special operator" for a special operator, or "functor" for a Prolog functor. The Var column will display "var" for a global variable or "con" for a constant. The Class column will display "class" for a standard-class, "struct" for a structure-class, "nonstd" for certain non-standard classes, or "type" for a type that does not name a class (such as bignum). Other columns will display only a single particular string indicator or nothing, such as "setf" in the Setf column, where the particular string simply makes it unnecessary to look up at the column header for the meaning of the indicator.

Double clicking on a symbol name (or selecting it and pressing enter) displays a Find Definition dialog allowing you to find the source code of the definition of the symbol if that code is available.

At any time, clicking on the Search button updates the display.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 8.1 page.
Created 2016.6.21.