============================================================================== *lz.n* A dead simple lazy-loading Lua library for Neovim plugins. It is intended to be used - by users of plugin managers that don't provide a convenient API for lazy-loading. - by plugin managers, to provide a convenient API for lazy-loading. ============================================================================== Table of Contents *lz.n.contents* ········································································ |lz.n| lz.n Lua API ························································ |lz.n.api| lz.n type definitions ············································· |lz.n.types| Safe state management for handlers ························ |lz.n.handler.state| ============================================================================== 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(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` instances to maintain referential transparency. 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[] **Stateful version:** - 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, such as in `before` or `after` hooks. - 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). M.load() *M.load* @overload fun(spec: lz.n.Spec) Register a list with your plugin specs or a single plugin spec to be lazy-loaded. @overload fun(import: string) Register a Lua module name that contains your plugin spec(s) to be lazy-loaded. M.lookup({name}, {opts?}) *M.lookup* Lookup a plugin that is pending to be loaded by name. Parameters: ~ {name} (string) {opts?} (lz.n.lookup.Opts) @return lz.n.Plugin? lz.n.lookup.Opts *lz.n.lookup.Opts* Fields: ~ {filter} (string|string[]) The handlers to include in the search (filtered by `spec_field`) In case of multiple filters, the order of the filter list determines the order in which handlers' `lookup` functions are called. M.register_handler({handler}) *M.register_handler* Register a custom handler. Parameters: ~ {handler} (lz.n.Handler) Returns: ~ (boolean) success ============================================================================== lz.n type definitions *lz.n.types* lz.n.PluginBase *lz.n.PluginBase* Fields: ~ {enabled?} (boolean|fun():boolean) Whether to enable this plugin. Useful to disable plugins under certain conditions. {priority?} (number) Only useful for lazy=false plugins to force loading certain plugins first. Default priority is 50 {load?} (fun(name:string)) Set this to override the `load` function for an individual plugin. Defaults to `vim.g.lz_n.load()`, see |lz.n.Config|. lz.n.Event *lz.n.Event* Type: ~ {id:string,event:string[]|string,pattern?:string[]|string} lz.n.EventSpec *lz.n.EventSpec* Type: ~ string|{event?:string|string[],pattern?:string|string[]}|string[] lz.n.PluginHooks *lz.n.PluginHooks* Fields: ~ {beforeAll?} (fun(self:lz.n.Plugin)) Will be run before loading any plugins {before?} (fun(self:lz.n.Plugin)) Will be run before loading this plugin {after?} (fun(self:lz.n.Plugin)) Will be executed after loading this plugin lz.n.PluginHandlers *lz.n.PluginHandlers* Fields: ~ {event?} (lz.n.Event[]) {keys?} (lz.n.Keys[]) {cmd?} (string[]) {colorscheme?} (string[]) {lazy?} (boolean) lz.n.PluginSpecHandlers *lz.n.PluginSpecHandlers* Fields: ~ {event?} (string|lz.n.EventSpec[]) Load a plugin on one or more |autocmd-events|. {cmd?} (string[]|string) Load a plugin on one or more |user-commands|. {ft?} (string[]|string) Load a plugin on one or more |FileType| events. {keys?} (string|string[]|lz.n.KeysSpec[]) Load a plugin on one or more |key-mapping|s. {colorscheme?} (string[]|string) Load a plugin on one or more |colorscheme| events. lz.n.KeysBase : vim.keymap.set.Opts *lz.n.KeysBase* Fields: ~ {desc?} (string) {noremap?} (boolean) {remap?} (boolean) {expr?} (boolean) {nowait?} (boolean) {ft?} (string|string[]) lz.n.KeysSpec : lz.n.KeysBase *lz.n.KeysSpec* Fields: ~ {1} (string) lhs {2?} (string|fun()|false) rhs {mode?} (string|string[]) lz.n.Keys : lz.n.KeysBase *lz.n.Keys* Fields: ~ {lhs} (string) lhs {rhs?} (string|fun()) rhs {mode?} (string) {id} (string) {name} (string) *lz.n.Plugin* lz.n.Plugin : lz.n.PluginBase, lz.n.PluginHandlers, lz.n.PluginHooks Fields: ~ {name} (string) The plugin name (not its main module), e.g. "sweetie.nvim" {lazy?} (boolean) Whether to lazy-load this plugin. Defaults to `false`. *lz.n.PluginSpec* lz.n.PluginSpec : lz.n.PluginBase, lz.n.PluginSpecHandlers, lz.n.PluginHooks Fields: ~ {1} (string) The plugin name (not its main module), e.g. "sweetie.nvim" lz.n.SpecImport *lz.n.SpecImport* Fields: ~ {import} (string) spec module to import {enabled?} (boolean|fun():boolean) lz.n.Spec *lz.n.Spec* Type: ~ lz.n.PluginSpec|lz.n.SpecImport|lz.n.Spec[] lz.n.Config *lz.n.Config* Fields: ~ {load?} (fun(name:string)) Callback to load a plugin. Takes the plugin name (not the module name). Defaults to |packadd| if not set. lz.n.Handler *lz.n.Handler* Fields: ~ {spec_field} (string) The |lz.n.PluginSpec| field used to configure this handler. {add} (fun(plugin:lz.n.Plugin)) Add a plugin to this handler. {del} (fun(name:string)) Remove a plugin from this handler by name. {lookup} (fun(name:string):lz.n.Plugin) Lookup a plugin by name. ============================================================================== Safe state management for handlers *lz.n.handler.state* This module is to be used by |lz.n.Handler| implementations. It provides an API for safely managing handler state, ensuring that `trigger_load` can be called in plugin hooks. state.new() *state.new* Returns: ~ (lz.n.handler.State) lz.n.handler.State *lz.n.handler.State* Fields: ~ {insert} (fun(key:string,plugin:lz.n.Plugin)|fun(plugin:lz.n.Plugin)) Insert a plugin (optionally, by key). {del} (fun(plugin_name:string,callback?:fun(key:string))) Remove a plugin by its name. {has_pending_plugins} (fun(key?:string):boolean) Check if there are pending plugins (optionally, by key) {lookup_plugin} (fun(plugin_name:string):lz.n.Plugin|nil) Lookup a plugin by its name. {each_pending} (fun(key:string,callback:fun(plugin:lz.n.Plugin)):string[]|fun(callback:fun(plugin:lz.n.Plugin)):string[]) Safely apply a callback to all pending plugins (optionally, by key). vim:tw=78:ts=8:noet:ft=help:norl: