X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/6d96d6eb86e92d7a9772d60bdfb54f2a8e90678f..e91d4202004eb76d6edddbcea3d27c11b546a788:/lispref/abbrevs.texi diff --git a/lispref/abbrevs.texi b/lispref/abbrevs.texi index 8e31c7c870..52b3dfe1ad 100644 --- a/lispref/abbrevs.texi +++ b/lispref/abbrevs.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1999 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1999, 2002, 2003, 2004, +@c 2005, 2006 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/abbrevs @node Abbrevs, Processes, Syntax Tables, Top @@ -24,12 +24,17 @@ each abbreviation. The symbol's name is the abbreviation; its value is the expansion; its function definition is the hook function to do the expansion (@pxref{Defining Abbrevs}); its property list cell typically contains the use count, the number of times the abbreviation -has been expanded. (Alternatively, the use count is on the +has been expanded. Alternatively, the use count is on the @code{count} property and the system-abbrev flag is on the -@code{system-type} property.) Because these symbols are not interned -in the usual obarray, they will never appear as the result of reading -a Lisp expression; in fact, normally they are never used except by the -code that handles abbrevs. Therefore, it is safe to use them in an +@code{system-type} property. Abbrevs with a non-@code{nil} +@code{system-type} property are called ``system'' abbrevs. They are +usually defined by modes or packages, instead of by the user, and are +treated specially in certain respects. + +Because the symbols used for abbrevs are not interned in the usual +obarray, they will never appear as the result of reading a Lisp +expression; in fact, normally they are never used except by the code +that handles abbrevs. Therefore, it is safe to use them in an extremely nonstandard way. @xref{Creating Symbols}. For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev @@ -46,7 +51,7 @@ Mode, emacs, The GNU Emacs Manual}. @node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs @comment node-name, next, previous, up -@section Setting Up Abbrev Mode +@section Setting Up Abbrev Mode Abbrev mode is a minor mode controlled by the value of the variable @code{abbrev-mode}. @@ -80,13 +85,28 @@ This function undefines all the abbrevs in abbrev table @var{table}, leaving it empty. It always returns @code{nil}. @end defun +@defun copy-abbrev-table table +This function returns a copy of abbrev table @var{table}---a new +abbrev table that contains the same abbrev definitions. The only +difference between @var{table} and the returned copy is that this +function sets the property lists of all copied abbrevs to 0. +@end defun + @defun define-abbrev-table tabname definitions This function defines @var{tabname} (a symbol) as an abbrev table name, i.e., as a variable whose value is an abbrev table. It defines abbrevs in the table according to @var{definitions}, a list of elements of the form @code{(@var{abbrevname} @var{expansion} -@var{hook} @var{usecount} @r{[}@var{system-flag}@r{]})}. The return -value is always @code{nil}. +@var{hook} @var{usecount} @var{system-flag})}. If an element of +@var{definitions} has length less than five, omitted elements default +to @code{nil}. A value of @code{nil} for @var{usecount} is equivalent +to zero. The return value is always @code{nil}. + +If this function is called more than once for the same @var{tabname}, +subsequent calls add the definitions in @var{definitions} to +@var{tabname}, rather than overriding the entire original contents. +(A subsequent call only overrides abbrevs explicitly redefined or +undefined in @var{definitions}.) @end defun @defvar abbrev-table-name-list @@ -100,38 +120,24 @@ named @var{name}. The argument @var{name} is a symbol whose value is an abbrev table. The return value is always @code{nil}. If @var{human} is non-@code{nil}, the description is human-oriented. -Otherwise the description is a Lisp expression---a call to -@code{define-abbrev-table} that would define @var{name} exactly as it -is currently defined. +System abbrevs are listed and identified as such. Otherwise the +description is a Lisp expression---a call to @code{define-abbrev-table} +that would define @var{name} as it is currently defined, but without +the system abbrevs. (The mode or package using @var{name} is supposed +to add these to @var{name} separately.) @end defun @node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs @comment node-name, next, previous, up @section Defining Abbrevs - - These functions define an abbrev in a specified abbrev table. -@code{define-abbrev} is the low-level basic function, while -@code{add-abbrev} is used by commands that ask for information from -the user. When major modes predefine standard abbrevs, they should -call @code{define-abbrev} and specify @code{t} for @var{system-flag}. - -@defun add-abbrev table type arg -This function adds an abbreviation to abbrev table @var{table} based on -information from the user. The argument @var{type} is a string -describing in English the kind of abbrev this will be (typically, -@code{"global"} or @code{"mode-specific"}); this is used in prompting -the user. The argument @var{arg} is the number of words in the -expansion. - -The return value is the symbol that internally represents the new -abbrev, or @code{nil} if the user declines to confirm redefining an -existing abbrev. -@end defun + @code{define-abbrev} is the low-level basic function for defining an +abbrev in a specified abbrev table. When major modes predefine +standard abbrevs, they should call @code{define-abbrev} and specify +@code{t} for @var{system-flag}. @defun define-abbrev table name expansion &optional hook count system-flag This function defines an abbrev named @var{name}, in @var{table}, to -expand to @var{expansion} and call @var{hook}. The return value is a -symbol that represents the abbrev inside Emacs; its name is +expand to @var{expansion} and call @var{hook}. The return value is @var{name}. The value of @var{count}, if specified, initializes the abbrev's @@ -149,13 +155,14 @@ non-@code{nil}, then it is called with no arguments after the abbrev is replaced with @var{expansion}; point is located at the end of @var{expansion} when @var{hook} is called. -If @var{hook} is a non-nil symbol whose @code{no-self-insert} property -is non-@code{nil}, @var{hook} can explicitly control whether to insert -the self-inserting input character that triggered the expansion. If -@var{hook} returns non-@code{nil} in this case, that inhibits insertion -of the character. By contrast, if @var{hook} returns @code{nil}, -@code{expand-abbrev} also returns @code{nil}, as if expansion had not -really occurred. +@cindex @code{no-self-insert} property +If @var{hook} is a non-@code{nil} symbol whose @code{no-self-insert} +property is non-@code{nil}, @var{hook} can explicitly control whether +to insert the self-inserting input character that triggered the +expansion. If @var{hook} returns non-@code{nil} in this case, that +inhibits insertion of the character. By contrast, if @var{hook} +returns @code{nil}, @code{expand-abbrev} also returns @code{nil}, as +if expansion had not really occurred. If @var{system-flag} is non-@code{nil}, that marks the abbrev as a ``system'' abbrev with the @code{system-type} property. @@ -204,9 +211,10 @@ This function does not display any messages. It returns @code{nil}. @end defun @defopt save-abbrevs -A non-@code{nil} value for @code{save-abbrev} means that Emacs should -save abbrevs when files are saved. @code{abbrev-file-name} specifies -the file to save the abbrevs in. +A non-@code{nil} value for @code{save-abbrevs} means that Emacs should +offer the user to save abbrevs when files are saved. If the value is +@code{silently}, Emacs saves the abbrevs without asking the user. +@code{abbrev-file-name} specifies the file to save the abbrevs in. @end defopt @defvar abbrevs-changed @@ -216,11 +224,11 @@ various Emacs commands to offer to save your abbrevs. @end defvar @deffn Command write-abbrev-file &optional filename -Save all abbrev definitions (except ``system'' abbrevs), in all abbrev -tables, in the file @var{filename}, in the form of a Lisp program that -when loaded will define the same abbrevs. If @var{filename} is -@code{nil} or omitted, @code{abbrev-file-name} is used. This function -returns @code{nil}. +Save all abbrev definitions (except ``system'' abbrevs), for all abbrev +tables listed in @code{abbrev-table-name-list}, in the file +@var{filename}, in the form of a Lisp program that when loaded will +define the same abbrevs. If @var{filename} is @code{nil} or omitted, +@code{abbrev-file-name} is used. This function returns @code{nil}. @end deffn @node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs @@ -243,9 +251,10 @@ abbrev table. @defun abbrev-expansion abbrev &optional table This function returns the string that @var{abbrev} would expand into (as -defined by the abbrev tables used for the current buffer). The optional -argument @var{table} specifies the abbrev table to use, as in -@code{abbrev-symbol}. +defined by the abbrev tables used for the current buffer). If +@var{abbrev} is not a valid abbrev, the function returns @code{nil}. +The optional argument @var{table} specifies the abbrev table to use, +as in @code{abbrev-symbol}. @end defun @deffn Command expand-abbrev @@ -260,10 +269,15 @@ returns @code{nil} even though expansion did occur. @end deffn @deffn Command abbrev-prefix-mark &optional arg -Mark current point as the beginning of an abbrev. The next call to -@code{expand-abbrev} will use the text from here to point (where it is -then) as the abbrev to expand, rather than using the previous word as -usual. +This command marks the current location of point as the beginning of +an abbrev. The next call to @code{expand-abbrev} will use the text +from here to point (where it is then) as the abbrev to expand, rather +than using the previous word as usual. + +First, this command expands any abbrev before point, unless @var{arg} +is non-@code{nil}. (Interactively, @var{arg} is the prefix argument.) +Then it inserts a hyphen before point, to indicate the start of the +next abbrev to be expanded. The actual expansion removes the hyphen. @end deffn @defopt abbrev-all-caps @@ -274,9 +288,10 @@ expansion. @end defopt @defvar abbrev-start-location -This is the buffer position for @code{expand-abbrev} to use as the start -of the next abbrev to be expanded. (@code{nil} means use the word -before point instead.) @code{abbrev-start-location} is set to +The value of this variable is a buffer position (an integer or a marker) +for @code{expand-abbrev} to use as the start of the next abbrev to be +expanded. The value can also be @code{nil}, which means to use the +word before point instead. @code{abbrev-start-location} is set to @code{nil} each time @code{expand-abbrev} is called. This variable is also set by @code{abbrev-prefix-mark}. @end defvar @@ -316,35 +331,43 @@ hook, the hook functions receive no arguments. However, they can find the abbrev to be expanded by looking in the buffer before point. Running the hook is the first thing that @code{expand-abbrev} does, and so a hook function can be used to change the current abbrev table before -abbrev lookup happens. +abbrev lookup happens. (Although you have to do this carefully. See +the example below.) @end defvar The following sample code shows a simple use of -@code{pre-abbrev-expand-hook}. If the user terminates an abbrev with a -punctuation character, the hook function asks for confirmation. Thus, -this hook allows the user to decide whether to expand the abbrev, and -aborts expansion if it is not confirmed. +@code{pre-abbrev-expand-hook}. It assumes that @code{foo-mode} is a +mode for editing certain files in which lines that start with @samp{#} +are comments. You want to use Text mode abbrevs for those lines. The +regular local abbrev table, @code{foo-mode-abbrev-table} is +appropriate for all other lines. Then you can put the following code +in your @file{.emacs} file. @xref{Standard Abbrev Tables}, for the +definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}. @smallexample -(add-hook 'pre-abbrev-expand-hook 'query-if-not-space) - -;; @r{This is the function invoked by @code{pre-abbrev-expand-hook}.} - -;; @r{If the user terminated the abbrev with a space, the function does} -;; @r{nothing (that is, it returns so that the abbrev can expand). If the} -;; @r{user entered some other character, this function asks whether} -;; @r{expansion should continue.} - -;; @r{If the user answers the prompt with @kbd{y}, the function returns} -;; @r{@code{nil} (because of the @code{not} function), but that is} -;; @r{acceptable; the return value has no effect on expansion.} - -(defun query-if-not-space () - (if (/= ?\ (preceding-char)) - (if (not (y-or-n-p "Do you want to expand this abbrev? ")) - (error "Not expanding this abbrev")))) +(defun foo-mode-pre-abbrev-expand () + (when (save-excursion (forward-line 0) (eq (char-after) ?#)) + (let ((local-abbrev-table text-mode-abbrev-table) + ;; Avoid infinite loop. + (pre-abbrev-expand-hook nil)) + (expand-abbrev)) + ;; We have already called `expand-abbrev' in this hook. + ;; Hence we want the "actual" call following this hook to be a no-op. + (setq abbrev-start-location (point-max) + abbrev-start-location-buffer (current-buffer)))) + +(add-hook 'foo-mode-hook + #'(lambda () + (add-hook 'pre-abbrev-expand-hook + 'foo-mode-pre-abbrev-expand + nil t))) @end smallexample +Note that @code{foo-mode-pre-abbrev-expand} just returns @code{nil} +without doing anything for lines not starting with @samp{#}. Hence +abbrevs expand normally using @code{foo-mode-abbrev-table} as local +abbrev table for such lines. + @node Standard Abbrev Tables, , Abbrev Expansion, Abbrevs @comment node-name, next, previous, up @section Standard Abbrev Tables @@ -377,3 +400,6 @@ This is the local abbrev table used in Text mode. This is the local abbrev table used in Lisp mode and Emacs Lisp mode. @end defvar +@ignore + arch-tag: 5ffdbe08-2cd4-48ec-a5a8-080f95756eec +@end ignore