mirror of
https://github.com/neovim/neovim.git
synced 2025-09-06 03:18:16 +00:00
feat(docs): generate builtin.txt (#24493)
- eval.lua is now the source of truth. - Formatting is much more consistent. - Fixed Lua type generation for polymorphic functions (get(), etc). - Removed "Overview" section from builtin.txt - Can generate this if we really want it. - Moved functions from sign.txt and testing.txt into builtin.txt. - Removed the *timer* *timers* tags since libuv timers via vim.uv should be preferred. - Removed the temp-file-name tag from tempname() - Moved lueval() from lua.txt to builtin.txt. * Fix indent * fixup! * fixup! fixup! * fixup! better tag formatting * fixup: revert changes no longer needed * fixup! CI --------- Co-authored-by: zeertzjq <zeertzjq@outlook.com>
This commit is contained in:
Lewis Russell
274
scripts/gen_eval_files.lua
Executable file
274
scripts/gen_eval_files.lua
Executable file
@@ -0,0 +1,274 @@
|
||||
#!/usr/bin/env -S nvim -l
|
||||
-- Generator for src/nvim/eval.lua
|
||||
|
||||
local funcs = require('src/nvim/eval').funcs
|
||||
|
||||
local LUA_KEYWORDS = {
|
||||
['and'] = true,
|
||||
['end'] = true,
|
||||
['function'] = true,
|
||||
['or'] = true,
|
||||
['if'] = true,
|
||||
['while'] = true,
|
||||
['repeat'] = true,
|
||||
}
|
||||
|
||||
--- @param f string
|
||||
--- @param params {[1]:string,[2]:string}[]|true
|
||||
local function render_fun_sig(f, params)
|
||||
local param_str --- @type string
|
||||
if params == true then
|
||||
param_str = '...'
|
||||
else
|
||||
param_str = table.concat(
|
||||
vim.tbl_map(
|
||||
--- @param v {[1]:string,[2]:string}
|
||||
function(v)
|
||||
return v[1]
|
||||
end,
|
||||
params
|
||||
),
|
||||
', '
|
||||
)
|
||||
end
|
||||
|
||||
if LUA_KEYWORDS[f] then
|
||||
return string.format("vim.fn['%s'] = function(%s) end", f, param_str)
|
||||
else
|
||||
return string.format('function vim.fn.%s(%s) end', f, param_str)
|
||||
end
|
||||
end
|
||||
|
||||
--- Uniquify names
|
||||
--- Fix any names that are lua keywords
|
||||
--- @param params {[1]:string,[2]:string}[]
|
||||
--- @return {[1]:string,[2]:string}[]
|
||||
local function process_params(params)
|
||||
local seen = {} --- @type table<string,true>
|
||||
local sfx = 1
|
||||
|
||||
for _, p in ipairs(params) do
|
||||
if LUA_KEYWORDS[p[1]] then
|
||||
p[1] = p[1] .. '_'
|
||||
end
|
||||
if seen[p[1]] then
|
||||
p[1] = p[1] .. sfx
|
||||
sfx = sfx + 1
|
||||
else
|
||||
seen[p[1]] = true
|
||||
end
|
||||
end
|
||||
|
||||
return params
|
||||
end
|
||||
|
||||
--- @param f string
|
||||
--- @param fun vim.EvalFn
|
||||
--- @param write fun(line: string)
|
||||
local function render_vimfn(f, fun, write)
|
||||
if fun.lua == false then
|
||||
return
|
||||
end
|
||||
|
||||
local funname = fun.name or f
|
||||
|
||||
local params = process_params(fun.params)
|
||||
|
||||
if fun.signature then
|
||||
write('')
|
||||
if fun.deprecated then
|
||||
write('--- @deprecated')
|
||||
end
|
||||
|
||||
local desc = fun.desc
|
||||
|
||||
if desc then
|
||||
desc = desc:gsub('\n%s*\n%s*$', '\n')
|
||||
for _, l in ipairs(vim.split(desc, '\n', { plain = true })) do
|
||||
l = l:gsub('^ ', ''):gsub('\t', ' '):gsub('@', '\\@')
|
||||
write('--- ' .. l)
|
||||
end
|
||||
end
|
||||
|
||||
local req_args = type(fun.args) == 'table' and fun.args[1] or fun.args or 0
|
||||
|
||||
for i, param in ipairs(params) do
|
||||
local pname, ptype = param[1], param[2]
|
||||
local optional = (pname ~= '...' and i > req_args) and '?' or ''
|
||||
write(string.format('--- @param %s%s %s', pname, optional, ptype))
|
||||
end
|
||||
|
||||
if fun.returns ~= false then
|
||||
write('--- @return ' .. (fun.returns or 'any'))
|
||||
end
|
||||
|
||||
write(render_fun_sig(funname, params))
|
||||
|
||||
return
|
||||
end
|
||||
|
||||
print('no doc for', funname)
|
||||
end
|
||||
|
||||
--- @type table<string,true>
|
||||
local rendered_tags = {}
|
||||
|
||||
--- @param f string
|
||||
--- @param fun vim.EvalFn
|
||||
--- @param write fun(line: string)
|
||||
local function render_eval_doc(f, fun, write)
|
||||
if fun.deprecated then
|
||||
return
|
||||
end
|
||||
|
||||
if not fun.signature then
|
||||
return
|
||||
end
|
||||
|
||||
local desc = fun.desc
|
||||
|
||||
if not desc then
|
||||
write(fun.signature)
|
||||
return
|
||||
end
|
||||
|
||||
local name = fun.name or f
|
||||
local tags = { '*' .. name .. '()*' }
|
||||
if fun.tags then
|
||||
for _, t in ipairs(fun.tags) do
|
||||
tags[#tags + 1] = '*' .. t .. '*'
|
||||
end
|
||||
end
|
||||
local tag = table.concat(tags, ' ')
|
||||
|
||||
local siglen = #fun.signature
|
||||
if rendered_tags[name] then
|
||||
write(fun.signature)
|
||||
else
|
||||
if siglen + #tag > 80 then
|
||||
write(string.rep('\t', 6) .. tag)
|
||||
write(fun.signature)
|
||||
else
|
||||
local tt = math.max(1, (76 - siglen - #tag) / 8)
|
||||
write(string.format('%s%s%s', fun.signature, string.rep('\t', tt), tag))
|
||||
end
|
||||
end
|
||||
rendered_tags[name] = true
|
||||
|
||||
desc = vim.trim(desc)
|
||||
local desc_l = vim.split(desc, '\n', { plain = true })
|
||||
for _, l in ipairs(desc_l) do
|
||||
l = l:gsub('^ ', '')
|
||||
if vim.startswith(l, '<') and not l:match('^<[A-Z][A-Z]') then
|
||||
write('<\t\t' .. l:sub(2))
|
||||
else
|
||||
write('\t\t' .. l)
|
||||
end
|
||||
end
|
||||
|
||||
if #desc_l > 0 and not desc_l[#desc_l]:match('^<?$') then
|
||||
write('')
|
||||
end
|
||||
end
|
||||
|
||||
--- @class nvim.gen_eval_files.elem
|
||||
--- @field path string
|
||||
--- @field render fun(f:string,fun:vim.EvalFn,write:fun(line:string))
|
||||
--- @field header? string[]
|
||||
--- @field footer? string[]
|
||||
|
||||
--- @type nvim.gen_eval_files.elem[]
|
||||
local CONFIG = {
|
||||
{
|
||||
path = 'runtime/lua/vim/_meta/vimfn.lua',
|
||||
render = render_vimfn,
|
||||
header = {
|
||||
'--- @meta',
|
||||
'-- THIS FILE IS GENERATED',
|
||||
'-- DO NOT EDIT',
|
||||
},
|
||||
},
|
||||
{
|
||||
path = 'runtime/doc/builtin.txt',
|
||||
render = render_eval_doc,
|
||||
header = {
|
||||
'*builtin.txt* Nvim',
|
||||
'',
|
||||
'',
|
||||
'\t\t VIM REFERENCE MANUAL\t by Bram Moolenaar',
|
||||
'',
|
||||
'',
|
||||
'Builtin functions\t\t*vimscript-functions* *builtin-functions*',
|
||||
'',
|
||||
'For functions grouped by what they are used for see |function-list|.',
|
||||
'',
|
||||
'\t\t\t\t Type |gO| to see the table of contents.',
|
||||
'==============================================================================',
|
||||
'1. Details *builtin-function-details*',
|
||||
'',
|
||||
},
|
||||
footer = {
|
||||
'==============================================================================',
|
||||
'2. Matching a pattern in a String *string-match*',
|
||||
'',
|
||||
'This is common between several functions. A regexp pattern as explained at',
|
||||
'|pattern| is normally used to find a match in the buffer lines. When a',
|
||||
'pattern is used to find a match in a String, almost everything works in the',
|
||||
'same way. The difference is that a String is handled like it is one line.',
|
||||
'When it contains a "\\n" character, this is not seen as a line break for the',
|
||||
'pattern. It can be matched with a "\\n" in the pattern, or with ".". Example:',
|
||||
'>',
|
||||
'\t:let a = "aaaa\\nxxxx"',
|
||||
'\t:echo matchstr(a, "..\\n..")',
|
||||
'\taa',
|
||||
'\txx',
|
||||
'\t:echo matchstr(a, "a.x")',
|
||||
'\ta',
|
||||
'\tx',
|
||||
'',
|
||||
'Don\'t forget that "^" will only match at the first character of the String and',
|
||||
'"$" at the last character of the string. They don\'t match after or before a',
|
||||
'"\\n".',
|
||||
'',
|
||||
' vim:tw=78:ts=8:noet:ft=help:norl:',
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
--- @param elem nvim.gen_eval_files.elem
|
||||
local function render(elem)
|
||||
local o = assert(io.open(elem.path, 'w'))
|
||||
|
||||
--- @param l string
|
||||
local function write(l)
|
||||
local l1 = l:gsub('%s+$', '')
|
||||
o:write(l1)
|
||||
o:write('\n')
|
||||
end
|
||||
|
||||
for _, l in ipairs(elem.header or {}) do
|
||||
write(l)
|
||||
end
|
||||
|
||||
--- @type string[]
|
||||
local fnames = vim.tbl_keys(funcs)
|
||||
table.sort(fnames)
|
||||
|
||||
for _, f in ipairs(fnames) do
|
||||
elem.render(f, funcs[f], write)
|
||||
end
|
||||
|
||||
for _, l in ipairs(elem.footer or {}) do
|
||||
write(l)
|
||||
end
|
||||
|
||||
o:close()
|
||||
end
|
||||
|
||||
local function main()
|
||||
for _, c in ipairs(CONFIG) do
|
||||
render(c)
|
||||
end
|
||||
end
|
||||
|
||||
main()
|
||||
Reference in New Issue
Block a user