GNU bug report logs -
#34150
26.1; Document filtering with `isearch-filter-predicate' in Elisp manual
Previous Next
Reported by: Drew Adams <drew.adams <at> oracle.com>
Date: Mon, 21 Jan 2019 00:18:01 UTC
Severity: normal
Found in version 26.1
Done: Eli Zaretskii <eliz <at> gnu.org>
Bug is archived. No further changes may be made.
Full log
View this message in rfc822 format
[Message part 1 (text/plain, inline)]
Your bug report
#34150: 26.1; Document filtering with `isearch-filter-predicate' in Elisp manual
which was filed against the emacs package, has been closed.
The explanation is attached below, along with your original report.
If you require more details, please reply to 34150 <at> debbugs.gnu.org.
--
34150: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=34150
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems
[Message part 2 (message/rfc822, inline)]
> Date: Sun, 20 Jan 2019 16:17:41 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
>
> See https://emacs.stackexchange.com/q/47302/105, as one possible
> motivaton.
>
> The only doc I can find about making Isearch and `perform-replace' (all
> of its uses) ignore/exclude certain matches is the doc string of
> variable `isearch-filter-predicate'.
I don't see why the doc string shouldn't be enough. This is a quite
obscure feature, so I don't think it warrants to be described in the
manual.
> And that doc string isn't very precise about the args of the predicate.
> It says only: "The function has two arguments: the positions of start
> and end of text matched by the search."
>
> It would help to add that these positions are `(match-beginning 0)' and
> `(match-end 0)', respectively, and to say that the match start position
> is the first of the two args.
To me, "the positions of start and end of the matched text" says
precisely that. I don't see what can references to match-beginning
and match-end add; if anything, they might confuse, because at least
some readers will be sent down the rabbit hole to the descriptions of
those two, something that IMO is entirely unnecessary for writing a
filter.
> It would also be good to state whether predefined search functions such
> as `re-search-forward' respect it. (I imagine that they do not, but I
> haven't checked, and there's no doc about this AFAIK.) You could guess
> no, based on the `isearch' part of the variable name. But if you guess
> like that then you likely won't also guess that the variable applies to
> `perform-replace' - it's not just about Isearch.
I modified the doc string to mention Isearch and replace commands.
> One thing that it would also be good to make extra clear is that
> filtering takes place _after_ input matching; it is not part of
> matching.
How can it be part of matching, if the filter needs to be passed the
limits of the matched text?
[Message part 3 (message/rfc822, inline)]
See https://emacs.stackexchange.com/q/47302/105, as one possible
motivaton.
The only doc I can find about making Isearch and `perform-replace' (all
of its uses) ignore/exclude certain matches is the doc string of
variable `isearch-filter-predicate'.
And that doc string isn't very precise about the args of the predicate.
It says only: "The function has two arguments: the positions of start
and end of text matched by the search."
It would help to add that these positions are `(match-beginning 0)' and
`(match-end 0)', respectively, and to say that the match start position
is the first of the two args. (Sure, start coming first is not
surprising, but it also doesn't follow from the description.)
I suggest adding a short topic about filtering with this predicate,
perhaps with a simple example. At least mention that this is used in
the predefined search commands (including Isearch) and the predefined
replacement commands.
It would also be good to state whether predefined search functions such
as `re-search-forward' respect it. (I imagine that they do not, but I
haven't checked, and there's no doc about this AFAIK.) You could guess
no, based on the `isearch' part of the variable name. But if you guess
like that then you likely won't also guess that the variable applies to
`perform-replace' - it's not just about Isearch.
One thing that it would also be good to make extra clear is that
filtering takes place _after_ input matching; it is not part of
matching. Not getting this can be a gotcha with greedy regexp matching.
For example, a filter predicate that excludes matches that extend past
column 70 does not keep the part of a match before column 70, even if
that part also matches the same regexp.
In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 10.0.17134
Configured using:
`configure --without-dbus --host=x86_64-w64-mingw32
--without-compress-install 'CFLAGS=-O2 -static -g3''
This bug report was last modified 6 years and 125 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.