diff options
-rw-r--r-- | README.md | 35 | ||||
-rw-r--r-- | doc/conform.txt | 27 | ||||
-rw-r--r-- | lua/conform/init.lua | 9 |
3 files changed, 44 insertions, 27 deletions
@@ -574,21 +574,26 @@ require("conform").formatters.my_formatter = { `format(opts, callback): boolean` \ Format a buffer -| Param | Type | Desc | | -| -------- | ---------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 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 | -| | formatters | `nil\|string[]` | List of formatters to run. Defaults to all formatters for the buffer filetype. | -| | lsp_format | `nil\|"never"\|"fallback"\|"prefer"\|"first"\|"last"` | "fallback" LSP formatting when no other formatters are available, "prefer" only LSP formatting when available, "first" LSP formatting then other formatters, "last" other formatters then LSP. | -| | 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 | -| callback | `nil\|fun(err: nil\|string, did_edit: nil\|boolean)` | Called once formatting has completed | | +| Param | Type | Desc | | +| -------- | ---------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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 | +| | 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 | +| | 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 | +| callback | `nil\|fun(err: nil\|string, did_edit: nil\|boolean)` | Called once formatting has completed | | Returns: diff --git a/doc/conform.txt b/doc/conform.txt index a3d3c2e..4d2c0b6 100644 --- a/doc/conform.txt +++ b/doc/conform.txt @@ -119,12 +119,12 @@ setup({opts}) *conform.setu {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` I - f this is set, Conform will run the formatter on + {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. - {format_after_save} `nil|conform.FormatOpts|fun(bufnr: integer): nil|conform.FormatOpts` I - f this is set, Conform will run the formatter + {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. @@ -133,8 +133,8 @@ 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). - {formatters} `nil|table<string, conform.FormatterConfigOverride|fun(bufnr: integer): nil|conform.FormatterConfigOverride>` C - ustom formatters and overrides for built-in + {formatters} `nil|table<string, conform.FormatterConfigOverride|fun(bufnr: integer): nil|conform.FormatterConfigOverride>` + Custom formatters and overrides for built-in formatters. format({opts}, {callback}): boolean *conform.format* @@ -152,11 +152,16 @@ format({opts}, {callback}): boolean *conform.forma the buffer {formatters} `nil|string[]` List of formatters to run. Defaults to all formatters for the buffer filetype. - {lsp_format} `nil|"never"|"fallback"|"prefer"|"first"|"last"` "fallbac - k" LSP formatting when no other formatters are available, - "prefer" only LSP formatting when available, "first" LSP - formatting then other formatters, "last" other formatters - then LSP. + {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` diff --git a/lua/conform/init.lua b/lua/conform/init.lua index 0bab347..aa97f1c 100644 --- a/lua/conform/init.lua +++ b/lua/conform/init.lua @@ -328,13 +328,20 @@ 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 formatters nil|string[] List of formatters to run. Defaults to all formatters for the buffer filetype. ----@field lsp_format? "never"|"fallback"|"prefer"|"first"|"last" "fallback" LSP formatting when no other formatters are available, "prefer" only LSP formatting when available, "first" LSP formatting then other formatters, "last" other formatters then LSP. +---@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 |