Skip to content

Commit d0aa124

Browse files
kyazdani42kyazdani42
committed
feat(api): add public API module
1 parent 06e48c2 commit d0aa124

File tree

4 files changed

+269
-45
lines changed

4 files changed

+269
-45
lines changed

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,10 @@ Basic commands:
9898

9999
`:NvimTreeCollapse` Collapses the nvim-tree recursively.
100100

101+
## Api
102+
103+
nvim-tree exposes a public api; see [:help nvim-tree-api](doc/nvim-tree-lua.txt). This is a stable non breaking api.
104+
101105
## Mappings
102106

103107
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‎

Lines changed: 133 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,12 @@ CONTENTS *nvim-tree*
1010
3. Commands |nvim-tree-commands|
1111
4. Setup/Configuration |nvim-tree-setup|
1212
4.1 Vinegar Style |nvim-tree-vinegar|
13-
5. Mappings |nvim-tree-mappings|
14-
6. Highlight Groups |nvim-tree-highlight|
15-
7. Events |nvim-tree-events|
16-
7.1 Available Events |nvim-tree.events|
17-
8. Bookmarks |nvim-tree-bookmarks|
13+
5. Api |nvim-tree-api|
14+
6. Mappings |nvim-tree-mappings|
15+
7. Highlight Groups |nvim-tree-highlight|
16+
8. Events |nvim-tree-events|
17+
8.1 Available Events |nvim-tree.events|
18+
9. Bookmarks |nvim-tree-bookmarks|
1819

1920
==============================================================================
2021
1. INTRODUCTION *nvim-tree-introduction*
@@ -951,7 +952,97 @@ You'll also need to set |nvim-tree.hijack_netrw| to `true` during setup.
951952
A good functionnality to enable is |nvim-tree.hijack_directories|.
952953

953954
==============================================================================
954-
5. MAPPINGS *nvim-tree-mappings*
955+
5. API *nvim-tree-api*
956+
957+
Nvim-tree's public API can be used to access features.
958+
>
959+
local nt_api = require("nvim-tree.api")
960+
<
961+
This module exposes stable functionalities, it is advised to use this in order
962+
to avoid breaking configurations due to internal breaking changes.
963+
964+
The api is separated in multiple modules, which can be accessed with
965+
`require("nvim-tree.api").moduleName.functionality`.
966+
967+
Functions that needs a tree node parameter are exposed with an abstraction
968+
that injects the node from the cursor position in the tree when calling
969+
the function. It will use the node you pass as an argument in priority if it
970+
exists.
971+
972+
- api.tree: *nvim-tree.api.tree*
973+
- open `(path?: string)`
974+
- close
975+
- toggle `(find_file?: bool, no_focus?: bool, path?: string)`
976+
- focus
977+
- reload
978+
- change_root `(path: string)`
979+
- change_root_to_parent
980+
- get_node_under_cursor
981+
- find_file `(filename: string)`
982+
- search_node
983+
- collapse_all `(keep_buffers?: bool)`
984+
- expand_all
985+
- toggle_gitignore_filter
986+
- toggle_custom_filter
987+
- toggle_hidden_filter
988+
- toggle_help
989+
990+
- api.fs: *nvim-tree.api.fs*
991+
- create
992+
- remove
993+
- trash
994+
- rename
995+
- rename_sub
996+
- copy
997+
- cut
998+
- paste
999+
- print_clipboard
1000+
- copy.absolute_path
1001+
- copy.filename
1002+
- copy.relative_path
1003+
1004+
- api.node: *nvim-tree.api.node*
1005+
- open.edit
1006+
- open.vertical
1007+
- open.horizontal
1008+
- open.tab
1009+
- open.preview
1010+
- show_info_popup
1011+
- run.cmd
1012+
- run.system
1013+
- navigate.sibling.next
1014+
- navigate.sibling.prev
1015+
- navigate.sibling.first
1016+
- navigate.sibling.last
1017+
- navigate.parent
1018+
- navigate.parent_close
1019+
- navigate.git.next
1020+
- navigate.git.prev
1021+
- navigate.diagnostics.next
1022+
- navigate.diagnostics.prev
1023+
1024+
- api.git: *nvim-tree.api.git*
1025+
- reload
1026+
1027+
- api.events: *nvim-tree.api.events*
1028+
- subscribe `(eventType: Event, callback: function(...args))`
1029+
- Event (its an enum type, please see |nvim_tree_events_kind|)
1030+
1031+
- api.live_filter: *nvim-tree.api.live_filter*
1032+
- start
1033+
- clear
1034+
1035+
- api.marks: *nvim-tree.api.marks*
1036+
- get
1037+
- list
1038+
- toggle
1039+
- bulk.move
1040+
- navigate.next
1041+
- navigate.prev
1042+
- navigate.select
1043+
1044+
==============================================================================
1045+
6. MAPPINGS *nvim-tree-mappings*
9551046

