feat(spec)!: setting a table to `Plugin.config` is now deprecated. Please use `Plugin.opts` instead. (backward compatible for now)

This commit is contained in:
Folke Lemaitre 2023-01-08 15:01:49 +01:00
parent 6a31b97e37
commit 7260a2b28b
No known key found for this signature in database
GPG Key ID: 41F8B1FBACAE2040
7 changed files with 150 additions and 59 deletions

View File

@ -80,7 +80,7 @@ require("lazy").setup({
## 🔌 Plugin Spec ## 🔌 Plugin Spec
| Property | Type | Description | | Property | Type | Description |
| ---------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ---------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[1]` | `string?` | Short plugin url. Will be expanded using `config.git.url_format` | | `[1]` | `string?` | Short plugin url. Will be expanded using `config.git.url_format` |
| **dir** | `string?` | A directory pointing to a local plugin | | **dir** | `string?` | A directory pointing to a local plugin |
| **url** | `string?` | A custom git url where the plugin is hosted | | **url** | `string?` | A custom git url where the plugin is hosted |
@ -91,7 +91,8 @@ require("lazy").setup({
| **cond** | `boolean?` or `fun():boolean` | When `false`, or if the `function` returns false, then this plugin will not be loaded. Useful to disable some plugins in vscode, or firenvim for example. | | **cond** | `boolean?` or `fun():boolean` | When `false`, or if the `function` returns false, then this plugin will not be loaded. Useful to disable some plugins in vscode, or firenvim for example. |
| **dependencies** | `LazySpec[]` | A list of plugin names or plugin specs that should be loaded when the plugin loads. Dependencies are always lazy-loaded unless specified otherwise. When specifying a name, make sure the plugin spec has been defined somewhere else. | | **dependencies** | `LazySpec[]` | A list of plugin names or plugin specs that should be loaded when the plugin loads. Dependencies are always lazy-loaded unless specified otherwise. When specifying a name, make sure the plugin spec has been defined somewhere else. |
| **init** | `fun(LazyPlugin)` | `init` functions are always executed during startup | | **init** | `fun(LazyPlugin)` | `init` functions are always executed during startup |
| **config** | `fun(LazyPlugin)` or `true` or `table` | `config` is executed when the plugin loads. You can also set to `true` or pass a `table`, that will be passed to `require("plugin").setup(opts)` | | **config** | `fun(LazyPlugin, opts:table)` or `true` | `config` is executed when the plugin loads. You can also set it to `true`, to automatically run `require("plugin").setup(opts)`. See also `opts`. |
| **opts** | `table` or `fun(LazyPlugin, opts:table)` | `opts` should be a table (will be merged with parent specs), return a table (replaces parent specs) or should change a table. The table will be passed to the `Plugin.config()` function. Setting this value will imply `Plugin.config()` |
| **build** | `fun(LazyPlugin)` or `string` or a list of build commands | `build` is executed when a plugin is installed or updated. If it's a string it will be ran as a shell command. When prefixed with `:` it is a Neovim command. You can also specify a list to executed multiple build commands | | **build** | `fun(LazyPlugin)` or `string` or a list of build commands | `build` is executed when a plugin is installed or updated. If it's a string it will be ran as a shell command. When prefixed with `:` it is a Neovim command. You can also specify a list to executed multiple build commands |
| **branch** | `string?` | Branch of the repository | | **branch** | `string?` | Branch of the repository |
| **tag** | `string?` | Tag of the repository | | **tag** | `string?` | Tag of the repository |
@ -224,11 +225,11 @@ return {
config = true, -- run require("neorg").setup() config = true, -- run require("neorg").setup()
}, },
-- or set a custom config: -- or set custom options:
{ {
"nvim-neorg/neorg", "nvim-neorg/neorg",
ft = "norg", ft = "norg",
config = { foo = "bar" }, -- run require("neorg").setup({foo = "bar"}) opts = { foo = "bar" }, -- run require("neorg").setup({foo = "bar"})
}, },
{ {
@ -660,6 +661,24 @@ For a real-life example, you can check [LazyVim](https://github.com/LazyVim/Lazy
- [lazyvim.plugins](https://github.com/LazyVim/LazyVim/tree/main/lua/lazyvim/plugins) contains all the plugin specs that will be loaded - [lazyvim.plugins](https://github.com/LazyVim/LazyVim/tree/main/lua/lazyvim/plugins) contains all the plugin specs that will be loaded
### ↩️ Importing Specs, `config` & `opts`
As part of a spec, you can add `import` statements to import additional plugin modules.
Both of the `setup()` calls are equivalent:
```lua
require("lazy").setup("plugins")
-- same as:
require("lazy").setup({{import = "plugins"}})
```
When you import specs, you can override them by simply adding a spec for the same plugin to your local
specs, adding any keys you want to override / merge.
`opts`, `dependencies`, `cmd`, `event`, `ft` and `keys` are always merged with the parent spec.
Any other property will override the property from the parent spec.
## 📦 Migration Guide ## 📦 Migration Guide
### [packer.nvim](https://github.com/wbthomason/packer.nvim) ### [packer.nvim](https://github.com/wbthomason/packer.nvim)

View File

@ -220,7 +220,7 @@ function M._load(plugin, reason, opts)
end end
M.packadd(plugin.dir) M.packadd(plugin.dir)
if plugin.config then if plugin.config or plugin.opts then
M.config(plugin) M.config(plugin)
end end
@ -231,13 +231,32 @@ function M._load(plugin, reason, opts)
end) end)
end end
-- Merges super opts or runs the opts function to override opts or return new ones
---@param plugin LazyPlugin
function M.opts(plugin)
local opts = plugin._.super and M.opts(plugin._.super) or {}
---@type PluginOpts?
local plugin_opts = rawget(plugin, "opts")
if type(plugin_opts) == "table" then
opts = Util.merge(opts, plugin_opts)
elseif type(plugin_opts) == "function" then
local new_opts = plugin_opts(plugin, opts)
if new_opts then
opts = new_opts
end
end
return opts
end
--- runs plugin config --- runs plugin config
---@param plugin LazyPlugin ---@param plugin LazyPlugin
function M.config(plugin) function M.config(plugin)
local fn local fn
if type(plugin.config) == "function" then if type(plugin.config) == "function" then
fn = function() fn = function()
plugin.config(plugin) plugin.config(plugin, M.opts(plugin))
end end
else else
local normname = Util.normname(plugin.name) local normname = Util.normname(plugin.name)
@ -254,8 +273,8 @@ function M.config(plugin)
end end
if #mods == 1 then if #mods == 1 then
fn = function() fn = function()
local opts = plugin.config local opts = M.opts(plugin)
if opts == true then if next(opts) == nil then
opts = nil opts = nil
end end
require(mods[1]).setup(opts) require(mods[1]).setup(opts)

View File

@ -87,6 +87,15 @@ function Spec:add(plugin, results, is_dep)
plugin.cmd = type(plugin.cmd) == "string" and { plugin.cmd } or plugin.cmd plugin.cmd = type(plugin.cmd) == "string" and { plugin.cmd } or plugin.cmd
plugin.ft = type(plugin.ft) == "string" and { plugin.ft } or plugin.ft plugin.ft = type(plugin.ft) == "string" and { plugin.ft } or plugin.ft
if type(plugin.config) == "table" then
self:warn(
"{" .. plugin.name .. "}: setting a table to `Plugin.config` is deprecated. Please use `Plugin.opts` instead"
)
---@diagnostic disable-next-line: assign-type-mismatch
plugin.opts = plugin.config
plugin.config = nil
end
plugin._ = {} plugin._ = {}
plugin._.dep = is_dep plugin._.dep = is_dep

View File

@ -31,11 +31,11 @@ return {
config = true, -- run require("neorg").setup() config = true, -- run require("neorg").setup()
}, },
-- or set a custom config: -- or set custom options:
{ {
"nvim-neorg/neorg", "nvim-neorg/neorg",
ft = "norg", ft = "norg",
config = { foo = "bar" }, -- run require("neorg").setup({foo = "bar"}) opts = { foo = "bar" }, -- run require("neorg").setup({foo = "bar"})
}, },
{ {

View File

@ -68,8 +68,12 @@ function M.check_override(plugin)
return return
end end
local Handler = require("lazy.core.handler")
local skip = { "dependencies", "_", "opts" }
vim.list_extend(skip, vim.tbl_values(Handler.types))
for key, value in pairs(plugin._.super) do for key, value in pairs(plugin._.super) do
if key ~= "_" and plugin[key] and plugin[key] ~= value then if not vim.tbl_contains(skip, key) and plugin[key] and plugin[key] ~= value then
vim.health.report_warn("{" .. plugin.name .. "}: overriding <" .. key .. ">") vim.health.report_warn("{" .. plugin.name .. "}: overriding <" .. key .. ">")
end end
end end
@ -77,29 +81,31 @@ end
M.valid = { M.valid = {
1, 1,
"name",
"url",
"enabled",
"lazy",
"dev",
"dependencies",
"init",
"config",
"build",
"branch",
"tag",
"commit",
"version",
"module",
"pin",
"cmd",
"event",
"keys",
"ft",
"dir",
"priority",
"cond",
"_", "_",
"branch",
"build",
"cmd",
"commit",
"cond",
"config",
"dependencies",
"dev",
"dir",
"enabled",
"event",
"ft",
"import",
"init",
"keys",
"lazy",
"module",
"name",
"opts",
"pin",
"priority",
"tag",
"url",
"version",
} }
return M return M

View File

@ -15,10 +15,13 @@
---@field cond? boolean ---@field cond? boolean
---@field super? LazyPlugin ---@field super? LazyPlugin
---@alias PluginOpts table|fun(self:LazyPlugin, opts:table):table?
---@class LazyPluginHooks ---@class LazyPluginHooks
---@field init? fun(LazyPlugin) Will always be run ---@field init? fun(self:LazyPlugin) Will always be run
---@field config? fun(LazyPlugin)|true|table Will be executed when loading the plugin ---@field config? fun(self:LazyPlugin, opts:table)|true Will be executed when loading the plugin
---@field build? string|fun(LazyPlugin)|(string|fun(LazyPlugin))[] ---@field build? string|fun(self:LazyPlugin)|(string|fun(self:LazyPlugin))[]
---@field opts? PluginOpts
---@class LazyPluginHandlers ---@class LazyPluginHandlers
---@field event? string[] ---@field event? string[]

View File

@ -1,5 +1,6 @@
local Config = require("lazy.core.config") local Config = require("lazy.core.config")
local Plugin = require("lazy.core.plugin") local Plugin = require("lazy.core.plugin")
local Loader = require("lazy.core.loader")
local assert = require("luassert") local assert = require("luassert")
@ -272,3 +273,37 @@ describe("plugin spec opt", function()
end end
end) end)
end) end)
describe("plugin opts", function()
it("correctly parses opts", function()
---@type {spec:LazySpec, opts:table}[]
local tests = {
{
spec = { { "foo/foo", opts = { a = 1, b = 1 } }, { "foo/foo", opts = { a = 2 } } },
opts = { a = 2, b = 1 },
},
{
spec = { { "foo/foo", config = { a = 1, b = 1 } }, { "foo/foo", opts = { a = 2 } } },
opts = { a = 2, b = 1 },
},
{
spec = { { "foo/foo", opts = { a = 1, b = 1 } }, { "foo/foo", config = { a = 2 } } },
opts = { a = 2, b = 1 },
},
{
spec = { { "foo/foo", config = { a = 1, b = 1 } }, { "foo/foo", config = { a = 2 } } },
opts = { a = 2, b = 1 },
},
{
spec = { { "foo/foo", config = { a = 1, b = 1 } }, { "foo/foo", config = { a = vim.NIL } } },
opts = { b = 1 },
},
}
for _, test in ipairs(tests) do
local spec = Plugin.Spec.new(test.spec)
assert(spec.plugins.foo)
assert.same(test.opts, Loader.opts(spec.plugins.foo))
end
end)
end)