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