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, 11 insertions, 6 deletions

diff --git a/doc/conform.txt b/doc/conform.txt
index c2fe9f0..c123d11 100644
--- a/doc/conform.txt
+++ b/doc/conform.txt
@@ -44,14 +44,14 @@ OPTIONS                                                          *conform-option
       log_level = vim.log.levels.ERROR,
       -- Conform will notify you when a formatter errors
       notify_on_error = true,
-      -- Define custom formatters here
+      -- Custom formatters and changes to built-in formatters
       formatters = {
         my_formatter = {
-          -- This can be a string or a function that returns a string
+          -- This can be a string or a function that returns a string.
+          -- When defining a new formatter, this is the only field that is *required*
           command = "my_cmd",
-          -- OPTIONAL - all fields below this are optional
           -- A list of strings, or a function that returns a list of strings
-          -- Return a single string instead to run the command in a shell
+          -- Return a single string instead of a list to run the command in a shell
           args = { "--stdin-from-filename", "$FILENAME" },
           -- If the formatter supports range formatting, create the range arguments here
           range_args = function(ctx)
@@ -69,15 +69,20 @@ OPTIONS                                                          *conform-option
           condition = function(ctx)
             return vim.fs.basename(ctx.filename) ~= "README.md"
           end,
-          -- Exit codes that indicate success (default {0})
+          -- Exit codes that indicate success (default { 0 })
           exit_codes = { 0, 1 },
           -- Environment variables. This can also be a function that returns a table.
           env = {
             VAR = "value",
           },
+          -- Set to false to disable merging the config with the base definition
+          inherit = true,
+          -- When inherit = true, add these additional arguments to the command.
+          -- This can also be a function, like args
+          prepend_args = { "--use-tabs" },
         },
         -- These can also be a function that returns the formatter
-        other_formatter = function()
+        other_formatter = function(bufnr)
           return {
             command = "my_cmd",
           }