Skip to content

Commit

Permalink
feat(#2948): tidy decorator args and complete documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@alex-courtis
alex-courtis committed Dec 1, 2024
1 parent cb351ae commit 4bf4a85
Show file tree
Hide file tree
Showing 15 changed files with 172 additions and 267 deletions.
122 changes: 100 additions & 22 deletions doc/nvim-tree-lua.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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*
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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: >
Expand Down Expand Up @@ -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|
Expand Down Expand Up @@ -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()|
Expand Down
19 changes: 0 additions & 19 deletions lua/nvim-tree/_meta/aliases.lua
View file

This file was deleted.

98 changes: 7 additions & 91 deletions lua/nvim-tree/_meta/api_decorator.lua
View file
Original file line number Diff line number Diff line change
@@ -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"
Expand 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.
Expand All @@ -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 changes: 1 addition & 1 deletion lua/nvim-tree/api.lua
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]]

Expand Down
2 changes: 2 additions & 0 deletions lua/nvim-tree/renderer/builder.lua
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
Expand Down
13 changes: 4 additions & 9 deletions lua/nvim-tree/renderer/decorator/bookmarks.lua
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
Expand Down
Loading

0 comments on commit 4bf4a85

Please sign in to comment.