LW-ADD-ONS - Some additions to the LispWorks IDE


 

Abstract

LW-ADD-ONS is a collection of small "enhancements" to the LispWorks IDE that I usually load from my initialization file. Most of this code is intended to make LispWorks behave similar to SLIME and GNU Emacs. The details of what's included are outlined below. (Whether one thinks these are enhancements or rather distractions is of course a matter of taste.)

The code has been used and tested on LispWorks for Windows mostly (I don't use the IDE on Linux), but I hear there are also some Mac hackers using it successfully.. For an overview of which LispWorks releases are supported, see below.

It comes with a BSD-style license so you can basically do with it whatever you want.

The Apropos Dialog

 

Contents

  1. Download and installation
  2. Compatibility with different LispWorks releases
  3. Overview
    1. Symbol completion
    2. Information about the arguments of a function
    3. Apropos dialog
    4. "Transient mark mode"
    5. Search and replace
    6. Online documentation
    7. ASDF integration
    8. Listener shortcuts
    9. Alternative editor backups
    10. Miscellaneous
  4. The LW-ADD-ONS dictionary
    1. *backup-directory*
    2. *completion-match-function*
    3. *insert-right-parenthesis-if-no-args*
    4. *listener-shortcuts*
    5. *make-backup-filename-function*
    6. *max-completions-to-show*
    7. *max-info-length*
    8. *mop-page*
    9. *product-registry-path*
    10. *show-doc-string-when-showing-arglist*
    11. *swank-loader-pathname*
    12. *translate-asdf-systems*
    13. *use-abbreviated-complete-symbol*
    14. make-backup-filename-using-backup-directory
    15. start-swank-server
  5. Acknowledgements

 

Download and installation

LW-ADD-ONS together with this documentation can be downloaded from http://weitz.de/files/lw-add-ons.tar.gz. The current version is 0.9.0. It depends on my LW-DOC library. (Note that LW-DOC in turn depends on CL-PPCRE and you should have at least version 1.2.12.)

LW-ADD-ONS comes with a system definition for ASDF. It is supposed to be loaded from your init file and a sample init file (called .lispworks) which amongst other things sets up ASDF and loads LW-ADD-ONS is included. See the file README.txt for more detailed instructions. Note that the key bindings which can be found in the sample init file and which are mentioned below won't work if you use LispWorks' Windows editor emulation.

If you want to send patches, please read this first.
 

Compatibility with different LispWorks releases

LW-ADD-ONS was originally (in 2005) conceived and written for LispWorks 4.4.5/4.4.6 (and it will likely not work with older versions). Since then, the fine LispWorks hackers have added several new features to their IDE which rendered some parts of LW-ADD-ONS obsolete. As I usually use the latest LispWorks version, you can expect LW-ADD-ONS to be adapted to it pretty soon after its release. This might include dropping features which are now superseded by capabilities offered by the LispWorks IDE itself.

The newest LispWorks release which is currently supported is 5.1. LW-ADD-ONS 0.8.8 or higher should work with LispWorks 6.0, but this hasn't been extensively tested yet.

Also, support for older LispWorks versions might at some point disappear. Keep your old LW-ADD-ONS tarballs if you plan on sticking with a certain LispWorks release.
 

Overview

Here's an overview of what's currently in LW-ADD-ONS. If you want more details you got to look at the source code which should be reasonably documented.

Symbol completion

Symbol completion is divided into two editor commands. The "outer" command is "Indent And Complete Symbol" which tries to indent the current line and only performs completion if the line hasn't changed. I have bound this command to the TAB key in my init file, so I can use TAB for both indentation and completion.

The "inner" command is "Complete Symbol Without Dialog" which is intended to work more or less like SLIME's slime-complete-symbol* function, i.e. you can type, e.g., m-v-b and it'll be expanded to multiple-value-bind. If there's more than one possible completion, then the command only performs completion up to the longest unambiguous prefix and shows a list of (some of) the possible completions in the echo area. There's no GUI dialog popping up because I think that's distracting.

"Indent And Complete Symbol" calls "Complete Symbol Without Dialog" on LispWorks 4.4.x and 5.0.x. In 5.1, however, the new command "Abbreviated Complete Symbol" was introduced by LispWorks, so now you can decide which function should be used via the special variable *USE-ABBREVIATED-COMPLETE-SYMBOL*.

If it can be determined that you're within a string then "Indent And Complete Symbol" tries pathname completion instead. (This is not perfect, though, as it won't work if the string contains spaces.)

If the symbol which is completed denotes a function without arguments, "Complete Symbol Without Dialog" will automatically add a closing parenthesis. This can be customized through the variable *INSERT-RIGHT-PARENTHESIS-IF-NO-ARGS*.

