2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/abbrevs.info
8 @node Abbrevs, Extents, Syntax Tables, Top
9 @chapter Abbrevs And Abbrev Expansion
13 An abbreviation or @dfn{abbrev} is a string of characters that may be
14 expanded to a longer string. The user can insert the abbrev string and
15 find it replaced automatically with the expansion of the abbrev. This
18 The set of abbrevs currently in effect is recorded in an @dfn{abbrev
19 table}. Each buffer has a local abbrev table, but normally all buffers
20 in the same major mode share one abbrev table. There is also a global
21 abbrev table. Normally both are used.
23 An abbrev table is represented as an obarray containing a symbol for
24 each abbreviation. The symbol's name is the abbreviation; its value is
25 the expansion; its function definition is the hook function to do the
26 expansion (@pxref{Defining Abbrevs}); its property list cell contains
27 the use count, the number of times the abbreviation has been expanded.
28 Because these symbols are not interned in the usual obarray, they will
29 never appear as the result of reading a Lisp expression; in fact,
30 normally they are never used except by the code that handles abbrevs.
31 Therefore, it is safe to use them in an extremely nonstandard way.
32 @xref{Creating Symbols}.
34 For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev
35 Mode, sxemacs, The SXEmacs User's Manual}.
38 * Abbrev Mode:: Setting up SXEmacs for abbreviation.
39 * Tables: Abbrev Tables. Creating and working with abbrev tables.
40 * Defining Abbrevs:: Specifying abbreviations and their expansions.
41 * Files: Abbrev Files. Saving abbrevs in files.
42 * Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
43 * Standard Abbrev Tables:: Abbrev tables used by various major modes.
47 @section Setting Up Abbrev Mode
49 Abbrev mode is a minor mode controlled by the value of the variable
53 A non-@code{nil} value of this variable turns on the automatic expansion
54 of abbrevs when their abbreviations are inserted into a buffer.
55 If the value is @code{nil}, abbrevs may be defined, but they are not
56 expanded automatically.
58 This variable automatically becomes local when set in any fashion.
61 @defvar default-abbrev-mode
62 This is the value of @code{abbrev-mode} for buffers that do not override it.
63 This is the same as @code{(default-value 'abbrev-mode)}.
67 @section Abbrev Tables
69 This section describes how to create and manipulate abbrev tables.
71 @defun make-abbrev-table
72 This function creates and returns a new, empty abbrev table---an obarray
73 containing no symbols. It is a vector filled with zeros.
76 @defun clear-abbrev-table table
77 This function undefines all the abbrevs in abbrev table @var{table},
78 leaving it empty. The function returns @code{nil}.
81 @defun define-abbrev-table table-name definitions
82 This function defines @var{table-name} (a symbol) as an abbrev table name,
83 i.e., as a variable whose value is an abbrev table. It defines abbrevs
84 in the table according to @var{definitions}, a list of elements of the
85 form @code{(@var{abbrevname} @var{expansion} @var{hook}
86 @var{usecount})}. The value is always @code{nil}.
89 @defvar abbrev-table-name-list
90 This is a list of symbols whose values are abbrev tables.
91 @code{define-abbrev-table} adds the new abbrev table name to this list.
94 @defun insert-abbrev-table-description name &optional human
95 This function inserts before point a description of the abbrev table
96 named @var{name}. The argument @var{name} is a symbol whose value is an
97 abbrev table. The value is always @code{nil}.
99 If @var{human} is non-@code{nil}, the description is human-oriented.
100 Otherwise the description is a Lisp expression---a call to
101 @code{define-abbrev-table} that would define @var{name} exactly as it
102 is currently defined.
105 @node Defining Abbrevs
106 @section Defining Abbrevs
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
113 @defun add-abbrev table type arg
114 This function adds an abbreviation to abbrev table @var{table} based on
115 information from the user. The argument @var{type} is a string
116 describing in English the kind of abbrev this will be (typically,
117 @code{"global"} or @code{"mode-specific"}); this is used in prompting
118 the user. The argument @var{arg} is the number of words in the
121 The return value is the symbol that internally represents the new
122 abbrev, or @code{nil} if the user declines to confirm redefining an
126 @defun define-abbrev table name &optional expansion hook count
127 This function defines an abbrev in @var{table} named @var{name}, to
128 expand to @var{expansion}, and call @var{hook}. The return value is an
129 uninterned symbol that represents the abbrev inside XEmacs; its name is
132 The argument @var{name} should be a string. The argument
133 @var{expansion} should be a string, or @code{nil} to undefine the
136 The argument @var{hook} is a function or @code{nil}. If @var{hook} is
137 non-@code{nil}, then it is called with no arguments after the abbrev is
138 replaced with @var{expansion}; point is located at the end of
139 @var{expansion} when @var{hook} is called.
141 The use count of the abbrev is initialized to zero.
144 @defopt only-global-abbrevs
145 If this variable is non-@code{nil}, it means that the user plans to use
146 global abbrevs only. This tells the commands that define mode-specific
147 abbrevs to define global ones instead. This variable does not alter the
148 behavior of the functions in this section; it is examined by their
153 @section Saving Abbrevs in Files
155 A file of saved abbrev definitions is actually a file of Lisp code.
156 The abbrevs are saved in the form of a Lisp program to define the same
157 abbrev tables with the same contents. Therefore, you can load the file
158 with @code{load} (@pxref{How Programs Do Loading}). However, the
159 function @code{quietly-read-abbrev-file} is provided as a more
160 convenient interface.
162 User-level facilities such as @code{save-some-buffers} can save
163 abbrevs in a file automatically, under the control of variables
166 @defopt abbrev-file-name
167 This is the default file name for reading and saving abbrevs.
170 @defun quietly-read-abbrev-file &optional filename
171 This function reads abbrev definitions from a file named @var{filename},
172 previously 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.
176 This function does not display any messages. It returns @code{nil}.
180 A non-@code{nil} value for @code{save-abbrev} means that SXEmacs should
181 save abbrevs when files are saved. @code{abbrev-file-name} specifies
182 the file to save the abbrevs in.
185 @defvar abbrevs-changed
186 This variable is set non-@code{nil} by defining or altering any
187 abbrevs. This serves as a flag for various SXEmacs commands to offer to
191 @deffn Command write-abbrev-file filename
192 Save all abbrev definitions, in all abbrev tables, in the file
193 @var{filename}, in the form of a Lisp program that when loaded will
194 define the same abbrevs. This function returns @code{nil}.
197 @node Abbrev Expansion
198 @section Looking Up and Expanding Abbreviations
200 Abbrevs are usually expanded by commands for interactive use,
201 including @code{self-insert-command}. This section describes the
202 subroutines used in writing such functions, as well as the variables
203 they use for communication.
205 @defun abbrev-symbol abbrev &optional table
206 This function returns the symbol representing the abbrev named
207 @var{abbrev}. The value returned is @code{nil} if that abbrev is not
208 defined. The optional second argument @var{table} is the abbrev table
209 to look it up in. If @var{table} is @code{nil}, this function tries
210 first the current buffer's local abbrev table, and second the global
214 @defun abbrev-expansion abbrev &optional table
215 This function returns the string that @var{abbrev} would expand into (as
216 defined by the abbrev tables used for the current buffer). The optional
217 argument @var{table} specifies the abbrev table to use, as in
218 @code{abbrev-symbol}.
221 @deffn Command expand-abbrev
222 This command expands the abbrev before point, if any.
223 If point does not follow an abbrev, this command does nothing.
224 The command returns @code{t} if it did expansion, @code{nil} otherwise.
227 @deffn Command abbrev-prefix-mark &optional arg
228 Mark current point as the beginning of an abbrev. The next call to
229 @code{expand-abbrev} will use the text from here to point (where it is
230 then) as the abbrev to expand, rather than using the previous word as
234 @defopt abbrev-all-caps
235 When this is set non-@code{nil}, an abbrev entered entirely in upper
236 case is expanded using all upper case. Otherwise, an abbrev entered
237 entirely in upper case is expanded by capitalizing each word of the
241 @defvar abbrev-start-location
242 This is the buffer position for @code{expand-abbrev} to use as the start
243 of the next abbrev to be expanded. (@code{nil} means use the word
244 before point instead.) @code{abbrev-start-location} is set to
245 @code{nil} each time @code{expand-abbrev} is called. This variable is
246 also set by @code{abbrev-prefix-mark}.
249 @defvar abbrev-start-location-buffer
250 The value of this variable is the buffer for which
251 @code{abbrev-start-location} has been set. Trying to expand an abbrev
252 in any other buffer clears @code{abbrev-start-location}. This variable
253 is set by @code{abbrev-prefix-mark}.
257 This is the @code{abbrev-symbol} of the last abbrev expanded. This
258 information is left by @code{expand-abbrev} for the sake of the
259 @code{unexpand-abbrev} command.
262 @defvar last-abbrev-location
263 This is the location of the last abbrev expanded. This contains
264 information left by @code{expand-abbrev} for the sake of the
265 @code{unexpand-abbrev} command.
268 @defvar last-abbrev-text
269 This is the exact expansion text of the last abbrev expanded, after case
270 conversion (if any). Its value is @code{nil} if the abbrev has already
271 been unexpanded. This contains information left by @code{expand-abbrev}
272 for the sake of the @code{unexpand-abbrev} command.
276 @defvar pre-abbrev-expand-hook
277 This is a normal hook whose functions are executed, in sequence, just
278 before any expansion of an abbrev. @xref{Hooks}. Since it is a normal
279 hook, the hook functions receive no arguments. However, they can find
280 the abbrev to be expanded by looking in the buffer before point.
283 The following sample code shows a simple use of
284 @code{pre-abbrev-expand-hook}. If the user terminates an abbrev with a
285 punctuation character, the hook function asks for confirmation. Thus,
286 this hook allows the user to decide whether to expand the abbrev, and
287 aborts expansion if it is not confirmed.
290 (add-hook 'pre-abbrev-expand-hook 'query-if-not-space)
292 ;; @r{This is the function invoked by @code{pre-abbrev-expand-hook}.}
294 ;; @r{If the user terminated the abbrev with a space, the function does}
295 ;; @r{nothing (that is, it returns so that the abbrev can expand). If the}
296 ;; @r{user entered some other character, this function asks whether}
297 ;; @r{expansion should continue.}
299 ;; @r{If the user answers the prompt with @kbd{y}, the function returns}
300 ;; @r{@code{nil} (because of the @code{not} function), but that is}
301 ;; @r{acceptable; the return value has no effect on expansion.}
303 (defun query-if-not-space ()
304 (if (/= ?\ (preceding-char))
305 (if (not (y-or-n-p "Do you want to expand this abbrev? "))
306 (error "Not expanding this abbrev"))))
309 @node Standard Abbrev Tables
310 @section Standard Abbrev Tables
312 Here we list the variables that hold the abbrev tables for the
313 preloaded major modes of SXEmacs.
315 @defvar global-abbrev-table
316 This is the abbrev table for mode-independent abbrevs. The abbrevs
317 defined in it apply to all buffers. Each buffer may also have a local
318 abbrev table, whose abbrev definitions take precedence over those in the
322 @defvar local-abbrev-table
323 The value of this buffer-local variable is the (mode-specific)
324 abbreviation table of the current buffer.
327 @defvar fundamental-mode-abbrev-table
328 This is the local abbrev table used in Fundamental mode; in other words,
329 it is the local abbrev table in all buffers in Fundamental mode.
332 @defvar text-mode-abbrev-table
333 This is the local abbrev table used in Text mode.
336 @defvar c-mode-abbrev-table
337 This is the local abbrev table used in C mode.
340 @defvar lisp-mode-abbrev-table
341 This is the local abbrev table used in Lisp mode and Emacs Lisp mode.