All Manuals > Editor User Guide > 4 Editing Lisp Programs

4.3 Functions and definitions

4.3.1 Movement, marking and specifying indentation

Beginning of Defun Editor Command

Arguments: None
Key sequence: Meta+Ctrl+A

Moves the current point to the beginning of the current top-level form. A positive prefix argument p causes the point to be moved to the beginning of the form p forms back in the buffer.

End of Defun Editor Command

Arguments: None
Key sequence: Meta+Ctrl+E

Moves the current point to the end of the current top-level form. A positive prefix argument p causes the point to be moved to the end of the form p forms forward in the buffer.

Mark Defun Editor Command

Arguments: None
Key sequence: Meta+Ctrl+H

Puts the mark at the end of the current top-level form and the current point at the beginning of the form. The definition thereby becomes the current region. If the current point is initially located between two top-level forms, then the mark and current point are placed around the previous top-level form.

Defindent Editor Command

Arguments: no-of-args
Key sequence: None

Defines the number of arguments of the operator to be specially indented if they fall on a new line. The indent is defined for the operator name, for example defun.

Defindent affects the special argument indentation for all forms with that operator which you subsequently indent.

4.3.2 Definition searching

Definition searching involves taking a name (of a macro, variable, editor command, and so on), and finding the actual definition. This is particularly useful in large systems, where code may exist in a large number of source files.

Definitions are found by using information provided either by LispWorks source recording or by a Tags file. If source records or Tags information have not been made available to LispWorks, then the following commands do not work. To make the information available to LispWorks, set the variable dspec:*active-finders* appropriately. See the LispWorks® User Guide and Reference Manual for details.

Source records are created if the variable *record-source-files* is true when definitions are compiled, evaluated or loaded. See the LispWorks® User Guide and Reference Manual for details.

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 using Create Tags Buffer. GNU Emacs tag files are fully compatible with LispWorks editor tag files.

After a command such as Meta+. (Find Source), if there are multiple definitions repeated use of Meta+, (Continue Tags Search) finds them in turn. If you then wish to revisit a particular definition, try the commands Go Back and Select Go Back.

Find Source Editor Command

Arguments: name
Key sequence: Meta+. name

Tries to find the source code for name. The symbol under the current point is offered as a default value for name. A prefix argument automatically causes this default value to be used.

If the source code for name is found, the file in which it is contained is displayed in a buffer. When there is more than one definition for name, Find Source finds the first definition, and Meta+, (Continue Tags Search) finds subsequent definitions.

Find Source searches for definitions according to the value of dspec:*active-finders*. You can control which source record information is searched, and the order in which these are searched, by setting this variable appropriately. See the LispWorks® User Guide and Reference Manual for details. There is an example setting for this variable in the configuration files supplied.

If dspec:*active-finders* contains the value :tags, Find Source prompts for the name of a tags file, and this is used for the current and subsequent searches.

The found source is displayed according to the value of editor:*source-found-action*. This depends on the buffer with the found definition being in Lisp mode. For information on how to ensure this for particular file types, see 4.1 Automatic entry into Lisp mode.

Find Source For Dspec Editor Command

Arguments: dspec
Key sequence: None

This command is similar to Find Source, but takes a definition spec dspec instead of a name as its argument.

For example, given a generic function foo of one argument, with methods specializing on classes bar and baz:

Find Source for Dspec foo 

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

Find Source for Dspec (method foo (bar))

finds only the definition of the method on bar.

Find Command Definition Editor Command

Arguments: command
Key sequence: None

This command is similar to Find Source, but takes the name of an editor command, and tries to find its source code.

Except in the Personal Edition, you can use this command to find the definitions of the predefined editor commands. See 13.7 Finding source code in the LispWorks® User Guide and Reference Manual for details.

See also: Find Key Definition.

Edit Editor Command Editor Command

Arguments: command
Key sequence: None

This is a synonym for Find Command Definition.

Find Key Definition Editor Command

Arguments: keys
Key sequence: Ctrl+H Ctrl+S keys

The command Find Key Definition prompts for a key sequence keys, and finds the source code definition of the editor command (if any) that is bound to it.

See also: Find Command Definition.

Find Source For Current Package Editor Command

Arguments: None
Key sequence: None

This command is similar to Find Source, but finds the defpackage definition for the package at the current point. If a prefix argument is given, it first prompts for a package name.

View Source Search Editor Command

Arguments: function
Key sequence: None

Shows the results of the latest source search (initiated by Find Source or Find Source for Dspec or Find Command Definition) in the Find Definitions view of the Editor. See the chapter on the Editor tool in the LispWorks IDE User Guide for more information about the Find Definitions view.

List Definitions Editor Command

