Lightning Completion Manual

(info by John H. Palmieri)

Overview

As you are probably aware, Emacs does various sorts of completion, if you ask it to. For instance, if you hit C-x C-f to find a file, then (once you are in the minibuffer) if you hit the TAB key, Emacs completes the file name if there is a unique completion. Lightning completion offers an improvement to this, an improvement in several ways:

Once lightning completion is initiated, it remains active until a completion is found, or until turned off. If I have three files, `alphabet', `alpo', and `bozo', and I initiate completion on file names, if I hit a, then `alp' is inserted; hitting h would then produce `alphabet', and hitting o would produce `alpo'. Similarly, hitting b at the start, instead of a, would have produced `bozo'. This sort of completion, in which completion is always on--you don't have to keep hitting the SPC or TAB key to complete--is called "dynamic" completion.
Lightning completion takes effect only if Emacs is idle for a length of time specified by the variable lc-complete-idle-time-default, the default value of which is 0.5 seconds. So in the above example, you can type "alph" or "alpha" or "alphab"; then if you wait for half a second, Emacs will automatically complete it for you. This is a new feature of lightning completion; if you are used to the old version, you can set this delay to be 0. If you are a slow typist and you don't want Emacs completing unless you take a very deliberate pause, you can set it to something like 2.
Lightning completion can be initiated anywhere, not just in the minibuffer. If I'm writing email to someone, and I want to include the path name for some file, I type the first few letters of the path, then run the function completing-insert-file-name, and I'm in lightning completion mode. There are similar function calls for completion on buffer names, lisp objects, lisp functions, lisp variables, and the contents of the kill ring.

Some remarks:

Dynamic completion, like any completion, has a nice side-effect: you can use long (and hence descriptive) file names, variable names, function names, whatever, because you hardly ever have to type the whole thing in. So I don't mind that my directory structure in my account is deep and the directories have long names--I can find the file `~/tex/work/papers/hovey-strickland/axiomatic.tex' with 6 keystrokes: one each for "t", "w", "p", "h", and "a", and then RET. (One also gets in the habit of trying to arrange it so that each of one's files in any given directory starts with a different letter.)
If you mainly use lightning completion with file names and if you edit the same files over and over again, you will quickly learn exactly which characters you have to type to find each file. In this case, you might want to set lc-complete-idle-time-default to be close to zero. If you don't want to bother learning this, and if you are worried that lightning completion will make you watch the screen all the time to see what has been completed and what hasn't, then you should set lc-complete-idle-time-default to be a larger number, so that completions only occur after a good pause.
Lightning completion is also one of the main ingredients to Ultra-TeX mode, a major mode for typing TeX documents. Most TeX commands start with a backslash, so in that mode, hitting "\" starts lightning completion on TeX commands. The Ultra-TeX package is available from http://www.math.washington.edu/~palmieri/Emacs/ultratex.html.
This package should be compatible with GNU Emacs 19, GNU Emacs 20, and XEmacs ("should be compatible" means that I've at least tried it out a bit with each one of these, without running into problems). I mostly use GNU Emacs 20, so I know it works there. I expect it to work pretty well with XEmacs, too, but I don't use GNU Emacs 19 anymore, and I don't test this package very vigorously there.
Dynamic completion is an acquired taste. It can be rather off-putting at the start, especially with a short lc-complete-idle-time-default, but once you get used to it, it's just wonderful.

In the following sections, I describe what functions to call to start lightning completion, which keys do what once completion is engaged, how to automate things a bit (e.g., so that find-file automatically uses lightning completion on file names), and how to install all of this.

Completion functions

The file `light.el' defines several functions that do lightning completion:

completing-insert-file-name completes on file names.
completing-insert-buffer-name completes on buffer names.
completing-insert-lisp-object completes on lisp objects.
completing-insert-lisp-function completes on lisp functions.
completing-insert-lisp-variable completes on lisp variables.
completing-insert-kill completes on the contents of the kill ring.
completing-insert-buffer-contents completes on the contents of the current buffer, or with a prefix argument on the contents of any specified buffer. See section Buffer completion.
completing-insert-according-to-mode makes a guess as to what sort of completion it should do; if it can't figure it out, it completes on lisp objects. (This one is mainly useful in the minibuffer.)

(These functions all call the function completing-insert, which I'm too lazy to document. The casual user won't want to call it directly, anyway, and the more serious user can figure it out for herself.)

For example, if I'm typing an info page for lightning completion, and I want to insert the string `completing-insert-kill', I run completing-insert-lisp-function, and then use lightning completion to produce the function name, avoiding typing the whole thing in (and also avoiding typos). In detail: once I start completing-insert-lisp-function, the following happens:

I type the letters c, o, m, p, and Emacs inserts `comp'.
I type l and pause, and Emacs inserts `let' (so I have `complet' so far).
I type i and n and pause, and Emacs inserts `ing-' (so I have `completing-' so far).
I type i and pause, and Emacs inserts `insert' (so I have `completing-insert' so far).
I type - and pause, and Emacs inserts `-' (so I have `completing-insert-' so far).
I type k and pause, and Emacs inserts `kill' (so I have `completing-insert-kill', and completion stops).

