man/lispref/abbrevs.texi

   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, xemacs, The XEmacs User's 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 table-name definitions
  80 This function defines @var{table-name} (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 &optional expansion hook count
 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 &optional 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