feat(api): add public API module (#1432)

README.md

@@ -98,6 +98,10 @@ Basic commands:
 
 `:NvimTreeCollapse` Collapses the nvim-tree recursively.
 
+## Api
+
+nvim-tree exposes a public api; see [:help nvim-tree-api](doc/nvim-tree-lua.txt). This is a stable non breaking api.
+
 ## Mappings
 
 nvim-tree comes with number of mappings; for default mappings please see [:help nvim-tree-default-mappings](doc/nvim-tree-lua.txt), for way of configuring mappings see [:help nvim-tree-mappings](doc/nvim-tree-lua.txt)

doc/nvim-tree-lua.txt

@@ -10,11 +10,11 @@ CONTENTS                                                           *nvim-tree*
   3. Commands                                 |nvim-tree-commands|
   4. Setup/Configuration                      |nvim-tree-setup|
   4.1 Vinegar Style                           |nvim-tree-vinegar|
-  5. Mappings                                 |nvim-tree-mappings|
+  5. Api                                      |nvim-tree-api|
-  6. Highlight Groups                         |nvim-tree-highlight|
+  6. Mappings                                 |nvim-tree-mappings|
-  7. Events                                   |nvim-tree-events|
+  7. Highlight Groups                         |nvim-tree-highlight|
-  7.1 Available Events                        |nvim-tree.events|
+  8. Events                                   |nvim-tree-events|
-  8. Bookmarks                                |nvim-tree-bookmarks|
+  9. Bookmarks                                |nvim-tree-bookmarks|
 
 ==============================================================================
  1. INTRODUCTION                                      *nvim-tree-introduction*
@@ -949,7 +949,99 @@ You'll also need to set |nvim-tree.hijack_netrw| to `true` during setup.
 A good functionnality to enable is |nvim-tree.hijack_directories|.
 
 ==============================================================================
- 5. MAPPINGS                                              *nvim-tree-mappings*
+ 5. API                                                   *nvim-tree-api*
+
+Nvim-tree's public API can be used to access features.
+>
+    local nt_api = require("nvim-tree.api")
+
+    nt_api.tree.toggle()
+<
+This module exposes stable functionalities, it is advised to use this in order
+to avoid breaking configurations due to internal breaking changes.
+
+The api is separated in multiple modules, which can be accessed with
+`require("nvim-tree.api").moduleName.functionality`.
+
+Functions that needs a tree node parameter are exposed with an abstraction
+that injects the node from the cursor position in the tree when calling 
+the function. It will use the node you pass as an argument in priority if it
+exists.
+
+- api.tree:                                             *nvim-tree.api.tree*
+    - open `(path?: string)`
+    - close
+    - toggle `(find_file?: bool, no_focus?: bool, path?: string)`
+    - focus
+    - reload
+    - change_root `(path: string)`
+    - change_root_to_parent
+    - get_node_under_cursor
+    - find_file `(filename: string)`
+    - search_node
+    - collapse_all `(keep_buffers?: bool)`
+    - expand_all
+    - toggle_gitignore_filter
+    - toggle_custom_filter
+    - toggle_hidden_filter
+    - toggle_help
+
+- api.fs:                                               *nvim-tree.api.fs*
+    - create
+    - remove
+    - trash
+    - rename
+    - rename_sub
+    - copy
+    - cut
+    - paste
+    - print_clipboard
+    - copy.absolute_path
+    - copy.filename
+    - copy.relative_path
+
+- api.node:                                             *nvim-tree.api.node*
+    - open.edit
+    - open.vertical
+    - open.horizontal
+    - open.tab
+    - open.preview
+    - show_info_popup
+    - run.cmd
+    - run.system
+    - navigate.sibling.next
+    - navigate.sibling.prev
+    - navigate.sibling.first
+    - navigate.sibling.last
+    - navigate.parent
+    - navigate.parent_close
+    - navigate.git.next
+    - navigate.git.prev
+    - navigate.diagnostics.next
+    - navigate.diagnostics.prev
+
+- api.git:                                              *nvim-tree.api.git*
+    - reload
+
+- api.events:                                           *nvim-tree.api.events*
+    - subscribe `(eventType: Event, callback: function(...args))`
+    - Event (enum type, please see |nvim_tree_events_kind|)
+
+- api.live_filter:                                      *nvim-tree.api.live_filter*
+    - start
+    - clear
+
+- api.marks:                                            *nvim-tree.api.marks*
+    - get
+    - list
+    - toggle
+    - bulk.move
+    - navigate.next
+    - navigate.prev
+    - navigate.select
+
+==============================================================================
+ 6. MAPPINGS                                              *nvim-tree-mappings*
 
 The `list` option in `view.mappings.list` is a table of
 
@@ -1076,7 +1168,7 @@ DEFAULT MAPPINGS                                     *nvim-tree-default-mappings
   } -- END_DEFAULT_MAPPINGS
 <
 ==============================================================================
