Re: project.el semantics

[Stephen Leake]

Dmitry Gutov <address@hidden> writes:

> On 11/13/2015 12:04 AM, Dmitry Gutov wrote:
>
>> Please feel free to submit a patch across these lines (adding
>> project-metadata). It might be moot now, given that John decided to pull
>> project.el from Emacs 25.1, but it could at least serve as a point of
>> comparison for his project API proposal.
>
> Scratch that. John and I had a chat, and it seems project.el has a
> chance in Emacs 25.1, provided it's changed along the lines we've been
> discussing here.
>
> I've had some thoughts since.
>
> Some minor things:
>
> - We'll probably want to rename `project-roots' to
> `project-directories'. Even though they'll be treated like "roots"
> (traversed recursively) most of the time, a project backend can return
> different kinds of directories in this list, including certain
> subdirectories of the project root(s).
>
> For instance, in can include the test roots in there. Or, I don't
> know, some other kinds of directories that aren't supposed to be
> traversed recursively.

Then it also needs to indicate which are recursive and which aren't. One
way is to return a cons (recursive-dirs . non-recursive-dirs).

What is the use case for this?

We have two major use cases for "the list of directories in a project":

1) call "find" in an external process - this wants only the roots,
   together with ignores.

2) iterate over each directory in elisp - this wants all the
   directories, one at a time.

1 is satisfied by project-all-roots (ie (append (project-roots prj)
(project-library-roots prj))) and project-ignores. Allowing
project-all-roots to return non-roots breaks this case.

2 is not supported directly. It is not simple to get the list of all
directories from project-all-roots and project-ignores.

For Emacs 25, we should keep this as simple as possible; provide two
functions, one that returns all recursive roots and ignores, another
that returns a non-recursive list of all directories. Backends can
provide whichever is convenient; project.el can convert between them.

> - If we're only documenting the "categories" key inside
> project-metadata, why not have a project-directory-categories method
> instead? We can add the -metadata method, too, now or later.

This should wait for Emacs 26; we don't have a solid proposal.

-- 
-- Stephe