You can customize the behaviour of "Complete Symbol Without Dialog" by changing the value of the variable *COMPLETION-MATCH-FUNCTION*.

Information about the arguments of a function

The editor command "Insert Space and Show Arglist" which I've bound to the space key inserts a space and shows the argument list of the nearest enclosing operator in the echo area. If *SHOW-DOC-STRING-WHEN-SHOWING-ARGLIST* is true the documentation string of the operator is also shown.

Note that this command is different from the one that's distributed as an example together with LispWorks.

Apropos dialog

There is an Apropos dialog (see picture above) that can be reached via the LispWorks 'Tools' menu or the "Tools Apropos" editor command (bound to C-c C-a). The dialog should be mostly self-explanatory. Note that right-clicking on the results in the multi-column list panel (after selecting one or more items) pops up a menu with various options similar to other IDE tools. Double-clicking an item tries to find the corresponding source code or, failing that, the documentation.

Note that in LispWorks 5.0 a similar tool was introduced.

"Transient mark mode"

The editor tries to emulate GNU Emacs' transient mark mode if you bind the command "Set Mark And Highlight" to C-SPC and/or C-@. This results in the marked region always being highlighted.

Search and replace

The editor commands to find and replace strings are modified in such a way that they only operate on the marked region if there is one. Also, the effects of a "Replace..." command can be undone with a single "Undo" command. (The latter feature comes for free with LispWorks 5.1 and higher.)

In LispWorks 5.0 and earlier, the editor command "Continue Tags Search" and all commands (like, say, "Edit Callers") that make it applicable (see the LispWorks Editor User Guide) push the current position of point onto a definitions stack before they move to a new position. You can walk back through this "history" using the new editor command "Pop Definitions Stack".

Note that in LispWorks 5.1 a new command "Go Back" was introduced, so the code related to the definitions stack is disabled for 5.1 and higher.

Online documentation

The editor command "Meta Documentation" (bound to F5 in the sample init file) tries to find HTML documentation for the symbol at point and immediately shows it using the default web browser. This applies to the HyperSpec, the LispWorks reference manuals, the MOP (see *MOP-PAGE*), and some other useful stuff, e.g. format strings like ~*, reader macros like #x, and loop clauses like loop:until. Finally, HTML documentation for libraries like CL-PPCRE or LW-ADD-ONS itself that have Hyperdoc support will also be found.

If the command is invoked with a prefix argument you are prompted for a symbol and completion is available.

Note that this command is similar although not identical to the undocumented LispWorks command "Function Documentation".

ASDF integration

The LispWorks System Browser showing an ASDF system

If *TRANSLATE-ASDF-SYSTEMS* is set to a true value then ASDF system definitions are automatically converted to Common Defsystem definitions whenever you load or compile an ASDF system.

Note that ASDF is a lot more flexible than Common Defsystem and there's no hope to convert every conceivable ASDF system to an equivalent Common Defsystem system. The conversion is mainly intended to enable you to browse ASDF systems from the LispWorks IDE and use editor commands like "System Search" and "System Query Replace". It seems to work in practice for a lot of open source ASDF systems that can be used with LispWorks.

Listener shortcuts

Similar to SLIME's slime-handle-repl-shortcut you can press , (comma, for "Maybe Invoke Listener Shortcut") in the listener and then choose from a couple of shortcuts (see *LISTENER-SHORTCUTS*) to perform administrative tasks like loading a system via ASDF or changing the current directory.

Type F1 when prompted for a shortcut to see a list of what's available. Currently there are shortcuts for "Load ASDF System" (l), "Test ASDF System" (t), "Compile ASDF System" (c), "Change Package" (p), "Change Directory" (cd), "Show Directory" (pwd), and "Quit" (q or s) - see the documentation strings of these commands for details.

Alternative editor backups

LW-ADD-ONS can alter the way the IDE editor creates pathnames for backups. This might come in handy if you don't want your code directories to be cluttered with files like foo.lisp~. Read about *MAKE-BACKUP-FILENAME-FUNCTION*, MAKE-BACKUP-FILENAME-USING-BACKUP-DIRECTORY, and *BACKUP-DIRECTORY* and set these to values suiting your needs.

Miscellaneous

The command "Next Ordinary Window" (usually bound to C-x o) is modified to also allow switching from an editor window to a listener window.

The command "Find Alternate File" (usually bound to C-x C-v) is modified such that it checks whether the contents of the buffer are consistent with the file on disk. Also, it'll provide the full pathname of the current buffer as the default when prompting.

