Add cl-defgeneric project-name; first use case eglot

Add cl-defgeneric project-name; first use case eglot

[Stephen Leake]

eglot builds a name for a server using the root directory of the
project - in effect:

(file-name-base (directory-file-name (project-root (project-current))))

That name shows up in the elgot mode line, to tell the user which server
the buffer is connected to, in progress report messages, and in the name
of the EGLOT log buffer, which is useful for debugging things.

If the project root directory happens to have a meaningful name, that's
fine. In my use cases, it's usually not meaningful. For example, I have
two worktrees of my wisitoken project, one for the main branch, one for
a work branch. The eglot names, and the ones I'd like to see, are:

    default     desired
    "build"     "wisitoken main"
    "build"     "wisitoken work"

Similarly, the name for the ada_language_server worktree is:

    "gnat"      "als main"

There are probably other situations where providing a more meaningful
name for a project would be useful.

So I'd like to add a new cl-defgeneric to project.el:

(cl-defgeneric project-name (project)
  "A human-readable name for the project."
  (file-name-base (directory-file-name (project-root project))))

Then I can override that in my projects, and eglot will use my desired
name.

-- 
-- Stephe

Re: [SPAM UNSURE] Add cl-defgeneric project-name; first use case eglot

[Stephen Leake]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

> eglot builds a name for a server using the root directory of the
> project - in effect:
>
> (file-name-base (directory-file-name (project-root (project-current))))
>
> That name shows up in the elgot mode line, to tell the user which server
> the buffer is connected to, in progress report messages, and in the name
> of the EGLOT log buffer, which is useful for debugging things.
>
> If the project root directory happens to have a meaningful name, that's
> fine. In my use cases, it's usually not meaningful. For example, I have
> two worktrees of my wisitoken project, one for the main branch, one for
> a work branch. The eglot names, and the ones I'd like to see, are:
>
>     default     desired
>     "build"     "wisitoken main"
>     "build"     "wisitoken work"
>
> Similarly, the name for the ada_language_server worktree is:
>
>     "gnat"      "als main"
>
> There are probably other situations where providing a more meaningful
> name for a project would be useful.
>
> So I'd like to add a new cl-defgeneric to project.el:
>
> (cl-defgeneric project-name (project)
>   "A human-readable name for the project."
>   (file-name-base (directory-file-name (project-root project))))
>
> Then I can override that in my projects, and eglot will use my desired
> name.

There is an old bug report for this:
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=48747

-- 
-- Stephe

Re: [SPAM UNSURE] Add cl-defgeneric project-name; first use case eglot

[Stephen Leake]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

> So I'd like to add a new cl-defgeneric to project.el:
>
> (cl-defgeneric project-name (project)
>   "A human-readable name for the project."
>   (file-name-base (directory-file-name (project-root project))))
>
> Then I can override that in my projects, and eglot will use my desired
> name.

vc projects can add the branch name in the project name.

-- 
-- Stephe

Re: Add cl-defgeneric project-name; first use case eglot

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Cc: João Távora <joaotavora@gmail.com>
> Date: Sun, 20 Nov 2022 14:09:49 -0800
> 
> eglot builds a name for a server using the root directory of the
> project - in effect:
> 
> (file-name-base (directory-file-name (project-root (project-current))))
> 
> That name shows up in the elgot mode line, to tell the user which server
> the buffer is connected to, in progress report messages, and in the name
> of the EGLOT log buffer, which is useful for debugging things.
> 
> If the project root directory happens to have a meaningful name, that's
> fine. In my use cases, it's usually not meaningful.

So Eglot should allow customization of what is shown on the mode line.

> So I'd like to add a new cl-defgeneric to project.el:
> 
> (cl-defgeneric project-name (project)
>   "A human-readable name for the project."
>   (file-name-base (directory-file-name (project-root project))))
> 
> Then I can override that in my projects, and eglot will use my desired
> name.

I don't see why the needs of Eglot usage justify another generic in
project.el, or should be solved in project.el to begin with.  If Dmitry
wants to add such a generic for his own reasons, with some future
development of project.el in mind, I won't object, of course.  Otherwise, it
sounds like the wrong way of solving specific problems: by generalizing the
heck out of them.  E.g., tomorrow we decide that Eglot shouldn't use the
project name on the mode line, and puff! your solution evaporates.

