Re: project.el semantics

[Dmitry Gutov]

On 09/18/2015 08:14 PM, Stephen Leake wrote:

> I'm guessing you are talking about something like a new function
> project-find-file-at-point that does the following:
>
>      In a C file, if point is in an #include line, goto the beginning of
>      a buffer containing the corresponding file.

Pretty much, yes. But it would not necessarily use the content at point. 
Input with completion is also possible, very much in line with 
find-file-in-project discussed currently, with small differences.

> And similarly for other languages.
>
> In that case, the string in the #include could be something like
> "dir1/dir2/file1.h", or just "file2.h".

<dir1/dir2/file1.h>, actually. #include with double-quotes has a 
different meaning (those are relative includes, much easier to handle in 
a different way).

> If project-search-path is a superset of the C include path, we can
> iterate thru project-search-path, checking if (expand-file-name
> include-string dir) exists.

Right.

> However, if the C include path is not purely recursive (which is
> likely),

What is this guessing? I'm pretty sure it *is* "purely recursive", and 
if not, please quote some documentation.

And by "purely recursive" here, I mean that if /foo/bar is in 
C_INCLUDE_PATH, and foo.c contains "#include <tee/qux.h>", and 
/foo/bar/tee/qux.h exists, the compiler (or preprocessor, etc) *will* 
try to load it when compiling foo.c.

Hence, any file inside subtrees of C_INCLUDE_PATH is include-able, and 
jumping to any of them makes sense.

> then a purely recursive project-search-path will not be a
> superset, and this will fail (so it will fail with all of the current
> implementations of project-search-path).

I'm pretty sure that even if that were the case, it could be a 
good-enough feature, just one with undesirable quirks.

> That's an argument for providing project-flat-search-path (overkill for
> this use case, but not harmfull),

I don't think it is. Please, let's cease the flat-search-path discussion 
until we encounter a use case that's *really* hard to handle without it.

So far, I'm sorry, it simply looks like you're pushing your own 
preference. Which is fine to a certain extent, but really goes against 
my intent of having an easy-to-understand API.

> or project-c-include-search-path
> (precisely what this use case wants), or an argument to
> project-search-path telling it what sort of path to return.

Maybe we indeed should have two different generic functions, one for 
"source roots" (that doesn't return any two dirs where one is inside the 
other), and another that must return a list of directories exactly along 
the lines of C_INCLUDE_PATH. But let's not call it c-something, other 
languages have similar concepts (class path in Java, load path in Ruby).

Opinions welcome.

> On the other hand, find-file-in-project and xref-search-regexp want
> purely recursive search paths.

Yes. Although I wouldn't call C_INCLUDE_PATH "flat". It's just redundant 
for the above commands.

> EDE defines at least two kinds of paths; include and link, which have
> different content.

Could you point me to the documentation for this? There's no occurrences 
of "link" in ede/base.el.

> Different use cases have different requirements for the semantics of
> "search path". It will not be possible for a single function to meet all
> the required semantics.

You might be right.

> You suggest that we should define project-search-path loosely ("let the
> backend do whatever it wants"), and let the client code cope ("just call
> project-prune-directories").

Not what it wants, just within the documented leeway. I admit returning 
redundant elements is not documented, but for now it's just an idea, not 
something set in stone. Eventually it'll need to be documented, 
whichever way the decision comes out.

> But the API is the interface between the clients and the backend; it
> would be much better to have clearer semantics, and options in the API
> to choose among the possible semantics. That way client code can be
> written that is truly independent of the project backends, and new
> backends won't break existing client code.

100% agreement, except for "options in the API to choose among the 
different semantics". It's better to only have to deal with one 
semantics, as long as the result can be just as powerful.

> On the other hand, if we define project-search-path to return
> mixed-recursive (to match load-path or C include exactly), some client
> functions may be able to use it as is (they will have to make
> assumptions about what the backend is including).

The statement in parens above seems like a recipe for disaster. How 
would a function know what the backend is including? Will it have to 
provide different implementations for different backends? Remember, 
we're striving for "backend-agnostic" here.

> We should start a file that documents the use cases we've discussed, so
> we don't forget them.

Any suggestions for the collaboration platform?