About the interpretation of negative integer values for 'priority overlay property

About the interpretation of negative integer values for 'priority overlay property

[Sora Takai]

[-- Attachment #1: Type: text/plain, Size: 1308 bytes --]

According to the manual/reference (
https://www.gnu.org/software/emacs/manual/html_node/elisp/Overlay-Properties.html),
'priority value of an overlay can be either:

1. nil (which would be interpreted as 0)
2. integer value of 1 or higher (i.e. positive integer)
3. (primary . secondary) cons where both of which can take the value of
either (1) or (2).

However, I am seeing cases where negative integers are specified for
overlay 'priority property -- even in a core package like simple.el.

To be specific, these are:

lisp/progmodes/gud.el:3098:                    (overlay-put overlay
'priority -45) ; 5 less than hl-line.
lisp/simple.el:523:        (overlay-put ol 'priority -50)


Now the questions I have is:

1. Are negative 'priority integers interpreted in an intuitive sense?  That
is, would overlays with negative 'priority numbers rank distinctly lower
than anything with higher 'priority values (0 or above)?

2. Are they "valid" in a sense that emacs intends 'priority property to be
(in which case the manual description would have to be changed).


Personally, I think having negative 'priority -- given it works as intended
-- is useful, since I sometimes bump into use cases where I'd like to make
sure certain overlays have the lowest 'priority possible below all others.


Thanks,
Sora

[-- Attachment #2: Type: text/html, Size: 1576 bytes --]

Re: About the interpretation of negative integer values for 'priority overlay property

[Eli Zaretskii]

> From: Sora Takai <booksipadtest@gmail.com>
> Date: Mon, 19 Feb 2024 11:10:42 +0900
> 
> 1. Are negative 'priority integers interpreted in an intuitive sense?  That is, would overlays with negative
> 'priority numbers rank distinctly lower than anything with higher 'priority values (0 or above)?
> 
> 2. Are they "valid" in a sense that emacs intends 'priority property to be (in which case the manual description
> would have to be changed).

Negative priority values are valid, but used internally by Emacs.  So
we don't recommend using them in Lisp programs, as doing so might get
in the way of some Emacs features.

> Personally, I think having negative 'priority -- given it works as intended -- is useful, since I sometimes bump
> into use cases where I'd like to make sure certain overlays have the lowest 'priority possible below all others.

We recommend you not to use these values.

Re: About the interpretation of negative integer values for 'priority overlay property

[Sora Takai]

[-- Attachment #1: Type: text/plain, Size: 1075 bytes --]

Got it - thanks for clarifying!

-Sora

On Mon, Feb 19, 2024 at 9:30 PM Eli Zaretskii <eliz@gnu.org> wrote:

> > From: Sora Takai <booksipadtest@gmail.com>
> > Date: Mon, 19 Feb 2024 11:10:42 +0900
> >
> > 1. Are negative 'priority integers interpreted in an intuitive sense?
> That is, would overlays with negative
> > 'priority numbers rank distinctly lower than anything with higher
> 'priority values (0 or above)?
> >
> > 2. Are they "valid" in a sense that emacs intends 'priority property to
> be (in which case the manual description
> > would have to be changed).
>
> Negative priority values are valid, but used internally by Emacs.  So
> we don't recommend using them in Lisp programs, as doing so might get
> in the way of some Emacs features.
>
> > Personally, I think having negative 'priority -- given it works as
> intended -- is useful, since I sometimes bump
> > into use cases where I'd like to make sure certain overlays have the
> lowest 'priority possible below all others.
>
> We recommend you not to use these values.
>

[-- Attachment #2: Type: text/html, Size: 1528 bytes --]