From: Glenn Morris Date: Tue, 27 May 2014 01:53:45 +0000 (-0700) Subject: Doc updates re filter-buffer-substring X-Git-Tag: emacs-24.3.92~158 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=e9e341bb4bf06b25bc4feb754544c77b0021a3bd;p=emacs.git Doc updates re filter-buffer-substring * lisp/simple.el (filter-buffer-substring-functions) (filter-buffer-substring-function, buffer-substring-filters) (filter-buffer-substring, buffer-substring--filter): Doc fixes. * doc/lispref/text.texi (Buffer Contents): Update for filter-buffer-substring changes. * doc/lispref/hooks.texi: Remove old comment. * etc/NEWS: Related markup. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 75933560739..e4f5c60c2d1 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,5 +1,8 @@ 2014-05-27 Glenn Morris + * text.texi (Buffer Contents): + Update for filter-buffer-substring changes. + * abbrevs.texi (Abbrev Expansion): Update for expand-abbrev changes. * functions.texi (Advising Functions): Standardize menu case. diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi index 19e30163590..9408174872d 100644 --- a/doc/lispref/hooks.texi +++ b/doc/lispref/hooks.texi @@ -243,7 +243,6 @@ completion-at-point-functions completion-list-insert-choice-function deactivate-current-input-method-function describe-current-input-method-function -filter-buffer-substring-functions font-lock-function menu-bar-select-buffer-function read-file-name-function diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 3c70f5f96b0..4c3286adbfc 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -220,15 +220,17 @@ the current buffer, as a string. @end defun @defun filter-buffer-substring start end &optional delete -This function passes the buffer text between @var{start} and @var{end} -through the filter functions specified by the wrapper hook -@code{filter-buffer-substring-functions}, and returns the result. The -obsolete variable @code{buffer-substring-filters} is also consulted. -If both of these variables are @code{nil}, the value is the unaltered -text from the buffer, i.e., what @code{buffer-substring} would -return. - -If @var{delete} is non-@code{nil}, this function deletes the text +This function filters the buffer text between @var{start} and @var{end} +using a function specified by the variable +@code{filter-buffer-substring-function}, and returns the result. + +The default filter function consults the obsolete wrapper hook +@code{filter-buffer-substring-functions}, and the obsolete variable +@code{buffer-substring-filters}. If both of these are @code{nil}, it +returns the unaltered text from the buffer, i.e., what +@code{buffer-substring} would return. + +If @var{delete} is non-@code{nil}, the function deletes the text between @var{start} and @var{end} after copying it, like @code{delete-and-extract-region}. @@ -236,20 +238,29 @@ Lisp code should use this function instead of @code{buffer-substring}, @code{buffer-substring-no-properties}, or @code{delete-and-extract-region} when copying into user-accessible data structures such as the kill-ring, X clipboard, and registers. -Major and minor modes can add functions to -@code{filter-buffer-substring-functions} to alter such text as it is -copied out of the buffer. +Major and minor modes can modify @code{filter-buffer-substring-function} +to alter such text as it is copied out of the buffer. @end defun -@c FIXME: `filter-buffer-substring-function' should be documented. +@defvar filter-buffer-substring-function +The value of this variable is a function that @code{filter-buffer-substring} +will call to do the actual work. The function receives three +arguments, the same as those of @code{filter-buffer-substring}, +which it should treat as per the documentation of that function. It +should return the filtered text (and optionally delete the source text). +@end defvar + +@noindent The following two variables are obsoleted by +@code{filter-buffer-substring-function}, but are still supported for +backward compatibility. + @defvar filter-buffer-substring-functions -This variable is a wrapper hook (@pxref{Running Hooks}), whose members -should be functions that accept four arguments: @var{fun}, -@var{start}, @var{end}, and @var{delete}. @var{fun} is a function -that takes three arguments (@var{start}, @var{end}, and @var{delete}), -and returns a string. In both cases, the @var{start}, @var{end}, and -@var{delete} arguments are the same as those of -@code{filter-buffer-substring}. +This obsolete variable is a wrapper hook, whose members should be functions +that accept four arguments: @var{fun}, @var{start}, @var{end}, and +@var{delete}. @var{fun} is a function that takes three arguments +(@var{start}, @var{end}, and @var{delete}), and returns a string. In +both cases, the @var{start}, @var{end}, and @var{delete} arguments are +the same as those of @code{filter-buffer-substring}. The first hook function is passed a @var{fun} that is equivalent to the default operation of @code{filter-buffer-substring}, i.e., it @@ -263,14 +274,12 @@ hook functions acting in sequence. @end defvar @defvar buffer-substring-filters -This variable is obsoleted by -@code{filter-buffer-substring-functions}, but is still supported for -backward compatibility. Its value should should be a list of -functions which accept a single string argument and return another -string. @code{filter-buffer-substring} passes the buffer substring to -the first function in this list, and the return value of each function -is passed to the next function. The return value of the last function -is passed to @code{filter-buffer-substring-functions}. +The value of this obsolete variable should be a list of functions +that accept a single string argument and return another string. +The default @code{filter-buffer-substring} function passes the buffer +substring to the first function in this list, and the return value of +each function is passed to the next function. The return value of the +last function is passed to @code{filter-buffer-substring-functions}. @end defvar @defun current-word &optional strict really-word diff --git a/etc/NEWS b/etc/NEWS index 6dafa37711c..c272660af1b 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1361,6 +1361,7 @@ This is like the old `eval-after-load', but better behaved. *** `generic-make-keywords-list' *** `get-upcase-table' (use `case-table-get-table' instead). ++++ ** `with-wrapper-hook' is obsoleted by `add-function'. The few hooks that used with-wrapper-hook are replaced as follows: *** `abbrev-expand-function' obsoletes `abbrev-expand-functions'. diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 13f68a4f476..1b886000014 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,5 +1,9 @@ 2014-05-27 Glenn Morris + * simple.el (filter-buffer-substring-functions) + (filter-buffer-substring-function, buffer-substring-filters) + (filter-buffer-substring, buffer-substring--filter): Doc fixes. + * minibuffer.el (completion-in-region-functions, completion-in-region) (completion--in-region): Doc fixes. diff --git a/lisp/simple.el b/lisp/simple.el index 4e10de77964..f8499744194 100644 --- a/lisp/simple.el +++ b/lisp/simple.el @@ -3463,46 +3463,50 @@ These commands include \\[set-mark-command] and \\[start-kbd-macro]." (defvar filter-buffer-substring-functions nil - "This variable is a wrapper hook around `filter-buffer-substring'.") + "This variable is a wrapper hook around `buffer-substring--filter'.") (make-obsolete-variable 'filter-buffer-substring-functions 'filter-buffer-substring-function "24.4") (defvar filter-buffer-substring-function #'buffer-substring--filter "Function to perform the filtering in `filter-buffer-substring'. -The function is called with 3 arguments: -\(BEG END DELETE). The arguments BEG, END, and DELETE are the same -as those of `filter-buffer-substring' in each case. -It should return the buffer substring between BEG and END, after filtering.") +The function is called with the same 3 arguments (BEG END DELETE) +that `filter-buffer-substring' received. It should return the +buffer substring between BEG and END, after filtering. If DELETE is +non-nil, it should delete the text between BEG and END from the buffer.") (defvar buffer-substring-filters nil - "List of filter functions for `filter-buffer-substring'. -Each function must accept a single argument, a string, and return -a string. The buffer substring is passed to the first function -in the list, and the return value of each function is passed to -the next. + "List of filter functions for `buffer-substring--filter'. +Each function must accept a single argument, a string, and return a string. +The buffer substring is passed to the first function in the list, +and the return value of each function is passed to the next. As a special convention, point is set to the start of the buffer text -being operated on (i.e., the first argument of `filter-buffer-substring') +being operated on (i.e., the first argument of `buffer-substring--filter') before these functions are called.") (make-obsolete-variable 'buffer-substring-filters 'filter-buffer-substring-function "24.1") (defun filter-buffer-substring (beg end &optional delete) "Return the buffer substring between BEG and END, after filtering. -The hook `filter-buffer-substring-function' performs the actual filtering. -By default, no filtering is done. - -If DELETE is non-nil, the text between BEG and END is deleted -from the buffer. - -This function should be used instead of `buffer-substring', -`buffer-substring-no-properties', or `delete-and-extract-region' -when you want to allow filtering to take place. For example, -major or minor modes can use `filter-buffer-substring-function' to -extract characters that are special to a buffer, and should not -be copied into other buffers." +If DELETE is non-nil, delete the text between BEG and END from the buffer. + +This calls the function that `filter-buffer-substring-function' specifies +\(passing the same three arguments that it received) to do the work, +and returns whatever it does. The default function does no filtering, +unless a hook has been set. + +Use `filter-buffer-substring' instead of `buffer-substring', +`buffer-substring-no-properties', or `delete-and-extract-region' when +you want to allow filtering to take place. For example, major or minor +modes can use `filter-buffer-substring-function' to extract characters +that are special to a buffer, and should not be copied into other buffers." (funcall filter-buffer-substring-function beg end delete)) (defun buffer-substring--filter (beg end &optional delete) + "Default function to use for `filter-buffer-substring-function'. +Its arguments and return value are as specified for `filter-buffer-substring'. +This respects the wrapper hook `filter-buffer-substring-functions', +and the abnormal hook `buffer-substring-filters'. +No filtering is done unless a hook says to." (with-wrapper-hook filter-buffer-substring-functions (beg end delete) (cond ((or delete buffer-substring-filters)