bug#48747: 28.0.50; add project-name generic

bug#48747: 28.0.50; add project-name generic

[Stephen Leake]

In project.el, add a 'project-name' cl-defgeneric, to be used in prompts
and other situations where the user is asked to identify a project.

It must return a string, which is nominally unique among the user's
various projects.

The default could be 'project-root'.
-- 
-- Stephe

bug#48747: 28.0.50; add project-name generic

[Dmitry Gutov]

Hi Stephen,

On 30.05.2021 20:38, Stephen Leake wrote:
> In project.el, add a 'project-name' cl-defgeneric, to be used in prompts
> and other situations where the user is asked to identify a project.
> 
> It must return a string, which is nominally unique among the user's
> various projects.
> 
> The default could be 'project-root'.

Would you like to attach a patch that includes the places where we would 
use the new method?

project-prefixed-buffer-name?

I was also thinking project-prompt-project-dir, but we use absolute 
directory names there, so it seems difficult to incorporate, even if we 
agree to rename and update the docstring: the default implementation of 
'project-name' will supposedly be the base name of the root dir, and 
those are not always unique and easy to recognize.

Or, if the default impl returns the absolute directory name, we couldn't 
use it in project-prefixed-buffer-name.

bug#48747: 28.0.50; add project-name generic

[Lars Ingebrigtsen]

Dmitry Gutov <dgutov@yandex.ru> writes:

>> In project.el, add a 'project-name' cl-defgeneric, to be used in prompts
>> and other situations where the user is asked to identify a project.
>> It must return a string, which is nominally unique among the user's
>> various projects.
>> The default could be 'project-root'.
>
> Would you like to attach a patch that includes the places where we
> would use the new method?
>
> project-prefixed-buffer-name?

(I'm going through old bug reports that unfortunately weren't resolved
at the time.)

This was a year ago, and the original bug report didn't really include a
rationale for the cl-defgeneric.  Stephen, what would you use this for?

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

bug#48747: 28.0.50; add project-name generic

[Stephen Leake]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Dmitry Gutov <dgutov@yandex.ru> writes:
>
>>> In project.el, add a 'project-name' cl-defgeneric, to be used in prompts
>>> and other situations where the user is asked to identify a project.
>>> It must return a string, which is nominally unique among the user's
>>> various projects.
>>> The default could be 'project-root'.
>>
>> Would you like to attach a patch that includes the places where we
>> would use the new method?
>>
>> project-prefixed-buffer-name?
>
> (I'm going through old bug reports that unfortunately weren't resolved
> at the time.)
>
> This was a year ago, and the original bug report didn't really include a
> rationale for the cl-defgeneric.  Stephen, what would you use this for?

My wisi package has a menu of defined projects, allowing the user to
choose which one is the "current project"; it shows a project name,
which is currently defined in the wisi project type.

wisi also has a command to delete a project definition, which prompts
for a project, completing on the project name.

eglot needs to identify projects; it currently uses the project root,
which is not always the best way.

The current project.el assumes that projects are only identified by
"project-current" in some buffer, so there isn't anywhere in the current
code that would use this. Adding it is mainly for extensions like wisi
and eglot.

-- 
-- Stephe

bug#48747: add project-name generic

[Stephen Leake]

eglot provides a use case:

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"

I could override project-name that in my projects to provide my desired
name, and eglot will use my desired name.

-- 
-- Stephe

bug#48747: add project-name generic

[Dmitry Gutov]

On 21.11.2022 00:17, Stephen Leake wrote:
> 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"
> 
> I could override project-name that in my projects to provide my desired
> name, and eglot will use my desired name.

Okay, that sounds good.

But let's please go back to my question: could we use the new generic in 
project-prompt-project-dir? And should we?

If we do, we'll have to default the return value to

   (abbreviate-file-name (project-root pr))

rather than your suggested

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

. Would you say you intend to override project-name a lot? Or do you 
want to take advantage of the shorter default name in most cases?

What do you think about the first option anyway?

OTOH, it's also possible that some Powerline-style mode-line packages 
might want to use this method as well. And it seems they generally 
prefer the latter look because it's more compact. They currently don't 
show such info, though.

bug#48747: [SPAM UNSURE] Re: bug#48747: add project-name generic

[Stephen Leake]

Dmitry Gutov <dgutov@yandex.ru> writes:

> On 21.11.2022 00:17, Stephen Leake wrote:
>
> But let's please go back to my question: could we use the new generic
> in project-prompt-project-dir? And should we?

