mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-11-16 15:21:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: replace <pre> with ``` (#25136)

Browse Source
This commit is contained in:
Gregory Anders
2023-09-14 08:23:01 -05:00
committed by GitHub
parent 9fc321c976
commit 2e92065686
43 changed files with 1350 additions and 1245 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
runtime/doc/api.txt
View File

@@ -1791,9 +1791,9 @@ nvim_create_user_command({name}, {command}, {*opts})
For Lua usage see |lua-guide-commands-create|. For Lua usage see |lua-guide-commands-create|.
Example: >vim Example: >vim
:call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true}) :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true})
:SayHello :SayHello
Hello world! Hello world!
< <
Parameters: ~ Parameters: ~
@@ -2041,10 +2041,14 @@ whether a buffer is loaded.
nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
Activates buffer-update events on a channel, or as Lua callbacks. Activates buffer-update events on a channel, or as Lua callbacks.
Example (Lua): capture buffer updates in a global `events` variable (use "vim.print(events)" to see its contents): >lua Example (Lua): capture buffer updates in a global `events` variable (use
events = {} "vim.print(events)" to see its contents): >lua
vim.api.nvim_buf_attach(0, false, { events = {}
on_lines=function(...) table.insert(events, {...}) end}) vim.api.nvim_buf_attach(0, false, {
on_lines = function(...)
table.insert(events, {...})
end,
})
< <
Parameters: ~ Parameters: ~
@@ -2553,8 +2557,8 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {*opts})
Region can be given as (row,col) tuples, or valid extmark ids (whose Region can be given as (row,col) tuples, or valid extmark ids (whose
positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1) positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1)
respectively, thus the following are equivalent: >lua respectively, thus the following are equivalent: >lua
vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
vim.api.nvim_buf_get_extmarks(0, my_ns, {0,0}, {-1,-1}, {}) vim.api.nvim_buf_get_extmarks(0, my_ns, {0,0}, {-1,-1}, {})
< <
If `end` is less than `start`, traversal works backwards. (Useful with If `end` is less than `start`, traversal works backwards. (Useful with
@@ -2565,18 +2569,18 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {*opts})
an extmark will be considered. an extmark will be considered.
Example: >lua Example: >lua
local api = vim.api local api = vim.api
local pos = api.nvim_win_get_cursor(0) local pos = api.nvim_win_get_cursor(0)
local ns = api.nvim_create_namespace('my-plugin') local ns = api.nvim_create_namespace('my-plugin')
-- Create new extmark at line 1, column 1. -- Create new extmark at line 1, column 1.
local m1 = api.nvim_buf_set_extmark(0, ns, 0, 0, {}) local m1 = api.nvim_buf_set_extmark(0, ns, 0, 0, {})
-- Create new extmark at line 3, column 1. -- Create new extmark at line 3, column 1.
local m2 = api.nvim_buf_set_extmark(0, ns, 2, 0, {}) local m2 = api.nvim_buf_set_extmark(0, ns, 2, 0, {})
-- Get extmarks only from line 3. -- Get extmarks only from line 3.
local ms = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {}) local ms = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
-- Get all marks in this buffer + namespace. -- Get all marks in this buffer + namespace.
local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {}) local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {})
vim.print(ms) vim.print(ms)
< <
Parameters: ~ Parameters: ~
@@ -3062,6 +3066,7 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()*
Example (Lua): buffer-relative float (travels as buffer is scrolled) >lua Example (Lua): buffer-relative float (travels as buffer is scrolled) >lua
vim.api.nvim_open_win(0, false, vim.api.nvim_open_win(0, false,
{relative='win', width=12, height=3, bufpos={100,10}}) {relative='win', width=12, height=3, bufpos={100,10}})
})
< <
Attributes: ~ Attributes: ~
@@ -3340,9 +3345,9 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()*
}) })
< <
Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|), thus names like Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|),
"$HOME" and "~" must be expanded explicitly: >lua thus names like "$HOME" and "~" must be expanded explicitly: >lua
pattern = vim.fn.expand("~") .. "/some/path/*.py" pattern = vim.fn.expand("~") .. "/some/path/*.py"
< <
Parameters: ~ Parameters: ~
@@ -3447,17 +3452,17 @@ nvim_get_autocmds({*opts}) *nvim_get_autocmds()*
Get all autocommands that match the corresponding {opts}. Get all autocommands that match the corresponding {opts}.
These examples will get autocommands matching ALL the given criteria: >lua These examples will get autocommands matching ALL the given criteria: >lua
-- Matches all criteria -- Matches all criteria
autocommands = vim.api.nvim_get_autocmds({ autocommands = vim.api.nvim_get_autocmds({
group = "MyGroup", group = "MyGroup",
event = {"BufEnter", "BufWinEnter"}, event = {"BufEnter", "BufWinEnter"},
pattern = {"*.c", "*.h"} pattern = {"*.c", "*.h"}
}) })
-- All commands from one group -- All commands from one group
autocommands = vim.api.nvim_get_autocmds({ autocommands = vim.api.nvim_get_autocmds({
group = "MyGroup", group = "MyGroup",
}) })
< <
NOTE: When multiple patterns or events are provided, it will find all the NOTE: When multiple patterns or events are provided, it will find all the

7
runtime/doc/develop.txt
View File

@@ -238,7 +238,7 @@ Docstring format:
`---@see`, `---@param`, `---@returns` `---@see`, `---@param`, `---@returns`
- Limited markdown is supported. - Limited markdown is supported.
- List-items start with `-` (useful to nest or "indent") - List-items start with `-` (useful to nest or "indent")
- Use `<pre>` for code samples. - Use ``` for code samples.
Code samples can be annotated as `vim` or `lua` Code samples can be annotated as `vim` or `lua`
- Use `@nodoc` to prevent documentation generation. - Use `@nodoc` to prevent documentation generation.
- Files which has `@meta` are only used for typing and documentation. - Files which has `@meta` are only used for typing and documentation.
@@ -250,12 +250,13 @@ vim.paste in runtime/lua/vim/_editor.lua like this: >
--- (such as the |TUI|) pastes text into the editor. --- (such as the |TUI|) pastes text into the editor.
--- ---
--- Example: To remove ANSI color codes when pasting: --- Example: To remove ANSI color codes when pasting:
--- <pre>lua ---
--- ```lua
--- vim.paste = (function() --- vim.paste = (function()
--- local overridden = vim.paste --- local overridden = vim.paste
--- ... --- ...
--- end)() --- end)()
--- </pre> --- ```
--- ---
---@see |paste| ---@see |paste|
--- ---

18
runtime/doc/diagnostic.txt
View File

@@ -359,13 +359,11 @@ config({opts}, {namespace}) *vim.diagnostic.config()*
followed by namespace configuration, and finally global configuration. followed by namespace configuration, and finally global configuration.
For example, if a user enables virtual text globally with >lua For example, if a user enables virtual text globally with >lua
vim.diagnostic.config({ virtual_text = true })
vim.diagnostic.config({ virtual_text = true })
< <
and a diagnostic producer sets diagnostics with >lua and a diagnostic producer sets diagnostics with >lua
vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false })
vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false })
< <
then virtual text will not be enabled for those diagnostics. then virtual text will not be enabled for those diagnostics.
@@ -608,16 +606,14 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
Parse a diagnostic from a string. Parse a diagnostic from a string.
For example, consider a line of output from a linter: > For example, consider a line of output from a linter: >
WARNING filename:27:3: Variable 'foo' does not exist
WARNING filename:27:3: Variable 'foo' does not exist
< <
This can be parsed into a diagnostic |diagnostic-structure| with: >lua This can be parsed into a diagnostic |diagnostic-structure| with: >lua
local s = "WARNING filename:27:3: Variable 'foo' does not exist"
local s = "WARNING filename:27:3: Variable 'foo' does not exist" local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$" local groups = { "severity", "lnum", "col", "message" }
local groups = { "severity", "lnum", "col", "message" } vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
< <
Parameters: ~ Parameters: ~

145
runtime/doc/lsp.txt
View File

@@ -901,12 +901,11 @@ start({config}, {opts}) *vim.lsp.start()*
the current buffer to the client. the current buffer to the client.
Example: >lua Example: >lua
vim.lsp.start({
vim.lsp.start({ name = 'my-server-name',
name = 'my-server-name', cmd = {'name-of-language-server-executable'},
cmd = {'name-of-language-server-executable'}, root_dir = vim.fs.dirname(vim.fs.find({'pyproject.toml', 'setup.py'}, { upward = true })[1]),
root_dir = vim.fs.dirname(vim.fs.find({'pyproject.toml', 'setup.py'}, { upward = true })[1]), })
})
< <
See |vim.lsp.start_client()| for all available options. The most important See |vim.lsp.start_client()| for all available options. The most important
@@ -1078,9 +1077,9 @@ status() *vim.lsp.status()*
stop_client({client_id}, {force}) *vim.lsp.stop_client()* stop_client({client_id}, {force}) *vim.lsp.stop_client()*
Stops a client(s). Stops a client(s).
You can also use the `stop()` function on a |vim.lsp.client| object. To stop all clients: >lua You can also use the `stop()` function on a |vim.lsp.client| object. To
stop all clients: >lua
vim.lsp.stop_client(vim.lsp.get_clients()) vim.lsp.stop_client(vim.lsp.get_clients())
< <
By default asks the server to shutdown, unless stop was requested already By default asks the server to shutdown, unless stop was requested already
@@ -1196,10 +1195,10 @@ definition({options}) *vim.lsp.buf.definition()*
document_highlight() *vim.lsp.buf.document_highlight()* document_highlight() *vim.lsp.buf.document_highlight()*
Send request to the server to resolve document highlights for the current Send request to the server to resolve document highlights for the current
text document position. This request can be triggered by a key mapping or text document position. This request can be triggered by a key mapping or
by events such as `CursorHold` , e.g.: >vim by events such as `CursorHold`, e.g.: >vim
autocmd CursorHold <buffer> lua vim.lsp.buf.document_highlight() autocmd CursorHold <buffer> lua vim.lsp.buf.document_highlight()
autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight() autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight()
autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references() autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()
< <
Note: Usage of |vim.lsp.buf.document_highlight()| requires the following Note: Usage of |vim.lsp.buf.document_highlight()| requires the following
@@ -1242,12 +1241,12 @@ format({options}) *vim.lsp.buf.format()*
buffer (0). buffer (0).
• filter (function|nil): Predicate used to filter clients. • filter (function|nil): Predicate used to filter clients.
Receives a client as argument and must return a boolean. Receives a client as argument and must return a boolean.
Clients matching the predicate are included. Example: • >lua Clients matching the predicate are included. Example: >lua
-- Never request typescript-language-server for formatting -- Never request typescript-language-server for formatting
vim.lsp.buf.format { vim.lsp.buf.format {
filter = function(client) return client.name ~= "tsserver" end filter = function(client) return client.name ~= "tsserver" end
} }
< <
• async boolean|nil If true the method won't block. • async boolean|nil If true the method won't block.
Defaults to false. Editing the buffer while formatting Defaults to false. Editing the buffer while formatting
@@ -1366,24 +1365,23 @@ on_diagnostic({_}, {result}, {ctx}, {config})
See |vim.diagnostic.config()| for configuration options. Handler-specific See |vim.diagnostic.config()| for configuration options. Handler-specific
configuration can be set using |vim.lsp.with()|: >lua configuration can be set using |vim.lsp.with()|: >lua
vim.lsp.handlers["textDocument/diagnostic"] = vim.lsp.with(
vim.lsp.handlers["textDocument/diagnostic"] = vim.lsp.with( vim.lsp.diagnostic.on_diagnostic, {
vim.lsp.diagnostic.on_diagnostic, { -- Enable underline, use default values
-- Enable underline, use default values underline = true,
underline = true, -- Enable virtual text, override spacing to 4
-- Enable virtual text, override spacing to 4 virtual_text = {
virtual_text = { spacing = 4,
spacing = 4, },
}, -- Use a function to dynamically turn signs off
-- Use a function to dynamically turn signs off -- and on, using buffer local variables
-- and on, using buffer local variables signs = function(namespace, bufnr)
signs = function(namespace, bufnr) return vim.b[bufnr].show_signs == true
return vim.b[bufnr].show_signs == true end,
end, -- Disable a feature
-- Disable a feature update_in_insert = false,
update_in_insert = false, }
} )
)
< <
Parameters: ~ Parameters: ~
@@ -1395,24 +1393,23 @@ on_publish_diagnostics({_}, {result}, {ctx}, {config})
See |vim.diagnostic.config()| for configuration options. Handler-specific See |vim.diagnostic.config()| for configuration options. Handler-specific
configuration can be set using |vim.lsp.with()|: >lua configuration can be set using |vim.lsp.with()|: >lua
vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with( vim.lsp.diagnostic.on_publish_diagnostics, {
vim.lsp.diagnostic.on_publish_diagnostics, { -- Enable underline, use default values
-- Enable underline, use default values underline = true,
underline = true, -- Enable virtual text, override spacing to 4
-- Enable virtual text, override spacing to 4 virtual_text = {
virtual_text = { spacing = 4,
spacing = 4, },
}, -- Use a function to dynamically turn signs off
-- Use a function to dynamically turn signs off -- and on, using buffer local variables
-- and on, using buffer local variables signs = function(namespace, bufnr)
signs = function(namespace, bufnr) return vim.b[bufnr].show_signs == true
return vim.b[bufnr].show_signs == true end,
end, -- Disable a feature
-- Disable a feature update_in_insert = false,
update_in_insert = false, }
} )
)
< <
Parameters: ~ Parameters: ~
@@ -1457,7 +1454,7 @@ refresh() *vim.lsp.codelens.refresh()*
It is recommended to trigger this using an autocmd or via keymap. It is recommended to trigger this using an autocmd or via keymap.
Example: >vim Example: >vim
autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh() autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
< <
run() *vim.lsp.codelens.run()* run() *vim.lsp.codelens.run()*
@@ -1534,8 +1531,7 @@ start({bufnr}, {client_id}, {opts}) *vim.lsp.semantic_tokens.start()*
server that supports it, you can delete the semanticTokensProvider table server that supports it, you can delete the semanticTokensProvider table
from the {server_capabilities} of your client in your |LspAttach| callback from the {server_capabilities} of your client in your |LspAttach| callback
or your configuration's `on_attach` callback: >lua or your configuration's `on_attach` callback: >lua
client.server_capabilities.semanticTokensProvider = nil
client.server_capabilities.semanticTokensProvider = nil
< <
Parameters: ~ Parameters: ~
@@ -1565,15 +1561,14 @@ Lua module: vim.lsp.handlers *lsp-handlers*
hover({_}, {result}, {ctx}, {config}) *vim.lsp.handlers.hover()* hover({_}, {result}, {ctx}, {config}) *vim.lsp.handlers.hover()*
|lsp-handler| for the method "textDocument/hover" >lua |lsp-handler| for the method "textDocument/hover" >lua
vim.lsp.handlers["textDocument/hover"] = vim.lsp.with(
vim.lsp.handlers["textDocument/hover"] = vim.lsp.with( vim.lsp.handlers.hover, {
vim.lsp.handlers.hover, { -- Use a sharp border with `FloatBorder` highlights
-- Use a sharp border with `FloatBorder` highlights border = "single",
border = "single", -- add the title in hover float window
-- add the title in hover float window title = "hover"
title = "hover" }
} )
)
< <
Parameters: ~ Parameters: ~
@@ -1585,18 +1580,20 @@ hover({_}, {result}, {ctx}, {config}) *vim.lsp.handlers.hover()*
*vim.lsp.handlers.signature_help()* *vim.lsp.handlers.signature_help()*
signature_help({_}, {result}, {ctx}, {config}) signature_help({_}, {result}, {ctx}, {config})
|lsp-handler| for the method "textDocument/signatureHelp". The active |lsp-handler| for the method "textDocument/signatureHelp".
parameter is highlighted with |hl-LspSignatureActiveParameter|. >lua
vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with( The active parameter is highlighted with |hl-LspSignatureActiveParameter|. >lua
vim.lsp.handlers.signature_help, { vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
-- Use a sharp border with `FloatBorder` highlights vim.lsp.handlers.signature_help, {
border = "single" -- Use a sharp border with `FloatBorder` highlights
} border = "single"
) }
)
< <
Parameters: ~ Parameters: ~
• {result} (table) Response from the language server
• {ctx} (table) Client context
• {config} (table) Configuration table. • {config} (table) Configuration table.
• border: (default=nil) • border: (default=nil)
• Add borders to the floating window • Add borders to the floating window

741
runtime/doc/lua.txt
View File

File diff suppressed because it is too large Load Diff

2
runtime/doc/options.txt
View File

