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