0
+ − 1 @c -*-texinfo-*-
+ − 2 @c This is part of the XEmacs Lisp Reference Manual.
444
+ − 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
0
+ − 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
446
+ − 33 Mode, xemacs, The XEmacs User's Manual}.
0
+ − 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
444
+ − 45 @section Setting Up Abbrev Mode
0
+ − 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
444
+ − 79 @defun define-abbrev-table table-name definitions
+ − 80 This function defines @var{table-name} (a symbol) as an abbrev table name,
0
+ − 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
444
+ − 124 @defun define-abbrev table name &optional expansion hook count
0
+ − 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
444
+ − 168 @defun quietly-read-abbrev-file &optional filename
0
+ − 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
444
+ − 184 This variable is set non-@code{nil} by defining or altering any
0
+ − 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
