Skip to content

Commit 0f2c9a3

Browse files
kyazdani42kyazdani42
authored
feat(api): add public API module (nvim-tree#1432)
1 parent 9aa78d8 commit 0f2c9a3

File tree

4 files changed

+289
-140
lines changed

4 files changed

+289
-140
lines changed

‎README.md

+4
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

+144-96
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,11 @@ 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+
9. Bookmarks |nvim-tree-bookmarks|
1818

1919
==============================================================================
2020
1. INTRODUCTION *nvim-tree-introduction*
@@ -949,7 +949,99 @@ You'll also need to set |nvim-tree.hijack_netrw| to `true` during setup.
949949
A good functionnality to enable is |nvim-tree.hijack_directories|.
950950

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

9541046
The `list` option in `view.mappings.list` is a table of
9551047

@@ -1076,7 +1168,7 @@ DEFAULT MAPPINGS *nvim-tree-default-mappings
10761168
} -- END_DEFAULT_MAPPINGS
10771169
<
10781170
==============================================================================
1079-
6. HIGHLIGHT GROUPS *nvim-tree-highlight*
1171+
7. HIGHLIGHT GROUPS *nvim-tree-highlight*
10801172

10811173
All the following highlight groups can be configured by hand. Aside from
10821174
`NvimTreeWindowPicker`, it is not advised to colorize the background of these
@@ -1150,129 +1242,85 @@ NvimTreeBookmark
11501242

11511243

11521244
==============================================================================
1153-
7. EVENTS *nvim-tree-events*
1245+
8. EVENTS *nvim-tree-events*
11541246

11551247
|nvim_tree_events|
11561248

11571249
nvim-tree will dispatch events whenever an action is made. These events can be
11581250
subscribed to through handler functions. This allows for even further
11591251
customization of nvim-tree.
11601252

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

11661257
|nvim_tree_registering_handlers|
11671258

1168-
Handlers are registered by calling the `on_*` functions available in the
1169-
`require('nvim-tree.events')` module. See |nvim-tree.events|.
1259+
Handlers are registered by calling the `events.subscribe` function available in the
1260+
`require("nvim-tree.api")` module.
11701261

