[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master 7259377: project.el: Add more docs and two new key bindings
From: |
Dmitry Gutov |
Subject: |
master 7259377: project.el: Add more docs and two new key bindings |
Date: |
Sun, 19 Jul 2020 20:58:17 -0400 (EDT) |
branch: master
commit 7259377d70252ac013ec64acc01ad74b628e30d8
Author: Dmitry Gutov <dgutov@yandex.ru>
Commit: Dmitry Gutov <dgutov@yandex.ru>
project.el: Add more docs and two new key bindings
* lisp/progmodes/project.el:
Add a longer description of the package and how to use it.
(project-prefix-map): Add entries for
'project-or-external-find-file' and
'project-or-external-find-regexp'.
---
lisp/progmodes/project.el | 71 ++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 64 insertions(+), 7 deletions(-)
diff --git a/lisp/progmodes/project.el b/lisp/progmodes/project.el
index db8e54b..49a7735 100644
--- a/lisp/progmodes/project.el
+++ b/lisp/progmodes/project.el
@@ -37,11 +37,29 @@
;; current project, without having to know which package handles
;; detection of that project type, parsing its config files, etc.
;;
-;; Infrastructure:
+;; This file consists of following parts:
;;
-;; Function `project-current', to determine the current project
-;; instance, and 4 (at the moment) generic functions that act on it.
-;; This list is to be extended in future versions.
+;; Infrastructure (the public API):
+;;
+;; Function `project-current' that returns the current project
+;; instance based on the value of the hook `project-find-functions',
+;; and several generic functions that act on it.
+;;
+;; `project-root' must be defined for every project.
+;; `project-files' can be overridden for performance purposes.
+;; `project-ignores' and `project-external-roots' describe the project
+;; files and its relations to external directories. `project-files'
+;; should be consistent with `project-ignores'.
+;;
+;; This list can change in future versions.
+;;
+;; VC project:
+;;
+;; Originally conceived as an example implementation, now it's a
+;; relatively fast backend that delegates to 'git ls-files' or 'hg
+;; status' to list the project's files. It honors the VC ignore
+;; files, but supports additions to the list using the user option
+;; `project-vc-ignores' (usually through .dir-locals.el).
;;
;; Utils:
;;
@@ -50,9 +68,46 @@
;;
;; Commands:
;;
-;; `project-find-file', `project-find-regexp' and
-;; `project-or-external-find-regexp' use the current API, and thus
-;; will work in any project that has an adapter.
+;; `project-prefix-map' contains the full list of commands defined in
+;; this package. This map uses the prefix `C-x p' by default.
+;; Type `C-x p f' to find file in the current project.
+;; Type `C-x p C-h' to see all available commands and bindings.
+;;
+;; All commands defined in this package are implemented using the
+;; public API only. As a result, they will work with any project
+;; backend that follows the protocol.
+;;
+;; Any third-party code that wants to use this package should likewise
+;; target the public API. Use any of the built-in commands as the
+;; example.
+;;
+;; How to create a new backend:
+;;
+;; - Consider whether you really should, or whether there are other
+;; ways to reach your goals. If the backend's performance is
+;; significantly lower than that of the built-in one, and it's first
+;; in the list, it will affect all commands that use it. Unless you
+;; are going to be using it only yourself or in special circumstances,
+;; you will probably want it to be fast, and it's unlikely to be a
+;; trivial endeavor. `project-files' is the method to optimize (the
+;; default implementation gets slower the more files the directory
+;; has, and the longer the list of ignores is).
+;;
+;; - Choose the format of the value that represents a project for your
+;; backend (we call it project instance). Don't use any of the
+;; formats from other backends. The value can be arbitrary, as long
+;; as the datatype is something `cl-defmethod' can dispatch on.
+;;
+;; - Write a new function that will determine the current project
+;; based on the directory and add it to `project-find-functions'
+;; (which see) using `add-hook'. It is a good idea to depend on the
+;; directory only, and not on the current major mode, for example.
+;; Because the usual expectation is that all files in the directory
+;; belong to the same project (even if some/most of them are ignored).
+;;
+;; - Define new methods for some or all generic functions for this
+;; backend using `cl-defmethod'. A `project-root' method is
+;; mandatory, `project-files' is recommended, the rest are optional.
;;; TODO:
@@ -517,6 +572,7 @@ DIRS must contain directory names."
(defvar project-prefix-map
(let ((map (make-sparse-keymap)))
(define-key map "f" 'project-find-file)
+ (define-key map "F" 'project-or-external-find-file)
(define-key map "b" 'project-switch-to-buffer)
(define-key map "s" 'project-shell)
(define-key map "d" 'project-dired)
@@ -526,6 +582,7 @@ DIRS must contain directory names."
(define-key map "k" 'project-kill-buffers)
(define-key map "p" 'project-switch-project)
(define-key map "g" 'project-find-regexp)
+ (define-key map "G" 'project-or-external-find-regexp)
(define-key map "r" 'project-query-replace-regexp)
map)
"Keymap for project commands.")
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- master 7259377: project.el: Add more docs and two new key bindings,
Dmitry Gutov <=