From 45a14f6c3839783e653ace532e50922f02f0a64e Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 24 Nov 2024 12:04:10 +1100 Subject: [PATCH] feat(#2948): extract _meta following nvim pattern --- lua/nvim-tree/{meta.lua => _meta/api.lua} | 35 ++++---- lua/nvim-tree/_meta/api_decorator.lua | 88 +++++++++++++++++++ .../renderer/decorator/bookmarks.lua | 4 +- lua/nvim-tree/renderer/decorator/copied.lua | 2 +- lua/nvim-tree/renderer/decorator/cut.lua | 2 +- .../renderer/decorator/diagnostics.lua | 4 +- lua/nvim-tree/renderer/decorator/git.lua | 6 +- lua/nvim-tree/renderer/decorator/hidden.lua | 4 +- lua/nvim-tree/renderer/decorator/init.lua | 7 +- lua/nvim-tree/renderer/decorator/modified.lua | 4 +- lua/nvim-tree/renderer/decorator/opened.lua | 2 +- lua/nvim-tree/renderer/decorator/user.lua | 75 +--------------- 12 files changed, 130 insertions(+), 103 deletions(-) rename lua/nvim-tree/{meta.lua => _meta/api.lua} (69%) create mode 100644 lua/nvim-tree/_meta/api_decorator.lua diff --git a/lua/nvim-tree/meta.lua b/lua/nvim-tree/_meta/api.lua similarity index 69% rename from lua/nvim-tree/meta.lua rename to lua/nvim-tree/_meta/api.lua index d66e725530b..d5903603133 100644 --- a/lua/nvim-tree/meta.lua +++ b/lua/nvim-tree/_meta/api.lua @@ -1,9 +1,14 @@ ---@meta +error('Cannot require a meta file') + +-- TODO describe class +-- TODO describe user decorator -- -- Nodes -- +---Base Node, Abstract ---@class (exact) nvim_tree.api.Node: Class ---@field type "file" | "directory" | "link" uv.fs_stat.result.type ---@field absolute_path string @@ -15,45 +20,41 @@ ---@field parent nvim_tree.api.DirectoryNode? ---@field diag_severity lsp.DiagnosticSeverity? +---File ---@class (exact) nvim_tree.api.FileNode: nvim_tree.api.Node ---@field extension string +---Directory ---@class (exact) nvim_tree.api.DirectoryNode: nvim_tree.api.Node ---@field has_children boolean ---@field nodes nvim_tree.api.Node[] ---@field open boolean +---Root Directory ---@class (exact) nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode +---Link mixin ---@class (exact) nvim_tree.api.LinkNode: Class ---@field link_to string ---@field fs_stat_target uv.fs_stat.result +---File Link ---@class (exact) nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode +---DirectoryLink ---@class (exact) nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode -- --- Decorators +-- Various Types -- ----Highlight group range as per nvim-tree.renderer.highlight_* ----@alias DecoratorHighlightRange "none" | "icon" | "name" | "all" - ----Icon position as per renderer.icons.*_placement ----@alias DecoratorIconPlacement "none" | "before" | "after" | "signcolumn" | "right_align" - ----Decorator Constructor Arguments ----@class (exact) DecoratorArgs ----@field enabled boolean ----@field highlight_range DecoratorHighlightRange ----@field icon_placement DecoratorIconPlacement +---A string for rendering, with optional highlight groups to apply to it +---@class (exact) nvim_tree.api.HighlightedString +---@field str string +---@field hl string[] -- --- Types +-- Internal Aliases -- +---@alias HighlightedString nvim_tree.api.HighlightedString ----A string for rendering, with optional highlight groups to apply to it ----@class (exact) HighlightedString ----@field str string ----@field hl string[] diff --git a/lua/nvim-tree/_meta/api_decorator.lua b/lua/nvim-tree/_meta/api_decorator.lua new file mode 100644 index 00000000000..288979d325b --- /dev/null +++ b/lua/nvim-tree/_meta/api_decorator.lua @@ -0,0 +1,88 @@ +---@meta +error('Cannot require a meta file') + +---Highlight group range as per nvim-tree.renderer.highlight_* +---@alias nvim_tree.api.decorator.HighlightRange "none" | "icon" | "name" | "all" + +---Icon position as per renderer.icons.*_placement +---@alias nvim_tree.api.decorator.IconPlacement "none" | "before" | "after" | "signcolumn" | "right_align" + +---UserDecorator Constructor Arguments +---@class (exact) nvim_tree.api.decorator.UserDecoratorArgs +---@field enabled boolean +---@field highlight_range nvim_tree.api.decorator.HighlightRange +---@field icon_placement nvim_tree.api.decorator.IconPlacement + + +-- +-- Example UserDecorator +-- + +local UserDecorator = require("nvim-tree.renderer.decorator.user") + +---@class (exact) MyDecorator: UserDecorator +---@field private my_icon nvim_tree.api.HighlightedString +local MyDecorator = UserDecorator:extend() + +---Constructor +function MyDecorator:new() + + ---@type nvim_tree.api.decorator.UserDecoratorArgs + local args = { + enabled = true, + highlight_range = "all", + icon_placement = "signcolumn", + } + + -- construct super with args + MyDecorator.super.new(self, 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 + +---Overridde 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 + +return MyDecorator + +-- +-- Internal Aliases +-- +---@alias DecoratorHighlightRange nvim_tree.api.decorator.HighlightRange +---@alias DecoratorIconPlacement nvim_tree.api.decorator.IconPlacement + diff --git a/lua/nvim-tree/renderer/decorator/bookmarks.lua b/lua/nvim-tree/renderer/decorator/bookmarks.lua index b4baac890b8..4d074e55794 100644 --- a/lua/nvim-tree/renderer/decorator/bookmarks.lua +++ b/lua/nvim-tree/renderer/decorator/bookmarks.lua @@ -33,7 +33,7 @@ end ---Bookmark icon: renderer.icons.show.bookmarks and node is marked ---@param node Node ----@return HighlightedString[]|nil icons +---@return HighlightedString[]? icons function DecoratorBookmarks:icons(node) if self.explorer.marks:get(node) then return { self.icon } @@ -42,7 +42,7 @@ end ---Bookmark highlight: renderer.highlight_bookmarks and node is marked ---@param node Node ----@return string|nil group +---@return string? highlight_group function DecoratorBookmarks:highlight_group(node) if self.highlight_range ~= "none" and self.explorer.marks:get(node) then return "NvimTreeBookmarkHL" diff --git a/lua/nvim-tree/renderer/decorator/copied.lua b/lua/nvim-tree/renderer/decorator/copied.lua index 105da0a8a2c..85ded7b7453 100644 --- a/lua/nvim-tree/renderer/decorator/copied.lua +++ b/lua/nvim-tree/renderer/decorator/copied.lua @@ -24,7 +24,7 @@ end ---Copied highlight: renderer.highlight_clipboard and node is copied ---@param node Node ----@return string|nil group +---@return string? highlight_group function DecoratorCopied:highlight_group(node) if self.highlight_range ~= "none" and self.explorer.clipboard:is_copied(node) then return "NvimTreeCopiedHL" diff --git a/lua/nvim-tree/renderer/decorator/cut.lua b/lua/nvim-tree/renderer/decorator/cut.lua index 35c9af1356f..4546a990a7d 100644 --- a/lua/nvim-tree/renderer/decorator/cut.lua +++ b/lua/nvim-tree/renderer/decorator/cut.lua @@ -24,7 +24,7 @@ end ---Cut highlight: renderer.highlight_clipboard and node is cut ---@param node Node ----@return string|nil group +---@return string? highlight_group function DecoratorCut:highlight_group(node) if self.highlight_range ~= "none" and self.explorer.clipboard:is_cut(node) then return "NvimTreeCutHL" diff --git a/lua/nvim-tree/renderer/decorator/diagnostics.lua b/lua/nvim-tree/renderer/decorator/diagnostics.lua index 0b2e7f9abc2..d61996bffef 100644 --- a/lua/nvim-tree/renderer/decorator/diagnostics.lua +++ b/lua/nvim-tree/renderer/decorator/diagnostics.lua @@ -70,7 +70,7 @@ end ---Diagnostic icon: diagnostics.enable, renderer.icons.show.diagnostics and node has status ---@param node Node ----@return HighlightedString[]|nil icons +---@return HighlightedString[]? icons function DecoratorDiagnostics:icons(node) if node and self.enabled and self.diag_icons then local diag_status = diagnostics.get_diag_status(node) @@ -84,7 +84,7 @@ end ---Diagnostic highlight: diagnostics.enable, renderer.highlight_diagnostics and node has status ---@param node Node ----@return string|nil group +---@return string? highlight_group function DecoratorDiagnostics:highlight_group(node) if not node or not self.enabled or self.highlight_range == "none" then return nil diff --git a/lua/nvim-tree/renderer/decorator/git.lua b/lua/nvim-tree/renderer/decorator/git.lua index 1ed0df7cf25..a4e6cd7945c 100644 --- a/lua/nvim-tree/renderer/decorator/git.lua +++ b/lua/nvim-tree/renderer/decorator/git.lua @@ -3,7 +3,7 @@ local notify = require("nvim-tree.notify") local Decorator = require("nvim-tree.renderer.decorator") local DirectoryNode = require("nvim-tree.node.directory") ----@class (exact) GitHighlightedString: HighlightedString +---@class (exact) GitHighlightedString: nvim_tree.api.HighlightedString ---@field ord number decreasing priority ---@alias GitStatusStrings "deleted" | "ignored" | "renamed" | "staged" | "unmerged" | "unstaged" | "untracked" @@ -147,7 +147,7 @@ end ---Git icons: git.enable, renderer.icons.show.git and node has status ---@param node Node ----@return HighlightedString[]|nil modified icon +---@return HighlightedString[]? icons function DecoratorGit:icons(node) if not node or not self.enabled or not self.icons_by_xy then return nil @@ -208,7 +208,7 @@ end ---Git highlight: git.enable, renderer.highlight_git and node has status ---@param node Node ----@return string|nil group +---@return string? highlight_group function DecoratorGit:highlight_group(node) if not node or not self.enabled or self.highlight_range == "none" then return nil diff --git a/lua/nvim-tree/renderer/decorator/hidden.lua b/lua/nvim-tree/renderer/decorator/hidden.lua index 26d16b36f5c..0c4c8fe1507 100644 --- a/lua/nvim-tree/renderer/decorator/hidden.lua +++ b/lua/nvim-tree/renderer/decorator/hidden.lua @@ -34,7 +34,7 @@ end ---Hidden icon: renderer.icons.show.hidden and node starts with `.` (dotfile). ---@param node Node ----@return HighlightedString[]|nil icons +---@return HighlightedString[]? icons function DecoratorHidden:icons(node) if self.enabled and node:is_dotfile() then return { self.icon } @@ -43,7 +43,7 @@ end ---Hidden highlight: renderer.highlight_hidden and node starts with `.` (dotfile). ---@param node Node ----@return string|nil group +---@return string? highlight_group function DecoratorHidden:highlight_group(node) if not self.enabled or self.highlight_range == "none" or not node:is_dotfile() then return nil diff --git a/lua/nvim-tree/renderer/decorator/init.lua b/lua/nvim-tree/renderer/decorator/init.lua index e4a1c098727..adfd01dc96d 100644 --- a/lua/nvim-tree/renderer/decorator/init.lua +++ b/lua/nvim-tree/renderer/decorator/init.lua @@ -7,6 +7,11 @@ local Class = require("nvim-tree.classic") ---@field protected icon_placement DecoratorIconPlacement local Decorator = Class:extend() +---@class (exact) DecoratorArgs +---@field enabled boolean +---@field highlight_range DecoratorHighlightRange +---@field icon_placement DecoratorIconPlacement + ---@protected ---@param args DecoratorArgs function Decorator:new(args) @@ -105,7 +110,7 @@ end ---Maybe highlight group, optionally implemented ---@protected ---@param node Node ----@return string? group +---@return string? highlight_group function Decorator:highlight_group(node) self:nop(node) end diff --git a/lua/nvim-tree/renderer/decorator/modified.lua b/lua/nvim-tree/renderer/decorator/modified.lua index 80ecec9c13c..da55f19adf7 100644 --- a/lua/nvim-tree/renderer/decorator/modified.lua +++ b/lua/nvim-tree/renderer/decorator/modified.lua @@ -40,7 +40,7 @@ end ---Modified icon: modified.enable, renderer.icons.show.modified and node is modified ---@param node Node ----@return HighlightedString[]|nil icons +---@return HighlightedString[]? icons function DecoratorModified:icons(node) if self.enabled and buffers.is_modified(node) then return { self.icon } @@ -49,7 +49,7 @@ end ---Modified highlight: modified.enable, renderer.highlight_modified and node is modified ---@param node Node ----@return string|nil group +---@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 return nil diff --git a/lua/nvim-tree/renderer/decorator/opened.lua b/lua/nvim-tree/renderer/decorator/opened.lua index dbec8f7d4ea..7a02c6d4c99 100644 --- a/lua/nvim-tree/renderer/decorator/opened.lua +++ b/lua/nvim-tree/renderer/decorator/opened.lua @@ -27,7 +27,7 @@ end ---Opened highlight: renderer.highlight_opened_files and node has an open buffer ---@param node Node ----@return string|nil group +---@return string? highlight_group function DecoratorOpened:highlight_group(node) if self.highlight_range ~= "none" and buffers.is_opened(node) then return "NvimTreeOpenedHL" diff --git a/lua/nvim-tree/renderer/decorator/user.lua b/lua/nvim-tree/renderer/decorator/user.lua index c1c1adb4808..21e66236cc5 100644 --- a/lua/nvim-tree/renderer/decorator/user.lua +++ b/lua/nvim-tree/renderer/decorator/user.lua @@ -8,96 +8,29 @@ local Decorator = require("nvim-tree.renderer.decorator") ---Must call: --- super passing DecoratorArgs MyDecorator.super.new(self, args) --- define_sign when using "signcolumn" ----See example at end. ---@class (exact) UserDecorator: Decorator local UserDecorator = Decorator:extend() ---Override this method to set the node's icon ----@param node Node +---@param node nvim_tree.api.Node ---@return HighlightedString? icon_node function UserDecorator:icon_node(node) return self:nop(node) end ---Override this method to provide icons and the highlight groups to apply to DecoratorIconPlacement ----@param node Node +---@param node nvim_tree.api.Node ---@return HighlightedString[]? icons function UserDecorator:icons(node) self:nop(node) end ---Override this method to provide one highlight group to apply to DecoratorRange ----@param node Node ----@return string? group +---@param node nvim_tree.api.Node +---@return string? highlight_group function UserDecorator:highlight_group(node) self:nop(node) end return UserDecorator - - ---- ----Example user decorator ---[[ - -local UserDecorator = require("nvim-tree.renderer.decorator.user") - ----@class (exact) MyDecorator: UserDecorator ----@field private my_icon HighlightedString -local MyDecorator = UserDecorator:extend() - ----Constructor -function MyDecorator:new() - - ---@type DecoratorArgs - local args = { - enabled = true, - highlight_range = "all", - icon_placement = "signcolumn", - } - - MyDecorator.super.new(self, 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 - ----Overridden node icon ----@param node Node ----@return HighlightedString? icon_node -function MyDecorator:icon_node(node) - if node.name == "example" then - return self.my_icon - else - return nil - end -end - ----Just one icon for DecoratorIconPlacement ----@param node Node ----@return HighlightedString[]|nil 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 Node ----@return string|nil group -function MyDecorator:highlight_group(node) - if node.name == "example" then - return "ExampleHighlight" - else - return nil - end -end - ---]]