Re: project.el semantics

[Dmitry Gutov]

On 11/22/2015 11:27 PM, John Wiegley wrote:

> So maybe this has come full circle, but if so, I hope it adds some clarity.

To get back to this question, not really, as far as I'm concerned. The 
concept sounds nice, but the proposal is low on specifics, and the 
changes that I try to vaguely imagine complicate the API considerably.

It would be nice to discuss particular example of commands that don't 
work well with the current API (nor with trivial extensions of it), but 
will work better with some specific changes.

Or, like, if we'll have a family of commands that's similar along a 
certain axis, that the upgraded API will simplify reuse.

 * * *

I've tried out the "categories" change that we've discussed, along with 
a couple of variations, but to be honest, I'm less convinced now than 
before. Using effectively an alist where we can use separate generic 
functions seems inconsistent, and treating all directories the same way 
might imply some guarantees that we won't want to give.

See the branches scratch/project-directories*.

scratch/project-directories-with-shallow illustrates what we'll have to 
do to have some directories of explicit "nonrecursive" kind. The result 
is less scarier than I expected (when calling find, just need to pass 
'-maxdepth 1' to it), but even so, the "shallow" argument threads 
through every related function and complicates both 
project-subtract-directories and project-combine-directories. Even 
though it should be 100% equivalent to just adding "./*/" to the ignores 
list for each shallow directory. So unless someone demonstrates that 
using 'find -maxdepth 1' instead of ignores makes a real difference in 
practice, I remain in opposition.

scratch/project-directories-filtering-in-backend seems to be a natural 
extension of scratch/project-directories, but really it seems that this 
way we'll be forcing the backends to implement a rather involved piece 
of logic, in unstructured fashion. And even so, the proposed signature 
only covers the intersections of categories; what if we want to get 
directories "in A, but not in B"? Better to return the raw data to the 
user, and let them use the combinator functions.

scratch/project-directories itself basically seems wasteful: we're 
forcing the backend to produce directories of all kinds at the same 
time, always. A step forward would be to change the arguments list from 
"&rest categories" to one required argument "category".

But then, we'll have to document some allowed categories anyway, and we 
can just as well define the corresponding generic functions instead, 
like project-source-directories and project-test-directories.

To sum up, barring new, advanced proposals from someone else (or more 
detailed proposal from John), I'd rather keep the current structure, 
with possibly following changes:

- Rename project-library-roots to project-external-roots, as a more 
neutral name. Document it as a list of directories related to the 
current project but lying outside of it.

- Like in scratch/project-directories, rename and move the 
project-library-roots-function variable to the project-vc- namespace, 
and for now document that it'll only affect the project-vc backend.