The command "Indent And Complete Symbol" includes a workaround to make sure that the start of a top-level form will always be indented to the beginning of a line. LispWorks usually doesn't do that.

The commands "Evaluate Last Form And Inspect" (C-c i) and "Evaluate Last Form And Describe" (C-c d) are like "Evaluate Last Form" but open the result in an IDE inspector or describe it in a help window respectively.

The command "Untrace All" executes (untrace), the command "Toggle Trace" (C-c C-t) traces or untraces a function depending on its current state.

The included initialization file makes sure you start with an editor and (if you use the MDI interface) tiles the windows vertically.

A DDE Server as described in the LispWorks Knowledgebase is set up so you can open Lisp source files by double-clicking them. You have to configure Windows Explorer to use this facility, of course.

The function keys F11 and F12 are bound to commands that switch to an editor or a listener respectively (and create these tools if necessary).


 

The LW-ADD-ONS dictionary

LW-ADD-ONS exports the following symbols:


[Special variable]
*backup-directory*


The directory where backups are stored if the value of *MAKE-BACKUP-FILENAME-FUNCTION* designates the function MAKE-BACKUP-FILENAME-USING-BACKUP-DIRECTORY. It is recommended that you don't use this directory for other purposes.


[Special variable]
*completion-match-function*


The function used by "Complete Symbol Without Dialog" to check possible completions. Should be a designator for a function of two arguments and return true iff the second argument is a possible completion of the first one.


[Special variable]
*insert-right-parenthesis-if-no-args*


Whether "Complete Symbol Without Dialog" should insert a right parenthesis if the function is known to have an empty argument list.


[Special variable]
*listener-shortcuts*


An alist of commands that can be invoked with "Invoke Listener Shortcut", each one preceded by a shortcut.


[Special variable]
*make-backup-filename-function*


If the value of this variable is not NIL (which is the default), then it should be a designator for a function of one argument which accepts a pathname and returns a pathname. LispWork's own EDITOR::MAKE-BACKUP-FILENAME function will be replaced with this one in this case.


[Special variable]
*max-completions-to-show*


The maximum number of possible completions shown in the echo area by "Complete Symbol Without Dialog".


[Special variable]
*max-info-length*


The maximum length (in characters) of a message shown by the function SHOW-INFO (see source code) - unless FULL-LENGTH-P is true.


[Special variable]
*mop-page*


A pathname specifier denoting the location of the dictionary page from the AMOP HTML version. The page is available online at http://www.alu.org/mop/dictionary.html. Used by the "Meta Documentation" command.


[Special variable]
*product-registry-path*


Where LW-ADD-ONS stores persistent information - see PRODUCT-REGISTRY-PATH.


[Special variable]
*show-doc-string-when-showing-arglist*


Whether the editor command "Insert Space And Show Arglist" is supposed to show the documentation string as well.


[Special variable]
*swank-loader-pathname*


A pathname specifier denoting the location of the swank-loader.lisp file. Only needed if one wants to start the Swank server from LispWorks - see function START-SWANK-SERVER.


[Special variable]
*translate-asdf-systems*


Whether ASDF systems should be automatically converted to LispWorks Common Defsystem systems.


[Special variable]
*use-abbreviated-complete-symbol*


Whether "Indent And Complete Symbol" should call "Abbreviated Complete Symbol" (only available in LispWorks 5.1 or higher) instead of "Complete Symbol Without Dialog". The default value is NIL.


[Function]
make-backup-filename-using-backup-directory pathname => pathname'


Creates and returns a backup pathname for pathname (doing a simplified version of what GNU Emacs does if you use backup-directory-alist there). Assumes that *BACKUP-DIRECTORY* denotes a directory. Note that due to the way the backup pathname is constructed it is possible that two different files end up with the same backup filename! If in doubt, look at the source code of this function before you use it.


[Function]
start-swank-server => port


Starts Swank so you can control LispWorks from Emacs via SLIME.

 

Acknowledgements

The inhabitants of the LispWorks mailing list are an invaluable source of information when one writes LispWorks-specific code. Specifically, Jeff Caldwell, Bill Clementson, John DeSoi, Dmitriy Ivanov, Arthur Lemmens, Nick Levine, Sean Ross, Barry Wilkes, and (from LispWorks Ltd.) Dave Fox and Martin Simmons have been very helpful in various ways. Thanks also go to the cool SLIME project which provided inspiration and code to steal.

$Header: /usr/local/cvsrep/lw-add-ons/doc/index.html,v 1.84 2012-08-11 20:44:48 edi Exp $

BACK TO MY HOMEPAGE