Skip to content

Commit

Permalink
feat: vimdoc
Browse files Browse the repository at this point in the history
  • Loading branch information
@mrcjkb
mrcjkb committed Aug 26, 2024
1 parent afcaf87 commit fd46d97
Show file tree
Hide file tree
Showing 7 changed files with 450 additions and 99 deletions.
8 changes: 5 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -119,9 +119,11 @@ require("lz.n").load(plugins)

> [!TIP]
>
> You can call `load()` as you would call `lazy.nvim`'s `setup()`.
> Or, you can also use it to register individual plugin specs for lazy
> loading.
> - You can call `load()` as you would call `lazy.nvim`'s `setup()`.
> Or, you can also use it to register individual plugin specs for lazy
> loading.
>
> - See also: [`:h lz.n`](./doc/lz.n.txt)
> [!IMPORTANT]
>
Expand Down
221 changes: 221 additions & 0 deletions doc/lz.n.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,221 @@
==============================================================================
*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|

==============================================================================
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<unknown, 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.

@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[])


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.


vim:tw=78:ts=8:noet:ft=help:norl:
Loading

0 comments on commit fd46d97

Please sign in to comment.