From 34c999980444dc3aea494fbf87d71d858fbc3f0f Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Sat, 4 Feb 2012 11:48:06 -0800 Subject: [PATCH] Try to document filter-buffer-substring changes * doc/lispref/text.texi (Buffer Contents): Update filter-buffer-substring description. * lisp/simple.el (filter-buffer-substring-functions) (buffer-substring-filters, filter-buffer-substring): Doc fixes. * etc/NEWS: Related edits. --- doc/lispref/ChangeLog | 5 +++++ doc/lispref/text.texi | 52 ++++++++++++++++++++++--------------------- etc/NEWS | 6 +++++ lisp/ChangeLog | 5 +++++ lisp/simple.el | 38 ++++++++++++++++++++++--------- 5 files changed, 71 insertions(+), 35 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index e98e18b864d..ddc459cc50e 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,8 @@ +2012-02-04 Glenn Morris + + * text.texi (Buffer Contents): + Update filter-buffer-substring description. + 2012-02-04 Chong Yidong * functions.texi (What Is a Function): Add closures. Mention diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 448634ba5a7..8e7434de2ed 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -218,44 +218,46 @@ This is like @code{buffer-substring}, except that it does not copy text properties, just the characters themselves. @xref{Text Properties}. @end defun -@defun filter-buffer-substring start end &optional delete noprops +@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 variable -@code{buffer-substring-filters}, and returns the value from the last -filter function. If @code{buffer-substring-filters} is @code{nil}, -the value is the unaltered text from the buffer, what -@code{buffer-substring} would return. +through the filter functions specified by the wrapper hook +@code{filter-buffer-substring-functions}, and returns the final +result of applying all filters. 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, as @code{buffer-substring} would return. If @var{delete} is non-@code{nil}, this function deletes the text between @var{start} and @var{end} after copying it, like @code{delete-and-extract-region}. -If @var{noprops} is non-@code{nil}, the final string returned does not -include text properties, while the string passed through the filters -still includes text properties from the buffer text. - 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{buffer-substring-filters} to alter such text as it is copied out -of the buffer. +@code{filter-buffer-substring-functions} to alter such text as it is +copied out of the buffer. @end defun -@defvar buffer-substring-filters -This variable should be a list of functions that accept a single -argument, a string, and return a 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 -used as the return value of @code{filter-buffer-substring}. - -As a special convention, point is set to the start of the buffer text -being operated on (i.e., the @var{start} argument for -@code{filter-buffer-substring}) before these functions are called. - -If this variable is @code{nil}, no filtering is performed. +@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}. + +The first hook function is passed a @var{fun} that is equivalent to +the default operation of @code{filter-buffer-substring}, i.e. it +returns the buffer-substring between @var{start} and @var{end} +(processed by any @code{buffer-substring-filters}) and optionally +deletes the original text from the buffer. In most cases, the hook +function will call @var{fun} once, and then do its own processing of +the result. The next hook function receives a @var{fun} equivalent to +this, and so on. The actual return value is the result of all the +hook functions acting in sequence. @end defvar @defun buffer-string diff --git a/etc/NEWS b/etc/NEWS index 0a401eb3a3f..98fbc6302dd 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1019,6 +1019,11 @@ similar to the ones created by shift-selection. In previous Emacs versions, these regions were delineated by `mouse-drag-overlay', which has now been removed. ++++ +** The fourth argument of filter-buffer-substring, which says to remove +text properties from the final result, has been removed. +Eg simply pass the result through substring-no-properties if you need this. + --- ** cl.el no longer provides `cl-19'. @@ -1415,6 +1420,7 @@ an empty uninterned symbol. *** `tooltip-use-echo-area' is obsolete. Rather than setting this to t, disable Tooltip mode instead. ++++ *** buffer-substring-filters is obsolete. Use `filter-buffer-substring-functions' instead. diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 888b7e20307..89ce0f67408 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,8 @@ +2012-02-04 Glenn Morris + + * simple.el (filter-buffer-substring-functions) + (buffer-substring-filters, filter-buffer-substring): Doc fixes. + 2012-02-04 Lars Ljung (tiny change) * eshell/esh-ext.el (eshell-windows-shell-file): Match "cmdproxy" diff --git a/lisp/simple.el b/lisp/simple.el index cc56dfe04ce..8bd32a8db8d 100644 --- a/lisp/simple.el +++ b/lisp/simple.el @@ -2914,28 +2914,46 @@ These commands include \\[set-mark-command] and \\[start-kbd-macro]." (defvar filter-buffer-substring-functions nil - "Wrapper hook around `filter-buffer-substring'. -The functions on this special hook are called with four arguments: - NEXT-FUN BEG END DELETE -NEXT-FUN is a function of three arguments (BEG END DELETE) -that performs the default operation. The other three arguments -are like the ones passed to `filter-buffer-substring'.") + "This variable is a wrapper hook around `filter-buffer-substring'. +Each member of the hook should be a function accepting four arguments: +\(FUN BEG END DELETE), where FUN is itself a function of three arguments +\(BEG END DELETE). The arguments BEG, END, and DELETE are the same +as those of `filter-buffer-substring' in each case. + +The first hook function to be called receives a FUN equivalent +to the default operation of `filter-buffer-substring', +i.e. one that returns the buffer-substring between BEG and +END (processed by any `buffer-substring-filters'). Normally, +the hook function will call FUN and then do its own processing +of the result. The next hook function receives a FUN equivalent +to the previous hook function, calls it, and does its own +processing, and so on. The overall result is that of all hook +functions acting in sequence. + +Any hook may choose not to call FUN though, in which case it +effectively replaces the default behavior with whatever it chooses. +Of course, a later hook function may do the same thing.") (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. The return value of the last function is used as the -return value of `filter-buffer-substring'. +the next. The final result (if `buffer-substring-filters' is +nil, this is the unfiltered buffer-substring) is passed to the +first function on `filter-buffer-substring-functions'. -If this variable is nil, no filtering is performed.") +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') +before these functions are called.") (make-obsolete-variable 'buffer-substring-filters 'filter-buffer-substring-functions "24.1") (defun filter-buffer-substring (beg end &optional delete) "Return the buffer substring between BEG and END, after filtering. -The filtering is performed by `filter-buffer-substring-functions'. +The wrapper hook `filter-buffer-substring-functions' performs +the actual filtering. The obsolete variable `buffer-substring-filters' +is also consulted. If both of these are nil, no filtering is done. If DELETE is non-nil, the text between BEG and END is deleted from the buffer. -- 2.39.2