@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1999
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1999, 2002, 2003, 2004,
+@c 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/abbrevs
@node Abbrevs, Processes, Syntax Tables, Top
abbrev table. Normally both are used.
An abbrev table is represented as an obarray containing a symbol for
-each abbreviation. The symbol's name is the abbreviation; its value is
-the expansion; its function definition is the hook function to do the
-expansion (@pxref{Defining Abbrevs}); its property list cell contains
-the use count, the number of times the abbreviation has been expanded.
-Because these symbols are not interned in the usual obarray, they will
-never appear as the result of reading a Lisp expression; in fact,
-normally they are never used except by the code that handles abbrevs.
-Therefore, it is safe to use them in an extremely nonstandard way.
-@xref{Creating Symbols}.
+each abbreviation. The symbol's name is the abbreviation; its value
+is the expansion; its function definition is the hook function to do
+the expansion (@pxref{Defining Abbrevs}); its property list cell
+typically contains the use count, the number of times the abbreviation
+has been expanded. Alternatively, the use count is on the
+@code{count} property and the system-abbrev flag is on the
+@code{system-type} property. Abbrevs with a non-@code{nil}
+@code{system-type} property are called ``system'' abbrevs. They are
+usually defined by modes or packages, instead of by the user, and are
+treated specially in certain respects.
+
+Because the symbols used for abbrevs are not interned in the usual
+obarray, they will never appear as the result of reading a Lisp
+expression; in fact, normally they are never used except by the code
+that handles abbrevs. Therefore, it is safe to use them in an
+extremely nonstandard way. @xref{Creating Symbols}.
For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev
Mode, emacs, The GNU Emacs Manual}.
@node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs
@comment node-name, next, previous, up
-@section Setting Up Abbrev Mode
+@section Setting Up Abbrev Mode
Abbrev mode is a minor mode controlled by the value of the variable
@code{abbrev-mode}.
@defun clear-abbrev-table table
This function undefines all the abbrevs in abbrev table @var{table},
-leaving it empty. The function returns @code{nil}.
+leaving it empty. It always returns @code{nil}.
+@end defun
+
+@defun copy-abbrev-table table
+This function returns a copy of abbrev table @var{table}---a new
+abbrev table that contains the same abbrev definitions. The only
+difference between @var{table} and the returned copy is that this
+function sets the property lists of all copied abbrevs to 0.
@end defun
@defun define-abbrev-table tabname definitions
-This function defines @var{tabname} (a symbol) as an abbrev table name,
-i.e., as a variable whose value is an abbrev table. It defines abbrevs
-in the table according to @var{definitions}, a list of elements of the
-form @code{(@var{abbrevname} @var{expansion} @var{hook}
-@var{usecount})}. The return value is always @code{nil}.
+This function defines @var{tabname} (a symbol) as an abbrev table
+name, i.e., as a variable whose value is an abbrev table. It defines
+abbrevs in the table according to @var{definitions}, a list of
+elements of the form @code{(@var{abbrevname} @var{expansion}
+@var{hook} @var{usecount} @var{system-flag})}. If an element of
+@var{definitions} has length less than five, omitted elements default
+to @code{nil}. A value of @code{nil} for @var{usecount} is equivalent
+to zero. The return value is always @code{nil}.
+
+If this function is called more than once for the same @var{tabname},
+subsequent calls add the definitions in @var{definitions} to
+@var{tabname}, rather than overriding the entire original contents.
+(A subsequent call only overrides abbrevs explicitly redefined or
+undefined in @var{definitions}.)
@end defun
@defvar abbrev-table-name-list
abbrev table. The return value is always @code{nil}.
If @var{human} is non-@code{nil}, the description is human-oriented.
-Otherwise the description is a Lisp expression---a call to
-@code{define-abbrev-table} that would define @var{name} exactly as it
-is currently defined.
+System abbrevs are listed and identified as such. Otherwise the
+description is a Lisp expression---a call to @code{define-abbrev-table}
+that would define @var{name} as it is currently defined, but without
+the system abbrevs. (The mode or package using @var{name} is supposed
+to add these to @var{name} separately.)
@end defun
@node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs
@comment node-name, next, previous, up
@section Defining Abbrevs
+ @code{define-abbrev} is the low-level basic function for defining an
+abbrev in a specified abbrev table. When major modes predefine
+standard abbrevs, they should call @code{define-abbrev} and specify
+@code{t} for @var{system-flag}.
- These functions define an abbrev in a specified abbrev table.
-@code{define-abbrev} is the low-level basic function, while
-@code{add-abbrev} is used by commands that ask for information from the
-user.
-
-@defun add-abbrev table type arg
-This function adds an abbreviation to abbrev table @var{table} based on
-information from the user. The argument @var{type} is a string
-describing in English the kind of abbrev this will be (typically,
-@code{"global"} or @code{"mode-specific"}); this is used in prompting
-the user. The argument @var{arg} is the number of words in the
-expansion.
-
-The return value is the symbol that internally represents the new
-abbrev, or @code{nil} if the user declines to confirm redefining an
-existing abbrev.
-@end defun
-
-@defun define-abbrev table name expansion &optional hook count
+@defun define-abbrev table name expansion &optional hook count system-flag
This function defines an abbrev named @var{name}, in @var{table}, to
-expand to @var{expansion} and call @var{hook}. The value of
-@var{count}, if specified, initializes the abbrev's usage-count. If
-@var{count} is not specified or @code{nil}, the use count is initialized
-to zero. The return value is a symbol that represents the abbrev inside
-Emacs; its name is @var{name}.
+expand to @var{expansion} and call @var{hook}. The return value is
+@var{name}.
+
+The value of @var{count}, if specified, initializes the abbrev's
+usage-count. If @var{count} is not specified or @code{nil}, the use
+count is initialized to zero.
The argument @var{name} should be a string. The argument
@var{expansion} is normally the desired expansion (a string), or
non-@code{nil}, then it is called with no arguments after the abbrev is
replaced with @var{expansion}; point is located at the end of
@var{expansion} when @var{hook} is called.
+
+@cindex @code{no-self-insert} property
+If @var{hook} is a non-@code{nil} symbol whose @code{no-self-insert}
+property is non-@code{nil}, @var{hook} can explicitly control whether
+to insert the self-inserting input character that triggered the
+expansion. If @var{hook} returns non-@code{nil} in this case, that
+inhibits insertion of the character. By contrast, if @var{hook}
+returns @code{nil}, @code{expand-abbrev} also returns @code{nil}, as
+if expansion had not really occurred.
+
+If @var{system-flag} is non-@code{nil}, that marks the abbrev as a
+``system'' abbrev with the @code{system-type} property.
+
+Normally the function @code{define-abbrev} sets the variable
+@code{abbrevs-changed} to @code{t}, if it actually changes the abbrev.
+(This is so that some commands will offer to save the abbrevs.) It
+does not do this for a ``system'' abbrev, since those won't be saved
+anyway.
@end defun
@defopt only-global-abbrevs
@end defun
@defopt save-abbrevs
-A non-@code{nil} value for @code{save-abbrev} means that Emacs should
-save abbrevs when files are saved. @code{abbrev-file-name} specifies
-the file to save the abbrevs in.
+A non-@code{nil} value for @code{save-abbrevs} means that Emacs should
+offer the user to save abbrevs when files are saved. If the value is
+@code{silently}, Emacs saves the abbrevs without asking the user.
+@code{abbrev-file-name} specifies the file to save the abbrevs in.
@end defopt
@defvar abbrevs-changed
-This variable is set non-@code{nil} by defining or altering any
-abbrevs. This serves as a flag for various Emacs commands to offer to
-save your abbrevs.
+This variable is set non-@code{nil} by defining or altering any
+abbrevs (except ``system'' abbrevs). This serves as a flag for
+various Emacs commands to offer to save your abbrevs.
@end defvar
@deffn Command write-abbrev-file &optional filename
-Save all abbrev definitions, in all abbrev tables, in the file
+Save all abbrev definitions (except ``system'' abbrevs), for all abbrev
+tables listed in @code{abbrev-table-name-list}, in the file
@var{filename}, in the form of a Lisp program that when loaded will
define the same abbrevs. If @var{filename} is @code{nil} or omitted,
@code{abbrev-file-name} is used. This function returns @code{nil}.
@defun abbrev-expansion abbrev &optional table
This function returns the string that @var{abbrev} would expand into (as
-defined by the abbrev tables used for the current buffer). The optional
-argument @var{table} specifies the abbrev table to use, as in
-@code{abbrev-symbol}.
+defined by the abbrev tables used for the current buffer). If
+@var{abbrev} is not a valid abbrev, the function returns @code{nil}.
+The optional argument @var{table} specifies the abbrev table to use,
+as in @code{abbrev-symbol}.
@end defun
@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 which 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.
@end deffn
@deffn Command abbrev-prefix-mark &optional arg
-Mark current point as the beginning of an abbrev. The next call to
-@code{expand-abbrev} will use the text from here to point (where it is
-then) as the abbrev to expand, rather than using the previous word as
-usual.
+This command marks the current location of point as the beginning of
+an abbrev. The next call to @code{expand-abbrev} will use the text
+from here to point (where it is then) as the abbrev to expand, rather
+than using the previous word as usual.
+
+First, this command expands any abbrev before point, unless @var{arg}
+is non-@code{nil}. (Interactively, @var{arg} is the prefix argument.)
+Then it inserts a hyphen before point, to indicate the start of the
+next abbrev to be expanded. The actual expansion removes the hyphen.
@end deffn
@defopt abbrev-all-caps
@end defopt
@defvar abbrev-start-location
-This is the buffer position for @code{expand-abbrev} to use as the start
-of the next abbrev to be expanded. (@code{nil} means use the word
-before point instead.) @code{abbrev-start-location} is set to
+The value of this variable is a buffer position (an integer or a marker)
+for @code{expand-abbrev} to use as the start of the next abbrev to be
+expanded. The value can also be @code{nil}, which means to use the
+word before point instead. @code{abbrev-start-location} is set to
@code{nil} each time @code{expand-abbrev} is called. This variable is
also set by @code{abbrev-prefix-mark}.
@end defvar
the abbrev to be expanded by looking in the buffer before point.
Running the hook is the first thing that @code{expand-abbrev} does, and
so a hook function can be used to change the current abbrev table before
-abbrev lookup happens.
+abbrev lookup happens. (Although you have to do this carefully. See
+the example below.)
@end defvar
The following sample code shows a simple use of
-@code{pre-abbrev-expand-hook}. If the user terminates an abbrev with a
-punctuation character, the hook function asks for confirmation. Thus,
-this hook allows the user to decide whether to expand the abbrev, and
-aborts expansion if it is not confirmed.
+@code{pre-abbrev-expand-hook}. 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. Then you can put the following code
+in your @file{.emacs} file. @xref{Standard Abbrev Tables}, for the
+definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}.
@smallexample
-(add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
-
-;; @r{This is the function invoked by @code{pre-abbrev-expand-hook}.}
-
-;; @r{If the user terminated the abbrev with a space, the function does}
-;; @r{nothing (that is, it returns so that the abbrev can expand). If the}
-;; @r{user entered some other character, this function asks whether}
-;; @r{expansion should continue.}
-
-;; @r{If the user answers the prompt with @kbd{y}, the function returns}
-;; @r{@code{nil} (because of the @code{not} function), but that is}
-;; @r{acceptable; the return value has no effect on expansion.}
-
-(defun query-if-not-space ()
- (if (/= ?\ (preceding-char))
- (if (not (y-or-n-p "Do you want to expand this abbrev? "))
- (error "Not expanding this abbrev"))))
+(defun foo-mode-pre-abbrev-expand ()
+ (when (save-excursion (forward-line 0) (eq (char-after) ?#))
+ (let ((local-abbrev-table text-mode-abbrev-table)
+ ;; Avoid infinite loop.
+ (pre-abbrev-expand-hook nil))
+ (expand-abbrev))
+ ;; We have already called `expand-abbrev' in this hook.
+ ;; Hence we want the "actual" call following this hook to be a no-op.
+ (setq abbrev-start-location (point-max)
+ abbrev-start-location-buffer (current-buffer))))
+
+(add-hook 'foo-mode-hook
+ #'(lambda ()
+ (add-hook 'pre-abbrev-expand-hook
+ 'foo-mode-pre-abbrev-expand
+ nil t)))
@end smallexample
+Note that @code{foo-mode-pre-abbrev-expand} just returns @code{nil}
+without doing anything for lines not starting with @samp{#}. Hence
+abbrevs expand normally using @code{foo-mode-abbrev-table} as local
+abbrev table for such lines.
+
@node Standard Abbrev Tables, , Abbrev Expansion, Abbrevs
@comment node-name, next, previous, up
@section Standard Abbrev Tables
This is the local abbrev table used in Lisp mode and Emacs Lisp mode.
@end defvar
+@ignore
+ arch-tag: 5ffdbe08-2cd4-48ec-a5a8-080f95756eec
+@end ignore