Commit e9e341bb authored by Glenn Morris's avatar Glenn Morris

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.
parent 4a12fa5c
2014-05-27 Glenn Morris <rgm@gnu.org>
* 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.
......
......@@ -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
......
......@@ -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
......
......@@ -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'.
......
2014-05-27 Glenn Morris <rgm@gnu.org>
* 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.
......
......@@ -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)
......
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