` | Custom formatters and overrides for built-in formatters. |
### format(opts, callback)
`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 |
| | 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 |
| | 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 |
| | 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:
| Type | Desc |
| ------- | ------------------------------------- |
| boolean | True if any formatters were attempted |
### list_formatters(bufnr)
`list_formatters(bufnr): conform.FormatterInfo[]` \
Retrieve the available formatters for a buffer
| Param | Type | Desc |
| ----- | -------------- | ---- |
| bufnr | `nil\|integer` | |
### list_formatters_to_run(bufnr)
`list_formatters_to_run(bufnr): conform.FormatterInfo[], boolean` \
Get the exact formatters that will be run for a buffer.
| Param | Type | Desc |
| ----- | -------------- | ---- |
| bufnr | `nil\|integer` | |
Returns:
| Type | Desc |
| ----------------------- | -------------------------- |
| conform.FormatterInfo[] | |
| boolean | lsp Will use LSP formatter |
**Note:**
This accounts for stop_after_first, lsp fallback logic, etc.
### list_all_formatters()
`list_all_formatters(): conform.FormatterInfo[]` \
List information about all filetype-configured formatters
### get_formatter_info(formatter, bufnr)
`get_formatter_info(formatter, bufnr): conform.FormatterInfo` \
Get information about a formatter (including availability)
| Param | Type | Desc |
| --------- | -------------- | ------------------------- |
| formatter | `string` | The name of the formatter |
| bufnr | `nil\|integer` | |
## Acknowledgements
Thanks to
- [nvim-lint](https://github.com/mfussenegger/nvim-lint) for providing inspiration for the config and API. It's an excellent plugin that balances power and simplicity.
- [null-ls](https://github.com/jose-elias-alvarez/null-ls.nvim) for formatter configurations and being my formatter/linter of choice for a long time.