@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
+@c 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.) 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}.
For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev
Mode, emacs, The GNU Emacs Manual}.
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 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 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} @r{[}@var{system-flag}@r{]})}. The return
+value is always @code{nil}.
@end defun
@defvar abbrev-table-name-list
@defun insert-abbrev-table-description name &optional human
This function inserts before point a description of the abbrev table
named @var{name}. The argument @var{name} is a symbol whose value is an
-abbrev table. The value is always @code{nil}.
+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
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.
+@code{add-abbrev} is used by commands that ask for information from
+the user. When major modes predefine standard abbrevs, they should
+call @code{define-abbrev} and specify @code{t} for @var{system-flag}.
@defun add-abbrev table type arg
This function adds an abbreviation to abbrev table @var{table} based on
existing abbrev.
@end defun
-@defun define-abbrev table name expansion hook
-This function defines an abbrev in @var{table} named @var{name}, to
-expand to @var{expansion}, and call @var{hook}. The return value is an
-uninterned symbol that represents the abbrev inside Emacs; its name is
+@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}.
+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} should be a string, or @code{nil} to undefine the
-abbrev.
+@var{expansion} is normally the desired expansion (a string), or
+@code{nil} to undefine the abbrev. If it is anything but a string or
+@code{nil}, then the abbreviation ``expands'' solely by running
+@var{hook}.
The argument @var{hook} is a function or @code{nil}. If @var{hook} is
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.
-The use count of the abbrev is initialized to zero.
+If @var{hook} is a non-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
@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
-@var{filename}, in the form of a Lisp program that when loaded will
-define the same abbrevs. This function returns @code{nil}.
+@deffn Command write-abbrev-file &optional filename
+Save all abbrev definitions (except ``system'' abbrevs), in all abbrev
+tables, 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}.
@end deffn
@node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs
@comment node-name, next, previous, up
@section Looking Up and Expanding Abbreviations
- Abbrevs are usually expanded by commands for interactive use,
+ Abbrevs are usually expanded by certain interactive commands,
including @code{self-insert-command}. This section describes the
-subroutines used in writing such functions, as well as the variables
-they use for communication.
+subroutines used in writing such commands, as well as the variables they
+use for communication.
@defun abbrev-symbol abbrev &optional table
This function returns the symbol representing the abbrev named
@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
@end defvar
@defvar last-abbrev
-This is the @code{abbrev-symbol} of the last abbrev expanded. This
+This is the @code{abbrev-symbol} of the most recent abbrev expanded. This
information is left by @code{expand-abbrev} for the sake of the
-@code{unexpand-abbrev} command.
+@code{unexpand-abbrev} command (@pxref{Expanding Abbrevs,, Expanding
+Abbrevs, emacs, The GNU Emacs Manual}).
@end defvar
@defvar last-abbrev-location
-This is the location of the last abbrev expanded. This contains
+This is the location of the most recent abbrev expanded. This contains
information left by @code{expand-abbrev} for the sake of the
@code{unexpand-abbrev} command.
@end defvar
@defvar last-abbrev-text
-This is the exact expansion text of the last abbrev expanded, after case
-conversion (if any). Its value is @code{nil} if the abbrev has already
-been unexpanded. This contains information left by @code{expand-abbrev}
-for the sake of the @code{unexpand-abbrev} command.
+This is the exact expansion text of the most recent abbrev expanded,
+after case conversion (if any). Its value is @code{nil} if the abbrev
+has already been unexpanded. This contains information left by
+@code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command.
@end defvar
@c Emacs 19 feature
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.
@end defvar
The following sample code shows a simple use of
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
+
HCoop / bpt / emacs.git / blobdiff