view lispref/abbrevs.texi @ 16842:72276b334084 before-thomas-posix1996 glibc-2_0_2 libc-970108 libc-970109 libc-970110 libc-970111 libc-970112 libc-970113 libc-970114 libc-970115 libc-970116 libc-970117 libc-970118 libc-970119 libc-970120 libc-970121 libc-970122 libc-970123 libc-970124 libc-970125 libc-970126 libc-970127 libc-970128 libc-970129 libc-970130 libc-970131 libc-970201 libc-970202 libc-970203 libc-970204 libc-970205 libc-970206 libc-970207 libc-970208 libc-970209 libc-970210 libc-970211 libc-970212 libc-970213 libc-970214 libc-970215 libc-970216 libc-970217 libc-970218 libc-970219 libc-970220 libc-970221 libc-970222 libc-970223 libc-970224 libc-970225 libc-970226 libc-970227 libc-970228 libc-970301 libc-970302 libc-970303 libc-970304 libc-970305 libc-970306 libc-970307 libc-970308 libc-970309 libc-970310 libc-970311 libc-970312 libc-970313 libc-970314 libc-970315 libc-970316 libc-970317 libc-970318 libc-970319 libc-970320 libc-970321 libc-970322 libc-970323 libc-970324 libc20x-970306 libc20x-97031 libc20x-970316 libc20x-970318 libc20x-970319 libc20x-970404 root-libc-2_0_x-branch

Add hppa1.1-hitachi-hiuxmpp support, passed along by rms.

@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 See the file elisp.texi for copying conditions.
@setfilename ../info/abbrevs
@node Abbrevs, Processes, Syntax Tables, Top
@chapter Abbrevs And Abbrev Expansion
@cindex abbrev
@cindex abbrev table

  An abbreviation or @dfn{abbrev} is a string of characters that may be
expanded to a longer string.  The user can insert the abbrev string and
find it replaced automatically with the expansion of the abbrev.  This
saves typing.

  The set of abbrevs currently in effect is recorded in an @dfn{abbrev
table}.  Each buffer has a local abbrev table, but normally all buffers
in the same major mode share one abbrev table.  There is also a global
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}.

  For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev
Mode, emacs, The GNU Emacs Manual}.

@menu
* Abbrev Mode::                 Setting up Emacs for abbreviation.
* Tables: Abbrev Tables.        Creating and working with abbrev tables.
* Defining Abbrevs::            Specifying abbreviations and their expansions.
* Files: Abbrev Files.          Saving abbrevs in files.
* Expansion: Abbrev Expansion.  Controlling expansion; expansion subroutines.
* Standard Abbrev Tables::      Abbrev tables used by various major modes.
@end menu

@node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs
@comment  node-name,  next,  previous,  up
@section Setting Up Abbrev Mode    

  Abbrev mode is a minor mode controlled by the value of the variable
@code{abbrev-mode}.

@defvar abbrev-mode
A non-@code{nil} value of this variable turns on the automatic expansion
of abbrevs when their abbreviations are inserted into a buffer.
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.
@end defvar

@defvar default-abbrev-mode
This is the value of @code{abbrev-mode} for buffers that do not override it.
This is the same as @code{(default-value 'abbrev-mode)}.
@end defvar

@node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs
@section Abbrev Tables

  This section describes how to create and manipulate abbrev tables.

@defun make-abbrev-table
This function creates and returns a new, empty abbrev table---an obarray
containing no symbols.  It is a vector filled with zeros.
@end defun

@defun clear-abbrev-table table
This function undefines all the abbrevs in abbrev table @var{table},
leaving it empty.  The function 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}.
@end defun

@defvar abbrev-table-name-list
This is a list of symbols whose values are abbrev tables.
@code{define-abbrev-table} adds the new abbrev table name to this list.
@end defvar

@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}.

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.
@end defun

@node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs
@comment  node-name,  next,  previous,  up
@section Defining Abbrevs

  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
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
@var{name}.

The argument @var{name} should be a string.  The argument
@var{expansion} should be a string, or @code{nil} to undefine the
abbrev.

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.
@end defun

@defopt only-global-abbrevs
If this variable is non-@code{nil}, it means that the user plans to use
global abbrevs only.  This tells the commands that define mode-specific
abbrevs to define global ones instead.  This variable does not alter the
behavior of the functions in this section; it is examined by their
callers.
@end defopt

@node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs
@section Saving Abbrevs in Files

  A file of saved abbrev definitions is actually a file of Lisp code.
The abbrevs are saved in the form of a Lisp program to define the same
abbrev tables with the same contents.  Therefore, you can load the file
with @code{load} (@pxref{How Programs Do Loading}).  However, the
function @code{quietly-read-abbrev-file} is provided as a more
convenient interface.

  User-level facilities such as @code{save-some-buffers} can save
abbrevs in a file automatically, under the control of variables
described here.

@defopt abbrev-file-name
This is the default file name for reading and saving abbrevs.
@end defopt

@defun quietly-read-abbrev-file 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.

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.
@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.
@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}.
@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,
including @code{self-insert-command}.  This section describes the
subroutines used in writing such functions, as well as the variables
they use for communication.

@defun abbrev-symbol abbrev &optional table
This function returns the symbol representing the abbrev named
@var{abbrev}.  The value returned is @code{nil} if that abbrev is not
defined.  The optional second argument @var{table} is the abbrev table
to look it up in.  If @var{table} is @code{nil}, this function tries
first the current buffer's local abbrev table, and second the global
abbrev table.
@end defun

@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}.
@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.
@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.
@end deffn

@defopt abbrev-all-caps
When this is set non-@code{nil}, an abbrev entered entirely in upper
case is expanded using all upper case.  Otherwise, an abbrev entered
entirely in upper case is expanded by capitalizing each word of the
expansion.
@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
@code{nil} each time @code{expand-abbrev} is called.  This variable is
also set by @code{abbrev-prefix-mark}.
@end defvar

@defvar abbrev-start-location-buffer
The value of this variable is the buffer for which
@code{abbrev-start-location} has been set.  Trying to expand an abbrev
in any other buffer clears @code{abbrev-start-location}.  This variable
is set by @code{abbrev-prefix-mark}.
@end defvar

@defvar last-abbrev
This is the @code{abbrev-symbol} of the last abbrev expanded.  This
information is left by @code{expand-abbrev} for the sake of the
@code{unexpand-abbrev} command.
@end defvar

@defvar last-abbrev-location
This is the location of the last 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.
@end defvar

@c Emacs 19 feature
@defvar pre-abbrev-expand-hook
This is a normal hook whose functions are executed, in sequence, just
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.
@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.

@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"))))
@end smallexample

@node Standard Abbrev Tables,  , Abbrev Expansion, Abbrevs
@comment  node-name,  next,  previous,  up
@section Standard Abbrev Tables

  Here we list the variables that hold the abbrev tables for the
preloaded major modes of Emacs.

@defvar global-abbrev-table
This is the abbrev table for mode-independent abbrevs.  The abbrevs
defined in it apply to all buffers.  Each buffer may also have a local
abbrev table, whose abbrev definitions take precedence over those in the
global table.
@end defvar

@defvar local-abbrev-table
The value of this buffer-local variable is the (mode-specific)
abbreviation table of the current buffer.
@end defvar

@defvar fundamental-mode-abbrev-table
This is the local abbrev table used in Fundamental mode; in other words,
it is the local abbrev table in all buffers in Fundamental mode.
@end defvar

@defvar text-mode-abbrev-table
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