project-prompt-project-dir used to chose a project, by choosing a root
directory (in project-current, project-forget-project, and
project-switch-project). (that's not guarranteed to be a one-to-one
mapping, but that's a separate issue). It currently completes on a list
of file names.

Those file names come from project-list-file which relies on users or
clients calling project-remember-project.

It might be useful to include the project name in the completion list
for project-prompt-project-dir, but with the default implementation
returning the abbreviated project root it would only duplicate
information already in the completion table.

Instead, we could have project-prompt-project-by-name, which would
complete on project names. The list of names could also be in
project-list file, with a change in format; also maintained by
project-remember-project.

The functions that ask the user to complete on projects would have to
choose which way to do that; there would have to be a
project-prompt-style defcustom for the user to set.

I think a better design would be for the default project-name to return
nil; then project-prompt-project-dir could use names if they are
non-nil, falling back to abbreviated file names if the project name is
nil. That would allow a mix of named and un-named projects. Eglot could
do the same. project-list-file should store the project name.

In that case, project-prompt-project-dir could be renamed to
project-prompt-project.

> If we do, we'll have to default the return value to
>
>   (abbreviate-file-name (project-root pr))
>
> rather than your suggested
>
>   (file-name-base (directory-file-name (project-root pr)))

That's a reasonable choice; it does not work for the eglot use case.
Which argues for the default to be nil.

I'm not clear why you want this to be the default;
project-prompt-project-dir does not currently use abbreviate-file-name
(perhaps it should?).

> Would you say you intend to override project-name a lot? 

I'm not sure what counts as "a lot" here. All wisi projects have a name
provided by the user, and almost all projects I use are wisi projects.
So yes? On the other hand, I don't have plans to write any new projects
that need names. So no?

> Or do you want to take advantage of the shorter default name in most
> cases?

Deriving the project name from the root directory of the project is not
useful in my use cases. Abbreviating does not make it more useful; the
only useful label is the string provided by the user. And I
have situations where the root directory is the same for two projects;
for example, ada_language_server has main and test projects.

So wisi will continue to store a user provided string in a project
object slot; it will override project-name to return that slot.

Transient projects could also store a name as a plist entry in the
project object: '(transient /a/root/dir :name "wisitoken main")

> What do you think about the first option anyway?

I don't follow; what is "the first option"?

-- 
-- Stephe

bug#48747: [SPAM UNSURE] Re: bug#48747: add project-name generic

[Dmitry Gutov]

On 21/11/22 20:59, Stephen Leake wrote:
> Dmitry Gutov <dgutov@yandex.ru> writes:
> 
>> On 21.11.2022 00:17, Stephen Leake wrote:
>>
>> But let's please go back to my question: could we use the new generic
>> in project-prompt-project-dir? And should we?
> 
> project-prompt-project-dir used to chose a project, by choosing a root
> directory (in project-current, project-forget-project, and
> project-switch-project). (that's not guarranteed to be a one-to-one
> mapping, but that's a separate issue). It currently completes on a list
> of file names.
> 
> Those file names come from project-list-file which relies on users or
> clients calling project-remember-project.

I guess what you might be saying is that the file contains directories 
and not project instances. Thus, going to the project name is a 
non-trivial transition anyway. And for the whole list, potentially costly.

> I think a better design would be for the default project-name to return
> nil; then project-prompt-project-dir could use names if they are
> non-nil, falling back to abbreviated file names if the project name is
> nil. That would allow a mix of named and un-named projects. Eglot could
> do the same. project-list-file should store the project name.

That's a problem: if the default is nil, then for every project the user 
will have to customize it somehow. Otherwise the method is not going to 
be usable. That's not a great workflow from my POV.

If the place where you want to use it in Eglot, currently calls

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

then that is probably the best default after all.

> In that case, project-prompt-project-dir could be renamed to
> project-prompt-project.
> 
>> If we do, we'll have to default the return value to
>>
>>    (abbreviate-file-name (project-root pr))
>>
>> rather than your suggested
>>
>>    (file-name-base (directory-file-name (project-root pr)))
> 
> That's a reasonable choice; it does not work for the eglot use case.
> Which argues for the default to be nil.
> 
> I'm not clear why you want this to be the default;
> project-prompt-project-dir does not currently use abbreviate-file-name
> (perhaps it should?).

Abbreviate or not is a minor detail. Not too important for 
project-prompt-project-dir, but could be more valuable in other 
potential places, such as mode-line, which value compactness.

>> Would you say you intend to override project-name a lot?
> 
> I'm not sure what counts as "a lot" here. All wisi projects have a name
> provided by the user, and almost all projects I use are wisi projects.
> So yes? On the other hand, I don't have plans to write any new projects
> that need names. So no?
> 
>> Or do you want to take advantage of the shorter default name in most
>> cases?
> 
> Deriving the project name from the root directory of the project is not
> useful in my use cases. Abbreviating does not make it more useful; the
> only useful label is the string provided by the user. And I
> have situations where the root directory is the same for two projects;
> for example, ada_language_server has main and test projects.
> 
> So wisi will continue to store a user provided string in a project
> object slot; it will override project-name to return that slot.

That answers my questions, thanks.

> Transient projects could also store a name as a plist entry in the
> project object: '(transient /a/root/dir :name "wisitoken main")

Yes, but, for a transient object, there's nowhere to get the custom name 
from. The user just chooses a directory.

Anyway, I think we can proceed with your original proposal (where the 
default name is the base name of the root directory). Some users of 
project-vc backend will probably want to customize it too, we can add a 
buffer-local variable for that (now or later).

bug#48747: [SPAM UNSURE] Re: bug#48747: add project-name generic

[Stephen Leake]

Done in 361297c6f4be54d4699c588937d7ceb142ba99d7
-- 
-- Stephe

bug#48747: [SPAM UNSURE] Re: bug#48747: add project-name generic

[Dmitry Gutov]

On 22/11/22 21:02, Stephen Leake wrote:
> Done in 361297c6f4be54d4699c588937d7ceb142ba99d7

Thanks Stephen.