feat: format_on_save and format_after_save can be functions

1 files changed, 28 insertions, 12 deletions

diff --git a/doc/conform.txt b/doc/conform.txt
index 149db88..a62eca8 100644
--- a/doc/conform.txt
+++ b/doc/conform.txt
@@ -32,6 +32,11 @@ OPTIONS                                                          *conform-option
         lsp_fallback = true,
         timeout_ms = 500,
       },
+      -- If this is set, Conform will run the formatter asynchronously after save.
+      -- It will pass the table to conform.format().
+      format_after_save = {
+        lsp_fallback = true,
+      },
       -- Set the log level. Use `:ConformInfo` to see the location of the log file.
       log_level = vim.log.levels.ERROR,
       -- Conform will notify you when a formatter errors
@@ -96,7 +101,8 @@ format({opts}, {callback}): boolean                               *conform.forma
                          true.
           {bufnr}        `nil|integer` Format this buffer (default 0)
           {async}        `nil|boolean` If true the method won't block. Defaults
-                         to false.
+                         to false. If the buffer is modified before the
+                         formatter completes, the formatting will be discarded.
           {formatters}   `nil|string[]` List of formatters to run. Defaults to
                          all formatters for the buffer filetype.
           {lsp_fallback} `nil|boolean|"always"` Attempt LSP formatting if no
@@ -232,17 +238,27 @@ write it yourself using your own autocmd. For example:
       end,
     })
 
-    -- Format asynchronously on save
-    vim.api.nvim_create_autocmd("BufWritePost", {
-      pattern = "*",
-      callback = function(args)
-        require("conform").format({ async = true, lsp_fallback = true, bufnr = args.buf }, function(err)
-          if not err then
-            vim.api.nvim_buf_call(args.buf, function()
-              vim.cmd.update()
-            end)
-          end
-        end)
+    -- To eliminate the boilerplate, you can pass a function to format_on_save
+    -- and it will be called during the BufWritePre callback.
+    require("conform").setup({
+      format_on_save = function(bufnr)
+        if vim.g.disable_autoformat or vim.b[bufnr].disable_autoformat then
+          return
+        end
+        -- ...additional logic...
+        return { timeout_ms = 500, lsp_fallback = true }
+      end,
+    })
+
+    -- There is a similar affordance for format_after_save, which uses BufWritePost.
+    -- This is good for formatters that are too slow to run synchronously.
+    require("conform").setup({
+      format_after_save = function(bufnr)
+        if vim.g.disable_autoformat or vim.b[bufnr].disable_autoformat then
+          return
+        end
+        -- ...additional logic...
+        return { lsp_fallback = true }
       end,
     })
 <