mirrors/snacks.nvim
1
0
Fork 0
mirror of https://github.com/folke/snacks.nvim synced 2025-07-07 13:15:08 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: more docs...

Browse source
This commit is contained in:
Folke Lemaitre 2024-11-06 17:49:10 +01:00
parent 4a325ed3ab
commit 084fdf7d79
No known key found for this signature in database
GPG key ID: 41F8B1FBACAE2040
27 changed files with 166 additions and 92 deletions
Download patch file Download diff file Expand all files Collapse all files

2
doc/snacks-git.txt
View file

@ -36,7 +36,7 @@ SNACKS.GIT.BLAME_LINE() *snacks-git-module-snacks.git.blame_line()*
Show git log for the current line.
>lua
---@param opts? snacks.terminal.Config | {count?: number}
---@param opts? snacks.terminal.Opts | {count?: number}
Snacks.git.blame_line(opts)
<

2
doc/snacks-lazygit.txt
View file

@ -17,7 +17,7 @@ Table of Contents *snacks-lazygit-table-of-contents*
1. Config *snacks-lazygit-config*
>lua
---@class snacks.lazygit.Config: snacks.terminal.Config
---@class snacks.lazygit.Config: snacks.terminal.Opts
---@field args? string[]
---@field theme? snacks.lazygit.Theme
{

1
doc/snacks-notifier.txt
View file

@ -82,7 +82,6 @@ Notification options
---@field title? string
---@field icon? string
---@field timeout? number
---@field once? boolean
---@field ft? string
---@field keep? fun(notif: snacks.notifier.Notif): boolean
---@field style? snacks.notifier.style

2
doc/snacks-notify.txt
View file

@ -15,7 +15,7 @@ Table of Contents *snacks-notify-table-of-contents*
1. Types *snacks-notify-types*
>lua
---@alias snacks.notify.Opts {level?: number, title?: string, once?: boolean, ft?: string}
---@alias snacks.notify.Opts snacks.notifier.Notif.opts|{once?: boolean}
<

3
doc/snacks-quickfile.txt
View file

@ -4,6 +4,9 @@
Table of Contents *snacks-quickfile-table-of-contents*
1. Config |snacks-quickfile-config|
When doing `nvim somefile.txt`, it will render the file as quickly as possible,
before loading your plugins.
==============================================================================
1. Config *snacks-quickfile-config*

2
doc/snacks-rename.txt
View file

@ -58,6 +58,8 @@ LSP-integrated file renaming with support for plugins like neo-tree.nvim
SNACKS.RENAME.ON_RENAME_FILE()*snacks-rename-module-snacks.rename.on_rename_file()*
Lets LSP clients know that a file has been renamed
>lua
---@param from string
---@param to string

42
doc/snacks-terminal.txt
View file

@ -6,21 +6,27 @@ Table of Contents *snacks-terminal-table-of-contents*
1. Config |snacks-terminal-config|
2. Styles |snacks-terminal-styles|
- terminal |snacks-terminal-styles-terminal|
3. Module |snacks-terminal-module|
3. Types |snacks-terminal-types|
4. Module |snacks-terminal-module|
- Snacks.terminal() |snacks-terminal-module-snacks.terminal()|
- Snacks.terminal.open() |snacks-terminal-module-snacks.terminal.open()|
- Snacks.terminal.toggle() |snacks-terminal-module-snacks.terminal.toggle()|
Create and toggle terminal windows.
Based on the provided options, some defaults will be set:
- if no `cmd` is provided, the window will be opened in a bottom split
- if `cmd` is provided, the window will be opened in a floating window
- for splits, a `winbar` will be added with the terminal title
==============================================================================
1. Config *snacks-terminal-config*
>lua
---@class snacks.terminal.Config
---@field cwd? string
---@field env? table<string, string>
---@field win? snacks.win.Config
---@field interactive? boolean
---@field override? fun(cmd?: string|string[], opts?: snacks.terminal.Config) Use this to use a different terminal implementation
---@field override? fun(cmd?: string|string[], opts?: snacks.terminal.Opts) Use this to use a different terminal implementation
{
win = { style = "terminal" },
}
@ -71,12 +77,23 @@ TERMINAL *snacks-terminal-styles-terminal*
==============================================================================
3. Module *snacks-terminal-module*
3. Types *snacks-terminal-types*
>lua
---@class snacks.terminal.Opts: snacks.terminal.Config
---@field cwd? string
---@field env? table<string, string>
---@field interactive? boolean
<
==============================================================================
4. Module *snacks-terminal-module*
>lua
---@class snacks.terminal: snacks.win
---@field cmd? string | string[]
---@field opts snacks.terminal.Config
---@field opts snacks.terminal.Opts
Snacks.terminal = {}
<
@ -84,25 +101,30 @@ TERMINAL *snacks-terminal-styles-terminal*
SNACKS.TERMINAL() *snacks-terminal-module-snacks.terminal()*
>lua
---@type fun(cmd?: string|string[], opts?: snacks.terminal.Config): snacks.terminal
---@type fun(cmd?: string|string[], opts?: snacks.terminal.Opts): snacks.terminal
Snacks.terminal()
<
SNACKS.TERMINAL.OPEN() *snacks-terminal-module-snacks.terminal.open()*
Open a new terminal window.
>lua
---@param cmd? string | string[]
---@param opts? snacks.terminal.Config
---@param opts? snacks.terminal.Opts
Snacks.terminal.open(cmd, opts)
<
SNACKS.TERMINAL.TOGGLE() *snacks-terminal-module-snacks.terminal.toggle()*
Toggle a terminal window. The terminal id is based on the `cmd`, `cwd`, `env`
and `vim.v.count1` options.
>lua
---@param cmd? string | string[]
---@param opts? snacks.terminal.Config
---@param opts? snacks.terminal.Opts
Snacks.terminal.toggle(cmd, opts)
<

2
doc/snacks-toggle.txt
View file

@ -17,6 +17,8 @@ Table of Contents *snacks-toggle-table-of-contents*
- toggle:map() |snacks-toggle-module-toggle:map()|
- toggle:set() |snacks-toggle-module-toggle:set()|
- toggle:toggle() |snacks-toggle-module-toggle:toggle()|
Toggle keymaps integrated with which-key icons / colors
==============================================================================
1. Config *snacks-toggle-config*

48
doc/snacks-win.txt
View file

@ -3,16 +3,16 @@
==============================================================================
Table of Contents *snacks-win-table-of-contents*
1. Config |snacks-win-config|
2. Styles |snacks-win-styles|
1. Usage |snacks-win-usage|
2. Config |snacks-win-config|
3. Styles |snacks-win-styles|
- float |snacks-win-styles-float|
- minimal |snacks-win-styles-minimal|
- split |snacks-win-styles-split|
3. Types |snacks-win-types|
4. Module |snacks-win-module|
4. Types |snacks-win-types|
5. Module |snacks-win-module|
- Snacks.win() |snacks-win-module-snacks.win()|
- Snacks.win.new() |snacks-win-module-snacks.win.new()|
- Snacks.win.resolve() |snacks-win-module-snacks.win.resolve()|
- win:add_padding() |snacks-win-module-win:add_padding()|
- win:buf_valid() |snacks-win-module-win:buf_valid()|
- win:close() |snacks-win-module-win:close()|
@ -24,9 +24,30 @@ Table of Contents *snacks-win-table-of-contents*
- win:update() |snacks-win-module-win:update()|
- win:valid() |snacks-win-module-win:valid()|
- win:win_valid() |snacks-win-module-win:win_valid()|
Easily create and manage floating windows or splits
==============================================================================
1. Config *snacks-win-config*
1. Usage *snacks-win-usage*
>lua
Snacks.win({
file = vim.api.nvim_get_runtime_file("doc/news.txt", false)[1],
width = 0.6,
height = 0.6,
wo = {
spell = false,
wrap = false,
signcolumn = "yes",
statuscolumn = " ",
conceallevel = 3,
},
})
<
==============================================================================
2. Config *snacks-win-config*
>lua
---@class snacks.win.Config: vim.api.keyset.win_config
@ -60,7 +81,7 @@ Table of Contents *snacks-win-table-of-contents*
==============================================================================
2. Styles *snacks-win-styles*
3. Styles *snacks-win-styles*
FLOAT *snacks-win-styles-float*
@ -113,7 +134,7 @@ SPLIT *snacks-win-styles-split*
==============================================================================
3. Types *snacks-win-types*
4. Types *snacks-win-types*
>lua
---@class snacks.win.Keys: vim.api.keyset.keymap
@ -124,7 +145,7 @@ SPLIT *snacks-win-styles-split*
==============================================================================
4. Module *snacks-win-module*
5. Module *snacks-win-module*
>lua
---@class snacks.win
@ -155,15 +176,6 @@ SNACKS.WIN.NEW() *snacks-win-module-snacks.win.new()*
<
SNACKS.WIN.RESOLVE() *snacks-win-module-snacks.win.resolve()*
>lua
---@param ... snacks.win.Config|string
---@return snacks.win.Config
Snacks.win.resolve(...)
<
WIN:ADD_PADDING() *snacks-win-module-win:add_padding()*
>lua

2
doc/snacks-words.txt
View file

@ -7,6 +7,8 @@ Table of Contents *snacks-words-table-of-contents*
2. Module |snacks-words-module|
- Snacks.words.is_enabled() |snacks-words-module-snacks.words.is_enabled()|
- Snacks.words.jump() |snacks-words-module-snacks.words.jump()|
Auto-show LSP references and quickly navigate between them
==============================================================================
1. Config *snacks-words-config*

2
docs/git.md
View file

@ -24,7 +24,7 @@
Show git log for the current line.
```lua
---@param opts? snacks.terminal.Config | {count?: number}
---@param opts? snacks.terminal.Opts | {count?: number}
Snacks.git.blame_line(opts)
```

2
docs/lazygit.md
View file

@ -5,7 +5,7 @@
## ⚙️ Config
```lua
---@class snacks.lazygit.Config: snacks.terminal.Config
---@class snacks.lazygit.Config: snacks.terminal.Opts
---@field args? string[]
---@field theme? snacks.lazygit.Theme
{

1
docs/notifier.md
View file

@ -65,7 +65,6 @@ Notification options
---@field title? string
---@field icon? string
---@field timeout? number
---@field once? boolean
---@field ft? string
---@field keep? fun(notif: snacks.notifier.Notif): boolean
---@field style? snacks.notifier.style

2
docs/notify.md
View file

@ -5,7 +5,7 @@
## 📚 Types
```lua
---@alias snacks.notify.Opts {level?: number, title?: string, once?: boolean, ft?: string}
---@alias snacks.notify.Opts snacks.notifier.Notif.opts|{once?: boolean}
```
## 📦 Module

3
docs/quickfile.md
View file

@ -1,5 +1,8 @@
# 🍿 quickfile
When doing `nvim somefile.txt`, it will render the file as quickly as possible,
before loading your plugins.
<!-- docgen -->
## ⚙️ Config

2
docs/rename.md
View file

@ -41,6 +41,8 @@ vim.api.nvim_create_autocmd("User", {
### `Snacks.rename.on_rename_file()`
Lets LSP clients know that a file has been renamed
```lua
---@param from string
---@param to string

35
docs/terminal.md
View file

@ -1,16 +1,21 @@
# 🍿 terminal
Create and toggle terminal windows.
Based on the provided options, some defaults will be set:
- if no `cmd` is provided, the window will be opened in a bottom split
- if `cmd` is provided, the window will be opened in a floating window
- for splits, a `winbar` will be added with the terminal title
<!-- docgen -->
## ⚙️ Config
```lua
---@class snacks.terminal.Config
---@field cwd? string
---@field env? table<string, string>
---@field win? snacks.win.Config
---@field interactive? boolean
---@field override? fun(cmd?: string|string[], opts?: snacks.terminal.Config) Use this to use a different terminal implementation
---@field override? fun(cmd?: string|string[], opts?: snacks.terminal.Opts) Use this to use a different terminal implementation
{
win = { style = "terminal" },
}
@ -56,34 +61,48 @@
}
```
## 📚 Types
```lua
---@class snacks.terminal.Opts: snacks.terminal.Config
---@field cwd? string
---@field env? table<string, string>
---@field interactive? boolean
```
## 📦 Module
```lua
---@class snacks.terminal: snacks.win
---@field cmd? string | string[]
---@field opts snacks.terminal.Config
---@field opts snacks.terminal.Opts
Snacks.terminal = {}
```
### `Snacks.terminal()`
```lua
---@type fun(cmd?: string|string[], opts?: snacks.terminal.Config): snacks.terminal
---@type fun(cmd?: string|string[], opts?: snacks.terminal.Opts): snacks.terminal
Snacks.terminal()
```
### `Snacks.terminal.open()`
Open a new terminal window.
```lua
---@param cmd? string | string[]
---@param opts? snacks.terminal.Config
---@param opts? snacks.terminal.Opts
Snacks.terminal.open(cmd, opts)
```
### `Snacks.terminal.toggle()`
Toggle a terminal window.
The terminal id is based on the `cmd`, `cwd`, `env` and `vim.v.count1` options.
```lua
---@param cmd? string | string[]
---@param opts? snacks.terminal.Config
---@param opts? snacks.terminal.Opts
Snacks.terminal.toggle(cmd, opts)
```

2
docs/toggle.md
View file

@ -1,5 +1,7 @@
# 🍿 toggle
Toggle keymaps integrated with which-key icons / colors
<!-- docgen -->
## ⚙️ Config

27
docs/win.md
View file

@ -1,5 +1,24 @@
# 🍿 win
Easily create and manage floating windows or splits
## 🚀 Usage
```lua
Snacks.win({
file = vim.api.nvim_get_runtime_file("doc/news.txt", false)[1],
width = 0.6,
height = 0.6,
wo = {
spell = false,
wrap = false,
signcolumn = "yes",
statuscolumn = " ",
conceallevel = 3,
},
})
```
<!-- docgen -->
## ⚙️ Config
@ -119,14 +138,6 @@ Snacks.win()
Snacks.win.new(opts)
```
### `Snacks.win.resolve()`
```lua
---@param ... snacks.win.Config|string
---@return snacks.win.Config
Snacks.win.resolve(...)
```
### `win:add_padding()`
```lua

2
docs/words.md
View file

@ -1,5 +1,7 @@
# 🍿 words
Auto-show LSP references and quickly navigate between them
<!-- docgen -->
## ⚙️ Config

2
lua/snacks/git.lua
View file

@ -23,7 +23,7 @@ function M.get_root(path)
end
--- Show git log for the current line.
---@param opts? snacks.terminal.Config | {count?: number}
---@param opts? snacks.terminal.Opts | {count?: number}
function M.blame_line(opts)
opts = vim.tbl_deep_extend("force", {
count = 5,

2
lua/snacks/lazygit.lua
View file

@ -20,7 +20,7 @@ local M = setmetatable({}, {
---@field selectedLineBgColor snacks.lazygit.Color
---@field unstagedChangesColor snacks.lazygit.Color
---@class snacks.lazygit.Config: snacks.terminal.Config
---@class snacks.lazygit.Config: snacks.terminal.Opts
---@field args? string[]
---@field theme? snacks.lazygit.Theme
local defaults = {

3
lua/snacks/notifier.lua
View file

@ -23,7 +23,6 @@ local M = setmetatable({}, {
---@field title? string
---@field icon? string
---@field timeout? number
---@field once? boolean
---@field ft? string
---@field keep? fun(notif: snacks.notifier.Notif): boolean
---@field style? snacks.notifier.style
@ -325,6 +324,7 @@ function N:render(notif)
},
})
notif.win = win
---@diagnostic disable-next-line: invisible
local buf = win:open_buf()
vim.api.nvim_buf_clear_namespace(buf, N.ns, 0, -1)
local render = self:get_render(notif.style)
@ -430,6 +430,7 @@ function N:layout()
if not notif.win or notif.dirty or not notif.win:buf_valid() then
notif.dirty = false
self:render(notif)
---@diagnostic disable-next-line: assign-type-mismatch
notif.layout = notif.win:size()
end
notif.layout.top = find(notif.layout.height, notif.layout.top)

30
lua/snacks/notify.lua
View file

@ -7,7 +7,7 @@ local M = setmetatable({}, {
end,
})
---@alias snacks.notify.Opts {level?: number, title?: string, once?: boolean, ft?: string}
---@alias snacks.notify.Opts snacks.notifier.Notif.opts|{once?: boolean}
---@param msg string|string[]
---@param opts? snacks.notify.Opts
@ -17,44 +17,26 @@ function M.notify(msg, opts)
notify = vim.in_fast_event() and vim.schedule_wrap(notify) or notify
msg = type(msg) == "table" and table.concat(msg, "\n") or msg --[[@as string]]
msg = vim.trim(msg)
notify(msg, opts.level, {
title = opts.title or "Snacks",
ft = opts.ft,
-- used by nvim-notify
on_open = function(win)
vim.wo[win].conceallevel = 3
vim.wo[win].concealcursor = "n"
vim.wo[win].spell = false
local buf = vim.api.nvim_win_get_buf(win)
local ft = opts.ft or "markdown"
local lang = ft and vim.treesitter.language.get_lang(ft)
if lang and not vim.b[buf].ts_highlight and not pcall(vim.treesitter.start, buf, lang) then
lang = nil
end
if ft and not lang then
vim.bo[buf].filetype = ft
vim.bo[buf].syntax = ft
end
end,
})
opts.title = opts.title or "Snacks"
return notify(msg, opts.level, opts)
end
---@param msg string|string[]
---@param opts? snacks.notify.Opts
function M.warn(msg, opts)
M.notify(msg, vim.tbl_extend("keep", { level = vim.log.levels.WARN }, opts or {}))
return M.notify(msg, vim.tbl_extend("keep", { level = vim.log.levels.WARN }, opts or {}))
end
---@param msg string|string[]
---@param opts? snacks.notify.Opts
function M.info(msg, opts)
M.notify(msg, vim.tbl_extend("keep", { level = vim.log.levels.INFO }, opts or {}))
return M.notify(msg, vim.tbl_extend("keep", { level = vim.log.levels.INFO }, opts or {}))
end
---@param msg string|string[]
---@param opts? snacks.notify.Opts
function M.error(msg, opts)
M.notify(msg, vim.tbl_extend("keep", { level = vim.log.levels.ERROR }, opts or {}))
return M.notify(msg, vim.tbl_extend("keep", { level = vim.log.levels.ERROR }, opts or {}))
end
return M

1
lua/snacks/rename.lua
View file

@ -41,6 +41,7 @@ function M.rename_file()
end)
end
--- Lets LSP clients know that a file has been renamed
---@param from string
---@param to string
---@param rename? fun()

29
lua/snacks/terminal.lua
View file

@ -1,7 +1,7 @@
---@class snacks.terminal: snacks.win
---@field cmd? string | string[]
---@field opts snacks.terminal.Config
---@overload fun(cmd?: string|string[], opts?: snacks.terminal.Config): snacks.terminal
---@field opts snacks.terminal.Opts
---@overload fun(cmd?: string|string[], opts?: snacks.terminal.Opts): snacks.terminal
local M = setmetatable({}, {
__call = function(t, ...)
return t.toggle(...)
@ -9,15 +9,17 @@ local M = setmetatable({}, {
})
---@class snacks.terminal.Config
---@field cwd? string
---@field env? table<string, string>
---@field win? snacks.win.Config
---@field interactive? boolean
---@field override? fun(cmd?: string|string[], opts?: snacks.terminal.Config) Use this to use a different terminal implementation
---@field override? fun(cmd?: string|string[], opts?: snacks.terminal.Opts) Use this to use a different terminal implementation
local defaults = {
win = { style = "terminal" },
}
---@class snacks.terminal.Opts: snacks.terminal.Config
---@field cwd? string
---@field env? table<string, string>
---@field interactive? boolean
Snacks.config.style("terminal", {
bo = {
filetype = "snacks_terminal",
@ -55,12 +57,17 @@ Snacks.config.style("terminal", {
---@type table<string, snacks.win>
local terminals = {}
--- Open a new terminal window.
---@param cmd? string | string[]
---@param opts? snacks.terminal.Config
---@param opts? snacks.terminal.Opts
function M.open(cmd, opts)
local id = vim.v.count1
---@type snacks.terminal.Config
opts = Snacks.config.get("terminal", defaults, { win = { position = cmd and "float" or "bottom" } }, opts)
opts = Snacks.config.get(
"terminal",
defaults --[[@as snacks.terminal.Opts]],
{ win = { position = cmd and "float" or "bottom" } },
opts
)
opts.win = Snacks.win.resolve("terminal", opts.win)
opts.win.wo.winbar = opts.win.wo.winbar or (opts.win.position == "float" and "" or (id .. ": %{b:term_title}"))
@ -110,8 +117,10 @@ function M.open(cmd, opts)
return terminal
end
--- Toggle a terminal window.
--- The terminal id is based on the `cmd`, `cwd`, `env` and `vim.v.count1` options.
---@param cmd? string | string[]
---@param opts? snacks.terminal.Config
---@param opts? snacks.terminal.Opts
function M.toggle(cmd, opts)
opts = opts or {}

7
lua/snacks/win.lua
View file

@ -117,10 +117,11 @@ local win_opts = {
"zindex",
}
vim.api.nvim_set_hl(0, "SnackFloatBackdrop", { bg = "#000000", default = true })
vim.api.nvim_set_hl(0, "SnacksWinBackdrop", { bg = "#000000", default = true })
local id = 0
---@private
---@param ... snacks.win.Config|string
---@return snacks.win.Config
function M.resolve(...)
@ -393,12 +394,12 @@ function M:drop()
focusable = false,
zindex = self.opts.zindex - 1,
wo = {
winhighlight = "Normal:SnackFloatBackdrop",
winhighlight = "Normal:SnacksWinBackdrop",
winblend = self.opts.backdrop,
},
bo = {
buftype = "nofile",
filetype = "snack_float_backdrop",
filetype = "snacks_win_backdrop",
},
})
vim.api.nvim_create_autocmd("WinClosed", {