feat: allow customizing format() defaults

5 files changed, 64 insertions, 38 deletions

diff --git a/README.md b/README.md
index 82f5436..f7e255f 100644
--- a/README.md
+++ b/README.md
@@ -473,6 +473,11 @@ require("conform").setup({
     -- have other formatters configured.
     ["_"] = { "trim_whitespace" },
   },
+  -- Set this to change the default values when calling conform.format()
+  -- This will also affect the default values for format_on_save/format_after_save
+  default_format_opts = {
+    lsp_format = "fallback",
+  },
   -- If this is set, Conform will run the formatter on save.
   -- It will pass the table to conform.format().
   -- This can also be a function that returns the table.
@@ -576,6 +581,7 @@ require("conform").formatters.my_formatter = {
 | opts  | `nil\|conform.setupOpts` |                                                                                                                  |                                                                                                                                                                           |
 |       | formatters_by_ft         | `nil\|table<string, conform.FiletypeFormatter>`                                                                  | Map of filetype to formatters                                                                                                                                             |
 |       | format_on_save           | `nil\|conform.FormatOpts\|fun(bufnr: integer): nil\|conform.FormatOpts`                                          | If this is set, Conform will run the formatter on save. It will pass the table to conform.format(). This can also be a function that returns the table.                   |
+|       | default_format_opts      | `nil\|conform.DefaultFormatOpts`                                                                                 | The default options to use when calling conform.format()                                                                                                                  |
 |       | format_after_save        | `nil\|conform.FormatOpts\|fun(bufnr: integer): nil\|conform.FormatOpts`                                          | If this is set, Conform will run the formatter asynchronously after save. It will pass the table to conform.format(). This can also be a function that returns the table. |
 |       | log_level                | `nil\|integer`                                                                                                   | Set the log level (e.g. `vim.log.levels.DEBUG`). Use `:ConformInfo` to see the location of the log file.                                                                  |
 |       | notify_on_error          | `nil\|boolean`                                                                                                   | Conform will notify you when a formatter errors (default true).                                                                                                           |
@@ -596,13 +602,8 @@ Format a buffer
 |          | undojoin                                             | `nil\|boolean`                       | Use undojoin to merge formatting changes with previous edit (default false)                                                                          |
 |          | formatters                                           | `nil\|string[]`                      | List of formatters to run. Defaults to all formatters for the buffer filetype.                                                                       |
 |          | lsp_format                                           | `nil\|conform.LspFormatOpts`         | Configure if and when LSP should be used for formatting. Defaults to "never".                                                                        |
-|          |                                                      | > `"never"`                          | never use the LSP for formatting (default)                                                                                                           |
-|          |                                                      | > `"fallback"`                       | LSP formatting is used when no other formatters are available                                                                                        |
-|          |                                                      | > `"prefer"`                         | use only LSP formatting when available                                                                                                               |
-|          |                                                      | > `"first"`                          | LSP formatting is used when available and then other formatters                                                                                      |
-|          |                                                      | > `"last"`                           | other formatters are used then LSP formatting when available                                                                                         |
 |          | quiet                                                | `nil\|boolean`                       | Don't show any notifications for warnings or failures. Defaults to false.                                                                            |
-|          | range                                                | `nil\|table`                         | Range to format. Table must contain `start` and `end` keys with {row, col} tuples using (1,0) indexing. Defaults to current selection in visual mode |
+|          | range                                                | `nil\|conform.Range`                 | Range to format. Table must contain `start` and `end` keys with {row, col} tuples using (1,0) indexing. Defaults to current selection in visual mode |
 |          | id                                                   | `nil\|integer`                       | Passed to vim.lsp.buf.format when using LSP formatting                                                                                               |
 |          | name                                                 | `nil\|string`                        | Passed to vim.lsp.buf.format when using LSP formatting                                                                                               |
 |          | filter                                               | `nil\|fun(client: table): boolean`   | Passed to vim.lsp.buf.format when using LSP formatting                                                                                               |
diff --git a/doc/conform.txt b/doc/conform.txt
index 3f6568f..32baf86 100644
--- a/doc/conform.txt
+++ b/doc/conform.txt
@@ -33,6 +33,11 @@ OPTIONS                                                          *conform-option
         -- have other formatters configured.
         ["_"] = { "trim_whitespace" },
       },
+      -- Set this to change the default values when calling conform.format()
+      -- This will also affect the default values for format_on_save/format_after_save
+      default_format_opts = {
+        lsp_format = "fallback",
+      },
       -- If this is set, Conform will run the formatter on save.
       -- It will pass the table to conform.format().
       -- This can also be a function that returns the table.
@@ -123,6 +128,15 @@ setup({opts})                                                      *conform.setu
                              If this is set, Conform will run the formatter on
                              save. It will pass the table to conform.format().
                              This can also be a function that returns the table.
+          {default_format_opts} `nil|conform.DefaultFormatOpts` The default
+                             options to use when calling conform.format()
+              {timeout_ms} `nil|integer` Time in milliseconds to block for
+                           formatting. Defaults to 1000. No effect if async =
+                           true.
+              {lsp_format} `nil|conform.LspFormatOpts` Configure if and when LSP
+                           should be used for formatting. Defaults to "never".
+              {quiet}      `nil|boolean` Don't show any notifications for
+                           warnings or failures. Defaults to false.
           {format_after_save} `nil|conform.FormatOpts|fun(bufnr: integer): nil|conform.FormatOpts`
                              If this is set, Conform will run the formatter
                              asynchronously after save. It will pass the table
@@ -156,19 +170,13 @@ format({opts}, {callback}): boolean                               *conform.forma
                        formatters for the buffer filetype.
           {lsp_format} `nil|conform.LspFormatOpts` Configure if and when LSP
                        should be used for formatting. Defaults to "never".
-              `"never"`    never use the LSP for formatting (default)
-              `"fallback"` LSP formatting is used when no other formatters are
-                         available
-              `"prefer"`   use only LSP formatting when available
-              `"first"`    LSP formatting is used when available and then other
-                         formatters
-              `"last"`     other formatters are used then LSP formatting when
-                         available
           {quiet}      `nil|boolean` Don't show any notifications for warnings
                        or failures. Defaults to false.
-          {range}      `nil|table` Range to format. Table must contain `start`
-                       and `end` keys with {row, col} tuples using (1,0)
+          {range}      `nil|conform.Range` Range to format. Table must contain
+                       `start` and `end` keys with {row, col} tuples using (1,0)
                        indexing. Defaults to current selection in visual mode
+              {start} `integer[]`
+              {end}   `integer[]`
           {id}         `nil|integer` Passed to |vim.lsp.buf.format| when using
                        LSP formatting
           {name}       `nil|string` Passed to |vim.lsp.buf.format| when using
diff --git a/lua/conform/init.lua b/lua/conform/init.lua
index f0b2dfd..91ec1bd 100644
--- a/lua/conform/init.lua
+++ b/lua/conform/init.lua
@@ -10,12 +10,17 @@ M.formatters = {}
 
 M.notify_on_error = true
 
+---@type conform.DefaultFormatOpts
+M.default_format_opts = {}
+
 ---@param opts? conform.setupOpts
 M.setup = function(opts)
   opts = opts or {}
 
   M.formatters = vim.tbl_extend("force", M.formatters, opts.formatters or {})
   M.formatters_by_ft = vim.tbl_extend("force", M.formatters_by_ft, opts.formatters_by_ft or {})
+  M.default_format_opts =
+    vim.tbl_extend("force", M.default_format_opts, opts.default_format_opts or {})
 
   if opts.log_level then
     require("conform.log").level = opts.log_level
@@ -328,34 +333,14 @@ local function has_lsp_formatter(opts)
   return not vim.tbl_isempty(lsp_format.get_format_clients(opts))
 end
 
----@alias conform.LspFormatOpts
----| '"never"' # never use the LSP for formatting (default)
----| '"fallback"' # LSP formatting is used when no other formatters are available
----| '"prefer"' # use only LSP formatting when available
----| '"first"' # LSP formatting is used when available and then other formatters
----| '"last"' # other formatters are used then LSP formatting when available
-
----@class conform.FormatOpts
----@field timeout_ms nil|integer Time in milliseconds to block for formatting. Defaults to 1000. No effect if async = true.
----@field bufnr nil|integer Format this buffer (default 0)
----@field async nil|boolean If true the method won't block. Defaults to false. If the buffer is modified before the formatter completes, the formatting will be discarded.
----@field dry_run nil|boolean If true don't apply formatting changes to the buffer
----@field undojoin nil|boolean Use undojoin to merge formatting changes with previous edit (default false)
----@field formatters nil|string[] List of formatters to run. Defaults to all formatters for the buffer filetype.
----@field lsp_format? conform.LspFormatOpts Configure if and when LSP should be used for formatting. Defaults to "never".
----@field quiet nil|boolean Don't show any notifications for warnings or failures. Defaults to false.
----@field range nil|table Range to format. Table must contain `start` and `end` keys with {row, col} tuples using (1,0) indexing. Defaults to current selection in visual mode
----@field id nil|integer Passed to |vim.lsp.buf.format| when using LSP formatting
----@field name nil|string Passed to |vim.lsp.buf.format| when using LSP formatting
----@field filter nil|fun(client: table): boolean Passed to |vim.lsp.buf.format| when using LSP formatting
-
 ---Format a buffer
 ---@param opts? conform.FormatOpts
 ---@param callback? fun(err: nil|string, did_edit: nil|boolean) Called once formatting has completed
 ---@return boolean True if any formatters were attempted
 M.format = function(opts, callback)
   ---@type {timeout_ms: integer, bufnr: integer, async: boolean, dry_run: boolean, lsp_format: "never"|"first"|"last"|"prefer"|"fallback", quiet: boolean, formatters?: string[], range?: conform.Range, undojoin: boolean}
-  opts = vim.tbl_extend("keep", opts or {}, {
+  opts = vim.tbl_extend("keep", opts or {}, M.default_format_opts)
+  opts = vim.tbl_extend("keep", opts, {
     timeout_ms = 1000,
     bufnr = 0,
     async = false,
diff --git a/lua/conform/types.lua b/lua/conform/types.lua
index 05a4e4f..1f1beee 100644
--- a/lua/conform/types.lua
+++ b/lua/conform/types.lua
@@ -60,10 +60,37 @@
 
 ---@alias conform.FormatterUnit string|string[]
 ---@alias conform.FiletypeFormatter conform.FormatterUnit[]|fun(bufnr: integer): string[]
+---
+---@alias conform.LspFormatOpts
+---| '"never"' # never use the LSP for formatting (default)
+---| '"fallback"' # LSP formatting is used when no other formatters are available
+---| '"prefer"' # use only LSP formatting when available
+---| '"first"' # LSP formatting is used when available and then other formatters
+---| '"last"' # other formatters are used then LSP formatting when available
+
+---@class (exact) conform.FormatOpts
+---@field timeout_ms? integer Time in milliseconds to block for formatting. Defaults to 1000. No effect if async = true.
+---@field bufnr? integer Format this buffer (default 0)
+---@field async? boolean If true the method won't block. Defaults to false. If the buffer is modified before the formatter completes, the formatting will be discarded.
+---@field dry_run? boolean If true don't apply formatting changes to the buffer
+---@field undojoin? boolean Use undojoin to merge formatting changes with previous edit (default false)
+---@field formatters? string[] List of formatters to run. Defaults to all formatters for the buffer filetype.
+---@field lsp_format? conform.LspFormatOpts Configure if and when LSP should be used for formatting. Defaults to "never".
+---@field quiet? boolean Don't show any notifications for warnings or failures. Defaults to false.
+---@field range? conform.Range Range to format. Table must contain `start` and `end` keys with {row, col} tuples using (1,0) indexing. Defaults to current selection in visual mode
+---@field id? integer Passed to |vim.lsp.buf.format| when using LSP formatting
+---@field name? string Passed to |vim.lsp.buf.format| when using LSP formatting
+---@field filter? fun(client: table): boolean Passed to |vim.lsp.buf.format| when using LSP formatting
+
+---@class (exact) conform.DefaultFormatOpts
+---@field timeout_ms? integer Time in milliseconds to block for formatting. Defaults to 1000. No effect if async = true.
+---@field lsp_format? conform.LspFormatOpts Configure if and when LSP should be used for formatting. Defaults to "never".
+---@field quiet? boolean Don't show any notifications for warnings or failures. Defaults to false.
 
 ---@class (exact) conform.setupOpts
 ---@field formatters_by_ft? table<string, conform.FiletypeFormatter> Map of filetype to formatters
 ---@field format_on_save? conform.FormatOpts|fun(bufnr: integer): nil|conform.FormatOpts If this is set, Conform will run the formatter on save. It will pass the table to conform.format(). This can also be a function that returns the table.
+---@field default_format_opts? conform.DefaultFormatOpts The default options to use when calling conform.format()
 ---@field format_after_save? conform.FormatOpts|fun(bufnr: integer): nil|conform.FormatOpts If this is set, Conform will run the formatter asynchronously after save. It will pass the table to conform.format(). This can also be a function that returns the table.
 ---@field log_level? integer Set the log level (e.g. `vim.log.levels.DEBUG`). Use `:ConformInfo` to see the location of the log file.
 ---@field notify_on_error? boolean Conform will notify you when a formatter errors (default true).
diff --git a/scripts/options_doc.lua b/scripts/options_doc.lua
index 193b462..d47c832 100644
--- a/scripts/options_doc.lua
+++ b/scripts/options_doc.lua
@@ -20,6 +20,11 @@ require("conform").setup({
     -- have other formatters configured.
     ["_"] = { "trim_whitespace" },
   },
+  -- Set this to change the default values when calling conform.format()
+  -- This will also affect the default values for format_on_save/format_after_save
+  default_format_opts = {
+    lsp_format = "fallback",
+  },
   -- If this is set, Conform will run the formatter on save.
   -- It will pass the table to conform.format().
   -- This can also be a function that returns the table.