- 6. HIGHLIGHT GROUPS                                     *nvim-tree-highlight*
+ 7. HIGHLIGHT GROUPS                                     *nvim-tree-highlight*
 
 All the following highlight groups can be configured by hand. Aside from
 `NvimTreeWindowPicker`, it is not advised to colorize the background of these
@@ -1150,7 +1242,7 @@ NvimTreeBookmark
 
 
 ==============================================================================
- 7. EVENTS                                                  *nvim-tree-events*
+ 8. EVENTS                                                  *nvim-tree-events*
 
 |nvim_tree_events|
 
@@ -1158,121 +1250,77 @@ nvim-tree will dispatch events whenever an action is made. These events can be
 subscribed to through handler functions. This allows for even further
 customization of nvim-tree.
 
-A handler for an event is just a function which receives one argument -
+A handler for an event is just a function which receives one argument, the 
-the payload of the event. The payload is different for each event type. Refer
+payload of the event. The payload is different for each event type. Refer
 to |nvim_tree_registering_handlers| for more information.
-<
 
 |nvim_tree_registering_handlers|
 
-Handlers are registered by calling the `on_*` functions available in the
+Handlers are registered by calling the `events.subscribe` function available in the
-`require('nvim-tree.events')` module. See |nvim-tree.events|.
+`require("nvim-tree.api")` module.
 
+For example, registering a handler for when a node is renamed is done like this:
+>
+    local api = require('nvim-tree.api')
 
-For example, registering a handler for when a node is renamed is done like this: >
+    api.events.subscribe(Event.NodeRenamed, function(data)
-
-    local events = require('nvim-tree.events')
-
-    events.on_node_renamed(function(data)
         print("Node renamed from " .. data.old_name .. " to " ..  data.new_name)
     end)
+<
 
-==============================================================================
+|nvim_tree_events_kind|
- 7.1 Lua module: nvim-tree.events                           *nvim-tree.events*
 
-                                     *nvim-tree.events.on_nvim_tree_ready()*
+You can access the event enum with:
-on_nvim_tree_ready({handler})
+>
-                Registers a handler for when NvimTree has been initialized.
+    local Event = require('nvim-tree.api').events.Event
+<
+Here is the list of available variant of this enum:
 
-                Parameters: ~
+- Event.Ready 
-                  {handler}      `{function}` Handler function, with the
+                When NvimTree has been initialized
-                                 signature `function()`.
+                • Note: Handler takes no parameter.
 
-                                     *nvim-tree.events.on_node_renamed()*
+- Event.TreeOpen
-on_node_renamed({handler})
+                • Note: Handler takes no parameter.
-                Registers a handler for when a node is renamed.
+
+- Event.TreeClose
+                • Note: Handler takes no parameter.
+
+- Event.Resize - When NvimTree is resized.
+                handler parameters: ~
+                    size:        `number` size of the view in columns.
+
+- Event.NodeRenamed
                 • Note: A node can either be a file or a directory.
-
+                handler parameters: ~
-                Parameters: ~
-                  {handler}      `{function}` Handler function, with the
-                                 signature `function(payload)`.
-                payload: ~
                   {old_name}     `{string}` Absolute path to the old node location.
                   {new_name}     `{string}` Absolute path to the new node location.
 
-                                     *nvim-tree.events.on_file_created()*
+- Event.FileCreated
-on_file_created({handler})
+                handler parameters: ~
-                Registers a handler for when a file is created.
-
-                Parameters: ~
-                  {handler}      `{function}` Handler function, with the
-                                 signature `function(payload)`.
-                payload: ~
                   {fname}        `{string}` Absolute path to the created file
 
-                                     *nvim-tree.events.on_file_removed()*
+- Event.FileRemoved
-on_file_removed({handler})
+                handler parameters: ~
-                Registers a handler for when a file is removed.
-
-                Parameters: ~
-                  {handler}      `{function}` Handler function, with the
-                                 signature `function(payload)`.
-                payload: ~
                   {fname}        `{string}` Absolute path to the removed file.
 
-                                   *nvim-tree.events.on_folder_created()*
+- Event.FolderCreated
-on_folder_created({handler})
+                handler parameters: ~
-                Registers a handler for when a folder is created.
-
-                Parameters: ~
-                  {handler}      `{function}` Handler function, with the
-                                 signature `function(payload)`.
-                payload: ~
                   {folder_name}  `{string}` Absolute path to the created folder.
 
-                                   *nvim-tree.events.on_folder_removed()*
+- Event.FolderRemoved
-on_folder_removed({handler})
+                handler parameters: ~
-                Registers a handler for when a folder is removed.
-
-                Parameters: ~
-                  {handler}      `{function}` Handler function, with the
-                                 signature `function(payload)`.
-                payload: ~
                   {folder_name}  `{string}` Absolute path to the removed folder.
 
-                                   *nvim-tree.events.on_tree_open()*
-on_tree_open({handler})
-                Registers a handler for when NvimTree is opened.
-
-                Parameters: ~
-                  {handler}      `{function}` Handler function, with the
-                                 signature `function()`.
-
-                                   *nvim-tree.events.on_tree_close()*
-on_tree_close({handler})
-                Registers a handler for when NvimTree is closed.
-
-                Parameters: ~
-                  {handler}      `{function}` Handler function, with the
-                                 signature `function()`.
-
-                                   *nvim-tree.events.on_tree_resize()*
-on_tree_resize({handler})
-                Registers a handler for when NvimTree is resized.
-
-                Parameters: ~
-                  {handler}      `{function}` Handler function, with the
-                                 signature `function(size)`.
-
 ==============================================================================
- 8. BOOKMARKS                                      *nvim-tree-bookmarks*
+ 9. BOOKMARKS                                      *nvim-tree-bookmarks*
 
 You can toggle marks on files/folders with
-`require("nvim-tree.marks").toggle_mark(node)` which is bound to `m` by
+`require("nvim-tree.api").marks.toggle(node)` which is bound to `m` by
 default.
 
 To get the list of marked paths, you can call
-`require("nvim-tree.marks").get_marks()`. This will return `{node}`.
+`require("nvim-tree.api").marks.list()`. This will return `{node}`.
 
 *nvim-tree.bookmarks.navigation*
 
@@ -1282,8 +1330,8 @@ want to focus the tree view each time we wish to switch to another mark.
 This requires binding bookmark navigation yourself.
 
 -- in your lua configuration
-vim.keymap.set("n", "<leader>mn", require("nvim-tree.marks.navigation").next)
+vim.keymap.set("n", "<leader>mn", require("nvim-tree.api").marks.navigate.next)
-vim.keymap.set("n", "<leader>mp", require("nvim-tree.marks.navigation").prev)
+vim.keymap.set("n", "<leader>mp", require("nvim-tree.api").marks.navigate.prev)
-vim.keymap.set("n", "<leader>ms", require("nvim-tree.marks.navigation").select)
+vim.keymap.set("n", "<leader>ms", require("nvim-tree.api").marks.navigate.select)
 
  vim:tw=78:ts=4:sw=4:et:ft=help:norl:

lua/nvim-tree/api.lua

@@ -0,0 +1,112 @@
+local Api = {
+  tree = {},
+  node = { navigate = { sibling = {}, git = {}, diagnostics = {} }, run = {}, open = {} },
+  events = {},
+  marks = { bulk = {}, navigate = {} },
+  fs = { copy = {} },
+  git = {},
+  live_filter = {},
+}
+
+local function inject_node(f)
+  return function(node)
+    node = node or require("nvim-tree.lib").get_node_at_cursor()
+    f(node)
+  end
+end
+
+Api.tree.open = require("nvim-tree").open
+Api.tree.toggle = require("nvim-tree").toggle
+Api.tree.close = require("nvim-tree.view").close
+Api.tree.focus = require("nvim-tree").focus
+Api.tree.reload = require("nvim-tree.actions.reloaders.reloaders").reload_explorer
+Api.tree.change_root = require("nvim-tree").change_dir
+Api.tree.change_root_to_parent = inject_node(require("nvim-tree.actions.root.dir-up").fn)
+Api.tree.get_node_under_cursor = require("nvim-tree.lib").get_node_at_cursor
+Api.tree.find_file = require("nvim-tree.actions.finders.find-file").fn
+Api.tree.search_node = require("nvim-tree.actions.finders.search-node").fn
+Api.tree.collapse_all = require("nvim-tree.actions.tree-modifiers.collapse-all").fn
+Api.tree.expand_all = inject_node(require("nvim-tree.actions.tree-modifiers.expand-all").fn)
+Api.tree.toggle_gitignore_filter = require("nvim-tree.actions.tree-modifiers.toggles").git_ignored
+Api.tree.toggle_custom_filter = require("nvim-tree.actions.tree-modifiers.toggles").custom
+Api.tree.toggle_hidden_filter = require("nvim-tree.actions.tree-modifiers.toggles").dotfiles
+Api.tree.toggle_help = require("nvim-tree.actions.tree-modifiers.toggles").help
+
+Api.fs.create = inject_node(require("nvim-tree.actions.fs.create-file").fn)
+Api.fs.remove = inject_node(require("nvim-tree.actions.fs.remove-file").fn)
+Api.fs.trash = inject_node(require("nvim-tree.actions.fs.trash").fn)
+Api.fs.rename = inject_node(require("nvim-tree.actions.fs.rename-file").fn(false))
+Api.fs.rename_sub = inject_node(require("nvim-tree.actions.fs.rename-file").fn(true))
+Api.fs.copy = inject_node(require("nvim-tree.actions.fs.copy-paste").copy)
+Api.fs.cut = inject_node(require("nvim-tree.actions.fs.copy-paste").cut)
+Api.fs.paste = inject_node(require("nvim-tree.actions.fs.copy-paste").paste)
+Api.fs.print_clipboard = require("nvim-tree.actions.fs.copy-paste").print_clipboard
+Api.fs.copy.absolute_path = inject_node(require("nvim-tree.actions.fs.copy-paste").copy_absolute_path)
+Api.fs.copy.filename = inject_node(require("nvim-tree.actions.fs.copy-paste").copy_filename)
+Api.fs.copy.relative_path = inject_node(require("nvim-tree.actions.fs.copy-paste").copy_path)
+
+local function edit(mode, node)
+  local path = node.absolute_path
+  if node.link_to and not node.nodes then
+    path = node.link_to
+  end
+  require("nvim-tree.actions.node.open-file").fn(mode, path)
+end
+
+local function open_or_expand_or_dir_up(mode)
+  return function(node)
+    if node.name == ".." then
+      require("nvim-tree.actions.root.change-dir").fn ".."
+    elseif node.nodes then
+      require("nvim-tree.lib").expand_or_collapse(node)
+    else
+      edit(mode, node)
+    end
+  end
+end
+
+local function open_preview(node)
+  if node.nodes or node.name == ".." then
+    return
+  end
+
+  edit("preview", node)
+end
+
+Api.node.open.edit = inject_node(open_or_expand_or_dir_up "edit")
+Api.node.open.vertical = inject_node(open_or_expand_or_dir_up "vsplit")
+Api.node.open.horizontal = inject_node(open_or_expand_or_dir_up "split")
+Api.node.open.tab = inject_node(open_or_expand_or_dir_up "tabnew")
+Api.node.open.preview = inject_node(open_preview)
+
+Api.node.show_info_popup = inject_node(require("nvim-tree.actions.node.file-popup").toggle_file_info)
+Api.node.run.cmd = inject_node(require("nvim-tree.actions.node.run-command").run_file_command)
+Api.node.run.system = inject_node(require("nvim-tree.actions.node.system-open").fn)
+Api.node.navigate.sibling.next = inject_node(require("nvim-tree.actions.moves.sibling").fn "next")
+Api.node.navigate.sibling.prev = inject_node(require("nvim-tree.actions.moves.sibling").fn "prev")
+Api.node.navigate.sibling.first = inject_node(require("nvim-tree.actions.moves.sibling").fn "first")
+Api.node.navigate.sibling.last = inject_node(require("nvim-tree.actions.moves.sibling").fn "last")
+Api.node.navigate.parent = inject_node(require("nvim-tree.actions.moves.parent").fn(false))
+Api.node.navigate.parent_close = inject_node(require("nvim-tree.actions.moves.parent").fn(true))
+Api.node.navigate.git.next = inject_node(require("nvim-tree.actions.moves.item").fn("next", "git"))
+Api.node.navigate.git.prev = inject_node(require("nvim-tree.actions.moves.item").fn("prev", "git"))
+Api.node.navigate.diagnostics.next = inject_node(require("nvim-tree.actions.moves.item").fn("next", "diag"))
+Api.node.navigate.diagnostics.prev = inject_node(require("nvim-tree.actions.moves.item").fn("prev", "diag"))
+
+Api.git.reload = require("nvim-tree.actions.reloaders.reloaders").reload_git
+
+Api.events.subscribe = require("nvim-tree.events").subscribe
+Api.events.Event = require("nvim-tree.events").Event
+
+Api.live_filter.start = require("nvim-tree.live-filter").start_filtering
+Api.live_filter.clear = require("nvim-tree.live-filter").clear_filter
+
+Api.marks.get = inject_node(require("nvim-tree.marks").get_mark)
+Api.marks.list = require("nvim-tree.marks").get_marks
+Api.marks.toggle = inject_node(require("nvim-tree.marks").toggle_mark)
+Api.marks.bulk.move = require("nvim-tree.marks.bulk-move").bulk_move
+Api.marks.navigate.next = require("nvim-tree.marks.navigation").next
+Api.marks.navigate.prev = require("nvim-tree.marks.navigation").prev
+Api.marks.navigate.select = require("nvim-tree.marks.navigation").select
+
+return Api

lua/nvim-tree/events.lua

@@ -4,7 +4,7 @@ local M = {}
 
 local global_handlers = {}
 
-local Event = {
+M.Event = {
   Ready = "Ready",
   NodeRenamed = "NodeRenamed",
   TreeOpen = "TreeOpen",
@@ -20,7 +20,7 @@ local function get_handlers(event_name)
   return global_handlers[event_name] or {}
 end
 
-local function register_handler(event_name, handler)
+function M.subscribe(event_name, handler)
   local handlers = get_handlers(event_name)
   table.insert(handlers, handler)
   global_handlers[event_name] = handlers
@@ -37,107 +37,92 @@ end
 
 --@private
 function M._dispatch_ready()
-  dispatch(Event.Ready)
+  dispatch(M.Event.Ready)
 end
 
 --@private
 function M._dispatch_node_renamed(old_name, new_name)
-  dispatch(Event.NodeRenamed, { old_name = old_name, new_name = new_name })
+  dispatch(M.Event.NodeRenamed, { old_name = old_name, new_name = new_name })
 end
 
 --@private
 function M._dispatch_file_removed(fname)
-  dispatch(Event.FileRemoved, { fname = fname })
+  dispatch(M.Event.FileRemoved, { fname = fname })
 end
 
 --@private
 function M._dispatch_file_created(fname)
-  dispatch(Event.FileCreated, { fname = fname })
+  dispatch(M.Event.FileCreated, { fname = fname })
 end
 
 --@private
 function M._dispatch_folder_created(folder_name)
-  dispatch(Event.FolderCreated, { folder_name = folder_name })
+  dispatch(M.Event.FolderCreated, { folder_name = folder_name })
 end
 
 --@private
 function M._dispatch_folder_removed(folder_name)
-  dispatch(Event.FolderRemoved, { folder_name = folder_name })
+  dispatch(M.Event.FolderRemoved, { folder_name = folder_name })
 end
 
 --@private
 function M._dispatch_on_tree_open()
-  dispatch(Event.TreeOpen, nil)
+  dispatch(M.Event.TreeOpen, nil)
 end
 
 --@private
 function M._dispatch_on_tree_close()
-  dispatch(Event.TreeClose, nil)
+  dispatch(M.Event.TreeClose, nil)
 end
 
 --@private
 function M._dispatch_on_tree_resize(size)
-  dispatch(Event.Resize, size)
+  dispatch(M.Event.Resize, size)
 end
 
---Registers a handler for the Ready event.
+--- @deprecated
---@param handler (function) Handler with the signature `function()`
 function M.on_nvim_tree_ready(handler)
-  register_handler(Event.Ready, handler)
+  M.subscribe(M.Event.Ready, handler)
 end
 
---Registers a handler for the NodeRenamed event.
+--- @deprecated
---@param handler (function) Handler with the signature function(payload), where payload is a table containing:
---  - old_name (string) Absolute path to the old node location.
---  - new_name (string) Absolute path to the new node location.
 function M.on_node_renamed(handler)
-  register_handler(Event.NodeRenamed, handler)
+  M.subscribe(M.Event.NodeRenamed, handler)
 end
 
---Registers a handler for the FileCreated event.
+--- @deprecated
---@param handler (function) Handler with the signature function(payload), where payload is a table containing:
---  - fname (string) Absolute path to the created file.
 function M.on_file_created(handler)
-  register_handler(Event.FileCreated, handler)
+  M.subscribe(M.Event.FileCreated, handler)
 end
 
---Registers a handler for the FileRemoved event.
+--- @deprecated
---@param handler (function) Handler with the signature function(payload), where payload is a table containing:
---  - fname (string) Absolute path to the removed file.
 function M.on_file_removed(handler)
-  register_handler(Event.FileRemoved, handler)
+  M.subscribe(M.Event.FileRemoved, handler)
 end
 
---Registers a handler for the FolderCreated event.
+--- @deprecated
---@param handler (function) Handler with the signature function(payload), where payload is a table containing:
---  - folder_name (string) Absolute path to the created folder.
 function M.on_folder_created(handler)
-  register_handler(Event.FolderCreated, handler)
+  M.subscribe(M.Event.FolderCreated, handler)
 end
 
---Registers a handler for the FolderRemoved event.
+--- @deprecated
---@param handler (function) Handler with the signature function(payload), where payload is a table containing:
---  - folder_name (string) Absolute path to the removed folder.
 function M.on_folder_removed(handler)
-  register_handler(Event.FolderRemoved, handler)
+  M.subscribe(M.Event.FolderRemoved, handler)
 end
 
---Registers a handler for the TreeOpen event.
+--- @deprecated
---@param handler (function) Handler with the signature function(payload)
 function M.on_tree_open(handler)
-  register_handler(Event.TreeOpen, handler)
+  M.subscribe(M.Event.TreeOpen, handler)
 end
 
---Registers a handler for the TreeClose event.
+--- @deprecated
---@param handler (function) Handler with the signature function(payload)
 function M.on_tree_close(handler)
-  register_handler(Event.TreeClose, handler)
+  M.subscribe(M.Event.TreeClose, handler)
 end
 
---Registers a handler for the Resize event.
+--- @deprecated
---@param handler (function) Handler with the signature function(size)
 function M.on_tree_resize(handler)
-  register_handler(Event.Resize, handler)
+  M.subscribe(M.Event.Resize, handler)
 end
 
 return M