1262+
For example, registering a handler for when a node is renamed is done like this:
1263+
>
1264+
local api = require('nvim-tree.api')
11711265
1172-
For example, registering a handler for when a node is renamed is done like this: >
1173-
1174-
local events = require('nvim-tree.events')
1175-
1176-
events.on_node_renamed(function(data)
1266+
api.events.subscribe(Event.NodeRenamed, function(data)
11771267
print("Node renamed from " .. data.old_name .. " to " .. data.new_name)
11781268
end)
1269+
<
11791270

1180-
==============================================================================
1181-
7.1 Lua module: nvim-tree.events *nvim-tree.events*
1271+
|nvim_tree_events_kind|
1272+
1273+
You can access the event enum with:
1274+
>
1275+
local Event = require('nvim-tree.api').events.Event
1276+
<
1277+
Here is the list of available variant of this enum:
11821278

1183-
*nvim-tree.events.on_nvim_tree_ready()*
1184-
on_nvim_tree_ready({handler})
1185-
Registers a handler for when NvimTree has been initialized.
1279+
- Event.Ready
1280+
When NvimTree has been initialized
1281+
• Note: Handler takes no parameter.
11861282

1187-
Parameters: ~
1188-
{handler} `{function}` Handler function, with the
1189-
signature `function()`.
1283+
- Event.TreeOpen
1284+
• Note: Handler takes no parameter.
11901285

1191-
*nvim-tree.events.on_node_renamed()*
1192-
on_node_renamed({handler})
1193-
Registers a handler for when a node is renamed.
1194-
• Note: A node can either be a file or a directory.
1286+
- Event.TreeClose
1287+
• Note: Handler takes no parameter.
11951288

1196-
Parameters: ~
1197-
{handler} `{function}` Handler function, with the
1198-
signature `function(payload)`.
1199-
payload: ~
1289+
- Event.Resize - When NvimTree is resized.
1290+
handler parameters: ~
1291+
size: `number` size of the view in columns.
1292+
1293+
- Event.NodeRenamed
1294+
• Note: A node can either be a file or a directory.
1295+
handler parameters: ~
12001296
{old_name} `{string}` Absolute path to the old node location.
12011297
{new_name} `{string}` Absolute path to the new node location.
12021298

1203-
*nvim-tree.events.on_file_created()*
1204-
on_file_created({handler})
1205-
Registers a handler for when a file is created.
1206-
1207-
Parameters: ~
1208-
{handler} `{function}` Handler function, with the
1209-
signature `function(payload)`.
1210-
payload: ~
1299+
- Event.FileCreated
1300+
handler parameters: ~
12111301
{fname} `{string}` Absolute path to the created file
12121302

1213-
*nvim-tree.events.on_file_removed()*
1214-
on_file_removed({handler})
1215-
Registers a handler for when a file is removed.
1216-
1217-
Parameters: ~
1218-
{handler} `{function}` Handler function, with the
1219-
signature `function(payload)`.
1220-
payload: ~
1303+
- Event.FileRemoved
1304+
handler parameters: ~
12211305
{fname} `{string}` Absolute path to the removed file.
12221306

1223-
*nvim-tree.events.on_folder_created()*
1224-
on_folder_created({handler})
1225-
Registers a handler for when a folder is created.
1226-
1227-
Parameters: ~
1228-
{handler} `{function}` Handler function, with the
1229-
signature `function(payload)`.
1230-
payload: ~
1307+
- Event.FolderCreated
1308+
handler parameters: ~
12311309
{folder_name} `{string}` Absolute path to the created folder.
12321310

1233-
*nvim-tree.events.on_folder_removed()*
1234-
on_folder_removed({handler})
1235-
Registers a handler for when a folder is removed.
1236-
1237-
Parameters: ~
1238-
{handler} `{function}` Handler function, with the
1239-
signature `function(payload)`.
1240-
payload: ~
1311+
- Event.FolderRemoved
1312+
handler parameters: ~
12411313
{folder_name} `{string}` Absolute path to the removed folder.
12421314

1243-
*nvim-tree.events.on_tree_open()*
1244-
on_tree_open({handler})
1245-
Registers a handler for when NvimTree is opened.
1246-
1247-
Parameters: ~
1248-
{handler} `{function}` Handler function, with the
1249-
signature `function()`.
1250-
1251-
*nvim-tree.events.on_tree_close()*
1252-
on_tree_close({handler})
1253-
Registers a handler for when NvimTree is closed.
1254-
1255-
Parameters: ~
1256-
{handler} `{function}` Handler function, with the
1257-
signature `function()`.
1258-
1259-
*nvim-tree.events.on_tree_resize()*
1260-
on_tree_resize({handler})
1261-
Registers a handler for when NvimTree is resized.
1262-
1263-
Parameters: ~
1264-
{handler} `{function}` Handler function, with the
1265-
signature `function(size)`.
1266-
12671315
==============================================================================
1268-
8. BOOKMARKS *nvim-tree-bookmarks*
1316+
9. BOOKMARKS *nvim-tree-bookmarks*
12691317

12701318
You can toggle marks on files/folders with
1271-
`require("nvim-tree.marks").toggle_mark(node)` which is bound to `m` by
1319+
`require("nvim-tree.api").marks.toggle(node)` which is bound to `m` by
12721320
default.
12731321

12741322
To get the list of marked paths, you can call
1275-
`require("nvim-tree.marks").get_marks()`. This will return `{node}`.
1323+
`require("nvim-tree.api").marks.list()`. This will return `{node}`.
12761324

12771325
*nvim-tree.bookmarks.navigation*
12781326

@@ -1282,8 +1330,8 @@ want to focus the tree view each time we wish to switch to another mark.
12821330
This requires binding bookmark navigation yourself.
12831331

12841332
-- in your lua configuration
1285-
vim.keymap.set("n", "<leader>mn", require("nvim-tree.marks.navigation").next)
1286-
vim.keymap.set("n", "<leader>mp", require("nvim-tree.marks.navigation").prev)
1287-
vim.keymap.set("n", "<leader>ms", require("nvim-tree.marks.navigation").select)
1333+
vim.keymap.set("n", "<leader>mn", require("nvim-tree.api").marks.navigate.next)
1334+
vim.keymap.set("n", "<leader>mp", require("nvim-tree.api").marks.navigate.prev)
1335+
vim.keymap.set("n", "<leader>ms", require("nvim-tree.api").marks.navigate.select)
12881336

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

0 commit comments

Comments
 (0)