Lightning Completion Manual

(info by John H. Palmieri)


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:

Some remarks:

  1. 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.)
  2. 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.
  3. 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
  4. 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.
  5. 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:

(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:

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.

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
lisp functions
lisp variables
lisp objects
user variables
buffer names
info menu items
Enable lightning completion on buffer contents when using query-replace. This may not work very well, but I'm working on it...
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.

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.
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.
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.
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.
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.
Default value: nil. Description: list of commands for which lightning completion is disabled. See section Settings for lightning completion.
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.
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.
Default value: SPC. Description: Key to keep current completion in lightning completion mode. See section Key bindings.
Default value: DEL. Description: Key to delete last completion unit in lightning completion mode. See section Key bindings.
Default value: C-c. Description: Key to exit lightning completion mode. See section Key bindings.
Default value: C-q. Description: Key to quote next character in lightning completion mode. See section Key bindings.
Default value: C-h. Description: Help key in lightning completion mode. See section Key bindings.
Default value: C-f. Description: Key to cycle to next completion in lightning completion mode. See section Key bindings.
Default value: C-b. Description: Key to cycle to previous completion in lightning completion mode. See section Key bindings.
Default value: TAB. Description: Key to display all completions in lightning completion mode. See section Key bindings.
Default value: nil. Effect: if on, C-x c is the prefix key for the various lightning completion commands. See section Completion functions.
Default value: nil. Effect: if on, C-\ runs the function completing-insert-according-to-mode. See section Completion functions.


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."
  (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)

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

</html>" -32)
    ("<address>John H. Palmieri, Department of Mathematics, University
of Washington,</address>
" 0)
" -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)

" -15)

" -9)

" -8)

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

Function Index


  • completing-insert-according-to-mode
  • completing-insert-buffer-contents, completing-insert-buffer-contents
  • completing-insert-buffer-name
  • completing-insert-file-name
  • completing-insert-kill
  • completing-insert-lisp-function
  • completing-insert-lisp-object
  • l

  • lightnify
  • Concept Index


  • Buffer completion
  • c

  • C-\ completes a la mode
  • C-x c is completion
  • Completion functions
  • Completion on buffer contents
  • Completion on HTML tags
  • completion-ignored-extensions
  • Contexts for lightning completion
  • Customizable options
  • Customization
  • d

  • Disabling lightning completion for particular commands
  • e

  • Enabling lightning completion
  • f

  • Functions for completion
  • h

  • HTML tags
  • i

  • Ignored file extensions
  • Ignoring some files
  • Installation
  • k

  • Key bindings
  • Keys in completion
  • l

  • lc-dark-commands
  • lc-ignored-file-extensions
  • Light mode keys
  • Lightning completion and recursive minibuffers
  • Lightning completion functions
  • Lightning completion on buffer contents
  • Lightning completion on HTML tags
  • Lightning completion--contexts
  • Lightning completion--enabling
  • List of customizable options
  • o

  • Options
  • r

  • Recursive minibuffers
  • s

  • Situations for lightning completion
  • t

  • Toggling lightning completion

  • This document was generated on 17 September 1999 using the texi2html translator version 1.51a.