Commit e38a5ebe authored by Glenn Morris's avatar Glenn Morris

Doc updates re abbrev-expand-function

* doc/emacs/abbrevs.texi (Expanding Abbrevs): Update re abbrev-expand-function.

* doc/lispref/abbrevs.texi (Abbrev Expansion): Update for expand-abbrev changes.

* doc/lispref/functions.texi (Advising Functions): Standardize menu case.

* lisp/abbrev.el (abbrev-expand-functions, abbrev-expand-function)
(expand-abbrev, abbrev--default-expand): Doc fixes.
parent cf2f54c4
2014-05-27 Glenn Morris <rgm@gnu.org>
* abbrevs.texi (Expanding Abbrevs): Update re abbrev-expand-function.
2014-05-21 Eli Zaretskii <eliz@gnu.org>
* frames.texi (Fonts): Clarify which frames are affected by
......
......@@ -206,8 +206,9 @@ to turn on Abbrev mode first. It may also be useful together with a
special set of abbrev definitions for making several global replacements at
once. This command is effective even if Abbrev mode is not enabled.
Expanding any abbrev runs @code{abbrev-expand-functions}, a special
hook. Functions in this special hook can make arbitrary changes to
The function @code{expand-abbrev} peforms the expansion by calling
the function that @code{abbrev-expand-function} specifies. By
changing this function you can make arbitrary changes to
the abbrev expansion. @xref{Abbrev Expansion,,, elisp, The Emacs Lisp
Reference Manual}.
......
2014-05-27 Glenn Morris <rgm@gnu.org>
* abbrevs.texi (Abbrev Expansion): Update for expand-abbrev changes.
* functions.texi (Advising Functions): Standardize menu case.
2014-05-17 Eli Zaretskii <eliz@gnu.org>
* display.texi (Invisible Text): Clarify the description of
......
......@@ -257,13 +257,16 @@ as in @code{abbrev-symbol}.
@deffn Command expand-abbrev
This command expands the abbrev before point, if any. If point does not
follow an abbrev, this command does nothing. The command returns the
abbrev symbol if it did expansion, @code{nil} otherwise.
If the abbrev symbol has a hook function that is a symbol whose
@code{no-self-insert} property is non-@code{nil}, and if the hook
function returns @code{nil} as its value, then @code{expand-abbrev}
returns @code{nil} even though expansion did occur.
follow an abbrev, this command does nothing. To do the expansion, it
calls the function that is the value of the @code{abbrev-expand-function}
variable, with no arguments, and returns whatever that function does.
The default expansion function returns the abbrev symbol if it did
expansion, and @code{nil} otherwise. If the abbrev symbol has a hook
function that is a symbol whose @code{no-self-insert} property is
non-@code{nil}, and if the hook function returns @code{nil} as its
value, then the default expansion function returns @code{nil},
even though expansion did occur.
@end deffn
@defun abbrev-insert abbrev &optional name start end
......@@ -331,24 +334,21 @@ has already been unexpanded. This contains information left by
@code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command.
@end defvar
@defvar abbrev-expand-functions
This is a wrapper hook (@pxref{Running Hooks}) run around the
@code{expand-abbrev} function. Each function on this hook is called
with a single argument: a function that performs the normal abbrev
expansion. The hook function can hence do anything it wants before
and after performing the expansion. It can also choose not to call
its argument, thus overriding the default behavior; or it may even
call it several times. The function should return the abbrev symbol
if expansion took place.
@defvar abbrev-expand-function
The value of this variable is a function that @code{expand-abbrev}
will call with no arguments to do the expansion. The function can do
anything it wants before and after performing the expansion.
It should return the abbrev symbol if expansion took place.
@end defvar
The following sample code shows a simple use of
@code{abbrev-expand-functions}. It assumes that @code{foo-mode} is a
@code{abbrev-expand-function}. It assumes that @code{foo-mode} is a
mode for editing certain files in which lines that start with @samp{#}
are comments. You want to use Text mode abbrevs for those lines. The
regular local abbrev table, @code{foo-mode-abbrev-table} is
appropriate for all other lines. @xref{Standard Abbrev Tables}, for the
definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}.
@xref{Advising Functions}, for details of @code{add-function}.
@smallexample
(defun foo-mode-abbrev-expand-function (expand)
......@@ -361,9 +361,8 @@ definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}.
(add-hook 'foo-mode-hook
#'(lambda ()
(add-hook 'abbrev-expand-functions
'foo-mode-abbrev-expand-function
nil t)))
(add-function :around (local 'abbrev-expand-function)
#'foo-mode-abbrev-expand-function)))
@end smallexample
@node Standard Abbrev Tables
......
......@@ -1207,10 +1207,10 @@ specify how the two functions are composed, since there are many different
ways to do it. The added function is also called an @emph{advice}.
@menu
* Core Advising Primitives:: Primitives to Manipulate Advices
* Advising Named Functions:: Advising Named Functions
* Advice combinators:: Ways to compose advices
* Porting old advices:: Adapting code using the old defadvice
* Core Advising Primitives:: Primitives to manipulate advice.
* Advising Named Functions:: Advising named functions.
* Advice combinators:: Ways to compose advices.
* Porting old advices:: Adapting code using the old defadvice.
@end menu
@node Core Advising Primitives
......
2014-05-27 Glenn Morris <rgm@gnu.org>
* abbrev.el (abbrev-expand-functions, abbrev-expand-function)
(expand-abbrev, abbrev--default-expand): Doc fixes.
2014-05-26 Paul Eggert <eggert@cs.ucla.edu>
Include sources used to create macuvs.h.
......
......@@ -824,23 +824,28 @@ see `define-abbrev' for details."
value))
(defvar abbrev-expand-functions nil
"Wrapper hook around `expand-abbrev'.")
"Wrapper hook around `abbrev--default-expand'.")
(make-obsolete-variable 'abbrev-expand-functions 'abbrev-expand-function "24.4")
(defvar abbrev-expand-function #'abbrev--default-expand
"Function to perform abbrev expansion.
"Function that `expand-abbrev' uses to perform abbrev expansion.
Takes no argument and should return the abbrev symbol if expansion took place.")
(defun expand-abbrev ()
"Expand the abbrev before point, if there is an abbrev there.
Effective when explicitly called even when `abbrev-mode' is nil.
Returns the abbrev symbol, if expansion took place. (The actual
return value is that of `abbrev-insert'.)"
Before doing anything else, runs `pre-abbrev-expand-hook'.
Calls `abbrev-expand-function' with no argument to do the work,
and returns whatever it does. (This should be the abbrev symbol
if expansion occurred, else nil.)"
(interactive)
(run-hooks 'pre-abbrev-expand-hook)
(funcall abbrev-expand-function))
(defun abbrev--default-expand ()
"Default function to use for `abbrev-expand-function'.
This respects the wrapper hook `abbrev-expand-functions'.
Calls `abbrev-insert' to insert any expansion, and returns what it does."
(with-wrapper-hook abbrev-expand-functions ()
(pcase-let ((`(,sym ,name ,wordstart ,wordend) (abbrev--before-point)))
(when sym
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment