bug#48317: 27.1; text-property-search-forward moves point to end when not found

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Howard Melman]

The documentation of function text-property-search-forward says:

    If not found, return nil and don’t move point.

Yet I find it moves point to eob.

To reproduce in emacs -Q, with point at beginning of *scratch* buffer with
text in it, eval:

(require 'text-property-search)
(text-property-search-forward 'facet 'foo)

point is moved to end of buffer.

I can reporoduce this in GNUS Emacs 27.1 and the macport of 27.2.

Howard

In GNU Emacs 27.1 (build 1, x86_64-apple-darwin18.7.0, NS appkit-1671.60 Version 10.14.6 (Build 18G95))
 of 2020-08-12 built on builder10-14.porkrind.org
Windowing system distributor 'Apple', version 10.3.1894
System Description:  Mac OS X 10.15.7

Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.
Entering debugger...
Back to top level
Entering debugger...
Back to top level
Type C-x 1 to delete the help window, C-M-v to scroll help.
#s(prop-match 54 201 nil)
Mark activated
read--expression: Command attempted to use minibuffer while in minibuffer
Quit
Quit
Configured using:
 'configure --with-ns '--enable-locallisppath=/Library/Application
 Support/Emacs/${version}/site-lisp:/Library/Application
 Support/Emacs/site-lisp' --with-modules'

Configured features:
NOTIFY KQUEUE ACL GNUTLS LIBXML2 ZLIB TOOLKIT_SCROLL_BARS NS MODULES
THREADS JSON PDUMPER

Important settings:
  value of $LANG: en_US.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message rmc puny dired dired-loaddefs
format-spec rfc822 mml mml-sec password-cache epa derived epg epg-config
gnus-util rmail rmail-loaddefs time-date subr-x mm-decode mm-bodies
mm-encode mail-parse rfc2231 mailabbrev gmm-utils mailheader sendmail
rfc2047 rfc2045 ietf-drums mm-util mail-prsvr mail-utils cl-extra seq
byte-opt gv bytecomp byte-compile cconv flyspell ispell
text-property-search thingatpt help-fns radix-tree cl-print debug
backtrace help-mode easymenu find-func cl-loaddefs cl-lib tooltip eldoc
electric uniquify ediff-hook vc-hooks lisp-float-type mwheel term/ns-win
ns-win ucs-normalize mule-util term/common-win tool-bar dnd fontset
image regexp-opt fringe tabulated-list replace newcomment text-mode
elisp-mode lisp-mode prog-mode register page tab-bar menu-bar
rfn-eshadow isearch timer select scroll-bar mouse jit-lock font-lock
syntax facemenu font-core term/tty-colors frame minibuffer cl-generic
cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao
korean japanese eucjp-ms cp51932 hebrew greek romanian slovak czech
european ethiopic indian cyrillic chinese composite charscript charprop
case-table epa-hook jka-cmpr-hook help simple abbrev obarray
cl-preloaded nadvice loaddefs button faces cus-face macroexp files
text-properties overlay sha1 md5 base64 format env code-pages mule
custom widget hashtable-print-readable backquote threads kqueue cocoa ns
multi-tty make-network-process emacs)

Memory information:
((conses 16 58535 6154)
 (symbols 48 6797 1)
 (strings 32 20507 1782)
 (string-bytes 1 622865)
 (vectors 16 11726)
 (vector-slots 8 142380 15728)
 (floats 8 34 33)
 (intervals 56 320 3)
 (buffers 1000 14))

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Sun, 9 May 2021 12:41:17 -0400
> 
> 
> The documentation of function text-property-search-forward says:
> 
>     If not found, return nil and don’t move point.
> 
> Yet I find it moves point to eob.
> 
> To reproduce in emacs -Q, with point at beginning of *scratch* buffer with
> text in it, eval:
> 
> (require 'text-property-search)
> (text-property-search-forward 'facet 'foo)
> 
> point is moved to end of buffer.

How do you know it "didn't find" in this case? what was the value it
returned?

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Eli Zaretskii]

[Please use Reply All to keep the bug address on the CC list.]

> From: Howard Melman <hmelman@gmail.com>
> Date: Sun, 9 May 2021 13:28:09 -0400
> 
> > On May 9, 2021, at 1:07 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> > 
> >> To reproduce in emacs -Q, with point at beginning of *scratch* buffer with
> >> text in it, eval:
> >> 
> >> (require 'text-property-search)
> >> (text-property-search-forward 'facet 'foo)
> >> 
> >> point is moved to end of buffer.
> > 
> > How do you know it "didn't find" in this case? what was the value it
> > returned?
> 
> It returned (from *Messages*):
> 
> #s(prop-match 75 222 nil)
> 
> I tried again with an explicative-laden property name and the value 'foo and it returned:
> 
> #s(prop-match 77 224 nil)
> 
> If I change 'foo to nil it does not move point.

So in your original use case it _did_ find a match, which is why it
moved point.

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Eli Zaretskii]

[Please use Reply All to keep the bug address on the CC list.]

> From: Howard Melman <hmelman@gmail.com>
> Date: Sun, 9 May 2021 14:10:56 -0400
> 
> >> #s(prop-match 77 224 nil)
> >> 
> >> If I change 'foo to nil it does not move point.
> > 
> > So in your original use case it _did_ find a match, which is why it
> > moved point.
> 
> I don't think any region in the buffer has the property 'ffffffff let alone 
> with the value 'foo so I don't know what it thinks it's found.

What is the difference between "not having a property" and "having a
property with a nil value"?

> I see in the docstring:
> 
> If PREDICATE is nil, a value will match if it is non-nil and
> is NOT equal to VALUE.
> 
> But I don't think this applies because no region in the buffer has this property.

I'm trying to establish whether this is a documentation bug or a code
bug.  For now, I tend to think it's the former.

> Can you reproduce my simple test case?  
> Did it find a region with a random property name?

I don't think I understand the question.

Lars, would you please chime in?  Since you coded this stuff, I'm sure
you will be able to explain its workings much better.

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Howard Melman]

On May 9, 2021, at 2:33 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> [Please use Reply All to keep the bug address on the CC list.]

My apologies.

> What is the difference between "not having a property" and "having a
> property with a nil value"?

I don't think this function should move point in either case.

> I'm trying to establish whether this is a documentation bug or a code
> bug.  For now, I tend to think it's the former.

FWIW, I would have appreciated some less oblique confirmation that you could 
in fact reproduce my problem, particularly since I explicitly asked if you could and
you declined to answer it.

I think it's the latter.  I now see the bug seems to be in the test commented as
"We're standing in the property we're looking for" which is not the case.

My actual use case is trying to find a region with a specific face property.  

  (text-property-search-forward 'face 'my-package-face)

When there's a region with this face it works great.  In the cases where there 
is no region with this face property it moves point and I don't see why it should.
Based on my reading of the manual this is the appropriate function for that use, 
if not I'd appreciate a pointer to one.

In creating a small reproducible test case it turns out it also moves point when 
searching for a non-existing property if passed a value.

Howard

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Lars, would you please chime in?  Since you coded this stuff, I'm sure
> you will be able to explain its workings much better.

I think the doc string is wrong -- you rewrote it in 165890a and further
in df05c26.  The original doc string was correct, I think:

+Some convenience values for PREDICATE can also be used.  `t'
+means the same as `equal'.  `nil' means almost the same as \"not
+equal\", but will also end the match if the value of PROPERTY
+changes.  See the manual for extensive examples.

The code performs as originally documented in the test case from Howard,
as far as I can tell.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Howard Melman]

On May 10, 2021, at 5:05 AM, Lars Ingebrigtsen <larsi@gnus.org> wrote:

> I think the doc string is wrong -- you rewrote it in 165890a and further
> in df05c26.  The original doc string was correct, I think:
> 
> +Some convenience values for PREDICATE can also be used.  `t'
> +means the same as `equal'.  `nil' means almost the same as \"not
> +equal\", but will also end the match if the value of PROPERTY
> +changes.  See the manual for extensive examples.
> 
> The code performs as originally documented in the test case from Howard,
> as far as I can tell.

Ok, setting property to t solves both of my cases.

What threw me (and I still think is problematic) is this line from the docstring:

    If not found, return nil and don't move point.

And this line from the manual:

     If the text property can’t be found, the function returns ‘nil’.

Which I assume also infers point is not moved. If no region has the named property I can't see how it can be found and therefore point should not be moved.  In fact I don't see how predicate even comes into play in this case.  

I still think there's a bug here:

    ;; We're standing in the property we're looking for, so find the
    ;; end.
    ((and (text-property--match-p value (get-text-property (point) property)
                                  predicate)
          (not not-current))
     (text-property--find-end-forward (point) property value predicate))

Because this solves my problem:

    ((and (get-text-property (point) property)
          (text-property--match-p value (get-text-property (point) property)
                                  predicate)
          (not not-current))
     (text-property--find-end-forward (point) property value predicate))

Howard

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Lars Ingebrigtsen]

Howard Melman <hmelman@gmail.com> writes:

> What threw me (and I still think is problematic) is this line from the docstring:
>
>     If not found, return nil and don't move point.
>
> And this line from the manual:
>
>      If the text property can’t be found, the function returns ‘nil’.

I've now fixed the doc string in Emacs 28.

> Which I assume also infers point is not moved. If no region has the
> named property I can't see how it can be found and therefore point
> should not be moved.  In fact I don't see how predicate even comes
> into play in this case.

I'm sorry, I don't follow you.  It this still about

  (text-property-search-forward 'facet 'foo)

?  That works as designed, as far as I can tell.  (But not as documented
in the Emacs 27.1 doc string.)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,  48317@debbugs.gnu.org
> Date: Tue, 11 May 2021 14:32:31 +0200
> 
> Howard Melman <hmelman@gmail.com> writes:
> 
> > What threw me (and I still think is problematic) is this line from the docstring:
> >
> >     If not found, return nil and don't move point.
> >
> > And this line from the manual:
> >
> >      If the text property can’t be found, the function returns ‘nil’.
> 
> I've now fixed the doc string in Emacs 28.

Did you push that?  I don't think I see the change.

Thanks.

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Did you push that?  I don't think I see the change.

I keep forgetting to push, for some reason...  now done.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Howard Melman]

On May 11, 2021, at 8:32 AM, Lars Ingebrigtsen <larsi@gnus.org> wrote:
> 
>> If no region has the named property I can't see how it can be found
>> and therefore point should not be moved.  In fact I don't see how predicate
>> even comes into play in this case.
> 
> I'm sorry, I don't follow you.  It this still about
> 
>  (text-property-search-forward 'facet 'foo)
> 
> ?  That works as designed, as far as I can tell.  (But not as documented
> in the Emacs 27.1 doc string.)

Yes, Note that says "facet" and not "face"

To be more clear, I find when calling:

  (text-property-search-forward 'unused-property 'my-package-face)

when no text in the buffer has the property unused-property, that
calling text-property-search-forward moves point to eob.

Is this intended behavior?  If so I don't understand why. 

If I set the predicate to t point is not moved which is what I want,
but I don't see why that should be the case.  Does Emacs check for
properties with equal?

I think the bug is in the test commented as "We're standing in the
property we're looking for, so find the end" because the test is
matched because

    (get-text-property (point) property)

returns nil and text-property--match-p is called with

    (my-package-face nil nil) 

and returns non-nil.  I don't think this test should match
because point is not in the property unused-property.