9561047
The `list` option in `view.mappings.list` is a table of
9571048

@@ -1078,7 +1169,7 @@ DEFAULT MAPPINGS *nvim-tree-default-mappings
10781169
} -- END_DEFAULT_MAPPINGS
10791170
<
10801171
==============================================================================
1081-
6. HIGHLIGHT GROUPS *nvim-tree-highlight*
1172+
7. HIGHLIGHT GROUPS *nvim-tree-highlight*
10821173

10831174
All the following highlight groups can be configured by hand. Aside from
10841175
`NvimTreeWindowPicker`, it is not advised to colorize the background of these
@@ -1152,35 +1243,52 @@ NvimTreeBookmark
11521243

11531244

11541245
==============================================================================
1155-
7. EVENTS *nvim-tree-events*
1246+
8. EVENTS *nvim-tree-events*
11561247

11571248
|nvim_tree_events|
11581249

11591250
nvim-tree will dispatch events whenever an action is made. These events can be
11601251
subscribed to through handler functions. This allows for even further
11611252
customization of nvim-tree.
11621253

1163-
A handler for an event is just a function which receives one argument -
1164-
the payload of the event. The payload is different for each event type. Refer
1254+
A handler for an event is just a function which receives one argument, the
1255+
payload of the event. The payload is different for each event type. Refer
11651256
to |nvim_tree_registering_handlers| for more information.
1166-
<
11671257

11681258
|nvim_tree_registering_handlers|
11691259

1170-
Handlers are registered by calling the `on_*` functions available in the
1171-
`require('nvim-tree.events')` module. See |nvim-tree.events|.
1172-
1260+
Handlers are registered by calling the `events.subscribe` function available in the
1261+
`require("nvim-tree.api")` module.
11731262