Arguments: name
Key sequence: None

List the definitions for name. The symbol under the current point is offered as a default value for name. A prefix argument automatically causes this default value to be used.

This command searches for definitions and shows the results in the Find Definitions view of the Editor tool instead of finding the first definition. It does not set up the Meta+, action.

See the chapter on the Editor tool in the LispWorks IDE User Guide for more information about the Find Definitions view.

List Definitions For Dspec Editor Command

Arguments: dspec
Key sequence: None

This command is similar to List Definitions, but takes a definition spec dspec instead of a name as its argument.

This command searches for definitions and shows the results in the Find Definitions view of the Editor tool instead of finding the first definition. This command does not set up the Meta+, action.

See the chapter on the Editor tool in the LispWorks IDE User Guide for more information about the Find Definitions view.

Create Tags Buffer Editor Command

Arguments: 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 called TAGS 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

Key sequence: Meta+?

Tries to find the source code for a name containing a partial or complete match a supplied string by examining the Tags information indicated by the value of dspec:*active-finders*.

The text under the current point is offered as a default value for the string.

If the source code for a match is found, the file in which it is contained is displayed. When there is more than one definition, Find Tag finds the first definition, and Meta+, (Continue Tags Search) finds subsequent definitions.

The found source is displayed according to the value of editor:*source-found-action*.

If there is no tags information indicated by the value of dspec:*active-finders*, Find Tag prompts for the name of a tags file. The default is a file called TAGS in the current directory. If there is no such file, you can create one using Create Tags Buffer. If you want to search a different directory, specify the name of a tags file in that directory.

See the chapter on the DSPEC package in the LispWorks® User Guide and Reference Manual for information on how to use the dspec:*active-finders* variable to control how this command operates. There is an example setting for this variable in the configuration files supplied.

See also Find Source, Find Source for Dspec and Create Tags Buffer.

Tags Search Editor Command

Key sequence: None

Exhaustively searches each file mentioned in the Tags files indicated by the value of dspec:*active-finders* for a supplied string string. Note that this does not merely search for definitions, but for any occurrence of the string.

If string is found, it is displayed in a buffer containing the relevant file. When there is more than one definition, Tags Search finds the first definition, and Meta+, (Continue Tags Search) finds subsequent definitions.

If there is no Tags file on dspec:*active-finders*, Tags Search prompts for the name of a tags file. The default is a file called TAGS in the current directory. If there is no such file, you can create one using Create 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

Arguments: None
Key sequence: Meta+,

Searches for the next match in the current search. This command is only applicable if issued immediately after a Find Source, Find Source for Dspec, Find Command Definition, Edit Callers, Edit Callees, Find Tag or Tags Search command.

Tags Query Replace Editor Command

Key sequence: None

Allows you to replace occurrences of a supplied string target by a second supplied string replacement in each Tags file indicated by the value of dspec:*active-finders*.

Each time target is found, an action must be specified from the keyboard. For details of the possible actions see Query Replace.

If there is no Tags file indicated by dspec:*active-finders*, Tags Query Replace prompts for the name of a tags file. The default is a file called TAGS in the current directory. If there is no such file, you can create one using Create Tags Buffer.

Visit Tags File Editor Command

Key sequence: None

Prompts for a Tags file file and makes the source finding commands use it. This is done by modifying, if necessary, the value of dspec:*active-finders*.

If file is already in dspec:*active-finders*, this command does nothing.

If there are other Tags files indicated then Visit Tags File prompts for whether to add simply add file as the last element of dspec:*active-finders*, or to save the current value of dspec:*active-finders* and start a new list of active finders, setting dspec:*active-finders* to the new value (:internal file). In this case, the previous active finders list can be restored by the command Rotate Active Finders.

If the value :tags appears on the list dspec:*active-finders* then file replaces this value in the list.

If there is no tags information indicated then Visit Tags File simply adds file as the last element of dspec:*active-finders*.

Rotate Active Finders Editor Command

Key sequence: Meta+Ctrl+.

Rotates the active finders history, activating the least recent one. This modifies the value of dspec:*active-finders*.

The active finders history can have length greater than 1 if Visit Tags File started a new list of active finders, or if a buffer associated with a TAGS file on dspec:*active-finders* was killed.

Visit Other Tags File is a synonym for Rotate Active Finders.

4.3.3 Tracing functions

The commands described in this section use the Common Lisp trace facility. Note that you can switch tracing on and off using dspec:tracing-enabled-p - see the LispWorks® User Guide and Reference Manual for details of this.

Trace Function Editor Command

Arguments: function
Key sequence: None

This command traces 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.

Trace Function Inside Definition Editor Command

