Re: project.el semantics

[Dmitry Gutov]

On 11/12/2015 08:44 AM, Stephen Leake wrote:

> If I pass in a DIR that is _not_ related to the project, the category
> should be something like "unknown". So we have at least four values for
> category:

Why? The API consumer can determine that the directory is unrelated if 
it's not in project-roots or project-library-roots. Or whatever 
differenly named accessor we will have.

> unknown
> top-level (ie "the project")
> library
> other-dependency
>
> But then there is also, orthogonal to category:
>
> editable (or read-write)
> read-only

Is it orthogonal, though? I'd think top-level or other-dependency means 
"read-write", and the rest is "read-only".

But if it is orthogonal in some cases, I doubt a project backend can 
choose which directories are read-write. Then we don't need to document 
these, and leave them as possibly user-defined categories, for later.

> So you are focusing on the "read-only" vs "read/write" aspect.

I'm focusing on the "edited together" relation. Not on whether you can 
write to a particular directory.

> > So a search across "current project, as
> > well as code I edit together with it"
>
> This is project-roots.

Indeed.

> The user should be able to specify a subset of the search path for each
> search, at run-time. Having only project-roots and project-library-roots
> available is too limiting.

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.

Let's just keep that in mind, at least.

> The UI for a predicate is more complicated, yes. But the project.el API
> is simpler; a single predicate arg is clearly simpler than the confusion
> between project-roots and project-library-roots.

That doesn't help much if the API consumer doesn't know how to get the 
predicate from the user. *That's* a complication.

> Which is why I keep emphasizing that project.el is _not_ about the UI.

I imagine most of API consumers to be user-level commands.

> Not with the current API:
>
> (defun project-find-regexp (regexp)
> ...)
>
> How would I specify a single root or directory?

Like I said: "C-u M-x". Use the prefix argument; it's documented in its 
docstring. The API doesn't factor into it.

> > I can display all available metadata to the user, and ask: directories
> > with which pieces of metadata set do you want to search? The user
> > enters the category names, separated by spaces, and the search
> > proceeds.
>
> That would be a dialog-box style UI, yes.

I was thinking more of completing-read.

> The dialog box uses the user input to construct a predicate, which it
> passes to the project.el UI.

What kind of input? How does in turn into a predicate? Does the user 
write a whole predicate function in there?

> The alternative to an arbitrary predicate function is to hard-code some
> set of possible choices in the search code. Any such set is limiting.

You see, the usage of predicate will not be coded into the API either 
way; there's no need for it, the API doesn't care, it just returns 
directories the consumer will call predicates on.

But unless we document the properties the predicates can rely on, it 
amounts to exposing no information at all.

> On the GDS project, one search we repeated often was for FIXME:
> comments; we had some structure in them, identifying which release it
> had to be fixed for, who was assigned to fix it, etc. So I could have
> written a few predicates that take advantage of the structure, and used
> a menu to select among them for a search.

To find all FIXMEs, you have to run the search on all directories first, 
don't you? And then, when you get the results, you can filter down the 
matches. That has nothing to do with which directories to search, I think.

> Yes. Metadata query functions and search predicates work for a very
> large variety of UIs (menus, dialog boxes, Siri), as well as a very
> large variety of searches. "project-roots vs project-library-roots"
> works for a similar set of UIs but a much smaller set of searches.

If we go the project-directory-metadata route, what other accessors will 
be left? You want to remove project-library-roots, right?

Will project-roots retain its name?