Merge pull request #491 from stevearc/stevearc-config-refactor

feat!: large rework of configuration logic

1 files changed, 78 insertions, 35 deletions

diff --git a/doc/conform.txt b/doc/conform.txt
index 3f6568f..5af52f8 100644
--- a/doc/conform.txt
+++ b/doc/conform.txt
@@ -17,8 +17,8 @@ OPTIONS                                                          *conform-option
         lua = { "stylua" },
         -- Conform will run multiple formatters sequentially
         go = { "goimports", "gofmt" },
-        -- Use a sub-list to run only the first available formatter
-        javascript = { { "prettierd", "prettier" } },
+        -- You can also customize some of the format options for the filetype
+        rust = { "rustfmt", lsp_format = "fallback" },
         -- You can use a function here to determine the formatters dynamically
         python = function(bufnr)
           if require("conform").get_formatter_info("ruff_format", bufnr).available then
@@ -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.
@@ -51,6 +56,8 @@ OPTIONS                                                          *conform-option
       log_level = vim.log.levels.ERROR,
       -- Conform will notify you when a formatter errors
       notify_on_error = true,
+      -- Conform will notify you when no formatters are available for the buffer
+      notify_no_formatters = true,
       -- Custom formatters and overrides for built-in formatters
       formatters = {
         my_formatter = {
@@ -87,7 +94,6 @@ OPTIONS                                                          *conform-option
           -- Set to false to disable merging the config with the base definition
           inherit = true,
           -- When inherit = true, add these additional arguments to the beginning of the command.
-          -- When inherit = true, add these additional arguments to the command.
           -- This can also be a function, like args
           prepend_args = { "--use-tabs" },
           -- When inherit = true, add these additional arguments to the end of the command.
@@ -123,6 +129,26 @@ 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".
+                  `"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.
+              {stop_after_first} `nil|boolean` Only run the first available
+                                 formatter in the list. 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
@@ -133,6 +159,9 @@ setup({opts})                                                      *conform.setu
                              the location of the log file.
           {notify_on_error}  `nil|boolean` Conform will notify you when a
                              formatter errors (default true).
+          {notify_no_formatters} `nil|boolean` Conform will notify you when no
+                             formatters are available for the buffer (default
+                             true).
           {formatters}       `nil|table<string, conform.FormatterConfigOverride|fun(bufnr: integer): nil|conform.FormatterConfigOverride>`
                              Custom formatters and overrides for built-in
                              formatters.
@@ -142,20 +171,23 @@ format({opts}, {callback}): boolean                               *conform.forma
 
     Parameters:
       {opts}     `nil|conform.FormatOpts`
-          {timeout_ms} `nil|integer` Time in milliseconds to block for
-                       formatting. Defaults to 1000. No effect if async = true.
-          {bufnr}      `nil|integer` Format this buffer (default 0)
-          {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.
-          {dry_run}    `nil|boolean` If true don't apply formatting changes to
-                       the 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".
+          {timeout_ms}       `nil|integer` Time in milliseconds to block for
+                             formatting. Defaults to 1000. No effect if async =
+                             true.
+          {bufnr}            `nil|integer` Format this buffer (default 0)
+          {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.
+          {dry_run}          `nil|boolean` If true don't apply formatting
+                             changes to the 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
@@ -164,17 +196,22 @@ format({opts}, {callback}): boolean                               *conform.forma
                          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
-          {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
+          {stop_after_first} `nil|boolean` Only run the first available
+                             formatter in the list. Defaults to false.
+          {quiet}            `nil|boolean` Don't show any notifications for
+                             warnings or failures. Defaults to false.
+          {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 LSP formatting
+          {filter}           `nil|fun(client: table): boolean` Passed to |vim.ls
+                             p.buf.format| when using LSP formatting
       {callback} `nil|fun(err: nil|string, did_edit: nil|boolean)` Called once
                  formatting has completed
     Returns:
@@ -186,6 +223,18 @@ list_formatters({bufnr}): conform.FormatterInfo[]        *conform.list_formatter
     Parameters:
       {bufnr} `nil|integer`
 
+list_formatters_to_run({bufnr}): conform.FormatterInfo[], boolean *conform.list_formatters_to_run*
+    Get the exact formatters that will be run for a buffer.
+
+    Parameters:
+      {bufnr} `nil|integer`
+    Returns:
+      `conform.FormatterInfo[]`
+      `boolean` lsp Will use LSP formatter
+
+    Note:
+      This accounts for stop_after_first, lsp fallback logic, etc.
+
 list_all_formatters(): conform.FormatterInfo[]       *conform.list_all_formatters*
     List information about all filetype-configured formatters
 
@@ -197,12 +246,6 @@ get_formatter_info({formatter}, {bufnr}): conform.FormatterInfo *conform.get_for
       {formatter} `string` The name of the formatter
       {bufnr}     `nil|integer`
 
-will_fallback_lsp({options}): boolean                  *conform.will_fallback_lsp*
-    Check if the buffer will use LSP formatting when lsp_format = "fallback"
-
-    Parameters:
-      {options} `nil|table` Options passed to |vim.lsp.buf.format|
-
 --------------------------------------------------------------------------------
 FORMATTERS                                                    *conform-formatters*
 
@@ -258,7 +301,7 @@ FORMATTERS                                                    *conform-formatter
               follows Dart guidelines.
 `dcm_fix` - Fixes issues produced by dcm analyze, dcm check-unused-code or dcm
           check-dependencies commands.
-`dcm_format` - Formats *.dart files.
+`dcm_format` - Formats .dart files.
 `deno_fmt` - Use [Deno](https://deno.land/) to format TypeScript,
            JavaScript/JSON and markdown.
 `dfmt` - Formatter for D source code.