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:
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.
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.
lc-complete-idle-time-defaultto 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-defaultto be a larger number, so that completions only occur after a good pause.
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
uses lightning completion on file names), and how to install all of
The file `light.el' defines several functions that do lightning completion:
completing-insert-file-namecompletes on file names.
completing-insert-buffer-namecompletes on buffer names.
completing-insert-lisp-objectcompletes on lisp objects.
completing-insert-lisp-functioncompletes on lisp functions.
completing-insert-lisp-variablecompletes on lisp variables.
completing-insert-killcompletes on the contents of the kill ring.
completing-insert-buffer-contentscompletes 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-modemakes 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
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
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:
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
If it is non-nil, then C-\ runs
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
the default value of which is 0.5. In lightning completion mode, after
this number of seconds of idle time, Emacs tries to complete.
lc-clean-upis 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-upis nil, then Emacs beeps. If
lc-clean-upis non-nil, then Emacs beeps and deletes the `x'. If you have `al' and you type phx, if
lc-clean-upis non-nil, then the `x' is deleted and `abet' is inserted.)
*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.
*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.
Many of these keys can be customized (in the customization group
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-file-name (by hitting C-x c F, say, if
you have turned on the option
(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".
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
info menu items
query-replace. This may not work very well, but I'm working on it...
The easiest way to specify which contexts you want to enable is to
customize the variable
lightning-completion-list (in the
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
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
You might also want to, say, enable lightning completion on file names,
but disable it for particular commands. To do this, customize the
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)
personally have functions like
query-replace-regexp in my list of
Once you've unpacked the archive, you need to make sure that the file `light.el' is in your emacs load-path. Then put
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
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.
lightning-completion-listto specify contexts in which to use lightning completion. See section Enabling automatic lightning completion.
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.
completing-insert-according-to-mode. See section Completion functions.
If you are using this package to complete on file names, then you should
be aware of the lisp variable
(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
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 is an example of a use of lightning completion: it lets you complete on reasonably balanced substrings of a buffer. The main function is
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
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.
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, firstname.lastname@example.org</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")
This document was generated on 17 September 1999 using the texi2html translator version 1.51a.