All Manuals > LispWorks IDE User Guide > 12 The Editor

12.13 Using Lisp-specific commands

One of the main benefits of using the built-in editor is the large number of keyboard and menu commands available which can work directly on Lisp code. As well as editing facilities which work intelligently in a buffer containing Lisp code, there are easily-accessible commands which load, evaluate or compile, and run your code in any part of a buffer.

Other tools in the LispWorks IDE are integrated with the Editor. So for example you can find the source code definition of an object being examined in a browser, or set breakpoints in your code, or flag symbols in editor buffers for specific actions such as tracing or lambda list printing.

This section provides an introduction to the Lisp-specific facilities that are available using menu commands. For a full description of the extended editor commands, please refer to the Editor User Guide.

All of the commands described below are available in the Editor's Works > Buffers, Works > Definitions, and Works > Expression menus. They operate on the current buffers, definitions, or expression, the choice of which is affected by the current view.

12.13.1 Lisp mode

Some aspects of the LispWorks editor behave differently depending on which "mode" the buffer is using (see the Editor User Guide for information about editor modes). These include syntax coloring and parenthesis matching. which operate only in Lisp mode and are described in 3.2.3.2 Setting the text style attributes. Also, certain commands such as those for indentation operate specially in Lisp mode.

To make a new buffer suitable for Lisp code, you can use the New Buffer command or the File > New menu item, both of which start the buffer in Lisp mode.

If your Lisp source files are saved with an extension .lisp or .lsp, then the editor will automatically open them in a Lisp mode buffer.

12.13.2 Current buffers, definitions and expression

In the Text view, the current buffer is the currently visible buffer, and the Buffers menu acts on this. The current expression is the symbol over which the cursor is positioned, or the one immediately before the cursor if it is not on a symbol. The current definition is the definition in which that current symbol occurs. For example:

(defun test ()
  (test2))

In the function shown above, if the cursor were placed on the letter "e" of test2, the current expression would be the symbol test2, and the current definition would be test.

In the Buffers view, the current buffer(s) are all the selected buffers. The Definitions and Expression menus are not available.

In the Definitions, Changed Definitions and Find Definitions views, the current definitions are all the selected definitions. The Buffers and Expression menus are not available.

In each view, the Buffers, Definitions and Expression menu commands act on the current buffer(s), definition(s) or expression.

12.13.3 Evaluating code

When you are editing Lisp code, you may want to evaluate part or all of the buffer in order to test the code. The easiest way to do this is using menu commands, although there are keyboard commands which allow you to evaluate Lisp in the Editor as well.

There are three menu commands which allow you to evaluate Lisp in the current buffer.

Choose Works > Buffers > Evaluate to evaluate all the code in the current buffer. If you are in the Buffers view, then this command evaluates the code in all the selected buffers.

Choose Works > Expression > Evaluate Region to evaluate the Lisp code in the current region. You must make sure you have marked a region before choosing this command; see 12.11.1 Marking the region. Whether you use the mouse or keyboard commands to mark a region does not matter. If you have a few Lisp forms that you want to evaluate, but do not want to evaluate the whole buffer, you should use this command.

Choose Works > Definitions > Evaluate or click in the toolbar to evaluate the current definition. In the Text view this is a little like evaluating the marked region, except that only the current definition is evaluated, whereas working with a marked region lets you evaluate several. This command is useful if you have a single function in the current buffer which you want to test without taking the time to evaluate the whole buffer or mark a region.

In the various definitions views, this command evaluates the code for all the selected definitions.

To load the file associated with the current buffer, choose File > Load. To load multiple files associated with buffers, select them in the Buffers view and choose File > Load. If there is not a current buffer, the menu command File > Load... is available, which prompts for a file to load.

12.13.4 Compiling code

You can also compile Lisp code in an editor buffer in much the same way that you can evaluate it. Code can be compiled in memory or to a file.

12.13.4.1 Compiling in memory

Choose Works > Buffers > Compile or click in the toolbar to compile all the code in the current buffer.

Choose Works > Expression > Compile Region to compile the Lisp code in the current region.