Re: Add cl-defgeneric project-name; first use case eglot

[João Távora]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stephen Leake <stephen_leake@stephe-leake.org>
>> Cc: João Távora <joaotavora@gmail.com>
>> Date: Sun, 20 Nov 2022 14:09:49 -0800
>> 
>> eglot builds a name for a server using the root directory of the
>> project - in effect:
>> 
>> (file-name-base (directory-file-name (project-root (project-current))))
>> 
>> That name shows up in the elgot mode line, to tell the user which server
>> the buffer is connected to, in progress report messages, and in the name
>> of the EGLOT log buffer, which is useful for debugging things.
>> 
>> If the project root directory happens to have a meaningful name, that's
>> fine. In my use cases, it's usually not meaningful.
>
> So Eglot should allow customization of what is shown on the mode line.

Surely Eglot could offer that: a boolean option controlling whether to
show the project's name in the mode-line.  Or a more sophisticated
eglot-mode-line-format in the style of e.g. flymake-mode-line-format so
that multiple other things can be shown or hidden.

As to where Eglot gets the project's human-readable name from, I can't
think of a place other than project.el.  As Stephen explained, currently
Eglot guesses it from the name of the root directory, and that guess
isn't suitable 100% of the time.

So Stephen's suggestion sounds pretty reasonable to me.

João

Re: Add cl-defgeneric project-name; first use case eglot

[Eli Zaretskii]

> From: João Távora <joaotavora@gmail.com>
> Cc: Stephen Leake <stephen_leake@stephe-leake.org>,  emacs-devel@gnu.org
> Date: Mon, 21 Nov 2022 13:50:37 +0000
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > So Eglot should allow customization of what is shown on the mode line.
> 
> Surely Eglot could offer that: a boolean option controlling whether to
> show the project's name in the mode-line.  Or a more sophisticated
> eglot-mode-line-format in the style of e.g. flymake-mode-line-format so
> that multiple other things can be shown or hidden.
> 
> As to where Eglot gets the project's human-readable name from, I can't
> think of a place other than project.el.  As Stephen explained, currently
> Eglot guesses it from the name of the root directory, and that guess
> isn't suitable 100% of the time.

Why are you thinking only about changes related to how the project's name is
spelled out?  What if someone would like to make changes in Eglot's
mode-line indication that have nothing to do with the part of project name?

You see this as a request to customize project.el for some reason, whereas I
see this as a request to customize eglot.el, because the mode-line indicator
is produced by Eglot, and the fact that it currently shows the project name
in some form is not carved in stone.

Re: Add cl-defgeneric project-name; first use case eglot

[João Távora]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: João Távora <joaotavora@gmail.com>
>> Cc: Stephen Leake <stephen_leake@stephe-leake.org>,  emacs-devel@gnu.org
>> Date: Mon, 21 Nov 2022 13:50:37 +0000

> Why are you thinking only about changes related to how the project's name is
> spelled out?

Well, that was the subject of this thread.  Also this is not true, I
just wrote:

>> Or a more sophisticated
>> eglot-mode-line-format in the style of e.g. flymake-mode-line-format so
>> that multiple other things can be shown or hidden.
        ^^^^^^^^^^^^^^^^^^^^^

In other words: I support your idea to let Eglot's mode line be freely
customized by introducing a user-visible eglot-mode-line-format varible.
I'm simply stating that amongst the multiple elements possible in that
list, the element which puts in the project's "human-readable" name can
only logically get that information from project.el's API, which is
currently lacking in this regard.  Plugging that hole was Stephen's
suggestion, which I support.

João

Re: Add cl-defgeneric project-name; first use case eglot

[Kévin Le Gouguec]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stephen Leake <stephen_leake@stephe-leake.org>
>> Cc: João Távora <joaotavora@gmail.com>
>> Date: Sun, 20 Nov 2022 14:09:49 -0800

[...]

