GNU bug report logs -
#37488
27.0.50; Inconsistent naming of arg of `text-property-search-forward' and `-backward'
Previous Next
Full log
Message #52 received at 37488 <at> debbugs.gnu.org (full text, mbox):
Eli Zaretskii <eliz <at> gnu.org> writes:
>> > . The original doc string said about nil as PREDICATE:
>> >
>> > `nil' means almost the same as \"not equal\", but will also
>> > end the match if the value of PROPERTY changes.
>> >
>> > What does it mean to "end the match if the value changes"? The
>> > text went on to say "See the manual for extensive examples", but
>> > the manual doesn't mention this aspect of nil, it just says "not
>> > equal".
>>
>> If point is inside a region where PROPERTY has a non-nil value, using
>> nil as the predicate will end the search when PROPERTY changes value.
>
> OK, but then it should be obvious, and explicitly mentioning that in
> the doc string just makes it more confusing. Or am I missing
> something?
It's not obvious -- it's the difference between nil and a lambda that
just says (not (equal...)).
I think the manual needs those copious examples that I apparently forgot
to write.
It's probably easier to understand if you go to a buffer like this:
(defun text-property-setup ()
(insert "This is "
(propertize "bold1" 'face 'bold)
" and this is "
(propertize "italic1" 'face 'italic)
(propertize "bold2" 'face 'bold)
(propertize "italic2" 'face 'italic)
" at the end")
(goto-char (point-min)))
and see the difference between
(text-property-search-forward 'face 'bold nil)
and
(text-property-search-forward 'face 'bold
(lambda (val p-val) (not (equal val p-val))))
The latter will stop every time 'face changes, while the former stops in
a way that segments the buffer in all the regions that have not 'face
'bold.
>> > . The doc string stated:
>> >
>> > If NOT-CURRENT, if the match is under point, it will not be
>> > returned, but instead the next instance is returned, if any.
>> >
>> > But the code, AFAIU, just checks whether the value of PROPERTY at
>> > point matches that of the found region, which doesn't necessarily
>> > mean point is part of the region, it could just mean there are two
>> > regions with matching values of PROPERTY, and point belongs to one
>> > of them. Right?
>>
>> I'm not sure I understand the question...
>
> The code doesn't seem to make sure point is inside the same region as
> the one found by the initial attempt, it just compares the values of
> PROPERTY at point and in the found region, and if they match, it looks
> for another region. Is that a correct description of what the code
> does when NOT-CURRENT is non-nil?
Yes.
> If the description is correct, then the doc string doesn't describe
> what the code does accurately.
I think that's what the current doc string also says, but perhaps not
clearly enough.
>> What it's meant to do is basically how TAB works in buttons, which is a
>> common use case. If you're looking for "o", and point is where "|" is
>> below, then it'll find the last "oo" section after the x-es:
>>
>> oo|oxxxxxoo
>
> What does "o" stand for in this case?
Text with "o" as the property.
>> > . What is the reason for having VALUE an optional argument? Is it a
>> > frequent/useful operation to look for a VALUE of nil?
>>
>> If PREDICATE is nil, then having to use an explicit nil VALUE isn't
>> necessary.
>
> I don't understand how this answers my questions.
Try (text-property-search-forward 'face) on the example. It'll give you
all regions that has a face property.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
This bug report was last modified 5 years and 294 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.