mirror of https://github.com/folke/lazy.nvim.git
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:
parent
6a31b97e37
commit
7260a2b28b
27
README.md
27
README.md
|
@ -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)
|
||||||
|
|
|
@ -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)
|
||||||
|
|
|
@ -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
|
||||||
|
|
||||||
|
|
|
@ -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"})
|
||||||
},
|
},
|
||||||
|
|
||||||
{
|
{
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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[]
|
||||||
|
|
|
@ -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)
|
||||||
|
|
Loading…
Reference in New Issue