|
| 1 | +---@meta |
| 2 | +error("Cannot require a meta file") |
| 3 | + |
| 4 | +---@brief |
| 5 | +---nvim-tree exposes a public API. This is non breaking, with additions made as necessary. |
| 6 | +--- |
| 7 | +---Please do not require or use modules other than `nvim-tree.api`, as internal modules will change without notice. |
| 8 | +--- |
| 9 | +---The API is separated into multiple modules: |
| 10 | +--- |
| 11 | +---- [nvim-tree-api-commands] |
| 12 | +---- [nvim-tree-api-events] |
| 13 | +---- [nvim-tree-api-filter] |
| 14 | +---- [nvim-tree-api-fs] |
| 15 | +---- [nvim-tree-api-health] |
| 16 | +---- [nvim-tree-api-map] |
| 17 | +---- [nvim-tree-api-marks] |
| 18 | +---- [nvim-tree-api-node] |
| 19 | +---- [nvim-tree-api-tree] |
| 20 | +--- |
| 21 | +---Modules are accessed via `api.<module>.<function>` |
| 22 | +--- |
| 23 | +---Example invocation of the `reload` function in the `tree` module: |
| 24 | +---```lua |
| 25 | +--- |
| 26 | +---local api = require("nvim-tree.api") |
| 27 | +---api.tree.reload() |
| 28 | +---``` |
| 29 | +---Generally, functions accepting a [nvim_tree.api.Node] as their first argument will use the node under the cursor when that argument is not present or nil. e.g. the following are functionally identical: |
| 30 | +---```lua |
| 31 | +--- |
| 32 | +---api.node.open.edit(nil, { focus = true }) |
| 33 | +--- |
| 34 | +---api.node.open.edit(api.tree.get_node_under_cursor(), { focus = true }) |
| 35 | +---``` |
| 36 | + |
| 37 | + |
| 38 | +---The Node class is a data class. Instances may be provided by API functions for use as a: |
| 39 | +---- handle to pass back to API functions e.g. [nvim_tree.api.node.run.cmd()] |
| 40 | +---- reference in callbacks e.g. [nvim_tree.config.sort.Sorter] {sorter} |
| 41 | +--- |
| 42 | +---Please do not mutate the contents of any Node object. |
| 43 | +--- |
| 44 | +---@class nvim_tree.api.Node |
| 45 | +---@field absolute_path string of the file or directory |
| 46 | +---@field name string file or directory name |
| 47 | +---@field parent? nvim_tree.api.DirectoryNode parent directory, nil for root |
| 48 | +---@field type "file" | "directory" | "link" [uv.fs_stat()] {type} |
| 49 | +---@field executable boolean file is executable |
| 50 | +---@field fs_stat? uv.fs_stat.result at time of last tree display, see [uv.fs_stat()] |
| 51 | +---@field git_status nvim_tree.git.Status? for files and directories |
| 52 | +---@field diag_severity? lsp.DiagnosticSeverity diagnostic status |
| 53 | +---@field hidden boolean node is not visible in the tree |
| 54 | + |
| 55 | + |
| 56 | +--- |
| 57 | +---Git statuses for a single node. |
| 58 | +--- |
| 59 | +---`nvim_tree.git.XY`: 2 character string, see `man 1 git-status` "Short Format" |
| 60 | +---@alias nvim_tree.git.XY string |
| 61 | +--- |
| 62 | +---{dir} status is derived from its contents: |
| 63 | +---- `direct`: inherited from child files |
| 64 | +---- `indirect`: inherited from child directories |
| 65 | +--- |
| 66 | +---@class nvim_tree.git.Status |
| 67 | +---@field file? nvim_tree.git.XY status of a file node |
| 68 | +---@field dir? table<"direct" | "indirect", nvim_tree.git.XY[]> direct inclusive-or indirect status |
| 69 | + |
| 70 | + |
| 71 | + |
| 72 | + |
| 73 | +-- Following are exact as that prevents them from having documentation generated. |
| 74 | +-- They are not ready for public exposure as: |
| 75 | +-- - They are not classic classes |
| 76 | +-- - They are only used in a few locations: api.tree.get_nodes and UserDecorator |
| 77 | + |
| 78 | +--- |
| 79 | +---File |
| 80 | +--- |
| 81 | +---@class (exact) nvim_tree.api.FileNode: nvim_tree.api.Node |
| 82 | +---@field extension string |
| 83 | + |
| 84 | +--- |
| 85 | +---Directory |
| 86 | +--- |
| 87 | +---@class (exact) nvim_tree.api.DirectoryNode: nvim_tree.api.Node |
| 88 | +---@field has_children boolean |
| 89 | +---@field nodes nvim_tree.api.Node[] |
| 90 | +---@field open boolean |
| 91 | + |
| 92 | +--- |
| 93 | +---Root Directory |
| 94 | +--- |
| 95 | +---@class (exact) nvim_tree.api.RootNode: nvim_tree.api.DirectoryNode |
| 96 | + |
| 97 | +--- |
| 98 | +---Link mixin |
| 99 | +--- |
| 100 | +---@class (exact) nvim_tree.api.LinkNode |
| 101 | +---@field link_to string |
| 102 | +---@field fs_stat_target uv.fs_stat.result |
| 103 | + |
| 104 | +--- |
| 105 | +---File Link |
| 106 | +--- |
| 107 | +---@class (exact) nvim_tree.api.FileLinkNode: nvim_tree.api.FileNode, nvim_tree.api.LinkNode |
| 108 | + |
| 109 | +--- |
| 110 | +---DirectoryLink |
| 111 | +--- |
| 112 | +---@class (exact) nvim_tree.api.DirectoryLinkNode: nvim_tree.api.DirectoryNode, nvim_tree.api.LinkNode |
0 commit comments