From f3b930db4964d60e255c8f9e37b7f2218dfc08cb Mon Sep 17 00:00:00 2001 From: Steven Arcangeli Date: Wed, 22 May 2024 00:49:10 -0700 Subject: doc: add type annotations for setup() function --- README.md | 17 ++++++++++++- doc/conform.txt | 26 ++++++++++++++++++- lua/conform/fs.lua | 2 +- lua/conform/init.lua | 67 +++--------------------------------------------- lua/conform/types.lua | 68 +++++++++++++++++++++++++++++++++++++++++++++++++ scripts/options_doc.lua | 2 +- 6 files changed, 115 insertions(+), 67 deletions(-) create mode 100644 lua/conform/types.lua diff --git a/README.md b/README.md index 29b6d68..5b3f2cf 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ Lightweight yet powerful formatter plugin for Neovim - [Options](#options) - [Formatter options](#formatter-options) - [API](#api) + - [setup(opts)](#setupopts) - [format(opts, callback)](#formatopts-callback) - [list_formatters(bufnr)](#list_formattersbufnr) - [list_all_formatters()](#list_all_formatters) @@ -463,7 +464,7 @@ require("conform").setup({ log_level = vim.log.levels.ERROR, -- Conform will notify you when a formatter errors notify_on_error = true, - -- Custom formatters and changes to built-in formatters + -- Custom formatters and overrides for built-in formatters formatters = { my_formatter = { -- This can be a string or a function that returns a string. @@ -535,6 +536,20 @@ require("conform").formatters.my_formatter = { +### setup(opts) + +`setup(opts)` + +| Param | Type | Desc | | +| ----- | ------------------------ | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| opts | `nil\|conform.setupOpts` | | | +| | formatters_by_ft | `nil\|table` | Map of filetype to formatters | +| | format_on_save | `nil\|conform.FormatOpts\|fun(bufnr: integer): 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): 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). | +| | formatters | `nil\|table` | Custom formatters and overrides for built-in formatters. | + ### format(opts, callback) `format(opts, callback): boolean` \ diff --git a/doc/conform.txt b/doc/conform.txt index 2048692..4271e95 100644 --- a/doc/conform.txt +++ b/doc/conform.txt @@ -51,7 +51,7 @@ OPTIONS *conform-option log_level = vim.log.levels.ERROR, -- Conform will notify you when a formatter errors notify_on_error = true, - -- Custom formatters and changes to built-in formatters + -- Custom formatters and overrides for built-in formatters formatters = { my_formatter = { -- This can be a string or a function that returns a string. @@ -109,6 +109,30 @@ OPTIONS *conform-option -------------------------------------------------------------------------------- API *conform-api* +setup({opts}) *conform.setup* + + Parameters: + {opts} `nil|conform.setupOpts` + {formatters_by_ft} `nil|table` Map + of filetype to formatters + {format_on_save} `nil|conform.FormatOpts|fun(bufnr: integer): conform.FormatOpts` I + f 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): conform.FormatOpts` I + f 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). + {formatters} `nil|table` C + ustom formatters and overrides for built-in + formatters. + format({opts}, {callback}): boolean *conform.format* Format a buffer diff --git a/lua/conform/fs.lua b/lua/conform/fs.lua index 187bd7c..d3b5fed 100644 --- a/lua/conform/fs.lua +++ b/lua/conform/fs.lua @@ -30,7 +30,7 @@ M.abspath = function(path) return path end ---- Returns true if candidate is a subpath of root, or if they are the same path. +---Returns true if candidate is a subpath of root, or if they are the same path. ---@param root string ---@param candidate string ---@return boolean diff --git a/lua/conform/init.lua b/lua/conform/init.lua index 20048a9..705cf6a 100644 --- a/lua/conform/init.lua +++ b/lua/conform/init.lua @@ -2,67 +2,6 @@ local islist = vim.islist or vim.tbl_islist local M = {} ----@class (exact) conform.FormatterInfo ----@field name string ----@field command string ----@field cwd? string ----@field available boolean ----@field available_msg? string - ----@class (exact) conform.JobFormatterConfig ----@field command string|fun(self: conform.JobFormatterConfig, ctx: conform.Context): string ----@field args? string|string[]|fun(self: conform.JobFormatterConfig, ctx: conform.Context): string|string[] ----@field range_args? fun(self: conform.JobFormatterConfig, ctx: conform.RangeContext): string|string[] ----@field cwd? fun(self: conform.JobFormatterConfig, ctx: conform.Context): nil|string ----@field require_cwd? boolean When cwd is not found, don't run the formatter (default false) ----@field stdin? boolean Send buffer contents to stdin (default true) ----@field tmpfile_format? string When stdin=false, use this format for temporary files (default ".conform.$RANDOM.$FILENAME") ----@field condition? fun(self: conform.JobFormatterConfig, ctx: conform.Context): boolean ----@field exit_codes? integer[] Exit codes that indicate success (default {0}) ----@field env? table|fun(self: conform.JobFormatterConfig, ctx: conform.Context): table ----@field options? table - ----@class (exact) conform.LuaFormatterConfig ----@field format fun(self: conform.LuaFormatterConfig, ctx: conform.Context, lines: string[], callback: fun(err: nil|string, new_lines: nil|string[])) ----@field condition? fun(self: conform.LuaFormatterConfig, ctx: conform.Context): boolean ----@field options? table - ----@class (exact) conform.FileLuaFormatterConfig : conform.LuaFormatterConfig ----@field meta conform.FormatterMeta - ----@class (exact) conform.FileFormatterConfig : conform.JobFormatterConfig ----@field meta conform.FormatterMeta - ----@alias conform.FormatterConfig conform.JobFormatterConfig|conform.LuaFormatterConfig - ----@class (exact) conform.FormatterConfigOverride : conform.JobFormatterConfig ----@field inherit? boolean ----@field command? string|fun(self: conform.FormatterConfig, ctx: conform.Context): string ----@field prepend_args? string|string[]|fun(self: conform.FormatterConfig, ctx: conform.Context): string|string[] ----@field format? fun(self: conform.LuaFormatterConfig, ctx: conform.Context, lines: string[], callback: fun(err: nil|string, new_lines: nil|string[])) Mutually exclusive with command ----@field options? table - ----@class (exact) conform.FormatterMeta ----@field url string ----@field description string ----@field deprecated? boolean - ----@class (exact) conform.Context ----@field buf integer ----@field filename string ----@field dirname string ----@field range? conform.Range - ----@class (exact) conform.RangeContext : conform.Context ----@field range conform.Range - ----@class (exact) conform.Range ----@field start integer[] ----@field end integer[] - ----@alias conform.FormatterUnit string|string[] ----@alias conform.FiletypeFormatter conform.FormatterUnit[]|fun(bufnr: integer): string[] - ---@type table M.formatters_by_ft = {} @@ -71,6 +10,7 @@ M.formatters = {} M.notify_on_error = true +---@param opts? conform.setupOpts M.setup = function(opts) opts = opts or {} @@ -80,8 +20,9 @@ M.setup = function(opts) if opts.log_level then require("conform.log").level = opts.log_level end - if opts.notify_on_error ~= nil then - M.notify_on_error = opts.notify_on_error + local notify_on_error = opts.notify_on_error + if notify_on_error ~= nil then + M.notify_on_error = notify_on_error end local aug = vim.api.nvim_create_augroup("Conform", { clear = true }) diff --git a/lua/conform/types.lua b/lua/conform/types.lua new file mode 100644 index 0000000..bd98426 --- /dev/null +++ b/lua/conform/types.lua @@ -0,0 +1,68 @@ +---@class (exact) conform.FormatterInfo +---@field name string +---@field command string +---@field cwd? string +---@field available boolean +---@field available_msg? string + +---@class (exact) conform.JobFormatterConfig +---@field command string|fun(self: conform.JobFormatterConfig, ctx: conform.Context): string +---@field args? string|string[]|fun(self: conform.JobFormatterConfig, ctx: conform.Context): string|string[] +---@field range_args? fun(self: conform.JobFormatterConfig, ctx: conform.RangeContext): string|string[] +---@field cwd? fun(self: conform.JobFormatterConfig, ctx: conform.Context): nil|string +---@field require_cwd? boolean When cwd is not found, don't run the formatter (default false) +---@field stdin? boolean Send buffer contents to stdin (default true) +---@field tmpfile_format? string When stdin=false, use this format for temporary files (default ".conform.$RANDOM.$FILENAME") +---@field condition? fun(self: conform.JobFormatterConfig, ctx: conform.Context): boolean +---@field exit_codes? integer[] Exit codes that indicate success (default {0}) +---@field env? table|fun(self: conform.JobFormatterConfig, ctx: conform.Context): table +---@field options? table + +---@class (exact) conform.LuaFormatterConfig +---@field format fun(self: conform.LuaFormatterConfig, ctx: conform.Context, lines: string[], callback: fun(err: nil|string, new_lines: nil|string[])) +---@field condition? fun(self: conform.LuaFormatterConfig, ctx: conform.Context): boolean +---@field options? table + +---@class (exact) conform.FileLuaFormatterConfig : conform.LuaFormatterConfig +---@field meta conform.FormatterMeta + +---@class (exact) conform.FileFormatterConfig : conform.JobFormatterConfig +---@field meta conform.FormatterMeta + +---@alias conform.FormatterConfig conform.JobFormatterConfig|conform.LuaFormatterConfig + +---@class (exact) conform.FormatterConfigOverride : conform.JobFormatterConfig +---@field inherit? boolean +---@field command? string|fun(self: conform.FormatterConfig, ctx: conform.Context): string +---@field prepend_args? string|string[]|fun(self: conform.FormatterConfig, ctx: conform.Context): string|string[] +---@field format? fun(self: conform.LuaFormatterConfig, ctx: conform.Context, lines: string[], callback: fun(err: nil|string, new_lines: nil|string[])) Mutually exclusive with command +---@field options? table + +---@class (exact) conform.FormatterMeta +---@field url string +---@field description string +---@field deprecated? boolean + +---@class (exact) conform.Context +---@field buf integer +---@field filename string +---@field dirname string +---@field range? conform.Range + +---@class (exact) conform.RangeContext : conform.Context +---@field range conform.Range + +---@class (exact) conform.Range +---@field start integer[] +---@field end integer[] + +---@alias conform.FormatterUnit string|string[] +---@alias conform.FiletypeFormatter conform.FormatterUnit[]|fun(bufnr: integer): string[] + +---@class (exact) conform.setupOpts +---@field formatters_by_ft? table Map of filetype to formatters +---@field format_on_save? conform.FormatOpts|fun(bufnr: integer): 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 format_after_save? conform.FormatOpts|fun(bufnr: integer): 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). +---@field formatters? table Custom formatters and overrides for built-in formatters. diff --git a/scripts/options_doc.lua b/scripts/options_doc.lua index 3e22802..238cd33 100644 --- a/scripts/options_doc.lua +++ b/scripts/options_doc.lua @@ -38,7 +38,7 @@ require("conform").setup({ log_level = vim.log.levels.ERROR, -- Conform will notify you when a formatter errors notify_on_error = true, - -- Custom formatters and changes to built-in formatters + -- Custom formatters and overrides for built-in formatters formatters = { my_formatter = { -- This can be a string or a function that returns a string. -- cgit v1.2.3-70-g09d2