+2012-02-04 Glenn Morris <rgm@gnu.org>
+
+ * text.texi (Buffer Contents):
+ Update filter-buffer-substring description.
+
2012-02-04 Chong Yidong <cyd@gnu.org>
* functions.texi (What Is a Function): Add closures. Mention
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
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'.
*** `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.
+2012-02-04 Glenn Morris <rgm@gnu.org>
+
+ * simple.el (filter-buffer-substring-functions)
+ (buffer-substring-filters, filter-buffer-substring): Doc fixes.
+
2012-02-04 Lars Ljung <lars@matholka.se> (tiny change)
* eshell/esh-ext.el (eshell-windows-shell-file): Match "cmdproxy"
\f
(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.
projects / emacs.git / commitdiff