get-relation

$Revision: 5.0.2.4 $

Function

Package: CROSS-REFERENCE

Arguments: (relation name1 name2 &key in-files in-functions exhaustive errorp)

This function returns (rather than prints) information on whether the function identified by name1 has the relation identified by relation to the function or global variable identified by name2. (Of course, a relation will be identified only if the cross reference database contains information on the relation.)

name1 should always be a function name or :wild. A function name is a symbol or certain types of lists. See implementation.htm for information on allowable types of lists.:wild indicates that a list of all functions in the database having relation to name2 (but perhaps restricted by in-files and in-functions - see below). name2 should be a function name if relation is one of the calls relations and should be a global variable if relation is one of the uses relations. Calls and uses relations are defined just below. name2 can also be the keyword :wild, in which case a list is returned with all functions in the database (perhaps restricted by the in-files and in-functions arguments) which have the relationship specified by relation to name1.

Only one of name1 and name2 can be :wild. If both are specified :wild, an error will be signaled.

The value of relation can be any of the following keywords. The first four are calls relations and the second four are uses relations.

:direct-calls: true if name1 directly calls name2.
:indirect-calls: true if name1 indirectly calls name2 (i.e. refers to #'bar for the function bar).
:macro-calls: true if name1 calls the macro identified by name2.
:calls: true if any of the three previous relations is true.

:binds: true if name1 binds the global variable identified by name2.
:references: true if name1 references the global variable identified by name2.
:sets: true if name1 sets the global variable identified by name2.
:uses: true if any of the three previous relations are true.

The in-functions and in-files keyword arguments can be used to restrict the search to particular functions (for in-functions) or functions defined in particular files (for in-files). The default value for each argument is nil, which calls for an unrestricted search. If either or both is non-nil, their values should be lists, of functions or global variables (as appropriate) for in-functions and files for in-files. If either is non-nil, the return result will be restricted to functions or global variables specified in the in-functions list and to functions defined in the files specified by the in-files list. Note that although it is not an error, it is unusual to specify values for either of these arguments unless one of name1 or name2 is :wild.

The exhaustive keyword argument is a boolean. When true, get-relation will look for relations established in the actual implementation (by examining code vectors of function objects) allowing some information to be retrieved even when the is no information in the xref database. This argument defaults to the opposite of xref:*use-xref-database-only* (i.e. default to nil when that variable is true and to t when that variable is nil).

This function returns nil if name1 does not have relation with name2 and neither is :wild. If neither is :wild and relation is true, name2 is returned. If either is :wild, a (possibly empty) list of functions or global variables satisfying relation with the non-:wild argument is returned. What is returned is filtered through the lists which are the values of in-functions or in-files if such are specified.

See cross_reference.htm for more information on the cross reference facility.

The general documentation description is in introduction.htm. The index in index.htm.