Introduce apheleia-inhibit-functions (#138)

Fixes #134

(I accidentally force-pushed #135 from a shallow repo)

Co-authored-by: Radon Rosborough <radon@intuitiveexplanations.com>

CHANGELOG.md

@@ -5,6 +5,12 @@ The format is based on [Keep a Changelog].
 
 ## Unreleased
 ### Features
+* You can use `apheleia-inhibit` as a file-local variable to disable
+  Apheleia turning on automatically for a file or directory. You can
+  also use `apheleia-inhibit-functions` to configure custom logic to
+  prevent Apheleia from turning on automatically under certain
+  circumstances, without needing to adjust file-local variables. See
+  [#134] and [#138].
 * `apheleia-mode` lighter is now customizable ([#143]).
 
 ### Enhancements
@@ -74,6 +80,8 @@ The format is based on [Keep a Changelog].
 [#128]: https://github.com/radian-software/apheleia/pull/128
 [#132]: https://github.com/radian-software/apheleia/pull/132
 [#137]: https://github.com/radian-software/apheleia/pull/137
+[#134]: https://github.com/radian-software/apheleia/issues/134
+[#138]: https://github.com/radian-software/apheleia/pull/138
 [#143]: https://github.com/radian-software/apheleia/pull/143
 
 ## 3.0 (released 2022-06-01)

README.md

@@ -157,6 +157,9 @@ variables:
       of `file` in general.
 * `apheleia-formatter`: Optional buffer-local variable specifying the
   formatter to use in this buffer. Overrides `apheleia-mode-alist`.
+* `apheleia-inhibit`: Optional buffer-local variable, if set to
+  non-nil then Apheleia does not turn on automatically even if
+  `apheleia-global-mode` is on.
 
 You can run `M-x apheleia-mode` to toggle automatic formatting on save
 in a single buffer, or `M-x apheleia-global-mode` to toggle the
@@ -209,6 +212,11 @@ Apheleia exposes some hooks for advanced customization:
   or it could be a list if multiple formatters were run in a chain),
   and a boolean for whether there was an error.
 
+* `apheleia-inhibit-functions`: List of functions to run before
+  turning on Apheleia automatically from `apheleia-global-mode`. If
+  one of these returns non-nil then `apheleia-mode` is not enabled in
+  the buffer.
+
 ## Known issues
 
 * `process aphelieia-whatever no longer connected to pipe; closed it`:
@@ -224,7 +232,7 @@ Please see [the contributor guide for my
 projects](https://github.com/raxod502/contributor-guide) for general
 information, and the following sections for Apheleia-specific details.
 
-There's also a [wiki](https://github.com/radian-software/apheleia/wiki) that could do with additions/clarity. Any 
+There's also a [wiki](https://github.com/radian-software/apheleia/wiki) that could do with additions/clarity. Any
 improvement suggestions should be submitted as an issue.
 
 ### Adding a formatter

apheleia.el

@@ -1326,6 +1326,16 @@ changes), CALLBACK, if provided, is invoked with no arguments."
   "Normal hook run after Apheleia formats a buffer successfully."
   :type 'hook)
 
+(defcustom apheleia-inhibit-functions nil
+  "List of functions that prevent Apheleia from turning on automatically.
+If one of these returns non-nil then `apheleia-mode' is not
+enabled in a buffer, even if `apheleia-global-mode' is on. You
+can still manually enable `apheleia-mode' in such a buffer.
+
+See also `apheleia-inhibit' for another way to accomplish a
+similar task."
+  :type '(repeat function))
+
 ;; Handle recursive references.
 (defvar apheleia-mode)
 
@@ -1367,8 +1377,26 @@ and `apheleia-formatters'."
         (add-hook 'after-save-hook #'apheleia--format-after-save nil 'local)
       (remove-hook 'after-save-hook #'apheleia--format-after-save 'local)))
 
+
+  (defvar-local apheleia-inhibit nil
+    "Do not enable `apheleia-mode' automatically if non-nil.
+This is designed for use in .dir-locals.el.
+
+See also `apheleia-inhibit-functions'.")
+  (put 'apheleia-inhibit 'safe-local-variable #'booleanp)
+
+  (defun apheleia-mode-maybe ()
+    "Enable `apheleia-mode' if allowed by user configuration.
+This checks `apheleia-inhibit-functions' and `apheleia-inhibit'
+to see if it is allowed."
+    (unless (or
+             apheleia-inhibit
+             (run-hook-with-args-until-success
+              'apheleia-inhibit-functions))
+      (apheleia-mode)))
+
   (define-globalized-minor-mode apheleia-global-mode
-    apheleia-mode apheleia-mode)
+    apheleia-mode apheleia-mode-maybe)
 
   (put 'apheleia-mode 'safe-local-variable #'booleanp))