branch: elpa/dirvish
commit e02395c40bd5439ece54989229760bde1e9ea4c1
Author: Alex Lu <hellosimon1...@hotmail.com>
Commit: Alex Lu <hellosimon1...@hotmail.com>
refactor: improve `dirvish-find-entry-hook` (closes #324)
---
dirvish.el | 14 ++++++++++++--
docs/CUSTOMIZING.org | 45 ++++++++++++++++++++++++++++++++++++++++-----
2 files changed, 52 insertions(+), 7 deletions(-)
diff --git a/dirvish.el b/dirvish.el
index b2eea1c7e4..5d47ef9080 100644
--- a/dirvish.el
+++ b/dirvish.el
@@ -250,7 +250,14 @@ input for `dirvish-redisplay-debounce' seconds."
:group 'dirvish :type 'hook)
(defcustom dirvish-find-entry-hook nil
- "Functions called before a Dired buffer is displayed."
+ "Functions to be called before opening a directory or file.
+Each function is called with the file's FILENAME and FIND-FN until one
+returns a non-nil value. When a Dired buffer is created for the first
+time, FIND-FN is `dired', and the function is called with that Dired
+buffer as `current-buffer'; Otherwise, it is one of `find-file',
+`find-alternate-file', or `find-file-other-window'. A non-nil return
+value terminates `dirvish--find-entry', allowing interception of file
+opening and customized handling of specific file types."
:group 'dirvish :type 'hook)
(defcustom dirvish-preview-setup-hook nil
@@ -574,6 +581,9 @@ filename or a string with format of `dirvish-fd-bufname'."
(setq find-fn (prog1 'dirvish-fd (require 'dirvish-fd nil t)))
(pcase-let ((`(,re ,dir ,_) (split-string (substring entry 1) "📁")))
(cl-return-from dirvish--find-entry (funcall find-fn dir re))))
+ (and (run-hook-with-args-until-success
+ 'dirvish-find-entry-hook entry find-fn)
+ (cl-return-from dirvish--find-entry))
;; forward requests from `find-dired'
(unless dv (cl-return-from dirvish--find-entry (funcall find-fn entry)))
(and (dv-curr-layout dv) (eq find-fn 'find-file-other-window)
@@ -1460,7 +1470,7 @@ With optional NOSELECT just find files but do not select
them."
(setf (dv-index dv) (cons key buffer))
(let ((key (if (string-prefix-p "🔍" key) (buffer-name buffer) key)))
(setq dirvish--history (seq-take (push key dirvish--history) 200)))
- (run-hook-with-args 'dirvish-find-entry-hook key buffer)
+ (run-hook-with-args 'dirvish-find-entry-hook key 'dired)
buffer)))
;;;; Commands
diff --git a/docs/CUSTOMIZING.org b/docs/CUSTOMIZING.org
index aced181da8..ae84e32322 100644
--- a/docs/CUSTOMIZING.org
+++ b/docs/CUSTOMIZING.org
@@ -105,14 +105,49 @@ See:
[[https://github.com/alexluigit/dirvish/discussions/102#discussioncomment-3
Apart from the hooks provided by Dired, Dirvish got some additions.
- * ~dirvish-setup-hook~: Functions called when directory data for the root
buffer
- is ready.
+*** ~dirvish-setup-hook~
- * ~dirvish-after-revert-hook~: Functions called after running =revert-buffer=
command.
+Functions called when directory data for the root buffer is ready.
- * ~dirvish-find-entry-hook~: Functions called before a Dired buffer is
displayed.
+*** ~dirvish-after-revert-hook~:
- * ~dirvish-preview-setup-hook~: Functions called in the regular preview
buffer.
+Functions called after running =revert-buffer= command.
+
+*** ~dirvish-find-entry-hook~
+
+Functions to be called before opening a directory or file.
+
+Each function is called with the file's FILENAME and FIND-FN until one returns
a
+non-nil value. When a Dired buffer is created for the first time, FIND-FN is
+=dired=, and the function is called with that Dired buffer as =current-buffer=;
+Otherwise, it is one of =find-file=, =find-alternate-file=, or
+=find-file-other-window=. A non-nil return value from
+=run-hook-with-args-until-succuss= terminates =dirvish--find-entry=, allowing
+interception of file opening and customized handling of specific file types.
+
+The code below configures ~dired-find-file*~ commands to automatically detect
+binary files based on their extensions and open them externally.
+
+#+begin_src emacs-lisp
+(defun dirvish-open-binaries-externally (file fn)
+ "When FN is not `dired', open binary FILE externally."
+ (when-let* (((not (eq fn 'dired)))
+ ((file-exists-p file))
+ ((not (file-directory-p file)))
+ ((member (downcase (or (file-name-extension file) ""))
+ dirvish-binary-exts)))
+ ;; return t to terminate `dirvish--find-entry'.
+ (prog1 t (dired-do-open))))
+
+(add-hook 'dirvish-find-entry-hook #'dirvish-open-binaries-externally)
+#+end_src
+
+In practical applications, you might register multiple functions to handle
+different file types, assigning specific handlers for each.
+
+*** ~dirvish-preview-setup-hook~
+
+Functions called in the regular preview buffer.
** =find-dired= integration
