Re: project.el semantics

[Dmitry Gutov <dgutov@yandex.ru>]

On 11/21/2015 12:03 PM, Stephen Leake wrote:

>> 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).

Those will be directories of different kinds, and the "non-recursive" 
(or, most-likely) "non-traversable" status would be reflected in their 
category name.

For instance, some directory might contain the key config files of the 
project; its category, then, will be "config-file-are-here".

I'm not sure it would be a good idea to have two directories belonging 
to the same set of categories, that the callers would have to treat 
differently WRT traversal.

> What is the use case for this?

For instance, in addition to the "project root" (let's imagine there's 
just one root), a Java project can have an src and test directories 
inside it. The backend could report that "src" belongs to the 
"source-roots" category, and "test" belongs to "test-roots" category.

Then, provided there is a stable test file naming convention, we could 
define commands that would allow the user to jump between the source 
file and its test, and perform other related operations.

> 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.

Basically, the caller would have to pass the returned value through 
`project-combine-directory'. Alternatively, we can have a helper like this:

(defun project-directories-in-categories (project &rest categories)
   (project-combine-directories
    (cl-delete-if-not
     (lambda (dir)
       (cl-subsetp categories (project-categories project dir)))
     (project-directories project))))

Or, as yet another option, we can define `project-directories' to have 
this signature, and the project backend to implement it. But I'd prefer 
to have the helper.

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

I'm not convinced it's actually needed. Like discussed previously, the 
capability encourages slower implementations. Instead, where possible, 
the API consumers should combine 'find' with other programs.

Even so, while it's "not simple", it perfectly possible to implement it 
on top of the API. So we can include it as a utility function, but 
there's no need to make it a method, for a backend to implement.

> 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.

And I'm against that:

a) See above.

b) Having only these two functions won't make it possible to have both 
project-find-regexp and project-or-libraries-find-regexp (or whatever 
its name will be). I've explained why its beneficial to have both, and 
the distinction 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.

I thought the idea is pretty simple. What would you like me to clarify?