Howard

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Lars Ingebrigtsen]

Howard Melman <hmelman@gmail.com> writes:

>> I'm sorry, I don't follow you.  It this still about
>> 
>>  (text-property-search-forward 'facet 'foo)
>> 
>> ?  That works as designed, as far as I can tell.  (But not as documented
>> in the Emacs 27.1 doc string.)
>
> Yes, Note that says "facet" and not "face"

Yes, that the text property you're looking for is called `facet'?

> To be more clear, I find when calling:
>
>   (text-property-search-forward 'unused-property 'my-package-face)
>
> when no text in the buffer has the property unused-property, that
> calling text-property-search-forward moves point to eob.
>
> Is this intended behavior?  If so I don't understand why. 

I'm not sure I understand what you're not understanding.  :-)  You're
using nil as the PREDICATE here (a missing parameter is nil), which
means that you're searching for areas in the buffer where the text
property `facet' is not equal to `foo'.  Which is the rest of the
buffer.

If you're looking for a portion of the buffer where `unused-property' is
`my-package-face', then you should say:

(text-property-search-forward 'unused-property 'my-package-face t)

or

(text-property-search-forward 'unused-property 'my-package-face #'eq)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Howard Melman]

On May 11, 2021, at 12:36 PM, Lars Ingebrigtsen <larsi@gnus.org> wrote:
> 
> Howard Melman <hmelman@gmail.com> writes:
> 
>>> I'm sorry, I don't follow you.  It this still about
>>> 
>>> (text-property-search-forward 'facet 'foo)
>>> 
>>> ?  That works as designed, as far as I can tell.  (But not as documented
>>> in the Emacs 27.1 doc string.)
>> 
>> Yes, Note that says "facet" and not "face"
> 
> Yes, that the text property you're looking for is called `facet'?
> 
>> To be more clear, I find when calling:
>> 
>>  (text-property-search-forward 'unused-property 'my-package-face)
>> 
>> when no text in the buffer has the property unused-property, that
>> calling text-property-search-forward moves point to eob.
>> 
>> Is this intended behavior?  If so I don't understand why. 
> 
> I'm not sure I understand what you're not understanding.  :-)  

I have felt the same way :)  Thanks for your patience.

> You're using nil as the PREDICATE here (a missing parameter is nil), which
> means that you're searching for areas in the buffer where the text
> property `facet' is not equal to `foo'.  Which is the rest of the buffer.

Thank you for explaining the logic and not just saying "working as designed".
"Which is the rest of the buffer." is what clicked for me.

I was reading "text-property-search-forward" as "look forward to find
a text property PROPERTY with value VALUE."  There wasn't one, so the
search should should fail and not move point.  

