4.2 Functions and definitions

4.2.2 Definition searching

Definition searching involves taking a function name and finding the actual definition of that function. This is particularly useful in large systems, where code may exist in a large number of source files.

Function definitions are found by using information provided either by the LispWorks cross-referencer or by a Tags buffer. If cross-referencing or Tags information has not been produced, then the following commands do not work.

Cross-referencing information is produced by turning source debugging on while compiling and loading the relevant definitions (seetoggle-source-debugging in the LispWorks Reference Manual).

Tag information is set up by the editor itself, and can be saved to a file for future use. For each file in a defined system, the tag file contains a relevant file name entry, followed by names and positions of each defining form in that file. Before tag searching can take place, there must exist a buffer containing the required tag information. You can specify a previously saved tag file as the current tag buffer, or you can create a new one usingCreate Tags Buffer. GNU Emacs tag files are fully compatible with LispWorks editor tag files.

Find Source

Editor Command

: Argument: function [tags-file]
Key sequence: +.function [tags-file]
: Tries to find the source code for function. The symbol under the current point is offered as a default value for function. A prefix argument automatically causes this default value to be used.
: If the source code for function is found, the file in which it is contained is displayed in a new buffer. When there is more than one definition,Find Sourcefinds the first definition, and +, (Continue Tags Search) finds subsequent definitions.
: Find Sourcefirst looks for definitions that have been loaded or evaluated (i.e. using cross-referencing information). If it cannot find the definition here, it looks at the current tags file by issuing the commandFind Tag (for this reason,Find Source is recommended rather thanFind Tag).
: If there is no current tags buffer,Find Source prompts for the name of a tags file. The default is a file calledTAGS in the current directory. If there is no such file, you can create one usingCreate Tags Buffer. If you want to search a different directory, specify the name of a tags file in that directory (see documentation on Tags commands given below).
: See the chapter on theDSPEC package in the LispWorks Reference Manual for information on how to use thedpsec:*active-finders* variable to control how this command operates. The fileconfig/a-dot-lispworks.lisp contains an example setting for this variable.

Find Source for Dspec

Editor Command

: Argument: function [tags-file]
Key sequence: None
: Similar toFind Source, but takes a dspec instead of a name as its argument.
: For example, given a generic functionfoo of one argument, with methods specializing onbar andbaz,

Find Source foo

: will find each method definition in turn (with the continuation viaMeta+), whereas

Find Source for Dspec (method foo (bar))

: immediately finds the definition of the method onbar.

View Source Search

Editor Command

: Argument: function
Key sequence: None
: Shows the results of the latest source search (initiated by Find Source or Find Source for Dspec) in the Find Definitions view of the Editor.

Create Tags Buffer

Editor Command

: Argument: None
Key sequence: None
: Creates a buffer containing tag search information, for all the.lisp files in the current directory. If you want to use this information at a later date then save this buffer to a file (preferably a file calledTAGS in the current directory).
: The format of the information contained in this buffer is compatible with that of GNU Emacs tags files.
: A prefix argument causes the user to be prompted for the name of a file containing a list of files, to be used for constructing the tags table.

Find Tag

Editor Command

: Argument: string [tags-file]
Key sequence: +?
: Tries to find the source code for a symbol containing a partial or complete match with string by examining the tags contained in the current tags buffer and loading the correct file when a match is found. The symbol under the current point is offered as a default value for string.
: If the source code for a match with string is found, the file in which it is contained is displayed in a new buffer. When there is more than one definition,Find Tagfinds the first definition, and +, (Continue Tags Search) finds subsequent definitions.
: If there is no current tags buffer,Find Tag prompts for the name of a tags file. The default is a file calledTAGS in the current directory. If there is no such file, you can create one usingCreate Tags Buffer. If you want to search a different directory, specify the name of a tags file in that directory.
: See the chapter on theDSPEC package in the LispWorks Reference Manual for information on how to use thedpsec:*active-finders* variable to control how this command operates. The fileconfig/a-do-lispworks.lisp contains an example setting for this variable.
: See also Find Source and Find Source for Dspec, which find the source code for a function.

Tags Search

Editor Command

: Argument: string [tags-file]
Key sequence: None
: Exhaustively searches each file mentioned in the current tags buffer for string. If string is found, it is displayed in a new buffer containing the relevant file. When there is more than one definition,Tags Searchfinds the first definition, and +, (Continue Tags Search) finds subsequent definitions.
: If there is no current tags buffer,Tags Search prompts for the name of a tags file. The default is a file calledTAGS in the current directory. If there is no such file, you can create one usingCreate Tags Buffer. If you want to search a different directory, specify the name of a tags file in that directory.

Continue Tags Search

Editor Command

: Argument: None
Key sequence: +,
: Searches for the next match for the last tag-based search. This command is only applicable if issued immediately after aFind Source,Find Tag orTags Search command.

Tags Query Replace

Editor Command

: Argument: target replacement [tags-file]
Key sequence: None
: Replaces occurrences of target string by replacement string, for each file mentioned in the current tags buffer, but only after querying the user. Each time target is found, an action must be indicated from the keyboard. For details of possible actions seeQuery Replace on page 73.
: If there is no current tags file,Tags Query Replace prompts for the name of a tags file. The default is a file calledTAGS in the current directory. If there is no such file, you can create one usingCreate Tags Buffer.

Visit Tags File

Editor Command

: Argument: file
Key sequence: None
: Creates a new tags buffer containing the tag information provided by file. The default is a file calledTAGS in the current directory. The tag information contained in the new buffer is subsequently used for tag searches.