[#317] New user option: apheleia-skip-functions (#318)

Closes #317

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog].
 
 ## Unreleased
+### Features
+* New user option `apheleia-skip-functions`, like
+  `apheleia-inhibit-functions` but for skipping a formatter run even
+  when `apheleia-mode` is generally enabled ([#317]).
+
 ### Formatters
 * [`typstyle`](https://github.com/Enter-tainer/typstyle) for
   [typst](https://typst.app/) ([#313]).
@@ -26,6 +31,7 @@ The format is based on [Keep a Changelog].
 [#301]: https://github.com/radian-software/apheleia/pull/301
 [#313]: https://github.com/radian-software/apheleia/pull/313
 [#316]: https://github.com/radian-software/apheleia/pull/316
+[#317]: https://github.com/radian-software/apheleia/issues/317
 
 ## 4.2 (released 2024-08-03)
 ### Changes

README.md

@@ -238,6 +238,10 @@ Apheleia exposes some hooks for advanced customization:
   one of these returns non-nil then `apheleia-mode` is not enabled in
   the buffer.
 
+* `apheleia-skip-functions`: List of functions to run before *each*
+  Apheleia formatter invocation. If one of these returns non-nil then
+  the formatter is not run, even if `apheleia-mode` is enabled.
+
 ### Formatter configuration
 
 There is no configuration interface in Apheleia for formatter

apheleia.el

@@ -45,13 +45,26 @@
       (buffer-hash)
     (md5 (current-buffer))))
 
+(defcustom apheleia-skip-functions nil
+  "List of functions that prevent Apheleia from running when enabled.
+These are invoked every time Apheleia wants to format a buffer,
+and the formatting operation is skipped if any of them return
+non-nil. See also `apheleia-inhibit-functions' for functions that
+prevent `apheleia-mode' from being turned on in the first place."
+  :type '(repeat function)
+  :group 'apheleia)
+
 (defun apheleia--disallowed-p ()
   "Return an error message if Apheleia cannot be run, else nil."
-  (when (and buffer-file-name
-             (file-remote-p (or buffer-file-name
-                                default-directory))
-             (eq apheleia-remote-algorithm 'cancel))
-    "Apheleia refused to run formatter due to `apheleia-remote-algorithm'"))
+  (cond
+   ((and buffer-file-name
+         (file-remote-p (or buffer-file-name
+                            default-directory))
+         (eq apheleia-remote-algorithm 'cancel))
+    "Apheleia refused to run formatter due to `apheleia-remote-algorithm'")
+   ((run-hook-with-args-until-success
+     'apheleia-skip-functions)
+    "Apheleia skipped running formatter due to `apheleia-skip-functions'")))
 
 (defmacro apheleia--with-on-error (on-error &rest body)
   "Call ON-ERROR with an error if BODY throws an error.
@@ -211,7 +224,8 @@ 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."
+similar task. See also `apheleia-skip-functions' for functions
+that prevent Apheleia from running even when the mode is enabled."
   :type '(repeat function)
   :group 'apheleia)