Skip to content

Commit 2061b93

Browse files
alex-courtisalex-courtis
committed
docs(#3088): extract api/tree.lua
1 parent de9c62c commit 2061b93

File tree

6 files changed

+234
-12
lines changed

6 files changed

+234
-12
lines changed

‎doc/nvim-tree-lua.txt‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3068,4 +3068,85 @@ Class: Config.Log *nvim-tree-config-log*
30683068

30693069

30703070

3071+
==============================================================================
3072+
Lua module: nvim_tree.api.tree *nvim-tree-api-tree*
3073+
3074+
focus() *nvim_tree.api.tree.focus()*
3075+
TODO #3088 descriptions are needed to properly format the functions
3076+
3077+
nvim_tree.api.tree.change_root() *nvim_tree.api.tree.change_root()*
3078+
3079+
*nvim_tree.api.tree.change_root_to_node()*
3080+
nvim_tree.api.tree.change_root_to_node()
3081+
3082+
*nvim_tree.api.tree.change_root_to_parent()*
3083+
nvim_tree.api.tree.change_root_to_parent()
3084+
3085+
nvim_tree.api.tree.close() *nvim_tree.api.tree.close()*
3086+
3087+
*nvim_tree.api.tree.close_in_all_tabs()*
3088+
nvim_tree.api.tree.close_in_all_tabs()
3089+
3090+
*nvim_tree.api.tree.close_in_this_tab()*
3091+
nvim_tree.api.tree.close_in_this_tab()
3092+
3093+
nvim_tree.api.tree.collapse_all() *nvim_tree.api.tree.collapse_all()*
3094+
3095+
nvim_tree.api.tree.expand_all() *nvim_tree.api.tree.expand_all()*
3096+
3097+
nvim_tree.api.tree.find_file() *nvim_tree.api.tree.find_file()*
3098+
3099+
*nvim_tree.api.tree.get_node_under_cursor()*
3100+
nvim_tree.api.tree.get_node_under_cursor()
3101+
3102+
nvim_tree.api.tree.get_nodes() *nvim_tree.api.tree.get_nodes()*
3103+
3104+
nvim_tree.api.tree.is_tree_buf() *nvim_tree.api.tree.is_tree_buf()*
3105+
3106+
nvim_tree.api.tree.is_visible() *nvim_tree.api.tree.is_visible()*
3107+
3108+
nvim_tree.api.tree.reload() *nvim_tree.api.tree.reload()*
3109+
3110+
nvim_tree.api.tree.resize() *nvim_tree.api.tree.resize()*
3111+
3112+
nvim_tree.api.tree.search_node() *nvim_tree.api.tree.search_node()*
3113+
3114+
nvim_tree.api.tree.toggle() *nvim_tree.api.tree.toggle()*
3115+
3116+
*nvim_tree.api.tree.toggle_custom_filter()*
3117+
nvim_tree.api.tree.toggle_custom_filter()
3118+
3119+
*nvim_tree.api.tree.toggle_enable_filters()*
3120+
nvim_tree.api.tree.toggle_enable_filters()
3121+
3122+
*nvim_tree.api.tree.toggle_git_clean_filter()*
3123+
nvim_tree.api.tree.toggle_git_clean_filter()
3124+
3125+
*nvim_tree.api.tree.toggle_gitignore_filter()*
3126+
nvim_tree.api.tree.toggle_gitignore_filter()
3127+
3128+
nvim_tree.api.tree.toggle_help() *nvim_tree.api.tree.toggle_help()*
3129+
3130+
*nvim_tree.api.tree.toggle_hidden_filter()*
3131+
nvim_tree.api.tree.toggle_hidden_filter()
3132+
3133+
*nvim_tree.api.tree.toggle_no_bookmark_filter()*
3134+
nvim_tree.api.tree.toggle_no_bookmark_filter()
3135+
3136+
*nvim_tree.api.tree.toggle_no_buffer_filter()*
3137+
nvim_tree.api.tree.toggle_no_buffer_filter()
3138+
3139+
nvim_tree.api.tree.winid() *nvim_tree.api.tree.winid()*
3140+
3141+
open({opts}) *nvim_tree.api.tree.open()*
3142+
3143+
Parameters: ~
3144+
• {opts} (`table?`) A table with the following fields:
3145+
• {path} (`string?`) path
3146+
• {current_window} (`boolean?`) default false
3147+
• {winid} (`number?`)
3148+
• {find_file} (`boolean?`) default false
3149+
• {update_root} (`boolean?`) default false
3150+
3151+
30713152
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

‎lua/nvim-tree.lua‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -793,6 +793,9 @@ function M.setup(conf)
793793

794794
vim.g.NvimTreeSetup = 1
795795
vim.api.nvim_exec_autocmds("User", { pattern = "NvimTreeSetup" })
796+
797+
-- TODO #3088 remove this bootstrap once api/init.lua replaces old api.lua
798+
require("nvim-tree.api.init")
796799
end
797800

798801
vim.g.NvimTreeRequired = 1

‎lua/nvim-tree/api.lua‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,9 @@ local function wrap_explorer_member(explorer_member, member_method)
123123
end)
124124
end
125125

