Skip to content

Commit

Permalink
feat(spec): event, keys, ft and cmd can now also be a function that r…
Browse files Browse the repository at this point in the history 
…eturns the values to be used
  • Loading branch information
@folke
folke committed Jan 12, 2023
1 parent bcd87a0 commit 2128ca9
Show file tree
Hide file tree
Showing 6 changed files with 76 additions and 75 deletions.
52 changes: 26 additions & 26 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,32 +79,32 @@ require("lazy").setup({

## 🔌 Plugin Spec

| Property | Type | Description |
| ---------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[1]` | `string?` | Short plugin url. Will be expanded using `config.git.url_format` |
| **dir** | `string?` | A directory pointing to a local plugin |
| **url** | `string?` | A custom git url where the plugin is hosted |
| **name** | `string?` | A custom name for the plugin used for the local plugin directory and as the display name |
| **dev** | `boolean?` | When `true`, a local plugin directory will be used instead. See `config.dev` |
| **lazy** | `boolean?` | When `true`, the plugin will only be loaded when needed. Lazy-loaded plugins are automatically loaded when their Lua modules are `required`, or when one of the lazy-loading handlers triggers |
| **enabled** | `boolean?` or `fun():boolean` | When `false`, or if the `function` returns false, then this plugin will not be included in the spec |
| **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. |
| **init** | `fun(LazyPlugin)` | `init` functions are always executed during startup |
| **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()` |
| **config** | `fun(LazyPlugin, opts:table)` or `true` | `config` is executed when the plugin loads. The default implementation will automatically run `require("plugin").setup(opts)`. See also `opts`. |
| **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 |
| **tag** | `string?` | Tag of the repository |
| **commit** | `string?` | Commit of the repository |
| **version** | `string?` | Version to use from the repository. Full [Semver](https://devhints.io/semver) ranges are supported |
| **pin** | `boolean?` | When `true`, this plugin will not be included in updates |
| **event** | `string?` or `string[]` | Lazy-load on event. Events can be specified as `BufEnter` or with a pattern like `BufEnter *.lua` |
| **cmd** | `string?` or `string[]` | Lazy-load on command |
| **ft** | `string?` or `string[]` | Lazy-load on filetype |
| **keys** | `string?` or `string[]` or `LazyKeys[]` | Lazy-load on key mapping |
| **module** | `false?` | Do not automatically load this Lua module when it's required somewhere |
| **priority** | `number?` | Only useful for **start** plugins (`lazy=false`) to force loading certain plugins first. Default priority is `50`. It's recommended to set this to a high number for colorschemes. |
| Property | Type | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[1]` | `string?` | Short plugin url. Will be expanded using `config.git.url_format` |
| **dir** | `string?` | A directory pointing to a local plugin |
| **url** | `string?` | A custom git url where the plugin is hosted |
| **name** | `string?` | A custom name for the plugin used for the local plugin directory and as the display name |
| **dev** | `boolean?` | When `true`, a local plugin directory will be used instead. See `config.dev` |
| **lazy** | `boolean?` | When `true`, the plugin will only be loaded when needed. Lazy-loaded plugins are automatically loaded when their Lua modules are `required`, or when one of the lazy-loading handlers triggers |
| **enabled** | `boolean?` or `fun():boolean` | When `false`, or if the `function` returns false, then this plugin will not be included in the spec |
| **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. |
| **init** | `fun(LazyPlugin)` | `init` functions are always executed during startup |
| **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()` |
| **config** | `fun(LazyPlugin, opts:table)` or `true` | `config` is executed when the plugin loads. The default implementation will automatically run `require("plugin").setup(opts)`. See also `opts`. |
| **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 |
| **tag** | `string?` | Tag of the repository |
| **commit** | `string?` | Commit of the repository |
| **version** | `string?` | Version to use from the repository. Full [Semver](https://devhints.io/semver) ranges are supported |
| **pin** | `boolean?` | When `true`, this plugin will not be included in updates |
| **event** | `string?` or `string[]` or `fun(self:LazyPlugin, event:string[]):string[]` | Lazy-load on event. Events can be specified as `BufEnter` or with a pattern like `BufEnter *.lua` |
| **cmd** | `string?` or `string[]` or `fun(self:LazyPlugin, cmd:string[]):string[]` | Lazy-load on command |
| **ft** | `string?` or `string[]` or `fun(self:LazyPlugin, ft:string[]):string[]` | Lazy-load on filetype |
| **keys** | `string?` or `string[]` or `LazyKeys[]` or `fun(self:LazyPlugin, keys:string[]):(string \| LazyKeys)[]` | Lazy-load on key mapping |
| **module** | `false?` | Do not automatically load this Lua module when it's required somewhere |
| **priority** | `number?` | Only useful for **start** plugins (`lazy=false`) to force loading certain plugins first. Default priority is `50`. It's recommended to set this to a high number for colorschemes. |

### Lazy Loading

Expand Down
2 changes: 1 addition & 1 deletion lua/lazy/core/cache.lua
View file
Original file line number Diff line number Diff line change
Expand Up @@ -346,7 +346,7 @@ function M.find(modname, opts)
local updated = false
---@type LazyCoreConfig
local Config = package.loaded["lazy.core.config"]
if Config then
if Config and Config.spec then
for _, plugin in pairs(Config.spec.plugins) do
if not (M.indexed[plugin.dir] or plugin._.loaded or plugin.module == false) then
updated = M._index(plugin.dir) or updated
Expand Down
25 changes: 3 additions & 22 deletions lua/lazy/core/loader.lua
View file
Original file line number Diff line number Diff line change
Expand Up @@ -231,33 +231,14 @@ function M._load(plugin, reason, opts)
end)
end

-- Merges super opts or runs the opts function to override opts or return new ones
---@param plugin LazyPlugin
function M.opts(plugin)
---@type table
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
---@param plugin LazyPlugin
function M.config(plugin)
local opts = Plugin.values(plugin, "opts", false)
local fn
if type(plugin.config) == "function" then
fn = function()
plugin.config(plugin, M.opts(plugin))
plugin.config(plugin, opts)
end
else
local normname = Util.normname(plugin.name)
Expand All @@ -274,7 +255,7 @@ function M.config(plugin)
end
if #mods == 1 then
fn = function()
require(mods[1]).setup(M.opts(plugin))
require(mods[1]).setup(opts)
end
else
return Util.error(
Expand Down

0 comments on commit 2128ca9

Please sign in to comment.