@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 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
-@chapter Abbrevs And Abbrev Expansion
+@chapter Abbrevs and Abbrev Expansion
@cindex abbrev
@cindex abbrev table
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}.
If the value is @code{nil}, abbrevs may be defined, but they are not
expanded automatically.
-This variable automatically becomes local when set in any fashion.
+This variable automatically becomes buffer-local when set in any fashion.
@end defvar
@defvar default-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 hook
+@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 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
replaced with @var{expansion}; point is located at the end of
@var{expansion} when @var{hook} is called.
-The use count of the abbrev is initialized to zero.
+@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
This is the default file name for reading and saving abbrevs.
@end defopt
-@defun quietly-read-abbrev-file filename
+@defun quietly-read-abbrev-file &optional filename
This function reads abbrev definitions from a file named @var{filename},
previously written with @code{write-abbrev-file}. If @var{filename} is
-@code{nil}, the file specified in @code{abbrev-file-name} is used.
-@code{save-abbrevs} is set to @code{t} so that changes will be saved.
+omitted or @code{nil}, the file specified in @code{abbrev-file-name} is
+used. @code{save-abbrevs} is set to @code{t} so that changes will be
+saved.
This function does not display any messages. It returns @code{nil}.
@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 filename
-Save all abbrev definitions, in all abbrev tables, in the file
+@deffn Command write-abbrev-file &optional filename
+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. This function returns @code{nil}.
+define the same abbrevs. If @var{filename} is @code{nil} or omitted,
+@code{abbrev-file-name} is used. This function returns @code{nil}.
@end deffn
@node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs
@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 @code{t} if it did expansion, @code{nil} otherwise.
+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
before any expansion of an abbrev. @xref{Hooks}. Since it is a normal
hook, the hook functions receive no arguments. However, they can find
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. (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 Text mode.
@end defvar
-@defvar c-mode-abbrev-table
-This is the local abbrev table used in C mode.
-@end defvar
-
@defvar lisp-mode-abbrev-table
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