126+
function Api.hydrate_tree(tree)
127+
Api.tree = tree
128+
126129
---@class ApiTreeOpenOpts
127130
---@field path string|nil path
128131
---@field current_window boolean|nil default false
@@ -220,6 +223,8 @@ Api.tree.is_visible = wrap(view.is_visible)
220223

221224
Api.tree.winid = wrap(view.winid)
222225

226+
end
227+
223228
Api.fs.create = wrap_node_or_nil(actions.fs.create_file.fn)
224229
Api.fs.remove = wrap_node(actions.fs.remove_file.fn)
225230
Api.fs.trash = wrap_node(actions.fs.trash.fn)

‎lua/nvim-tree/api/init.lua‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
return {
2+
tree = require("nvim-tree.api.tree")
3+
}

‎lua/nvim-tree/api/tree.lua‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---@meta
2+
local nvim_tree = { api = { tree = {} } }
3+
4+
---@class nvim_tree.api.tree.open.Opts
5+
---@inlinedoc
6+
---@field path string|nil path
7+
---@field current_window boolean|nil default false
8+
---@field winid number|nil
9+
---@field find_file boolean|nil default false
10+
---@field update_root boolean|nil default false
11+
12+
---@param opts? nvim_tree.api.tree.open.Opts
13+
function nvim_tree.api.tree.open(opts) end
14+
15+
---TODO #3088 descriptions are needed to properly format the functions
16+
function nvim_tree.api.tree.focus() end
17+
18+
---@class nvim_tree.api.tree.toggle.Opts
19+
---@inlinedoc
20+
---@field path string|nil
21+
---@field current_window boolean|nil default false
22+
---@field winid number|nil
23+
---@field find_file boolean|nil default false
24+
---@field update_root boolean|nil default false
25+
---@field focus boolean|nil default true
26+
27+
function nvim_tree.api.tree.toggle(opts) end
28+
29+
function nvim_tree.api.tree.close() end
30+
31+
function nvim_tree.api.tree.close_in_this_tab() end
32+
33+
function nvim_tree.api.tree.close_in_all_tabs() end
34+
35+
function nvim_tree.api.tree.reload() end
36+
37+
---@class nvim_tree.api.tree.resize.Opts
38+
---@inlinedoc
39+
---@field width string|function|number|table|nil
40+
---@field absolute number|nil
41+
---@field relative number|nil
42+
43+
function nvim_tree.api.tree.resize(opts) end
44+
45+
function nvim_tree.api.tree.change_root() end
46+
47+
function nvim_tree.api.tree.change_root_to_node() end
48+
49+
function nvim_tree.api.tree.change_root_to_parent() end
50+
51+
function nvim_tree.api.tree.get_node_under_cursor() end
52+
53+
function nvim_tree.api.tree.get_nodes() end
54+
55+
---@class nvim_tree.api.tree.find_file.Opts
56+
---@inlinedoc
57+
---@field buf string|number|nil
58+
---@field open boolean|nil default false
59+
---@field current_window boolean|nil default false
60+
---@field winid number|nil
61+
---@field update_root boolean|nil default false
62+
---@field focus boolean|nil default false
63+
64+
function nvim_tree.api.tree.find_file(opts) end
65+
66+
function nvim_tree.api.tree.search_node() end
67+
68+
---@class nvim_tree.api.tree.collapse.Opts
69+
---@inlinedoc
70+
---@field keep_buffers boolean|nil default false
71+
72+
function nvim_tree.api.tree.collapse_all(opts) end
73+
74+
---@class nvim_tree.api.tree.expand.Opts
75+
---@inlinedoc
76+
---@field expand_until (fun(expansion_count: integer, node: Node): boolean)|nil
77+
78+
function nvim_tree.api.tree.expand_all(opts) end
79+
80+
function nvim_tree.api.tree.toggle_enable_filters() end
81+
82+
function nvim_tree.api.tree.toggle_gitignore_filter() end
83+
84+
function nvim_tree.api.tree.toggle_git_clean_filter() end
85+
86+
function nvim_tree.api.tree.toggle_no_buffer_filter() end
87+
88+
function nvim_tree.api.tree.toggle_custom_filter() end
89+
90+
function nvim_tree.api.tree.toggle_hidden_filter() end
91+
92+
function nvim_tree.api.tree.toggle_no_bookmark_filter() end
93+
94+
function nvim_tree.api.tree.toggle_help() end
95+
96+
function nvim_tree.api.tree.is_tree_buf() end
97+
98+
---@class nvim_tree.api.tree.is_visible.Opts
99+
---@inlinedoc
100+
---@field tabpage number|nil
101+
---@field any_tabpage boolean|nil default false
102+
103+
function nvim_tree.api.tree.is_visible(opts) end
104+
105+
---@class nvim_tree.api.tree.winid.Opts
106+
---@inlinedoc
107+
---@field tabpage number|nil default nil
108+
109+
function nvim_tree.api.tree.winid(opts) end
110+
111+
require("nvim-tree.api").hydrate_tree(nvim_tree.api.tree)
112+
113+
return nvim_tree.api.tree

