tomas.mirchev/nvim-tree.lua
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(#2948): tidy decorator args and complete documentation

Browse Source
This commit is contained in:
Alexander Courtis 2024-12-01 15:17:25 +11:00
parent cb351ae1de
commit 4bf4a85b9f
15 changed files with 172 additions and 267 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
doc/nvim-tree-lua.txt
View File

@ -52,14 +52,15 @@ CONTENTS *nvim-tree*
8.2 Highlight: Overhaul |nvim-tree-highlight-overhaul|
9. Events |nvim-tree-events|
10. Prompts |nvim-tree-prompts|
11. OS Specific Restrictions |nvim-tree-os-specific|
12. Netrw |nvim-tree-netrw|
13. Legacy |nvim-tree-legacy|
13.1 Legacy: Opts |nvim-tree-legacy-opts|
13.2 Legacy: Highlight |nvim-tree-legacy-highlight|
14. Index |nvim-tree-index|
14.1 Index: Opts |nvim-tree-index-opts|
14.2 Index: API |nvim-tree-index-api|
11. Decorators |nvim-tree-decorators|
12. OS Specific Restrictions |nvim-tree-os-specific|
13. Netrw |nvim-tree-netrw|
14. Legacy |nvim-tree-legacy|
14.1 Legacy: Opts |nvim-tree-legacy-opts|
14.2 Legacy: Highlight |nvim-tree-legacy-highlight|
15. Index |nvim-tree-index|
15.1 Index: Opts |nvim-tree-index-opts|
15.2 Index: API |nvim-tree-index-api|
==============================================================================
1. INTRODUCTION *nvim-tree-introduction*
@ -843,9 +844,6 @@ Use nvim-tree in a floating window.
==============================================================================
5.3 OPTS: RENDERER *nvim-tree-opts-renderer*
Highlight precedence, additive, change via |nvim-tree.renderer.decorators|
git < opened < modified < bookmarked < diagnostics < copied < cut
*nvim-tree.renderer.add_trailing*
Appends a trailing slash to folder names.
Type: `boolean`, Default: `false`
@ -1013,9 +1011,6 @@ Configuration options for tree indent markers.
*nvim-tree.renderer.icons*
Configuration options for icons.
Icon order and sign column precedence, change via |nvim-tree.renderer.decorators|
git < hidden < modified < bookmarked < diagnostics
`renderer.icons.*_placement` options may be:
- `"before"` : before file/folder, after the file/folders icons
- `"after"` : after file/folder
@ -2772,7 +2767,90 @@ configurations for different types of prompts.
send all bookmarked to trash during |nvim-tree-api.marks.bulk.trash()|
==============================================================================
11. OS SPECIFIC RESTRICTIONS *nvim-tree-os-specific*
11. DECORATORS *nvim-tree-decorators*
Highlighting and icons for nodes are is provided by Decorators. You may provide
your own in addition to the builtin decorators.
Decorators may:
- Add icons
- Set highlight group for the name or icons
- Override node icon
Create your decorator class via `api.decorator.DecoratorUser:extend()` and add it
to |nvim-tree.renderer.decorators|
e.g. default decorators with an user decorator being overridden only by Cut: >lua
{
"Git",
"Opened",
"Hidden",
"Modified",
"Bookmarks",
"Diagnostics",
"Copied",
MyDecorator,
"Cut",
}
<
See `api_decorator.lua` for decorator class definition and full documentation.
Example decorator: >lua
---Create your decorator class
---@class (exact) MyDecorator: nvim_tree.api.decorator.DecoratorUser
---@field private my_icon nvim_tree.api.HighlightedString
local MyDecorator = require("nvim-tree.api").decorator.DecoratorUser:extend()
---Mandatory constructor :new() will be called once per tree render, with no arguments.
function MyDecorator:new()
self.enabled = true
self.highlight_range = "all"
self.icon_placement = "signcolumn"
-- create your icon once, for convenience
self.my_icon = { str = "I", hl = { "MyIcon" } }
-- Define the icon sign only once
-- Only needed if you are using icon_placement = "signcolumn"
self:define_sign(self.my_icon)
end
---Override node icon
---@param node nvim_tree.api.Node
---@return nvim_tree.api.HighlightedString? icon_node
function MyDecorator:icon_node(node)
if node.name == "example" then
return self.my_icon
else
return nil
end
end
---Return one icon for DecoratorIconPlacement
---@param node nvim_tree.api.Node
---@return nvim_tree.api.HighlightedString[]? icons
function MyDecorator:icons(node)
if node.name == "example" then
return { self.my_icon }
else
return nil
end
end
---Exactly one highlight group for DecoratorHighlightRange
---@param node nvim_tree.api.Node
---@return string? highlight_group
function MyDecorator:highlight_group(node)
if node.name == "example" then
return "MyHighlight"
else
return nil
end
end
<
==============================================================================
12. OS SPECIFIC RESTRICTIONS *nvim-tree-os-specific*
Windows WSL and PowerShell
- Trash is synchronized
@ -2784,7 +2862,7 @@ Windows WSL and PowerShell
issues or disable this feature.
==============================================================================
12. NETRW *nvim-tree-netrw*
13. NETRW *nvim-tree-netrw*
|netrw| is a standard neovim plugin that is enabled by default. It provides,
amongst other functionality, a file/directory browser.
@ -2805,14 +2883,14 @@ keep using |netrw| without its browser features please ensure:
|nvim-tree.hijack_netrw| ` = true`
==============================================================================
13. LEGACY *nvim-tree-legacy*
14. LEGACY *nvim-tree-legacy*
Breaking refactors have been made however the legacy versions will be silently
migrated and used.
There are no plans to remove this migration.
==============================================================================
13.1 LEGACY: OPTS *nvim-tree-legacy-opts*
14.1 LEGACY: OPTS *nvim-tree-legacy-opts*
Legacy options are translated to the current, making type and value changes as
needed.
@ -2830,7 +2908,7 @@ needed.
`renderer.icons.webdev_colors` |nvim-tree.renderer.icons.web_devicons.file.color|
==============================================================================
13.2 LEGACY: HIGHLIGHT *nvim-tree-legacy-highlight*
14.2 LEGACY: HIGHLIGHT *nvim-tree-legacy-highlight*
Legacy highlight group are still obeyed when they are defined and the current
highlight group is not, hard linking as follows: >
@ -2879,10 +2957,10 @@ highlight group is not, hard linking as follows: >
NvimTreeLspDiagnosticsHintFolderText NvimTreeDiagnosticHintFolderHL
<
==============================================================================
14 INDEX *nvim-tree-index*
15 INDEX *nvim-tree-index*
==============================================================================
14.1 INDEX: OPTS *nvim-tree-index-opts*
15.1 INDEX: OPTS *nvim-tree-index-opts*
|nvim-tree.actions.change_dir|
|nvim-tree.actions.change_dir.enable|
@ -3051,7 +3129,7 @@ highlight group is not, hard linking as follows: >
|nvim-tree.view.width.padding|
==============================================================================
14.2 INDEX: API *nvim-tree-index-api*
15.2 INDEX: API *nvim-tree-index-api*
|nvim-tree-api.commands.get()|
|nvim-tree-api.config.mappings.default_on_attach()|

19
lua/nvim-tree/_meta/aliases.lua
View File

@ -1,19 +0,0 @@
---@meta
error("Cannot require a meta file")
--
--Internal convenience aliases for api types
--
--
--api.lua
--
---@alias HighlightedString nvim_tree.api.HighlightedString
--
--api_decorator.lua
--
---@alias DecoratorHighlightRange nvim_tree.api.decorator.HighlightRange
---@alias DecoratorIconPlacement nvim_tree.api.decorator.IconPlacement

98
lua/nvim-tree/_meta/api_decorator.lua
View File

@ -1,19 +1,7 @@
---@meta
error("Cannot require a meta file")
local nvim_tree = { api = { decorator = { DecoratorUser = {} } } }
---Custom decorator
---It may:
--- Add icons
--- Set highlight group for the name or icons
--- Override node icon
---Register it via :help nvim-tree.renderer.decorators
---Create class via require("nvim-tree.api").decorator.DecoratorUser:extend()
---Mandatory constructor :new() will be called once per tree render, with no arguments.
---Constructor must call:
--- :init
--- :define_sign when using "signcolumn" range
local nvim_tree = {}
---Highlight group range as per nvim-tree.renderer.highlight_*
---@alias nvim_tree.api.decorator.HighlightRange "none" | "icon" | "name" | "all"
@ -24,27 +12,28 @@ local nvim_tree = { api = { decorator = { DecoratorUser = {} } } }
---Names of builtin decorators or your decorator classes. Builtins are ordered lowest to highest priority.
---@alias nvim_tree.api.decorator.Name "Git" | "Opened" | "Hidden" | "Modified" | "Bookmarks" | "Diagnostics" | "Copied" | "Cut" | nvim_tree.api.decorator.DecoratorUser
---Your decorator will extend this class via require("nvim-tree.api").decorator.DecoratorUser:extend()
---Custom decorator, see :help nvim-tree-decorators
---
---@class (exact) nvim_tree.api.decorator.DecoratorUser
---@field protected enabled boolean
---@field protected highlight_range nvim_tree.api.decorator.HighlightRange
---@field protected icon_placement nvim_tree.api.decorator.IconPlacement
---Abstract: no-args constructor must be implemented.
---Abstract: no-args constructor must be implemented and will be called once per tree render.
---Must set all fields.
---
function nvim_tree.api.decorator.DecoratorUser:new() end
---Abstract: optionally implement to set the node's icon
---
---@param node nvim_tree.api.Node
---@return HighlightedString? icon_node
---@return nvim_tree.api.HighlightedString? icon_node
function nvim_tree.api.decorator.DecoratorUser:icon_node(node) end
---Abstract: optionally implement to provide icons and the highlight groups for your icon_placement.
---
---@param node nvim_tree.api.Node
---@return HighlightedString[]? icons
---@return nvim_tree.api.HighlightedString[]? icons
function nvim_tree.api.decorator.DecoratorUser:icons(node) end
---Abstract: optionally implement to provide one highlight group to apply to your highlight_range.
@ -53,81 +42,8 @@ function nvim_tree.api.decorator.DecoratorUser:icons(node) end
---@return string? highlight_group
function nvim_tree.api.decorator.DecoratorUser:highlight_group(node) end
---Must be called from your constructor.
---
---@class (exact) nvim_tree.api.decorator.InitArgs
---@field enabled boolean
---@field highlight_range nvim_tree.api.decorator.HighlightRange
---@field icon_placement nvim_tree.api.decorator.IconPlacement
---
---@protected
---@param args nvim_tree.api.decorator.InitArgs
function nvim_tree.api.decorator.DecoratorUser:init(args) end
---Define a sign. This should be called in the constructor.
---
---@protected
---@param icon HighlightedString?
---@param icon nvim_tree.api.HighlightedString?
function nvim_tree.api.decorator.DecoratorUser:define_sign(icon) end
--
-- Example Decorator
--
---@class (exact) MyDecorator: nvim_tree.api.decorator.DecoratorUser
---@field private my_icon nvim_tree.api.HighlightedString
local MyDecorator = require("nvim-tree.api").decorator.DecoratorUser:extend()
---Mandatory constructor :new() will be called once per tree render, with no arguments.
function MyDecorator:new()
---@type nvim_tree.api.decorator.InitArgs
local args = {
enabled = true,
highlight_range = "all",
icon_placement = "signcolumn",
}
-- init
self:init(args)
-- create your icon once, for convenience
self.my_icon = { str = "I", hl = { "MyIcon" } }
-- Define the icon sign only once
-- Only needed if you are using icon_placement = "signcolumn"
self:define_sign(self.my_icon)
end
---Override node icon
---@param node nvim_tree.api.Node
---@return nvim_tree.api.HighlightedString? icon_node
function MyDecorator:icon_node(node)
if node.name == "example" then
return self.my_icon
else
return nil
end
end
---Return one icon for DecoratorIconPlacement
---@param node nvim_tree.api.Node
---@return nvim_tree.api.HighlightedString[]? icons
function MyDecorator:icons(node)
if node.name == "example" then
return { self.my_icon }
else
return nil
end
end
---Exactly one highlight group for DecoratorHighlightRange
---@param node nvim_tree.api.Node
---@return string? highlight_group
function MyDecorator:highlight_group(node)
if node.name == "example" then
return "MyHighlight"
else
return nil
end
end

2
lua/nvim-tree/api.lua
View File

@ -313,7 +313,7 @@ Api.commands.get = wrap(function()
return require("nvim-tree.commands").get()
end)
---User provided decorator. Extend this class via :extend()
---Create a decorator class by calling :extend()
---@type nvim_tree.api.decorator.DecoratorUser
Api.decorator.DecoratorUser = DecoratorUser --[[@as nvim_tree.api.decorator.DecoratorUser]]

2
lua/nvim-tree/renderer/builder.lua
View File

@ -18,6 +18,8 @@ local DecoratorUser = require("nvim-tree.renderer.decorator.user")
local pad = require("nvim-tree.renderer.components.padding")
---@alias HighlightedString nvim_tree.api.HighlightedString
-- Builtin Decorators
---@type table<nvim_tree.api.decorator.Name, Decorator>
local BUILTIN_DECORATORS = {

13
lua/nvim-tree/renderer/decorator/bookmarks.lua
View File

@ -11,16 +11,11 @@ local DecoratorBookmarks = Decorator:extend()
---@protected
---@param args DecoratorArgs
function DecoratorBookmarks:new(args)
self.explorer = args.explorer
self.explorer = args.explorer
---@type AbstractDecoratorArgs
local a = {
enabled = true,
highlight_range = self.explorer.opts.renderer.highlight_bookmarks or "none",
icon_placement = self.explorer.opts.renderer.icons.bookmarks_placement or "none",
}
DecoratorBookmarks.super.new(self, a)
self.enabled = true
self.highlight_range = self.explorer.opts.renderer.highlight_bookmarks or "none"
self.icon_placement = self.explorer.opts.renderer.icons.bookmarks_placement or "none"
if self.explorer.opts.renderer.icons.show.bookmarks then
self.icon = {

13
lua/nvim-tree/renderer/decorator/copied.lua
View File

@ -10,16 +10,11 @@ local DecoratorCopied = Decorator:extend()
---@protected
---@param args DecoratorArgs
function DecoratorCopied:new(args)
self.explorer = args.explorer
self.explorer = args.explorer
---@type AbstractDecoratorArgs
local a = {
enabled = true,
highlight_range = self.explorer.opts.renderer.highlight_clipboard or "none",
icon_placement = "none",
}
DecoratorCopied.super.new(self, a)
self.enabled = true
self.highlight_range = self.explorer.opts.renderer.highlight_clipboard or "none"
self.icon_placement = "none"
end
---Copied highlight: renderer.highlight_clipboard and node is copied

13
lua/nvim-tree/renderer/decorator/cut.lua
View File

@ -10,16 +10,11 @@ local DecoratorCut = Decorator:extend()
---@protected
---@param args DecoratorArgs
function DecoratorCut:new(args)
self.explorer = args.explorer
self.explorer = args.explorer
---@type AbstractDecoratorArgs
local a = {
enabled = true,
highlight_range = self.explorer.opts.renderer.highlight_clipboard or "none",
icon_placement = "none",
}
DecoratorCut.super.new(self, a)
self.enabled = true
self.highlight_range = self.explorer.opts.renderer.highlight_clipboard or "none"
self.icon_placement = "none"
end
---Cut highlight: renderer.highlight_clipboard and node is cut

21
lua/nvim-tree/renderer/decorator/diagnostics.lua
View File

@ -41,20 +41,11 @@ local DecoratorDiagnostics = Decorator:extend()
---@protected
---@param args DecoratorArgs
function DecoratorDiagnostics:new(args)
self.explorer = args.explorer
self.explorer = args.explorer
---@type AbstractDecoratorArgs
local a = {
enabled = true,
highlight_range = self.explorer.opts.renderer.highlight_diagnostics or "none",
icon_placement = self.explorer.opts.renderer.icons.diagnostics_placement or "none",
}
DecoratorDiagnostics.super.new(self, a)
if not self.enabled then
return
end
self.enabled = true
self.highlight_range = self.explorer.opts.renderer.highlight_diagnostics or "none"
self.icon_placement = self.explorer.opts.renderer.icons.diagnostics_placement or "none"
if self.explorer.opts.renderer.icons.show.diagnostics then
self.diag_icons = {}
@ -72,7 +63,7 @@ end
---@param node Node
---@return HighlightedString[]? icons
function DecoratorDiagnostics:icons(node)
if node and self.enabled and self.diag_icons then
if node and self.diag_icons then
local diag_status = diagnostics.get_diag_status(node)
local diag_value = diag_status and diag_status.value
@ -86,7 +77,7 @@ end
---@param node Node
---@return string? highlight_group
function DecoratorDiagnostics:highlight_group(node)
if not node or not self.enabled or self.highlight_range == "none" then
if self.highlight_range == "none" then
return nil
end

17
lua/nvim-tree/renderer/decorator/git.lua
View File

@ -26,16 +26,11 @@ local DecoratorGit = Decorator:extend()
---@protected
---@param args DecoratorArgs
function DecoratorGit:new(args)
self.explorer = args.explorer
self.explorer = args.explorer
---@type AbstractDecoratorArgs
local a = {
enabled = self.explorer.opts.git.enable,
highlight_range = self.explorer.opts.renderer.highlight_git or "none",
icon_placement = self.explorer.opts.renderer.icons.git_placement or "none",
}
DecoratorGit.super.new(self, a)
self.enabled = self.explorer.opts.git.enable
self.highlight_range = self.explorer.opts.renderer.highlight_git or "none"
self.icon_placement = self.explorer.opts.renderer.icons.git_placement or "none"
if not self.enabled then
return
@ -149,7 +144,7 @@ end
---@param node Node
---@return HighlightedString[]? icons
function DecoratorGit:icons(node)
if not node or not self.enabled or not self.icons_by_xy then
if not self.icons_by_xy then
return nil
end
@ -210,7 +205,7 @@ end
---@param node Node
---@return string? highlight_group
function DecoratorGit:highlight_group(node)
if not node or not self.enabled or self.highlight_range == "none" then
if self.highlight_range == "none" then
return nil
end

17
lua/nvim-tree/renderer/decorator/hidden.lua
View File

@ -12,16 +12,11 @@ local DecoratorHidden = Decorator:extend()
---@protected
---@param args DecoratorArgs
function DecoratorHidden:new(args)
self.explorer = args.explorer
self.explorer = args.explorer
---@type AbstractDecoratorArgs
local a = {
enabled = true,
highlight_range = self.explorer.opts.renderer.highlight_hidden or "none",
icon_placement = self.explorer.opts.renderer.icons.hidden_placement or "none",
}
DecoratorHidden.super.new(self, a)
self.enabled = true
self.highlight_range = self.explorer.opts.renderer.highlight_hidden or "none"
self.icon_placement = self.explorer.opts.renderer.icons.hidden_placement or "none"
if self.explorer.opts.renderer.icons.show.hidden then
self.icon = {
@ -36,7 +31,7 @@ end
---@param node Node
---@return HighlightedString[]? icons
function DecoratorHidden:icons(node)
if self.enabled and node:is_dotfile() then
if node:is_dotfile() then
return { self.icon }
end
end
@ -45,7 +40,7 @@ end
---@param node Node
---@return string? highlight_group
function DecoratorHidden:highlight_group(node)
if not self.enabled or self.highlight_range == "none" or not node:is_dotfile() then
if self.highlight_range == "none" or not node:is_dotfile() then
return nil
end

62
lua/nvim-tree/renderer/decorator/init.lua
View File

@ -3,29 +3,34 @@ local Class = require("nvim-tree.classic")
---Abstract Decorator
---@class (exact) Decorator: Class
---@field protected enabled boolean
---@field protected highlight_range DecoratorHighlightRange
---@field protected icon_placement DecoratorIconPlacement
---@field protected highlight_range nvim_tree.api.decorator.HighlightRange
---@field protected icon_placement nvim_tree.api.decorator.IconPlacement
local Decorator = Class:extend()
---@class (exact) DecoratorArgs
---@field explorer Explorer
---Abstract constructor
---@class (exact) AbstractDecoratorArgs
---@field enabled boolean
---@field highlight_range DecoratorHighlightRange
---@field icon_placement DecoratorIconPlacement
---
---Abstract icon override, optionally implemented
---@param node Node
---@return HighlightedString? icon_node
function Decorator:icon_node(node)
return self:nop(node)
end
---Abstract icons, optionally implemented
---@protected
---@param args AbstractDecoratorArgs
function Decorator:new(args)
if args then
self.enabled = args.enabled
self.highlight_range = args.highlight_range
self.icon_placement = args.icon_placement
else
self.enabled = false
end
---@param node Node
---@return HighlightedString[]? icons
function Decorator:icons(node)
self:nop(node)
end
---Abstract highlight group, optionally implemented
---@protected
---@param node Node
---@return string? highlight_group
function Decorator:highlight_group(node)
self:nop(node)
end
---Maybe highlight groups for icon and name
@ -96,29 +101,6 @@ function Decorator:icons_right_align(node)
return self:icons(node)
end
---Maybe icon override, optionally implemented
---@param node Node
---@return HighlightedString? icon_node
function Decorator:icon_node(node)
return self:nop(node)
end
---Maybe icons, optionally implemented
---@protected
---@param node Node
---@return HighlightedString[]? icons
function Decorator:icons(node)
self:nop(node)
end
---Maybe highlight group, optionally implemented
---@protected
---@param node Node
---@return string? highlight_group
function Decorator:highlight_group(node)
self:nop(node)
end
---Define a sign
---@protected
---@param icon HighlightedString?

21
lua/nvim-tree/renderer/decorator/modified.lua
View File

@ -14,20 +14,11 @@ local DecoratorModified = Decorator:extend()
---@protected
---@param args DecoratorArgs
function DecoratorModified:new(args)
self.explorer = args.explorer
self.explorer = args.explorer
---@type AbstractDecoratorArgs
local a = {
enabled = true,
highlight_range = self.explorer.opts.renderer.highlight_modified or "none",
icon_placement = self.explorer.opts.renderer.icons.modified_placement or "none",
}
DecoratorModified.super.new(self, a)
if not self.enabled then
return
end
self.enabled = true
self.highlight_range = self.explorer.opts.renderer.highlight_modified or "none"
self.icon_placement = self.explorer.opts.renderer.icons.modified_placement or "none"
if self.explorer.opts.renderer.icons.show.modified then
self.icon = {
@ -42,7 +33,7 @@ end
---@param node Node
---@return HighlightedString[]? icons
function DecoratorModified:icons(node)
if self.enabled and buffers.is_modified(node) then
if buffers.is_modified(node) then
return { self.icon }
end
end
@ -51,7 +42,7 @@ end
---@param node Node
---@return string? highlight_group
function DecoratorModified:highlight_group(node)
if not self.enabled or self.highlight_range == "none" or not buffers.is_modified(node) then
if self.highlight_range == "none" or not buffers.is_modified(node) then
return nil
end

13
lua/nvim-tree/renderer/decorator/opened.lua
View File

@ -13,16 +13,11 @@ local DecoratorOpened = Decorator:extend()
---@protected
---@param args DecoratorArgs
function DecoratorOpened:new(args)
self.explorer = args.explorer
self.explorer = args.explorer
---@type AbstractDecoratorArgs
local a = {
enabled = true,
highlight_range = self.explorer.opts.renderer.highlight_opened_files or "none",
icon_placement = "none",
}
DecoratorOpened.super.new(self, a)
self.enabled = true
self.highlight_range = self.explorer.opts.renderer.highlight_opened_files or "none"
self.icon_placement = "none"
end
---Opened highlight: renderer.highlight_opened_files and node has an open buffer

6
lua/nvim-tree/renderer/decorator/user.lua
View File

@ -4,10 +4,4 @@ local Decorator = require("nvim-tree.renderer.decorator")
---@class (exact) DecoratorUser: Decorator
local DecoratorUser = Decorator:extend()
---User calls this instead of new
---@param args nvim_tree.api.decorator.InitArgs
function DecoratorUser:init(args)
DecoratorUser.super.new(self, args)
end
return DecoratorUser