;;; project.el --- Operations on the current project -*- lexical-binding: t; -*-
-;; Copyright (C) 2015 Free Software Foundation, Inc.
+;; Copyright (C) 2015-2016 Free Software Foundation, Inc.
;; This file is part of GNU Emacs.
;;; Commentary:
;; This file contains generic infrastructure for dealing with
-;; projects, and a number of public functions: finding the current
-;; root, related project directories, search path, etc.
+;; projects, some utility functions, and commands using that
+;; infrastructure.
;;
;; The goal is to make it easier for Lisp programs to operate on the
;; current project, without having to know which package handles
;; detection of that project type, parsing its config files, etc.
+;;
+;; Infrastructure:
+;;
+;; Function `project-current', to determine the current project
+;; instance, and 3 (at the moment) generic functions that act on it.
+;; This list is to be extended in future versions.
+;;
+;; Utils:
+;;
+;; `project-combine-directories' and `project-subtract-directories',
+;; mainly for use in the abovementioned generics' implementations.
+;;
+;; Commands:
+;;
+;; `project-find-regexp' and `project-or-external-find-regexp' use the
+;; current API, and thus will work in any project that has an adapter.
+
+;;; TODO:
+
+;; * Commands `project-find-file' and `project-or-external-find-file'.
+;; Currently blocked on adding a new completion style that would let
+;; the user enter just the base file name (or a part of it), and get
+;; it expanded to the absolute file name.
+;;
+;; * Build tool related functionality. Start with a `project-build'
+;; command, which should provide completions on tasks to run, and
+;; maybe allow entering some additional arguments. This might
+;; be handled better with a separate API, though. Then we won't
+;; force every project backend to be aware of the build tool(s) the
+;; project is using.
+;;
+;; * Command to (re)build the tag files in all project roots. To that
+;; end, we might need to add a way to provide file whitelist
+;; wildcards for each root to limit etags to certain files (in
+;; addition to the blacklist provided by ignores), and/or allow
+;; specifying additional tag regexps.
+;;
+;; * UI for the user to be able to pick the current project for the
+;; whole Emacs session, independent of the current directory. Or,
+;; in the more advanced case, open a set of projects, and have some
+;; project-related commands to use them all. E.g., have a command
+;; to search for a regexp across all open projects. Provide a
+;; history of projects that were opened in the past (storing it as a
+;; list of directories should suffice).
+;;
+;; * Support for project-local variables: a UI to edit them, and a
+;; utility function to retrieve a value. Probably useless without
+;; support in various built-in commands. In the API, we might get
+;; away with only adding a `project-configuration-directory' method,
+;; defaulting to the project root the current file/buffer is in.
+;; And prompting otherwise. How to best mix that with backends that
+;; want to set/provide certain variables themselves, is up for
+;; discussion.
;;; Code:
argument (the directory) and should return either nil to mean
that it is not applicable, or a project instance.")
-;; FIXME: Using the current approach, we don't have access to the
-;; "library roots" of language A from buffers of language B, which
-;; seems desirable in multi-language projects, at least for some
-;; potential uses, like "jump to a file in project or library".
-;;
-;; We can add a second argument to this function: a file extension, or
-;; a language name. Some projects will know the set of languages used
-;; in them; for others, like VC-based projects, we'll need
-;; auto-detection. I see two options:
-;;
-;; - That could be implemented as a separate second hook, with a
-;; list of functions that return file extensions.
-;;
-;; - This variable will be turned into a hook with "append" semantics,
-;; and each function in it will perform auto-detection when passed
-;; nil instead of an actual file extension. Then this hook will, in
-;; general, be modified globally, and not from major mode functions.
-(defvar project-library-roots-function 'etags-library-roots
- "Function that returns a list of library roots.
-
-It should return a list of directories that contain source files
-related to the current buffer. Depending on the language, it
-should include the headers search path, load path, class path,
-and so on.
-
-The directory names should be absolute. Used in the default
-implementation of `project-library-roots'.")
-
;;;###autoload
(defun project-current (&optional maybe-prompt dir)
"Return the project instance in DIR or `default-directory'.
(defun project--find-in-directory (dir)
(run-hook-with-args-until-success 'project-find-functions dir))
-;; FIXME: Add MODE argument, like in `ede-source-paths'?
-(cl-defgeneric project-library-roots (project)
- "Return the list of library roots for PROJECT.
+(cl-defgeneric project-roots (project)
+ "Return the list of directory roots of the current project.
-It's the list of directories outside of the project that contain
-related source files.
+Most often it's just one directory which contains the project
+build file and everything else in the project. But in more
+advanced configurations, a project can span multiple directories.
-Project-specific version of `project-library-roots-function',
-which see. Unless it knows better, a specialized implementation
-should use the value returned by that function."
- (project-subtract-directories
- (project-combine-directories
- (funcall project-library-roots-function))
- (project-roots project)))
-
-(cl-defgeneric project-roots (project)
- "Return the list of directory roots belonging to the current project.
+The directory names should be absolute.")
-Most often it's just one directory, which contains the project
-file and everything else in the project. But in more advanced
-configurations, a project can span multiple directories.
+;; FIXME: Add MODE argument, like in `ede-source-paths'?
+(cl-defgeneric project-external-roots (_project)
+ "Return the list of external roots for PROJECT.
-The rule of tumb for whether to include a directory here, and not
-in `project-library-roots', is whether its contents are meant to
-be edited together with the rest of the project.
+It's the list of directories outside of the project that are
+still related to it. If the project deals with source code then,
+depending on the languages used, this list should include the
+headers search path, load path, class path, and so on.
-The directory names should be absolute.")
+The rule of thumb for whether to include a directory here, and
+not in `project-roots', is whether its contents are meant to be
+edited together with the rest of the project."
+ nil)
(cl-defgeneric project-ignores (_project _dir)
"Return the list of glob patterns to ignore inside DIR.
Patterns can match both regular files and directories.
To root an entry, start it with `./'. To match directories only,
end it with `/'. DIR must be one of `project-roots' or
-`project-library-roots'."
+`project-external-roots'."
(require 'grep)
(defvar grep-find-ignored-files)
(nconc
"Project implementation using the VC package."
:group 'tools)
-(defcustom project-vc-library-roots nil
- "List ot directories to include in `project-library-roots'.
-The file names can be absolute, or relative to the project root."
- :type '(repeat file)
- :safe 'listp)
-
(defcustom project-vc-ignores nil
"List ot patterns to include in `project-ignores'."
:type '(repeat string)
:safe 'listp)
+;; FIXME: Using the current approach, major modes are supposed to set
+;; this variable to a buffer-local value. So we don't have access to
+;; the "external roots" of language A from buffers of language B, which
+;; seems desirable in multi-language projects, at least for some
+;; potential uses, like "jump to a file in project or external dirs".
+;;
+;; We could add a second argument to this function: a file extension,
+;; or a language name. Some projects will know the set of languages
+;; used in them; for others, like VC-based projects, we'll need
+;; auto-detection. I see two options:
+;;
+;; - That could be implemented as a separate second hook, with a
+;; list of functions that return file extensions.
+;;
+;; - This variable will be turned into a hook with "append" semantics,
+;; and each function in it will perform auto-detection when passed
+;; nil instead of an actual file extension. Then this hook will, in
+;; general, be modified globally, and not from major mode functions.
+;;
+;; The second option seems simpler, but the first one has the
+;; advantage that the user could override the list of languages used
+;; in a project via a directory-local variable, thus skipping
+;; languages they're not working on personally (in a big project), or
+;; working around problems in language detection (the detection logic
+;; might be imperfect for the project in question, or it might work
+;; too slowly for the user's taste).
+(defvar project-vc-external-roots-function (lambda () tags-table-list)
+ "Function that returns a list of external roots.
+
+It should return a list of directory roots that contain source
+files related to the current buffer.
+
+The directory names should be absolute. Used in the VC project
+backend implementation of `project-external-roots'.")
+
(defun project-try-vc (dir)
(let* ((backend (ignore-errors (vc-responsible-backend dir)))
(root (and backend (ignore-errors
(cl-defmethod project-roots ((project (head vc)))
(list (cdr project)))
-(cl-defmethod project-library-roots ((project (head vc)))
+(cl-defmethod project-external-roots ((project (head vc)))
(project-subtract-directories
(project-combine-directories
- (append
- (let ((root (cdr project)))
- (mapcar
- (lambda (dir) (file-name-as-directory (expand-file-name dir root)))
- (project--value-in-dir 'project-vc-library-roots root)))
- (funcall project-library-roots-function)))
+ (mapcar
+ #'file-name-as-directory
+ (funcall project-vc-external-roots-function)))
(project-roots project)))
(cl-defmethod project-ignores ((project (head vc)) dir)
(declare-function grep-read-files "grep")
(declare-function xref-collect-matches "xref")
(declare-function xref--show-xrefs "xref")
+(declare-function xref-backend-identifier-at-point "xref")
;;;###autoload
(defun project-find-regexp (regexp)
- "Find all matches for REGEXP in the current project.
+ "Find all matches for REGEXP in the current project's roots.
With \\[universal-argument] prefix, you can specify the directory
to search in, and the file name pattern to search for."
(interactive (list (project--read-regexp)))
(project--find-regexp-in dirs regexp pr)))
;;;###autoload
-(defun project-or-libraries-find-regexp (regexp)
- "Find all matches for REGEXP in the current project or libraries.
+(defun project-or-external-find-regexp (regexp)
+ "Find all matches for REGEXP in the project roots or external roots.
With \\[universal-argument] prefix, you can specify the file name
pattern to search for."
(interactive (list (project--read-regexp)))
(let* ((pr (project-current t))
(dirs (append
(project-roots pr)
- (project-library-roots pr))))
+ (project-external-roots pr))))
(project--find-regexp-in dirs regexp pr)))
(defun project--read-regexp ()
- (defvar xref-identifier-at-point-function)
- (require 'xref)
(read-regexp "Find regexp"
- (funcall xref-identifier-at-point-function)))
+ (xref-backend-identifier-at-point (xref-find-backend))))
(defun project--find-regexp-in (dirs regexp project)
(require 'grep)