Re: project.el semantics

[Dmitry Gutov]

On 11/12/2015 09:28 PM, Stephen Leake wrote:

> Why define that in the API? Let the user do whatever they want.

Or that. I'm just saying that a project backend probably wouldn't be 
able to tell.

> Clearly, read/write is a useful item. One way the user can set it is via
> .dir-local.

Yeah, maybe.

> I'm assuming the "edited together" comment on `project-roots' implies
> "don't edit" on `project-library-roots'. Thus project-roots is
> read-write, and project-library-roots is read-only.

"Don't edit when working on this project".

> Note that I am not talking about OS level file permissions, but about
> the logical use of those directories in the context of the project.

Very well.

> > Let's be realistic. I doubt most people are going to use arbitrary
> > predicates and searches that only touch some of the library-roots, as
> > well as some of project-roots but other others, often. So we can serve
> > the simplest case first.
>
> I agree. But the simplest case is to always search all the directories
> (ie project-root and project-library-root). You are allowing that, plus
> one other case.

I meant the simplest approach that still allows a certain distinctions, 
like the one we've discussed (read-only/read-write).

> In other words, I also doubt most people will want to search only
> project-roots or only project-library-roots.

I do think that many users would find only searching project-roots 
useful in practice. And that's what IDEs do: when you "search in 
project", you search only the project root(s). Maybe several projects, 
if they're open at the same time (in the same "workspace"), but not 
inside the libraries.

> > The API doesn't factor into it.
>
> That's bad; you should not be able to do something interactively that
> you cannot do programmatically. This should be:
>
> (defun project-find-regexp (regexp &optional dir)
>    "Find all matches for REGEXP in the current project.
> If DIR is non-nil (default prefix arg), search in that instead.
> If DIR is \\[universal-argument], prompts for DIR."

As you can see, you're still able to "do that programmatically". The 
modified project-find-regexp illustrates that, because it's an API 
consumer, not a part of it.

> The prompt for dir should use completing-read on project-roots and
> project-library-roots; project-ignores should not have to cope with dir
> outside that list.

I'd change this requirement as follows: search an arbitrary directory 
inside the project, but use the project-ignores value for the project 
root that it's inside.

There would be some technical issues, such as handling "rooted" ignores 
with find-grep.

> This can also be implemented via a predicate arg to project-find-regexp;
> then project-find-regexp-dir can prompt for a directory and construct
> the appropriate predicate.

I don't really see the need for the word "predicate" to appear anywhere 
near its definition, thus far.

> The code writes the predicate function, not the user.
>
> I'll just pick the "read-only" metadata for an example:
>
> -*- lexical-binding: t; -*-
>
> (let* ((read-only (completing-read "read-only?" '(t nil)))
>         (predicate
>           (lambda (dir)
>             (eq read-only (metadata-read-only (project-metadata project 
> dir))))))
>     (project-find-regexp regexp predicate))
>
> This could be extended to include the rest of the defined metadata.

The consumer doesn't need to construct a "formal" predicate function: 
just ask the project API for a list of dirs, and filter out ones you 
don't like, maybe using cl-loop.

> Well, that's one choice. But I'd prefer the predicate in the API, so I
> don't have to implement the same predicate-calling code in each
> higher-level function.

You can use cl-remove-if-not.

> On the other hand, the user code can just as easily distinguish
> project-roots from project-library-roots; so why is that in the API?

What user code? Please remember that the user doesn't in general, write 
Elisp code.

How would project-find-regexp distinguish them?

> You can't have it both ways; project-roots and project-libarary-roots is
> just one special predicate.

You could say that.

> Yes, we want to document those properties. That's why I'm pushing so
> hard to find out what "project-root" means; I'm trying to find out what
> properties of the project you actually care about.
>
> We seem to have settled on "read-only".

Yes, but if we're going the more flexible route, I prefer the words like 
"libraries" and "dependencies". Using them, the user might make the 
choice about which directories are interesting for the current search.

> Still, it illustrates the need for another predicate on the result;
> that could also be in the API, or at the client level.

The consumer can just as well filter the results using cl-remove-if-not.

> > If we go the project-directory-metadata route, what other accessors
> > will be left? You want to remove project-library-roots, right?
>
> Yes, and merge its content into project-roots.
>
> > Will project-roots retain its name?
>
> Yes, that's fine.

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.