Homepage: https://www.gnu.org/software/emacs
Author: Anders Holst
Expand text trying various ways to find its expansion
`hippie-expand' is a single function for a lot of different kinds
of completions and expansions. Called repeatedly it tries all
possible completions in succession.
Which kinds of completions to try, and in which order, is
determined by the contents of `hippie-expand-try-functions-list'.
Much customization of `hippie-expand' can be made by changing the
order of, removing, or inserting new functions in this list.
Given a positive numeric argument, `hippie-expand' jumps directly
ARG functions forward in this list. Given some other argument
(a negative argument or just Ctrl-U) it undoes the tried
completion.
If the variable `hippie-expand-verbose' is non-nil, `hippie-expand'
outputs in a message which try-function in the list that is used
currently (i.e. was used currently and will be tried first the next
time).
The variable `hippie-expand-max-buffers' determines in how many
buffers, apart from the current, to search for expansions in. It
is used by the try-functions named "-all-buffers".
The variable `hippie-expand-ignore-buffers' is a list of regexps
matching buffer names (as strings) or major modes (as atoms) of
buffers that should not be searched by the try-functions named
"-all-buffers".
If set, the variable `hippie-expand-only-buffers' does the opposite
of `hippie-expand-ignore-buffers', in that the search is restricted
to only the kind of buffers listed.
If the variable `hippie-expand-no-restriction' is non-nil, narrowed
buffers are widened before they are searched.
The variable `hippie-expand-dabbrev-skip-space' controls whether
trailing spaces will be included in the abbreviation to search for,
which then gives the same behavior as the original `dabbrev-expand'.
The variable `hippie-expand-dabbrev-as-symbol' controls whether
characters of syntax '_' is considered part of the words to expand
dynamically.
See also the function `make-hippie-expand-function' below.
A short description of the current try-functions in this file:
`try-complete-file-name' : very convenient to have in any buffer,
and not just in the minibuffer or (some) shell-mode. It goes
through all possible completions instead of just completing as
much as is unique.
`try-complete-file-name-partially' : To insert in the list just
before `try-complete-file-name' for those who want first to get
a file name completed only as many characters as is unique.
`try-expand-all-abbrevs' : can be removed if you don't use abbrevs.
Otherwise it looks through all abbrev-tables, starting with
the local followed by the global.
`try-expand-line' : Searches the buffer for an entire line that
begins exactly as the current line. Convenient sometimes, for
example as a substitute for (or complement to) the history
list in shell-like buffers. At other times, only confusing.
`try-expand-line-all-buffers' : Like `try-expand-line' but searches
in all buffers (except the current). (This may be a little
slow, don't use it unless you are really fond of `hippie-expand'.)
`try-expand-list' : Tries to expand the text back to the nearest
open delimiter, to a whole list from the buffer. Convenient for
example when writing Lisp or TeX.
`try-expand-list-all-buffers' : Like `try-expand-list' but searches
in all buffers (except the current).
`try-expand-dabbrev' : works exactly as dabbrev-expand (but of
course in a way compatible with the other try-functions).
`try-expand-dabbrev-all-buffers' : perhaps the most useful of them,
like `dabbrev-expand' but searches all Emacs buffers (except the
current) for matching words. (No, I don't find this one
particularly slow.)
`try-expand-dabbrev-visible': Searches the currently visible parts of
all windows. Can be put before `try-expand-dabbrev-all-buffers' to
first try the expansions you can see.
`try-expand-dabbrev-from-kill': Searches the kill ring for a suitable
completion of the word. Good to have, just in case the word was not
found elsewhere.
`try-expand-whole-kill' : Tries to complete text with a whole entry
from the kill ring. May be good if you don't know how far up in
the kill-ring the required entry is, and don't want to mess with
"Choose Next Paste".
`try-complete-lisp-symbol' : like `elisp-completion-at-point', but goes
through all possibilities instead of completing what is unique.
Might be tedious (usually a lot of possible completions) and
since its function is much like `completion-at-point', which
already has a key of its own, you might want to remove this.
`try-complete-lisp-symbol-partially' : To insert in the list just
before `try-complete-lisp-symbol' for those who first want to get
completion of what is unique in the name.
Not all of the above functions are by default in
`hippie-expand-try-functions-list'. This variable is better set
in ".emacs" to make `hippie-expand' behave maximally convenient
according to personal taste. Also, instead of loading the
variable with all kinds of try-functions above, it might be an
idea to use `make-hippie-expand-function' to construct different
`hippie-expand'-like functions, with different try-lists and bound
to different keys. It is also possible to make
`hippie-expand-try-functions-list' a buffer local variable, and
let it depend on the mode (by setting it in the mode-hooks).
To write new try-functions, consider the following:
Each try-function takes one argument OLD which is nil the first
time the function is called and true in succeeding calls for the
same string to complete. The first time the function has to
extract the string before point to complete, and substitute the
first completion alternative for it. On following calls it has to
substitute the next possible completion for the last tried string.
The try-function is to return t as long as it finds new
possible completions. When there are no more alternatives it has
to restore the text before point to its original contents, and
return nil (don't beep or message or anything).
The try-function can (should) use the following functions:
`he-init-string' : Initializes the text to substitute to the
contents of the region BEGIN to END. Also sets the variable
`he-search-string' to the text to expand.
`he-substitute-string' : substitutes STR into the region
initialized with `he-init-string'. (An optional second argument
TRANS-CASE non-nil, means transfer of case from the abbreviation
to the expansion is ok if that is enabled in the buffer.)
`he-reset-string' : Resets the initialized region to its original
contents.
There is also a variable: `he-tried-table' which is meant to contain
all tried expansions so far. The try-function can check this
variable to see whether an expansion has already been tried
(hint: `he-string-member').
Known bugs
It may happen that some completion suggestion occurs twice, in
spite of the use of `he-tried-table' to prevent that. This is
because different try-functions may try to complete different
lengths of text, and thus put different amounts of the
text in `he-tried-table'. Anyway this seems to occur seldom enough
not to be too disturbing. Also it should NOT be possible for the
opposite situation to occur, that `hippie-expand' misses some
suggestion because it thinks it has already tried it.
Acknowledgment
I want to thank Mikael Djurfeldt in discussions with whom the idea
of this function took form.
I am also grateful to all those who have given me suggestions on
how to improve it, and all those who helped to find and remove bugs.