To me, this function behaves unexpectedly different in these cases
(say in a font-locked elisp buffer just before the last defun):

    ;; a region with property face is found,
    ;; point is moved to the end of it
    (text-property-search-forward 'face)

    ;; a region with property unused is not found,
    ;; point is unmoved
    (text-property-search-forward 'unused)

    ;; a region with the specfied face is found,
    ;; point is moved to the beginning of it
    (text-property-search-forward 'face 'font-lock-function-name-face)

    ;; a region with the specfied face is not found,
    ;; point is moved to eob
    (text-property-search-forward 'face 'unused)

    ;; a region with the specfied property is not found,
    ;; point is moved to eob
    (text-property-search-forward 'unused-prop 'unused-value)

The first two behave perfectly reasonably to me.  And as the manual
suggests, behaves the same as search-forward.

The 3rd does as well, of course.

I'd expect both the 4th and the 5th to behave the same as the 2nd but
they move point to eob.

And while I now mostly understand (but don't fully grok) the logic,
it's baffling to me that to make the last three behave like the first
two I should set PREDICATE to t (and btw doing so changes the behavior
of the 3rd to leave point at the end of the match instead of the
beginning, which seems odd).

The difference between the 3rd and 4th isn't some subtle difference
between using equal and eq or something, it's that the specified value
of the face is not found as it was using the default predicate in the
3rd case.  And particularly in the 5th, the choice of predicate to
evaluate 'unused-value shouldn't come into play because 'unused-prop
itself isn't found.

And the documentation describing PREDICATE nil didn't help me at all.
In the manual it says for nil:

    (which means “not equal”)

which sounds to me as if it is using the function not.  

And in your updated docstring as:

    a value will match if is not `equal' to VALUE

which really throws me because the 3rd case above works and it's 
not "not `equal'" to font-lock-function-name-face!

Does this explain my confusion?

I interpret all of these:

    (search-forward "defun")
    (text-property-search-forward 'face)
    (text-property-search-forward 'face 'font-lock-function-name-face)

to mean search for the thing I specified, whether that's a string, a
specific property with any value or a specific property with a
specific value.  But somehow the last one is different. And try as I
might now to write how it's being interpreted I'm unable to. Search
for the property face but only if it is font-lock-function-name-face
or if it isn't...?

Howard

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Stephen Berman]

On Tue, 11 May 2021 15:28:48 -0400 Howard Melman <hmelman@gmail.com> wrote:

> To me, this function behaves unexpectedly different in these cases
> (say in a font-locked elisp buffer just before the last defun):
>
>     ;; a region with property face is found,
>     ;; point is moved to the end of it
>     (text-property-search-forward 'face)
>
>     ;; a region with property unused is not found,
>     ;; point is unmoved
>     (text-property-search-forward 'unused)
>
>     ;; a region with the specfied face is found,
>     ;; point is moved to the beginning of it
>     (text-property-search-forward 'face 'font-lock-function-name-face)
>
>     ;; a region with the specfied face is not found,
>     ;; point is moved to eob
>     (text-property-search-forward 'face 'unused)
>
>     ;; a region with the specfied property is not found,
>     ;; point is moved to eob
>     (text-property-search-forward 'unused-prop 'unused-value)
>
> The first two behave perfectly reasonably to me.  And as the manual
> suggests, behaves the same as search-forward.
>
> The 3rd does as well, of course.
>
> I'd expect both the 4th and the 5th to behave the same as the 2nd but
> they move point to eob.
>
> And while I now mostly understand (but don't fully grok) the logic,
> it's baffling to me that to make the last three behave like the first
> two I should set PREDICATE to t (and btw doing so changes the behavior
> of the 3rd to leave point at the end of the match instead of the
> beginning, which seems odd).

It's behaving as documented: without t, the search found some other
value of 'face (possibly nil) not equal to 'font-lock-function-name-face
and moved to the end of the thus propertized text, as documented.  You
should see this in the return value (shown as a message), which could be
something like this: #s(prop-match 37 41 nil)

> The difference between the 3rd and 4th isn't some subtle difference
> between using equal and eq or something, it's that the specified value
> of the face is not found as it was using the default predicate in the
> 3rd case.

No, in the third case the search stopped before the specified value was
found.

>            And particularly in the 5th, the choice of predicate to
> evaluate 'unused-value shouldn't come into play because 'unused-prop
> itself isn't found.
>
> And the documentation describing PREDICATE nil didn't help me at all.
> In the manual it says for nil:
>
>     (which means “not equal”)
>
> which sounds to me as if it is using the function not.  
>
> And in your updated docstring as:
>
>     a value will match if is not `equal' to VALUE
>
> which really throws me because the 3rd case above works and it's 
> not "not `equal'" to font-lock-function-name-face!

Again, this is correct: the found value (possibly nil, as illustrated
above) is not equal to 'font-lock-function-name-face.

> Does this explain my confusion?
>
> I interpret all of these:
>
>     (search-forward "defun")
>     (text-property-search-forward 'face)
>     (text-property-search-forward 'face 'font-lock-function-name-face)
>
> to mean search for the thing I specified, whether that's a string, a
> specific property with any value or a specific property with a
> specific value.  But somehow the last one is different. And try as I
> might now to write how it's being interpreted I'm unable to. Search
> for the property face but only if it is font-lock-function-name-face
> or if it isn't...?

In light of the above explanations, is it clearer now?

Steve Berman

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Lars Ingebrigtsen]

Howard Melman <hmelman@gmail.com> writes:

> To me, this function behaves unexpectedly different in these cases
> (say in a font-locked elisp buffer just before the last defun):
>
>     ;; a region with property face is found,
>     ;; point is moved to the end of it
>     (text-property-search-forward 'face)

The doc string in Emacs 27 is misleading, because it doesn't emphasise
the meaning of PREDICATE.

What the form above does is look for areas where there's a text property
named `face' that uses the nil predicate on a nil value.  :-)

That is, it finds all areas where the `face' property is not nil --
VALUE is nil, and PREDICATE is nil.

>     ;; a region with the specfied face is found,
>     ;; point is moved to the beginning of it
>     (text-property-search-forward 'face 'font-lock-function-name-face)

No, here you're looking for regions where `face' is not
`font-lock-function-name-face' -- which will indeed leave you at the
start of the region where `face' is `font-lock-function-name-face', but
that's not really what the function matched.

But I understand your confusion now.  The function searches for areas
where a text property is matching something (according to PREDICATE),
and leaves point at the end of the match.  You, instead, expect it to
leave point at the start of the match, which is the opposite of what it
does.

Hm...  Oh!  That's wrong in the doc string, too -- it says that it moves
point to the start of the region, which it certainly doesn't.  I've now
fixed this in the two doc strings.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Howard Melman]

On May 12, 2021, at 10:16 AM, Lars Ingebrigtsen <larsi@gnus.org> wrote:

> Howard Melman <hmelman@gmail.com> writes:
> 
>>    ;; a region with the specfied face is found,
>>    ;; point is moved to the beginning of it
>>    (text-property-search-forward 'face 'font-lock-function-name-face)
>> 
> No, here you're looking for regions where `face' is not
> `font-lock-function-name-face' -- which will indeed leave you at the
> start of the region where `face' is `font-lock-function-name-face', but
> that's not really what the function matched.

I have read the above a dozen times and still am not sure I follow
it. AIUI since predicate is nil this is looking for regions where face
is not font-lock-function-name-face.  But how does that leave you at
the start of a region where face is indeed
font-lock-function-name-face?  

Is what it's doing leaving you at the end of a region where face isn't
font-lock-function-name-face? (Which thanks to Stephen Berman I
realize that the function leaving you at the beginning or end of a
match was very significant to understanding what was happening).  If
so I think that is not at all intuitive from reading the above line of
code.

> But I understand your confusion now.  

Thank you, I thought I was going crazy.

> The function searches for areas where a text property is matching
> something (according to PREDICATE), and leaves point at the end of the
> match.  You, instead, expect it to leave point at the start of the
> match, which is the opposite of what it does.

I want to be more explicit here.  I do expect it to search for areas
where a text property is matching something.  It of course is
dependent on the value of all of its arguments including PREDICATE,
though I'd expect the default value of PREDICATE to DTRT in the common
case.  I know that common can be misunderstood but for a search
function I thought I was on strong ground that "find the thing I
specify" is the common case.  I don't much care whether this function
leaves you at the start or end of the match, I'd expect to find out
that specific detail from the docstring or observed behavior.  And
usually if I'm lucky I find in the docstring, manual or code some
convenient idiom like your while loop example that makes this choice
very convenient in actual use.

AIUI, all of this confusion is because "leaves you at the end of a not
matching area" and "leaves you at the beginning of a matching area"
happen to be the same place if such an area exists, but is quite
different if it doesn't.

Or could have been avoided if the function was named 
goto-end-of-region-not-matching-text-property
which I *think* is an accurate (though horrible) name?

> Hm...  Oh!  That's wrong in the doc string, too -- it says that it moves
> point to the start of the region, which it certainly doesn't.  I've now
> fixed this in the two doc strings.

It's probably impossible to change in the signature because of
compatibility but perhaps this could inform the docstring.  AIUI if
this function is not passed a VALUE or PREDICATE it searches for
regions that contain PROPERTY (a "trick" because a property having a
nil value is the same as not being present).  But with just a VALUE it
searches for areas that don't have the PROPERTY/VALUE combo because
PREDICATE is nil.  And if PREDICATE is t it searches for areas that do
have that combo.

Since in lisp a default optional argument is nil, I think the behavior
with the default value of PREDICATE is reversed from what it should be
for a function named "search". Particularly since it changes the sense
of the function from when just PROPERTY is passed as opposed to when
PROPERTY and VALUE are passed (right?).

Your example of using this function with a while loop definitely helps
reveal its intended use.  Perhaps including one when passing VALUE to
the function would help?

I will happily commented on a proposed docstring if you post it here.
I've not signed papers but do I have to for docstring contributions?

Thanks.

Howard

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Lars Ingebrigtsen]

Howard Melman <hmelman@gmail.com> writes:

> It's probably impossible to change in the signature because of
> compatibility but perhaps this could inform the docstring.  AIUI if
> this function is not passed a VALUE or PREDICATE it searches for
> regions that contain PROPERTY (a "trick" because a property having a
> nil value is the same as not being present).  But with just a VALUE it
> searches for areas that don't have the PROPERTY/VALUE combo because
> PREDICATE is nil.  And if PREDICATE is t it searches for areas that do
> have that combo.

I think you've gotten how the function works now.  :-)

Except that the nil PREDICATE isn't exactly the same as "not equal" --
in that case, all regions with the same value (that doesn't match) would
be one single match, but the nil PREDICATE also stops when the value
changes.

> Since in lisp a default optional argument is nil, I think the behavior
> with the default value of PREDICATE is reversed from what it should be
> for a function named "search". Particularly since it changes the sense
> of the function from when just PROPERTY is passed as opposed to when
> PROPERTY and VALUE are passed (right?).

The one parameter version is intuitive, while the two parameter version
isn't -- that's true.  And this certainly wasn't helped by the doc
string stating the opposite of how this function worked.  :-)

> Your example of using this function with a while loop definitely helps
> reveal its intended use.  Perhaps including one when passing VALUE to
> the function would help?

I think that's for the manual, which has copious examples and explains
all the bits.  (And has, as far as I can tell, not been corrected to be
wrong while I wasn't looking.  :-))

> I will happily commented on a proposed docstring if you post it here.
> I've not signed papers but do I have to for docstring contributions?

No, that's not necessary -- but is there anything that needs to be
clarified further?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Howard Melman]

On May 12, 2021, at 1:03 PM, Howard Melman <hmelman@gmail.com> wrote:
> 
> On May 12, 2021, at 12:55 PM, Lars Ingebrigtsen <larsi@gnus.org> wrote:
>> 
>>> I will happily commented on a proposed docstring if you post it here.
>>> I've not signed papers but do I have to for docstring contributions?
>> 
>> No, that's not necessary -- but is there anything that needs to be
>> clarified further?
> 
> Just, do I need to sign papers for docstring contributions?  
> I have that question for an unrelated issue.
> 
> Otherwise feel free to close this bug.

FYI, I believe this bug is still open and can be closed.

Howard

bug#48317: 27.1; text-property-search-forward moves point to end when not found

[Lars Ingebrigtsen]

Howard Melman <hmelman@gmail.com> writes:

> FYI, I believe this bug is still open and can be closed.

Yup; I've now closed it.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no