diff --git a/README.md b/README.md index 2543564..638569b 100755 --- a/README.md +++ b/README.md @@ -433,20 +433,25 @@ using the `trigger_load` function: The function provides two overloads, each suited for different use cases: 1. **Stateless version:** - - Usage: `trigger_load(plugin: lz.n.Plugin | lz.n.Plugin[])` - - Intended for: Use by a `lz.n.Handler` - - Description: This version should be used when working with `lz.n.Handler` + - *Usage:* `trigger_load(plugin: lz.n.Plugin)` + - *Intended for:* Use by a `lz.n.Handler` + - *Description:* This version should be used when working with `lz.n.Handler` instances to maintain referential transparency. Each handler has full authority over its internal state, ensuring it remains isolated and unaffected by external influences[^5], thereby preventing multiple sources of truth. + - *Note:* If loading multiple plugins simultaneously, + handlers should iterate over a deep copy (`:h vim.deepcopy`) of the plugins, + verifying they are still pending before each `trigger_load` call. + This practice allows for safe invocation of the stateful `trigger_load` + in `before` and `after` hooks. 2. **Stateful version:** - - Usage: `trigger_load(plugin_name: string | string[], opts?: lz.n.lookup.Opts)` - - Returns: A list of plugin names that were skipped + - *Usage:* `trigger_load(plugin_name: string | string[], opts?: lz.n.lookup.Opts)` + - *Returns:* A list of plugin names that were skipped (empty if all plugins were loaded). - - Intended for: Scenarios where handler state is unknown or inaccessible, + - *Intended for:* Scenarios where handler state is unknown or inaccessible, such as in `before` or `after` hooks. - - Description: This version allows you to load plugins by name. + - *Description:* This version allows you to load plugins by name. It searches through the handlers, querying their `lookup` functions to identify an appropriate plugin, and returns the first match. You can fine-tune the search process by providing a [`lz.n.lookup.Opts` table](#lookup). diff --git a/doc/lz.n.txt b/doc/lz.n.txt index 002cccd..55854dd 100644 --- a/doc/lz.n.txt +++ b/doc/lz.n.txt @@ -21,7 +21,7 @@ lz.n Lua API *lz.n.api* M.trigger_load() *M.trigger_load* The function provides two overloads, each suited for different use cases: - @overload fun(plugins: lz.n.Plugin | string[] | lz.n.Plugin[] | table) + @overload fun(plugin: lz.n.Plugin) **Stateless version:** - Intended for: Use by a `lz.n.Handler` - Description: This version should be used when working with `lz.n.Handler` @@ -29,8 +29,13 @@ M.trigger_load() *M.trigger_load* Each handler has full authority over its internal state, ensuring it remains isolated and unaffected by external influences, thereby preventing multiple sources of truth. + - Note: If loading multiple plugins simultaneously, + handlers should iterate over |vim.deepcopy| of the plugins, + verifying they are still pending before each `trigger_load` call. + This practice allows for safe invocation of the stateful `trigger_load` + in `before` and `after` hooks. - @overload fun(plugins: string | string[], opts: lz.n.lookup.Opts): string[] + @overload fun(plugins: string | string[], opts?: lz.n.lookup.Opts): string[] **Stateful version:** - Returns: A list of plugin names that were skipped (empty if all plugins were loaded). diff --git a/lua/lz/n/init.lua b/lua/lz/n/init.lua index 2092adf..c474788 100644 --- a/lua/lz/n/init.lua +++ b/lua/lz/n/init.lua @@ -29,7 +29,7 @@ end) --- The function provides two overloads, each suited for different use cases: --- ----@overload fun(plugins: lz.n.Plugin | string[] | lz.n.Plugin[] | table) +---@overload fun(plugin: lz.n.Plugin) --- **Stateless version:** --- - Intended for: Use by a `lz.n.Handler` --- - Description: This version should be used when working with `lz.n.Handler` @@ -37,8 +37,13 @@ end) --- Each handler has full authority over its internal state, ensuring it --- remains isolated and unaffected by external influences, --- thereby preventing multiple sources of truth. +--- - Note: If loading multiple plugins simultaneously, +--- handlers should iterate over |vim.deepcopy| of the plugins, +--- verifying they are still pending before each `trigger_load` call. +--- This practice allows for safe invocation of the stateful `trigger_load` +--- in `before` and `after` hooks. --- ----@overload fun(plugins: string | string[], opts: lz.n.lookup.Opts): string[] +---@overload fun(plugins: string | string[], opts?: lz.n.lookup.Opts): string[] --- **Stateful version:** --- - Returns: A list of plugin names that were skipped --- (empty if all plugins were loaded). diff --git a/lua/lz/n/loader.lua b/lua/lz/n/loader.lua index 6f72bac..4e1fd88 100644 --- a/lua/lz/n/loader.lua +++ b/lua/lz/n/loader.lua @@ -98,14 +98,16 @@ local function hook(hook_key, plugin) end end ----@overload fun(plugins: lz.n.Plugin | string[] | lz.n.Plugin[] | table) +---@overload fun(plugin: lz.n.Plugin) ---@overload fun(plugins: string | string[], lookup: fun(name: string): lz.n.Plugin?): string[] function M.load(plugins, lookup) - local iterator = vim.islist(plugins) and ipairs or pairs + local islist = vim.islist(plugins) + local iterator = islist and ipairs or pairs plugins = (type(plugins) == "string" or plugins.name) and { plugins } or plugins ---@cast plugins (string|lz.n.Plugin)[] | table ---@type string[] local skipped = {} + local plugin_spec_count = 0 -- used to detect deprecated use for _, plugin in iterator(plugins) do local loadable = true -- NOTE: do not make this loop into vim.iter @@ -117,14 +119,33 @@ function M.load(plugins, lookup) loadable = false table.insert(skipped, plugin) end - ---@cast plugin lz.n.Plugin + else + plugin_spec_count = plugin_spec_count + 1 end + ---@cast plugin lz.n.Plugin if loadable then hook("before", plugin) M._load(plugin) hook("after", plugin) end end + if plugin_spec_count > 1 then + if islist then + vim.deprecate( + "'trigger_load(plugins: lz.n.PluginSpec[])'", + "'trigger_load(plugin: lz.n.PluginSpec)'", + "3.0.0", + "lz.n" + ) + else + vim.deprecate( + "'trigger_load(plugins: table)'", + "'trigger_load(plugin: lz.n.PluginSpec)'", + "3.0.0", + "lz.n" + ) + end + end return skipped end