From 93cf3f9f427d5aa826824b8de88ecf1dc3e20329 Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sun, 24 Nov 2024 17:49:35 +1100 Subject: [PATCH] feat(#2948): document API --- lua/nvim-tree/_meta/api_decorator.lua | 64 +++++++++---------- lua/nvim-tree/api.lua | 27 ++++++-- lua/nvim-tree/renderer/decorator/registry.lua | 15 +---- lua/nvim-tree/renderer/decorator/user.lua | 6 ++ 4 files changed, 58 insertions(+), 54 deletions(-) diff --git a/lua/nvim-tree/_meta/api_decorator.lua b/lua/nvim-tree/_meta/api_decorator.lua index 819d276aa8f..253e3da1b23 100644 --- a/lua/nvim-tree/_meta/api_decorator.lua +++ b/lua/nvim-tree/_meta/api_decorator.lua @@ -3,60 +3,56 @@ error("Cannot require a meta file") local nvim_tree = { api = { decorator = { BaseDecorator = {} } } } +---Create a custom decorator, extending nvim_tree.api.decorator.BaseDecorator +---It may: +--- Add icons +--- Set name highlight group +--- Override node icon +---Class must be created via nvim_tree.api.decorator.create() +---Mandatory constructor :new() will be called once per tree render, with no arguments. +---Constructor must call: +--- :init +--- :define_sign when using "signcolumn" range + ---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" --- --- BaseDecorator Class, see example implementation below --- +---Names of predefined decorators or your decorator classes +---@alias nvim_tree.api.decorator.Name "Cut" | "Copied" | "Diagnostics" | "Bookmarks" | "Modified" | "Hidden" | "Opened" | "Git" | nvim_tree.api.decorator.BaseDecorator ----User defined decorator to optionally add: ---- Additional icons ---- Name highlight group ---- Node icon override ----Class must be created via nvim_tree.api.decorator.BaseDecorator:extend() ----Mandatory constructor :new() will be called once per tree render, with no arguments. ----Constructor must call: ---- .super.new(self, args) passing nvim_tree.api.decorator.BaseDecoratorArgs ---- :define_sign(...) when using "signcolumn" range +---BaseDecorator Class, your decorator will extend this ---@class (exact) nvim_tree.api.decorator.BaseDecorator ---@field protected enabled boolean ---@field protected highlight_range nvim_tree.api.decorator.HighlightRange ---@field protected icon_placement nvim_tree.api.decorator.IconPlacement ----Constructor Arguments ----@class (exact) nvim_tree.api.decorator.BaseDecoratorArgs +---No-args constructor must be implemented +function nvim_tree.api.decorator.BaseDecorator:new() 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 - ----Use to instantiate your decorator class -function nvim_tree.api.decorator.BaseDecorator:extend() end - ----Super constructor must be called from your constructor ----BaseDecorator.super.new(self, args) +--- ---@protected ----@param self nvim_tree.api.decorator.BaseDecorator your instance ----@param args nvim_tree.api.decorator.BaseDecoratorArgs -function nvim_tree.api.decorator.BaseDecorator.new(self, args) end +---@param args nvim_tree.api.decorator.InitArgs +function nvim_tree.api.decorator.BaseDecorator:init(args) end ----Must implement a constructor and call super -function nvim_tree.api.decorator.BaseDecorator:new() end - ----Implement this method to set the node's icon +---Optionally implement this method to set the node's icon ---@param node nvim_tree.api.Node ---@return HighlightedString? icon_node function nvim_tree.api.decorator.BaseDecorator:icon_node(node) end ----Implement this method to provide icons and the highlight groups to apply to IconPlacement +---Optionally implement this method to provide icons and the highlight groups for your icon_placement ---@param node nvim_tree.api.Node ---@return HighlightedString[]? icons function nvim_tree.api.decorator.BaseDecorator:icons(node) end ----Implement this method to provide one highlight group to apply to HighlightRange +---Optionally implement this method to provide one highlight group to apply to your highlight_range ---@param node nvim_tree.api.Node ---@return string? highlight_group function nvim_tree.api.decorator.BaseDecorator:highlight_group(node) end @@ -65,23 +61,21 @@ function nvim_tree.api.decorator.BaseDecorator:highlight_group(node) end -- Example Decorator -- -local BaseDecorator = require("nvim-tree.api").decorator.BaseDecorator - ---@class (exact) MyDecorator: nvim_tree.api.decorator.BaseDecorator ---@field private my_icon nvim_tree.api.HighlightedString -local MyDecorator = BaseDecorator:extend() +local MyDecorator = require("nvim-tree.api").decorator.create() ---Mandatory constructor :new() will be called once per tree render, with no arguments. function MyDecorator:new() - ----@type nvim_tree.api.decorator.BaseDecoratorArgs + ---@type nvim_tree.api.decorator.InitArgs local args = { enabled = true, highlight_range = "all", icon_placement = "signcolumn", } - -- construct super with args - BaseDecorator.new(self, args) + -- init + self:init(args) -- create your icon once, for convenience self.my_icon = { str = "I", hl = { "MyIcon" } } diff --git a/lua/nvim-tree/api.lua b/lua/nvim-tree/api.lua index 9e3fdc989c7..64d778339bd 100644 --- a/lua/nvim-tree/api.lua +++ b/lua/nvim-tree/api.lua @@ -12,6 +12,7 @@ local decorator_registry = require("nvim-tree.renderer.decorator.registry") local DirectoryNode = require("nvim-tree.node.directory") local FileLinkNode = require("nvim-tree.node.file-link") local RootNode = require("nvim-tree.node.root") +local DecoratorUser = require("nvim-tree.renderer.decorator.user") local Api = { tree = {}, @@ -313,10 +314,26 @@ Api.commands.get = wrap(function() return require("nvim-tree.commands").get() end) --- TODO provide a registration convenience to hide classic --- TODO add doc -Api.decorator.BaseDecorator = require("nvim-tree.renderer.decorator.user") --[[@as nvim_tree.api.decorator.BaseDecorator ]] -Api.decorator.register = decorator_registry.register -Api.decorator.unregister = decorator_registry.unregister +---Create a new decorator class +--- +---@return nvim_tree.api.decorator.BaseDecorator +Api.decorator.create = function() return DecoratorUser:extend() end + +---Register a decorator class +--- +---@class RegisterOpts +---@field decorator nvim_tree.api.decorator.BaseDecorator +---@field below nvim_tree.api.decorator.Name? +--- +---@param opts RegisterOpts +Api.decorator.register = function(opts) decorator_registry.register(opts) end + +---Unregister a decorator class +--- +---@class UnRegisterOpts +---@field decorator nvim_tree.api.decorator.BaseDecorator +--- +---@param opts UnRegisterOpts +Api.decorator.unregister = function(opts) decorator_registry.unregister(opts) end return Api diff --git a/lua/nvim-tree/renderer/decorator/registry.lua b/lua/nvim-tree/renderer/decorator/registry.lua index 5c94a31b4ac..dec70621235 100644 --- a/lua/nvim-tree/renderer/decorator/registry.lua +++ b/lua/nvim-tree/renderer/decorator/registry.lua @@ -1,4 +1,3 @@ -local notify = require("nvim-tree.notify") local utils = require("nvim-tree.utils") local DecoratorBookmarks = require("nvim-tree.renderer.decorator.bookmarks") @@ -11,12 +10,8 @@ local DecoratorHidden = require("nvim-tree.renderer.decorator.hidden") local DecoratorOpened = require("nvim-tree.renderer.decorator.opened") local DecoratorUser = require("nvim-tree.renderer.decorator.user") --- Globally registered decorators including user --- Lowest priority first - ----@alias DecoratorName nvim_tree.api.decorator.BaseDecorator | "Cut" | "Copied" | "Diagnostics" | "Bookmarks" | "Modified" | "Hidden" | "Opened" | "Git" - local M = { + -- Globally registered decorators including user. Lowest priority first. ---@type Decorator[] registered = { DecoratorGit, @@ -30,10 +25,6 @@ local M = { } } ----@class RegisterOpts ----@field decorator nvim_tree.api.decorator.BaseDecorator ----@field below DecoratorName? - ---@param opts RegisterOpts function M.register(opts) if not opts or not opts.decorator then @@ -41,7 +32,6 @@ function M.register(opts) end if vim.tbl_contains(M.registered, opts.decorator) then - notify.error("decorator already registered") return end @@ -56,9 +46,6 @@ function M.register(opts) table.insert(M.registered, opts.decorator) end ----@class UnRegisterOpts ----@field decorator nvim_tree.api.decorator.BaseDecorator - ---@param opts UnRegisterOpts function M.unregister(opts) if not opts or not opts.decorator then diff --git a/lua/nvim-tree/renderer/decorator/user.lua b/lua/nvim-tree/renderer/decorator/user.lua index 5dcbb7b82fc..61915d44b09 100644 --- a/lua/nvim-tree/renderer/decorator/user.lua +++ b/lua/nvim-tree/renderer/decorator/user.lua @@ -4,4 +4,10 @@ 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