‎scripts/gen_vimdoc_config.lua‎

Lines changed: 29 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ local modules = {
3030
{ helptag = "nvim-tree-config-ui", title = "Class: Config.UI", path = "./lua/nvim_tree/_meta/config/ui.lua", name = "UI", },
3131
{ helptag = "nvim-tree-config-experimental", title = "Class: Config.Experimental", path = "./lua/nvim_tree/_meta/config/experimental.lua", },
3232
{ helptag = "nvim-tree-config-log", title = "Class: Config.Log", path = "./lua/nvim_tree/_meta/config/log.lua", },
33+
34+
{ helptag = "nvim-tree-api-tree", title = "Lua module: nvim_tree.api.tree", path = "./lua/nvim_tree/api/tree.lua", },
3335
}
3436

3537
-- hydrate file names
@@ -59,26 +61,41 @@ local config = {
5961
files = vim.tbl_map(function(m) return m.path end, modules),
6062

6163
section_fmt = function(name)
64+
print(string.format("section_fmt name=%s", name))
6265
return modules_by_name[name] and modules_by_name[name].title or error(string.format("unknown module %s passed to section_fmt", name))
6366
end,
6467

6568
helptag_fmt = function(name)
69+
print(string.format("helptag_fmt name=%s", name))
6670
return modules_by_name[name] and modules_by_name[name].helptag or error(string.format("unknown module %s passed to helptag_fmt", name))
6771
end,
6872

69-
-- class/function's help tag
70-
fn_helptag_fmt = function(fun)
71-
-- Modified copy of fn_helptag_fmt_common
72-
-- Uses fully qualified class name in the tag for methods.
73-
-- The module is used everywhere else, however not available for classes.
74-
local fn_sfx = fun.table and "" or "()"
75-
if fun.classvar then
76-
return string.format("%s:%s%s", fun.class or fun.classvar, fun.name, fn_sfx)
77-
end
78-
if fun.module then
79-
return string.format("%s.%s%s", fun.module, fun.name, fn_sfx)
73+
-- optional, no default xform
74+
fn_xform = function(fun)
75+
print(string.format("fn_xform fun=%s", vim.inspect(fun)))
76+
77+
if (fun.module) then
78+
-- generator doesn't strip meta
79+
-- also cascades into fn_helptag_fmt
80+
local module = fun.module:gsub("._meta", "", 1)
81+
82+
if module ~= fun.module then
83+
error("unexpected _meta in module")
84+
print(string.format("fn_xform module: %s -> %s", fun.module, module))
85+
end
86+
87+
-- remove the API prefix from the left aligned function name
88+
-- this will cascade into fn_helptag_fmt, which will apply the module prefix anyway
89+
local name, replaced = fun.name:gsub("^" .. module .. "%.", "", 1)
90+
if (replaced ~= 1) then
91+
error(string.format("function name does not start with module: %s", vim.inspect(fun)))
92+
end
93+
94+
print(string.format("fn_xform name: %s -> %s", fun.name, name))
95+
96+
fun.module = module
97+
fun.name = name
8098
end
81-
return fun.name .. fn_sfx
8299
end,
83100
}
84101
}

0 commit comments

Comments
 (0)