Mercurial > hg > xemacs-beta
annotate man/lispref/abbrevs.texi @ 5865:a45722e74335
Merge.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Thu, 12 Mar 2015 16:27:13 +0000 |
| parents | 9fae6227ede5 |
| children |
| rev | line source |
|---|---|
| 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
446
diff
changeset
|
44 @node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs |
| 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
446
diff
changeset
|
64 @node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs |
| 0 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
446
diff
changeset
|
103 @node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs |
| 0 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
446
diff
changeset
|
150 @node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs |
| 0 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
446
diff
changeset
|
195 @node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs |
| 0 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
446
diff
changeset
|
307 @node Standard Abbrev Tables, , Abbrev Expansion, Abbrevs |
| 0 | 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 |