X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/c73bd236f75b742ad4642ec94798987ae6e3e1e8..ea274122d5d221b4d74435c22a48083550ad43c5:/doc/lispref/abbrevs.texi diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi index a52ba2c6c8..90da5aaa48 100644 --- a/doc/lispref/abbrevs.texi +++ b/doc/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, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/abbrevs @node Abbrevs, Processes, Syntax Tables, Top @@ -19,23 +19,27 @@ table}. Each buffer has a local abbrev table, but normally all buffers in the same major mode share one abbrev table. There is also a global abbrev table. Normally both are used. - An abbrev table is represented as an obarray containing a symbol for -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 -@code{count} property and the system-abbrev flag is on the -@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 + An abbrev table is represented as an obarray. @xref{Creating +Symbols}, for information about obarrays. Each abbreviation is +represented by a symbol in the obarray. The symbol's name is the +abbreviation; its value is the expansion; its function definition is +the hook function for performing the expansion (@pxref{Defining +Abbrevs}); and its property list cell contains various additional +properties, including the use count and the number of times the +abbreviation has been expanded (@pxref{Abbrev Properties}). + +@cindex system abbrev + Certain abbrevs, called @dfn{system abbrevs}, are defined by a major +mode instead of the user. A system abbrev is identified by its +non-@code{nil} @code{:system} property (@pxref{Abbrev Properties}). +When abbrevs are saved to an abbrev file, system abbrevs are omitted. +@xref{Abbrev Files}. + + 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}. +extremely nonstandard way. For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev Mode, emacs, The GNU Emacs Manual}. @@ -47,60 +51,68 @@ Mode, emacs, The GNU Emacs Manual}. * Files: Abbrev Files. Saving abbrevs in files. * Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines. * Standard Abbrev Tables:: Abbrev tables used by various major modes. +* Abbrev Properties:: How to read and set abbrev properties. + Which properties have which effect. +* Abbrev Table Properties:: How to read and set abbrev table properties. + Which properties have which effect. @end menu @node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs @comment node-name, next, previous, up @section Setting Up Abbrev Mode - Abbrev mode is a minor mode controlled by the value of the variable + Abbrev mode is a minor mode controlled by the variable @code{abbrev-mode}. -@defvar abbrev-mode -A non-@code{nil} value of this variable turns on the automatic expansion -of abbrevs when their abbreviations are inserted into a buffer. -If the value is @code{nil}, abbrevs may be defined, but they are not -expanded automatically. +@defopt abbrev-mode +If this variable is non-@code{nil}, abbrevs are automatically expanded +in the buffer. If the value is @code{nil}, abbrevs may be defined, +but they are not expanded automatically. This variable automatically becomes buffer-local when set in any fashion. -@end defvar - -@defvar default-abbrev-mode -This is the value of @code{abbrev-mode} for buffers that do not override it. -This is the same as @code{(default-value 'abbrev-mode)}. -@end defvar +@end defopt @node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs @section Abbrev Tables This section describes how to create and manipulate abbrev tables. -@defun make-abbrev-table -This function creates and returns a new, empty abbrev table---an obarray -containing no symbols. It is a vector filled with zeros. +@defun make-abbrev-table &optional props +This function creates and returns a new, empty abbrev table---an +obarray containing no symbols. It is a vector filled with zeros. +@var{props} is a property list that is applied to the new table +(@pxref{Abbrev Table Properties}). @end defun -@defun clear-abbrev-table table -This function undefines all the abbrevs in abbrev table @var{table}, -leaving it empty. It always returns @code{nil}. +@defun abbrev-table-p object +This function returns a non-@code{nil} value if @var{object} is an +abbrev table. @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. +@defun clear-abbrev-table abbrev-table +This function undefines all the abbrevs in @var{abbrev-table}, leaving +it empty. It always returns @code{nil}. @end defun -@defun define-abbrev-table tabname definitions +@defun copy-abbrev-table abbrev-table +This function returns a copy of @var{abbrev-table}---a new abbrev +table containing the same abbrev definitions. There is one difference +between the contents of @var{abbrev-table} and the returned copy: all +abbrevs in the latter have their property lists set to @code{nil}. +@end defun + +@defun define-abbrev-table tabname definitions &optional docstring &rest props 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} @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}. +[@var{hook}] [@var{props}...])}. These elements are passed as +arguments to @code{define-abbrev}. The return value is always +@code{nil}. + +The optional string @var{docstring} is the documentation string of the +variable @var{tabname}. The property list @var{props} is applied to +the abbrev table (@pxref{Abbrev Table Properties}). If this function is called more than once for the same @var{tabname}, subsequent calls add the definitions in @var{definitions} to @@ -130,28 +142,30 @@ to add these to @var{name} separately.) @node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs @comment node-name, next, previous, up @section Defining Abbrevs + @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}. Be aware that any saved non-``system'' abbrevs are -restored at startup, i.e. before some major modes are loaded. Major modes -should therefore not assume that when they are first loaded their abbrev -tables are empty. - -@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 -@var{name}. - -The value of @var{count}, if specified, initializes the abbrev's -usage-count. If @var{count} is not specified or @code{nil}, the use -count is initialized to zero. - -The argument @var{name} should be a string. The argument -@var{expansion} is normally the desired expansion (a string), or -@code{nil} to undefine the abbrev. If it is anything but a string or -@code{nil}, then the abbreviation ``expands'' solely by running -@var{hook}. +abbrev in an abbrev table. + + When a major mode defines a system abbrev, it should call +@code{define-abbrev} and specify a @code{t} for the @code{:system} +property. Be aware that any saved non-``system'' abbrevs are restored +at startup, i.e. before some major modes are loaded. Therefore, major +modes should not assume that their abbrev tables are empty when they +are first loaded. + +@defun define-abbrev abbrev-table name expansion &optional hook &rest props +This function defines an abbrev named @var{name}, in +@var{abbrev-table}, to expand to @var{expansion} and call @var{hook}, +with properties @var{props} (@pxref{Abbrev Properties}). The return +value is @var{name}. The @code{:system} property in @var{props} is +treated specially here: if it has the value @code{force}, then it will +overwrite an existing definition even for a non-``system'' abbrev of +the same name. + +@var{name} should be a string. The argument @var{expansion} is +normally the desired expansion (a string), or @code{nil} to undefine +the abbrev. If it is anything but a string or @code{nil}, then the +abbreviation ``expands'' solely by running @var{hook}. The argument @var{hook} is a function or @code{nil}. If @var{hook} is non-@code{nil}, then it is called with no arguments after the abbrev is @@ -167,17 +181,10 @@ 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. Unless -@var{system-flag} has the value @code{force}, a ``system'' abbrev will -not overwrite an existing definition for a non-``system'' abbrev of the -same name. - -Normally the function @code{define-abbrev} sets the variable +Normally, @code{define-abbrev} sets the variable @code{abbrevs-changed} to @code{t}, if it actually changes the abbrev. (This is so that some commands will offer to save the abbrevs.) It -does not do this for a ``system'' abbrev, since those won't be saved -anyway. +does not do this for a system abbrev, since those aren't saved anyway. @end defun @defopt only-global-abbrevs @@ -225,12 +232,12 @@ offer the user to save abbrevs when files are saved. If the value is @defvar abbrevs-changed This variable is set non-@code{nil} by defining or altering any -abbrevs (except ``system'' abbrevs). This serves as a flag for -various Emacs commands to offer to save your abbrevs. +abbrevs (except system abbrevs). This serves as a flag for 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), for all abbrev +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, @@ -250,9 +257,9 @@ use for communication. This function returns the symbol representing the abbrev named @var{abbrev}. The value returned is @code{nil} if that abbrev is not defined. The optional second argument @var{table} is the abbrev table -to look it up in. If @var{table} is @code{nil}, this function tries -first the current buffer's local abbrev table, and second the global -abbrev table. +in which to look it up. If @var{table} is @code{nil}, this function +tries first the current buffer's local abbrev table, and second the +global abbrev table. @end defun @defun abbrev-expansion abbrev &optional table @@ -274,6 +281,16 @@ function returns @code{nil} as its value, then @code{expand-abbrev} returns @code{nil} even though expansion did occur. @end deffn +@defun abbrev-insert abbrev &optional name start end +This function inserts the abbrev expansion of @code{abbrev}, replacing +the text between @code{start} and @code{end}. If @code{start} is +omitted, it defaults to point. @code{name}, if non-@code{nil}, should +be the name by which this abbrev was found (a string); it is used to +figure out whether to adjust the capitalization of the expansion. The +function returns @code{abbrev} if the abbrev was successfully +inserted. +@end defun + @deffn Command abbrev-prefix-mark &optional arg 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 @@ -329,20 +346,19 @@ has already been unexpanded. This contains information left by @code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command. @end defvar -@c Emacs 19 feature -@defvar pre-abbrev-expand-hook -This is a normal hook whose functions are executed, in sequence, just -before any expansion of an abbrev. @xref{Hooks}. Since it is a normal -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. (Although you have to do this carefully. See -the example below.) +@defvar abbrev-expand-functions +This is a special hook run @emph{around} the @code{expand-abbrev} +function. Each function on this hook is called with a single +argument: a function that performs the normal abbrev expansion. The +hook function can hence do anything it wants before and after +performing the expansion. It can also choose not to call its +argument, thus overriding the default behavior; or it may even call it +several times. The function should return the abbrev symbol if +expansion took place. @end defvar The following sample code shows a simple use of -@code{pre-abbrev-expand-hook}. It assumes that @code{foo-mode} is a +@code{abbrev-expand-functions}. 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 @@ -351,30 +367,22 @@ in your @file{.emacs} file. @xref{Standard Abbrev Tables}, for the definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}. @smallexample -(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)))) +(defun foo-mode-abbrev-expand-function (expand) + (if (not (save-excursion (forward-line 0) (eq (char-after) ?#))) + ;; Performs normal expansion. + (funcall expand) + ;; We're inside a comment: use the text-mode abbrevs. + (let ((local-abbrev-table text-mode-abbrev-table)) + (funcall expand)))) (add-hook 'foo-mode-hook - #'(lambda () - (add-hook 'pre-abbrev-expand-hook - 'foo-mode-pre-abbrev-expand - nil t))) + #'(lambda () + (add-hook 'abbrev-expand-functions + 'foo-mode-abbrev-expand-function + 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 +@node Standard Abbrev Tables, Abbrev Properties, Abbrev Expansion, Abbrevs @comment node-name, next, previous, up @section Standard Abbrev Tables @@ -390,7 +398,16 @@ global table. @defvar local-abbrev-table The value of this buffer-local variable is the (mode-specific) -abbreviation table of the current buffer. +abbreviation table of the current buffer. It can also be a list of +such tables. +@end defvar + +@defvar abbrev-minor-mode-table-alist +The value of this variable is a list of elements of the form +@code{(@var{mode} . @var{abbrev-table})} where @var{mode} is the name +of a variable: if the variable is bound to a non-@code{nil} value, +then the @var{abbrev-table} is active, otherwise it is ignored. +@var{abbrev-table} can also be a list of abbrev tables. @end defvar @defvar fundamental-mode-abbrev-table @@ -406,6 +423,96 @@ 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 +@node Abbrev Properties, Abbrev Table Properties, Standard Abbrev Tables, Abbrevs +@section Abbrev Properties + +Abbrevs have properties, some of which influence the way they work. +You can provide them as arguments to @code{define-abbrev} and you can +manipulate them with the following functions: + +@defun abbrev-put abbrev prop val +Set the property @var{prop} of @var{abbrev} to value @var{val}. +@end defun + +@defun abbrev-get abbrev prop +Return the property @var{prop} of @var{abbrev}, or @code{nil} if the +abbrev has no such property. +@end defun + +The following properties have special meanings: + +@table @code +@item :count +This property counts the number of times the abbrev has +been expanded. If not explicitly set, it is initialized to 0 by +@code{define-abbrev}. + +@item :system +If non-@code{nil}, this property marks the abbrev as a system abbrev. +Such abbrevs are not saved (@pxref{Abbrev Files}). + +@item :enable-function +If non-@code{nil}, this property should be a function of no +arguments which returns @code{nil} if the abbrev should not be used +and @code{t} otherwise. + +@item :case-fixed +If non-@code{nil}, this property indicates that the case of the +abbrev's name is significant and should only match a text with the +same pattern of capitalization. It also disables the code that +modifies the capitalization of the expansion. +@end table + +@node Abbrev Table Properties, , Abbrev Properties, Abbrevs +@section Abbrev Table Properties + +Like abbrevs, abbrev tables have properties, some of which influence +the way they work. You can provide them as arguments to +@code{define-abbrev-table} and you can manipulate them with the +functions: + +@defun abbrev-table-put table prop val +Set the property @var{prop} of abbrev table @var{table} to value @var{val}. +@end defun + +@defun abbrev-table-get table prop +Return the property @var{prop} of abbrev table @var{table}, or @code{nil} +if the abbrev has no such property. +@end defun + +The following properties have special meaning: + +@table @code +@item :enable-function +This is like the @code{:enable-function} abbrev property except that +it applies to all abbrevs in the table and is used even before trying +to find the abbrev before point so it can dynamically modify the +abbrev table. + +@item :case-fixed +This is like the @code{:case-fixed} abbrev property except that it +applies to all abbrevs in the table. + +@item :regexp +If non-@code{nil}, this property is a regular expression that +indicates how to extract the name of the abbrev before point before +looking it up in the table. When the regular expression matches +before point, the abbrev name is expected to be in submatch 1. +If this property is @code{nil}, @code{expand-function} defaults to +@code{"\\<\\(\\w+\\)\\W"}. This property allows the use of abbrevs +whose name contains characters of non-word syntax. + +@item :parents +This property holds the list of tables from which to inherit +other abbrevs. + +@item :abbrev-table-modiff +This property holds a counter incremented each time a new abbrev is +added to the table. + +@end table + + @ignore arch-tag: 5ffdbe08-2cd4-48ec-a5a8-080f95756eec @end ignore