feat!: merge configs in conform.formatters with defaults (#140)

This breaking change should make it significantly easier to modify formatters. While I expect 99% of configs to be backwards-compatible, this can still potentially cause problems. If you:

* define a formatter in the `formatters` option
* that has the same name as a built-in formatter
* and omits a property from the original formatter (e.g. leaves out `range_args` or `cwd`)

Then you may encounter breaking behavior from this commit, because now your config definition will be merged with the built-in definition, and so will inherit those omitted properties. This config merging behavior can be opted-out of by adding `inherit = false` to your formatter config.

1 files changed, 8 insertions, 70 deletions

diff --git a/doc/recipes.md b/doc/recipes.md
index 2d33ca2..97eaa16 100644
--- a/doc/recipes.md
+++ b/doc/recipes.md
@@ -3,11 +3,9 @@
 <!-- TOC -->
 
 - [Format command](#format-command)
-- [Customizing formatters](#customizing-formatters)
 - [Autoformat with extra features](#autoformat-with-extra-features)
 - [Command to toggle format-on-save](#command-to-toggle-format-on-save)
 - [Automatically run slow formatters async](#automatically-run-slow-formatters-async)
-- [Add extra arguments to a formatter command](#add-extra-arguments-to-a-formatter-command)
 - [Lazy loading with lazy.nvim](#lazy-loading-with-lazynvim)
 
 <!-- /TOC -->
@@ -30,37 +28,6 @@ vim.api.nvim_create_user_command("Format", function(args)
 end, { range = true })
 ```
 
-## Customizing formatters
-
-If you want to customize how a formatter runs (for example, to pass in environment variables or
-change the command arguments), you can either edit the formatter directly or create one yourself.
-
-```lua
--- Directly change the values on the built-in configuration
-require("conform.formatters.yamlfix").env = {
-  YAMLFIX_SEQUENCE_STYLE = "block_style",
-}
-
--- Or create your own formatter that overrides certain values
-require("conform").formatters.yamlfix =
-  vim.tbl_deep_extend("force", require("conform.formatters.yamlfix"), {
-    env = {
-      YAMLFIX_SEQUENCE_STYLE = "block_style",
-    },
-  })
-
--- Here is an example that modifies the command arguments for prettier to add
--- a custom config file, if it is present
-require("conform.formatters.prettier").args = function(ctx)
-  local args = { "--stdin-filepath", "$FILENAME" }
-  local found = vim.fs.find(".custom-config.json", { upward = true, path = ctx.dirname })[1]
-  if found then
-    vim.list_extend(args, { "--config", found })
-  end
-  return args
-end
-```
-
 ## Autoformat with extra features
 
 If you want more complex logic than the basic `format_on_save` option allows, you can use a function instead.
@@ -168,36 +135,6 @@ require("conform").setup({
 })
 ```
 
-## Add extra arguments to a formatter command
-
-The official recommended way to change the arguments of a formatter is to just copy the default
-values and mutate them however you like. For example:
-
-```lua
-require("conform.formatters.shfmt").args = { "-i", "4", "-filename", "$FILENAME" }
-```
-
-But if you really want to _add_ arguments instead of replacing them, there is a utility function to
-make this easier:
-
-```lua
-local util = require("conform.util")
-local prettier = require("conform.formatters.prettier")
-require("conform").formatters.prettier = vim.tbl_deep_extend("force", prettier, {
-  args = util.extend_args(prettier.args, { "--tab", "--indent", "2" }),
-  range_args = util.extend_args(prettier.range_args, { "--tab", "--indent", "2" }),
-})
-
--- Pass append=true to append the extra arguments to the end
-local deno_fmt = require("conform.formatters.deno_fmt")
-require("conform").formatters.deno_fmt = vim.tbl_deep_extend("force", deno_fmt, {
-  args = util.extend_args(deno_fmt.args, { "--use-tabs" }, { append = true }),
-})
-
--- There is also a utility to modify a formatter in-place
-util.add_formatter_args(require("conform.formatters.prettier"), { "--tab", "--indent", "2" })
-```
-
 ## Lazy loading with lazy.nvim
 
 Here is the recommended config for lazy-loading using lazy.nvim
@@ -220,23 +157,24 @@ return {
   },
   -- Everything in opts will be passed to setup()
   opts = {
+    -- Define your formatters
     formatters_by_ft = {
       lua = { "stylua" },
       python = { "isort", "black" },
       javascript = { { "prettierd", "prettier" } },
     },
+    -- Set up format-on-save
     format_on_save = { timeout_ms = 500, lsp_fallback = true },
+    -- Customize formatters
+    formatters = {
+      shfmt = {
+        prepend_args = { "-i", "2" },
+      },
+    },
   },
   init = function()
     -- If you want the formatexpr, here is the place to set it
     vim.o.formatexpr = "v:lua.require'conform'.formatexpr()"
   end,
-
-  -- This function is optional, but if you want to customize formatters do it here
-  config = function(_, opts)
-    local util = require("conform.util")
-    util.add_formatter_args(require("conform.formatters.shfmt"), { "-i", "2" })
-    require("conform").setup(opts)
-  end,
 }
 ```