--- Begin Message ---
|
Subject: |
26.1; Document filtering with `isearch-filter-predicate' in Elisp manual |
|
Date: |
Sun, 20 Jan 2019 16:17:41 -0800 (PST) |
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''
--- End Message ---
--- Begin Message ---
|
Subject: |
Re: bug#34150: 26.1; Document filtering with `isearch-filter-predicate' in Elisp manual |
|
Date: |
Mon, 21 Jan 2019 18:21:22 +0200 |
> Date: Sun, 20 Jan 2019 16:17:41 -0800 (PST)
> From: Drew Adams <address@hidden>
>
> 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?
--- End Message ---