zoriya/lz.n
1
0
Fork 0
mirror of https://github.com/zoriya/lz.n.git synced 2025-12-06 06:36:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: vimdoc (#65)

Browse Source
This commit is contained in:
Marc Jakobi
2024-08-27 00:44:38 +07:00
committed by GitHub
parent afcaf87c83
commit c8c06af2ac
7 changed files with 446 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@@ -119,9 +119,11 @@ require("lz.n").load(plugins)
> [!TIP]
>
> You can call `load()` as you would call `lazy.nvim`'s `setup()`.
> - 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]
>

221
doc/lz.n.txt Normal file
View File

@@ -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:

110
flake.lock generated Executable file → Normal file
View File

@@ -194,6 +194,24 @@
"type": "indirect"
}
},
"flake-parts_6": {
"inputs": {
"nixpkgs-lib": "nixpkgs-lib_4"
},
"locked": {
"lastModified": 1696343447,
"narHash": "sha256-B2xAZKLkkeRFG5XcHHSXXcP7To9Xzr59KXeZiRf4vdQ=",
"owner": "hercules-ci",
"repo": "flake-parts",
"rev": "c9afaba3dfa4085dbd2ccb38dfade5141e33d9d4",
"type": "github"
},
"original": {
"owner": "hercules-ci",
"repo": "flake-parts",
"type": "github"
}
},
"gen-luarc": {
"inputs": {
"flake-parts": "flake-parts_2",
@@ -276,11 +294,11 @@
]
},
"locked": {
"lastModified": 1724227338,
"narHash": "sha256-TuSaYdhOxeaaE9885mFO1lZHHax33GD5A9dczJrGUjw=",
"lastModified": 1724440431,
"narHash": "sha256-9etXEOUtzeMgqg1u0wp+EdwG7RpmrAZ2yX516bMj2aE=",
"owner": "cachix",
"repo": "git-hooks.nix",
"rev": "6cedaa7c1b4f82a266e5d30f212273e60d62cb0d",
"rev": "c8a54057aae480c56e28ef3e14e4960628ac495b",
"type": "github"
},
"original": {
@@ -425,11 +443,11 @@
"nixpkgs": "nixpkgs_4"
},
"locked": {
"lastModified": 1724477135,
"narHash": "sha256-uoHYEefxVLWtAvWw41t11R8l7oQG7MgwvnA0FYVsY2s=",
"lastModified": 1724649927,
"narHash": "sha256-VVl1jvW3DC2IAgBKQy8PhhlxUZie1hivfnTzqQahJ5I=",
"owner": "nvim-neorocks",
"repo": "neorocks",
"rev": "960271da8c15fced6314deecfd7ef6f77787326c",
"rev": "bc52a030e810726a813bb991cca7897b7e629a14",
"type": "github"
},
"original": {
@@ -448,11 +466,11 @@
"nixpkgs": "nixpkgs_3"
},
"locked": {
"lastModified": 1724391918,
"narHash": "sha256-cE2PmF0Ayw/flzTL3aEtiak5QkBTp0z265CDWnUKoM8=",
"lastModified": 1724575478,
"narHash": "sha256-8jWDD3SI5Xmi3x7PiAmGQSNjIkMoT9UFwhIAF8IzA8s=",
"owner": "nix-community",
"repo": "neovim-nightly-overlay",
"rev": "4fb7a5de4d5024a49bb60b7ff5ddb54252fe4622",
"rev": "d7860e03b1849714482eceff96433bf2d9fbeb68",
"type": "github"
},
"original": {
@@ -464,11 +482,11 @@
"neovim-src": {
"flake": false,
"locked": {
"lastModified": 1724363148,
"narHash": "sha256-mvxaYMDkhOM0f1LEmu43u2qMtHkY40Me4bcP2XqQ9MM=",
"lastModified": 1724537263,
"narHash": "sha256-Gvx0buJ7kFv1LzgKzhy9LjVfDI149+1KkeaH7kJn/Zs=",
"owner": "neovim",
"repo": "neovim",
"rev": "3b32869ced32821fb58f0a7c08094105be7bdaf0",
"rev": "cf44121f7fb6f55a22e644a1e5e1f1dc6b90c27a",
"type": "github"
},
"original": {
@@ -529,6 +547,24 @@
"url": "https://github.com/NixOS/nixpkgs/archive/a5d394176e64ab29c852d03346c1fc9b0b7d33eb.tar.gz"
}
},
"nixpkgs-lib_4": {
"locked": {
"dir": "lib",
"lastModified": 1696019113,
"narHash": "sha256-X3+DKYWJm93DRSdC5M6K5hLqzSya9BjibtBsuARoPco=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "f5892ddac112a1e9b3612c39af1b72987ee5783a",
"type": "github"
},
"original": {
"dir": "lib",
"owner": "NixOS",
"ref": "nixos-unstable",
"repo": "nixpkgs",
"type": "github"
}
},
"nixpkgs-stable": {
"locked": {
"lastModified": 1720386169,
@@ -595,11 +631,11 @@
},
"nixpkgs_3": {
"locked": {
"lastModified": 1724300212,
"narHash": "sha256-x3jl6OWTs+L9C7EtscuWZmGZWI0iSBDafvg3X7JMa1A=",
"lastModified": 1724395761,
"narHash": "sha256-zRkDV/nbrnp3Y8oCADf5ETl1sDrdmAW6/bBVJ8EbIdQ=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "4de4818c1ffa76d57787af936e8a23648bda6be4",
"rev": "ae815cee91b417be55d43781eb4b73ae1ecc396c",
"type": "github"
},
"original": {
@@ -611,11 +647,11 @@
},
"nixpkgs_4": {
"locked": {
"lastModified": 1724363052,
"narHash": "sha256-Nf/iQWamRVAwAPFccQMfm5Qcf+rLLnU1rWG3f9orDVE=",
"lastModified": 1724395761,
"narHash": "sha256-zRkDV/nbrnp3Y8oCADf5ETl1sDrdmAW6/bBVJ8EbIdQ=",
"owner": "nixos",
"repo": "nixpkgs",
"rev": "5de1564aed415bf9d0f281461babc2d101dd49ff",
"rev": "ae815cee91b417be55d43781eb4b73ae1ecc396c",
"type": "github"
},
"original": {
@@ -657,6 +693,22 @@
"type": "github"
}
},
"nixpkgs_7": {
"locked": {
"lastModified": 1697379843,
"narHash": "sha256-RcnGuJgC2K/UpTy+d32piEoBXq2M+nVFzM3ah/ZdJzg=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "12bdeb01ff9e2d3917e6a44037ed7df6e6c3df9d",
"type": "github"
},
"original": {
"owner": "NixOS",
"ref": "nixpkgs-unstable",
"repo": "nixpkgs",
"type": "github"
}
},
"pre-commit-hooks": {
"inputs": {
"flake-compat": "flake-compat_6",
@@ -684,7 +736,27 @@
"gen-luarc": "gen-luarc",
"neorocks": "neorocks",
"nixpkgs": "nixpkgs_5",
"pre-commit-hooks": "pre-commit-hooks"
"pre-commit-hooks": "pre-commit-hooks",
"vimcats": "vimcats"
}
},
"vimcats": {
"inputs": {
"flake-parts": "flake-parts_6",
"nixpkgs": "nixpkgs_7"
},
"locked": {
"lastModified": 1724691612,
"narHash": "sha256-YZPLZgC0v5zw/+X3r0G1MZ+46c0K8J3ClFQYH5BqbUE=",
"owner": "mrcjkb",
"repo": "vimcats",
"rev": "a51bfb9587f95b8fd6a588bdfe97b7f8f4b1e624",
"type": "github"
},
"original": {
"owner": "mrcjkb",
"repo": "vimcats",
"type": "github"
}
}
},

12
flake.nix
View File

@@ -13,6 +13,8 @@
neorocks.url = "github:nvim-neorocks/neorocks";
gen-luarc.url = "github:mrcjkb/nix-gen-luarc-json";
vimcats.url = "github:mrcjkb/vimcats";
};
outputs = inputs @ {
@@ -45,7 +47,7 @@
...
}: let
ci-overlay = import ./nix/ci-overlay.nix {
inherit self;
inherit self inputs;
plugin-name = name;
};
@@ -86,6 +88,13 @@
"CHANGELOG.md"
];
};
docgen = {
enable = true;
name = "docgen";
entry = "${pkgs.docgen}/bin/docgen";
files = "\\.(lua)$";
pass_filenames = false;
};
};
};
@@ -100,6 +109,7 @@
++ (with pkgs; [
lua-language-server
busted-nlua
docgen
]);
};
in {

54
lua/lz/n/init.lua
View File

@@ -1,4 +1,17 @@
---@mod lz.n
---
---@brief [[
---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.
---@brief ]]
---@toc lz.n.contents
---@mod lz.n.api lz.n Lua API
local M = {}
@@ -14,20 +27,27 @@ local deferred_ui_enter = vim.schedule_wrap(function()
vim.api.nvim_exec_autocmds("User", { pattern = "DeferredUIEnter", modeline = false })
end)
---@type fun(handler: lz.n.Handler): boolean
M.register_handler = function(...)
return require("lz.n.handler").register_handler(...)
end
--- Accepts plugin names (`string | string[]`, when called in another
--- plugin's hook), or |lz.n.Plugin| items (when called by a |lz.n.Handler|).
--- If called with a plugin name, it will use the registered
--- handlers' `lookup` functions to search for a plugin to load
--- (loading the first one it finds).
--- Once a plugin has been loaded, it will be removed from all handlers (via `del`).
--- As a result, calling `trigger_load` with a plugin name is stateful and idempotent.
--- 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.trigger_load = function(plugins, opts)
return require("lz.n.loader").load(plugins, function(name)
return M.lookup(name, opts)
@@ -35,7 +55,10 @@ M.trigger_load = function(plugins, opts)
end
---@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.
function M.load(spec)
if type(spec) == "string" then
spec = { import = spec }
@@ -80,4 +103,11 @@ end
--- determines the order in which handlers' `lookup` functions are called.
---@field filter string | string[]
---Register a custom handler.
---@param handler lz.n.Handler
---@return boolean success
M.register_handler = function(handler)
return require("lz.n.handler").register_handler(handler)
end
return M

10
lua/lz/n/meta.lua
View File

@@ -1,5 +1,4 @@
---@meta
error("Cannot import a meta module")
---@mod lz.n.types lz.n type definitions
---@class lz.n.PluginBase
---
@@ -66,6 +65,7 @@ error("Cannot import a meta module")
---@field name string
---@class lz.n.Plugin: lz.n.PluginBase,lz.n.PluginHandlers,lz.n.PluginHooks
---
--- The plugin name (not its main module), e.g. "sweetie.nvim"
---@field name string
---
@@ -73,6 +73,7 @@ error("Cannot import a meta module")
---@field lazy? boolean
---@class lz.n.PluginSpec: lz.n.PluginBase,lz.n.PluginSpecHandlers,lz.n.PluginHooks
---
--- The plugin name (not its main module), e.g. "sweetie.nvim"
---@field [1] string
@@ -104,3 +105,8 @@ error("Cannot import a meta module")
---@type lz.n.Config
vim.g.lz_n = vim.g.lz_n
error("Cannot import a meta module")
local M = {}
return M

16
nix/ci-overlay.nix
View File

@@ -1,10 +1,9 @@
# Add flake.nix test inputs as arguments here
{
self,
inputs,
plugin-name,
}: final: prev:
with final.lib;
with final.stdenv; let
}: final: prev: let
nvim-nightly = final.neovim-nightly;
mkNeorocksTest = {
@@ -40,10 +39,21 @@ with final.stdenv; let
cp -r tests $out
'';
};
docgen = final.writeShellApplication {
name = "docgen";
runtimeInputs = [
inputs.vimcats.packages.${final.system}.default
];
text = ''
mkdir -p doc
vimcats lua/lz/n/{init,meta}.lua > doc/lz.n.txt
'';
};
in {
nvim-stable-tests = mkNeorocksTest {name = "neovim-stable-tests";};
nvim-nightly-tests = mkNeorocksTest {
name = "neovim-nightly-tests";
nvim = nvim-nightly;
};
inherit docgen;
}