>> So I'd like to add a new cl-defgeneric to project.el:
>> 
>> (cl-defgeneric project-name (project)
>>   "A human-readable name for the project."
>>   (file-name-base (directory-file-name (project-root project))))
>> 
>> Then I can override that in my projects, and eglot will use my desired
>> name.
>
> I don't see why the needs of Eglot usage justify another generic in
> project.el, or should be solved in project.el to begin with.  If Dmitry
> wants to add such a generic for his own reasons, with some future
> development of project.el in mind, I won't object, of course.

FWIW, being able to tell project.el "this project is named foobar,
nevermind the path" would help me in a couple of situations:

(1) C-x p p emacs TAB is currently rather crowded, because I stuff a lot
of things under ~/src/emacs: emacs.git worktrees, elpa.git, upstream
repos for *ELPA packages…

If I could "name" projects such that only emacs.git worktrees included
the string "emacs" (rather than all repos under ~/src/emacs), that'd
make completion more efficient.

(2) I'd like to be able to give nicknames to projects.  I could make
project-prompt-project-dir use the flex style to match e.g. "fts" to
"foo-testsuite", but I can think of other nicknames that wouldn't match
(e.g. "xfoo" for "cross-foo").

(3) I'd like to stick (project-name) in my frame-title-format; currently
using "(file-name-base (directory-file-name (project-root
(project-current))))", but my lack of creativity in worktree naming is
biting me in the rear ("ah yes, the “master” project 😐").

Granted, I would still need to come up with my own logic for more
informative project names, but at least I could keep it separate from my
frame-title-format logic.  E.g. if I had different project-naming
conventions for $HOBBIES and $DAYJOB, I could keep frame-title-format in
sync everywhere, but give different machines different project-naming
code.

Granted², I can already define my own indirection layer today; I don't
need to wait for project-name to be introduced.

(4) Similar itch with Magit buffer names:

(info "(magit) Naming Buffers")
https://magit.vc/manual/magit.html#Naming-Buffers

Being able to stick a (project-name) in there (or a "%p") would be
convenient, for the same reasons as frame-title-format: use the same
Magit buffer-name config everywhere; keep project-naming logic
"workplace-bound".


ISTM those look like "use-cases" for teaching project.el about "project
names" untangled from project root paths.  I'd make use of that feature,
regardless of what Eglot does.

(Can't say whether a defgeneric is the most suited technical answer;
FWIW I'd expect my project-naming code to look at various things,
e.g. the project path, the repo's upstream URL, the current branch.  Not
sure it matters much to me whether we use a defgeneric or a
project-name-function, but then I'm not very familiar with generics)

>                                                                Otherwise, it
> sounds like the wrong way of solving specific problems: by generalizing the
> heck out of them.  E.g., tomorrow we decide that Eglot shouldn't use the
> project name on the mode line, and puff! your solution evaporates.

Re: Add cl-defgeneric project-name; first use case eglot

[Dmitry Gutov]

On 22/11/22 11:56, Kévin Le Gouguec wrote:

>> I don't see why the needs of Eglot usage justify another generic in
>> project.el, or should be solved in project.el to begin with.  If Dmitry
>> wants to add such a generic for his own reasons, with some future
>> development of project.el in mind, I won't object, of course.
> 
> FWIW, being able to tell project.el "this project is named foobar,
> nevermind the path" would help me in a couple of situations:

I have just added (efe599df3127) a way to set the project name for VC 
backend through dir-locals.

Not sure if this way will be to your liking, but it's the most 
straightforward. Though I suppose we could also make this variable take 
an alist value, associating root dirs with names.

> (1) C-x p p emacs TAB is currently rather crowded, because I stuff a lot
> of things under ~/src/emacs: emacs.git worktrees, elpa.git, upstream
> repos for *ELPA packages…
> 
> If I could "name" projects such that only emacs.git worktrees included
> the string "emacs" (rather than all repos under ~/src/emacs), that'd
> make completion more efficient.

You're welcome to experiment with project-prompt-project-dir's code. But 
note that until now that function didn't require to "materialize" 
project instances for every entry, it just works off saved directory names.

The feature you have in mind seems to require fetching a project 
instance for every dir and calling 'project-name' on it. The apparent #1 
gotcha would be with remote filesystems where connection is 
slow/impossible, but it might be possible to skip those when computing 
the names.

> (2) I'd like to be able to give nicknames to projects.  I could make
> project-prompt-project-dir use the flex style to match e.g. "fts" to
> "foo-testsuite", but I can think of other nicknames that wouldn't match
> (e.g. "xfoo" for "cross-foo").
> 
> (3) I'd like to stick (project-name) in my frame-title-format; currently
> using "(file-name-base (directory-file-name (project-root
> (project-current))))", but my lack of creativity in worktree naming is
> biting me in the rear ("ah yes, the “master” project 😐").
> 
> Granted, I would still need to come up with my own logic for more
> informative project names, but at least I could keep it separate from my
> frame-title-format logic.  E.g. if I had different project-naming
> conventions for $HOBBIES and $DAYJOB, I could keep frame-title-format in
> sync everywhere, but give different machines different project-naming
> code.
> 
> Granted², I can already define my own indirection layer today; I don't
> need to wait for project-name to be introduced.
> 
> (4) Similar itch with Magit buffer names:
> 
> (info "(magit) Naming Buffers")
> https://magit.vc/manual/magit.html#Naming-Buffers
> 
> Being able to stick a (project-name) in there (or a "%p") would be
> convenient, for the same reasons as frame-title-format: use the same
> Magit buffer-name config everywhere; keep project-naming logic
> "workplace-bound".

Cool. Hopefully the performance of 'project-current' won't make any of 
these applications unfeasible (like the mode-line which has to refresh 
after every change in any buffer, every keypress, etc).

> ISTM those look like "use-cases" for teaching project.el about "project
> names" untangled from project root paths.  I'd make use of that feature,
> regardless of what Eglot does.
> 
> (Can't say whether a defgeneric is the most suited technical answer;
> FWIW I'd expect my project-naming code to look at various things,
> e.g. the project path, the repo's upstream URL, the current branch.  Not
> sure it matters much to me whether we use a defgeneric or a
> project-name-function, but then I'm not very familiar with generics)

The general design is we leave it up to the project implementations how 
to implement things internally. E.g. Projectile might already have its 
own way to specify the name. So we don't have any global vars which 
affect what all projects do.

Re: Add cl-defgeneric project-name; first use case eglot

[Juri Linkov]

>> (1) C-x p p emacs TAB is currently rather crowded, because I stuff a lot
>> of things under ~/src/emacs: emacs.git worktrees, elpa.git, upstream
>> repos for *ELPA packages…
>> If I could "name" projects such that only emacs.git worktrees included
>> the string "emacs" (rather than all repos under ~/src/emacs), that'd
>> make completion more efficient.
>
> You're welcome to experiment with project-prompt-project-dir's code. But
> note that until now that function didn't require to "materialize" project
> instances for every entry, it just works off saved directory names.
>
> The feature you have in mind seems to require fetching a project instance
> for every dir and calling 'project-name' on it. The apparent #1 gotcha
> would be with remote filesystems where connection is slow/impossible, but
> it might be possible to skip those when computing the names.

It's possible to add projects names to project--list that it saved in
~/.emacs.d/projects, e.g. '(("~/project/dir/" (name . "Project name")) ...)

Re: Add cl-defgeneric project-name; first use case eglot

[Dmitry Gutov]

On 23/11/22 10:33, Juri Linkov wrote:
>>> (1) C-x p p emacs TAB is currently rather crowded, because I stuff a lot
>>> of things under ~/src/emacs: emacs.git worktrees, elpa.git, upstream
>>> repos for *ELPA packages…
>>> If I could "name" projects such that only emacs.git worktrees included
>>> the string "emacs" (rather than all repos under ~/src/emacs), that'd
>>> make completion more efficient.
>> You're welcome to experiment with project-prompt-project-dir's code. But
>> note that until now that function didn't require to "materialize" project
>> instances for every entry, it just works off saved directory names.
>>
>> The feature you have in mind seems to require fetching a project instance
>> for every dir and calling 'project-name' on it. The apparent #1 gotcha
>> would be with remote filesystems where connection is slow/impossible, but
>> it might be possible to skip those when computing the names.
> It's possible to add projects names to project--list that it saved in
> ~/.emacs.d/projects, e.g. '(("~/project/dir/" (name . "Project name")) ...)

I'm not sure it's a good idea because

a) That breakes the idea that every project type decides things (e.g. 
Projectile has projectile-project-name[-function]).