Arguments: function
Key sequence: None

This command is like Trace Function, except that function is only traced within the definition that contains the cursor.

Untrace Function Editor Command

Arguments: function
Key sequence: None

This command untraces 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.

Trace Definition Editor Command

Arguments: None
Key sequence: None

This command traces the function defined by the current top-level form.

Trace Definition Inside Definition Editor Command

Arguments: None
Key sequence: None

This command is like Trace Definition, except that with a non-nil prefix argument, prompts for a symbol to trace. Also, it prompts for a symbol naming a second function, and traces the first only inside this.

Untrace Definition Editor Command

Arguments: None
Key sequence: None

This command untraces the function defined by the current top-level form.

Untrace All Editor Command

Arguments: None
Key sequence: None

The command Untrace All untraces all traced definitions.

Break Function Editor Command

Arguments: function
Key sequence: None

This command is like Trace Function but the trace is with :break t so that when function is entered, the debugger is entered.

Break Function on Exit Editor Command

Arguments: function
Key sequence: None

This command is like Trace Function but the trace is with :break-on-exit t so that when a called to function exits, the debugger is entered.

Break Definition Editor Command

Arguments: None
Key sequence: None

Like Trace Definition but the definition is traced with :break t.

Break Definition on Exit Editor Command

Arguments: None
Key sequence: None

Like Trace Definition but the definition is traced with :break-on-exit t.

4.3.4 Function callers and callees

The commands described in this section, require that LispWorks is producing cross-referencing information. This information is produced by turning source debugging on while compiling and loading the relevant definitions (see toggle-source-debugging in the LispWorks® User Guide and Reference Manual).

List Callers Editor Command

Arguments: dspec
Key sequence: None

Produces a Function Call Browser window showing those functions that call the definition named by dspec. The name of the current top-level definition is offered as a default value for dspec. A prefix argument automatically causes this default value to be used.

See 7 Dspecs: Tools for Handling Definitions in the LispWorks® User Guide and Reference Manual for a description of dspecs.

List Callees Editor Command

Arguments: dspec
Key sequence: None

Produces a Function Call Browser window showing those functions that are called by the definition named by dspec. The name of the current top-level definition is offered as a default value for dspec. A prefix argument automatically causes this default value to be used.

See 7 Dspecs: Tools for Handling Definitions in the LispWorks® User Guide and Reference Manual for a description of dspecs.

Show Paths To Editor Command

Arguments: dspec
Key sequence: None

Produces a Function Call Browser window showing the callers of the definition named by dspec. The name of the current top-level definition is offered as a default value for dspec. A prefix argument automatically causes this default value to be used.

See 7 Dspecs: Tools for Handling Definitions in the LispWorks® User Guide and Reference Manual for a description of dspecs.

Show Paths From Editor Command

Arguments: dspec
Key sequence: None

Produces a Function Call Browser window showing the function calls from the definition named by dspec. The name of the current top-level definition is offered as a default value for dspec. A prefix argument automatically causes this default value to be used.

See 7 Dspecs: Tools for Handling Definitions in the LispWorks® User Guide and Reference Manual for a description of dspecs.

Edit Callers Editor Command

Arguments: function
Key sequence: None

Produces an Editor window showing the latest definition found for a function that calls function. The name of the current top-level definition is offered as a default value for function. A prefix argument automatically causes this default value to be used. The latest definitions of each of the other functions that call function are available via the Continue Tags Search command.

Edit Callees Editor Command

Arguments: function
Key sequence: None

Produces an Editor window showing the latest definition found for a function called by function. The name of the current top-level definition is offered as a default value for function. A prefix argument automatically causes this default value to be used. The latest definitions of each of the other functions that are called by function are available via the Continue Tags Search command.

4.3.5 Indentation and Completion

Indent Selection or Complete Symbol Editor Command

Arguments: None
Key sequence: Tab
Mode: Lisp

Does Lisp indentation if there is a visible region. Otherwise, it attempts to indent the current line. If the current line is already indented correctly then it attempts to complete the symbol before the current point. See Complete Symbol for more details.

The prefix argument, if supplied, is interpreted as if by Indent Selection or Complete Symbol.

Indent or Complete Symbol Editor Command

Arguments: None
Key sequence: None

Attempts to indent the current line. If the current line is already indented correctly then it attempts to complete the symbol before the current point. See Complete Symbol for more details.

The prefix argument, if supplied, is interpreted as if by Indent or Complete Symbol.

Complete Symbol Editor Command

Arguments: None
Key sequence: Meta+Ctrl+I

Attempts to complete the text before the current point to a symbol. If the string to be completed is not unique, a list of possible completions is displayed.

