1   Limp: When You Need More Than Just A Lisp

1.4.1.1   Configuration

Limp uses a Perl script, limp/bin/limp-hyperspec.pl, for invoking a browser with the documentation. I use Opera (www.opera.com), so Limp comes comes pre-configured to use it. I've done some testing with Lynx and Netscape, so uncomment those lines to try those browsers. I haven't gotten Konqueror to work to my satisfaction; if you do, please drop me an e-mail.

There are a few configuration parameters you can set in the file to modify the default browser and such.

$BASE

Where you keep your copy of the HyperSpec. Defaults to /usr/share/doc/hyperspec.

$browser_name

The name of your browser, assumed findable via your $PATH. Defaults to "opera".

$external

Will your browser open a new window (e.g. set to 0 to use lynx). Defaults to 1.

@browser_args

Array of string arguments to your browser. Opera's "new-page" argument to openURL gives each set of HyperSpec search results a new page. Other browsers may have analogous flags, and similar behavior.

limp-hyperspec.pl replaces %s in @browser_args with the URL to be opened. See the Opera configuration for an example.

$READLINE_ON_BROWSER_START

Whether to make you press enter when it starts a browser for the first time. Defaults to 0 (i.e. no).

The script requires you to have a local copy of the HyperSpec. It searches $BASE/Front/X_Perm_*.htm to find the symbols you want it to look for. You can find a tarball of the CLHS at http://www.xanalys.com. If you use Debian or a derivative, such as Ubuntu, apt-get install hyperspec will put the HyperSpec in /usr/share/doc/hyperspec. limp-hyperspec.pl looks for it there, by default.

1.4.2.1   Name Completion

Limp can complete the names of symbols. They tend to be rather long, so it's a useful thing.

First, type this in Vim...

Then, hitting ^N (Ctrl-N) will expand least- into least-negative-long-float first, then (with another ^N) least-positive-long-float, then least-negative-short-float, and so on.

1.4.2.2   Name Expansion

There's a convention to talk about dashed names by abbreviating them into the first letter of each word, e.g.:

First, type this in Vim...

Then, hitting ^N^N (Ctrl-N twice) will expand the p-n to package-name. ^N again will replace package-name with pathname-name, and ^N yet again will replace that with pprint-newline. See Vim help for complete, compl-generic, and i_CTRL-X_CTRL-T. Also, see below for notes on this facility.

1.4.2.3   Notes

• Due to the way the Vim thesaurus works, you have to press ^N (Ctrl-N) twice to get the first replacement for abbreviations like w-a => with-accessors, but only once after that. For Vim to know to expand w-a into with-accessors, I have to include w-a in the thesaurus file, so w-a expands first into just w-a, then with-accessors. See the lisp-thesaurus file and "help i_CTRL-X_CTRL-T".
• For the multi-word symbols beginning with * and & (e.g. &allow-other-keys), you can expand on an abbreviation with or without the leading special character (e.g. a-o-k and &a-o-k both expand into &allow-other-keys (if you've set iskeyword correctly -- see above)).
• lisp-thesaurus sorts keywords by length, and then alphabetically. This mostly matters when expanding ambiguous abbreviations for multi-word symbols. E.g., c-i expands into char-int, then count-if (which both have eight characters), then clear-input (which comes before count-if alphabetically, but has eleven characters).
• I generated lisp-thesaurus from the HyperSpec with make-lisp-thes.pl. Figuring it out is left as an exercise to the reader.

Finally, you should install SuperTab and and use that instead of the default keys used for completion!

1.4.3.1   GVim notes

The default behaviour when running gvim is to open an xterm. There are two flags you can adjust:

b:listener_always_open_window

Open a separate xterm even if running console vim

b:listener_keep_open

Open the xterm in the background. Will not prevent you from pressing F12 multiple times (and thus open many xterms).

1.4.4.1   Listener

This is a regular screen session. Escape is <Ctrl-z>, and <F12> is mapped to detach (<Ctrl-z> d).

1.4.4.2   Lisp Interaction

For sending code to a Lisp.

• \ec: (Evaluate Current): Evaluate the current form
• \et: (Evaluate current Top level form): Evaluate the currrent form to the top level
• \ex: (Evaluate eXpression): Prompt for arbitrary expression to evaluate
• \eb/ec/et: (Evaluate currently selected Block): Evaluate the currently visual block
• \lf: (Load File): Load the current file in Lisp
• \la: (Load Any file): Load any version (.lisp, .fasl, ...) of this file
• \cf: (Compile File): Compile the current file
• \cl: (Compile and Load): Compile current file and load
• \ar: (Abort Reset): Send ABORT to Lisp
• \ai :(Abort Interrupt): Send C-c to Lisp

1.4.4.3   S-Exp Manipulation

Source transformation.

• \mt: (Mark Top): Mark the current form to the top level
• \fc: (Format Current): Reindent/format current form
• \ft: (Format current Top level form): Reindent/format current form to the top level
• \sw: (S-exp Wrap): Wrap the current form inside another list
• \sp: (S-exp Peel): Peel off a list around the current s-exp
• \sc :(S-exp Comment top): Comment top form
• \sC :(S-exp comment Current): Comment current form
• (, ): Go to previous/next s-exp
• {, }: Transpose current s-exp backward/forward (Experimental! Works only for easy cases.)

1.4.4.4   Limp

Vim interaction.

• \gt: (Goto Test): Goto the test buffer
• \gs: (Goto Scratch): Goto the scratch buffer (where the latest evaluated form is)
• \gl: (Goto Last): Goto the last buffer
• \tc: (Test Current): Send current form to test buffer
• \tt: (Test Top): Send top-level form to test buffer

1.4.4.5   Documentation

Looks things up in the HyperSpec, by opening a browser pointing to a local copy of the HyperSpec.

• \hd: (Help Describe): Describe the current symbol in the Lisp listener
• \he: (Help Exact): Lookup exact symbol
• \hp: (Help Prefix): Lookup symbol as prefix
• \hs: (Help Prefix): Lookup symbol as suffix
• \hg: (Help Grep): Lookup symbol by greping through all symbols
• \hi: (Help Index): Go the the index page of the first letter of the current word. E.g., if you have the cursor on "member" and type hi, takes you to the Permuted Symbol Index (M) page.
• \hI: (Help Index page): Takes you to the Alphabetical Symbol Index & Permuted Symbol Index page.

Moreover, K works as expected, doing an exact matching.

1.4.4.6   Brackets

When typing an opening bracket, paren or double-quote, it automatically adds the closing bracket. You can now either type the closing symbol yourself or skip it altogether. Backspacing over it removes the pair.

1.4.4.7   OS X Notes

Depending on your keyboard preferences, you might have to press Cmd-(Shift-)F12. Also, Ctrl-F12 seems to be chomped by the system, so you'll have to change vim/limp.vim to use something else than <C-F12> for disconnect. (Or, you can simply quit Vim; that'll have the same effect.)

Also, if Vim doesn't say you're connected after booting Lisp, you might have to set the proper location to SBCL/SBCL_HOME in bin/lisp.sh.

1.4.4.8   Useful Vim Commands

Vim comes with support for a few useful things out-of-the-box. You should try these out:

[<CTRL-I>

Jump to the definition of the word under the cursor

[I

Display all lines containing the word under the cursor.

Exuberant Ctags works perfectly well for Lisp source code, so you can use the tag system to navigate in your Lisp source code. For non-US keyboards, the default keybinding can be impossible to type in. Here's a better mapping, <Ctrl-Space> (... which generates C-@):

map <C-@> <C-]>