From 659838ff4244ef6af095395ce68aaaf99fa8e696 Mon Sep 17 00:00:00 2001
From: Steven Arcangeli <506791+stevearc@users.noreply.github.com>
Date: Wed, 6 Dec 2023 22:20:29 -0800
Subject: refactor!: formatter config functions take self as first argument
 (#233)

This is a breaking API change, but there is a shim in place that will keep existing functions working, just with a warning notification. Most people should not encounter this at all. For anyone overriding a formatter config value with a function that takes `(ctx)` as the parameter, it will need to be updated to take `(self, ctx)`.
---
 doc/conform.txt | 54 ++++++++++++++++++------------------------------------
 1 file changed, 18 insertions(+), 36 deletions(-)

(limited to 'doc/conform.txt')

diff --git a/doc/conform.txt b/doc/conform.txt
index 66514cc..096c195 100644
--- a/doc/conform.txt
+++ b/doc/conform.txt
@@ -6,7 +6,7 @@ CONTENTS                                                        *conform-content
   1. Options                                                 |conform-options|
   2. Api                                                         |conform-api|
   3. Formatters                                           |conform-formatters|
-  4. Autoformat                                           |conform-autoformat|
+  4. Self argument migration                               |conform-self-args|
 
 --------------------------------------------------------------------------------
 OPTIONS                                                          *conform-options*
@@ -331,45 +331,27 @@ FORMATTERS                                                    *conform-formatter
 `zprint` - Formatter for Clojure and EDN.
 
 --------------------------------------------------------------------------------
-AUTOFORMAT                                                    *conform-autoformat*
+SELF ARGUMENT MIGRATION                                        *conform-self-args*
 
-If you want more complex logic than the `format_on_save` option allows, you can
-write it yourself using your own autocmd. For example:
+The function arguments for formatter config functions have changed. Previously,
+they took a single `ctx` argument.
 >lua
-    -- if format_on_save is a function, it will be called during BufWritePre
-    require("conform").setup({
-      format_on_save = function(bufnr)
-        -- Disable autoformat on certain filetypes
-        local ignore_filetypes = { "sql", "java" }
-        if vim.tbl_contains(ignore_filetypes, vim.bo[bufnr].filetype) then
-          return
-        end
-        -- Disable with a global or buffer-local variable
-        if vim.g.disable_autoformat or vim.b[bufnr].disable_autoformat then
-          return
-        end
-        -- Disable autoformat for files in a certain path
-        local bufname = vim.api.nvim_buf_get_name(bufnr)
-        if bufname:match("/node_modules/") then
-          return
+    {
+        command = "phpcbf",
+        args = function(ctx)
+            return { "-q", "--stdin-path=" .. ctx.filename, "-" }
         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
+    }
+<Now, they take `self` as the first argument, and `ctx` as the second.
+>lua
+    {
+        command = "phpcbf",
+        args = function(self, ctx)
+            return { "-q", "--stdin-path=" .. ctx.filename, "-" }
         end
-        -- ...additional logic...
-        return { lsp_fallback = true }
-      end,
-    })
-<
+    }
+<The config values that can be defined as functions are: `command`, `args`,
+`range_args`, `cwd`, `env`, and `condition`.
 
 ================================================================================
 vim:tw=80:ts=2:ft=help:norl:syntax=help:
-- 
cgit v1.2.3-70-g09d2