If the Use in-place completion preference is selected then the completions are displayed in a window which allows most keyboard gestures to be processed as ordinary editor input. This allows speedy reduction of the number of possible completions, while you can select the desired completion with Return, Up and Down.

If a prefix argument is supplied then only symbols which are bound or fbound are offered amongst the possible completions.

Abbreviated Complete Symbol Editor Command

Arguments: None
Key sequence: Meta+I

Attempts to complete the symbol abbreviation before the current point. If the string to be completed is not unique, a list of possible completions is displayed.

A symbol abbreviation is a sequence of words (sequences of alphanumeric characters) separated by connectors (sequences of non-alphanumeric, non-whitespace characters). Each word (connector) is a prefix of the corresponding word (connector) in the expansions. Thus if you complete the symbol abbreviation w-o then with-open-file and with-open-stream are amongst the completions offered, assuming the COMMON-LISP package is visible.

If the Use in-place completion preference is selected then the completions are displayed in a window which allows most keyboard gestures to be processed as ordinary editor input. This allows speedy reduction of the number of possible completions, while you can select the desired completion with Return, Up and Down.

If a prefix argument is supplied then only symbols which are bound or fbound are offered amongst the possible completions.

4.3.6 Miscellaneous

Buffer Changed Definitions Editor Command

Arguments: None
Key sequence: None

Calculates which definitions have been changed in the current buffer during the current LispWorks session, and displays these in the Changed Definitions tab of the Editor tool.

By default the reference point against which changes are calculated is the time when the file was last read into the buffer. A prefix argument equal to the value of the editor variable prefix-argument-default means the reference point is the last evaluation. A prefix argument of 1 means the reference point is the time the buffer was last saved to file.

Note: the most convenient way to use this command is via the Editor tool. Switch it to the Changed Definitions tab, where you can specify the reference point for calculating the changes.

Function Arglist Editor Command

Arguments: function
Key sequence: Meta+= function

Prints the arguments expected by function in the Echo Area. 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.

Example code showing how to use this command to display argument lists automatically is supplied with LispWorks:

(example-edit-file "editor/commands/space-show-arglist")

Function Argument List Editor Command

Arguments: function
Key sequence: Ctrl+Shift+A function

The command Function Argument List is a more sophisticated version of Function Arglist which works on the current form rather than the current symbol.

The symbol at the head of the current form is offered as a default value for function, unless that symbol is a member of the list editor:*find-likely-function-ignores* in which case the second symbol in the form is offered as the default. A prefix argument automatically causes this default value to be used.

Function Arglist Displayer Editor Command

Arguments: None
Key sequence: Ctrl+`

Shows or hides information about the operator in the current form. The command controls display of a special window (displayer) on top of the editor. The displayer shows the operator and its arguments, and tries to highlight the current argument (that is, the argument at the cursor position). If it does not recognize the operator of the current form, it tries the surrounding form, and if that fails it tries a third level of surrounding form.

While the displayer is visible:

Ctrl++
Moves the displayer up.
Ctrl+-
Moves the displayer down.

You can dismiss the displayer by invoking the command again, or by entering Ctrl+G. On Cocoa and Windows it is dismissed automatically when the underlying pane loses the focus.

In the LispWorks IDE you can change the style of the highlighting by Preferences... > Environment > Styles > Colors and Attributes > Arglist Highlight.

Additionally, while the displayer is visible:

Ctrl+/
Controls whether the documentation string of the operator is also shown.

Lastly, if passed a prefix argument, for example by typing Ctrl+U Ctrl+` then it displays the operator and its arguments, with highlight, in the Echo Area, rather than a displayer window. This Echo Area display is interface-specific, and implemented only for the Editor and other tools based on the editor.

Describe Class Editor Command

Arguments: class
Key sequence: None

Displays a description of the class named by class in a Class Browser tool. The symbol under the current point is offered as a default value for class. A prefix argument automatically causes this default value to be used.

Describe Generic Function Editor Command

Arguments: function
Key sequence: None

Displays a description of function in a Generic Function Browser tool. 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.

Describe Method Call Editor Command

Arguments: None
Key sequence: None

Displays a Generic Function Browser tool, with a specific method combination shown.

When invoked with a prefix argument p while the cursor is in a defmethod form, it uses the generic function and specializers of the method to choose the method combination.

Otherwise, it prompts for the generic function name and the list of specializers, which can be class names or lists of the form (eql object) where object is not evaluated.

Describe System Editor Command

Arguments: system
Key sequence: None

Displays a description of the defsystem-defined system named by system. The symbol under the current point is offered as a default value for system. A prefix argument automatically causes this default value to be used.


Editor User Guide (Unix version) - 01 Dec 2021 19:35:19