*** empty log message ***
[emacs.git] / lispref / abbrevs.texi
blob8e31c7c870d453ddbb943447f4672729217fc2f9
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1999 
4 @c   Free Software Foundation, Inc. 
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/abbrevs
7 @node Abbrevs, Processes, Syntax Tables, Top
8 @chapter Abbrevs and Abbrev Expansion
9 @cindex abbrev
10 @cindex abbrev table
12   An abbreviation or @dfn{abbrev} is a string of characters that may be
13 expanded to a longer string.  The user can insert the abbrev string and
14 find it replaced automatically with the expansion of the abbrev.  This
15 saves typing.
17   The set of abbrevs currently in effect is recorded in an @dfn{abbrev
18 table}.  Each buffer has a local abbrev table, but normally all buffers
19 in the same major mode share one abbrev table.  There is also a global
20 abbrev table.  Normally both are used.
22   An abbrev table is represented as an obarray containing a symbol for
23 each abbreviation.  The symbol's name is the abbreviation; its value
24 is the expansion; its function definition is the hook function to do
25 the expansion (@pxref{Defining Abbrevs}); its property list cell
26 typically contains the use count, the number of times the abbreviation
27 has been expanded.  (Alternatively, the use count is on the
28 @code{count} property and the system-abbrev flag is on the
29 @code{system-type} property.)  Because these symbols are not interned
30 in the usual obarray, they will never appear as the result of reading
31 a Lisp expression; in fact, normally they are never used except by the
32 code that handles abbrevs.  Therefore, it is safe to use them in an
33 extremely nonstandard way.  @xref{Creating Symbols}.
35   For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev
36 Mode, emacs, The GNU Emacs Manual}.
38 @menu
39 * Abbrev Mode::                 Setting up Emacs for abbreviation.
40 * Tables: Abbrev Tables.        Creating and working with abbrev tables.
41 * Defining Abbrevs::            Specifying abbreviations and their expansions.
42 * Files: Abbrev Files.          Saving abbrevs in files.
43 * Expansion: Abbrev Expansion.  Controlling expansion; expansion subroutines.
44 * Standard Abbrev Tables::      Abbrev tables used by various major modes.
45 @end menu
47 @node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs
48 @comment  node-name,  next,  previous,  up
49 @section Setting Up Abbrev Mode    
51   Abbrev mode is a minor mode controlled by the value of the variable
52 @code{abbrev-mode}.
54 @defvar abbrev-mode
55 A non-@code{nil} value of this variable turns on the automatic expansion
56 of abbrevs when their abbreviations are inserted into a buffer.
57 If the value is @code{nil}, abbrevs may be defined, but they are not
58 expanded automatically.
60 This variable automatically becomes buffer-local when set in any fashion.
61 @end defvar
63 @defvar default-abbrev-mode
64 This is the value of @code{abbrev-mode} for buffers that do not override it.
65 This is the same as @code{(default-value 'abbrev-mode)}.
66 @end defvar
68 @node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs
69 @section Abbrev Tables
71   This section describes how to create and manipulate abbrev tables.
73 @defun make-abbrev-table
74 This function creates and returns a new, empty abbrev table---an obarray
75 containing no symbols.  It is a vector filled with zeros.
76 @end defun
78 @defun clear-abbrev-table table
79 This function undefines all the abbrevs in abbrev table @var{table},
80 leaving it empty.  It always returns @code{nil}.
81 @end defun
83 @defun define-abbrev-table tabname definitions
84 This function defines @var{tabname} (a symbol) as an abbrev table
85 name, i.e., as a variable whose value is an abbrev table.  It defines
86 abbrevs in the table according to @var{definitions}, a list of
87 elements of the form @code{(@var{abbrevname} @var{expansion}
88 @var{hook} @var{usecount} @r{[}@var{system-flag}@r{]})}.  The return
89 value is always @code{nil}.
90 @end defun
92 @defvar abbrev-table-name-list
93 This is a list of symbols whose values are abbrev tables.
94 @code{define-abbrev-table} adds the new abbrev table name to this list.
95 @end defvar
97 @defun insert-abbrev-table-description name &optional human
98 This function inserts before point a description of the abbrev table
99 named @var{name}.  The argument @var{name} is a symbol whose value is an
100 abbrev table.  The return value is always @code{nil}.
102 If @var{human} is non-@code{nil}, the description is human-oriented.
103 Otherwise the description is a Lisp expression---a call to
104 @code{define-abbrev-table} that would define @var{name} exactly as it
105 is currently defined.
106 @end defun
108 @node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs
109 @comment  node-name,  next,  previous,  up
110 @section Defining Abbrevs
112   These functions define an abbrev in a specified abbrev table.
113 @code{define-abbrev} is the low-level basic function, while
114 @code{add-abbrev} is used by commands that ask for information from
115 the user.  When major modes predefine standard abbrevs, they should
116 call @code{define-abbrev} and specify @code{t} for @var{system-flag}.
118 @defun add-abbrev table type arg
119 This function adds an abbreviation to abbrev table @var{table} based on
120 information from the user.  The argument @var{type} is a string
121 describing in English the kind of abbrev this will be (typically,
122 @code{"global"} or @code{"mode-specific"}); this is used in prompting
123 the user.  The argument @var{arg} is the number of words in the
124 expansion.
126 The return value is the symbol that internally represents the new
127 abbrev, or @code{nil} if the user declines to confirm redefining an
128 existing abbrev.
129 @end defun
131 @defun define-abbrev table name expansion &optional hook count system-flag
132 This function defines an abbrev named @var{name}, in @var{table}, to
133 expand to @var{expansion} and call @var{hook}.  The return value is a
134 symbol that represents the abbrev inside Emacs; its name is
135 @var{name}.
137 The value of @var{count}, if specified, initializes the abbrev's
138 usage-count.  If @var{count} is not specified or @code{nil}, the use
139 count is initialized to zero.
141 The argument @var{name} should be a string.  The argument
142 @var{expansion} is normally the desired expansion (a string), or
143 @code{nil} to undefine the abbrev.  If it is anything but a string or
144 @code{nil}, then the abbreviation ``expands'' solely by running
145 @var{hook}.
147 The argument @var{hook} is a function or @code{nil}.  If @var{hook} is
148 non-@code{nil}, then it is called with no arguments after the abbrev is
149 replaced with @var{expansion}; point is located at the end of
150 @var{expansion} when @var{hook} is called.
152 If @var{hook} is a non-nil symbol whose @code{no-self-insert} property
153 is non-@code{nil}, @var{hook} can explicitly control whether to insert
154 the self-inserting input character that triggered the expansion.  If
155 @var{hook} returns non-@code{nil} in this case, that inhibits insertion
156 of the character.  By contrast, if @var{hook} returns @code{nil},
157 @code{expand-abbrev} also returns @code{nil}, as if expansion had not
158 really occurred.
160 If @var{system-flag} is non-@code{nil}, that marks the abbrev as a
161 ``system'' abbrev with the @code{system-type} property.
163 Normally the function @code{define-abbrev} sets the variable
164 @code{abbrevs-changed} to @code{t}, if it actually changes the abbrev.
165 (This is so that some commands will offer to save the abbrevs.)  It
166 does not do this for a ``system'' abbrev, since those won't be saved
167 anyway.
168 @end defun
170 @defopt only-global-abbrevs
171 If this variable is non-@code{nil}, it means that the user plans to use
172 global abbrevs only.  This tells the commands that define mode-specific
173 abbrevs to define global ones instead.  This variable does not alter the
174 behavior of the functions in this section; it is examined by their
175 callers.
176 @end defopt
178 @node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs
179 @section Saving Abbrevs in Files
181   A file of saved abbrev definitions is actually a file of Lisp code.
182 The abbrevs are saved in the form of a Lisp program to define the same
183 abbrev tables with the same contents.  Therefore, you can load the file
184 with @code{load} (@pxref{How Programs Do Loading}).  However, the
185 function @code{quietly-read-abbrev-file} is provided as a more
186 convenient interface.
188   User-level facilities such as @code{save-some-buffers} can save
189 abbrevs in a file automatically, under the control of variables
190 described here.
192 @defopt abbrev-file-name
193 This is the default file name for reading and saving abbrevs.
194 @end defopt
196 @defun quietly-read-abbrev-file &optional filename
197 This function reads abbrev definitions from a file named @var{filename},
198 previously written with @code{write-abbrev-file}.  If @var{filename} is
199 omitted or @code{nil}, the file specified in @code{abbrev-file-name} is
200 used.  @code{save-abbrevs} is set to @code{t} so that changes will be
201 saved.
203 This function does not display any messages.  It returns @code{nil}.
204 @end defun
206 @defopt save-abbrevs
207 A non-@code{nil} value for @code{save-abbrev} means that Emacs should
208 save abbrevs when files are saved.  @code{abbrev-file-name} specifies
209 the file to save the abbrevs in.
210 @end defopt
212 @defvar abbrevs-changed
213 This variable is set non-@code{nil} by defining or altering any
214 abbrevs (except ``system'' abbrevs).  This serves as a flag for
215 various Emacs commands to offer to save your abbrevs.
216 @end defvar
218 @deffn Command write-abbrev-file &optional filename
219 Save all abbrev definitions (except ``system'' abbrevs), in all abbrev
220 tables, in the file @var{filename}, in the form of a Lisp program that
221 when loaded will define the same abbrevs.  If @var{filename} is
222 @code{nil} or omitted, @code{abbrev-file-name} is used.  This function
223 returns @code{nil}.
224 @end deffn
226 @node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs
227 @comment  node-name,  next,  previous,  up
228 @section Looking Up and Expanding Abbreviations
230   Abbrevs are usually expanded by certain interactive commands,
231 including @code{self-insert-command}.  This section describes the
232 subroutines used in writing such commands, as well as the variables they
233 use for communication.
235 @defun abbrev-symbol abbrev &optional table
236 This function returns the symbol representing the abbrev named
237 @var{abbrev}.  The value returned is @code{nil} if that abbrev is not
238 defined.  The optional second argument @var{table} is the abbrev table
239 to look it up in.  If @var{table} is @code{nil}, this function tries
240 first the current buffer's local abbrev table, and second the global
241 abbrev table.
242 @end defun
244 @defun abbrev-expansion abbrev &optional table
245 This function returns the string that @var{abbrev} would expand into (as
246 defined by the abbrev tables used for the current buffer).  The optional
247 argument @var{table} specifies the abbrev table to use, as in
248 @code{abbrev-symbol}.
249 @end defun
251 @deffn Command expand-abbrev
252 This command expands the abbrev before point, if any.  If point does not
253 follow an abbrev, this command does nothing.  The command returns the
254 abbrev symbol if it did expansion, @code{nil} otherwise.
256 If the abbrev symbol has a hook function which is a symbol whose
257 @code{no-self-insert} property is non-@code{nil}, and if the hook
258 function returns @code{nil} as its value, then @code{expand-abbrev}
259 returns @code{nil} even though expansion did occur.
260 @end deffn
262 @deffn Command abbrev-prefix-mark &optional arg
263 Mark current point as the beginning of an abbrev.  The next call to
264 @code{expand-abbrev} will use the text from here to point (where it is
265 then) as the abbrev to expand, rather than using the previous word as
266 usual.
267 @end deffn
269 @defopt abbrev-all-caps
270 When this is set non-@code{nil}, an abbrev entered entirely in upper
271 case is expanded using all upper case.  Otherwise, an abbrev entered
272 entirely in upper case is expanded by capitalizing each word of the
273 expansion.
274 @end defopt
276 @defvar abbrev-start-location
277 This is the buffer position for @code{expand-abbrev} to use as the start
278 of the next abbrev to be expanded.  (@code{nil} means use the word
279 before point instead.)  @code{abbrev-start-location} is set to
280 @code{nil} each time @code{expand-abbrev} is called.  This variable is
281 also set by @code{abbrev-prefix-mark}.
282 @end defvar
284 @defvar abbrev-start-location-buffer
285 The value of this variable is the buffer for which
286 @code{abbrev-start-location} has been set.  Trying to expand an abbrev
287 in any other buffer clears @code{abbrev-start-location}.  This variable
288 is set by @code{abbrev-prefix-mark}.
289 @end defvar
291 @defvar last-abbrev
292 This is the @code{abbrev-symbol} of the most recent abbrev expanded.  This
293 information is left by @code{expand-abbrev} for the sake of the
294 @code{unexpand-abbrev} command (@pxref{Expanding Abbrevs,, Expanding
295 Abbrevs, emacs, The GNU Emacs Manual}).
296 @end defvar
298 @defvar last-abbrev-location
299 This is the location of the most recent abbrev expanded.  This contains
300 information left by @code{expand-abbrev} for the sake of the
301 @code{unexpand-abbrev} command.
302 @end defvar
304 @defvar last-abbrev-text
305 This is the exact expansion text of the most recent abbrev expanded,
306 after case conversion (if any).  Its value is @code{nil} if the abbrev
307 has already been unexpanded.  This contains information left by
308 @code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command.
309 @end defvar
311 @c Emacs 19 feature
312 @defvar pre-abbrev-expand-hook
313 This is a normal hook whose functions are executed, in sequence, just
314 before any expansion of an abbrev.  @xref{Hooks}.  Since it is a normal
315 hook, the hook functions receive no arguments.  However, they can find
316 the abbrev to be expanded by looking in the buffer before point.
317 Running the hook is the first thing that @code{expand-abbrev} does, and
318 so a hook function can be used to change the current abbrev table before
319 abbrev lookup happens.
320 @end defvar
322   The following sample code shows a simple use of
323 @code{pre-abbrev-expand-hook}.  If the user terminates an abbrev with a
324 punctuation character, the hook function asks for confirmation.  Thus,
325 this hook allows the user to decide whether to expand the abbrev, and
326 aborts expansion if it is not confirmed.
328 @smallexample
329 (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
331 ;; @r{This is the function invoked by @code{pre-abbrev-expand-hook}.}
333 ;; @r{If the user terminated the abbrev with a space, the function does}
334 ;; @r{nothing (that is, it returns so that the abbrev can expand).  If the}
335 ;; @r{user entered some other character, this function asks whether}
336 ;; @r{expansion should continue.}
338 ;; @r{If the user answers the prompt with @kbd{y}, the function returns}
339 ;; @r{@code{nil} (because of the @code{not} function), but that is}
340 ;; @r{acceptable; the return value has no effect on expansion.}
342 (defun query-if-not-space ()
343   (if (/= ?\  (preceding-char))
344       (if (not (y-or-n-p "Do you want to expand this abbrev? "))
345           (error "Not expanding this abbrev"))))
346 @end smallexample
348 @node Standard Abbrev Tables,  , Abbrev Expansion, Abbrevs
349 @comment  node-name,  next,  previous,  up
350 @section Standard Abbrev Tables
352   Here we list the variables that hold the abbrev tables for the
353 preloaded major modes of Emacs.
355 @defvar global-abbrev-table
356 This is the abbrev table for mode-independent abbrevs.  The abbrevs
357 defined in it apply to all buffers.  Each buffer may also have a local
358 abbrev table, whose abbrev definitions take precedence over those in the
359 global table.
360 @end defvar
362 @defvar local-abbrev-table
363 The value of this buffer-local variable is the (mode-specific)
364 abbreviation table of the current buffer.
365 @end defvar
367 @defvar fundamental-mode-abbrev-table
368 This is the local abbrev table used in Fundamental mode; in other words,
369 it is the local abbrev table in all buffers in Fundamental mode.
370 @end defvar
372 @defvar text-mode-abbrev-table
373 This is the local abbrev table used in Text mode.
374 @end defvar
376 @defvar lisp-mode-abbrev-table
377 This is the local abbrev table used in Lisp mode and Emacs Lisp mode.
378 @end defvar