https://github.com/beixiyo/vv-utils.nvim
Shared Lua utilities for vv-* Neovim plugins (path / fs / git / diagnostics / hl / help_panel / ui_window / bufdelete / yaml). vv-* 系列 Neovim 插件的共享工具库
https://github.com/beixiyo/vv-utils.nvim
lua neovim neovim-lua neovim-plugin neovim-utils nvim nvim-plugin vv-utils
Last synced: 19 days ago
JSON representation
Shared Lua utilities for vv-* Neovim plugins (path / fs / git / diagnostics / hl / help_panel / ui_window / bufdelete / yaml). vv-* 系列 Neovim 插件的共享工具库
- Host: GitHub
- URL: https://github.com/beixiyo/vv-utils.nvim
- Owner: beixiyo
- License: mit
- Created: 2026-04-25T06:37:29.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-30T17:26:53.000Z (30 days ago)
- Last Synced: 2026-05-30T19:12:39.587Z (30 days ago)
- Topics: lua, neovim, neovim-lua, neovim-plugin, neovim-utils, nvim, nvim-plugin, vv-utils
- Language: Lua
- Size: 69.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
vv-utils.nvim
vv-* 系列插件的共享工具库 — 纯 Lua，零外部依赖
---
## 安装
通常不需要手动安装 — 其他 `vv-*` 插件通过 `dependencies` 自动拉取。如果直接消费：
```lua
{
'beixiyo/vv-utils.nvim',
lazy = false,
priority = 1000, -- 其他插件启动期 require 时需要先就位
}
```
## 模块
| 模块 | 说明 |
|------|------|
| `vv-utils.path` | `norm(p)` 规范化路径、`get_root(buf?)` 向上找项目根、`get_cwd()` |
| `vv-utils.yaml` | 轻量 YAML 解析（够用于 `pnpm-workspace.yaml` 等简单配置） |
| `vv-utils.fs` | fs 原语：`mkdir_p` / `create_file` / `delete`（递归）/ `rename`（EXDEV 降级）/ `copy`（递归）/ `read_all` / `write_all`（原子写入） |
| `vv-utils.git` | 异步 git 索引：`index(root, cb)` → `{ status_map, is_ignored, symbol_for }`；`register_hl()` 注册 VSCode Dark+ 调色板 |
| `vv-utils.diagnostics` | `collect_by_path()` 聚合诊断 → `{[path]={[severity]=count}}`；`symbol_for(counts)` 选最高 severity；`format_range(buf, l1, l2?)` 行范围诊断 → `"Label: message"[]` |
| `vv-utils.timer` | `debounce(fn, wait)` / `throttle(fn, limit)`，时间参数支持传入函数实现动态延时 |
| `vv-utils.hl` | `register(augroup, specs)` 批量注册 highlight（自动 `default=true` + `ColorScheme` 重挂）；`get_fg(name)` |
| `vv-utils.ui_window` | UI buffer 窗口 chrome 管理（关行号 / signcolumn 等），支持 restore |
| `vv-utils.help_panel` | 通用 keymap 帮助浮窗：反读 buffer mappings 按 desc 前缀分组 |
| `vv-utils.bufdelete` | 删 buffer 不破坏窗口布局：`delete` / `all` / `other` / `smart` |
| `vv-utils.loading` | buffer 行内 loading 动画：`start(opts)` → `stop()`；内置 `presets.braille`（默认）/ `dots` / `bounce`；`hl_mode='combine'` 透明背景 |
| `vv-utils.editor` | `copy(text)` / `visual_range()` / `copy_path(opts?)` |
| `vv-utils.sys` | `open_default(path)` 跨平台打开（`vim.ui.open`）；niri 下额外把被打开的应用窗口聚焦回来 |
| `vv-utils.exec` | `resolve(path, opts?)` 按文件类型解析执行命令：shebang（`/usr/bin/env` 透传）> 扩展名运行器优先级，取首个 `executable()` 者，返回 `{cmd, runner}` 纯数据 |
| `vv-utils.drop` | 终端拖拽路径检测 + handler 分发（需 `setup()` 启用）。两条路统一走 `dispatch(paths, pos)`：① 覆写 `vim.paste` 从 bracketed paste 检测路径（`pos=nil`，无坐标）；② **kitty DnD 协议（OSC 72，kitty ≥ 0.47 且脱 tmux）** 带落点坐标 + 拖拽事件（`pos={x,y,op}`）。`register(handler)` 签名 `fun(paths, pos)`；`on_drag(cb)` 订阅移动/离开（实时高亮用）；内置默认 handler（Normal 下 `:edit`）；`setup({ kitty_dnd=false })` 关协议 |
| `vv-utils.bigfile` | 大文件保护（需 `setup()` 启用），禁用 matchparen / folding / completion 等 |
| `vv-utils.format` | 中英文排版：`add_spaces_around_english` / `clean_line_trailing`（需 `setup()` 启用） |
| `vv-utils.animate` | 通用补间动画引擎：`add(from, to, cb, opts?)` / `del(id)`，uv_timer 驱动 + easing（linear/outQuad/outCubic/inQuad/inOutQuad） |
## 引用方式
```lua
-- 直接引用子模块
local path = require('vv-utils.path')
path.get_root()
-- 或走 facade
local utils = require('vv-utils')
utils.path.get_root()
utils.yaml.parse(...)
```
## 配置
大多数模块是纯函数库，无需配置。带副作用的模块需显式启用：
```lua
require('vv-utils').setup({
drop = true, -- 终端拖拽：粘贴检测 + kitty DnD 落点协议（覆写 vim.paste）
bigfile = true, -- 启用大文件保护
format = true, -- 启用中英文排版命令（:VVAddSpaces / :VVCleanTrailing）
-- 传 table 可透传子模块配置
-- bigfile = { size_threshold = 1024 * 500 },
})
```