diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/conform.txt | 17 | ||||
-rw-r--r-- | doc/recipes.md | 78 |
2 files changed, 19 insertions, 76 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", } diff --git a/doc/recipes.md b/doc/recipes.md index 2d33ca2..97eaa16 100644 --- a/doc/recipes.md +++ b/doc/recipes.md @@ -3,11 +3,9 @@ <!-- TOC --> - [Format command](#format-command) -- [Customizing formatters](#customizing-formatters) - [Autoformat with extra features](#autoformat-with-extra-features) - [Command to toggle format-on-save](#command-to-toggle-format-on-save) - [Automatically run slow formatters async](#automatically-run-slow-formatters-async) -- [Add extra arguments to a formatter command](#add-extra-arguments-to-a-formatter-command) - [Lazy loading with lazy.nvim](#lazy-loading-with-lazynvim) <!-- /TOC --> @@ -30,37 +28,6 @@ vim.api.nvim_create_user_command("Format", function(args) end, { range = true }) ``` -## Customizing formatters - -If you want to customize how a formatter runs (for example, to pass in environment variables or -change the command arguments), you can either edit the formatter directly or create one yourself. - -```lua --- Directly change the values on the built-in configuration -require("conform.formatters.yamlfix").env = { - YAMLFIX_SEQUENCE_STYLE = "block_style", -} - --- Or create your own formatter that overrides certain values -require("conform").formatters.yamlfix = - vim.tbl_deep_extend("force", require("conform.formatters.yamlfix"), { - env = { - YAMLFIX_SEQUENCE_STYLE = "block_style", - }, - }) - --- Here is an example that modifies the command arguments for prettier to add --- a custom config file, if it is present -require("conform.formatters.prettier").args = function(ctx) - local args = { "--stdin-filepath", "$FILENAME" } - local found = vim.fs.find(".custom-config.json", { upward = true, path = ctx.dirname })[1] - if found then - vim.list_extend(args, { "--config", found }) - end - return args -end -``` - ## Autoformat with extra features If you want more complex logic than the basic `format_on_save` option allows, you can use a function instead. @@ -168,36 +135,6 @@ require("conform").setup({ }) ``` -## Add extra arguments to a formatter command - -The official recommended way to change the arguments of a formatter is to just copy the default -values and mutate them however you like. For example: - -```lua -require("conform.formatters.shfmt").args = { "-i", "4", "-filename", "$FILENAME" } -``` - -But if you really want to _add_ arguments instead of replacing them, there is a utility function to -make this easier: - -```lua -local util = require("conform.util") -local prettier = require("conform.formatters.prettier") -require("conform").formatters.prettier = vim.tbl_deep_extend("force", prettier, { - args = util.extend_args(prettier.args, { "--tab", "--indent", "2" }), - range_args = util.extend_args(prettier.range_args, { "--tab", "--indent", "2" }), -}) - --- Pass append=true to append the extra arguments to the end -local deno_fmt = require("conform.formatters.deno_fmt") -require("conform").formatters.deno_fmt = vim.tbl_deep_extend("force", deno_fmt, { - args = util.extend_args(deno_fmt.args, { "--use-tabs" }, { append = true }), -}) - --- There is also a utility to modify a formatter in-place -util.add_formatter_args(require("conform.formatters.prettier"), { "--tab", "--indent", "2" }) -``` - ## Lazy loading with lazy.nvim Here is the recommended config for lazy-loading using lazy.nvim @@ -220,23 +157,24 @@ return { }, -- Everything in opts will be passed to setup() opts = { + -- Define your formatters formatters_by_ft = { lua = { "stylua" }, python = { "isort", "black" }, javascript = { { "prettierd", "prettier" } }, }, + -- Set up format-on-save format_on_save = { timeout_ms = 500, lsp_fallback = true }, + -- Customize formatters + formatters = { + shfmt = { + prepend_args = { "-i", "2" }, + }, + }, }, init = function() -- If you want the formatexpr, here is the place to set it vim.o.formatexpr = "v:lua.require'conform'.formatexpr()" end, - - -- This function is optional, but if you want to customize formatters do it here - config = function(_, opts) - local util = require("conform.util") - util.add_formatter_args(require("conform.formatters.shfmt"), { "-i", "2" }) - require("conform").setup(opts) - end, } ``` |