Choose Works > Definitions > Compile or click in the toolbar to compile the current definition.

During compilation, the Editor tool temporarily displays compiler output in the Output tab. Once compilation has finished, you can press Space to display the current buffer once again.

Additionally, if any conditions were signalled during the compilation, you can view these in the Compilation Conditions Browser by pressing Return. You can also locate the source code that generated a message via the context menu, as described in 21.1 Interactive compilation messages.

You can review the output at any time by clicking the Output tab of the Editor.

12.13.4.2 Compiling to a file

To compile the file associated with the current buffer, choose File > Compile. To compile multiple files associated with buffers, select them in the Buffers view and choose File > Compile. If there is not a current buffer, the menu command File > Compile... is available, which prompts for a file to compile.

Note: this command calls the Common Lisp function compile-file; it creates the fasl file but does not load it. You can use File > Load to later load the fasl.

To compile a file (or files) and load the resulting fasl file(s) with a single command, choose File > Compile and Load. If there is not a current buffer, the menu command File > Compile and Load... is available.

12.13.5 Argument list information

Press Ctrl+` to show information about the operator in the current form, in a displayer window on top of the Editor. The displayer shows the operator and its arguments, and tries to highlight the argument at the cursor position using the style "Arglist Highlight" .

While the displayer is visible:

12.13.6 Breakpoints

A breakpoint causes execution of Lisp code to stop when it is reached, and the LispWorks IDE displays the stack and the source code in a Stepper Tool. See 25.6 Breakpoints for information about using breakpoints with the Stepper Tool.

A breakpoint can be at the start, function call or return point of a form.

12.13.6.1 Setting breakpoints

To set a breakpoint, for example at the call to + in one of your functions:

  1. Open the file containing the call in an Editor tool.
  2. Ensure the definition is indented. You can use the Lisp mode command Indent Form (Alt+Ctrl+Q in Emacs emulation).
  3. Ensure the definition is compiled.
  4. Position the cursor on the symbol +.
  5. Choose the menu command Works > Expression > Toggle Breakpoint, or click in the Editor toolbar, or run the editor command Toggle Breakpoint. The symbol + is highlighted red indicating that a breakpoint is set.

When the breakpoint is reached, a Stepper tool is invoked, allowing you to step through the code, add further breakpoints, and so on. See 25 The Stepper for more information about the Stepper tool.

12.13.6.2 Editing breakpoints

To edit the Conditional or Printing properties of a breakpoint, choose the menu command Works > Expression > Edit Breakpoints and proceed as described in 25.6.4 Editing breakpoints.

To visit the source code where a breakpoint was set, choose the menu command Works > Expression > Edit Breakpoints, select a breakpoint and press the Goto Source button. This cancels the dialog and then displays the source containing the breakpoint.

12.13.6.3 Removing breakpoints

To remove a breakpoint under the cursor, click in the toolbar. Equivalently choose the menu command Works > Expression > Toggle Breakpoint or run the editor command Toggle Breakpoint.

Where you wish to remove one or more breakpoints without finding them in the source, choose Works > Expression > Edit Breakpoints, select a breakpoint or breakpoints in the Breakpoints list, and click Remove.

12.13.6.4 Reloading code with breakpoints

A message like this:

Retain 1 breakpoint from loaded file...

means that a breakpoint is set in a buffer while you have loaded that buffer's underlying file from disk, for example by menu commands File > Load or File > Compile And Load. Loading the file re-evaluates all of its forms, but the IDE does not have a way to reset the breakpoints in these forms automatically. Therefore it asks you what to do.

Answer Yes to add breakpoints to the newly loaded definitions. Answer No to remove the breakpoints.

12.13.7 Tracing symbols and functions

A wide variety of tracing operations are available in the Works > Buffers, Works > Definitions and Works > Expression menus. The scope of each operation depends on which menu the command is chosen from.

Choose Trace from either the Works > Buffers, Works > Definitions or Works > Expression menus to display a menu of trace commands that you can apply to the current region or expression, or the currently selected buffers or definitions, as appropriate. Note that you can select several items in the buffers and definitions views.

See 3.10 Tracing symbols from tools for full details of the tracing facilities available in the Editor.

12.13.8 Packages

It is important to understand how the current package (that is, the value of the Common Lisp variable *package*) is determined when running Lisp operations such as evaluation or compilation commands in a buffer. Usually it is obvious: most Lisp source files have a single in-package form. The Editor uses the specified package as the current package when you evaluate or compile code in that buffer, or perform some other operation that depends on the current package.

However it is possible for a source file to contain multiple in-package forms, or none at all. In this case, the Editor uses a suitable binding for the current package depending on the location in the buffer, as described below. This means that you do not have to worry about setting the package explicitly before evaluating part of a buffer, and that operations within a buffer use the expected current package.

12.13.8.1 The primary package

Each buffer has a package associated with it, known as the primary package. This is set when the buffer is created, and is displayed in the message area at the bottom of the Editor window. The primary package provides a default, used when the current package cannot be determined by other means.

If the buffer is created by opening a file containing an in-package form, that package is the primary package. If there are multiple in-package forms, the primary package is taken from the first of these forms. If there is no in-package form, the primary package is CL-USER.

You can set the primary package if needed with the editor command Set Buffer Package. See the Editor User Guide for details.

12.13.8.2 The current package for Lisp operations

When evaluating or compiling an entire buffer, the Editor uses in-package forms as they appear in the code. For any code that precedes the first in-package form, or when there is no in-package form, the code is evaluated or compiled in the primary package.

When evaluating or compiling a region of the current buffer (as opposed to all of it), the Editor uses in-package forms as they appear in the region. For any code that precedes the first in-package form of the region, or when there is no in-package form in the region at all, the Editor searches for the previous in-package form in the buffer. If this is found, it determines the current package, otherwise the primary package is used.

When evaluating or compiling a definition, and for operations such as symbol completion at the cursor point, the Editor searches for the previous in-package form in the buffer. If this is found, it determines the current package, otherwise the primary package is used.

12.13.9 Indentation of forms

The Editor provides facilities for indenting your code to help you see its structure. These facilities are available only in Lisp mode. The Emacs key Alt+Ctrl+Q indents the current Lisp form, and the Tab key indents a single line.

You can customize Lisp mode indentation by using the Defindent command, see the Editor User Guide for details.

See 12.13.1 Lisp mode for more information about Lisp mode.

12.13.10 Other facilities

A number of other Lisp-specific facilities are available using the menus in the Editor.

If the current buffer is associated with a file that is part of a system as defined by defsystem, choose File > Browse Parent System to browse the system it is part of in the System Browser. See 26 The System Browser for more information about this tool.

Choose Works > Definitions > Undefine... to remove the current definitions from your Lisp image. Similarly, choose Works > Buffers > Undefine... to remove the definitions in the current buffer or selected buffers. By selecting items in the Buffers view, or the various definitions views, you can control over the definitions which can be removed with one command. Both of these commands prompt you for confirmation with a second chance to modify the list of definitions to remove.

Choose Works > Definitions > Generic Function to describe the current definition in a Generic Function Browser. See 15 The Generic Function Browser for more details.

Standard action commands can be found on the Works > Expression menu, allowing you to perform a number of operations on the current expression. See 3.8 Performing operations on selected objects for full details.

Choose Works > Expression > Arguments to print the lambda list of the current expression in the echo area, if it is a function, generic function or method. This is the same as using the Emacs key command Alt+=, except that the current expression is automatically used.

Choose Works > Expression > Value to display the value of the current expression in the echo area.

Choose Works > Expression > Macroexpand or click in the toolbar to macroexpand the current form. The macroexpansion is printed in the Output tab, in the same way that compilation output is shown. Note how an in-package form containing the current package is printed with the macroexpansion, meaning that you can preform a further macroexpansion. Press Space when the cursor is at the end of the output window to return to the Text tab.

Choose Works > Expression > Walk to recursively macroexpand the current form.


LispWorks IDE User Guide (Windows version) - 01 Dec 2021 19:37:58