1174-
For example, registering a handler for when a node is renamed is done like this: >
1175-
1176-
local events = require('nvim-tree.events')
1263+
For example, registering a handler for when a node is renamed is done like this:
1264+
>
1265+
local api = require('nvim-tree.api')
11771266
1178-
events.on_node_renamed(function(data)
1267+
api.events.subscribe(Event.NodeRenamed, function(data)
11791268
print("Node renamed from " .. data.old_name .. " to " .. data.new_name)
11801269
end)
1270+
<
1271+
1272+
|nvim_tree_events_kind|
1273+
1274+
You can access the event enum with:
1275+
>
1276+
local Event = require('nvim-tree.api').events.Event
1277+
<
1278+
Here is the list of available variant of this enum:
1279+
1280+
- Event.Ready
1281+
- Event.NodeRenamed
1282+
- Event.TreeOpen
1283+
- Event.TreeClose
1284+
- Event.FileCreated
1285+
- Event.FileRemoved
1286+
- Event.FolderCreated
1287+
- Event.FolderRemoved
1288+
- Event.Resize
11811289

11821290
==============================================================================
1183-
7.1 Lua module: nvim-tree.events *nvim-tree.events*
1291+
8.1 Lua module: nvim-tree.events *nvim-tree.events*
11841292

11851293
*nvim-tree.events.on_nvim_tree_ready()*
11861294
on_nvim_tree_ready({handler})
@@ -1267,14 +1375,14 @@ on_tree_resize({handler})
12671375
signature `function(size)`.
12681376

12691377
==============================================================================
1270-
8. BOOKMARKS *nvim-tree-bookmarks*
1378+
9. BOOKMARKS *nvim-tree-bookmarks*
12711379

12721380
You can toggle marks on files/folders with
1273-
`require("nvim-tree.marks").toggle_mark(node)` which is bound to `m` by
1381+
`require("nvim-tree.api").marks.toggle(node)` which is bound to `m` by
12741382
default.
12751383

12761384
To get the list of marked paths, you can call
1277-
`require("nvim-tree.marks").get_marks()`. This will return `{node}`.
1385+
`require("nvim-tree.api").marks.list()`. This will return `{node}`.
12781386

12791387
*nvim-tree.bookmarks.navigation*
12801388

@@ -1284,8 +1392,8 @@ want to focus the tree view each time we wish to switch to another mark.
12841392
This requires binding bookmark navigation yourself.
12851393

12861394
-- in your lua configuration
1287-
vim.keymap.set("n", "<leader>mn", require("nvim-tree.marks.navigation").next)
1288-
vim.keymap.set("n", "<leader>mp", require("nvim-tree.marks.navigation").prev)
1289-
vim.keymap.set("n", "<leader>ms", require("nvim-tree.marks.navigation").select)
1395+
vim.keymap.set("n", "<leader>mn", require("nvim-tree.api").marks.navigate.next)
1396+
vim.keymap.set("n", "<leader>mp", require("nvim-tree.api").marks.navigate.prev)
1397+
vim.keymap.set("n", "<leader>ms", require("nvim-tree.api").marks.navigate.select)
12901398

12911399
vim:tw=78:ts=4:sw=4:et:ft=help:norl:

‎lua/nvim-tree/api.lua‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
local Api = {
2+
tree = {},
3+
node = { navigate = { sibling = {}, git = {}, diagnostics = {} }, run = {}, open = {} },
4+
events = {},
5+
marks = { bulk = {}, navigate = {} },
6+
fs = { copy = {} },
7+
git = {},
8+
live_filter = {},
9+
}
10+
11+
local function inject_node(f)
12+
return function(node)
13+
node = node or require("nvim-tree.lib").get_node_at_cursor()
14+
f(node)
15+
end
16+
end
17+
18+
Api.tree.open = require("nvim-tree").open
19+
Api.tree.toggle = require("nvim-tree").toggle
20+
Api.tree.close = require("nvim-tree.view").close
21+
Api.tree.focus = require("nvim-tree").focus
22+
Api.tree.reload = require("nvim-tree.actions.reloaders.reloaders").reload_explorer
23+
Api.tree.change_root = require("nvim-tree").change_dir
24+
Api.tree.change_root_to_parent = inject_node(require("nvim-tree.actions.root.dir-up").fn)
25+
Api.tree.get_node_under_cursor = require("nvim-tree.lib").get_node_at_cursor
26+
Api.tree.find_file = require("nvim-tree.actions.finders.find-file").fn
27+
Api.tree.search_node = require("nvim-tree.actions.finders.search-node").fn
28+
Api.tree.collapse_all = require("nvim-tree.actions.tree-modifiers.collapse-all").fn
29+
Api.tree.expand_all = inject_node(require("nvim-tree.actions.tree-modifiers.expand-all").fn)
30+
Api.tree.toggle_gitignore_filter = require("nvim-tree.actions.tree-modifiers.toggles").git_ignored
31+
Api.tree.toggle_custom_filter = require("nvim-tree.actions.tree-modifiers.toggles").custom
32+
Api.tree.toggle_hidden_filter = require("nvim-tree.actions.tree-modifiers.toggles").dotfiles
33+
Api.tree.toggle_help = require("nvim-tree.actions.tree-modifiers.toggles").help
34+
35+
Api.fs.create = inject_node(require("nvim-tree.actions.fs.create-file").fn)
36+
Api.fs.remove = inject_node(require("nvim-tree.actions.fs.remove-file").fn)
37+
Api.fs.trash = inject_node(require("nvim-tree.actions.fs.trash").fn)
38+
Api.fs.rename = inject_node(require("nvim-tree.actions.fs.rename-file").fn(false))
39+
Api.fs.rename_sub = inject_node(require("nvim-tree.actions.fs.rename-file").fn(true))
40+
Api.fs.copy = inject_node(require("nvim-tree.actions.fs.copy-paste").copy)
41+
Api.fs.cut = inject_node(require("nvim-tree.actions.fs.copy-paste").cut)
42+
Api.fs.paste = inject_node(require("nvim-tree.actions.fs.copy-paste").paste)
43+
Api.fs.print_clipboard = require("nvim-tree.actions.fs.copy-paste").print_clipboard
44+
Api.fs.copy.absolute_path = inject_node(require("nvim-tree.actions.fs.copy-paste").copy_absolute_path)
45+
Api.fs.copy.filename = inject_node(require("nvim-tree.actions.fs.copy-paste").copy_filename)
46+
Api.fs.copy.relative_path = inject_node(require("nvim-tree.actions.fs.copy-paste").copy_path)
47+
48+
local function edit(mode, node)
49+
local path = node.absolute_path
50+
if node.link_to and not node.nodes then
51+
path = node.link_to
52+
end
53+
require("nvim-tree.actions.node.open-file").fn(mode, path)
54+
end
55+
56+
local function open_or_expand_or_dir_up(mode)
57+
return function(node)
58+
if node.name == ".." then
59+
require("nvim-tree.actions.root.change-dir").fn ".."
60+
elseif node.nodes then
61+
require("nvim-tree.lib").expand_or_collapse(node)
62+
else
63+
edit(mode, node)
64+
end
65+
end
66+
end
67+
68+
local function open_preview(node)
69+
if node.nodes or node.name == ".." then
70+
return
71+
end
72+
73+
edit("preview", node)
74+
end
75+
76+
Api.node.open.edit = inject_node(open_or_expand_or_dir_up "edit")
77+
Api.node.open.vertical = inject_node(open_or_expand_or_dir_up "vsplit")
78+
Api.node.open.horizontal = inject_node(open_or_expand_or_dir_up "split")
79+
Api.node.open.tab = inject_node(open_or_expand_or_dir_up "tabnew")
80+
Api.node.open.preview = inject_node(open_preview)
81+
82+
Api.node.show_info_popup = inject_node(require("nvim-tree.actions.node.file-popup").toggle_file_info)
83+
Api.node.run.cmd = inject_node(require("nvim-tree.actions.node.run-command").run_file_command)
84+
Api.node.run.system = inject_node(require("nvim-tree.actions.node.system-open").fn)
85+
Api.node.navigate.sibling.next = inject_node(require("nvim-tree.actions.moves.sibling").fn "next")
86+
Api.node.navigate.sibling.prev = inject_node(require("nvim-tree.actions.moves.sibling").fn "prev")
87+
Api.node.navigate.sibling.first = inject_node(require("nvim-tree.actions.moves.sibling").fn "first")
88+
Api.node.navigate.sibling.last = inject_node(require("nvim-tree.actions.moves.sibling").fn "last")
89+
Api.node.navigate.parent = inject_node(require("nvim-tree.actions.moves.parent").fn(false))
90+
Api.node.navigate.parent_close = inject_node(require("nvim-tree.actions.moves.parent").fn(true))
91+
Api.node.navigate.git.next = inject_node(require("nvim-tree.actions.moves.item").fn("next", "git"))
92+
Api.node.navigate.git.prev = inject_node(require("nvim-tree.actions.moves.item").fn("prev", "git"))
93+
Api.node.navigate.diagnostics.next = inject_node(require("nvim-tree.actions.moves.item").fn("next", "diag"))
94+
Api.node.navigate.diagnostics.prev = inject_node(require("nvim-tree.actions.moves.item").fn("prev", "diag"))
95+
96+
Api.git.reload = require("nvim-tree.actions.reloaders.reloaders").reload_git
97+
98+
Api.events.subscribe = require("nvim-tree.events").subscribe
99+
Api.events.Event = require("nvim-tree.events").Event
100+
101+
Api.live_filter.start = require("nvim-tree.live-filter").start_filtering
102+
Api.live_filter.clear = require("nvim-tree.live-filter").clear_filter
103+
104+
Api.marks.get = inject_node(require("nvim-tree.marks").get_mark)
105+
Api.marks.list = require("nvim-tree.marks").get_marks
106+
Api.marks.toggle = inject_node(require("nvim-tree.marks").toggle_mark)
107+
Api.marks.bulk.move = require("nvim-tree.marks.bulk-move").bulk_move
108+
Api.marks.navigate.next = require("nvim-tree.marks.navigation").next
109+
Api.marks.navigate.prev = require("nvim-tree.marks.navigation").prev
110+
Api.marks.navigate.select = require("nvim-tree.marks.navigation").select
111+
112+
return Api

0 commit comments

Comments
 (0)