b) This file is transient. It should be allowed to clear off the 
projects that haven't been used for a while (or just all but 10-20 most 
recently used ones), and if the file contains important info, we won't 
be allowed to do that automatically.

Re: Add cl-defgeneric project-name; first use case eglot

[Kévin Le Gouguec]

Dmitry Gutov <dgutov@yandex.ru> writes:

> On 22/11/22 11:56, Kévin Le Gouguec wrote:
>
>>> I don't see why the needs of Eglot usage justify another generic in
>>> project.el, or should be solved in project.el to begin with.  If Dmitry
>>> wants to add such a generic for his own reasons, with some future
>>> development of project.el in mind, I won't object, of course.
>> FWIW, being able to tell project.el "this project is named foobar,
>> nevermind the path" would help me in a couple of situations:
>
> I have just added (efe599df3127) a way to set the project name for VC backend
> through dir-locals.
>
> Not sure if this way will be to your liking, but it's the most
> straightforward. Though I suppose we could also make this variable take an alist
> value, associating root dirs with names.

Thanks!  So to recap, IIUC now users have a couple of ways to control
how projects are named:

(1) Coding up their own project-name defmethod; AFAIU this is what
Stephen has in mind, when he talked about overriding the default
implementation?

Not very familiar with generic functions yet, so currently going through
"(elisp) Generic Functions" to better understand the mechanics.

(
  Thoughts after experimenting for 5 minutes: my first instinct was to
  specialize methods by regex-matching on (project-root project), but
  that doesn't seem straightforward to do.  AFAICT the defmethod ARGS
  are not in scope when &context EXPR forms are evaluated?  So I can't
  use &context as an "escape hatch" to string-match-p on (project-root
  project).

  IIUC I could define my own "regex" specializer with
  cl-generic-generalizers?  No idea how judicious that is.
)

(2) Through the project-vc-name variable you introduced, using either
.dir-locals.el files or directory classes.


(Neither here nor there, but: I was surprised to see project-name go in
master "so soon"; OT1H I realize that some discussion had already
happened in bug#48747, OTOH I wouldn't have expected this feature to be
committed before the emacs-29 branch was cut, since that pretty much
"cements" the current design, to some extent?)

>> (1) C-x p p emacs TAB is currently rather crowded, because I stuff a lot
>> of things under ~/src/emacs: emacs.git worktrees, elpa.git, upstream
>> repos for *ELPA packages…
>> If I could "name" projects such that only emacs.git worktrees included
>> the string "emacs" (rather than all repos under ~/src/emacs), that'd
>> make completion more efficient.
>
> You're welcome to experiment with project-prompt-project-dir's code. But note
> that until now that function didn't require to "materialize" project instances
> for every entry, it just works off saved directory names.
>
> The feature you have in mind seems to require fetching a project instance for
> every dir and calling 'project-name' on it. The apparent #1 gotcha would be with
> remote filesystems where connection is slow/impossible, but it might be possible
> to skip those when computing the names.

Point taken.

>> [… KLG: lots of my vaporware elided …]
>
> Cool. Hopefully the performance of 'project-current' won't make any of these
> applications unfeasible (like the mode-line which has to refresh after every
> change in any buffer, every keypress, etc).

Hopefully 🤞  As an anecdata point, I've had project-current in my
frame-title-format for years, with no ill effects.

(<87h7vy9wrv.fsf@gmail.com> is the only time I remember experiencing any
kind of impact, and you dealt with it swiftly enough 🙇)