@@ -945,7 +945,7 @@ A jump table for the options with a short description can be found at |Q_op|.
backups if you don't care about losing the file. backups if you don't care about losing the file.
Note that environment variables are not expanded. If you want to use Note that environment variables are not expanded. If you want to use
$HOME you must expand it explicitly, e.g.: > $HOME you must expand it explicitly, e.g.: >vim
:let &backupskip = escape(expand('$HOME'), '\') .. '/tmp/*' :let &backupskip = escape(expand('$HOME'), '\') .. '/tmp/*'
< Note that the default also makes sure that "crontab -e" works (when a < Note that the default also makes sure that "crontab -e" works (when a

67
runtime/doc/treesitter.txt
View File

@@ -551,8 +551,7 @@ Lua module: vim.treesitter *lua-treesitter-core*
foldexpr({lnum}) *vim.treesitter.foldexpr()* foldexpr({lnum}) *vim.treesitter.foldexpr()*
Returns the fold level for {lnum} in the current buffer. Can be set Returns the fold level for {lnum} in the current buffer. Can be set
directly to 'foldexpr': >lua directly to 'foldexpr': >lua
vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'
vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'
< <
Parameters: ~ Parameters: ~
@@ -746,13 +745,12 @@ start({bufnr}, {lang}) *vim.treesitter.start()*
the call to `start`. the call to `start`.
Example: >lua Example: >lua
vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex',
vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex', callback = function(args)
callback = function(args) vim.treesitter.start(args.buf, 'latex')
vim.treesitter.start(args.buf, 'latex') vim.bo[args.buf].syntax = 'on' -- only if additional legacy syntax is needed
vim.bo[args.buf].syntax = 'on' -- only if additional legacy syntax is needed end
end })
})
< <
Parameters: ~ Parameters: ~
@@ -922,7 +920,7 @@ omnifunc({findstart}, {base}) *vim.treesitter.query.omnifunc()*
Omnifunc for completing node names and predicates in treesitter queries. Omnifunc for completing node names and predicates in treesitter queries.
Use via >lua Use via >lua
vim.bo.omnifunc = 'v:lua.vim.treesitter.query.omnifunc' vim.bo.omnifunc = 'v:lua.vim.treesitter.query.omnifunc'
< <
parse({lang}, {query}) *vim.treesitter.query.parse()* parse({lang}, {query}) *vim.treesitter.query.parse()*
@@ -958,14 +956,13 @@ Query:iter_captures({node}, {source}, {start}, {stop})
The iterator returns three values: a numeric id identifying the capture, The iterator returns three values: a numeric id identifying the capture,
the captured node, and metadata from any directives processing the match. the captured node, and metadata from any directives processing the match.
The following example shows how to get captures by name: >lua The following example shows how to get captures by name: >lua
for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do
for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do local name = query.captures[id] -- name of the capture in the query
local name = query.captures[id] -- name of the capture in the query -- typically useful info about the node:
-- typically useful info about the node: local type = node:type() -- type of the captured node
local type = node:type() -- type of the captured node local row1, col1, row2, col2 = node:range() -- range of the capture
local row1, col1, row2, col2 = node:range() -- range of the capture -- ... use the info here ...
-- ... use the info here ... end
end
< <
Parameters: ~ Parameters: ~
@@ -988,18 +985,18 @@ Query:iter_matches({node}, {source}, {start}, {stop}, {opts})
(1-based) index of the pattern in the query, a table mapping capture (1-based) index of the pattern in the query, a table mapping capture
indices to nodes, and metadata from any directives processing the match. indices to nodes, and metadata from any directives processing the match.
If the query has more than one pattern, the capture table might be sparse If the query has more than one pattern, the capture table might be sparse
and e.g. `pairs()` method should be used over `ipairs` . Here is an example iterating over all captures in every match: >lua and e.g. `pairs()` method should be used over `ipairs`. Here is an example
iterating over all captures in every match: >lua
for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do
for id, node in pairs(match) do
local name = query.captures[id]
-- `node` was captured by the `name` capture in the match
for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do local node_data = metadata[id] -- Node level metadata
for id, node in pairs(match) do
local name = query.captures[id]
-- `node` was captured by the `name` capture in the match
local node_data = metadata[id] -- Node level metadata -- ... use the info here ...
end
-- ... use the info here ... end
end
end
< <
Parameters: ~ Parameters: ~
@@ -1039,11 +1036,8 @@ inject other languages, recursively. For example a Lua buffer containing
some Vimscript commands needs multiple parsers to fully understand its some Vimscript commands needs multiple parsers to fully understand its
contents. contents.
To create a LanguageTree (parser object) for a given buffer and language, use: To create a LanguageTree (parser object) for a given buffer and language, use: >lua
local parser = vim.treesitter.get_parser(bufnr, lang)
>lua
local parser = vim.treesitter.get_parser(bufnr, lang)
< <
@@ -1052,11 +1046,8 @@ Note: currently the parser is retained for the lifetime of a buffer but
this may change; a plugin should keep a reference to the parser object if this may change; a plugin should keep a reference to the parser object if
it wants incremental updates. it wants incremental updates.
Whenever you need to access the current syntax tree, parse the buffer: Whenever you need to access the current syntax tree, parse the buffer: >lua
local tree = parser:parse({ start_row, end_row })
>lua
local tree = parser:parse({ start_row, end_row })
< <

5
runtime/lua/vim/F.lua
View File

@@ -5,13 +5,14 @@ local F = {}
--- If all arguments are nil, returns nil. --- If all arguments are nil, returns nil.
--- ---
--- Examples: --- Examples:
--- <pre> ---
--- ```lua
--- local a = nil --- local a = nil
--- local b = nil --- local b = nil
--- local c = 42 --- local c = 42
--- local d = true --- local d = true
--- assert(vim.F.if_nil(a, b, c, d) == 42) --- assert(vim.F.if_nil(a, b, c, d) == 42)
--- </pre> --- ```
--- ---
---@param ... any ---@param ... any
---@return any ---@return any

96
runtime/lua/vim/_editor.lua
View File

@@ -70,23 +70,24 @@ vim.log = {
--- Run a system command --- Run a system command
--- ---
--- Examples: --- Examples:
--- <pre>lua
--- ---
--- local on_exit = function(obj) --- ```lua
--- print(obj.code)
--- print(obj.signal)
--- print(obj.stdout)
--- print(obj.stderr)
--- end
--- ---
--- -- Run asynchronously --- local on_exit = function(obj)
--- vim.system({'echo', 'hello'}, { text = true }, on_exit) --- print(obj.code)
--- print(obj.signal)
--- print(obj.stdout)
--- print(obj.stderr)
--- end
--- ---
--- -- Run synchronously --- -- Run asynchronously
--- local obj = vim.system({'echo', 'hello'}, { text = true }):wait() --- vim.system({'echo', 'hello'}, { text = true }, on_exit)
--- -- { code = 0, signal = 0, stdout = 'hello', stderr = '' }
--- ---
--- </pre> --- -- Run synchronously
--- local obj = vim.system({'echo', 'hello'}, { text = true }):wait()
--- -- { code = 0, signal = 0, stdout = 'hello', stderr = '' }
---
--- ```
--- ---
--- See |uv.spawn()| for more details. --- See |uv.spawn()| for more details.
--- ---
@@ -200,7 +201,8 @@ do
--- (such as the |TUI|) pastes text into the editor. --- (such as the |TUI|) pastes text into the editor.
--- ---
--- Example: To remove ANSI color codes when pasting: --- Example: To remove ANSI color codes when pasting:
--- <pre>lua ---
--- ```lua
--- vim.paste = (function(overridden) --- vim.paste = (function(overridden)
--- return function(lines, phase) --- return function(lines, phase)
--- for i,line in ipairs(lines) do --- for i,line in ipairs(lines) do
@@ -210,7 +212,7 @@ do
--- overridden(lines, phase) --- overridden(lines, phase)
--- end --- end
--- end)(vim.paste) --- end)(vim.paste)
--- </pre> --- ```
--- ---
---@see |paste| ---@see |paste|
---@alias paste_phase -1 | 1 | 2 | 3 ---@alias paste_phase -1 | 1 | 2 | 3
@@ -361,32 +363,33 @@ local VIM_CMD_ARG_MAX = 20
--- command. --- command.
--- ---
--- Example: --- Example:
--- <pre>lua
--- vim.cmd('echo 42')
--- vim.cmd([[
--- augroup My_group
--- autocmd!
--- autocmd FileType c setlocal cindent
--- augroup END
--- ]])
--- ---
--- -- Ex command :echo "foo" --- ```lua
--- -- Note string literals need to be double quoted. --- vim.cmd('echo 42')
--- vim.cmd('echo "foo"') --- vim.cmd([[
--- vim.cmd { cmd = 'echo', args = { '"foo"' } } --- augroup My_group
--- vim.cmd.echo({ args = { '"foo"' } }) --- autocmd!
--- vim.cmd.echo('"foo"') --- autocmd FileType c setlocal cindent
--- augroup END
--- ]])
--- ---
--- -- Ex command :write! myfile.txt --- -- Ex command :echo "foo"
--- vim.cmd('write! myfile.txt') --- -- Note string literals need to be double quoted.
--- vim.cmd { cmd = 'write', args = { "myfile.txt" }, bang = true } --- vim.cmd('echo "foo"')
--- vim.cmd.write { args = { "myfile.txt" }, bang = true } --- vim.cmd { cmd = 'echo', args = { '"foo"' } }
--- vim.cmd.write { "myfile.txt", bang = true } --- vim.cmd.echo({ args = { '"foo"' } })
--- vim.cmd.echo('"foo"')
--- ---
--- -- Ex command :colorscheme blue --- -- Ex command :write! myfile.txt
--- vim.cmd('colorscheme blue') --- vim.cmd('write! myfile.txt')
--- vim.cmd.colorscheme('blue') --- vim.cmd { cmd = 'write', args = { "myfile.txt" }, bang = true }
--- </pre> --- vim.cmd.write { args = { "myfile.txt" }, bang = true }
--- vim.cmd.write { "myfile.txt", bang = true }
---
--- -- Ex command :colorscheme blue
--- vim.cmd('colorscheme blue')
--- vim.cmd.colorscheme('blue')
--- ```
--- ---
---@param command string|table Command(s) to execute. ---@param command string|table Command(s) to execute.
--- If a string, executes multiple lines of Vim script at once. In this --- If a string, executes multiple lines of Vim script at once. In this
@@ -871,9 +874,10 @@ end
--- "Pretty prints" the given arguments and returns them unmodified. --- "Pretty prints" the given arguments and returns them unmodified.
--- ---
--- Example: --- Example:
--- <pre>lua ---
--- local hl_normal = vim.print(vim.api.nvim_get_hl_by_name('Normal', true)) --- ```lua
--- </pre> --- local hl_normal = vim.print(vim.api.nvim_get_hl_by_name('Normal', true))
--- ```
--- ---
--- @see |vim.inspect()| --- @see |vim.inspect()|
--- @see |:=| --- @see |:=|
@@ -900,10 +904,12 @@ end
--- Translate keycodes. --- Translate keycodes.
--- ---
--- Example: --- Example:
--- <pre>lua ---
--- local k = vim.keycode --- ```lua
--- vim.g.mapleader = k'<bs>' --- local k = vim.keycode
--- </pre> --- vim.g.mapleader = k'<bs>'
--- ```
---
--- @param str string String to be converted. --- @param str string String to be converted.
--- @return string --- @return string
--- @see |nvim_replace_termcodes()| --- @see |nvim_replace_termcodes()|

96
runtime/lua/vim/_meta/api.lua generated
View File

@@ -127,11 +127,16 @@ function vim.api.nvim__unpack(str) end
function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start, col_end) end function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start, col_end) end
--- Activates buffer-update events on a channel, or as Lua callbacks. --- Activates buffer-update events on a channel, or as Lua callbacks.
--- Example (Lua): capture buffer updates in a global `events` variable (use "vim.print(events)" to see its contents): --- Example (Lua): capture buffer updates in a global `events` variable (use
--- "vim.print(events)" to see its contents):
---
--- ```lua --- ```lua
--- events = {} --- events = {}
--- vim.api.nvim_buf_attach(0, false, { --- vim.api.nvim_buf_attach(0, false, {
--- on_lines=function(...) table.insert(events, {...}) end}) --- on_lines = function(...)
--- table.insert(events, {...})
--- end,
--- })
--- ``` --- ```
--- ---
--- @param buffer integer Buffer handle, or 0 for current buffer --- @param buffer integer Buffer handle, or 0 for current buffer
@@ -314,29 +319,32 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end
--- Region can be given as (row,col) tuples, or valid extmark ids (whose --- Region can be given as (row,col) tuples, or valid extmark ids (whose
--- positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1) --- positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1)
--- respectively, thus the following are equivalent: --- respectively, thus the following are equivalent:
---
--- ```lua --- ```lua
--- vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) --- vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
--- vim.api.nvim_buf_get_extmarks(0, my_ns, {0,0}, {-1,-1}, {}) --- vim.api.nvim_buf_get_extmarks(0, my_ns, {0,0}, {-1,-1}, {})
--- ``` --- ```
---
--- If `end` is less than `start`, traversal works backwards. (Useful with --- If `end` is less than `start`, traversal works backwards. (Useful with
--- `limit`, to get the first marks prior to a given position.) --- `limit`, to get the first marks prior to a given position.)
--- Note: when using extmark ranges (marks with a end_row/end_col position) --- Note: when using extmark ranges (marks with a end_row/end_col position)
--- the `overlap` option might be useful. Otherwise only the start position of --- the `overlap` option might be useful. Otherwise only the start position of
--- an extmark will be considered. --- an extmark will be considered.
--- Example: --- Example:
---
--- ```lua --- ```lua
--- local api = vim.api --- local api = vim.api
--- local pos = api.nvim_win_get_cursor(0) --- local pos = api.nvim_win_get_cursor(0)
--- local ns = api.nvim_create_namespace('my-plugin') --- local ns = api.nvim_create_namespace('my-plugin')
--- -- Create new extmark at line 1, column 1. --- -- Create new extmark at line 1, column 1.
--- local m1 = api.nvim_buf_set_extmark(0, ns, 0, 0, {}) --- local m1 = api.nvim_buf_set_extmark(0, ns, 0, 0, {})
--- -- Create new extmark at line 3, column 1. --- -- Create new extmark at line 3, column 1.
--- local m2 = api.nvim_buf_set_extmark(0, ns, 2, 0, {}) --- local m2 = api.nvim_buf_set_extmark(0, ns, 2, 0, {})
--- -- Get extmarks only from line 3. --- -- Get extmarks only from line 3.
--- local ms = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {}) --- local ms = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
--- -- Get all marks in this buffer + namespace. --- -- Get all marks in this buffer + namespace.
--- local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {}) --- local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {})
--- vim.print(ms) --- vim.print(ms)
--- ``` --- ```
--- ---
--- @param buffer integer Buffer handle, or 0 for current buffer --- @param buffer integer Buffer handle, or 0 for current buffer
@@ -775,6 +783,7 @@ function vim.api.nvim_command_output(command) end
--- Create or get an autocommand group `autocmd-groups`. --- Create or get an autocommand group `autocmd-groups`.
--- To get an existing group id, do: --- To get an existing group id, do:
---
--- ```lua --- ```lua
--- local id = vim.api.nvim_create_augroup("MyGroup", { --- local id = vim.api.nvim_create_augroup("MyGroup", {
--- clear = false --- clear = false
@@ -790,6 +799,7 @@ function vim.api.nvim_create_augroup(name, opts) end
--- Creates an `autocommand` event handler, defined by `callback` (Lua function or Vimscript function name string) or `command` (Ex command string). --- Creates an `autocommand` event handler, defined by `callback` (Lua function or Vimscript function name string) or `command` (Ex command string).
--- Example using Lua callback: --- Example using Lua callback:
---
--- ```lua --- ```lua
--- vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { --- vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
--- pattern = {"*.c", "*.h"}, --- pattern = {"*.c", "*.h"},
@@ -798,17 +808,21 @@ function vim.api.nvim_create_augroup(name, opts) end
--- end --- end
--- }) --- })
--- ``` --- ```
---
--- Example using an Ex command as the handler: --- Example using an Ex command as the handler:
---
--- ```lua --- ```lua
--- vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { --- vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
--- pattern = {"*.c", "*.h"}, --- pattern = {"*.c", "*.h"},
--- command = "echo 'Entering a C or C++ file'", --- command = "echo 'Entering a C or C++ file'",
--- }) --- })
--- ``` --- ```
--- Note: `pattern` is NOT automatically expanded (unlike with `:autocmd`), thus names like ---
--- "$HOME" and "~" must be expanded explicitly: --- Note: `pattern` is NOT automatically expanded (unlike with `:autocmd`),
--- thus names like "$HOME" and "~" must be expanded explicitly:
---
--- ```lua --- ```lua
--- pattern = vim.fn.expand("~") .. "/some/path/*.py" --- pattern = vim.fn.expand("~") .. "/some/path/*.py"
--- ``` --- ```
--- ---
--- @param event any (string|array) Event(s) that will trigger the handler --- @param event any (string|array) Event(s) that will trigger the handler
@@ -870,10 +884,11 @@ function vim.api.nvim_create_namespace(name) end
--- Creates a global `user-commands` command. --- Creates a global `user-commands` command.
--- For Lua usage see `lua-guide-commands-create`. --- For Lua usage see `lua-guide-commands-create`.
--- Example: --- Example:
---
--- ```vim --- ```vim
--- :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true}) --- :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true})
--- :SayHello --- :SayHello
--- Hello world! --- Hello world!
--- ``` --- ```
--- ---
--- @param name string Name of the new user command. Must begin with an uppercase --- @param name string Name of the new user command. Must begin with an uppercase
@@ -1084,6 +1099,7 @@ function vim.api.nvim_execute_lua(code, args) end
--- with escape_ks=false) to replace `keycodes`, then pass the result to --- with escape_ks=false) to replace `keycodes`, then pass the result to
--- nvim_feedkeys(). --- nvim_feedkeys().
--- Example: --- Example:
---
--- ```vim --- ```vim
--- :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true) --- :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true)
--- :call nvim_feedkeys(key, 'n', v:false) --- :call nvim_feedkeys(key, 'n', v:false)
@@ -1111,19 +1127,21 @@ function vim.api.nvim_get_api_info() end
--- Get all autocommands that match the corresponding {opts}. --- Get all autocommands that match the corresponding {opts}.
--- These examples will get autocommands matching ALL the given criteria: --- These examples will get autocommands matching ALL the given criteria:
--- ```lua
--- -- Matches all criteria
--- autocommands = vim.api.nvim_get_autocmds({
--- group = "MyGroup",
--- event = {"BufEnter", "BufWinEnter"},
--- pattern = {"*.c", "*.h"}
--- })
--- ---
--- -- All commands from one group --- ```lua
--- autocommands = vim.api.nvim_get_autocmds({ --- -- Matches all criteria
--- group = "MyGroup", --- autocommands = vim.api.nvim_get_autocmds({
--- }) --- group = "MyGroup",
--- event = {"BufEnter", "BufWinEnter"},
--- pattern = {"*.c", "*.h"}
--- })
---
--- -- All commands from one group
--- autocommands = vim.api.nvim_get_autocmds({
--- group = "MyGroup",
--- })
--- ``` --- ```
---
--- NOTE: When multiple patterns or events are provided, it will find all the --- NOTE: When multiple patterns or events are provided, it will find all the
--- autocommands that match any combination of them. --- autocommands that match any combination of them.
--- ---
@@ -1149,6 +1167,7 @@ function vim.api.nvim_get_chan_info(chan) end
--- Returns the 24-bit RGB value of a `nvim_get_color_map()` color name or --- Returns the 24-bit RGB value of a `nvim_get_color_map()` color name or
--- "#rrggbb" hexadecimal string. --- "#rrggbb" hexadecimal string.
--- Example: --- Example:
---
--- ```vim --- ```vim
--- :echo nvim_get_color_by_name("Pink") --- :echo nvim_get_color_by_name("Pink")
--- :echo nvim_get_color_by_name("#cbcbcb") --- :echo nvim_get_color_by_name("#cbcbcb")
@@ -1471,14 +1490,18 @@ function vim.api.nvim_open_term(buffer, opts) end
--- could let floats hover outside of the main window like a tooltip, but this --- could let floats hover outside of the main window like a tooltip, but this
--- should not be used to specify arbitrary WM screen positions. --- should not be used to specify arbitrary WM screen positions.
--- Example (Lua): window-relative float --- Example (Lua): window-relative float
---
--- ```lua --- ```lua
--- vim.api.nvim_open_win(0, false, --- vim.api.nvim_open_win(0, false,
--- {relative='win', row=3, col=3, width=12, height=3}) --- {relative='win', row=3, col=3, width=12, height=3})
--- ``` --- ```
---
--- Example (Lua): buffer-relative float (travels as buffer is scrolled) --- Example (Lua): buffer-relative float (travels as buffer is scrolled)
---
--- ```lua --- ```lua
--- vim.api.nvim_open_win(0, false, --- vim.api.nvim_open_win(0, false,
--- {relative='win', width=12, height=3, bufpos={100,10}}) --- {relative='win', width=12, height=3, bufpos={100,10}})
--- })
--- ``` --- ```
--- ---
--- @param buffer integer Buffer to display, or 0 for current buffer --- @param buffer integer Buffer to display, or 0 for current buffer
@@ -1856,10 +1879,13 @@ function vim.api.nvim_set_hl_ns_fast(ns_id) end
--- Unlike `:map`, leading/trailing whitespace is accepted as part of the --- Unlike `:map`, leading/trailing whitespace is accepted as part of the
--- {lhs} or {rhs}. Empty {rhs} is `<Nop>`. `keycodes` are replaced as usual. --- {lhs} or {rhs}. Empty {rhs} is `<Nop>`. `keycodes` are replaced as usual.
--- Example: --- Example:
---
--- ```vim --- ```vim
--- call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true}) --- call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})
--- ``` --- ```
---
--- is equivalent to: --- is equivalent to:
---
--- ```vim --- ```vim
--- nmap <nowait> <Space><NL> <Nop> --- nmap <nowait> <Space><NL> <Nop>
--- ``` --- ```

44
runtime/lua/vim/_meta/builtin.lua
View File

@@ -131,7 +131,8 @@ function vim.str_utf_pos(str) end
--- The result can be added to {index} to get the starting byte of a character. --- The result can be added to {index} to get the starting byte of a character.
--- ---
--- Examples: --- Examples:
--- <pre>lua ---
--- ```lua
--- -- The character 'æ' is stored as the bytes '\xc3\xa6' (using UTF-8) --- -- The character 'æ' is stored as the bytes '\xc3\xa6' (using UTF-8)
--- ---
--- -- Returns 0 because the index is pointing at the first byte of a character --- -- Returns 0 because the index is pointing at the first byte of a character
@@ -139,7 +140,7 @@ function vim.str_utf_pos(str) end
--- ---
--- -- Returns -1 because the index is pointing at the second byte of a character --- -- Returns -1 because the index is pointing at the second byte of a character
--- vim.str_utf_start('æ', 2) --- vim.str_utf_start('æ', 2)
--- </pre> --- ```
--- ---
--- @param str string --- @param str string
--- @param index number --- @param index number
@@ -150,7 +151,8 @@ function vim.str_utf_start(str, index) end
--- to. --- to.
--- ---
--- Examples: --- Examples:
--- <pre>lua ---
--- ```lua
--- -- The character 'æ' is stored as the bytes '\xc3\xa6' (using UTF-8) --- -- The character 'æ' is stored as the bytes '\xc3\xa6' (using UTF-8)
--- ---
--- -- Returns 0 because the index is pointing at the last byte of a character --- -- Returns 0 because the index is pointing at the last byte of a character
@@ -158,7 +160,7 @@ function vim.str_utf_start(str, index) end
--- ---
--- -- Returns 1 because the index is pointing at the penultimate byte of a character --- -- Returns 1 because the index is pointing at the penultimate byte of a character
--- vim.str_utf_end('æ', 1) --- vim.str_utf_end('æ', 1)
--- </pre> --- ```
--- ---
--- @param str string --- @param str string
--- @param index number --- @param index number
@@ -204,7 +206,8 @@ function vim.schedule(callback) end
--- this time. --- this time.
--- ---
--- Examples: --- Examples:
--- <pre>lua ---
--- ```lua
--- ---
--- --- --- ---
--- -- Wait for 100 ms, allowing other events to process --- -- Wait for 100 ms, allowing other events to process
@@ -226,7 +229,7 @@ function vim.schedule(callback) end
--- if vim.wait(10000, function() return vim.g.timer_result end) then --- if vim.wait(10000, function() return vim.g.timer_result end) then
--- print('Only waiting a little bit of time!') --- print('Only waiting a little bit of time!')
--- end --- end
--- </pre> --- ```
--- ---
--- @param time integer Number of milliseconds to wait --- @param time integer Number of milliseconds to wait
--- @param callback? fun(): boolean Optional callback. Waits until {callback} returns true --- @param callback? fun(): boolean Optional callback. Waits until {callback} returns true
@@ -258,22 +261,23 @@ function vim.wait(time, callback, interval, fast_only) end
--- likewise experimental). --- likewise experimental).
--- ---
--- Example (stub for a |ui-popupmenu| implementation): --- Example (stub for a |ui-popupmenu| implementation):
--- <pre>lua
--- ---
--- ns = vim.api.nvim_create_namespace('my_fancy_pum') --- ```lua
--- ns = vim.api.nvim_create_namespace('my_fancy_pum')
---
--- vim.ui_attach(ns, {ext_popupmenu=true}, function(event, ...)
--- if event == "popupmenu_show" then
--- local items, selected, row, col, grid = ...
--- print("display pum ", #items)
--- elseif event == "popupmenu_select" then
--- local selected = ...
--- print("selected", selected)
--- elseif event == "popupmenu_hide" then
--- print("FIN")
--- end
--- end)
--- ```
--- ---
--- vim.ui_attach(ns, {ext_popupmenu=true}, function(event, ...)
--- if event == "popupmenu_show" then
--- local items, selected, row, col, grid = ...
--- print("display pum ", #items)
--- elseif event == "popupmenu_select" then
--- local selected = ...
--- print("selected", selected)
--- elseif event == "popupmenu_hide" then
--- print("FIN")
--- end
--- end)
--- </pre>
--- @param ns integer --- @param ns integer
--- @param options table<string, any> --- @param options table<string, any>
--- @param callback fun() --- @param callback fun()

35
runtime/lua/vim/_meta/diff.lua
View File

@@ -6,24 +6,25 @@
--- either directly or via callback arguments, are 1-based. --- either directly or via callback arguments, are 1-based.
--- ---
--- Examples: --- Examples:
--- <pre>lua
--- vim.diff('a\\n', 'b\\nc\\n')
--- -- =>
--- -- @@ -1 +1,2 @@
--- -- -a
--- -- +b
--- -- +c
--- ---
--- vim.diff('a\\n', 'b\\nc\\n', {result_type = 'indices'}) --- ```lua
--- -- => --- vim.diff('a\n', 'b\nc\n')
--- -- { --- -- =>
--- -- {1, 1, 1, 2} --- -- @@ -1 +1,2 @@
--- -- } --- -- -a
--- </pre> --- -- +b
--- -- +c
--- ---
--- @param a string First string to compare --- vim.diff('a\n', 'b\nc\n', {result_type = 'indices'})
--- @param b string Second string to compare --- -- =>
--- @param opts table<string,any> Optional parameters: --- -- {
--- -- {1, 1, 1, 2}
--- -- }
--- ```
---
---@param a string First string to compare
---@param b string Second string to compare
---@param opts table<string,any> Optional parameters:
--- - `on_hunk` (callback): --- - `on_hunk` (callback):
--- Invoked for each hunk in the diff. Return a negative number --- Invoked for each hunk in the diff. Return a negative number
--- to cancel the callback for any remaining hunks. --- to cancel the callback for any remaining hunks.
@@ -64,6 +65,6 @@
--- Use the indent heuristic for the internal --- Use the indent heuristic for the internal
--- diff library. --- diff library.
--- ---
--- @return string|table|nil ---@return string|table|nil
--- See {opts.result_type}. `nil` if {opts.on_hunk} is given. --- See {opts.result_type}. `nil` if {opts.on_hunk} is given.
function vim.diff(a, b, opts) end function vim.diff(a, b, opts) end

37
runtime/lua/vim/_meta/json.lua
View File

@@ -1,8 +1,8 @@
--- @meta ---@meta
-- luacheck: no unused args -- luacheck: no unused args
--- @defgroup vim.json ---@defgroup vim.json
--- ---
--- This module provides encoding and decoding of Lua objects to and --- This module provides encoding and decoding of Lua objects to and
--- from JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. --- from JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|.
@@ -14,24 +14,23 @@
--- - Decodes empty array as `{}` (empty Lua table). --- - Decodes empty array as `{}` (empty Lua table).
--- ---
--- Example: --- Example:
--- <pre>lua ---
--- :lua vim.print(vim.json.decode('{"bar":[],"foo":{},"zub":null}')) --- ```lua
--- --> { bar = {}, foo = vim.empty_dict(), zub = vim.NIL } --- vim.print(vim.json.decode('{"bar":[],"foo":{},"zub":null}'))
--- </pre> --- -- { bar = {}, foo = vim.empty_dict(), zub = vim.NIL }
--- Parameters: ~ --- ```
--- • {str} Stringified JSON data. ---
--- • {opts} Options map keys: ---@param str string Stringified JSON data.
--- • luanil: { object: bool, array: bool } ---@param opts? table<string,any> Options table with keys:
--- • `luanil.object=true` converts `null` in JSON objects to --- - luanil: (table) Table with keys:
--- Lua `nil` instead of `vim.NIL`. --- * object: (boolean) When true, converts `null` in JSON objects
--- • `luanil.array=true` converts `null` in JSON arrays to Lua --- to Lua `nil` instead of |vim.NIL|.
--- `nil` instead of `vim.NIL`. --- * array: (boolean) When true, converts `null` in JSON arrays
--- @param str string --- to Lua `nil` instead of |vim.NIL|.
--- @param opts? table<string, any> ---@return any
--- @return any
function vim.json.decode(str, opts) end function vim.json.decode(str, opts) end
--- Encodes (or "packs") Lua object {obj} as JSON in a Lua string. --- Encodes (or "packs") Lua object {obj} as JSON in a Lua string.
--- @param obj any ---@param obj any
--- @return string ---@return string
function vim.json.encode(obj) end function vim.json.encode(obj) end

8
runtime/lua/vim/_meta/misc.lua
View File

@@ -5,9 +5,11 @@
--- Invokes |vim-function| or |user-function| {func} with arguments {...}. --- Invokes |vim-function| or |user-function| {func} with arguments {...}.
--- See also |vim.fn|. --- See also |vim.fn|.
--- Equivalent to: --- Equivalent to:
--- <pre>lua ---
--- vim.fn[func]({...}) --- ```lua
--- </pre> --- vim.fn[func]({...})
--- ```
---
--- @param func fun() --- @param func fun()
--- @param ... any --- @param ... any
function vim.call(func, ...) end function vim.call(func, ...) end

52
runtime/lua/vim/_meta/options.lua generated
View File

@@ -141,6 +141,7 @@ vim.bo.ai = vim.bo.autoindent
--- :set autoread< --- :set autoread<
--- ``` --- ```
--- ---
---
--- @type boolean --- @type boolean
vim.o.autoread = true vim.o.autoread = true
vim.o.ar = vim.o.autoread vim.o.ar = vim.o.autoread
@@ -354,6 +355,7 @@ vim.go.bkc = vim.go.backupcopy
--- ``` --- ```
--- :set bdir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces --- :set bdir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces
--- ``` --- ```
---
--- See also 'backup' and 'writebackup' options. --- See also 'backup' and 'writebackup' options.
--- If you want to hide your backup files on Unix, consider this value: --- If you want to hide your backup files on Unix, consider this value:
--- ``` --- ```
@@ -409,9 +411,9 @@ vim.go.bex = vim.go.backupext
--- ---
--- Note that environment variables are not expanded. If you want to use --- Note that environment variables are not expanded. If you want to use
--- $HOME you must expand it explicitly, e.g.: --- $HOME you must expand it explicitly, e.g.:
--- ```
--- :let &backupskip = escape(expand('$HOME'), '\') .. '/tmp/*'
--- ---
--- ```vim
--- :let &backupskip = escape(expand('$HOME'), '\') .. '/tmp/*'
--- ``` --- ```
--- Note that the default also makes sure that "crontab -e" works (when a --- Note that the default also makes sure that "crontab -e" works (when a
--- backup would be made by renaming the original file crontab won't see --- backup would be made by renaming the original file crontab won't see
@@ -833,6 +835,7 @@ vim.bo.cino = vim.bo.cinoptions
--- set cinscopedecls+=signals,public\ slots,private\ slots --- set cinscopedecls+=signals,public\ slots,private\ slots
--- ``` --- ```
--- ---
---
--- @type string --- @type string
vim.o.cinscopedecls = "public,protected,private" vim.o.cinscopedecls = "public,protected,private"
vim.o.cinsd = vim.o.cinscopedecls vim.o.cinsd = vim.o.cinscopedecls
@@ -916,11 +919,11 @@ vim.go.cwh = vim.go.cmdwinheight
--- The screen column can be an absolute number, or a number preceded with --- The screen column can be an absolute number, or a number preceded with
--- '+' or '-', which is added to or subtracted from 'textwidth'. --- '+' or '-', which is added to or subtracted from 'textwidth'.
--- ``` --- ```
---
--- :set cc=+1 " highlight column after 'textwidth' --- :set cc=+1 " highlight column after 'textwidth'
--- :set cc=+1,+2,+3 " highlight three columns after 'textwidth' --- :set cc=+1,+2,+3 " highlight three columns after 'textwidth'
--- :hi ColorColumn ctermbg=lightgrey guibg=lightgrey --- :hi ColorColumn ctermbg=lightgrey guibg=lightgrey
--- ``` --- ```
---
--- When 'textwidth' is zero then the items with '-' and '+' are not used. --- When 'textwidth' is zero then the items with '-' and '+' are not used.
--- A maximum of 256 columns are highlighted. --- A maximum of 256 columns are highlighted.
--- ---
@@ -1418,6 +1421,7 @@ vim.wo.crb = vim.wo.cursorbind
--- au WinEnter * set cursorline cursorcolumn --- au WinEnter * set cursorline cursorcolumn
--- ``` --- ```
--- ---
---
--- @type boolean --- @type boolean
vim.o.cursorcolumn = false vim.o.cursorcolumn = false
vim.o.cuc = vim.o.cursorcolumn vim.o.cuc = vim.o.cursorcolumn
@@ -1499,6 +1503,7 @@ vim.go.debug = vim.o.debug
--- let &l:define = '^\s*\ze\k\+\s*=\s*function(' --- let &l:define = '^\s*\ze\k\+\s*=\s*function('
--- ``` --- ```
--- ---
---
--- @type string --- @type string
vim.o.define = "" vim.o.define = ""
vim.o.def = vim.o.define vim.o.def = vim.o.define
@@ -1679,6 +1684,7 @@ vim.go.dex = vim.go.diffexpr
--- :set diffopt-=internal " do NOT use the internal diff parser --- :set diffopt-=internal " do NOT use the internal diff parser
--- ``` --- ```
--- ---
---
--- @type string --- @type string
vim.o.diffopt = "internal,filler,closeoff" vim.o.diffopt = "internal,filler,closeoff"
vim.o.dip = vim.o.diffopt vim.o.dip = vim.o.diffopt
@@ -1729,6 +1735,7 @@ vim.go.dg = vim.go.digraph
--- ``` --- ```
--- :set dir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces --- :set dir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces
--- ``` --- ```
---
--- Editing the same file twice will result in a warning. Using "/tmp" on --- Editing the same file twice will result in a warning. Using "/tmp" on
--- is discouraged: if the system crashes you lose the swap file. And --- is discouraged: if the system crashes you lose the swap file. And
--- others on the computer may be able to see the files. --- others on the computer may be able to see the files.
@@ -1917,6 +1924,7 @@ vim.go.efm = vim.go.errorformat
--- :set ei=WinEnter,WinLeave --- :set ei=WinEnter,WinLeave
--- ``` --- ```
--- ---
---
--- @type string --- @type string
vim.o.eventignore = "" vim.o.eventignore = ""
vim.o.ei = vim.o.eventignore vim.o.ei = vim.o.eventignore
@@ -2634,14 +2642,12 @@ vim.go.gp = vim.go.grepprg
--- To disable cursor-styling, reset the option: --- To disable cursor-styling, reset the option:
--- ``` --- ```
--- :set guicursor= --- :set guicursor=
---
--- ``` --- ```
--- To enable mode shapes, "Cursor" highlight, and blinking: --- To enable mode shapes, "Cursor" highlight, and blinking:
--- ``` --- ```
--- :set guicursor=n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50 --- :set guicursor=n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50
--- \,a:blinkwait700-blinkoff400-blinkon250-Cursor/lCursor --- \,a:blinkwait700-blinkoff400-blinkon250-Cursor/lCursor
--- \,sm:block-blinkwait175-blinkoff150-blinkon175 --- \,sm:block-blinkwait175-blinkoff150-blinkon175
---
--- ``` --- ```
--- The option is a comma-separated list of parts. Each part consists of a --- The option is a comma-separated list of parts. Each part consists of a
--- mode-list and an argument-list: --- mode-list and an argument-list:
@@ -2719,6 +2725,7 @@ vim.go.gp = vim.go.grepprg
--- :highlight Cursor gui=NONE guifg=bg guibg=fg --- :highlight Cursor gui=NONE guifg=bg guibg=fg
--- ``` --- ```
--- ---
---
--- @type string --- @type string
vim.o.guicursor = "n-v-c-sm:block,i-ci-ve:ver25,r-cr-o:hor20" vim.o.guicursor = "n-v-c-sm:block,i-ci-ve:ver25,r-cr-o:hor20"
vim.o.gcr = vim.o.guicursor vim.o.gcr = vim.o.guicursor
@@ -2790,6 +2797,7 @@ vim.go.gcr = vim.go.guicursor
--- :set guifont=Andale_Mono:h7.5:w4.5 --- :set guifont=Andale_Mono:h7.5:w4.5
--- ``` --- ```
--- ---
---
--- @type string --- @type string
vim.o.guifont = "" vim.o.guifont = ""
vim.o.gfn = vim.o.guifont vim.o.gfn = vim.o.guifont
@@ -2944,6 +2952,7 @@ vim.go.gtl = vim.go.guitablabel
--- :let &guitabtooltip = "line one\nline two" --- :let &guitabtooltip = "line one\nline two"
--- ``` --- ```
--- ---
---
--- @type string --- @type string
vim.o.guitabtooltip = "" vim.o.guitabtooltip = ""
vim.o.gtt = vim.o.guitabtooltip vim.o.gtt = vim.o.guitabtooltip
@@ -3206,6 +3215,7 @@ vim.go.inc = vim.go.include
--- ``` --- ```
--- :setlocal includeexpr=tr(v:fname,'.','/') --- :setlocal includeexpr=tr(v:fname,'.','/')
--- ``` --- ```
---
--- Also used for the `gf` command if an unmodified file name can't be --- Also used for the `gf` command if an unmodified file name can't be
--- found. Allows doing "gf" on the name after an 'include' statement. --- found. Allows doing "gf" on the name after an 'include' statement.
--- Also used for `<cfile>`. --- Also used for `<cfile>`.
@@ -3258,6 +3268,7 @@ vim.bo.inex = vim.bo.includeexpr
--- autocmd CmdlineLeave /,\? :set nohlsearch --- autocmd CmdlineLeave /,\? :set nohlsearch
--- augroup END --- augroup END
--- ``` --- ```
---
--- CTRL-L can be used to add one character from after the current match --- CTRL-L can be used to add one character from after the current match
--- to the command line. If 'ignorecase' and 'smartcase' are set and the --- to the command line. If 'ignorecase' and 'smartcase' are set and the
--- command line has no uppercase characters, the added character is --- command line has no uppercase characters, the added character is
@@ -3565,6 +3576,7 @@ vim.go.kp = vim.go.keywordprg
--- ``` --- ```
--- :set langmap=zy,yz,ZY,YZ --- :set langmap=zy,yz,ZY,YZ
--- ``` --- ```
---
--- The 'langmap' option is a list of parts, separated with commas. Each --- The 'langmap' option is a list of parts, separated with commas. Each
--- part can be in one of two forms: --- part can be in one of two forms:
--- 1. A list of pairs. Each pair is a "from" character immediately --- 1. A list of pairs. Each pair is a "from" character immediately
@@ -3762,6 +3774,7 @@ vim.go.lw = vim.go.lispwords
--- ``` --- ```
--- :set list lcs=tab:\ \ --- :set list lcs=tab:\ \
--- ``` --- ```
---
--- Note that list mode will also affect formatting (set with 'textwidth' --- Note that list mode will also affect formatting (set with 'textwidth'
--- or 'wrapmargin') when 'cpoptions' includes 'L'. See 'listchars' for --- or 'wrapmargin') when 'cpoptions' includes 'L'. See 'listchars' for
--- changing the way tabs are displayed. --- changing the way tabs are displayed.
@@ -3790,6 +3803,7 @@ vim.wo.list = vim.o.list
--- >-- --- >--
--- etc. --- etc.
--- ``` --- ```
---
--- tab:xyz The 'z' is always used, then 'x' is prepended, and --- tab:xyz The 'z' is always used, then 'x' is prepended, and
--- then 'y' is used as many times as will fit. Thus --- then 'y' is used as many times as will fit. Thus
--- "tab:<->" displays: --- "tab:<->" displays:
@@ -3801,6 +3815,7 @@ vim.wo.list = vim.o.list
--- <--> --- <-->
--- etc. --- etc.
--- ``` --- ```
---
--- When "tab:" is omitted, a tab is shown as ^I. --- When "tab:" is omitted, a tab is shown as ^I.
--- *lcs-space* --- *lcs-space*
--- space:c Character to show for a space. When omitted, spaces --- space:c Character to show for a space. When omitted, spaces
@@ -3816,6 +3831,7 @@ vim.wo.list = vim.o.list
--- ``` --- ```
--- ---+---+-- --- ---+---+--
--- ``` --- ```
---
--- *lcs-lead* --- *lcs-lead*
--- lead:c Character to show for leading spaces. When omitted, --- lead:c Character to show for leading spaces. When omitted,
--- leading spaces are blank. Overrides the "space" and --- leading spaces are blank. Overrides the "space" and
@@ -3824,6 +3840,7 @@ vim.wo.list = vim.o.list
--- ``` --- ```
--- :set listchars+=tab:>-,lead:. --- :set listchars+=tab:>-,lead:.
--- ``` --- ```
---
--- *lcs-leadmultispace* --- *lcs-leadmultispace*
--- leadmultispace:c... --- leadmultispace:c...
--- Like the `lcs-multispace` value, but for leading --- Like the `lcs-multispace` value, but for leading
@@ -3834,6 +3851,7 @@ vim.wo.list = vim.o.list
--- ``` --- ```
--- ---+---+--XXX --- ---+---+--XXX
--- ``` --- ```
---
--- Where "XXX" denotes the first non-blank characters in --- Where "XXX" denotes the first non-blank characters in
--- the line. --- the line.
--- *lcs-trail* --- *lcs-trail*
@@ -3941,6 +3959,7 @@ vim.go.mef = vim.go.makeef
--- :set makeencoding=char " system locale is used --- :set makeencoding=char " system locale is used
--- ``` --- ```
--- ---
---
--- @type string --- @type string
vim.o.makeencoding = "" vim.o.makeencoding = ""
vim.o.menc = vim.o.makeencoding vim.o.menc = vim.o.makeencoding
@@ -3986,13 +4005,11 @@ vim.go.mp = vim.go.makeprg
--- '>' (for HTML): --- '>' (for HTML):
--- ``` --- ```
--- :set mps+=<:> --- :set mps+=<:>
---
--- ``` --- ```
--- A more exotic example, to jump between the '=' and ';' in an --- A more exotic example, to jump between the '=' and ';' in an
--- assignment, useful for languages like C and Java: --- assignment, useful for languages like C and Java:
--- ``` --- ```
--- :au FileType c,cpp,java set mps+==:; --- :au FileType c,cpp,java set mps+==:;
---
--- ``` --- ```
--- For a more advanced way of using "%", see the matchit.vim plugin in --- For a more advanced way of using "%", see the matchit.vim plugin in
--- the $VIMRUNTIME/plugin directory. `add-local-help` --- the $VIMRUNTIME/plugin directory. `add-local-help`
@@ -4078,6 +4095,7 @@ vim.go.mis = vim.go.menuitems
--- ``` --- ```
--- {start},{inc},{added} --- {start},{inc},{added}
--- ``` --- ```
---
--- For most languages the uncompressed word tree fits in memory. {start} --- For most languages the uncompressed word tree fits in memory. {start}
--- gives the amount of memory in Kbyte that can be used before any --- gives the amount of memory in Kbyte that can be used before any
--- compression is done. It should be a bit smaller than the amount of --- compression is done. It should be a bit smaller than the amount of
@@ -4196,6 +4214,7 @@ vim.go.more = vim.o.more
--- ``` --- ```
--- :set mouse=nv --- :set mouse=nv
--- ``` --- ```
---
--- To temporarily disable mouse support, hold the shift key while using --- To temporarily disable mouse support, hold the shift key while using
--- the mouse. --- the mouse.
--- ---
@@ -4299,6 +4318,7 @@ vim.go.mh = vim.go.mousehide
--- :map <4-S-LeftDrag> <4-RightDrag> --- :map <4-S-LeftDrag> <4-RightDrag>
--- :map <4-S-LeftRelease> <4-RightRelease> --- :map <4-S-LeftRelease> <4-RightRelease>
--- ``` --- ```
---
--- Mouse commands requiring the CTRL modifier can be simulated by typing --- Mouse commands requiring the CTRL modifier can be simulated by typing
--- the "g" key before using the mouse: --- the "g" key before using the mouse:
--- "g<LeftMouse>" is "<C-LeftMouse> (jump to tag under mouse click) --- "g<LeftMouse>" is "<C-LeftMouse> (jump to tag under mouse click)
@@ -4477,6 +4497,7 @@ vim.bo.nf = vim.bo.nrformats
--- |there | 4 there | 1 there | 1 there --- |there | 4 there | 1 there | 1 there
--- ``` --- ```
--- ---
---
--- @type boolean --- @type boolean
vim.o.number = false vim.o.number = false
vim.o.nu = vim.o.number vim.o.nu = vim.o.number
@@ -4710,10 +4731,10 @@ vim.wo.pvw = vim.wo.previewwindow
--- the popupmenu using `highlight-blend`. For instance, to enable --- the popupmenu using `highlight-blend`. For instance, to enable
--- transparency but force the current selected element to be fully opaque: --- transparency but force the current selected element to be fully opaque:
--- ``` --- ```
---
--- :set pumblend=15 --- :set pumblend=15
--- :hi PmenuSel blend=0 --- :hi PmenuSel blend=0
--- ``` --- ```
---
--- UI-dependent. Works best with RGB colors. 'termguicolors' --- UI-dependent. Works best with RGB colors. 'termguicolors'
--- ---
--- @type integer --- @type integer
@@ -4986,6 +5007,7 @@ vim.go.ru = vim.go.ruler
--- :set rulerformat=%15(%c%V\ %p%%%) --- :set rulerformat=%15(%c%V\ %p%%%)
--- ``` --- ```
--- ---
---
--- @type string --- @type string
vim.o.rulerformat = "" vim.o.rulerformat = ""
vim.o.ruf = vim.o.rulerformat vim.o.ruf = vim.o.rulerformat
@@ -5363,6 +5385,7 @@ vim.go.ssop = vim.go.sessionoptions
--- ``` --- ```
--- :set shada='50,<1000,s100,:0,n~/nvim/shada --- :set shada='50,<1000,s100,:0,n~/nvim/shada
--- ``` --- ```
---
--- '50 Marks will be remembered for the last 50 files you --- '50 Marks will be remembered for the last 50 files you
--- edited. --- edited.
--- <1000 Contents of registers (up to 1000 lines each) will be --- <1000 Contents of registers (up to 1000 lines each) will be
@@ -5449,7 +5472,6 @@ vim.go.sdf = vim.go.shadafile
--- let &shellredir = '2>&1 | %%{ "$_" } | Out-File %s; exit $LastExitCode' --- let &shellredir = '2>&1 | %%{ "$_" } | Out-File %s; exit $LastExitCode'
--- let &shellpipe = '2>&1 | %%{ "$_" } | tee %s; exit $LastExitCode' --- let &shellpipe = '2>&1 | %%{ "$_" } | tee %s; exit $LastExitCode'
--- set shellquote= shellxquote= --- set shellquote= shellxquote=
---
--- ``` --- ```
--- This option cannot be set from a `modeline` or in the `sandbox`, for --- This option cannot be set from a `modeline` or in the `sandbox`, for
--- security reasons. --- security reasons.
@@ -5726,6 +5748,7 @@ vim.go.shm = vim.go.shortmess
--- :setlocal showbreak=NONE --- :setlocal showbreak=NONE
--- ``` --- ```
--- ---
---
--- @type string --- @type string
vim.o.showbreak = "" vim.o.showbreak = ""
vim.o.sbr = vim.o.showbreak vim.o.sbr = vim.o.showbreak
@@ -5858,15 +5881,16 @@ vim.go.ss = vim.go.sidescroll
--- setlocal sidescrolloff< --- setlocal sidescrolloff<
--- setlocal sidescrolloff=-1 --- setlocal sidescrolloff=-1
--- ``` --- ```
---
--- Example: Try this together with 'sidescroll' and 'listchars' as --- Example: Try this together with 'sidescroll' and 'listchars' as
--- in the following example to never allow the cursor to move --- in the following example to never allow the cursor to move
--- onto the "extends" character: --- onto the "extends" character:
--- ``` --- ```
---
--- :set nowrap sidescroll=1 listchars=extends:>,precedes:< --- :set nowrap sidescroll=1 listchars=extends:>,precedes:<
--- :set sidescrolloff=1 --- :set sidescrolloff=1
--- ``` --- ```
--- ---
---
--- @type integer --- @type integer
vim.o.sidescrolloff = 0 vim.o.sidescrolloff = 0
vim.o.siso = vim.o.sidescrolloff vim.o.siso = vim.o.sidescrolloff
@@ -6171,6 +6195,7 @@ vim.bo.spo = vim.bo.spelloptions
--- ``` --- ```
--- :set sps=file:~/.config/nvim/sugg,best,expr:MySuggest() --- :set sps=file:~/.config/nvim/sugg,best,expr:MySuggest()
--- ``` --- ```
---
--- This option cannot be set from a `modeline` or in the `sandbox`, for --- This option cannot be set from a `modeline` or in the `sandbox`, for
--- security reasons. --- security reasons.
--- ---
@@ -6263,6 +6288,7 @@ vim.go.sol = vim.go.startofline
--- handler should be written with this in mind. --- handler should be written with this in mind.
--- ---
--- Examples: --- Examples:
---
--- ```vim --- ```vim
--- " Relative number with bar separator and click handlers: --- " Relative number with bar separator and click handlers:
--- :set statuscolumn=%@SignCb@%s%=%T%@NumCb@%r│%T --- :set statuscolumn=%@SignCb@%s%=%T%@NumCb@%r│%T
@@ -6282,7 +6308,6 @@ vim.go.sol = vim.go.startofline
--- :let &stc='%#NonText#%{&nu?v:lnum:""}' . --- :let &stc='%#NonText#%{&nu?v:lnum:""}' .
--- '%=%{&rnu&&(v:lnum%2)?"\ ".v:relnum:""}' . --- '%=%{&rnu&&(v:lnum%2)?"\ ".v:relnum:""}' .
--- '%#LineNr#%{&rnu&&!(v:lnum%2)?"\ ".v:relnum:""}' --- '%#LineNr#%{&rnu&&!(v:lnum%2)?"\ ".v:relnum:""}'
---
--- ``` --- ```
--- WARNING: this expression is evaluated for each screen line so defining --- WARNING: this expression is evaluated for each screen line so defining
--- an expensive expression can negatively affect render performance. --- an expensive expression can negatively affect render performance.
@@ -6522,6 +6547,7 @@ vim.wo.stc = vim.wo.statuscolumn
--- :endfunction --- :endfunction
--- ``` --- ```
--- ---
---
--- @type string --- @type string
vim.o.statusline = "" vim.o.statusline = ""
vim.o.stl = vim.o.statusline vim.o.stl = vim.o.statusline
@@ -6553,6 +6579,7 @@ vim.go.su = vim.go.suffixes
--- :set suffixesadd=.java --- :set suffixesadd=.java
--- ``` --- ```
--- ---
---
--- @type string --- @type string
vim.o.suffixesadd = "" vim.o.suffixesadd = ""
vim.o.sua = vim.o.suffixesadd vim.o.sua = vim.o.suffixesadd
@@ -7445,6 +7472,7 @@ vim.go.ww = vim.go.whichwrap
--- :set wc=<Tab> --- :set wc=<Tab>
--- ``` --- ```
--- ---
---
--- @type integer --- @type integer
vim.o.wildchar = 9 vim.o.wildchar = 9
vim.o.wc = vim.o.wildchar vim.o.wc = vim.o.wildchar
@@ -7533,6 +7561,7 @@ vim.go.wic = vim.go.wildignorecase
--- :cnoremap <Left> <Space><BS><Left> --- :cnoremap <Left> <Space><BS><Left>
--- :cnoremap <Right> <Space><BS><Right> --- :cnoremap <Right> <Space><BS><Right>
--- ``` --- ```
---
--- `hl-WildMenu` highlights the current match. --- `hl-WildMenu` highlights the current match.
--- ---
--- @type boolean --- @type boolean
@@ -7762,6 +7791,7 @@ vim.go.wh = vim.go.winheight
--- set winhighlight=Normal:MyNormal,NormalNC:MyNormalNC --- set winhighlight=Normal:MyNormal,NormalNC:MyNormalNC
--- ``` --- ```
--- ---
---
--- @type string --- @type string
vim.o.winhighlight = "" vim.o.winhighlight = ""
vim.o.winhl = vim.o.winhighlight vim.o.winhl = vim.o.winhighlight

15
runtime/lua/vim/_meta/spell.lua
View File

@@ -10,13 +10,14 @@
--- the buffer. Consider calling this with |nvim_buf_call()|. --- the buffer. Consider calling this with |nvim_buf_call()|.
--- ---
--- Example: --- Example:
--- <pre>lua ---
--- vim.spell.check("the quik brown fox") --- ```lua
--- -- => --- vim.spell.check("the quik brown fox")
--- -- { --- -- =>
--- -- {'quik', 'bad', 5} --- -- {
--- -- } --- -- {'quik', 'bad', 5}
--- </pre> --- -- }
--- ```
--- ---
--- @param str string --- @param str string
--- @return {[1]: string, [2]: string, [3]: string}[] --- @return {[1]: string, [2]: string, [3]: string}[]

231
runtime/lua/vim/_options.lua
View File

@@ -7,11 +7,12 @@
---"references". |lua-guide-variables| For example, using \`vim.fn.remove()\` on ---"references". |lua-guide-variables| For example, using \`vim.fn.remove()\` on
---a Lua list copies the list object to Vimscript and does NOT modify the Lua ---a Lua list copies the list object to Vimscript and does NOT modify the Lua
---list: ---list:
---<pre>lua ---
--- local list = { 1, 2, 3 } --- ```lua
--- vim.fn.remove(list, 0) --- local list = { 1, 2, 3 }
--- vim.print(list) --> "{ 1, 2, 3 }" --- vim.fn.remove(list, 0)
---</pre> --- vim.print(list) --> "{ 1, 2, 3 }"
--- ```
---@addtogroup lua-vimscript ---@addtogroup lua-vimscript
---@brief <pre>help ---@brief <pre>help
@@ -131,13 +132,17 @@ local function get_options_info(name)
return info return info
end end
---Environment variables defined in the editor session. --- Environment variables defined in the editor session.
---See |expand-env| and |:let-environment| for the Vimscript behavior. --- See |expand-env| and |:let-environment| for the Vimscript behavior.
---Invalid or unset key returns `nil`. --- Invalid or unset key returns `nil`.
---Example: <pre>lua ---
--- vim.env.FOO = 'bar' --- Example:
--- print(vim.env.TERM) ---
---</pre> --- ```lua
--- vim.env.FOO = 'bar'
--- print(vim.env.TERM)
--- ```
---
---@param var string ---@param var string
vim.env = setmetatable({}, { vim.env = setmetatable({}, {
__index = function(_, k) __index = function(_, k)
@@ -226,16 +231,18 @@ end
---global value of a |global-local| option, see |:setglobal|. ---global value of a |global-local| option, see |:setglobal|.
---</pre> ---</pre>
---Get or set |options|. Like `:set`. Invalid key is an error. --- Get or set |options|. Like `:set`. Invalid key is an error.
--- ---
---Note: this works on both buffer-scoped and window-scoped options using the --- Note: this works on both buffer-scoped and window-scoped options using the
---current buffer and window. --- current buffer and window.
--- ---
---Example: <pre>lua --- Example:
--- vim.o.cmdheight = 4 ---
--- print(vim.o.columns) --- ```lua
--- print(vim.o.foo) -- error: invalid key --- vim.o.cmdheight = 4
---</pre> --- print(vim.o.columns)
--- print(vim.o.foo) -- error: invalid key
--- ```
vim.o = setmetatable({}, { vim.o = setmetatable({}, {
__index = function(_, k) __index = function(_, k)
return api.nvim_get_option_value(k, {}) return api.nvim_get_option_value(k, {})
@@ -245,18 +252,20 @@ vim.o = setmetatable({}, {
end, end,
}) })
---Get or set global |options|. Like `:setglobal`. Invalid key is --- Get or set global |options|. Like `:setglobal`. Invalid key is
---an error. --- an error.
--- ---
---Note: this is different from |vim.o| because this accesses the global --- Note: this is different from |vim.o| because this accesses the global
---option value and thus is mostly useful for use with |global-local| --- option value and thus is mostly useful for use with |global-local|
---options. --- options.
--- ---
---Example: <pre>lua --- Example:
--- vim.go.cmdheight = 4 ---
--- print(vim.go.columns) --- ```lua
--- print(vim.go.bar) -- error: invalid key --- vim.go.cmdheight = 4
---</pre> --- print(vim.go.columns)
--- print(vim.go.bar) -- error: invalid key
--- ```
vim.go = setmetatable({}, { vim.go = setmetatable({}, {
__index = function(_, k) __index = function(_, k)
return api.nvim_get_option_value(k, { scope = 'global' }) return api.nvim_get_option_value(k, { scope = 'global' })
@@ -266,37 +275,39 @@ vim.go = setmetatable({}, {
end, end,
}) })
---Get or set buffer-scoped |options| for the buffer with number {bufnr}. --- Get or set buffer-scoped |options| for the buffer with number {bufnr}.
---Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current --- Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current
---buffer is used. Invalid {bufnr} or key is an error. --- buffer is used. Invalid {bufnr} or key is an error.
--- ---
---Note: this is equivalent to both `:set` and `:setlocal`. --- Note: this is equivalent to both `:set` and `:setlocal`.
--- ---
---Example: <pre>lua --- Example:
--- local bufnr = vim.api.nvim_get_current_buf() ---
--- vim.bo[bufnr].buflisted = true -- same as vim.bo.buflisted = true --- ```lua
--- print(vim.bo.comments) --- local bufnr = vim.api.nvim_get_current_buf()
--- print(vim.bo.baz) -- error: invalid key --- vim.bo[bufnr].buflisted = true -- same as vim.bo.buflisted = true
---</pre> --- print(vim.bo.comments)
---@param bufnr integer|nil --- print(vim.bo.baz) -- error: invalid key
--- ```
vim.bo = new_buf_opt_accessor() vim.bo = new_buf_opt_accessor()
---Get or set window-scoped |options| for the window with handle {winid} and --- Get or set window-scoped |options| for the window with handle {winid} and
---buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like --- buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like
---`:set` otherwise. If [{winid}] is omitted then the current window is --- `:set` otherwise. If [{winid}] is omitted then the current window is
---used. Invalid {winid}, {bufnr} or key is an error. --- used. Invalid {winid}, {bufnr} or key is an error.
--- ---
---Note: only {bufnr} with value `0` (the current buffer in the window) is --- Note: only {bufnr} with value `0` (the current buffer in the window) is
---supported. --- supported.
--- ---
---Example: <pre>lua --- Example:
--- local winid = vim.api.nvim_get_current_win()
--- vim.wo[winid].number = true -- same as vim.wo.number = true
--- print(vim.wo.foldmarker)
--- print(vim.wo.quux) -- error: invalid key
--- vim.wo[winid][0].spell = false -- like ':setlocal nospell'
--- ---
---</pre> --- ```lua
--- local winid = vim.api.nvim_get_current_win()
--- vim.wo[winid].number = true -- same as vim.wo.number = true
--- print(vim.wo.foldmarker)
--- print(vim.wo.quux) -- error: invalid key
--- vim.wo[winid][0].spell = false -- like ':setlocal nospell'
--- ```
vim.wo = new_win_opt_accessor() vim.wo = new_win_opt_accessor()
---@brief [[ ---@brief [[
@@ -795,77 +806,93 @@ end
--- @diagnostic disable-next-line:unused-local used for gen_vimdoc --- @diagnostic disable-next-line:unused-local used for gen_vimdoc
local Option = {} -- luacheck: no unused local Option = {} -- luacheck: no unused
---Returns a Lua-representation of the option. Boolean, number and string --- Returns a Lua-representation of the option. Boolean, number and string
---values will be returned in exactly the same fashion. --- values will be returned in exactly the same fashion.
--- ---
---For values that are comma-separated lists, an array will be returned with --- For values that are comma-separated lists, an array will be returned with
---the values as entries in the array: <pre>lua --- the values as entries in the array:
--- vim.cmd [[set wildignore=*.pyc,*.o]]
--- ---
--- vim.print(vim.opt.wildignore:get()) --- ```lua
--- -- { "*.pyc", "*.o", } --- vim.cmd [[set wildignore=*.pyc,*.o]]
--- ---
--- for _, ignore_pattern in ipairs(vim.opt.wildignore:get()) do --- vim.print(vim.opt.wildignore:get())
--- print("Will ignore:", ignore_pattern) --- -- { "*.pyc", "*.o", }
--- end
--- -- Will ignore: *.pyc
--- -- Will ignore: *.o
---</pre>
--- ---
---For values that are comma-separated maps, a table will be returned with --- for _, ignore_pattern in ipairs(vim.opt.wildignore:get()) do
---the names as keys and the values as entries: <pre>lua --- print("Will ignore:", ignore_pattern)
--- vim.cmd [[set listchars=space:_,tab:>~]] --- end
--- -- Will ignore: *.pyc
--- -- Will ignore: *.o
--- ```
--- ---
--- vim.print(vim.opt.listchars:get()) --- For values that are comma-separated maps, a table will be returned with
--- -- { space = "_", tab = ">~", } --- the names as keys and the values as entries:
--- ---
--- for char, representation in pairs(vim.opt.listchars:get()) do --- ```lua
--- print(char, "=>", representation) --- vim.cmd [[set listchars=space:_,tab:>~]]
--- end
---</pre>
--- ---
---For values that are lists of flags, a set will be returned with the flags --- vim.print(vim.opt.listchars:get())
---as keys and `true` as entries. <pre>lua --- -- { space = "_", tab = ">~", }
--- vim.cmd [[set formatoptions=njtcroql]]
--- ---
--- vim.print(vim.opt.formatoptions:get()) --- for char, representation in pairs(vim.opt.listchars:get()) do
--- -- { n = true, j = true, c = true, ... } --- print(char, "=>", representation)
--- end
--- ```
---
--- For values that are lists of flags, a set will be returned with the flags
--- as keys and `true` as entries.
---
--- ```lua
--- vim.cmd [[set formatoptions=njtcroql]]
---
--- vim.print(vim.opt.formatoptions:get())
--- -- { n = true, j = true, c = true, ... }
---
--- local format_opts = vim.opt.formatoptions:get()
--- if format_opts.j then
--- print("J is enabled!")
--- end
--- ```
--- ---
--- local format_opts = vim.opt.formatoptions:get()
--- if format_opts.j then
--- print("J is enabled!")
--- end
---</pre>
---@return string|integer|boolean|nil value of option ---@return string|integer|boolean|nil value of option
---@diagnostic disable-next-line:unused-local used for gen_vimdoc ---@diagnostic disable-next-line:unused-local used for gen_vimdoc
function Option:get() end function Option:get() end
---Append a value to string-style options. See |:set+=| --- Append a value to string-style options. See |:set+=|
---
--- These are equivalent:
---
--- ```lua
--- vim.opt.formatoptions:append('j')
--- vim.opt.formatoptions = vim.opt.formatoptions + 'j'
--- ```
--- ---
---These are equivalent: <pre>lua
--- vim.opt.formatoptions:append('j')
--- vim.opt.formatoptions = vim.opt.formatoptions + 'j'
---</pre>
---@param value string Value to append ---@param value string Value to append
--- @diagnostic disable-next-line:unused-local used for gen_vimdoc ---@diagnostic disable-next-line:unused-local used for gen_vimdoc
function Option:append(value) end -- luacheck: no unused function Option:append(value) end -- luacheck: no unused
---Prepend a value to string-style options. See |:set^=| --- Prepend a value to string-style options. See |:set^=|
---
--- These are equivalent:
---
--- ```lua
--- vim.opt.wildignore:prepend('*.o')
--- vim.opt.wildignore = vim.opt.wildignore ^ '*.o'
--- ```
--- ---
---These are equivalent: <pre>lua
--- vim.opt.wildignore:prepend('*.o')
--- vim.opt.wildignore = vim.opt.wildignore ^ '*.o'
---</pre>
---@param value string Value to prepend ---@param value string Value to prepend
---@diagnostic disable-next-line:unused-local used for gen_vimdoc ---@diagnostic disable-next-line:unused-local used for gen_vimdoc
function Option:prepend(value) end -- luacheck: no unused function Option:prepend(value) end -- luacheck: no unused
---Remove a value from string-style options. See |:set-=| --- Remove a value from string-style options. See |:set-=|
---
--- These are equivalent:
---
--- ```lua
--- vim.opt.wildignore:remove('*.pyc')
--- vim.opt.wildignore = vim.opt.wildignore - '*.pyc'
--- ```
--- ---
---These are equivalent: <pre>lua
--- vim.opt.wildignore:remove('*.pyc')
--- vim.opt.wildignore = vim.opt.wildignore - '*.pyc'
---</pre>
---@param value string Value to remove ---@param value string Value to remove
---@diagnostic disable-next-line:unused-local used for gen_vimdoc ---@diagnostic disable-next-line:unused-local used for gen_vimdoc
function Option:remove(value) end -- luacheck: no unused function Option:remove(value) end -- luacheck: no unused

32
runtime/lua/vim/diagnostic.lua
View File

@@ -553,14 +553,16 @@ end
--- followed by namespace configuration, and finally global configuration. --- followed by namespace configuration, and finally global configuration.
--- ---
--- For example, if a user enables virtual text globally with --- For example, if a user enables virtual text globally with
--- <pre>lua ---
--- vim.diagnostic.config({ virtual_text = true }) --- ```lua
--- </pre> --- vim.diagnostic.config({ virtual_text = true })
--- ```
--- ---
--- and a diagnostic producer sets diagnostics with --- and a diagnostic producer sets diagnostics with
--- <pre>lua ---
--- vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false }) --- ```lua
--- </pre> --- vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false })
--- ```
--- ---
--- then virtual text will not be enabled for those diagnostics. --- then virtual text will not be enabled for those diagnostics.
--- ---
@@ -1601,18 +1603,20 @@ end
--- Parse a diagnostic from a string. --- Parse a diagnostic from a string.
--- ---
--- For example, consider a line of output from a linter: --- For example, consider a line of output from a linter:
--- <pre> ---
--- ```
--- WARNING filename:27:3: Variable 'foo' does not exist --- WARNING filename:27:3: Variable 'foo' does not exist
--- </pre> --- ```
--- ---
--- This can be parsed into a diagnostic |diagnostic-structure| --- This can be parsed into a diagnostic |diagnostic-structure|
--- with: --- with:
--- <pre>lua ---
--- local s = "WARNING filename:27:3: Variable 'foo' does not exist" --- ```lua
--- local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$" --- local s = "WARNING filename:27:3: Variable 'foo' does not exist"
--- local groups = { "severity", "lnum", "col", "message" } --- local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
--- vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN }) --- local groups = { "severity", "lnum", "col", "message" }
--- </pre> --- vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
--- ```
--- ---
---@param str string String to parse diagnostics from. ---@param str string String to parse diagnostics from.
---@param pat string Lua pattern with capture groups. ---@param pat string Lua pattern with capture groups.

101
runtime/lua/vim/filetype.lua
View File

@@ -2081,43 +2081,45 @@ end
--- See $VIMRUNTIME/lua/vim/filetype.lua for more examples. --- See $VIMRUNTIME/lua/vim/filetype.lua for more examples.
--- ---
--- Example: --- Example:
--- <pre>lua ---
--- vim.filetype.add({ --- ```lua
--- extension = { --- vim.filetype.add({
--- foo = 'fooscript', --- extension = {
--- bar = function(path, bufnr) --- foo = 'fooscript',
--- if some_condition() then --- bar = function(path, bufnr)
--- return 'barscript', function(bufnr) --- if some_condition() then
--- -- Set a buffer variable --- return 'barscript', function(bufnr)
--- vim.b[bufnr].barscript_version = 2 --- -- Set a buffer variable
--- end --- vim.b[bufnr].barscript_version = 2
--- end --- end
--- return 'bar' --- end
--- end, --- return 'bar'
--- }, --- end,
--- filename = { --- },
--- ['.foorc'] = 'toml', --- filename = {
--- ['/etc/foo/config'] = 'toml', --- ['.foorc'] = 'toml',
--- }, --- ['/etc/foo/config'] = 'toml',
--- pattern = { --- },
--- ['.*/etc/foo/.*'] = 'fooscript', --- pattern = {
--- -- Using an optional priority --- ['.*/etc/foo/.*'] = 'fooscript',
--- ['.*/etc/foo/.*%.conf'] = { 'dosini', { priority = 10 } }, --- -- Using an optional priority
--- -- A pattern containing an environment variable --- ['.*/etc/foo/.*%.conf'] = { 'dosini', { priority = 10 } },
--- ['${XDG_CONFIG_HOME}/foo/git'] = 'git', --- -- A pattern containing an environment variable
--- ['README.(%a+)$'] = function(path, bufnr, ext) --- ['${XDG_CONFIG_HOME}/foo/git'] = 'git',
--- if ext == 'md' then --- ['README.(%a+)$'] = function(path, bufnr, ext)
--- return 'markdown' --- if ext == 'md' then
--- elseif ext == 'rst' then --- return 'markdown'
--- return 'rst' --- elseif ext == 'rst' then
--- end --- return 'rst'
--- end, --- end
--- }, --- end,
--- }) --- },
--- </pre> --- })
--- ```
--- ---
--- To add a fallback match on contents, use --- To add a fallback match on contents, use
--- <pre>lua ---
--- ```lua
--- vim.filetype.add { --- vim.filetype.add {
--- pattern = { --- pattern = {
--- ['.*'] = { --- ['.*'] = {
@@ -2133,7 +2135,7 @@ end
--- }, --- },
--- }, --- },
--- } --- }
--- </pre> --- ```
--- ---
---@param filetypes vim.filetype.add.filetypes A table containing new filetype maps (see example). ---@param filetypes vim.filetype.add.filetypes A table containing new filetype maps (see example).
function M.add(filetypes) function M.add(filetypes)
@@ -2256,19 +2258,19 @@ end
--- Each of the three options is specified using a key to the single argument of this function. --- Each of the three options is specified using a key to the single argument of this function.
--- Example: --- Example:
--- ---
--- <pre>lua --- ```lua
--- -- Using a buffer number --- -- Using a buffer number
--- vim.filetype.match({ buf = 42 }) --- vim.filetype.match({ buf = 42 })
--- ---
--- -- Override the filename of the given buffer --- -- Override the filename of the given buffer
--- vim.filetype.match({ buf = 42, filename = 'foo.c' }) --- vim.filetype.match({ buf = 42, filename = 'foo.c' })
--- ---
--- -- Using a filename without a buffer --- -- Using a filename without a buffer
--- vim.filetype.match({ filename = 'main.lua' }) --- vim.filetype.match({ filename = 'main.lua' })
--- ---
--- -- Using file contents --- -- Using file contents
--- vim.filetype.match({ contents = {'#!/usr/bin/env bash'} }) --- vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })
--- </pre> --- ```
--- ---
---@param args vim.filetype.match.args Table specifying which matching strategy to use. ---@param args vim.filetype.match.args Table specifying which matching strategy to use.
--- Accepted keys are: --- Accepted keys are:
@@ -2404,9 +2406,10 @@ end
--- is set, meaning it should respect all FileType autocmds and ftplugin files. --- is set, meaning it should respect all FileType autocmds and ftplugin files.
--- ---
--- Example: --- Example:
--- <pre>lua ---
--- vim.filetype.get_option('vim', 'commentstring') --- ```lua
--- </pre> --- vim.filetype.get_option('vim', 'commentstring')
--- ```
--- ---
--- Note: this uses |nvim_get_option_value()| but caches the result. --- Note: this uses |nvim_get_option_value()| but caches the result.
--- This means |ftplugin| and |FileType| autocommands are only --- This means |ftplugin| and |FileType| autocommands are only

27
runtime/lua/vim/fs.lua
View File

@@ -5,7 +5,8 @@ local iswin = vim.uv.os_uname().sysname == 'Windows_NT'
--- Iterate over all the parents of the given path. --- Iterate over all the parents of the given path.
--- ---
--- Example: --- Example:
--- <pre>lua ---
--- ```lua
--- local root_dir --- local root_dir
--- for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do --- for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do
--- if vim.fn.isdirectory(dir .. "/.git") == 1 then --- if vim.fn.isdirectory(dir .. "/.git") == 1 then
@@ -17,7 +18,7 @@ local iswin = vim.uv.os_uname().sysname == 'Windows_NT'
--- if root_dir then --- if root_dir then
--- print("Found git repository at", root_dir) --- print("Found git repository at", root_dir)
--- end --- end
--- </pre> --- ```
--- ---
---@param start (string) Initial path. ---@param start (string) Initial path.
---@return fun(_, dir: string): string? # Iterator ---@return fun(_, dir: string): string? # Iterator
@@ -165,7 +166,8 @@ end
--- to narrow the search to find only that type. --- to narrow the search to find only that type.
--- ---
--- Examples: --- Examples:
--- <pre>lua ---
--- ```lua
--- -- location of Cargo.toml from the current buffer's path --- -- location of Cargo.toml from the current buffer's path
--- local cargo = vim.fs.find('Cargo.toml', { --- local cargo = vim.fs.find('Cargo.toml', {
--- upward = true, --- upward = true,
@@ -183,7 +185,7 @@ end
--- local cpp_hpp = vim.fs.find(function(name, path) --- local cpp_hpp = vim.fs.find(function(name, path)
--- return name:match('.*%.[ch]pp$') and path:match('[/\\\\]lib$') --- return name:match('.*%.[ch]pp$') and path:match('[/\\\\]lib$')
--- end, {limit = math.huge, type = 'file'}) --- end, {limit = math.huge, type = 'file'})
--- </pre> --- ```
--- ---
---@param names (string|string[]|fun(name: string, path: string): boolean) Names of the items to find. ---@param names (string|string[]|fun(name: string, path: string): boolean) Names of the items to find.
--- Must be base names, paths and globs are not supported when {names} is a string or a table. --- Must be base names, paths and globs are not supported when {names} is a string or a table.
@@ -322,16 +324,17 @@ end
--- variables are also expanded. --- variables are also expanded.
--- ---
--- Examples: --- Examples:
--- <pre>lua
--- vim.fs.normalize('C:\\\\Users\\\\jdoe')
--- --> 'C:/Users/jdoe'
--- ---
--- vim.fs.normalize('~/src/neovim') --- ```lua
--- --> '/home/jdoe/src/neovim' --- vim.fs.normalize('C:\\\\Users\\\\jdoe')
--- -- 'C:/Users/jdoe'
--- ---
--- vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim') --- vim.fs.normalize('~/src/neovim')
--- --> '/Users/jdoe/.config/nvim/init.vim' --- -- '/home/jdoe/src/neovim'
--- </pre> ---
--- vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim')
--- -- '/Users/jdoe/.config/nvim/init.vim'
--- ```
--- ---
---@param path (string) Path to normalize ---@param path (string) Path to normalize
---@param opts table|nil Options: ---@param opts table|nil Options:

31
runtime/lua/vim/highlight.lua
View File

@@ -1,23 +1,24 @@
---@defgroup vim.highlight ---@defgroup vim.highlight
--- ---
---@brief --- Nvim includes a function for highlighting a selection on yank.
---Nvim includes a function for highlighting a selection on yank.
--- ---
---To enable it, add the following to your `init.vim`: --- To enable it, add the following to your `init.vim`:
---<pre>vim
--- au TextYankPost * silent! lua vim.highlight.on_yank()
---</pre>
--- ---
---You can customize the highlight group and the duration of --- ```vim
---the highlight via: --- au TextYankPost * silent! lua vim.highlight.on_yank()
---<pre>vim --- ```
--- au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150}
---</pre>
--- ---
---If you want to exclude visual selections from highlighting on yank, use: --- You can customize the highlight group and the duration of the highlight via:
---<pre>vim ---
--- au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false} --- ```vim
---</pre> --- au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150}
--- ```
---
--- If you want to exclude visual selections from highlighting on yank, use:
---
--- ```vim
--- au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false}
--- ```
local api = vim.api local api = vim.api

39
runtime/lua/vim/keymap.lua
View File

@@ -2,20 +2,21 @@ local keymap = {}
--- Adds a new |mapping|. --- Adds a new |mapping|.
--- Examples: --- Examples:
--- <pre>lua ---
--- -- Map to a Lua function: --- ```lua
--- vim.keymap.set('n', 'lhs', function() print("real lua function") end) --- -- Map to a Lua function:
--- -- Map to multiple modes: --- vim.keymap.set('n', 'lhs', function() print("real lua function") end)
--- vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, { buffer = true }) --- -- Map to multiple modes:
--- -- Buffer-local mapping: --- vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, { buffer = true })
--- vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", { silent = true, buffer = 5 }) --- -- Buffer-local mapping:
--- -- Expr mapping: --- vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", { silent = true, buffer = 5 })
--- vim.keymap.set('i', '<Tab>', function() --- -- Expr mapping:
--- return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>" --- vim.keymap.set('i', '<Tab>', function()
--- end, { expr = true }) --- return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>"
--- -- <Plug> mapping: --- end, { expr = true })
--- vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)') --- -- <Plug> mapping:
--- </pre> --- vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')
--- ```
--- ---
---@param mode string|table Mode short-name, see |nvim_set_keymap()|. ---@param mode string|table Mode short-name, see |nvim_set_keymap()|.
--- Can also be list of modes to create mapping on multiple modes. --- Can also be list of modes to create mapping on multiple modes.
@@ -80,11 +81,13 @@ end
--- Remove an existing mapping. --- Remove an existing mapping.
--- Examples: --- Examples:
--- <pre>lua
--- vim.keymap.del('n', 'lhs')
--- ---
--- vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buffer = 5 }) --- ```lua
--- </pre> --- vim.keymap.del('n', 'lhs')
---
--- vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buffer = 5 })
--- ```
---
---@param opts table|nil A table of optional arguments: ---@param opts table|nil A table of optional arguments:
--- - "buffer": (number|boolean) Remove a mapping from the given buffer. --- - "buffer": (number|boolean) Remove a mapping from the given buffer.
--- When `0` or `true`, use the current buffer. --- When `0` or `true`, use the current buffer.

17
runtime/lua/vim/lsp.lua
View File

@@ -809,13 +809,14 @@ end
--- Attaches the current buffer to the client. --- Attaches the current buffer to the client.
--- ---
--- Example: --- Example:
--- <pre>lua ---
--- ```lua
--- vim.lsp.start({ --- vim.lsp.start({
--- name = 'my-server-name', --- name = 'my-server-name',
--- cmd = {'name-of-language-server-executable'}, --- cmd = {'name-of-language-server-executable'},
--- root_dir = vim.fs.dirname(vim.fs.find({'pyproject.toml', 'setup.py'}, { upward = true })[1]), --- root_dir = vim.fs.dirname(vim.fs.find({'pyproject.toml', 'setup.py'}, { upward = true })[1]),
--- }) --- })
--- </pre> --- ```
--- ---
--- See |vim.lsp.start_client()| for all available options. The most important are: --- See |vim.lsp.start_client()| for all available options. The most important are:
--- ---
@@ -1988,9 +1989,10 @@ end
--- ---
--- You can also use the `stop()` function on a |vim.lsp.client| object. --- You can also use the `stop()` function on a |vim.lsp.client| object.
--- To stop all clients: --- To stop all clients:
--- <pre>lua ---
--- ```lua
--- vim.lsp.stop_client(vim.lsp.get_clients()) --- vim.lsp.stop_client(vim.lsp.get_clients())
--- </pre> --- ```
--- ---
--- By default asks the server to shutdown, unless stop was requested --- By default asks the server to shutdown, unless stop was requested
--- already for this client, then force-shutdown is attempted. --- already for this client, then force-shutdown is attempted.
@@ -2502,12 +2504,7 @@ end
---@param bufnr integer Buffer number ---@param bufnr integer Buffer number
---@param fn function Function to run on each client attached to buffer ---@param fn function Function to run on each client attached to buffer
--- {bufnr}. The function takes the client, client ID, and --- {bufnr}. The function takes the client, client ID, and
--- buffer number as arguments. Example: --- buffer number as arguments.
--- <pre>lua
--- vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr)
--- vim.print(client)
--- end)
--- </pre>
---@deprecated use lsp.get_clients({ bufnr = bufnr }) with regular loop ---@deprecated use lsp.get_clients({ bufnr = bufnr }) with regular loop
function lsp.for_each_buffer_client(bufnr, fn) function lsp.for_each_buffer_client(bufnr, fn)
return for_each_buffer_client(bufnr, fn) return for_each_buffer_client(bufnr, fn)

23
runtime/lua/vim/lsp/buf.lua
View File

@@ -168,13 +168,11 @@ end
--- ---
--- - filter (function|nil): --- - filter (function|nil):
--- Predicate used to filter clients. Receives a client as argument and must return a --- Predicate used to filter clients. Receives a client as argument and must return a
--- boolean. Clients matching the predicate are included. Example: --- boolean. Clients matching the predicate are included. Example: <pre>lua
--- --- -- Never request typescript-language-server for formatting
--- <pre>lua --- vim.lsp.buf.format {
--- -- Never request typescript-language-server for formatting --- filter = function(client) return client.name ~= "tsserver" end
--- vim.lsp.buf.format { --- }
--- filter = function(client) return client.name ~= "tsserver" end
--- }
--- </pre> --- </pre>
--- ---
--- - async boolean|nil --- - async boolean|nil
@@ -555,11 +553,12 @@ end
--- Send request to the server to resolve document highlights for the current --- Send request to the server to resolve document highlights for the current
--- text document position. This request can be triggered by a key mapping or --- text document position. This request can be triggered by a key mapping or
--- by events such as `CursorHold`, e.g.: --- by events such as `CursorHold`, e.g.:
--- <pre>vim ---
--- autocmd CursorHold <buffer> lua vim.lsp.buf.document_highlight() --- ```vim
--- autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight() --- autocmd CursorHold <buffer> lua vim.lsp.buf.document_highlight()
--- autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references() --- autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight()
--- </pre> --- autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()
--- ```
--- ---
--- Note: Usage of |vim.lsp.buf.document_highlight()| requires the following highlight groups --- Note: Usage of |vim.lsp.buf.document_highlight()| requires the following highlight groups
--- to be defined or you won't be able to see the actual highlights. --- to be defined or you won't be able to see the actual highlights.

6
runtime/lua/vim/lsp/codelens.lua
View File

@@ -255,10 +255,10 @@ end
--- It is recommended to trigger this using an autocmd or via keymap. --- It is recommended to trigger this using an autocmd or via keymap.
--- ---
--- Example: --- Example:
--- <pre>vim
--- autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
--- </pre>
--- ---
--- ```vim
--- autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
--- ```
function M.refresh() function M.refresh()
local params = { local params = {
textDocument = util.make_text_document_params(), textDocument = util.make_text_document_params(),

10
runtime/lua/vim/lsp/diagnostic.lua
View File

@@ -203,7 +203,8 @@ end
--- ---
--- See |vim.diagnostic.config()| for configuration options. Handler-specific --- See |vim.diagnostic.config()| for configuration options. Handler-specific
--- configuration can be set using |vim.lsp.with()|: --- configuration can be set using |vim.lsp.with()|:
--- <pre>lua ---
--- ```lua
--- vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with( --- vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
--- vim.lsp.diagnostic.on_publish_diagnostics, { --- vim.lsp.diagnostic.on_publish_diagnostics, {
--- -- Enable underline, use default values --- -- Enable underline, use default values
@@ -221,7 +222,7 @@ end
--- update_in_insert = false, --- update_in_insert = false,
--- } --- }
--- ) --- )
--- </pre> --- ```
--- ---
---@param config table Configuration table (see |vim.diagnostic.config()|). ---@param config table Configuration table (see |vim.diagnostic.config()|).
function M.on_publish_diagnostics(_, result, ctx, config) function M.on_publish_diagnostics(_, result, ctx, config)
@@ -263,7 +264,8 @@ end
--- ---
--- See |vim.diagnostic.config()| for configuration options. Handler-specific --- See |vim.diagnostic.config()| for configuration options. Handler-specific
--- configuration can be set using |vim.lsp.with()|: --- configuration can be set using |vim.lsp.with()|:
--- <pre>lua ---
--- ```lua
--- vim.lsp.handlers["textDocument/diagnostic"] = vim.lsp.with( --- vim.lsp.handlers["textDocument/diagnostic"] = vim.lsp.with(
--- vim.lsp.diagnostic.on_diagnostic, { --- vim.lsp.diagnostic.on_diagnostic, {
--- -- Enable underline, use default values --- -- Enable underline, use default values
@@ -281,7 +283,7 @@ end
--- update_in_insert = false, --- update_in_insert = false,
--- } --- }
--- ) --- )
--- </pre> --- ```
--- ---
---@param config table Configuration table (see |vim.diagnostic.config()|). ---@param config table Configuration table (see |vim.diagnostic.config()|).
function M.on_diagnostic(_, result, ctx, config) function M.on_diagnostic(_, result, ctx, config)

43
runtime/lua/vim/lsp/handlers.lua
View File

@@ -342,16 +342,18 @@ M[ms.textDocument_completion] = function(_, result, _, _)
end end
--- |lsp-handler| for the method "textDocument/hover" --- |lsp-handler| for the method "textDocument/hover"
--- <pre>lua ---
--- vim.lsp.handlers["textDocument/hover"] = vim.lsp.with( --- ```lua
--- vim.lsp.handlers.hover, { --- vim.lsp.handlers["textDocument/hover"] = vim.lsp.with(
--- -- Use a sharp border with `FloatBorder` highlights --- vim.lsp.handlers.hover, {
--- border = "single", --- -- Use a sharp border with `FloatBorder` highlights
--- -- add the title in hover float window --- border = "single",
--- title = "hover" --- -- add the title in hover float window
--- } --- title = "hover"
--- ) --- }
--- </pre> --- )
--- ```
---
---@param config table Configuration table. ---@param config table Configuration table.
--- - border: (default=nil) --- - border: (default=nil)
--- - Add borders to the floating window --- - Add borders to the floating window
@@ -430,15 +432,20 @@ M[ms.textDocument_typeDefinition] = location_handler
M[ms.textDocument_implementation] = location_handler M[ms.textDocument_implementation] = location_handler
--- |lsp-handler| for the method "textDocument/signatureHelp". --- |lsp-handler| for the method "textDocument/signatureHelp".
---
--- The active parameter is highlighted with |hl-LspSignatureActiveParameter|. --- The active parameter is highlighted with |hl-LspSignatureActiveParameter|.
--- <pre>lua ---
--- vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with( --- ```lua
--- vim.lsp.handlers.signature_help, { --- vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
--- -- Use a sharp border with `FloatBorder` highlights --- vim.lsp.handlers.signature_help, {
--- border = "single" --- -- Use a sharp border with `FloatBorder` highlights
--- } --- border = "single"
--- ) --- }
--- </pre> --- )
--- ```
---
---@param result table Response from the language server
---@param ctx table Client context
---@param config table Configuration table. ---@param config table Configuration table.
--- - border: (default=nil) --- - border: (default=nil)
--- - Add borders to the floating window --- - Add borders to the floating window

7
runtime/lua/vim/lsp/semantic_tokens.lua
View File

@@ -555,9 +555,10 @@ local M = {}
--- delete the semanticTokensProvider table from the {server_capabilities} of --- delete the semanticTokensProvider table from the {server_capabilities} of
--- your client in your |LspAttach| callback or your configuration's --- your client in your |LspAttach| callback or your configuration's
--- `on_attach` callback: --- `on_attach` callback:
--- <pre>lua ---
--- client.server_capabilities.semanticTokensProvider = nil --- ```lua
--- </pre> --- client.server_capabilities.semanticTokensProvider = nil
--- ```
--- ---
---@param bufnr integer ---@param bufnr integer
---@param client_id integer ---@param client_id integer

120
runtime/lua/vim/shared.lua
View File

@@ -65,19 +65,21 @@ end
--- (as opposed to |vim.split()| which is "eager"). --- (as opposed to |vim.split()| which is "eager").
--- ---
--- Example: --- Example:
--- <pre>lua ---
--- for s in vim.gsplit(':aa::b:', ':', {plain=true}) do --- ```lua
--- print(s) --- for s in vim.gsplit(':aa::b:', ':', {plain=true}) do
--- end --- print(s)
--- </pre> --- end
--- ```
--- ---
--- If you want to also inspect the separator itself (instead of discarding it), use --- If you want to also inspect the separator itself (instead of discarding it), use
--- |string.gmatch()|. Example: --- |string.gmatch()|. Example:
--- <pre>lua ---
--- for word, num in ('foo111bar222'):gmatch('([^0-9]*)(%d*)') do --- ```lua
--- print(('word: %s num: %s'):format(word, num)) --- for word, num in ('foo111bar222'):gmatch('([^0-9]*)(%d*)') do
--- end --- print(('word: %s num: %s'):format(word, num))
--- </pre> --- end
--- ```
--- ---
--- @see |string.gmatch()| --- @see |string.gmatch()|
--- @see |vim.split()| --- @see |vim.split()|
@@ -165,12 +167,13 @@ end
--- |vim.gsplit()|). --- |vim.gsplit()|).
--- ---
--- Examples: --- Examples:
--- <pre>lua ---
--- split(":aa::b:", ":") --> {'','aa','','b',''} --- ```lua
--- split("axaby", "ab?") --> {'','x','y'} --- split(":aa::b:", ":") --> {'','aa','','b',''}
--- split("x*yz*o", "*", {plain=true}) --> {'x','yz','o'} --- split("axaby", "ab?") --> {'','x','y'}
--- split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'} --- split("x*yz*o", "*", {plain=true}) --> {'x','yz','o'}
--- </pre> --- split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'}
--- ```
--- ---
---@see |vim.gsplit()| ---@see |vim.gsplit()|
---@see |string.gmatch()| ---@see |string.gmatch()|
@@ -259,12 +262,13 @@ end
--- a predicate that is checked for each value. --- a predicate that is checked for each value.
--- ---
--- Example: --- Example:
--- <pre>lua ---
--- vim.tbl_contains({ 'a', { 'b', 'c' } }, function(v) --- ```lua
--- return vim.deep_equal(v, { 'b', 'c' }) --- vim.tbl_contains({ 'a', { 'b', 'c' } }, function(v)
--- end, { predicate = true }) --- return vim.deep_equal(v, { 'b', 'c' })
--- -- true --- end, { predicate = true })
--- </pre> --- -- true
--- ```
--- ---
---@see |vim.list_contains()| for checking values in list-like tables ---@see |vim.list_contains()| for checking values in list-like tables
--- ---
@@ -455,10 +459,11 @@ end
--- Return `nil` if the key does not exist. --- Return `nil` if the key does not exist.
--- ---
--- Examples: --- Examples:
--- <pre>lua ---
--- vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true --- ```lua
--- vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil --- vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true
--- </pre> --- vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil
--- ```
--- ---
---@param o table Table to index ---@param o table Table to index
---@param ... any Optional keys (0 or more, variadic) via which to index the table ---@param ... any Optional keys (0 or more, variadic) via which to index the table
@@ -626,10 +631,10 @@ end
--- Counts the number of non-nil values in table `t`. --- Counts the number of non-nil values in table `t`.
--- ---
--- <pre>lua --- ```lua
--- vim.tbl_count({ a=1, b=2 }) --> 2 --- vim.tbl_count({ a=1, b=2 }) --> 2
--- vim.tbl_count({ 1, 2 }) --> 2 --- vim.tbl_count({ 1, 2 }) --> 2
--- </pre> --- ```
--- ---
---@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua ---@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua
---@param t table Table ---@param t table Table
@@ -703,38 +708,41 @@ end
--- Validates a parameter specification (types and values). --- Validates a parameter specification (types and values).
--- ---
--- Usage example: --- Usage example:
--- <pre>lua ---
--- function user.new(name, age, hobbies) --- ```lua
--- vim.validate{ --- function user.new(name, age, hobbies)
--- name={name, 'string'}, --- vim.validate{
--- age={age, 'number'}, --- name={name, 'string'},
--- hobbies={hobbies, 'table'}, --- age={age, 'number'},
--- } --- hobbies={hobbies, 'table'},
--- ... --- }
--- end --- ...
--- </pre> --- end
--- ```
--- ---
--- Examples with explicit argument values (can be run directly): --- Examples with explicit argument values (can be run directly):
--- <pre>lua
--- vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
--- --> NOP (success)
--- ---
--- vim.validate{arg1={1, 'table'}} --- ```lua
--- --> error('arg1: expected table, got number') --- vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
--- --> NOP (success)
--- ---
--- vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}} --- vim.validate{arg1={1, 'table'}}
--- --> error('arg1: expected even number, got 3') --- --> error('arg1: expected table, got number')
--- </pre> ---
--- vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}}
--- --> error('arg1: expected even number, got 3')
--- ```
--- ---
--- If multiple types are valid they can be given as a list. --- If multiple types are valid they can be given as a list.
--- <pre>lua
--- vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}}
--- --> NOP (success)
--- ---
--- vim.validate{arg1={1, {'string', 'table'}}} --- ```lua
--- --> error('arg1: expected string|table, got number') --- vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}}
--- -- NOP (success)
--- ---
--- </pre> --- vim.validate{arg1={1, {'string', 'table'}}}
--- -- error('arg1: expected string|table, got number')
---
--- ```
--- ---
---@param opt table Names of parameters to validate. Each key is a parameter ---@param opt table Names of parameters to validate. Each key is a parameter
--- name; each value is a tuple in one of these forms: --- name; each value is a tuple in one of these forms:
@@ -866,10 +874,10 @@ end
--- If {create} is `nil`, this will create a defaulttable whose constructor function is --- If {create} is `nil`, this will create a defaulttable whose constructor function is
--- this function, effectively allowing to create nested tables on the fly: --- this function, effectively allowing to create nested tables on the fly:
--- ---
--- <pre>lua --- ```lua
--- local a = vim.defaulttable() --- local a = vim.defaulttable()
--- a.b.c = 1 --- a.b.c = 1
--- </pre> --- ```
--- ---
---@param create function?(key:any):any The function called to create a missing value. ---@param create function?(key:any):any The function called to create a missing value.
---@return table Empty table with metamethod ---@return table Empty table with metamethod
@@ -938,7 +946,7 @@ do
--- Create a ring buffer limited to a maximal number of items. --- Create a ring buffer limited to a maximal number of items.
--- Once the buffer is full, adding a new entry overrides the oldest entry. --- Once the buffer is full, adding a new entry overrides the oldest entry.
--- ---
--- <pre> --- ```lua
--- local ringbuf = vim.ringbuf(4) --- local ringbuf = vim.ringbuf(4)
--- ringbuf:push("a") --- ringbuf:push("a")
--- ringbuf:push("b") --- ringbuf:push("b")
@@ -952,7 +960,7 @@ do
--- for val in ringbuf do --- for val in ringbuf do
--- print(val) --- print(val)
--- end --- end
--- </pre> --- ```
--- ---
--- Returns a Ringbuf instance with the following methods: --- Returns a Ringbuf instance with the following methods:
--- ---

11
runtime/lua/vim/treesitter.lua
View File

@@ -441,14 +441,15 @@ end
--- In this case, add ``vim.bo.syntax = 'on'`` after the call to `start`. --- In this case, add ``vim.bo.syntax = 'on'`` after the call to `start`.
--- ---
--- Example: --- Example:
--- <pre>lua ---
--- ```lua
--- vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex', --- vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex',
--- callback = function(args) --- callback = function(args)
--- vim.treesitter.start(args.buf, 'latex') --- vim.treesitter.start(args.buf, 'latex')
--- vim.bo[args.buf].syntax = 'on' -- only if additional legacy syntax is needed --- vim.bo[args.buf].syntax = 'on' -- only if additional legacy syntax is needed
--- end --- end
--- }) --- })
--- </pre> --- ```
--- ---
---@param bufnr (integer|nil) Buffer to be highlighted (default: current buffer) ---@param bufnr (integer|nil) Buffer to be highlighted (default: current buffer)
---@param lang (string|nil) Language of the parser (default: buffer filetype) ---@param lang (string|nil) Language of the parser (default: buffer filetype)
@@ -502,9 +503,11 @@ function M.preview_query()
end end
--- Returns the fold level for {lnum} in the current buffer. Can be set directly to 'foldexpr': --- Returns the fold level for {lnum} in the current buffer. Can be set directly to 'foldexpr':
--- <pre>lua ---
--- ```lua
--- vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()' --- vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'
--- </pre> --- ```
---
---@param lnum integer|nil Line number to calculate fold level for ---@param lnum integer|nil Line number to calculate fold level for
---@return string ---@return string
function M.foldexpr(lnum) function M.foldexpr(lnum)

12
runtime/lua/vim/treesitter/languagetree.lua
View File

@@ -7,9 +7,9 @@
--- ---
--- To create a LanguageTree (parser object) for a given buffer and language, use: --- To create a LanguageTree (parser object) for a given buffer and language, use:
--- ---
--- <pre>lua --- ```lua
--- local parser = vim.treesitter.get_parser(bufnr, lang) --- local parser = vim.treesitter.get_parser(bufnr, lang)
--- </pre> --- ```
--- ---
--- (where `bufnr=0` means current buffer). `lang` defaults to 'filetype'. --- (where `bufnr=0` means current buffer). `lang` defaults to 'filetype'.
--- Note: currently the parser is retained for the lifetime of a buffer but this may change; --- Note: currently the parser is retained for the lifetime of a buffer but this may change;
@@ -17,9 +17,9 @@
--- ---
--- Whenever you need to access the current syntax tree, parse the buffer: --- Whenever you need to access the current syntax tree, parse the buffer:
--- ---
--- <pre>lua --- ```lua
--- local tree = parser:parse({ start_row, end_row }) --- local tree = parser:parse({ start_row, end_row })
--- </pre> --- ```
--- ---
--- This returns a table of immutable |treesitter-tree| objects representing the current state of --- This returns a table of immutable |treesitter-tree| objects representing the current state of
--- the buffer. When the plugin wants to access the state after a (possible) edit it must call --- the buffer. When the plugin wants to access the state after a (possible) edit it must call

18
runtime/lua/vim/treesitter/query.lua
View File

@@ -692,7 +692,8 @@ end
--- The iterator returns three values: a numeric id identifying the capture, --- The iterator returns three values: a numeric id identifying the capture,
--- the captured node, and metadata from any directives processing the match. --- the captured node, and metadata from any directives processing the match.
--- The following example shows how to get captures by name: --- The following example shows how to get captures by name:
--- <pre>lua ---
--- ```lua
--- for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do --- for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do
--- local name = query.captures[id] -- name of the capture in the query --- local name = query.captures[id] -- name of the capture in the query
--- -- typically useful info about the node: --- -- typically useful info about the node:
@@ -700,7 +701,7 @@ end
--- local row1, col1, row2, col2 = node:range() -- range of the capture --- local row1, col1, row2, col2 = node:range() -- range of the capture
--- -- ... use the info here ... --- -- ... use the info here ...
--- end --- end
--- </pre> --- ```
--- ---
---@param node TSNode under which the search will occur ---@param node TSNode under which the search will occur
---@param source (integer|string) Source buffer or string to extract text from ---@param source (integer|string) Source buffer or string to extract text from
@@ -743,7 +744,8 @@ end
--- If the query has more than one pattern, the capture table might be sparse --- If the query has more than one pattern, the capture table might be sparse
--- and e.g. `pairs()` method should be used over `ipairs`. --- and e.g. `pairs()` method should be used over `ipairs`.
--- Here is an example iterating over all captures in every match: --- Here is an example iterating over all captures in every match:
--- <pre>lua ---
--- ```lua
--- for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do --- for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do
--- for id, node in pairs(match) do --- for id, node in pairs(match) do
--- local name = query.captures[id] --- local name = query.captures[id]
@@ -754,7 +756,7 @@ end
--- -- ... use the info here ... --- -- ... use the info here ...
--- end --- end
--- end --- end
--- </pre> --- ```
--- ---
---@param node TSNode under which the search will occur ---@param node TSNode under which the search will occur
---@param source (integer|string) Source buffer or string to search ---@param source (integer|string) Source buffer or string to search
@@ -824,9 +826,11 @@ end
--- Omnifunc for completing node names and predicates in treesitter queries. --- Omnifunc for completing node names and predicates in treesitter queries.
--- ---
--- Use via --- Use via
--- <pre>lua ---
--- vim.bo.omnifunc = 'v:lua.vim.treesitter.query.omnifunc' --- ```lua
--- </pre> --- vim.bo.omnifunc = 'v:lua.vim.treesitter.query.omnifunc'
--- ```
---
function M.omnifunc(findstart, base) function M.omnifunc(findstart, base)
return require('vim.treesitter._query_linter').omnifunc(findstart, base) return require('vim.treesitter._query_linter').omnifunc(findstart, base)
end end

54
runtime/lua/vim/ui.lua
View File

@@ -3,6 +3,23 @@ local M = {}
--- Prompts the user to pick from a list of items, allowing arbitrary (potentially asynchronous) --- Prompts the user to pick from a list of items, allowing arbitrary (potentially asynchronous)
--- work until `on_choice`. --- work until `on_choice`.
--- ---
--- Example:
---
--- ```lua
--- vim.ui.select({ 'tabs', 'spaces' }, {
--- prompt = 'Select tabs or spaces:',
--- format_item = function(item)
--- return "I'd like to choose " .. item
--- end,
--- }, function(choice)
--- if choice == 'spaces' then
--- vim.o.expandtab = true
--- else
--- vim.o.expandtab = false
--- end
--- end)
--- ```
---
---@param items table Arbitrary items ---@param items table Arbitrary items
---@param opts table Additional options ---@param opts table Additional options
--- - prompt (string|nil) --- - prompt (string|nil)
@@ -19,23 +36,6 @@ local M = {}
--- Called once the user made a choice. --- Called once the user made a choice.
--- `idx` is the 1-based index of `item` within `items`. --- `idx` is the 1-based index of `item` within `items`.
--- `nil` if the user aborted the dialog. --- `nil` if the user aborted the dialog.
---
---
--- Example:
--- <pre>lua
--- vim.ui.select({ 'tabs', 'spaces' }, {
--- prompt = 'Select tabs or spaces:',
--- format_item = function(item)
--- return "I'd like to choose " .. item
--- end,
--- }, function(choice)
--- if choice == 'spaces' then
--- vim.o.expandtab = true
--- else
--- vim.o.expandtab = false
--- end
--- end)
--- </pre>
function M.select(items, opts, on_choice) function M.select(items, opts, on_choice)
vim.validate({ vim.validate({
items = { items, 'table', false }, items = { items, 'table', false },
@@ -58,6 +58,14 @@ end
--- Prompts the user for input, allowing arbitrary (potentially asynchronous) work until --- Prompts the user for input, allowing arbitrary (potentially asynchronous) work until
--- `on_confirm`. --- `on_confirm`.
--- ---
--- Example:
---
--- ```lua
--- vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input)
--- vim.o.shiftwidth = tonumber(input)
--- end)
--- ```
---
---@param opts table Additional options. See |input()| ---@param opts table Additional options. See |input()|
--- - prompt (string|nil) --- - prompt (string|nil)
--- Text of the prompt --- Text of the prompt
@@ -77,13 +85,6 @@ end
--- `input` is what the user typed (it might be --- `input` is what the user typed (it might be
--- an empty string if nothing was entered), or --- an empty string if nothing was entered), or
--- `nil` if the user aborted the dialog. --- `nil` if the user aborted the dialog.
---
--- Example:
--- <pre>lua
--- vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input)
--- vim.o.shiftwidth = tonumber(input)
--- end)
--- </pre>
function M.input(opts, on_confirm) function M.input(opts, on_confirm)
vim.validate({ vim.validate({
on_confirm = { on_confirm, 'function', false }, on_confirm = { on_confirm, 'function', false },
@@ -110,11 +111,12 @@ end
--- Expands "~/" and environment variables in filesystem paths. --- Expands "~/" and environment variables in filesystem paths.
--- ---
--- Examples: --- Examples:
--- <pre>lua ---
--- ```lua
--- vim.ui.open("https://neovim.io/") --- vim.ui.open("https://neovim.io/")
--- vim.ui.open("~/path/to/file") --- vim.ui.open("~/path/to/file")
--- vim.ui.open("$VIMRUNTIME") --- vim.ui.open("$VIMRUNTIME")
--- </pre> --- ```
--- ---
---@param path string Path or URL to open ---@param path string Path or URL to open
--- ---

131
runtime/lua/vim/version.lua
View File

@@ -5,12 +5,13 @@
--- available tools and dependencies on the current system. --- available tools and dependencies on the current system.
--- ---
--- Example: --- Example:
--- <pre>lua ---
--- local v = vim.version.parse(vim.fn.system({'tmux', '-V'}), {strict=false}) --- ```lua
--- if vim.version.gt(v, {3, 2, 0}) then --- local v = vim.version.parse(vim.fn.system({'tmux', '-V'}), {strict=false})
--- -- ... --- if vim.version.gt(v, {3, 2, 0}) then
--- end --- -- ...
--- </pre> --- end
--- ```
--- ---
--- \*vim.version()\* returns the version of the current Nvim process. --- \*vim.version()\* returns the version of the current Nvim process.
--- ---
@@ -21,35 +22,36 @@
--- ---
--- Supported range specs are shown in the following table. --- Supported range specs are shown in the following table.
--- Note: suffixed versions (1.2.3-rc1) are not matched. --- Note: suffixed versions (1.2.3-rc1) are not matched.
--- <pre>
--- 1.2.3 is 1.2.3
--- =1.2.3 is 1.2.3
--- >1.2.3 greater than 1.2.3
--- <1.2.3 before 1.2.3
--- >=1.2.3 at least 1.2.3
--- ~1.2.3 is >=1.2.3 <1.3.0 "reasonably close to 1.2.3"
--- ^1.2.3 is >=1.2.3 <2.0.0 "compatible with 1.2.3"
--- ^0.2.3 is >=0.2.3 <0.3.0 (0.x.x is special)
--- ^0.0.1 is =0.0.1 (0.0.x is special)
--- ^1.2 is >=1.2.0 <2.0.0 (like ^1.2.0)
--- ~1.2 is >=1.2.0 <1.3.0 (like ~1.2.0)
--- ^1 is >=1.0.0 <2.0.0 "compatible with 1"
--- ~1 same "reasonably close to 1"
--- 1.x same
--- 1.* same
--- 1 same
--- * any version
--- x same
--- ---
--- 1.2.3 - 2.3.4 is >=1.2.3 <=2.3.4 --- ```
--- 1.2.3 is 1.2.3
--- =1.2.3 is 1.2.3
--- >1.2.3 greater than 1.2.3
--- <1.2.3 before 1.2.3
--- >=1.2.3 at least 1.2.3
--- ~1.2.3 is >=1.2.3 <1.3.0 "reasonably close to 1.2.3"
--- ^1.2.3 is >=1.2.3 <2.0.0 "compatible with 1.2.3"
--- ^0.2.3 is >=0.2.3 <0.3.0 (0.x.x is special)
--- ^0.0.1 is =0.0.1 (0.0.x is special)
--- ^1.2 is >=1.2.0 <2.0.0 (like ^1.2.0)
--- ~1.2 is >=1.2.0 <1.3.0 (like ~1.2.0)
--- ^1 is >=1.0.0 <2.0.0 "compatible with 1"
--- ~1 same "reasonably close to 1"
--- 1.x same
--- 1.* same
--- 1 same
--- * any version
--- x same
--- ---
--- Partial right: missing pieces treated as x (2.3 => 2.3.x). --- 1.2.3 - 2.3.4 is >=1.2.3 <=2.3.4
--- 1.2.3 - 2.3 is >=1.2.3 <2.4.0
--- 1.2.3 - 2 is >=1.2.3 <3.0.0
--- ---
--- Partial left: missing pieces treated as 0 (1.2 => 1.2.0). --- Partial right: missing pieces treated as x (2.3 => 2.3.x).
--- 1.2 - 2.3.0 is 1.2.0 - 2.3.0 --- 1.2.3 - 2.3 is >=1.2.3 <2.4.0
--- </pre> --- 1.2.3 - 2 is >=1.2.3 <3.0.0
---
--- Partial left: missing pieces treated as 0 (1.2 => 1.2.0).
--- 1.2 - 2.3.0 is 1.2.0 - 2.3.0
--- ```
local M = {} local M = {}
@@ -237,29 +239,32 @@ function VersionRange:has(version)
end end
--- Parses a semver |version-range| "spec" and returns a range object: --- Parses a semver |version-range| "spec" and returns a range object:
--- <pre> ---
--- { --- ```
--- from: Version --- {
--- to: Version --- from: Version
--- has(v: string|Version) --- to: Version
--- } --- has(v: string|Version)
--- </pre> --- }
--- ```
--- ---
--- `:has()` checks if a version is in the range (inclusive `from`, exclusive `to`). --- `:has()` checks if a version is in the range (inclusive `from`, exclusive `to`).
--- ---
--- Example: --- Example:
--- <pre>lua ---
--- local r = vim.version.range('1.0.0 - 2.0.0') --- ```lua
--- print(r:has('1.9.9')) -- true --- local r = vim.version.range('1.0.0 - 2.0.0')
--- print(r:has('2.0.0')) -- false --- print(r:has('1.9.9')) -- true
--- print(r:has(vim.version())) -- check against current Nvim version --- print(r:has('2.0.0')) -- false
--- </pre> --- print(r:has(vim.version())) -- check against current Nvim version
--- ```
--- ---
--- Or use cmp(), eq(), lt(), and gt() to compare `.to` and `.from` directly: --- Or use cmp(), eq(), lt(), and gt() to compare `.to` and `.from` directly:
--- <pre>lua ---
--- local r = vim.version.range('1.0.0 - 2.0.0') --- ```lua
--- print(vim.version.gt({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to)) --- local r = vim.version.range('1.0.0 - 2.0.0')
--- </pre> --- print(vim.version.gt({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to))
--- ```
--- ---
--- @see # https://github.com/npm/node-semver#ranges --- @see # https://github.com/npm/node-semver#ranges
--- ---
@@ -345,16 +350,17 @@ end
--- specified literally as a `{major, minor, patch}` tuple, e.g. `{1, 0, 3}`). --- specified literally as a `{major, minor, patch}` tuple, e.g. `{1, 0, 3}`).
--- ---
--- Example: --- Example:
--- <pre>lua ---
--- if vim.version.cmp({1,0,3}, {0,2,1}) == 0 then --- ```lua
--- -- ... --- if vim.version.cmp({1,0,3}, {0,2,1}) == 0 then
--- end --- -- ...
--- local v1 = vim.version.parse('1.0.3-pre') --- end
--- local v2 = vim.version.parse('0.2.1') --- local v1 = vim.version.parse('1.0.3-pre')
--- if vim.version.cmp(v1, v2) == 0 then --- local v2 = vim.version.parse('0.2.1')
--- -- ... --- if vim.version.cmp(v1, v2) == 0 then
--- end --- -- ...
--- </pre> --- end
--- ```
--- ---
--- @note Per semver, build metadata is ignored when comparing two otherwise-equivalent versions. --- @note Per semver, build metadata is ignored when comparing two otherwise-equivalent versions.
--- ---
@@ -399,9 +405,10 @@ end
--- Parses a semantic version string and returns a version object which can be used with other --- Parses a semantic version string and returns a version object which can be used with other
--- `vim.version` functions. For example "1.0.1-rc1+build.2" returns: --- `vim.version` functions. For example "1.0.1-rc1+build.2" returns:
--- <pre> ---
--- { major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" } --- ```
--- </pre> --- { major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" }
--- ```
--- ---
--- @see # https://semver.org/spec/v2.0.0.html --- @see # https://semver.org/spec/v2.0.0.html
--- ---

15
scripts/gen_eval_files.lua
View File

@@ -213,17 +213,20 @@ end
--- Convert vimdoc references to markdown literals --- Convert vimdoc references to markdown literals
--- Convert vimdoc codeblocks to markdown codeblocks --- Convert vimdoc codeblocks to markdown codeblocks
---
--- Ensure code blocks have one empty line before the start fence and after the closing fence.
---
--- @param x string --- @param x string
--- @return string --- @return string
local function norm_text(x) local function norm_text(x)
return ( return (
x:gsub('|([^ ]+)|', '`%1`') x:gsub('|([^ ]+)|', '`%1`')
:gsub('>lua', '\n```lua') :gsub('\n*>lua', '\n\n```lua')
:gsub('>vim', '\n```vim') :gsub('\n*>vim', '\n\n```vim')
:gsub('\n<$', '\n```') :gsub('\n+<$', '\n```')
:gsub('\n<\n', '\n```\n') :gsub('\n+<\n+', '\n```\n\n')
:gsub('%s+>\n', '\n```\n') :gsub('%s+>\n+', '\n```\n')
:gsub('\n<%s+\n?', '\n```\n') :gsub('\n+<%s+\n?', '\n```\n')
) )
end end

37
scripts/gen_vimdoc.py
View File

@@ -585,13 +585,12 @@ def render_node(n, text, prefix='', indent='', width=text_width - indentation,
text += '>{}{}\n<'.format(ensure_nl, o) text += '>{}{}\n<'.format(ensure_nl, o)
elif n.nodeName == 'programlisting': # codeblock (```) elif n.nodeName == 'programlisting': # codeblock (```)
o = get_text(n) o = get_text(n)
filename = n.attributes['filename'].value text += '>'
if filename: if 'filename' in n.attributes:
text += '>{}'.format(filename.lstrip('.')) filename = n.attributes['filename'].value
else: text += filename.lstrip('.')
text += '>'
text += '\n\n{}\n<'.format(textwrap.indent(o, ' ' * 4)) text += '\n{}\n<'.format(textwrap.indent(o, ' ' * 4))
elif is_inline(n): elif is_inline(n):
text = doc_wrap(get_text(n), prefix=prefix, indent=indent, width=width) text = doc_wrap(get_text(n), prefix=prefix, indent=indent, width=width)
elif n.nodeName == 'verbatim': elif n.nodeName == 'verbatim':
@@ -768,6 +767,27 @@ def para_as_map(parent, indent='', width=text_width - indentation, fmt_vimhelp=F
return chunks, xrefs return chunks, xrefs
def is_program_listing(para):
"""
Return True if `para` contains a "programlisting" (i.e. a Markdown code
block ```).
Sometimes a <para> element will have only a single "programlisting" child
node, but othertimes it will have extra whitespace around the
"programlisting" node.
@param para XML <para> node
@return True if <para> is a programlisting
"""
# Remove any child text nodes that are only whitespace
children = [
n for n in para.childNodes
if n.nodeType != n.TEXT_NODE or n.data.strip() != ''
]
return len(children) == 1 and children[0].nodeName == 'programlisting'
def fmt_node_as_vimhelp(parent: Element, width=text_width - indentation, indent='', def fmt_node_as_vimhelp(parent: Element, width=text_width - indentation, indent='',
fmt_vimhelp=False): fmt_vimhelp=False):
"""Renders (nested) Doxygen <para> nodes as Vim :help text. """Renders (nested) Doxygen <para> nodes as Vim :help text.
@@ -799,10 +819,7 @@ def fmt_node_as_vimhelp(parent: Element, width=text_width - indentation, indent=
# 'programlisting' blocks are Markdown code blocks. Do not include # 'programlisting' blocks are Markdown code blocks. Do not include
# these as a separate paragraph, but append to the last non-empty line # these as a separate paragraph, but append to the last non-empty line
# in the text # in the text
if ( if is_program_listing(child):
len(child.childNodes) == 1
and child.childNodes[0].nodeName == 'programlisting'
):
while rendered_blocks and rendered_blocks[-1] == '': while rendered_blocks and rendered_blocks[-1] == '':
rendered_blocks.pop() rendered_blocks.pop()
rendered_blocks[-1] += ' ' + para['text'] rendered_blocks[-1] += ' ' + para['text']

73
src/nvim/api/autocmd.c
View File

@@ -49,19 +49,20 @@ static int64_t next_autocmd_id = 1;
/// Get all autocommands that match the corresponding {opts}. /// Get all autocommands that match the corresponding {opts}.
/// ///
/// These examples will get autocommands matching ALL the given criteria: /// These examples will get autocommands matching ALL the given criteria:
/// <pre>lua
/// -- Matches all criteria
/// autocommands = vim.api.nvim_get_autocmds({
/// group = "MyGroup",
/// event = {"BufEnter", "BufWinEnter"},
/// pattern = {"*.c", "*.h"}
/// })
/// ///
/// -- All commands from one group /// ```lua
/// autocommands = vim.api.nvim_get_autocmds({ /// -- Matches all criteria
/// group = "MyGroup", /// autocommands = vim.api.nvim_get_autocmds({
/// }) /// group = "MyGroup",
/// </pre> /// event = {"BufEnter", "BufWinEnter"},
/// pattern = {"*.c", "*.h"}
/// })
///
/// -- All commands from one group
/// autocommands = vim.api.nvim_get_autocmds({
/// group = "MyGroup",
/// })
/// ```
/// ///
/// NOTE: When multiple patterns or events are provided, it will find all the autocommands that /// NOTE: When multiple patterns or events are provided, it will find all the autocommands that
/// match any combination of them. /// match any combination of them.
@@ -344,28 +345,31 @@ cleanup:
/// function _name_ string) or `command` (Ex command string). /// function _name_ string) or `command` (Ex command string).
/// ///
/// Example using Lua callback: /// Example using Lua callback:
/// <pre>lua ///
/// vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { /// ```lua
/// pattern = {"*.c", "*.h"}, /// vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
/// callback = function(ev) /// pattern = {"*.c", "*.h"},
/// print(string.format('event fired: \%s', vim.inspect(ev))) /// callback = function(ev)
/// end /// print(string.format('event fired: %s', vim.inspect(ev)))
/// }) /// end
/// </pre> /// })
/// ```
/// ///
/// Example using an Ex command as the handler: /// Example using an Ex command as the handler:
/// <pre>lua ///
/// vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { /// ```lua
/// pattern = {"*.c", "*.h"}, /// vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
/// command = "echo 'Entering a C or C++ file'", /// pattern = {"*.c", "*.h"},
/// }) /// command = "echo 'Entering a C or C++ file'",
/// </pre> /// })
/// ```
/// ///
/// Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|), thus names like "$HOME" /// Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|), thus names like "$HOME"
/// and "~" must be expanded explicitly: /// and "~" must be expanded explicitly:
/// <pre>lua ///
/// pattern = vim.fn.expand("~") .. "/some/path/*.py" /// ```lua
/// </pre> /// pattern = vim.fn.expand("~") .. "/some/path/*.py"
/// ```
/// ///
/// @param event (string|array) Event(s) that will trigger the handler (`callback` or `command`). /// @param event (string|array) Event(s) that will trigger the handler (`callback` or `command`).
/// @param opts Options dict: /// @param opts Options dict:
@@ -619,11 +623,12 @@ cleanup:
/// Create or get an autocommand group |autocmd-groups|. /// Create or get an autocommand group |autocmd-groups|.
/// ///
/// To get an existing group id, do: /// To get an existing group id, do:
/// <pre>lua ///
/// local id = vim.api.nvim_create_augroup("MyGroup", { /// ```lua
/// clear = false /// local id = vim.api.nvim_create_augroup("MyGroup", {
/// }) /// clear = false
/// </pre> /// })
/// ```
/// ///
/// @param name String: The name of the group /// @param name String: The name of the group
/// @param opts Dictionary Parameters /// @param opts Dictionary Parameters

14
src/nvim/api/buffer.c
View File

@@ -85,11 +85,15 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
/// ///
/// Example (Lua): capture buffer updates in a global `events` variable /// Example (Lua): capture buffer updates in a global `events` variable
/// (use "vim.print(events)" to see its contents): /// (use "vim.print(events)" to see its contents):
/// <pre>lua ///
/// events = {} /// ```lua
/// vim.api.nvim_buf_attach(0, false, { /// events = {}
/// on_lines=function(...) table.insert(events, {...}) end}) /// vim.api.nvim_buf_attach(0, false, {
/// </pre> /// on_lines = function(...)
/// table.insert(events, {...})
/// end,
/// })
/// ```
/// ///
/// @see |nvim_buf_detach()| /// @see |nvim_buf_detach()|
/// @see |api-buffer-updates-lua| /// @see |api-buffer-updates-lua|

11
src/nvim/api/command.c
View File

@@ -860,11 +860,12 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin
/// For Lua usage see |lua-guide-commands-create|. /// For Lua usage see |lua-guide-commands-create|.
/// ///
/// Example: /// Example:
/// <pre>vim ///
/// :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true}) /// ```vim
/// :SayHello /// :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true})
/// Hello world! /// :SayHello
/// </pre> /// Hello world!
/// ```
/// ///
/// @param name Name of the new user command. Must begin with an uppercase letter. /// @param name Name of the new user command. Must begin with an uppercase letter.
/// @param command Replacement command to execute when this user command is executed. When called /// @param command Replacement command to execute when this user command is executed. When called

38
src/nvim/api/extmark.c
View File

@@ -300,10 +300,11 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
/// Region can be given as (row,col) tuples, or valid extmark ids (whose /// Region can be given as (row,col) tuples, or valid extmark ids (whose
/// positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1) /// positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1)
/// respectively, thus the following are equivalent: /// respectively, thus the following are equivalent:
/// <pre>lua ///
/// vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) /// ```lua
/// vim.api.nvim_buf_get_extmarks(0, my_ns, {0,0}, {-1,-1}, {}) /// vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
/// </pre> /// vim.api.nvim_buf_get_extmarks(0, my_ns, {0,0}, {-1,-1}, {})
/// ```
/// ///
/// If `end` is less than `start`, traversal works backwards. (Useful /// If `end` is less than `start`, traversal works backwards. (Useful
/// with `limit`, to get the first marks prior to a given position.) /// with `limit`, to get the first marks prior to a given position.)
@@ -313,20 +314,21 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
/// of an extmark will be considered. /// of an extmark will be considered.
/// ///
/// Example: /// Example:
/// <pre>lua ///
/// local api = vim.api /// ```lua
/// local pos = api.nvim_win_get_cursor(0) /// local api = vim.api
/// local ns = api.nvim_create_namespace('my-plugin') /// local pos = api.nvim_win_get_cursor(0)
/// -- Create new extmark at line 1, column 1. /// local ns = api.nvim_create_namespace('my-plugin')
/// local m1 = api.nvim_buf_set_extmark(0, ns, 0, 0, {}) /// -- Create new extmark at line 1, column 1.
/// -- Create new extmark at line 3, column 1. /// local m1 = api.nvim_buf_set_extmark(0, ns, 0, 0, {})
/// local m2 = api.nvim_buf_set_extmark(0, ns, 2, 0, {}) /// -- Create new extmark at line 3, column 1.
/// -- Get extmarks only from line 3. /// local m2 = api.nvim_buf_set_extmark(0, ns, 2, 0, {})
/// local ms = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {}) /// -- Get extmarks only from line 3.
/// -- Get all marks in this buffer + namespace. /// local ms = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
/// local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {}) /// -- Get all marks in this buffer + namespace.
/// vim.print(ms) /// local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {})
/// </pre> /// vim.print(ms)
/// ```
/// ///
/// @param buffer Buffer handle, or 0 for current buffer /// @param buffer Buffer handle, or 0 for current buffer
/// @param ns_id Namespace id from |nvim_create_namespace()| or -1 for all namespaces /// @param ns_id Namespace id from |nvim_create_namespace()| or -1 for all namespaces

32
src/nvim/api/vim.c
View File

@@ -212,10 +212,11 @@ void nvim_set_hl_ns_fast(Integer ns_id, Error *err)
/// nvim_feedkeys(). /// nvim_feedkeys().
/// ///
/// Example: /// Example:
/// <pre>vim ///
/// :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true) /// ```vim
/// :call nvim_feedkeys(key, 'n', v:false) /// :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true)
/// </pre> /// :call nvim_feedkeys(key, 'n', v:false)
/// ```
/// ///
/// @param keys to be typed /// @param keys to be typed
/// @param mode behavior flags, see |feedkeys()| /// @param mode behavior flags, see |feedkeys()|
@@ -1280,10 +1281,11 @@ void nvim_unsubscribe(uint64_t channel_id, String event)
/// "#rrggbb" hexadecimal string. /// "#rrggbb" hexadecimal string.
/// ///
/// Example: /// Example:
/// <pre>vim ///
/// :echo nvim_get_color_by_name("Pink") /// ```vim
/// :echo nvim_get_color_by_name("#cbcbcb") /// :echo nvim_get_color_by_name("Pink")
/// </pre> /// :echo nvim_get_color_by_name("#cbcbcb")
/// ```
/// ///
/// @param name Color name or "#rrggbb" string /// @param name Color name or "#rrggbb" string
/// @return 24-bit RGB value, or -1 for invalid argument. /// @return 24-bit RGB value, or -1 for invalid argument.
@@ -1420,14 +1422,16 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode)
/// Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual. /// Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual.
/// ///
/// Example: /// Example:
/// <pre>vim ///
/// call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true}) /// ```vim
/// </pre> /// call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})
/// ```
/// ///
/// is equivalent to: /// is equivalent to:
/// <pre>vim ///
/// nmap <nowait> <Space><NL> <Nop> /// ```vim
/// </pre> /// nmap <nowait> <Space><NL> <Nop>
/// ```
/// ///
/// @param channel_id /// @param channel_id
/// @param mode Mode short-name (map command prefix: "n", "i", "v", "x", …) /// @param mode Mode short-name (map command prefix: "n", "i", "v", "x", …)

19
src/nvim/api/win_config.c
View File

@@ -56,16 +56,19 @@
/// this should not be used to specify arbitrary WM screen positions. /// this should not be used to specify arbitrary WM screen positions.
/// ///
/// Example (Lua): window-relative float /// Example (Lua): window-relative float
/// <pre>lua ///
/// vim.api.nvim_open_win(0, false, /// ```lua
/// {relative='win', row=3, col=3, width=12, height=3}) /// vim.api.nvim_open_win(0, false,
/// </pre> /// {relative='win', row=3, col=3, width=12, height=3})
/// ```
/// ///
/// Example (Lua): buffer-relative float (travels as buffer is scrolled) /// Example (Lua): buffer-relative float (travels as buffer is scrolled)
/// <pre>lua ///
/// vim.api.nvim_open_win(0, false, /// ```lua
/// {relative='win', width=12, height=3, bufpos={100,10}}) /// vim.api.nvim_open_win(0, false,
/// </pre> /// {relative='win', width=12, height=3, bufpos={100,10}})
/// })
/// ```
/// ///
/// @param buffer Buffer to display, or 0 for current buffer /// @param buffer Buffer to display, or 0 for current buffer
/// @param enter Enter the window (make it the current window) /// @param enter Enter the window (make it the current window)

2
src/nvim/options.lua
View File

@@ -566,7 +566,7 @@ return {
backups if you don't care about losing the file. backups if you don't care about losing the file.
Note that environment variables are not expanded. If you want to use Note that environment variables are not expanded. If you want to use
$HOME you must expand it explicitly, e.g.: > $HOME you must expand it explicitly, e.g.: >vim
:let &backupskip = escape(expand('$HOME'), '\') .. '/tmp/*' :let &backupskip = escape(expand('$HOME'), '\') .. '/tmp/*'
< Note that the default also makes sure that "crontab -e" works (when a < Note that the default also makes sure that "crontab -e" works (when a