project.el semantics

[Stephen Leake]

Dmitry Gutov <address@hidden> writes:

> Currently, the default implementation of project-search-path calls
> project-prune-directories. We could require it of all implementations,
> so that there's no duplication of this kind.
>
> But then we won't be able to search for "qualified file names", like
> "semantic/symref/cscope.el" (or would do it less accurately). Which
> might be important in "jump to an import" usages. Not in Elisp (we
> have a better implementation of that already), but in other languages.

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.

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

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.

However, if the C include path is not purely recursive (which is
likely), 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).

That's an argument for providing project-flat-search-path (overkill for
this use case, but not harmfull), 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.

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

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

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

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.

I believe all the use cases we've discussed so far can be met with
reasonable efficency by providing both purely recursive and purely flat
search paths.

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). Those that want pure
recursive can call project-prune-directories on the result, and those
that want flat can call project-recursive-ignores-to-flat.

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

-- 
-- Stephe