>> ISTM those look like "use-cases" for teaching project.el about "project
>> names" untangled from project root paths.  I'd make use of that feature,
>> regardless of what Eglot does.
>> (Can't say whether a defgeneric is the most suited technical answer;
>> FWIW I'd expect my project-naming code to look at various things,
>> e.g. the project path, the repo's upstream URL, the current branch.  Not
>> sure it matters much to me whether we use a defgeneric or a
>> project-name-function, but then I'm not very familiar with generics)
>
> The general design is we leave it up to the project implementations how to
> implement things internally. E.g. Projectile might already have its own way to
> specify the name. So we don't have any global vars which affect what all
> projects do.

(Noted; if anything, that's one more reason for me to get around to
learning generics)

Re: Add cl-defgeneric project-name; first use case eglot

[Dmitry Gutov]

On 27/11/22 20:47, Kévin Le Gouguec wrote:

>> Not sure if this way will be to your liking, but it's the most
>> straightforward. Though I suppose we could also make this variable take an alist
>> value, associating root dirs with names.
> 
> Thanks!  So to recap, IIUC now users have a couple of ways to control
> how projects are named:
> 
> (1) Coding up their own project-name defmethod; AFAIU this is what
> Stephen has in mind, when he talked about overriding the default
> implementation?
> 
> Not very familiar with generic functions yet, so currently going through
> "(elisp) Generic Functions" to better understand the mechanics.
> 
> (
>    Thoughts after experimenting for 5 minutes: my first instinct was to
>    specialize methods by regex-matching on (project-root project), but
>    that doesn't seem straightforward to do.  AFAICT the defmethod ARGS
>    are not in scope when &context EXPR forms are evaluated?  So I can't
>    use &context as an "escape hatch" to string-match-p on (project-root
>    project).
> 
>    IIUC I could define my own "regex" specializer with
>    cl-generic-generalizers?  No idea how judicious that is.
> )

I suppose you could just write your own override form (copying either 
the default definition, or the specialized one -- e.g. for (head vc)), 
and if you make sure it's evaluated after project.el, you'll use the 
updated definition.

> (2) Through the project-vc-name variable you introduced, using either
> .dir-locals.el files or directory classes.
> 
> 
> (Neither here nor there, but: I was surprised to see project-name go in
> master "so soon"; OT1H I realize that some discussion had already
> happened in bug#48747, OTOH I wouldn't have expected this feature to be
> committed before the emacs-29 branch was cut, since that pretty much
> "cements" the current design, to some extent?)

It's been a long-requested feature, and I haven't seen many comments or 
alternative suggestions. If you find problems, especially conceptual 
ones, please don't hesitate to report.

Also, for a :core package, using parallel branches for development is a 
pain.

>>> [… KLG: lots of my vaporware elided …]
>>
>> Cool. Hopefully the performance of 'project-current' won't make any of these
>> applications unfeasible (like the mode-line which has to refresh after every
>> change in any buffer, every keypress, etc).
> 
> Hopefully 🤞  As an anecdata point, I've had project-current in my
> frame-title-format for years, with no ill effects.
> 
> (<87h7vy9wrv.fsf@gmail.com> is the only time I remember experiencing any
> kind of impact, and you dealt with it swiftly enough 🙇)

Nice! Good to hear that.

>>> ISTM those look like "use-cases" for teaching project.el about "project
>>> names" untangled from project root paths.  I'd make use of that feature,
>>> regardless of what Eglot does.
>>> (Can't say whether a defgeneric is the most suited technical answer;
>>> FWIW I'd expect my project-naming code to look at various things,
>>> e.g. the project path, the repo's upstream URL, the current branch.  Not
>>> sure it matters much to me whether we use a defgeneric or a
>>> project-name-function, but then I'm not very familiar with generics)
>>
>> The general design is we leave it up to the project implementations how to
>> implement things internally. E.g. Projectile might already have its own way to
>> specify the name. So we don't have any global vars which affect what all
>> projects do.
> 
> (Noted; if anything, that's one more reason for me to get around to
> learning generics)

Writing a new project backend might not be a best idea for everyone, 
though, especially if you only wanted to tweak one thing.

So if you don't find a comfortable enough way to customize 
project-name's logic, we can still plug in a var somewhere. E.g. either 
introduce a project-name-default-function, or allow project-vc-name to 
be set to a function as well.