There are user customizable variables (in the customization group "lightning-completion") related to these functions. If the variable lc-ctrl-x-c-is-completion is non-nil, then C-x c is the prefix key for these commands. This is one of the few global key bindings available, probably because it is too close to C-x C-c. So be warned, if you use these key bindings, you may occasionally hit C-x C-c instead of C-x c. Anyway, enabling this options provides the following key bindings:

C-x c F: runs completing-insert-file-name.
C-x c b: runs completing-insert-buffer-name.
C-x c o: runs completing-insert-lisp-object.
C-x c f: runs completing-insert-lisp-function.
C-x c v: runs completing-insert-lisp-variable.
C-x c k: runs completing-insert-kill.
C-x c y: runs completing-insert-buffer-contents.
C-x c u: runs completing-insert-according-to-mode.

Note that if one plans on using lightning completion only occasionally, and always from the minibuffer, one might be able to get away with only using the function completing-insert-according-to-mode. There is a customizable variable lc-ctrl-backslash-completes-a-la-mode. If it is non-nil, then C-\ runs completing-insert-according-to-mode.

Key bindings

While in lightning completion, the behavior of each key is modified. Here is a description of what each key does; these functions are loosely based on the behavior of standard completion in Emacs. I have also included examples; for all of the examples, suppose that you are completing on file names, and you have files `albatross', `alpo', `alphabet', and `alphabet-soup'.

There is a customizable variable lc-complete-idle-time-default, the default value of which is 0.5. In lightning completion mode, after this number of seconds of idle time, Emacs tries to complete.

a-z, A-Z, 0-9, etc.: After the delay, you get an error if there is no valid completion based on that character. If there are valid completions, then Emacs inserts the characters in common with all the valid completions. If there is a unique such completion, then Emacs inserts that completion, and completion stops. (Example: if you have `alp' and you hit x, you get an error (but you're still in lightning completion mode); if you hit h, then `habet' is inserted, resulting in `alphabet' (and you're still in lightning completion mode). If you then hit -, then `-soup' is inserted, and completion stops.) When there are no valid completions, the value of the customizable variable lc-clean-up is relevant. If it is nil, then Emacs beeps and warns you that there are no valid completions. If it is non-nil, then in addition, Emacs deletes the offending characters. (Example: if you have `alp' and you hit x, then `x' is inserted. If lc-clean-up is nil, then Emacs beeps. If lc-clean-up is non-nil, then Emacs beeps and deletes the `x'. If you have `al' and you type phx, if lc-clean-up is non-nil, then the `x' is deleted and `abet' is inserted.)
SPC: If you have a valid completion, this key ends lightning completion, keeping the current completion; otherwise, if there is a valid completion based on the current string together with " ", then a space is inserted. Otherwise, SPC acts like the TAB key. (Example: if you have `alp' and you hit h, resulting in `alphabet', then hitting SPC would end completion and do nothing else. If you also have a file `al jolson', then typing `al' followed by SPC produces `al jolson'. Typing `alp' followed by SPC is just like typing `alp' and hitting TAB.)
RET: This key exits lightning completion, regardless of whether you have a valid completion, and inserts a new line or exits the minibuffer, whichever is appropriate. (Example: if you have `alp' and you hit RET would end completion and either insert a new line or exit the minibuffer.) (This is actually an example of the behavior of "Other control characters," described below.)
DEL: This deletes the last thing that was typed along with anything inserted automatically as a result. (Example: if you had `alp' and you hit h, resulting in `alphabet', then hitting DEL would delete `habet'---the characters that were just inserted.)
C-f: Hitting this key repeatedly cycles through the possible completions, in some order or other. (Example: if you have `a', then hitting C-f once will give `albatross'; hitting it again will give `alpo', etc.)
C-b: This works like C-f, but it cycles through the choices in the reverse order.
TAB: Hitting this key completes as far as possible. If there are several choices, then it opens up a new buffer in another window, called *Completions*, in which all of the valid completions are displayed. That buffer is buried once completion ends. (Example, if I have `alp' and I hit TAB, then a new buffer opens up, containing `alpo', `alphabet', and `alphabet-soup'. If I then hit h and then TAB, the *Completions* buffer then displays `alphabet' and `alphabet-soup'.) You can select a completion by clicking on it with mouse-2.
M-v: Hitting this key opens up a new buffer in another window, called *Completions*, just as with the TAB key, but also moves the point to that window. You can then move from one completion choice to another with the arrow keys, and you can select a completion with RET or with mouse-2.
C-c: Hitting this key exits lightning completion mode (useful if you've had enough of this completion nonsense, and you just want to type in the file name yourself; also useful if you want to type in the name of a file that doesn't exist).
C-q: This key quotes the next character (useful if you have a file name containing a control character like C-c or TAB, for instance).
C-h: Hitting this key displays a very brief help message in the minibuffer.
Other control characters: Hitting any other control character (or other non-printing character) has two effects: completion stops, and that character then has its normal effect. So C-g stops completion and beeps, C-e stops completion and moves you to the end of the line, etc.

Many of these keys can be customized (in the customization group lightning-completion-keys).

Lightning completion

Suppose you want to find a file, and you want to use lightning completion on file names. One way to accomplish this is to run find-file (by hitting C-x C-f, say), then once in the minibuffer, either running completing-insert-according-to-mode or completing-insert-file-name (by hitting C-x c F, say, if you have turned on the option lc-ctrl-x-c-is-completion (see section Completion functions)).

Another way to accomplish this is to have lightning completion potentially active whenever you enter the minibuffer, and to specify when "potentially active" should mean "active".

Enabling automatic lightning completion

To use lightning completion automatically in the minibuffer (in various circumstances), you should turn on the option toggle-lightning-completion, either by customization or by setting the variable toggle-lightning-completion to t. Once you've done this, then the variable lightning-completion-list specifies in which contexts lightning completion should be active; the possible contexts are:

file names
commands
lisp functions
lisp variables
lisp objects
user variables
buffer names
info menu items
query-replace: Enable lightning completion on buffer contents when using query-replace. This may not work very well, but I'm working on it...
miscellaneous: Enable lightning completion on everything else.

The easiest way to specify which contexts you want to enable is to customize the variable lightning-completion-list (in the customization group lightning-completion). For each context, you can turn lightning completion on (with the default delay time) or off, or you can also specify a number. If the number is negative, lightning completion is off; otherwise, lightning completion is on, with that number for the delay time for that context. (You can instead use the lightnify function to turn completion on or off, if you prefer. This function is a bit obsolete; in particular, it does not allow you to set a different delay time for each context.)

I suppose I should explain the effect of the "miscellaneous" context. Basically, if in some situation you can complete in the minibuffer by hitting the TAB key, then enabling miscellaneous completion means that lightning completion will be on in that situation. For example, in the news-reader Gnus, if you hit j (to run gnus-group-jump-to-group), then you will be thrown into lightning completion mode, completing on newsgroup names (you will see the message "Completing something...").

Settings for lightning completion

Lightning completion doesn't always work the way you want it, so there are some ways of partially disabling it.

For example, lightning completion doesn't work terribly well with recursive minibuffers, so there is a customizable variable lc-dark-recursive-minibufs. If this is nil, then lightning completion proceeds unhindered. If this has a numerical value N, then lightning completion is disabled when the recursion depth is larger than N. If this has some other non-nil value, then it is treated as if it had value 1 (disabling lightning completion in any recursive situation).

You might also want to, say, enable lightning completion on file names, but disable it for particular commands. To do this, customize the variable lc-dark-commands, which is a list of functions. For example, if you want to disable lightning completion when using insert-file, then add insert-file to this list. If you want two versions of a command like insert-file, only one of which uses lightning completion, then make an alias to insert-file, and disable lightning completion on that function:

(defalias 'insert-file-dark 'insert-file)

and add insert-file-dark to lc-dark-commands. I personally have functions like dired-create-directory, dired-do-symlink, and query-replace-regexp in my list of dark commands.

Installation and customization

Once you've unpacked the archive, you need to make sure that the file `light.el' is in your emacs load-path. Then put

(require 'light)

in your `.emacs' file. Restart emacs; then you can set all of the lightning completion options via customization: run

M-x customize-group lightning-completion

Customizable options

Here is a list of the customizable options for lightning completion, with pointers to relevant sections of this documentation. Use this command:

M-x customize-group lightning-completion

to customize any of these options.

lc-complete-idle-time-default: Default value: 0.5. Effect: when in lightning completion mode, after this much idle time (in seconds) has elapsed, try to complete. See section Overview, See section Key bindings.
toggle-lightning-completion: Default value: off. Effect: toggle whether lightning completion is potentially active in the minibuffer. If on, you should customize lightning-completion-list to specify contexts in which to use lightning completion. See section Enabling automatic lightning completion.
lightning-completion-list: Default value: all off. Effect: toggle lightning completion in, and specify the idle-time for, specific contexts: files, functions, commands, variables, user variables, lisp objects, info menu items, buffer names, query replace, miscellany. See section Enabling automatic lightning completion.
lc-clean-up: Default value: nil. Effect: If on, when there is no valid completion, remove the invalid characters. If off, just give warning when no valid completion. See section Key bindings.
lc-ignored-file-extensions: Default value: equal to completion-ignored-extensions. Description: a list of strings like ".dvi" and ".o"; files ending in these strings are ignored when doing lightning completion on file names. See section Ignoring some files.
lc-dark-commands: Default value: nil. Description: list of commands for which lightning completion is disabled. See section Settings for lightning completion.
lc-dark-recursive-minibufs: Default value: nil. Effect: If a number N, then don't use lightning completion when recursion-depth is bigger than N. If nil, then no restrictions on when to use lightning completion. See section Settings for lightning completion.
lc-override-flag: Default value: nil. Effect: If non-nil, override other local maps when using lightning completion. You may want to turn this on if using outline mode or some other minor mode which uses C-c as prefix. This may not be necessary, though.
lc-keep-key: Default value: SPC. Description: Key to keep current completion in lightning completion mode. See section Key bindings.
lc-del-key: Default value: DEL. Description: Key to delete last completion unit in lightning completion mode. See section Key bindings.
lc-stop-key: Default value: C-c. Description: Key to exit lightning completion mode. See section Key bindings.
lc-quote-key: Default value: C-q. Description: Key to quote next character in lightning completion mode. See section Key bindings.
lc-help-key: Default value: C-h. Description: Help key in lightning completion mode. See section Key bindings.
lc-cycle-key: Default value: C-f. Description: Key to cycle to next completion in lightning completion mode. See section Key bindings.
lc-back-cycle-key: Default value: C-b. Description: Key to cycle to previous completion in lightning completion mode. See section Key bindings.
lc-display-key: Default value: TAB. Description: Key to display all completions in lightning completion mode. See section Key bindings.
lc-ctrl-x-c-is-completion: Default value: nil. Effect: if on, C-x c is the prefix key for the various lightning completion commands. See section Completion functions.
lc-ctrl-backslash-completes-a-la-mode: Default value: nil. Effect: if on, C-\ runs the function completing-insert-according-to-mode. See section Completion functions.

Miscellany

Ignoring some files

If you are using this package to complete on file names, then you should be aware of the lisp variable completion-ignored-extensions. (Lightning completion on file names is based on a completion mode already present in Emacs, and this variable comes from that mode.)

Here is its documentation: "Completion ignores filenames ending in any string in this list. This variable does not affect lists of possible completions, but does affect the commands that actually do completions."

Lightning completion mode uses a similar variable, called lc-ignored-file-extensions, whose default value is equal to completion-ignored-extensions.

I use LaTeX, and when I start with a file `bozo.tex', then LaTeX produces a number of auxiliary files: `bozo.aux', `bozo.dvi', `bozo.log', and possibly `bozo.bbl', `bozo.blg', `bozo.toc', `bozo.lof', etc. When I am editing such a file, I edit the file `bozo.tex' frequently, and I almost never touch the others. So I make sure that lc-ignored-file-extensions contains the strings ".toc" ".log" ".aux" ".lof" ".blg" ".bbl" ".dvi". The easiest way to do this is to customize this variable.

In case you haven't been paying attention: suppose I have added "aux" to lc-ignored-file-extensions, and I want to find the file `bozo.aux', with lightning completion enabled. One way to do this is to type `bozo.aux' quickly enough that emacs is never idle for half a second. Another option is to hit C-c right at the start, to turn off lightning completion; then just type in `bozo.aux' at one's leisure. Another way to do this is to use lightning completion to get `bozo.tex' and ending completion there (if this is the only file that starts `bozo' that doesn't end in an ignored extension, completion will end automatically at this point; otherwise, hit SPC). Then delete `tex' and type in `aux'. There are other ways of doing this, no doubt, but I'll let you figure them out.

Buffer completion

Buffer completion is an example of a use of lightning completion: it lets you complete on reasonably balanced substrings of a buffer. The main function is

(completing-insert-buffer-contents BUF)

where BUF is interactively the current buffer or, with a prefix argument, a buffer specified by the user.

In other words, if I want to repeat something I said somewhere else in this buffer, I call the function completing-insert-buffer-contents. At that point, I enter lightning completion mode on the contents of this buffer. If I want to repeat something I said in a different buffer, I hit C-u and then call completing-insert-buffer-contents. Emacs prompts me for a buffer name, and then does lightning completion on the contents of that other buffer. This is useful if you're too lazy to switch buffers, find the material you want to copy, mark it, kill it, and yank it.

The `dabbrev' package (included as part of the standard GNU Emacs distribution) does some similar things, so you might want to look at that, too. I won't advocate the use of one package over the other--I think each has its uses.

HTML mode completion

Here is another example of how to use lightning completion: you can automatically complete on HTML tags when in html mode. I have the following lines in my `.emacs' file. The first line binds the < key to the function html-lightning-tag (you could use a different key, if you wanted, but since HTML tags all start with this character, it seems to make sense). The next lines define this function--it does lightning completion on HTML tags. And the remaining lines (starting with `(defvar html-light-alist') define the list of HTML tags on which to complete. A typical line is `("<h3></h3>" -5)'; the first entry is the tag, and the second entry is the number of characters from the end by which the point should be offset (i.e., Emacs inserts the string `"<h3></h3>"' and then moves forward -5 characters). (This whole business is intended to be used with the version of html-mode that is contained in the file `sgml-mode.el', part of (for example) the standard GNU Emacs distribution.

(define-key html-mode-map "<" 'html-lightning-tag)

(defun html-lightning-tag nil
  "Lightning complete control sequence."
  (interactive)
  (insert "<")
  (completing-insert html-light-alist nil 1 'point-adjust-hook
		     "html tags"))

(defvar html-light-alist
  '(
    ("<a href=\"\"></a>" -6)
    ("<h1></h1>" -5)
    ("<h2></h2>" -5)
    ("<h3></h3>" -5)
    ("<h4></h4>" -5)
    ("<h-5></h-5>" -5)
    ("<h6></h6>" -5)
    ("<hr>

" 0)
    ("<!--   -->" -5)    
    ("<img src=\"\" alt=\"\">" -9)
    ("<ol>
<li> 
</ol>" -6)
    ("<ul>
<li> 
</ul>" -6)
    ("<li> " 0)
    ("<dl>
<dt> 
<dd> 
</dl>" -12)
    ("<dt> 
<dd> " -6)
    ("<p>
" 0)
    ("<table>
<tr>
<th> </th>
</tr>
</table>" -20)
    ("<th> </th>" -5)
    ("<tr>
<td> </td>
</tr>" -11)
    ("<td> </td>" -5)
    ("<html>
<head>
<title> </title>
</head>
<body lang=\"EN\">

</body>
</html>" -32)
    ("<address>John H. Palmieri, Department of Mathematics, University
of Washington, palmieri@math.washington.edu</address>
" 0)
    ("<address></address>
" -11)
    ("<cite></cite>" -7)
    ("<kbd></kbd>" -6)
    ("<dfn></dfn>" -6)
    ("<em></em>" -5)
    ("<samp></samp>" -7)
    ("<small></small>" -8)
    ("<strong></strong>" -9)
    ("<sub></sub>" -6)
    ("<sup></sup>" -6)
    ("<tt></tt>" -5)
    ("<var></var>" -6)
    ("<code></code>" -7)
    ("<blockquote>

</blockquote>
" -15)
    ("<math>

</math>
" -9)
    ("<pre>

</pre>
" -8)
    ("<br>

" 0))
  "Alist of html tags for use with lightning completion")