Commit 34c99998 authored by Glenn Morris's avatar Glenn Morris
Browse files

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.
parent 79c1cc1e
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
......
......@@ -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
......
......@@ -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.
......
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"
......
......@@ -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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment