doc/lispref/abbrevs.texi

   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, 2001, 2002, 2003,
   4 @c   2004, 2005, 2006, 2007, 2008, 2009  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 @c  @cindex abbrev table  Redundant with "abbrev".
  11
  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.
  16
  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.
  21
  22   An abbrev table is represented as an obarray.  @xref{Creating
  23 Symbols}, for information about obarrays.  Each abbreviation is
  24 represented by a symbol in the obarray.  The symbol's name is the
  25 abbreviation; its value is the expansion; its function definition is
  26 the hook function for performing the expansion (@pxref{Defining
  27 Abbrevs}); and its property list cell contains various additional
  28 properties, including the use count and the number of times the
  29 abbreviation has been expanded (@pxref{Abbrev Properties}).
  30
  31 @cindex system abbrev
  32   Certain abbrevs, called @dfn{system abbrevs}, are defined by a major
  33 mode instead of the user.  A system abbrev is identified by its
  34 non-@code{nil} @code{:system} property (@pxref{Abbrev Properties}).
  35 When abbrevs are saved to an abbrev file, system abbrevs are omitted.
  36 @xref{Abbrev Files}.
  37
  38   Because the symbols used for abbrevs are not interned in the usual
  39 obarray, they will never appear as the result of reading a Lisp
  40 expression; in fact, normally they are never used except by the code
  41 that handles abbrevs.  Therefore, it is safe to use them in an
  42 extremely nonstandard way.
  43
  44   For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev
  45 Mode, emacs, The GNU Emacs Manual}.
  46
  47 @menu
  48 * Abbrev Mode::                 Setting up Emacs for abbreviation.
  49 * Tables: Abbrev Tables.        Creating and working with abbrev tables.
  50 * Defining Abbrevs::            Specifying abbreviations and their expansions.
  51 * Files: Abbrev Files.          Saving abbrevs in files.
  52 * Expansion: Abbrev Expansion.  Controlling expansion; expansion subroutines.
  53 * Standard Abbrev Tables::      Abbrev tables used by various major modes.
  54 * Abbrev Properties::           How to read and set abbrev properties.
  55                                 Which properties have which effect.
  56 * Abbrev Table Properties::     How to read and set abbrev table properties.
  57                                 Which properties have which effect.
  58 @end menu
  59
  60 @node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs
  61 @comment  node-name,  next,  previous,  up
  62 @section Setting Up Abbrev Mode
  63
  64   Abbrev mode is a minor mode controlled by the variable
  65 @code{abbrev-mode}.
  66
  67 @defvar abbrev-mode
  68 If this variable is non-@code{nil}, abbrevs are automatically expanded
  69 in the buffer.  If the value is @code{nil}, abbrevs may be defined,
  70 but they are not expanded automatically.
  71
  72 This variable automatically becomes buffer-local when set in any fashion.
  73 @end defvar
  74
  75 @defvar default-abbrev-mode
  76 This is the value of @code{abbrev-mode} for buffers that do not
  77 override it.  It is the same as @code{(default-value 'abbrev-mode)}.
  78 @end defvar
  79
  80 @node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs
  81 @section Abbrev Tables
  82
  83   This section describes how to create and manipulate abbrev tables.
  84
  85 @defun make-abbrev-table &rest props
  86 This function creates and returns a new, empty abbrev table---an
  87 obarray containing no symbols.  It is a vector filled with zeros.
  88 @var{props} is a property list that is applied to the new table
  89 (@pxref{Abbrev Table Properties}).
  90 @end defun
  91
  92 @defun abbrev-table-p object
  93 This function returns a non-@code{nil} value if @var{object} is an
  94 abbrev table.
  95 @end defun
  96
  97 @defun clear-abbrev-table abbrev-table
  98 This function undefines all the abbrevs in @var{abbrev-table}, leaving
  99 it empty.  It always returns @code{nil}.
 100 @end defun
 101
 102 @defun copy-abbrev-table abbrev-table
 103 This function returns a copy of @var{abbrev-table}---a new abbrev
 104 table containing the same abbrev definitions.  There is one difference
 105 between the contents of @var{abbrev-table} and the returned copy: all
 106 abbrevs in the latter have their property lists set to @code{nil}.
 107 @end defun
 108
 109 @defun define-abbrev-table tabname definitions &optional docstring &rest props
 110 This function defines @var{tabname} (a symbol) as an abbrev table
 111 name, i.e., as a variable whose value is an abbrev table.  It defines
 112 abbrevs in the table according to @var{definitions}, a list of
 113 elements of the form @code{(@var{abbrevname} @var{expansion}
 114 [@var{hook}] [@var{props}...])}.  These elements are passed as
 115 arguments to @code{define-abbrev}.  The return value is always
 116 @code{nil}.
 117
 118 The optional string @var{docstring} is the documentation string of the
 119 variable @var{tabname}.  The property list @var{props} is applied to
 120 the abbrev table (@pxref{Abbrev Table Properties}).
 121
 122 If this function is called more than once for the same @var{tabname},
 123 subsequent calls add the definitions in @var{definitions} to
 124 @var{tabname}, rather than overriding the entire original contents.
 125 (A subsequent call only overrides abbrevs explicitly redefined or
 126 undefined in @var{definitions}.)
 127 @end defun
 128
 129 @defvar abbrev-table-name-list
 130 This is a list of symbols whose values are abbrev tables.
 131 @code{define-abbrev-table} adds the new abbrev table name to this list.
 132 @end defvar
 133
 134 @defun insert-abbrev-table-description name &optional human
 135 This function inserts before point a description of the abbrev table
 136 named @var{name}.  The argument @var{name} is a symbol whose value is an
 137 abbrev table.  The return value is always @code{nil}.
 138
 139 If @var{human} is non-@code{nil}, the description is human-oriented.
 140 System abbrevs are listed and identified as such.  Otherwise the
 141 description is a Lisp expression---a call to @code{define-abbrev-table}
 142 that would define @var{name} as it is currently defined, but without
 143 the system abbrevs.  (The mode or package using @var{name} is supposed
 144 to add these to @var{name} separately.)
 145 @end defun
 146
 147 @node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs
 148 @comment  node-name,  next,  previous,  up
 149 @section Defining Abbrevs
 150
 151   @code{define-abbrev} is the low-level basic function for defining an
 152 abbrev in an abbrev table.
 153
 154   When a major mode defines a system abbrev, it should call
 155 @code{define-abbrev} and specify a @code{t} for the @code{:system}
 156 property.  Be aware that any saved non-``system'' abbrevs are restored
 157 at startup, i.e. before some major modes are loaded.  Therefore, major
 158 modes should not assume that their abbrev tables are empty when they
 159 are first loaded.
 160
 161 @defun define-abbrev abbrev-table name expansion &optional hook &rest props
 162 This function defines an abbrev named @var{name}, in
 163 @var{abbrev-table}, to expand to @var{expansion} and call @var{hook},
 164 with properties @var{props} (@pxref{Abbrev Properties}).  The return
 165 value is @var{name}.  The @code{:system} property in @var{props} is
 166 treated specially here: if it has the value @code{force}, then it will
 167 overwrite an existing definition even for a non-``system'' abbrev of
 168 the same name.
 169
 170 @var{name} should be a string.  The argument @var{expansion} is
 171 normally the desired expansion (a string), or @code{nil} to undefine
 172 the abbrev.  If it is anything but a string or @code{nil}, then the
 173 abbreviation ``expands'' solely by running @var{hook}.
 174
 175 The argument @var{hook} is a function or @code{nil}.  If @var{hook} is
 176 non-@code{nil}, then it is called with no arguments after the abbrev is
 177 replaced with @var{expansion}; point is located at the end of
 178 @var{expansion} when @var{hook} is called.
 179
 180 @cindex @code{no-self-insert} property
 181 If @var{hook} is a non-@code{nil} symbol whose @code{no-self-insert}
 182 property is non-@code{nil}, @var{hook} can explicitly control whether
 183 to insert the self-inserting input character that triggered the
 184 expansion.  If @var{hook} returns non-@code{nil} in this case, that
 185 inhibits insertion of the character.  By contrast, if @var{hook}
 186 returns @code{nil}, @code{expand-abbrev} also returns @code{nil}, as
 187 if expansion had not really occurred.
 188
 189 Normally, @code{define-abbrev} sets the variable
 190 @code{abbrevs-changed} to @code{t}, if it actually changes the abbrev.
 191 (This is so that some commands will offer to save the abbrevs.)  It
 192 does not do this for a system abbrev, since those aren't saved anyway.
 193 @end defun
 194
 195 @defopt only-global-abbrevs
 196 If this variable is non-@code{nil}, it means that the user plans to use
 197 global abbrevs only.  This tells the commands that define mode-specific
 198 abbrevs to define global ones instead.  This variable does not alter the
 199 behavior of the functions in this section; it is examined by their
 200 callers.
 201 @end defopt
 202
 203 @node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs
 204 @section Saving Abbrevs in Files
 205
 206   A file of saved abbrev definitions is actually a file of Lisp code.
 207 The abbrevs are saved in the form of a Lisp program to define the same
 208 abbrev tables with the same contents.  Therefore, you can load the file
 209 with @code{load} (@pxref{How Programs Do Loading}).  However, the
 210 function @code{quietly-read-abbrev-file} is provided as a more
 211 convenient interface.
 212
 213   User-level facilities such as @code{save-some-buffers} can save
 214 abbrevs in a file automatically, under the control of variables
 215 described here.
 216
 217 @defopt abbrev-file-name
 218 This is the default file name for reading and saving abbrevs.
 219 @end defopt
 220
 221 @defun quietly-read-abbrev-file &optional filename
 222 This function reads abbrev definitions from a file named @var{filename},
 223 previously written with @code{write-abbrev-file}.  If @var{filename} is
 224 omitted or @code{nil}, the file specified in @code{abbrev-file-name} is
 225 used.  @code{save-abbrevs} is set to @code{t} so that changes will be
 226 saved.
 227
 228 This function does not display any messages.  It returns @code{nil}.
 229 @end defun
 230
 231 @defopt save-abbrevs
 232 A non-@code{nil} value for @code{save-abbrevs} means that Emacs should
 233 offer the user to save abbrevs when files are saved.  If the value is
 234 @code{silently}, Emacs saves the abbrevs without asking the user.
 235 @code{abbrev-file-name} specifies the file to save the abbrevs in.
 236 @end defopt
 237
 238 @defvar abbrevs-changed
 239 This variable is set non-@code{nil} by defining or altering any
 240 abbrevs (except system abbrevs).  This serves as a flag for various
 241 Emacs commands to offer to save your abbrevs.
 242 @end defvar
 243
 244 @deffn Command write-abbrev-file &optional filename
 245 Save all abbrev definitions (except system abbrevs), for all abbrev
 246 tables listed in @code{abbrev-table-name-list}, in the file
 247 @var{filename}, in the form of a Lisp program that when loaded will
 248 define the same abbrevs.  If @var{filename} is @code{nil} or omitted,
 249 @code{abbrev-file-name} is used.  This function returns @code{nil}.
 250 @end deffn
 251
 252 @node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs
 253 @comment  node-name,  next,  previous,  up
 254 @section Looking Up and Expanding Abbreviations
 255
 256   Abbrevs are usually expanded by certain interactive commands,
 257 including @code{self-insert-command}.  This section describes the
 258 subroutines used in writing such commands, as well as the variables they
 259 use for communication.
 260
 261 @defun abbrev-symbol abbrev &optional table
 262 This function returns the symbol representing the abbrev named
 263 @var{abbrev}.  The value returned is @code{nil} if that abbrev is not
 264 defined.  The optional second argument @var{table} is the abbrev table
 265 in which to look it up.  If @var{table} is @code{nil}, this function
 266 tries first the current buffer's local abbrev table, and second the
 267 global abbrev table.
 268 @end defun
 269
 270 @defun abbrev-expansion abbrev &optional table
 271 This function returns the string that @var{abbrev} would expand into (as
 272 defined by the abbrev tables used for the current buffer).  If
 273 @var{abbrev} is not a valid abbrev, the function returns @code{nil}.
 274 The optional argument @var{table} specifies the abbrev table to use,
 275 as in @code{abbrev-symbol}.
 276 @end defun
 277
 278 @deffn Command expand-abbrev
 279 This command expands the abbrev before point, if any.  If point does not
 280 follow an abbrev, this command does nothing.  The command returns the
 281 abbrev symbol if it did expansion, @code{nil} otherwise.
 282
 283 If the abbrev symbol has a hook function which is a symbol whose
 284 @code{no-self-insert} property is non-@code{nil}, and if the hook
 285 function returns @code{nil} as its value, then @code{expand-abbrev}
 286 returns @code{nil} even though expansion did occur.
 287 @end deffn
 288
 289 @deffn abbrev-insert abbrev &optional name start end
 290 This function inserts the abbrev expansion of @code{abbrev}, replacing
 291 the text between @code{start} and @code{end}.  If @code{start} is
 292 omitted, it defaults to point.  @code{name}, if non-@code{nil}, should
 293 be the name by which this abbrev was found (a string); it is used to
 294 figure out whether to adjust the capitalization of the expansion.  The
 295 function returns @code{abbrev} if the abbrev was successfully
 296 inserted.
 297 @end deffn
 298
 299 @deffn Command abbrev-prefix-mark &optional arg
 300 This command marks the current location of point as the beginning of
 301 an abbrev.  The next call to @code{expand-abbrev} will use the text
 302 from here to point (where it is then) as the abbrev to expand, rather
 303 than using the previous word as usual.
 304
 305 First, this command expands any abbrev before point, unless @var{arg}
 306 is non-@code{nil}.  (Interactively, @var{arg} is the prefix argument.)
 307 Then it inserts a hyphen before point, to indicate the start of the
 308 next abbrev to be expanded.  The actual expansion removes the hyphen.
 309 @end deffn
 310
 311 @defopt abbrev-all-caps
 312 When this is set non-@code{nil}, an abbrev entered entirely in upper
 313 case is expanded using all upper case.  Otherwise, an abbrev entered
 314 entirely in upper case is expanded by capitalizing each word of the
 315 expansion.
 316 @end defopt
 317
 318 @defvar abbrev-start-location
 319 The value of this variable is a buffer position (an integer or a marker)
 320 for @code{expand-abbrev} to use as the start of the next abbrev to be
 321 expanded.  The value can also be @code{nil}, which means to use the
 322 word before point instead.  @code{abbrev-start-location} is set to
 323 @code{nil} each time @code{expand-abbrev} is called.  This variable is
 324 also set by @code{abbrev-prefix-mark}.
 325 @end defvar
 326
 327 @defvar abbrev-start-location-buffer
 328 The value of this variable is the buffer for which
 329 @code{abbrev-start-location} has been set.  Trying to expand an abbrev
 330 in any other buffer clears @code{abbrev-start-location}.  This variable
 331 is set by @code{abbrev-prefix-mark}.
 332 @end defvar
 333
 334 @defvar last-abbrev
 335 This is the @code{abbrev-symbol} of the most recent abbrev expanded.  This
 336 information is left by @code{expand-abbrev} for the sake of the
 337 @code{unexpand-abbrev} command (@pxref{Expanding Abbrevs,, Expanding
 338 Abbrevs, emacs, The GNU Emacs Manual}).
 339 @end defvar
 340
 341 @defvar last-abbrev-location
 342 This is the location of the most recent abbrev expanded.  This contains
 343 information left by @code{expand-abbrev} for the sake of the
 344 @code{unexpand-abbrev} command.
 345 @end defvar
 346
 347 @defvar last-abbrev-text
 348 This is the exact expansion text of the most recent abbrev expanded,
 349 after case conversion (if any).  Its value is @code{nil} if the abbrev
 350 has already been unexpanded.  This contains information left by
 351 @code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command.
 352 @end defvar
 353
 354 @defvar abbrev-expand-functions
 355 This is a special hook run @emph{around} the @code{expand-abbrev}
 356 function.  Each function on this hook is called with a single
 357 argument: a function that performs the normal abbrev expansion.  The
 358 hook function can hence do anything it wants before and after
 359 performing the expansion.  It can also choose not to call its
 360 argument, thus overriding the default behavior; or it may even call it
 361 several times.  The function should return the abbrev symbol if
 362 expansion took place.
 363 @end defvar
 364
 365   The following sample code shows a simple use of
 366 @code{abbrev-expand-functions}.  It assumes that @code{foo-mode} is a
 367 mode for editing certain files in which lines that start with @samp{#}
 368 are comments.  You want to use Text mode abbrevs for those lines.  The
 369 regular local abbrev table, @code{foo-mode-abbrev-table} is
 370 appropriate for all other lines.  Then you can put the following code
 371 in your @file{.emacs} file.  @xref{Standard Abbrev Tables}, for the
 372 definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}.
 373
 374 @smallexample
 375 (defun foo-mode-abbrev-expand-function (expand)
 376   (if (not (save-excursion (forward-line 0) (eq (char-after) ?#)))
 377       ;; Performs normal expansion.
 378       (funcall expand)
 379     ;; We're inside a comment: use the text-mode abbrevs.
 380     (let ((local-abbrev-table text-mode-abbrev-table))
 381       (funcall expand))))
 382
 383 (add-hook 'foo-mode-hook
 384           #'(lambda ()
 385               (add-hook 'abbrev-expand-functions
 386                         'foo-mode-abbrev-expand-function
 387                         nil t)))
 388 @end smallexample
 389
 390 @node Standard Abbrev Tables, Abbrev Properties, Abbrev Expansion, Abbrevs
 391 @comment  node-name,  next,  previous,  up
 392 @section Standard Abbrev Tables
 393
 394   Here we list the variables that hold the abbrev tables for the
 395 preloaded major modes of Emacs.
 396
 397 @defvar global-abbrev-table
 398 This is the abbrev table for mode-independent abbrevs.  The abbrevs
 399 defined in it apply to all buffers.  Each buffer may also have a local
 400 abbrev table, whose abbrev definitions take precedence over those in the
 401 global table.
 402 @end defvar
 403
 404 @defvar local-abbrev-table
 405 The value of this buffer-local variable is the (mode-specific)
 406 abbreviation table of the current buffer.  It can also be a list of
 407 such tables.
 408 @end defvar
 409
 410 @defvar abbrev-minor-mode-table-alist
 411 The value of this variable is a list of elements of the form
 412 @code{(@var{mode} . @var{abbrev-table})} where @var{mode} is the name
 413 of a variable: if the variable is bound to a non-@code{nil} value,
 414 then the @var{abbrev-table} is active, otherwise it is ignored.
 415 @var{abbrev-table} can also be a list of abbrev tables.
 416 @end defvar
 417
 418 @defvar fundamental-mode-abbrev-table
 419 This is the local abbrev table used in Fundamental mode; in other words,
 420 it is the local abbrev table in all buffers in Fundamental mode.
 421 @end defvar
 422
 423 @defvar text-mode-abbrev-table
 424 This is the local abbrev table used in Text mode.
 425 @end defvar
 426
 427 @defvar lisp-mode-abbrev-table
 428 This is the local abbrev table used in Lisp mode and Emacs Lisp mode.
 429 @end defvar
 430
 431 @node Abbrev Properties, Abbrev Table Properties, Standard Abbrev Tables, Abbrevs
 432 @section Abbrev Properties
 433
 434 Abbrevs have properties, some of which influence the way they work.
 435 You can provide them as arguments to @code{define-abbrev} and you can
 436 manipulate them with the following functions:
 437
 438 @defun abbrev-put abbrev prop val
 439 Set the property @var{prop} of @var{abbrev} to value @var{val}.
 440 @end defun
 441
 442 @defun abbrev-get abbrev prop
 443 Return the property @var{prop} of @var{abbrev}, or @code{nil} if the
 444 abbrev has no such property.
 445 @end defun
 446
 447 The following properties have special meanings:
 448
 449 @table @code
 450 @item :count
 451 This property counts the number of times the abbrev has
 452 been expanded.  If not explicitly set, it is initialized to 0 by
 453 @code{define-abbrev}.
 454
 455 @item :system
 456 If non-@code{nil}, this property marks the abbrev as a system abbrev.
 457 Such abbrevs are not saved (@pxref{Abbrev Files}).
 458
 459 @item :enable-function
 460 If non-@code{nil}, this property should be a function of no
 461 arguments which returns @code{nil} if the abbrev should not be used
 462 and @code{t} otherwise.
 463
 464 @item :case-fixed
 465 If non-@code{nil}, this property indicates that the case of the
 466 abbrev's name is significant and should only match a text with the
 467 same pattern of capitalization.  It also disables the code that
 468 modifies the capitalization of the expansion.
 469 @end table
 470
 471 @node Abbrev Table Properties,  , Abbrev Properties, Abbrevs
 472 @section Abbrev Table Properties
 473
 474 Like abbrevs, abbrev tables have properties, some of which influence
 475 the way they work.  You can provide them as arguments to
 476 @code{define-abbrev-table} and you can manipulate them with the
 477 functions:
 478
 479 @defun abbrev-table-put table prop val
 480 Set the property @var{prop} of abbrev table @var{table} to value @var{val}.
 481 @end defun
 482
 483 @defun abbrev-table-get table prop
 484 Return the property @var{prop} of abbrev table @var{table}, or @code{nil}
 485 if the abbrev has no such property.
 486 @end defun
 487
 488 The following properties have special meaning:
 489
 490 @table @code
 491 @item :enable-function
 492 This is like the @code{:enable-function} abbrev property except that
 493 it applies to all abbrevs in the table and is used even before trying
 494 to find the abbrev before point so it can dynamically modify the
 495 abbrev table.
 496
 497 @item :case-fixed
 498 This is like the @code{:case-fixed} abbrev property except that it
 499 applies to all abbrevs in the table.
 500
 501 @item :regexp
 502 If non-@code{nil}, this property is a regular expression that
 503 indicates how to extract the name of the abbrev before point before
 504 looking it up in the table.  When the regular expression matches
 505 before point, the abbrev name is expected to be in submatch 1.
 506 If this property is @code{nil}, @code{expand-function} defaults to
 507 @code{"\\<\\(\\w+\\)\\W"}.  This property allows the use of abbrevs
 508 whose name contains characters of non-word syntax.
 509
 510 @item :parents
 511 This property holds the list of tables from which to inherit
 512 other abbrevs.
 513
 514 @item :abbrev-table-modiff
 515 This property holds a counter incremented each time a new abbrev is
 516 added to the table.
 517
 518 @end table
 519
 520
 521 @ignore
 522    arch-tag: 5ffdbe08-2cd4-48ec-a5a8-080f95756eec
 523 @end ignore