mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-09-05 19:08:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #21154 from clason/vimdoc-injections

Browse Source 
feat(help): highlighted codeblocks
This commit is contained in:
Christian Clason
2022-12-02 16:45:39 +01:00
committed by GitHub
parent 7314323420 e40df8b1bc
commit 07e6296520
48 changed files with 879 additions and 848 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
cmake.deps/CMakeLists.txt
View File

@@ -203,8 +203,8 @@ set(TREESITTER_LUA_SHA256 930d0370dc15b66389869355c8e14305b9ba7aafd36edbfdb468c8
set(TREESITTER_VIM_URL https://github.com/vigoux/tree-sitter-viml/archive/55ff1b080c09edeced9b748cf4c16d0b49d17fb9.tar.gz)
set(TREESITTER_VIM_SHA256 1b1cd39e33c8fb02fa7fe3977e844883c2a8508a7edd621f2d21e39a9aeefa92)
set(TREESITTER_HELP_URL https://github.com/neovim/tree-sitter-vimdoc/archive/v1.2.5.tar.gz)
set(TREESITTER_HELP_SHA256 379d764937a0e3a38e3f9ce9a62c93ba24211a236c74181dd04ee3b4631472a8)
set(TREESITTER_HELP_URL https://github.com/neovim/tree-sitter-vimdoc/archive/ce20f13c3f12506185754888feaae3f2ad54c287.tar.gz)
set(TREESITTER_HELP_SHA256 2b8b166438cce66064aab56a744430b1f44871f43e47f70b51246d14bb826609)
set(TREESITTER_URL https://github.com/tree-sitter/tree-sitter/archive/v0.20.7.tar.gz)
set(TREESITTER_SHA256 b355e968ec2d0241bbd96748e00a9038f83968f85d822ecb9940cbe4c42e182e)

125
runtime/doc/api.txt
View File

@@ -51,7 +51,7 @@ Connecting to the socket is the easiest way a programmer can test the API,
which can be done through any msgpack-rpc client library or full-featured
|api-client|. Here's a Ruby script that prints "hello world!" in the current
Nvim instance:
>
>ruby
#!/usr/bin/env ruby
# Requires msgpack-rpc: gem install msgpack-rpc
#
@@ -79,7 +79,7 @@ functions can be called interactively:
<
You can also embed Nvim via |jobstart()|, and communicate using |rpcrequest()|
and |rpcnotify()|:
>
>vim
let nvim = jobstart(['nvim', '--embed'], {'rpc': v:true})
echo rpcrequest(nvim, 'nvim_eval', '"Hello " . "world!"')
call jobstop(nvim)
@@ -201,9 +201,9 @@ any of these approaches:
Example (requires Python "pyyaml" and "msgpack-python" modules): >
nvim --api-info | python -c 'import msgpack, sys, yaml; yaml.dump(msgpack.unpackb(sys.stdin.buffer.read()), sys.stdout)'
<
3. Use the |api_info()| Vimscript function. >
3. Use the |api_info()| Vimscript function. >vim
:lua print(vim.inspect(vim.fn.api_info()))
< Example using |filter()| to exclude non-deprecated API functions: >
< Example using |filter()| to exclude non-deprecated API functions: >vim
:new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name')
==============================================================================
@@ -361,10 +361,10 @@ callbacks. These callbacks are called frequently in various contexts;
receive parameters ("lines", {buf}, {changedtick}, {firstline}, {lastline},
{new_lastline}, {old_byte_size} [, {old_utf32_size}, {old_utf16_size}]).
Unlike remote channel events the text contents are not passed. The new text can
be accessed inside the callback as
`vim.api.nvim_buf_get_lines(buf, firstline, new_lastline, true)`
be accessed inside the callback as >lua
vim.api.nvim_buf_get_lines(buf, firstline, new_lastline, true)
<
{old_byte_size} is the total size of the replaced region {firstline} to
{lastline} in bytes, including the final newline after {lastline}. if
`utf_sizes` is set to true in |nvim_buf_attach()| keyword args, then the
@@ -400,7 +400,7 @@ performance can be improved by calling |nvim_buf_add_highlight()| as an
asynchronous notification, after first (synchronously) requesting a source id.
Example using the Python API client (|pynvim|):
>
>python
src = vim.new_highlight_source()
buf = vim.current.buffer
for i in range(5):
@@ -414,7 +414,7 @@ clear highlights from a specific source, in a specific line range or the
entire buffer by passing in the line range 0, -1 (the latter is the default in
python as used above).
Example using the API from Vimscript: >
Example using the API from Vimscript: >vim
call nvim_buf_set_lines(0, 0, 0, v:true, ["test text"])
let src = nvim_buf_add_highlight(0, 0, "String", 1, 0, 4)
@@ -438,7 +438,7 @@ Two ways to create a floating window:
To close it use |nvim_win_close()| or a command such as |:close|.
To check whether a window is floating, check whether the `relative` option in
its config is non-empty: >
its config is non-empty: >lua
if vim.api.nvim_win_get_config(window_id).relative ~= '' then
-- window with this window_id is floating
@@ -456,7 +456,7 @@ Currently, floating windows don't support some widgets like scrollbar.
The output of |:mksession| does not include commands for restoring floating
windows.
Example: create a float with scratch buffer: >
Example: create a float with scratch buffer: >vim
let buf = nvim_create_buf(v:false, v:true)
call nvim_buf_set_lines(buf, 0, -1, v:true, ["test", "text"])
@@ -510,19 +510,20 @@ Let's set an extmark at the first row (row=0) and third column (column=2).
01 2345678
0 ex|ample..
^ extmark position
<
>vim
let g:mark_ns = nvim_create_namespace('myplugin')
let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 2, {})
<
We can get the mark by its id: >
We can get the mark by its id: >vim
echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id, {})
=> [0, 2]
" => [0, 2]
We can get all marks in a buffer by |namespace| (or by a range): >
We can get all marks in a buffer by |namespace| (or by a range): >vim
echo nvim_buf_get_extmarks(0, g:mark_ns, 0, -1, {})
=> [[1, 0, 2]]
" => [[1, 0, 2]]
Deleting all surrounding text does NOT remove an extmark! To remove extmarks
use |nvim_buf_del_extmark()|. Deleting "x" in our example: >
@@ -530,9 +531,10 @@ use |nvim_buf_del_extmark()|. Deleting "x" in our example: >
0 12345678
0 e|ample..
^ extmark position
<
>vim
echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id, {})
=> [0, 1]
" => [0, 1]
<
Note: Extmark "gravity" decides how it will shift after a text edit.
See |nvim_buf_set_extmark()|
@@ -801,7 +803,7 @@ nvim_feedkeys({keys}, {mode}, {escape_ks}) *nvim_feedkeys()*
with escape_ks=false) to replace |keycodes|, then pass the result to
nvim_feedkeys().
Example: >
Example: >vim
:let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true)
:call nvim_feedkeys(key, 'n', v:false)
<
@@ -857,7 +859,7 @@ nvim_get_color_by_name({name}) *nvim_get_color_by_name()*
Returns the 24-bit RGB value of a |nvim_get_color_map()| color name or
"#rrggbb" hexadecimal string.
Example: >
Example: >vim
:echo nvim_get_color_by_name("Pink")
:echo nvim_get_color_by_name("#cbcbcb")
<
@@ -1442,11 +1444,11 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()*
Unlike |:map|, leading/trailing whitespace is accepted as part of the
{lhs} or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual.
Example: >
Example: >vim
call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})
<
is equivalent to: >
is equivalent to: >vim
nmap <nowait> <Space><NL> <Nop>
<
@@ -1744,7 +1746,7 @@ nvim_create_user_command({name}, {command}, {*opts})
{command} is the replacement text or Lua function to execute.
Example: >
Example: >vim
:call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
:SayHello
Hello world!
@@ -2025,7 +2027,7 @@ whether a buffer is loaded.
nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
Activates buffer-update events on a channel, or as Lua callbacks.
Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its contents): >
Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its contents): >lua
events = {}
vim.api.nvim_buf_attach(0, false, {
on_lines=function(...) table.insert(events, {...}) end})
@@ -2527,29 +2529,27 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
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)
respectively, thus the following are equivalent:
>
nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {})
respectively, thus the following are equivalent: >lua
nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {})
<
If `end` is less than `start`, traversal works backwards. (Useful with
`limit`, to get the first marks prior to a given position.)
Example:
>
local a = vim.api
local pos = a.nvim_win_get_cursor(0)
local ns = a.nvim_create_namespace('my-plugin')
-- Create new extmark at line 1, column 1.
local m1 = a.nvim_buf_set_extmark(0, ns, 0, 0, {})
-- Create new extmark at line 3, column 1.
local m2 = a.nvim_buf_set_extmark(0, ns, 0, 2, {})
-- Get extmarks only from line 3.
local ms = a.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
-- Get all marks in this buffer + namespace.
local all = a.nvim_buf_get_extmarks(0, ns, 0, -1, {})
print(vim.inspect(ms))
Example: >lua
local a = vim.api
local pos = a.nvim_win_get_cursor(0)
local ns = a.nvim_create_namespace('my-plugin')
-- Create new extmark at line 1, column 1.
local m1 = a.nvim_buf_set_extmark(0, ns, 0, 0, {})
-- Create new extmark at line 3, column 1.
local m2 = a.nvim_buf_set_extmark(0, ns, 0, 2, {})
-- Get extmarks only from line 3.
local ms = a.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
-- Get all marks in this buffer + namespace.
local all = a.nvim_buf_get_extmarks(0, ns, 0, -1, {})
print(vim.inspect(ms))
<
Parameters: ~
@@ -2967,12 +2967,12 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()*
could let floats hover outside of the main window like a tooltip, but this
should not be used to specify arbitrary WM screen positions.
Example (Lua): window-relative float >
Example (Lua): window-relative float >lua
vim.api.nvim_open_win(0, false,
{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
vim.api.nvim_open_win(0, false,
{relative='win', width=12, height=3, bufpos={100,10}})
<
@@ -3208,7 +3208,7 @@ nvim_clear_autocmds({*opts}) *nvim_clear_autocmds()*
nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()*
Create or get an autocommand group |autocmd-groups|.
To get an existing group id, do: >
To get an existing group id, do: >lua
local id = vim.api.nvim_create_augroup("MyGroup", {
clear = false
})
@@ -3233,7 +3233,7 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()*
executed when the autocommand triggers: a callback function (Lua or
Vimscript), or a command (like regular autocommands).
Example using callback: >
Example using callback: >lua
-- Lua function
local myluafun = function() print("This buffer enters") end
@@ -3248,40 +3248,39 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()*
Lua functions receive a table with information about the autocmd event as
an argument. To use a function which itself accepts another (optional)
parameter, wrap the function in a lambda:
>
-- Lua function with an optional parameter.
-- The autocmd callback would pass a table as argument but this
-- function expects number|nil
local myluafun = function(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() end
parameter, wrap the function in a lambda: >lua
-- Lua function with an optional parameter.
-- The autocmd callback would pass a table as argument but this
-- function expects number|nil
local myluafun = function(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() end
vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
pattern = {"*.c", "*.h"},
callback = function() myluafun() end,
})
vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
pattern = {"*.c", "*.h"},
callback = function() myluafun() end,
})
<
Example using command: >
Example using command: >lua
vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
pattern = {"*.c", "*.h"},
command = "echo 'Entering a C or C++ file'",
})
<
Example values for pattern: >
Example values for pattern: >lua
pattern = "*.py"
pattern = { "*.py", "*.pyi" }
<
Note: The `pattern` is passed to callbacks and commands as a literal string; environment
variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|. Instead,
|expand()| such variables explicitly: >
|expand()| such variables explicitly: >lua
pattern = vim.fn.expand("~") .. "/some/path/*.py"
<
Example values for event: >
"BufWritePre"
{"CursorHold", "BufWritePre", "BufWritePost"}
Example values for event: >lua
event = "BufWritePre"
event = {"CursorHold", "BufWritePre", "BufWritePost"}
<
Parameters: ~
@@ -3392,7 +3391,7 @@ nvim_exec_autocmds({event}, {*opts}) *nvim_exec_autocmds()*
nvim_get_autocmds({*opts}) *nvim_get_autocmds()*
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",

14
runtime/doc/channel.txt
View File

@@ -91,7 +91,7 @@ only bytes can be written to Nvim's own stderr.
There are two ways to deal with this:
- 1. To wait for the entire output, use |channel-buffered| mode.
- 2. To read line-by-line, use the following code: >
- 2. To read line-by-line, use the following code: >vim
let s:lines = ['']
func! s:on_event(job_id, data, event) dict
let eof = (a:data == [''])
@@ -108,7 +108,7 @@ callbacks.
Data can be sent to the channel using the |chansend()| function. Here is a
simple example, echoing some data through a cat-process:
>
>vim
function! s:OnEvent(id, data, event) dict
let str = join(a:data, "\n")
echomsg str
@@ -119,7 +119,7 @@ simple example, echoing some data through a cat-process:
Here is a example of setting a buffer to the result of grep, but only after
all data has been processed:
>
>vim
function! s:OnEvent(id, data, event) dict
call nvim_buf_set_lines(2, 0, -1, v:true, a:data)
endfunction
@@ -142,7 +142,7 @@ However, change of PTY size can be signaled to the slave using |jobresize()|.
See also |terminal-emulator|.
Terminal characteristics (termios) for |:terminal| and PTY channels are copied
from the host TTY, or if Nvim is |--headless| it uses default values: >
from the host TTY, or if Nvim is |--headless| it uses default values: >vim
:echo system('nvim --headless +"te stty -a" +"sleep 1" +"1,/^$/print" +q')
==============================================================================
@@ -163,7 +163,7 @@ used as a channel. See also |--embed|.
Call |stdioopen()| during |startup| to open the stdio channel as |channel-id| 1.
Nvim's stderr is always available as |v:stderr|, a write-only bytes channel.
Example: >
Example: >vim
func! OnEvent(id, data, event)
if a:data == [""]
quit
@@ -172,7 +172,7 @@ Example: >
endfunc
call stdioopen({'on_stdin': 'OnEvent'})
<
Put this in `uppercase.vim` and run: >
Put this in `uppercase.vim` and run: >bash
nvim --headless --cmd "source uppercase.vim"
==============================================================================
@@ -223,7 +223,7 @@ start of the line.
Here is an example for Unix. It starts a shell in the background and prompts
for the next shell command. Output from the shell is displayed above the
prompt. >
prompt. >vim
" Function handling a line of text that has been typed.
func TextEntered(text)

2
runtime/doc/deprecated.txt
View File

@@ -30,7 +30,7 @@ ENVIRONMENT VARIABLES
- detect a parent Nvim (use |$NVIM| instead)
- Ignored if --listen is given.
- Unset by |terminal| and |jobstart()| unless explicitly given by the "env"
option. Example: >
option. Example: >vim
call jobstart(['foo'], { 'env': { 'NVIM_LISTEN_ADDRESS': v:servername } })
<

87
runtime/doc/dev_style.txt
View File

@@ -38,7 +38,7 @@ All header files should have `#define` guards to prevent multiple inclusion.
The format of the symbol name should be `NVIM_<DIRECTORY>_<FILE>_H`.
In foo/bar.h:
>
>c
#ifndef NVIM_FOO_BAR_H
#define NVIM_FOO_BAR_H
@@ -71,7 +71,7 @@ C99 allows you to declare variables anywhere in a function. Declare them in as
local a scope as possible, and as close to the first use as possible. This
makes it easier for the reader to find the declaration and see what type the
variable is and what it was initialized to. In particular, initialization
should be used instead of declaration and assignment, e.g. >
should be used instead of declaration and assignment, e.g. >c
int i;
i = f(); // BAD: initialization separate from declaration.
@@ -110,7 +110,7 @@ Variable-length arrays can cause hard to detect stack overflows.
Postincrement and Postdecrement ~
Use postfix form (`i++`) in statements. >
Use postfix form (`i++`) in statements. >c
for (int i = 0; i < 3; i++) { }
int j = ++i; // OK: ++i is used as an expression.
@@ -136,7 +136,7 @@ Use `const` pointers whenever possible. Avoid `const` on non-pointer parameter d
before the "noun" (`int`).
That said, while we encourage putting `const` first, we do not require it.
But be consistent with the code around you! >
But be consistent with the code around you! >c
void foo(const char *p, int i);
}
@@ -176,14 +176,14 @@ Type unsigned signed
Booleans ~
Use `bool` to represent boolean values. >
Use `bool` to represent boolean values. >c
int loaded = 1; // BAD: loaded should have type bool.
Conditions ~
Don't use "yoda-conditions". Use at most one assignment per condition. >
Don't use "yoda-conditions". Use at most one assignment per condition. >c
if (1 == x) {
@@ -196,7 +196,7 @@ Function declarations ~
Every function must not have a separate declaration.
Function declarations are created by the gendeclarations.lua script. >
Function declarations are created by the gendeclarations.lua script. >c
static void f(void);
@@ -209,7 +209,7 @@ Function declarations are created by the gendeclarations.lua script. >
General translation unit layout ~
The definitions of public functions precede the definitions of static
functions. >
functions. >c
<HEADER>
@@ -230,7 +230,7 @@ if .c file does not contain any static functions.
Included file name consists of the .c file name without extension, preceded by
the directory name relative to src/nvim. Name of the file containing static
functions declarations ends with `.c.generated.h`, `*.h.generated.h` files
contain only non-static function declarations. >
contain only non-static function declarations. >c
// src/nvim/foo.c file
#include <stddef.h>
@@ -274,7 +274,7 @@ comparisons, and structure alignment.
`#pragma pack()` and `__declspec(align())`.
- Use the `LL` or `ULL` suffixes as needed to create 64-bit constants. For
example: >
example: >c
int64_t my_value = 0x123456789LL;
uint64_t my_mask = 3ULL << 48;
@@ -288,7 +288,7 @@ Use `sizeof(varname)` when you take the size of a particular variable.
`sizeof(varname)` will update appropriately if someone changes the variable
type either now or later. You may use `sizeof(type)` for code unrelated to any
particular variable, such as code that manages an external or internal data
format where a variable of an appropriate C type is not convenient. >
format where a variable of an appropriate C type is not convenient. >c
Struct data;
memset(&data, 0, sizeof(data));
@@ -324,7 +324,7 @@ Give as descriptive a name as possible, within reason. Do not worry about
saving horizontal space as it is far more important to make your code
immediately understandable by a new reader. Do not use abbreviations that are
ambiguous or unfamiliar to readers outside your project, and do not abbreviate
by deleting letters within a word. >
by deleting letters within a word. >c
int price_count_reader; // No abbreviation.
int num_errors; // "num" is a widespread convention.
@@ -361,7 +361,7 @@ Typedef-ed structs and enums start with a capital letter and have a capital
letter for each new word, with no underscores: `MyExcitingStruct`.
Non-Typedef-ed structs and enums are all lowercase with underscores between
words: `struct my_exciting_struct` . >
words: `struct my_exciting_struct` . >c
struct my_struct {
...
@@ -376,7 +376,7 @@ instance: `my_exciting_local_variable`.
Common Variable names ~
For example: >
For example: >c
string table_name; // OK: uses underscore.
string tablename; // OK: all lowercase.
@@ -386,7 +386,7 @@ instance: `my_exciting_local_variable`.
Struct Variables ~
Data members in structs should be named like regular variables. >
Data members in structs should be named like regular variables. >c
struct url_table_properties {
string name;
@@ -406,7 +406,7 @@ Use a `k` followed by mixed case: `kDaysInAWeek`.
All compile-time constants, whether they are declared locally or globally,
follow a slightly different naming convention from other variables. Use a `k`
followed by words with uppercase first letters: >
followed by words with uppercase first letters: >c
const int kDaysInAWeek = 7;
@@ -416,7 +416,7 @@ Function names are all lowercase, with underscores between words. For
instance: `my_exceptional_function()`. All functions in the same header file
should have a common prefix.
In `os_unix.h`: >
In `os_unix.h`: >c
void unix_open(const char *path);
void unix_user_id(void);
@@ -429,7 +429,7 @@ normal operation.
Enumerator Names ~
Enumerators should be named like constants: `kEnumName`. >
Enumerators should be named like constants: `kEnumName`. >c
enum url_table_errors {
kOK = 0,
@@ -440,7 +440,7 @@ Enumerators should be named like constants: `kEnumName`. >
Macro Names ~
They're like this: `MY_MACRO_THAT_SCARES_CPP_DEVELOPERS`. >
They're like this: `MY_MACRO_THAT_SCARES_CPP_DEVELOPERS`. >c
#define ROUND(x) ...
#define PI_ROUNDED 5.0
@@ -461,7 +461,7 @@ Nvim uses Doxygen comments.
Comment Style ~
Use the `//`-style syntax only. >
Use the `//`-style syntax only. >c
// This is a comment spanning
// multiple lines
@@ -489,7 +489,7 @@ Start each file with a description of its contents.
mention in the `.c` that the documentation is in the `.h` file.
Do not duplicate comments in both the `.h` and the `.c`. Duplicated
comments diverge. >
comments diverge. >c
/// A brief description of this file.
///
@@ -500,7 +500,7 @@ Start each file with a description of its contents.
Struct Comments ~
Every struct definition should have accompanying comments that describes what
it is for and how it should be used. >
it is for and how it should be used. >c
/// Window info stored with a buffer.
///
@@ -522,7 +522,7 @@ it is for and how it should be used. >
};
If the field comments are short, you can also put them next to the field. But
be consistent within one struct, and follow the necessary doxygen style. >
be consistent within one struct, and follow the necessary doxygen style. >c
struct wininfo_S {
WinInfo *wi_next; ///< Next entry or NULL for last entry.
@@ -560,8 +560,7 @@ of a function describe operation.
- If the function allocates memory that the caller must free.
- Whether any of the arguments can be a null pointer.
- If there are any performance implications of how a function is used.
- If the function is re-entrant. What are its synchronization assumptions?
>
- If the function is re-entrant. What are its synchronization assumptions? >c
/// Brief description of the function.
///
/// Detailed description.
@@ -589,7 +588,7 @@ of a function describe operation.
Note you should not just repeat the comments given with the function
declaration, in the `.h` file or wherever. It's okay to recapitulate
briefly what the function does, but the focus of the comments should be on
how it does it. >
how it does it. >c
// Note that we don't use Doxygen comments here.
Iterator *get_iterator(void *arg1, void *arg2)
@@ -607,7 +606,7 @@ comments are required.
Global Variables ~
All global variables should have a comment describing what they are and
what they are used for. For example: >
what they are used for. For example: >c
/// The total number of tests cases that we run
/// through in this regression test.
@@ -623,7 +622,7 @@ interesting, or important parts of your code.
Also, lines that are non-obvious should get a comment at the end of the
line. These end-of-line comments should be separated from the code by 2
spaces. Example: >
spaces. Example: >c
// If we have enough memory, mmap the data portion too.
mmap_budget = max<int64>(0, mmap_budget - index_->length());
@@ -636,7 +635,7 @@ interesting, or important parts of your code.
function returns.
If you have several comments on subsequent lines, it can often be more
readable to line them up: >
readable to line them up: >c
do_something(); // Comment here so the comments line up.
do_something_else_that_is_longer(); // Comment here so there are two spaces between
@@ -652,7 +651,7 @@ interesting, or important parts of your code.
When you pass in a null pointer, boolean, or literal integer values to
functions, you should consider adding a comment about what they are, or
make your code self-documenting by using constants. For example, compare:
>
>c
bool success = calculate_something(interesting_value,
10,
@@ -660,7 +659,7 @@ interesting, or important parts of your code.
NULL); // What are these arguments??
<
versus: >
versus: >c
bool success = calculate_something(interesting_value,
10, // Default base value.
@@ -668,7 +667,7 @@ interesting, or important parts of your code.
NULL); // No callback.
<
Or alternatively, constants or self-describing variables: >
Or alternatively, constants or self-describing variables: >c
const int kDefaultBaseValue = 10;
const bool kFirstTimeCalling = false;
@@ -683,7 +682,7 @@ interesting, or important parts of your code.
Note that you should never describe the code itself. Assume that the
person reading the code knows C better than you do, even though he or she
does not know what you are trying to do: >
does not know what you are trying to do: >c
// Now go through the b array and make sure that if i occurs,
// the next element is i+1.
@@ -718,7 +717,7 @@ about the problem referenced by the `TODO`. The main purpose is to have a
consistent `TODO` format that can be searched to find the person who can
provide more details upon request. A `TODO` is not a commitment that the
person referenced will fix the problem. Thus when you create a `TODO`, it is
almost always your name that is given. >
almost always your name that is given. >c
// TODO(kl@gmail.com): Use a "*" here for concatenation operator.
// TODO(Zeke): change this to use relations.
@@ -786,19 +785,19 @@ Function Calls ~
On one line if it fits; otherwise, wrap arguments at the parenthesis.
Function calls have the following format: >
Function calls have the following format: >c
bool retval = do_something(argument1, argument2, argument3);
If the arguments do not all fit on one line, they should be broken up onto
multiple lines, with each subsequent line aligned with the first argument. Do
not add spaces after the open paren or before the close paren: >
not add spaces after the open paren or before the close paren: >c
bool retval = do_something(averyveryveryverylongargument1,
argument2, argument3);
If the function has many arguments, consider having one per line if this makes
the code more readable: >
the code more readable: >c
bool retval = do_something(argument1,
argument2,
@@ -806,7 +805,7 @@ the code more readable: >
argument4);
Arguments may optionally all be placed on subsequent lines, with one line per
argument: >
argument: >c
if (...) {
...
@@ -830,7 +829,7 @@ place but with one space after the `{` and one space before the `}`
If the braced list follows a name (e.g. a type or variable name), format as if
the `{}` were the parentheses of a function call with that name. If there is
no name, assume a zero-length name. >
no name, assume a zero-length name. >c
struct my_struct m = { // Here, you could also break before {.
superlongvariablename1,
@@ -847,7 +846,7 @@ Annotate non-trivial fall-through between cases.
If not conditional on an enumerated value, switch statements should always
have a `default` case (in the case of an enumerated value, the compiler will
warn you if any values are not handled). If the default case should never
execute, simply `assert`: >
execute, simply `assert`: >c
switch (var) {
case 0:
@@ -865,7 +864,7 @@ Return Values ~
Do not needlessly surround the `return` expression with parentheses.
Use parentheses in `return expr`; only where you would use them in `x =
expr;`. >
expr;`. >c
return result;
return (some_long_condition && another_condition);
@@ -879,12 +878,12 @@ Horizontal Whitespace ~
Use of horizontal whitespace depends on location.
General ~
>
>c
int x[] = { 0 }; // Spaces inside braces for braced-init-list.
<
Variables ~
>
>c
int long_variable = 0; // Don't align assignments.
int i = 1;
@@ -901,7 +900,7 @@ Use of horizontal whitespace depends on location.
Operators ~
>
>c
x = 0; // Assignment operators always have spaces around
// them.
x = -5; // No spaces separating unary operators and their

8
runtime/doc/develop.txt
View File

@@ -119,7 +119,7 @@ reflects whether Python support is working.
*provider-reload*
Sometimes a GUI or other application may want to force a provider to
"reload". To reload a provider, undefine its "loaded" flag, then use
|:runtime| to reload it: >
|:runtime| to reload it: >vim
:unlet g:loaded_clipboard_provider
:runtime autoload/provider/clipboard.vim
@@ -185,6 +185,7 @@ Docstring format:
- Limited markdown is supported.
- List-items start with `-` (useful to nest or "indent")
- Use `<pre>` for code samples.
Code samples can be annotated as `vim` or `lua`
Example: the help for |nvim_open_win()| is generated from a docstring defined
in src/nvim/api/win_config.c like this: >
@@ -193,7 +194,7 @@ in src/nvim/api/win_config.c like this: >
/// ...
///
/// Example (Lua): window-relative float
/// <pre>
/// <pre>lua
/// vim.api.nvim_open_win(0, false,
/// {relative='win', row=3, col=3, width=12, height=3})
/// </pre>
@@ -223,6 +224,7 @@ Docstring format:
- Limited markdown is supported.
- List-items start with `-` (useful to nest or "indent")
- Use `<pre>` for code samples.
Code samples can be annotated as `vim` or `lua`
Example: the help for |vim.paste()| is generated from a docstring decorating
vim.paste in runtime/lua/vim/_editor.lua like this: >
@@ -231,7 +233,7 @@ vim.paste in runtime/lua/vim/_editor.lua like this: >
--- (such as the |TUI|) pastes text into the editor.
---
--- Example: To remove ANSI color codes when pasting:
--- <pre>
--- <pre>lua
--- vim.paste = (function()
--- local overridden = vim.paste
--- ...

40
runtime/doc/diagnostic.txt
View File

@@ -68,11 +68,11 @@ The "severity" key in a diagnostic is one of the values defined in
Functions that take a severity as an optional parameter (e.g.
|vim.diagnostic.get()|) accept one of two forms:
1. A single |vim.diagnostic.severity| value: >
1. A single |vim.diagnostic.severity| value: >lua
vim.diagnostic.get(0, { severity = vim.diagnostic.severity.WARN })
2. A table with a "min" or "max" key (or both): >
2. A table with a "min" or "max" key (or both): >lua
vim.diagnostic.get(0, { severity = { min = vim.diagnostic.severity.WARN } })
@@ -107,7 +107,7 @@ Nvim provides these handlers by default: "virtual_text", "signs", and
*diagnostic-handlers-example*
The example below creates a new handler that notifies the user of diagnostics
with |vim.notify()|: >
with |vim.notify()|: >lua
-- It's good practice to namespace custom handlers to avoid collisions
vim.diagnostic.handlers["my/notify"] = {
@@ -135,7 +135,7 @@ In this example, there is nothing to do when diagnostics are hidden, so we
omit the "hide" function.
Existing handlers can be overridden. For example, use the following to only
show a sign for the highest severity diagnostic on a given line: >
show a sign for the highest severity diagnostic on a given line: >lua
-- Create a custom namespace. This will aggregate signs from all other
-- namespaces and only show the one with the highest severity on a
@@ -185,7 +185,7 @@ own default highlight groups.
For example, the default highlighting for |hl-DiagnosticSignError| is linked
to |hl-DiagnosticError|. To change the default (and therefore the linked
highlights), use the |:highlight| command: >
highlights), use the |:highlight| command: >vim
highlight DiagnosticError guifg="BrightRed"
<
@@ -279,7 +279,7 @@ SIGNS *diagnostic-signs*
Signs are defined for each diagnostic severity. The default text for each sign
is the first letter of the severity name (for example, "E" for ERROR). Signs
can be customized using the following: >
can be customized using the following: >vim
sign define DiagnosticSignError text=E texthl=DiagnosticSignError linehl= numhl=
sign define DiagnosticSignWarn text=W texthl=DiagnosticSignWarn linehl= numhl=
@@ -299,7 +299,7 @@ DiagnosticChanged After diagnostics have changed. When used from Lua,
the new diagnostics are passed to the autocmd
callback in the "data" table.
Example: >
Example: >lua
vim.api.nvim_create_autocmd('DiagnosticChanged', {
callback = function(args)
@@ -320,12 +320,12 @@ config({opts}, {namespace}) *vim.diagnostic.config()*
|vim.diagnostic.show()|). Ephemeral configuration has highest priority,
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 >lua
vim.diagnostic.config({ virtual_text = true })
<
and a diagnostic producer sets diagnostics with >
and a diagnostic producer sets diagnostics with >lua
vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false })
<
@@ -372,14 +372,14 @@ config({opts}, {namespace}) *vim.diagnostic.config()*
to render an LSP diagnostic error code.
• format: (function) A function that takes a diagnostic
as input and returns a string. The return value is
the text used to display the diagnostic. Example: >
the text used to display the diagnostic. Example: >lua
function(diagnostic)
if diagnostic.severity == vim.diagnostic.severity.ERROR then
return string.format("E: %s", diagnostic.message)
function(diagnostic)
if diagnostic.severity == vim.diagnostic.severity.ERROR then
return string.format("E: %s", diagnostic.message)
end
return diagnostic.message
end
return diagnostic.message
end
<
• signs: (default true) Use signs for diagnostics.
@@ -553,12 +553,12 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
WARNING filename:27:3: Variable 'foo' does not exist
<
This can be parsed into a diagnostic |diagnostic-structure| with: >
This can be parsed into a diagnostic |diagnostic-structure| with: >lua
local s = "WARNING filename:27:3: Variable 'foo' does not exist"
local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
local groups = { "severity", "lnum", "col", "message" }
vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
local s = "WARNING filename:27:3: Variable 'foo' does not exist"
local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
local groups = { "severity", "lnum", "col", "message" }
vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
<
Parameters: ~

62
runtime/doc/if_pyth.txt
View File

@@ -16,7 +16,7 @@ Commands *python-commands*
*:python* *:py* *E263* *E264* *E887*
:[range]py[thon] {stmt}
Execute Python statement {stmt}. A simple check if
the `:python` command is working: >
the `:python` command is working: >vim
:python print "Hello"
:[range]py[thon] << [endmarker]
@@ -31,7 +31,7 @@ The {endmarker} below the {script} must NOT be preceded by any white space.
If [endmarker] is omitted from after the "<<", a dot '.' must be used after
{script}, like for the |:append| and |:insert| commands.
Example: >
Example: >vim
function! IcecreamInitialize()
python << EOF
class StrawberryIcecream:
@@ -40,7 +40,7 @@ Example: >
EOF
endfunction
To see what version of Python you have: >
To see what version of Python you have: >vim
:python print(sys.version)
There is no need to "import sys", it's done by default.
@@ -64,12 +64,12 @@ Note: Python is very sensitive to indenting. Make sure the "class" line and
is the whole file: "1,$".
Examples:
>
>vim
:pydo return "%s\t%d" % (line[::-1], len(line))
:pydo if line: return "%4d: %s" % (linenr, line)
<
One can use `:pydo` in possible conjunction with `:py` to filter a range using
python. For example: >
python. For example: >vim
:py3 << EOF
needle = vim.eval('@a')
@@ -94,12 +94,13 @@ In the case of :pyfile, the code to execute is the contents of the given file.
Python commands cannot be used in the |sandbox|.
To pass arguments you need to set sys.argv[] explicitly. Example: >
To pass arguments you need to set sys.argv[] explicitly. Example: >vim
:python sys.argv = ["foo", "bar"]
:pyfile myscript.py
Here are some examples *python-examples* >
Here are some examples *python-examples*
>vim
:python from vim import *
:python from string import upper
@@ -113,7 +114,7 @@ to the next, just like the Python REPL.
*script-here*
When using a script language in-line, you might want to skip this when the
language isn't supported. Note that this mechanism doesn't work:
>
>vim
if has('python')
python << EOF
this will NOT work!
@@ -121,7 +122,7 @@ language isn't supported. Note that this mechanism doesn't work:
endif
Instead, put the Python command in a function and call that function:
>
>vim
if has('python')
function DefPython()
python << EOF
@@ -139,10 +140,10 @@ The vim module *python-vim*
Python code gets all of its access to vim (with one exception - see
|python-output| below) via the "vim" module. The vim module implements two
methods, three constants, and one error object. You need to import the vim
module before using it: >
module before using it: >vim
:python import vim
Overview >
Overview >vim
:py print "Hello" # displays a message
:py vim.command(cmd) # execute an Ex command
:py w = vim.windows[n] # gets window "n"
@@ -166,10 +167,10 @@ Methods of the "vim" module
vim.command(str) *python-command*
Executes the vim (ex-mode) command str. Returns None.
Examples: >
Examples: >vim
:py vim.command("set tw=72")
:py vim.command("%s/aaa/bbb/g")
< The following definition executes Normal mode commands: >
< The following definition executes Normal mode commands: >python
def normal(str):
vim.command("normal "+str)
# Note the use of single quotes to delimit a string containing
@@ -177,7 +178,7 @@ vim.command(str) *python-command*
normal('"a2dd"aP')
< *E659*
The ":python" command cannot be used recursively with Python 2.2 and
older. This only works with Python 2.3 and later: >
older. This only works with Python 2.3 and later: >vim
:py vim.command("python print 'Hello again Python'")
vim.eval(str) *python-eval*
@@ -187,7 +188,7 @@ vim.eval(str) *python-eval*
- a list if the Vim expression evaluates to a Vim list
- a dictionary if the Vim expression evaluates to a Vim dictionary
Dictionaries and lists are recursively expanded.
Examples: >
Examples: >vim
:py text_width = vim.eval("&tw")
:py str = vim.eval("12+12") # NB result is a string! Use
# string.atoi() to convert to
@@ -215,7 +216,7 @@ Error object of the "vim" module
vim.error *python-error*
Upon encountering a Vim error, Python raises an exception of type
vim.error.
Example: >
Example: >python
try:
vim.command("put a")
except vim.error:
@@ -229,7 +230,7 @@ Constants of the "vim" module
vim.buffers *python-buffers*
A mapping object providing access to the list of vim buffers. The
object supports the following operations: >
object supports the following operations: >vim
:py b = vim.buffers[i] # Indexing (read-only)
:py b in vim.buffers # Membership test
:py n = len(vim.buffers) # Number of elements
@@ -237,7 +238,7 @@ vim.buffers *python-buffers*
<
vim.windows *python-windows*
A sequence object providing access to the list of vim windows. The
object supports the following operations: >
object supports the following operations: >vim
:py w = vim.windows[i] # Indexing (read-only)
:py w in vim.windows # Membership test
:py n = len(vim.windows) # Number of elements
@@ -251,7 +252,7 @@ vim.windows *python-windows*
vim.tabpages *python-tabpages*
A sequence object providing access to the list of vim tab pages. The
object supports the following operations: >
object supports the following operations: >vim
:py t = vim.tabpages[i] # Indexing (read-only)
:py t in vim.tabpages # Membership test
:py n = len(vim.tabpages) # Number of elements
@@ -277,7 +278,7 @@ vim.current *python-current*
switching to given buffer, window or tab page. It is the only way to
switch UI objects in python: you can't assign to
|python-tabpage|.window attribute. To switch without triggering
autocommands use >
autocommands use >vim
py << EOF
saved_eventignore = vim.options['eventignore']
vim.options['eventignore'] = 'all'
@@ -330,7 +331,7 @@ the list of paths found in 'runtimepath': with this directory in sys.path and
vim.path_hooks in sys.path_hooks python will try to load module from
{rtp}/python3 and {rtp}/pythonx for each {rtp} found in 'runtimepath'.
Implementation is similar to the following, but written in C: >
Implementation is similar to the following, but written in C: >python
from imp import find_module, load_module
import vim
@@ -461,12 +462,12 @@ The buffer object methods are:
numbers s and e |inclusive|.
Note that when adding a line it must not contain a line break character '\n'.
A trailing '\n' is allowed and ignored, so that you can do: >
A trailing '\n' is allowed and ignored, so that you can do: >vim
:py b.append(f.readlines())
Buffer object type is available using "Buffer" attribute of vim module.
Examples (assume b is the current buffer) >
Examples (assume b is the current buffer) >vim
:py print b.name # write the buffer file name
:py b[0] = "hello!!!" # replace the top line
:py b[:] = None # delete the whole buffer
@@ -605,10 +606,10 @@ variants explicitly if Python 3 is required.
{script}
{endmarker}
The `:py3` and `:python3` commands work similar to `:python`. A
simple check if the `:py3` command is working: >
simple check if the `:py3` command is working: >vim
:py3 print("Hello")
<
To see what version of Python you have: >
To see what version of Python you have: >vim
:py3 import sys
:py3 print(sys.version)
< *:py3file*
@@ -619,11 +620,12 @@ variants explicitly if Python 3 is required.
The `:py3do` command works similar to `:pydo`.
*E880*
Raising SystemExit exception in python isn't endorsed way to quit vim, use: >
Raising SystemExit exception in python isn't endorsed way to quit vim, use:
>vim
:py vim.command("qall!")
<
*has-python*
You can test if Python is available with: >
You can test if Python is available with: >vim
if has('pythonx')
echo 'there is Python'
endif
@@ -642,10 +644,10 @@ works with Python 2.6+ and Python 3. As Nvim only supports Python 3,
all these commands are now synonymous to their "python3" equivalents.
*:pyx* *:pythonx*
`:pyx` and `:pythonx` work the same as `:python3`. To check if `:pyx` works: >
`:pyx` and `:pythonx` work the same as `:python3`. To check if `:pyx` works: >vim
:pyx print("Hello")
To see what version of Python is being used: >
To see what version of Python is being used: >vim
:pyx import sys
:pyx print(sys.version)
<
@@ -656,7 +658,7 @@ To see what version of Python is being used: >
`:pyxdo` works the same as `:py3do`.
*has-pythonx*
To check if `pyx*` functions and commands are available: >
To check if `pyx*` functions and commands are available: >vim
if has('pythonx')
echo 'pyx* commands are available. (Python ' .. &pyx .. ')'
endif

4
runtime/doc/intro.txt
View File

@@ -408,12 +408,12 @@ the ":map" command. The rules are:
The <> notation uses <lt> to escape the special meaning of key names. Using a
backslash also works, but only when 'cpoptions' does not include the 'B' flag.
Examples for mapping CTRL-H to the six characters "<Home>": >
Examples for mapping CTRL-H to the six characters "<Home>": >vim
:imap <C-H> \<Home>
:imap <C-H> <lt>Home>
The first one only works when the 'B' flag is not in 'cpoptions'. The second
one always works.
To get a literal "<lt>" in a mapping: >
To get a literal "<lt>" in a mapping: >vim
:map <C-L> <lt>lt>
The notation can be used in a double quoted strings, using "\<" at the start,

16
runtime/doc/job_control.txt
View File

@@ -30,7 +30,7 @@ Usage *job-control-usage*
To control jobs, use the "job…" family of functions: |jobstart()|,
|jobstop()|, etc.
Example: >
Example: >vim
function! s:OnEvent(job_id, data, event) dict
if a:event == 'stdout'
@@ -51,7 +51,7 @@ Example: >
let job1 = jobstart(['bash'], extend({'shell': 'shell 1'}, s:callbacks))
let job2 = jobstart(['bash', '-c', 'for i in {1..10}; do echo hello $i!; sleep 1; done'], extend({'shell': 'shell 2'}, s:callbacks))
To test the above script, copy it to a file ~/foo.vim and run it: >
To test the above script, copy it to a file ~/foo.vim and run it: >bash
nvim -u ~/foo.vim
<
Description of what happens:
@@ -75,7 +75,7 @@ Arguments passed to on_exit callback:
will not trigger the on_stdout/on_stderr callback (but if the process
ends, the on_exit callback will be invoked).
For example, "ruby -e" buffers output, so small strings will be
buffered unless "auto-flushing" ($stdout.sync=true) is enabled. >
buffered unless "auto-flushing" ($stdout.sync=true) is enabled. >vim
function! Receive(job_id, data, event)
echom printf('%s: %s',a:event,string(a:data))
endfunction
@@ -92,7 +92,7 @@ Arguments passed to on_exit callback:
- `abc\nefg` may arrive as `['abc', '']`, `['efg']` or `['abc']`,
`['','efg']`, or even `['ab']`, `['c','efg']`.
Easy way to deal with this: initialize a list as `['']`, then append
to it as follows: >
to it as follows: >vim
let s:chunks = ['']
func! s:on_stdout(job_id, data, event) dict
let s:chunks[-1] .= a:data[0]
@@ -101,7 +101,7 @@ Arguments passed to on_exit callback:
<
The |jobstart-options| dictionary is passed as |self| to the callback.
The above example could be written in this "object-oriented" style: >
The above example could be written in this "object-oriented" style: >vim
let Shell = {}
@@ -129,16 +129,16 @@ The above example could be written in this "object-oriented" style: >
let instance = Shell.new('bomb',
\ 'for i in $(seq 9 -1 1); do echo $i 1>&$((i % 2 + 1)); sleep 1; done')
<
To send data to the job's stdin, use |chansend()|: >
To send data to the job's stdin, use |chansend()|: >vim
:call chansend(job1, "ls\n")
:call chansend(job1, "invalid-command\n")
:call chansend(job1, "exit\n")
<
A job may be killed with |jobstop()|: >
A job may be killed with |jobstop()|: >vim
:call jobstop(job1)
<
A job may be killed at any time with the |jobstop()| function:
>
>vim
:call jobstop(job1)
<
Individual streams can be closed without killing the job, see |chanclose()|.

4
runtime/doc/lsp-extension.txt
View File

@@ -6,7 +6,7 @@
The `vim.lsp` Lua module is a framework for building LSP plugins.
1. Start with |vim.lsp.start_client()| and |vim.lsp.buf_attach_client()|.
2. Peek at the API: >
2. Peek at the API: >vim
:lua print(vim.inspect(vim.lsp))
< 3. See |lsp-extension-example| for a full example.
@@ -30,7 +30,7 @@ The example will:
3. Create a new LSP for that root directory if one doesn't exist.
4. Attach the buffer to the client for that root directory.
>
>lua
-- Some path manipulation utilities
local function is_dir(filename)
local stat = vim.loop.fs_stat(filename)

126
runtime/doc/lsp.txt
View File

@@ -33,7 +33,7 @@ Follow these steps to get LSP features:
2. Configure the LSP client per language server.
A minimal example:
>
>lua
vim.lsp.start({
name = 'my-server-name',
cmd = {'name-of-language-server-executable'},
@@ -44,7 +44,7 @@ Follow these steps to get LSP features:
3. Configure keymaps and autocmds to utilize LSP features.
See |lsp-config|.
<
*lsp-config*
Starting a LSP client will automatically report diagnostics via
@@ -66,7 +66,7 @@ language server supports the functionality.
To use other LSP features like hover, rename, etc. you can setup some
additional keymaps. It's recommended to setup them in a |LspAttach| autocmd to
ensure they're only active if there is a LSP client running. An example:
>
>lua
vim.api.nvim_create_autocmd('LspAttach', {
callback = function(args)
vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf })
@@ -86,7 +86,7 @@ The most used functions are:
Not all language servers provide the same capabilities. To ensure you only set
keymaps if the language server supports a feature, you can guard the keymap
calls behind capability checks:
>
>lua
vim.api.nvim_create_autocmd('LspAttach', {
callback = function(args)
local client = vim.lsp.get_client_by_id(args.data.client_id)
@@ -100,7 +100,7 @@ calls behind capability checks:
To learn what capabilities are available you can run the following command in
a buffer with a started LSP client:
>
>vim
:lua =vim.lsp.get_active_clients()[1].server_capabilities
<
@@ -110,14 +110,14 @@ Full list of features provided by default can be found in |lsp-buf|.
FAQ *lsp-faq*
- Q: How to force-reload LSP?
A: Stop all clients, then reload the buffer. >
A: Stop all clients, then reload the buffer. >vim
:lua vim.lsp.stop_client(vim.lsp.get_active_clients())
:edit
- Q: Why isn't completion working?
A: In the buffer where you want to use LSP, check that 'omnifunc' is set to
"v:lua.vim.lsp.omnifunc": >
"v:lua.vim.lsp.omnifunc": >vim
:verbose set omnifunc?
@@ -129,7 +129,7 @@ FAQ *lsp-faq*
A: Check if the function has an `async` parameter and set the value to
false.
E.g. code formatting: >
E.g. code formatting: >vim
" Auto-format *.rs (rust) files prior to saving them
" (async = false is the default for format)
@@ -162,7 +162,7 @@ to the given buffer. |lsp-buf|
LSP request/response handlers are implemented as Lua functions (see
|lsp-handler|). The |vim.lsp.handlers| table defines default handlers used
when creating a new client. Keys are LSP method names: >
when creating a new client. Keys are LSP method names: >vim
:lua print(vim.inspect(vim.tbl_keys(vim.lsp.handlers)))
<
@@ -291,7 +291,7 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
To configure the behavior of |vim.lsp.diagnostic.on_publish_diagnostics()|,
consider the following example, where a new |lsp-handler| is created using
|vim.lsp.with()| that no longer generates signs for the diagnostics: >
|vim.lsp.with()| that no longer generates signs for the diagnostics: >lua
vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
vim.lsp.diagnostic.on_publish_diagnostics, {
@@ -301,7 +301,7 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
)
<
To enable signs, use |vim.lsp.with()| again to create and assign a new
|lsp-handler| to |vim.lsp.handlers| for the associated method: >
|lsp-handler| to |vim.lsp.handlers| for the associated method: >lua
vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
vim.lsp.diagnostic.on_publish_diagnostics, {
@@ -311,7 +311,7 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
)
<
To configure a handler on a per-server basis, you can use the {handlers} key
for |vim.lsp.start_client()| >
for |vim.lsp.start_client()| >lua
vim.lsp.start_client {
..., -- Other configuration omitted.
@@ -325,7 +325,8 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
},
}
<
or if using 'nvim-lspconfig', you can use the {handlers} key of `setup()`: >
or if using 'nvim-lspconfig', you can use the {handlers} key of `setup()`:
>lua
require('lspconfig').rust_analyzer.setup {
handlers = {
@@ -340,7 +341,7 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
<
Some handlers do not have an explicitly named handler function (such as
||vim.lsp.diagnostic.on_publish_diagnostics()|). To override these, first
create a reference to the existing handler: >
create a reference to the existing handler: >lua
local on_references = vim.lsp.handlers["textDocument/references"]
vim.lsp.handlers["textDocument/references"] = vim.lsp.with(
@@ -357,14 +358,14 @@ Handlers can be set by:
vim.lsp.handlers is a global table that contains the default mapping of
|lsp-method| names to |lsp-handlers|.
To override the handler for the `"textDocument/definition"` method: >
To override the handler for the `"textDocument/definition"` method: >lua
vim.lsp.handlers["textDocument/definition"] = my_custom_default_definition
<
- The {handlers} parameter for |vim.lsp.start_client()|.
This will set the |lsp-handler| as the default handler for this server.
For example: >
For example: >lua
vim.lsp.start_client {
..., -- Other configuration omitted.
@@ -376,7 +377,7 @@ Handlers can be set by:
- The {handler} parameter for |vim.lsp.buf_request()|.
This will set the |lsp-handler| ONLY for the current request.
For example: >
For example: >lua
vim.lsp.buf_request(
0,
@@ -403,7 +404,7 @@ and helper functions for creating protocol-related objects.
https://github.com/microsoft/language-server-protocol/raw/gh-pages/_specifications/specification-3-14.md
For example `vim.lsp.protocol.ErrorCodes` allows reverse lookup by number or
name: >
name: >lua
vim.lsp.protocol.TextDocumentSyncKind.Full == 1
vim.lsp.protocol.TextDocumentSyncKind[1] == "Full"
@@ -426,7 +427,7 @@ For the format of the notification message, see:
- `context` table|nil. `ctx` from |lsp-handler|
This table can be used with vim.fn.setqflist or vim.fn.setloclist. E.g.:
>
>lua
local function on_list(options)
vim.fn.setqflist({}, ' ', options)
vim.api.nvim_command('cfirst')
@@ -436,7 +437,7 @@ This table can be used with vim.fn.setqflist or vim.fn.setloclist. E.g.:
vim.lsp.buf.references(nil, {on_list=on_list})
<
If you prefer loclist do something like this:
>
>lua
local function on_list(options)
vim.fn.setloclist(0, {}, ' ', options)
vim.api.nvim_command('lopen')
@@ -487,7 +488,7 @@ EVENTS *lsp-events*
*LspAttach*
After an LSP client attaches to a buffer. The |autocmd-pattern| is the
name of the buffer. When used from Lua, the client ID is passed to the
callback in the "data" table. Example: >
callback in the "data" table. Example: >lua
vim.api.nvim_create_autocmd("LspAttach", {
callback = function(args)
@@ -505,7 +506,7 @@ callback in the "data" table. Example: >
*LspDetach*
Just before an LSP client detaches from a buffer. The |autocmd-pattern| is the
name of the buffer. When used from Lua, the client ID is passed to the
callback in the "data" table. Example: >
callback in the "data" table. Example: >lua
vim.api.nvim_create_autocmd("LspDetach", {
callback = function(args)
@@ -525,7 +526,7 @@ LspRequest *LspRequest*
After a change to the active set of pending LSP requests. See {requests}
in |vim.lsp.client|.
Example: >
Example: >vim
autocmd User LspProgressUpdate redrawstatus
autocmd User LspRequest redrawstatus
<
@@ -680,7 +681,7 @@ for_each_buffer_client({bufnr}, {fn})
• {bufnr} (number) Buffer number
• {fn} (function) Function to run on each client attached to buffer
{bufnr}. The function takes the client, client ID, and buffer
number as arguments. Example: >
number as arguments. Example: >lua
vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr)
print(vim.inspect(client))
@@ -779,14 +780,13 @@ start({config}, {opts}) *vim.lsp.start()*
running client if one is found matching `name` and `root_dir`. Attaches
the current buffer to the client.
Example:
>
Example: >lua
vim.lsp.start({
name = 'my-server-name',
cmd = {'name-of-language-server-executable'},
root_dir = vim.fs.dirname(vim.fs.find({'pyproject.toml', 'setup.py'}, { upward = true })[1]),
})
vim.lsp.start({
name = 'my-server-name',
cmd = {'name-of-language-server-executable'},
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
@@ -963,11 +963,9 @@ start_client({config}) *vim.lsp.start_client()*
stop_client({client_id}, {force}) *vim.lsp.stop_client()*
Stops a client(s).
You can also use the `stop()` function on a |vim.lsp.client| object. To
stop all clients:
>
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_active_clients())
vim.lsp.stop_client(vim.lsp.get_active_clients())
<
By default asks the server to shutdown, unless stop was requested already
@@ -1077,11 +1075,10 @@ definition({options}) *vim.lsp.buf.definition()*
document_highlight() *vim.lsp.buf.document_highlight()*
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
by events such as `CursorHold`, e.g.:
>
autocmd CursorHold <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()
by events such as `CursorHold` , e.g.: >vim
autocmd CursorHold <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()
<
Note: Usage of |vim.lsp.buf.document_highlight()| requires the following
@@ -1125,12 +1122,12 @@ format({options}) *vim.lsp.buf.format()*
buffer (0).
• filter (function|nil): Predicate used to filter clients.
Receives a client as argument and must return a boolean.
Clients matching the predicate are included. Example: • >
Clients matching the predicate are included. Example: • >lua
-- Never request typescript-language-server for formatting
vim.lsp.buf.format {
filter = function(client) return client.name ~= "tsserver" end
}
-- Never request typescript-language-server for formatting
vim.lsp.buf.format {
filter = function(client) return client.name ~= "tsserver" end
}
<
• async boolean|nil If true the method won't block.
Defaults to false. Editing the buffer while formatting
@@ -1252,7 +1249,7 @@ on_publish_diagnostics({_}, {result}, {ctx}, {config})
|lsp-handler| for the method "textDocument/publishDiagnostics"
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()|: >lua
vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
vim.lsp.diagnostic.on_publish_diagnostics, {
@@ -1305,8 +1302,9 @@ refresh() *vim.lsp.codelens.refresh()*
Refresh the codelens for the current buffer
It is recommended to trigger this using an autocmd or via keymap.
>
autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
Example: >vim
autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
<
run() *vim.lsp.codelens.run()*
@@ -1325,16 +1323,16 @@ save({lenses}, {bufnr}, {client_id}) *vim.lsp.codelens.save()*
Lua module: vim.lsp.handlers *lsp-handlers*
hover({_}, {result}, {ctx}, {config}) *vim.lsp.handlers.hover()*
|lsp-handler| for the method "textDocument/hover" >
|lsp-handler| for the method "textDocument/hover" >lua
vim.lsp.handlers["textDocument/hover"] = vim.lsp.with(
vim.lsp.handlers.hover, {
-- Use a sharp border with `FloatBorder` highlights
border = "single",
-- add the title in hover float window
title = "hover"
}
)
vim.lsp.handlers["textDocument/hover"] = vim.lsp.with(
vim.lsp.handlers.hover, {
-- Use a sharp border with `FloatBorder` highlights
border = "single",
-- add the title in hover float window
title = "hover"
}
)
<
Parameters: ~
@@ -1346,14 +1344,14 @@ hover({_}, {result}, {ctx}, {config}) *vim.lsp.handlers.hover()*
*vim.lsp.handlers.signature_help()*
signature_help({_}, {result}, {ctx}, {config})
|lsp-handler| for the method "textDocument/signatureHelp". The active
parameter is highlighted with |hl-LspSignatureActiveParameter|. >
parameter is highlighted with |hl-LspSignatureActiveParameter|. >lua
vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
vim.lsp.handlers.signature_help, {
-- Use a sharp border with `FloatBorder` highlights
border = "single"
}
)
vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
vim.lsp.handlers.signature_help, {
-- Use a sharp border with `FloatBorder` highlights
border = "single"
}
)
<
Parameters: ~

333
runtime/doc/lua.txt
View File

@@ -12,7 +12,7 @@ Lua engine *lua* *Lua*
INTRODUCTION *lua-intro*
The Lua 5.1 script engine is builtin and always available. Try this command to
get an idea of what lurks beneath: >
get an idea of what lurks beneath: >vim
:lua print(vim.inspect(package.loaded))
@@ -56,20 +56,20 @@ https://www.lua.org/doc/cacm2018.pdf
versatile control for both Lua and its host (Nvim).
*lua-call-function*
Lua functions can be called in multiple ways. Consider the function: >
Lua functions can be called in multiple ways. Consider the function: >lua
local foo = function(a, b)
print("A: ", a)
print("B: ", b)
end
The first way to call this function is: >
The first way to call this function is: >lua
foo(1, 2)
-- ==== Result ====
-- A: 1
-- B: 2
This way of calling a function is familiar from most scripting languages.
In Lua, any missing arguments are passed as `nil`. Example: >
In Lua, any missing arguments are passed as `nil`. Example: >lua
foo(1)
-- ==== Result ====
-- A: 1
@@ -81,7 +81,7 @@ discarded.
It is also allowed to omit the parentheses (only) if the function takes
exactly one string (`"foo"`) or table literal (`{1,2,3}`). The latter is often
used to approximate the "named parameters" feature of languages like Python
("kwargs" or "keyword args"). Example: >
("kwargs" or "keyword args"). Example: >lua
local func_with_opts = function(opts)
local will_do_foo = opts.foo
local filename = opts.filename
@@ -95,7 +95,7 @@ There is nothing special going on here except that parentheses are treated as
whitespace. But visually, this small bit of sugar gets reasonably close to
a "keyword args" interface.
It is of course also valid to call the function with parentheses: >
It is of course also valid to call the function with parentheses: >lua
func_with_opts({ foo = true, filename = "hello.world" })
<
@@ -108,7 +108,7 @@ Lua intentionally does not support regular expressions, instead it has limited
"patterns" which avoid the performance pitfalls of extended regex.
|luaref-patterns|
Examples using |string.match()|: >
Examples using |string.match()|: >lua
print(string.match("foo123bar123", "%d+"))
-- 123
@@ -205,7 +205,7 @@ Note:
- Although adjustments happen automatically, Nvim does not track current
values of |package.path| or |package.cpath|. If you happen to delete some
paths from there you can set 'runtimepath' to trigger an update: >
paths from there you can set 'runtimepath' to trigger an update: >vim
let &runtimepath = &runtimepath
- Skipping paths from 'runtimepath' which contain semicolons applies both to
@@ -231,11 +231,11 @@ arguments separated by " " (space) instead of "\t" (tab).
chunk is evaluated as an expression and printed. `:lua =expr` is
equivalent to `:lua print(vim.inspect(expr))`
Examples: >
Examples: >vim
:lua vim.api.nvim_command('echo "Hello, Nvim!"')
< To see the Lua version: >
< To see the Lua version: >vim
:lua print(_VERSION)
< To see the LuaJIT version: >
< To see the LuaJIT version: >vim
:lua =jit.version
<
*:lua-heredoc*
@@ -246,7 +246,7 @@ arguments separated by " " (space) instead of "\t" (tab).
be preceded by whitespace. You can omit [endmarker] after the "<<" and use
a dot "." after {script} (similar to |:append|, |:insert|).
Example: >
Example: >vim
function! CurrentLineInfo()
lua << EOF
local linenr = vim.api.nvim_win_get_cursor(0)[1]
@@ -268,7 +268,7 @@ arguments separated by " " (space) instead of "\t" (tab).
that becomes the text of the corresponding buffer line. Default [range] is
the whole file: "1,$".
Examples: >
Examples: >vim
:luado return string.format("%s\t%d", line:reverse(), #line)
:lua require"lpeg"
@@ -282,7 +282,7 @@ arguments separated by " " (space) instead of "\t" (tab).
The whole argument is used as the filename (like |:edit|), spaces do not
need to be escaped. Alternatively you can |:source| Lua files.
Examples: >
Examples: >vim
:luafile script.lua
:luafile %
<
@@ -293,7 +293,7 @@ luaeval() *lua-eval* *luaeval()*
The (dual) equivalent of "vim.eval" for passing Lua values to Nvim is
"luaeval". "luaeval" takes an expression string and an optional argument used
for _A inside expression and returns the result of the expression. It is
semantically equivalent in Lua to: >
semantically equivalent in Lua to: >lua
local chunkheader = "local _A = select(1, ...) return "
function luaeval (expstr, arg)
@@ -307,11 +307,11 @@ converted to a |Blob|. Conversion of other Lua types is an error.
The magic global "_A" contains the second argument to luaeval().
Example: >
Example: >vim
:echo luaeval('_A[1] + _A[2]', [40, 2])
42
" 42
:echo luaeval('string.match(_A, "[a-z]+")', 'XYXfoo123')
foo
" foo
<
Lua tables are used as both dictionaries and lists, so it is impossible to
determine whether empty table is meant to be empty list or empty dictionary.
@@ -343,7 +343,7 @@ cases there is the following agreement:
form a 1-step sequence from 1 to N are ignored, as well as all
non-integral keys.
Examples: >
Examples: >vim
:echo luaeval('math.pi')
:function Rand(x,y) " random uniform between x and y
@@ -360,29 +360,29 @@ treated specially.
Vimscript v:lua interface *v:lua-call*
From Vimscript the special `v:lua` prefix can be used to call Lua functions
which are global or accessible from global tables. The expression >
v:lua.func(arg1, arg2)
is equivalent to the Lua chunk >
which are global or accessible from global tables. The expression >vim
call v:lua.func(arg1, arg2)
is equivalent to the Lua chunk >lua
return func(...)
where the args are converted to Lua values. The expression >
v:lua.somemod.func(args)
is equivalent to the Lua chunk >
where the args are converted to Lua values. The expression >vim
call v:lua.somemod.func(args)
is equivalent to the Lua chunk >lua
return somemod.func(...)
In addition, functions of packages can be accessed like >
v:lua.require'mypack'.func(arg1, arg2)
v:lua.require'mypack.submod'.func(arg1, arg2)
In addition, functions of packages can be accessed like >vim
call v:lua.require'mypack'.func(arg1, arg2)
call v:lua.require'mypack.submod'.func(arg1, arg2)
Note: Only single quote form without parens is allowed. Using
`require"mypack"` or `require('mypack')` as prefixes do NOT work (the latter
is still valid as a function call of itself, in case require returns a useful
value).
The `v:lua` prefix may be used to call Lua functions as |method|s. For
example: >
arg1->v:lua.somemod.func(arg2)
example: >vim
:eval arg1->v:lua.somemod.func(arg2)
<
You can use `v:lua` in "func" options like 'tagfunc', 'omnifunc', etc.
For example consider the following Lua omnifunc handler: >
For example consider the following Lua omnifunc handler: >lua
function mymod.omnifunc(findstart, base)
if findstart == 1 then
@@ -397,7 +397,7 @@ Note: The module ("mymod" in the above example) must either be a Lua global,
or use the require syntax as specified above to access it from a package.
Note: `v:lua` without a call is not allowed in a Vimscript expression:
|Funcref|s cannot represent Lua functions. The following are errors: >
|Funcref|s cannot represent Lua functions. The following are errors: >vim
let g:Myvar = v:lua.myfunc " Error
call SomeFunc(v:lua.mycallback) " Error
@@ -411,7 +411,7 @@ The Nvim Lua "standard library" (stdlib) is the `vim` module, which exposes
various functions and sub-modules. It is always loaded, thus `require("vim")`
is unnecessary.
You can peek at the module properties: >
You can peek at the module properties: >vim
:lua print(vim.inspect(vim))
@@ -431,7 +431,7 @@ Result is something like this: >
...
}
To find documentation on e.g. the "deepcopy" function: >
To find documentation on e.g. the "deepcopy" function: >vim
:help vim.deepcopy()
@@ -443,7 +443,7 @@ VIM.LOOP *lua-loop* *vim.loop*
`vim.loop` exposes all features of the Nvim event-loop. This is a low-level
API that provides functionality for networking, filesystem, and process
management. Try this command to see available functions: >
management. Try this command to see available functions: >vim
:lua print(vim.inspect(vim.loop))
<
@@ -452,14 +452,14 @@ see |luv-intro| for a full reference manual.
*E5560* *lua-loop-callbacks*
It is an error to directly invoke `vim.api` functions (except |api-fast|) in
`vim.loop` callbacks. For example, this is an error: >
`vim.loop` callbacks. For example, this is an error: >lua
local timer = vim.loop.new_timer()
timer:start(1000, 0, function()
vim.api.nvim_command('echomsg "test"')
end)
<
To avoid the error use |vim.schedule_wrap()| to defer the callback: >
To avoid the error use |vim.schedule_wrap()| to defer the callback: >lua
local timer = vim.loop.new_timer()
timer:start(1000, 0, vim.schedule_wrap(function()
@@ -471,7 +471,7 @@ wrapping.)
Example: repeating timer
1. Save this code to a file.
2. Execute it with ":luafile %". >
2. Execute it with ":luafile %". >lua
-- Create a timer handle (implementation detail: uv_timer_t).
local timer = vim.loop.new_timer()
@@ -492,7 +492,7 @@ Example: File-change detection *watch-file*
3. Use ":Watch %" to watch any file.
4. Try editing the file from another text editor.
5. Observe that the file reloads in Nvim (because on_change() calls
|:checktime|). >
|:checktime|). >lua
local w = vim.loop.new_fs_event()
local function on_change(err, fname, status)
@@ -515,7 +515,7 @@ Example: TCP echo-server *tcp-server*
1. Save this code to a file.
2. Execute it with ":luafile %".
3. Note the port number.
4. Connect from any TCP client (e.g. "nc 0.0.0.0 36795"): >
4. Connect from any TCP client (e.g. "nc 0.0.0.0 36795"): >lua
local function create_server(host, port, on_connect)
local server = vim.loop.new_tcp()
@@ -564,16 +564,16 @@ VIM.HIGHLIGHT *lua-highlight*
Nvim includes a function for highlighting a selection on yank (see for example
https://github.com/machakann/vim-highlightedyank). To enable it, add
>
>vim
au TextYankPost * silent! lua vim.highlight.on_yank()
<
to your `init.vim`. You can customize the highlight group and the duration of
the highlight via
>
>vim
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}
<
vim.highlight.on_yank({opts}) *vim.highlight.on_yank()*
@@ -646,20 +646,19 @@ vim.diff({a}, {b}, {opts}) *vim.diff()*
Run diff on strings {a} and {b}. Any indices returned by this function,
either directly or via callback arguments, are 1-based.
Examples: >
Examples: >lua
vim.diff('a\n', 'b\nc\n')
=>
@@ -1 +1,2 @@
-a
+b
+c
-- =>
-- @@ -1 +1,2 @@
-- -a
-- +b
-- +c
vim.diff('a\n', 'b\nc\n', {result_type = 'indices'})
=>
{
{1, 1, 1, 2}
}
-- =>
-- {
-- {1, 1, 1, 2}
-- }
<
Parameters: ~
• {a} First string to compare
@@ -730,13 +729,12 @@ vim.spell.check({str}) *vim.spell.check()*
'spellfile', 'spellcapcheck' and 'spelloptions' which can all be local to
the buffer. Consider calling this with |nvim_buf_call()|.
Example: >
Example: >lua
vim.spell.check("the quik brown fox")
=>
{
{'quik', 'bad', 4}
}
-- =>
-- {
-- {'quik', 'bad', 4}
-- }
<
Parameters: ~
• {str} String to spell check.
@@ -756,7 +754,7 @@ VIM *lua-builtin*
vim.api.{func}({...}) *vim.api*
Invokes Nvim |API| function {func} with arguments {...}.
Example: call the "nvim_get_current_line()" API function: >
Example: call the "nvim_get_current_line()" API function: >lua
print(tostring(vim.api.nvim_get_current_line()))
vim.version() *vim.version*
@@ -881,7 +879,7 @@ vim.wait({time} [, {callback}, {interval}, {fast_only}]) *vim.wait()*
If {callback} errors, the error is raised.
Examples: >
Examples: >lua
---
-- Wait for 100 ms, allowing other events to process
@@ -922,7 +920,7 @@ vim.ui_attach({ns}, {options}, {callback}) *vim.ui_attach()*
used to handle messages when setting 'cmdheight' to zero (which is
likewise experimental).
Example (stub for a |ui-popupmenu| implementation): >
Example (stub for a |ui-popupmenu| implementation): >lua
ns = vim.api.nvim_create_namespace('my_fancy_pum')
@@ -950,7 +948,7 @@ vim.type_idx *vim.type_idx*
vim.val_idx *vim.val_idx*
Value index for tables representing |Float|s. A table representing
floating-point value 1.0 looks like this: >
floating-point value 1.0 looks like this: >lua
{
[vim.type_idx] = vim.types.float,
[vim.val_idx] = 1.0,
@@ -997,7 +995,7 @@ See also https://github.com/nanotee/nvim-lua-guide.
vim.call({func}, {...}) *vim.call()*
Invokes |vim-function| or |user-function| {func} with arguments {...}.
See also |vim.fn|.
Equivalent to: >
Equivalent to: >lua
vim.fn[func]({...})
vim.cmd({command})
@@ -1005,7 +1003,7 @@ vim.cmd({command})
vim.fn.{func}({...}) *vim.fn*
Invokes |vim-function| or |user-function| {func} with arguments {...}.
To call autoload functions, use the syntax: >
To call autoload functions, use the syntax: >lua
vim.fn['some#function']({...})
<
Unlike vim.api.|nvim_call_function()| this converts directly between Vim
@@ -1028,7 +1026,7 @@ from Lua conveniently and idiomatically by referencing the `vim.*` Lua tables
described below. In this way you can easily read and modify global Vimscript
variables from Lua.
Example: >
Example: >lua
vim.g.foo = 5 -- Set the g:foo Vimscript variable.
print(vim.g.foo) -- Get and print the g:foo Vimscript variable.
@@ -1041,7 +1039,7 @@ Nvim. This is because the index into the namespace simply returns a copy.
Instead the whole dictionary must be written as one. This can be achieved by
creating a short-lived temporary.
Example: >
Example: >lua
vim.g.my_dict.field1 = 'value' -- Does not work
@@ -1076,7 +1074,7 @@ vim.env *vim.env*
Environment variables defined in the editor session.
See |expand-env| and |:let-environment| for the Vimscript behavior.
Invalid or unset key returns `nil`.
Example: >
Example: >lua
vim.env.FOO = 'bar'
print(vim.env.TERM)
<
@@ -1110,7 +1108,7 @@ vim.o *vim.o*
Note: this works on both buffer-scoped and window-scoped options using the
current buffer and window.
Example: >
Example: >lua
vim.o.cmdheight = 4
print(vim.o.columns)
print(vim.o.foo) -- error: invalid key
@@ -1123,7 +1121,7 @@ vim.go *vim.go*
option value and thus is mostly useful for use with |global-local|
options.
Example: >
Example: >lua
vim.go.cmdheight = 4
print(vim.go.columns)
print(vim.go.bar) -- error: invalid key
@@ -1135,7 +1133,7 @@ vim.bo[{bufnr}] *
Note: this is equivalent to both `:set` and `:setlocal`.
Example: >
Example: >lua
local bufnr = vim.api.nvim_get_current_buf()
vim.bo[bufnr].buflisted = true -- same as vim.bo.buflisted = true
print(vim.bo.comments)
@@ -1146,11 +1144,11 @@ vim.wo[{winid}] *
Like `:set`. If [{winid}] is omitted then the current window is used.
Invalid {winid} or key is an error.
Note: this does not access |local-options| (`:setlocal`) instead use: >
Note: this does not access |local-options| (`:setlocal`) instead use: >lua
nvim_get_option_value(OPTION, { scope = 'local', win = winid })
nvim_set_option_value(OPTION, VALUE, { scope = 'local', win = winid }
<
Example: >
Example: >lua
local winid = vim.api.nvim_get_current_win()
vim.wo[winid].number = true -- same as vim.wo.number = true
print(vim.wo.foldmarker)
@@ -1171,37 +1169,37 @@ offers object-oriented method for adding and removing entries.
Examples: ~
The following methods of setting a list-style option are equivalent:
In Vimscript:
`set wildignore=*.o,*.a,__pycache__`
In Lua using `vim.o`:
`vim.o.wildignore = '*.o,*.a,__pycache__'`
In Lua using `vim.opt`:
`vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }`
To replicate the behavior of |:set+=|, use: >
In Vimscript: >vim
set wildignore=*.o,*.a,__pycache__
<
In Lua using `vim.o`: >lua
vim.o.wildignore = '*.o,*.a,__pycache__'
<
In Lua using `vim.opt`: >lua
vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }
<
To replicate the behavior of |:set+=|, use: >lua
vim.opt.wildignore:append { "*.pyc", "node_modules" }
<
To replicate the behavior of |:set^=|, use: >
To replicate the behavior of |:set^=|, use: >lua
vim.opt.wildignore:prepend { "new_first_value" }
<
To replicate the behavior of |:set-=|, use: >
To replicate the behavior of |:set-=|, use: >lua
vim.opt.wildignore:remove { "node_modules" }
<
The following methods of setting a map-style option are equivalent:
In Vimscript:
`set listchars=space:_,tab:>~`
In Lua using `vim.o`:
`vim.o.listchars = 'space:_,tab:>~'`
In Lua using `vim.opt`:
`vim.opt.listchars = { space = '_', tab = '>~' }`
In Vimscript: >vim
set listchars=space:_,tab:>~
<
In Lua using `vim.o`: >lua
vim.o.listchars = 'space:_,tab:>~'
<
In Lua using `vim.opt`: >lua
vim.opt.listchars = { space = '_', tab = '>~' }
<
Note that |vim.opt| returns an `Option` object, not the value of the option,
which is accessed through |vim.opt:get()|:
@@ -1209,15 +1207,15 @@ which is accessed through |vim.opt:get()|:
Examples: ~
The following methods of getting a list-style option are equivalent:
In Vimscript:
`echo wildignore`
In Lua using `vim.o`:
`print(vim.o.wildignore)`
In Lua using `vim.opt`:
`vim.pretty_print(vim.opt.wildignore:get())`
In Vimscript: >vim
echo wildignore
<
In Lua using `vim.o`: >lua
print(vim.o.wildignore)
<
In Lua using `vim.opt`: >lua
vim.pretty_print(vim.opt.wildignore:get())
<
In any of the above examples, to replicate the behavior |:setlocal|, use
`vim.opt_local`. Additionally, to replicate the behavior of |:setglobal|, use
@@ -1232,7 +1230,7 @@ Option:get()
values will be returned in exactly the same fashion.
For values that are comma-separated lists, an array will be returned with
the values as entries in the array: >
the values as entries in the array: >lua
vim.cmd [[set wildignore=*.pyc,*.o]]
vim.pretty_print(vim.opt.wildignore:get())
@@ -1245,7 +1243,7 @@ Option:get()
-- Will ignore: *.o
<
For values that are comma-separated maps, a table will be returned with
the names as keys and the values as entries: >
the names as keys and the values as entries: >lua
vim.cmd [[set listchars=space:_,tab:>~]]
vim.pretty_print(vim.opt.listchars:get())
@@ -1256,7 +1254,7 @@ Option:get()
end
<
For values that are lists of flags, a set will be returned with the flags
as keys and `true` as entries. >
as keys and `true` as entries. >lua
vim.cmd [[set formatoptions=njtcroql]]
vim.pretty_print(vim.opt.formatoptions:get())
@@ -1272,28 +1270,28 @@ Option:append(value)
Append a value to string-style options. See |:set+=|
These are equivalent:
`vim.opt.formatoptions:append('j')`
`vim.opt.formatoptions = vim.opt.formatoptions + 'j'`
These are equivalent: >lua
vim.opt.formatoptions:append('j')
vim.opt.formatoptions = vim.opt.formatoptions + 'j'
<
*vim.opt:prepend()*
Option:prepend(value)
Prepend a value to string-style options. See |:set^=|
These are equivalent:
`vim.opt.wildignore:prepend('*.o')`
`vim.opt.wildignore = vim.opt.wildignore ^ '*.o'`
These are equivalent: >lua
vim.opt.wildignore:prepend('*.o')
vim.opt.wildignore = vim.opt.wildignore ^ '*.o'
<
*vim.opt:remove()*
Option:remove(value)
Remove a value from string-style options. See |:set-=|
These are equivalent:
`vim.opt.wildignore:remove('*.pyc')`
`vim.opt.wildignore = vim.opt.wildignore - '*.pyc'`
These are equivalent: >lua
vim.opt.wildignore:remove('*.pyc')
vim.opt.wildignore = vim.opt.wildignore - '*.pyc'
<
==============================================================================
Lua module: vim *lua-vim*
@@ -1304,7 +1302,7 @@ cmd({command}) *vim.cmd()*
Note that `vim.cmd` can be indexed with a command name to return a
callable function to the command.
Example: >
Example: >lua
vim.cmd('echo 42')
vim.cmd([[
@@ -1438,7 +1436,7 @@ paste({lines}, {phase}) *vim.paste()*
Paste handler, invoked by |nvim_paste()| when a conforming UI (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: >lua
vim.paste = (function(overridden)
return function(lines, phase)
@@ -1467,7 +1465,7 @@ paste({lines}, {phase}) *vim.paste()*
|paste| @alias paste_phase -1 | 1 | 2 | 3
pretty_print({...}) *vim.pretty_print()*
Prints given arguments in human-readable format. Example: >
Prints given arguments in human-readable format. Example: >lua
-- Print highlight group Normal and store it's contents in a variable.
local hl_normal = vim.pretty_print(vim.api.nvim_get_hl_by_name("Normal", true))
<
@@ -1546,10 +1544,11 @@ defaulttable({create}) *vim.defaulttable()*
If {create} is `nil`, this will create a defaulttable whose constructor
function is this function, effectively allowing to create nested tables on
the fly:
>
local a = vim.defaulttable()
a.b.c = 1
>lua
local a = vim.defaulttable()
a.b.c = 1
<
Parameters: ~
@@ -1639,12 +1638,12 @@ pesc({s}) *vim.pesc()*
split({s}, {sep}, {kwargs}) *vim.split()*
Splits a string at each instance of a separator.
Examples: >
Examples: >lua
split(":aa::b:", ":") => {'','aa','','b',''}
split("axaby", "ab?") => {'','x','y'}
split("x*yz*o", "*", {plain=true}) => {'x','yz','o'}
split("|x|y|z|", "|", {trimempty=true}) => {'x', 'y', 'z'}
split(":aa::b:", ":") --> {'','aa','','b',''}
split("axaby", "ab?") --> {'','x','y'}
split("x*yz*o", "*", {plain=true}) --> {'x','yz','o'}
split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'}
<
Parameters: ~
@@ -1697,10 +1696,11 @@ tbl_contains({t}, {value}) *vim.tbl_contains()*
tbl_count({t}) *vim.tbl_count()*
Counts the number of non-nil values in table `t`.
>
vim.tbl_count({ a=1, b=2 }) => 2
vim.tbl_count({ 1, 2 }) => 2
>lua
vim.tbl_count({ a=1, b=2 }) --> 2
vim.tbl_count({ 1, 2 }) --> 2
<
Parameters: ~
@@ -1773,7 +1773,7 @@ tbl_get({o}, {...}) *vim.tbl_get()*
Index into a table (first argument) via string keys passed as subsequent
arguments. Return `nil` if the key does not exist.
Examples: >
Examples: >lua
vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true
vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil
@@ -1860,7 +1860,7 @@ trim({s}) *vim.trim()*
validate({opt}) *vim.validate()*
Validates a parameter specification (types and values).
Usage example: >
Usage example: >lua
function user.new(name, age, hobbies)
vim.validate{
@@ -1872,25 +1872,25 @@ validate({opt}) *vim.validate()*
end
<
Examples with explicit argument values (can be run directly): >
Examples with explicit argument values (can be run directly): >lua
vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
=> NOP (success)
--> NOP (success)
vim.validate{arg1={1, 'table'}}
=> error('arg1: expected table, got number')
--> error('arg1: expected table, got number')
vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}}
=> error('arg1: expected even number, got 3')
--> 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. >lua
vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}}
=> NOP (success)
--> NOP (success)
vim.validate{arg1={1, {'string', table'}}}
=> error('arg1: expected string|table, got number')
--> error('arg1: expected string|table, got number')
<
Parameters: ~
@@ -1959,7 +1959,7 @@ Lua module: ui *lua-ui*
input({opts}, {on_confirm}) *vim.ui.input()*
Prompts the user for input
Example: >
Example: >lua
vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input)
vim.o.shiftwidth = tonumber(input)
@@ -1984,7 +1984,7 @@ input({opts}, {on_confirm}) *vim.ui.input()*
select({items}, {opts}, {on_choice}) *vim.ui.select()*
Prompts the user to pick a single item from a collection of entries
Example: >
Example: >lua
vim.ui.select({ 'tabs', 'spaces' }, {
prompt = 'Select tabs or spaces:',
@@ -2047,7 +2047,7 @@ add({filetypes}) *vim.filetype.add()*
See $VIMRUNTIME/lua/vim/filetype.lua for more examples.
Example: >
Example: >lua
vim.filetype.add({
extension = {
@@ -2083,7 +2083,7 @@ add({filetypes}) *vim.filetype.add()*
})
<
To add a fallback match on contents, use >
To add a fallback match on contents, use >lua
vim.filetype.add {
pattern = {
@@ -2122,19 +2122,20 @@ match({args}) *vim.filetype.match()*
Each of the three options is specified using a key to the single argument
of this function. Example:
>
-- Using a buffer number
vim.filetype.match({ buf = 42 })
>lua
-- Override the filename of the given buffer
vim.filetype.match({ buf = 42, filename = 'foo.c' })
-- Using a buffer number
vim.filetype.match({ buf = 42 })
-- Using a filename without a buffer
vim.filetype.match({ filename = 'main.lua' })
-- Override the filename of the given buffer
vim.filetype.match({ buf = 42, filename = 'foo.c' })
-- Using file contents
vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })
-- Using a filename without a buffer
vim.filetype.match({ filename = 'main.lua' })
-- Using file contents
vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })
<
Parameters: ~
@@ -2164,7 +2165,7 @@ match({args}) *vim.filetype.match()*
Lua module: keymap *lua-keymap*
del({modes}, {lhs}, {opts}) *vim.keymap.del()*
Remove an existing mapping. Examples: >
Remove an existing mapping. Examples: >lua
vim.keymap.del('n', 'lhs')
@@ -2180,7 +2181,7 @@ del({modes}, {lhs}, {opts}) *vim.keymap.del()*
|vim.keymap.set()|
set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()*
Add a new |mapping|. Examples: >
Add a new |mapping|. Examples: >lua
-- Can add mapping to Lua functions
vim.keymap.set('n', 'lhs', function() print("real lua function") end)
@@ -2199,14 +2200,14 @@ set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()*
vim.keymap.set('n', '[%', '<Plug>(MatchitNormalMultiBackward)')
<
Note that in a mapping like: >
Note that in a mapping like: >lua
vim.keymap.set('n', 'asdf', require('jkl').my_fun)
<
the `require('jkl')` gets evaluated during this call in order to access the function. If you
want to avoid this cost at startup you can wrap it in a function, for
example: >
example: >lua
vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
<
@@ -2304,8 +2305,8 @@ find({names}, {opts}) *vim.fs.find()*
number of matches.
Return: ~
(table) The normalized paths |vim.fs.normalize()| of all matching
files or directories
(table) Normalized paths |vim.fs.normalize()| of all matching files or
directories
normalize({path}) *vim.fs.normalize()*
Normalize a path to a standard format. A tilde (~) character at the
@@ -2313,16 +2314,16 @@ normalize({path}) *vim.fs.normalize()*
backslash (\) characters are converted to forward slashes (/). Environment
variables are also expanded.
Examples: >
Examples: >lua
vim.fs.normalize('C:\Users\jdoe')
=> 'C:/Users/jdoe'
--> 'C:/Users/jdoe'
vim.fs.normalize('~/src/neovim')
=> '/home/jdoe/src/neovim'
--> '/home/jdoe/src/neovim'
vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim')
=> '/Users/jdoe/.config/nvim/init.vim'
--> '/Users/jdoe/.config/nvim/init.vim'
<
Parameters: ~
@@ -2334,7 +2335,7 @@ normalize({path}) *vim.fs.normalize()*
parents({start}) *vim.fs.parents()*
Iterate over all the parents of the given file or directory.
Example: >
Example: >lua
local root_dir
for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do

410
runtime/doc/luaref.txt
View File

File diff suppressed because it is too large Load Diff

40
runtime/doc/luvref.txt
View File

@@ -28,7 +28,7 @@ TCP Echo Server Example~
Here is a small example showing a TCP echo server:
>
>lua
local uv = vim.loop
local server = uv.new_tcp()
@@ -250,7 +250,7 @@ uv.loop_configure({option}, {...}) *uv.loop_configure()*
An example of a valid call to this function is:
>
>lua
uv.loop_configure("block_signal", "sigprof")
<
@@ -343,7 +343,7 @@ uv.walk({callback}) *uv.walk()*
Returns: Nothing.
>
>lua
-- Example usage of uv.walk to close all handles that
-- aren't already closing.
uv.walk(function (handle)
@@ -613,7 +613,7 @@ uv.new_timer() *uv.new_timer()*
Returns: `uv_timer_t userdata` or `fail`
>
>lua
-- Creating a simple setTimeout wrapper
local function setTimeout(timeout, callback)
local timer = uv.new_timer()
@@ -737,7 +737,7 @@ uv.timer_get_due_in({timer}) *uv.timer_get_due_in()*
Prepare handles will run the given callback once per loop iteration, right
before polling for I/O.
>
>lua
local prepare = uv.new_prepare()
prepare:start(function()
print("Before I/O polling")
@@ -782,7 +782,7 @@ uv.prepare_stop({prepare}) *uv.prepare_stop()*
Check handles will run the given callback once per loop iteration, right after
polling for I/O.
>
>lua
local check = uv.new_check()
check:start(function()
print("After I/O polling")
@@ -834,7 +834,7 @@ blocking for I/O.
WARNING: Despite the name, idle handles will get their callbacks called on
every loop iteration, not when the loop is actually "idle".
>
>lua
local idle = uv.new_idle()
idle:start(function()
print("Before I/O polling, no blocking")
@@ -879,7 +879,7 @@ uv.idle_stop({check}) *uv.idle_stop()*
Async handles allow the user to "wakeup" the event loop and get a callback
called from another thread.
>
>lua
local async
async = uv.new_async(function()
print("async operation ran")
@@ -1062,7 +1062,7 @@ Unix Notes:
will lead to unpredictable behavior and is strongly discouraged. Future
versions of libuv may simply reject them.
>
>lua
-- Create a new signal handler
local signal = uv.new_signal()
-- Define a handler function
@@ -1164,7 +1164,7 @@ uv.spawn({path}, {options}, {on_exit}) *uv.spawn()*
permissions to use the setuid or setgid specified, or not
having enough memory to allocate for the new process.
>
>lua
local stdin = uv.new_pipe()
local stdout = uv.new_pipe()
local stderr = uv.new_pipe()
@@ -1358,7 +1358,7 @@ uv.accept({stream}, {client_stream}) *uv.accept()*
Returns: `0` or `fail`
>
>lua
server:listen(128, function (err)
local client = uv.new_tcp()
server:accept(client)
@@ -1382,7 +1382,7 @@ uv.read_start({stream}, {callback}) *uv.read_start()*
Returns: `0` or `fail`
>
>lua
stream:read_start(function (err, chunk)
if err then
-- handle read error
@@ -1690,7 +1690,7 @@ uv.tcp_connect({tcp}, {host}, {port}, {callback}) *uv.tcp_connect()*
Returns: `uv_connect_t userdata` or `fail`
>
>lua
local client = uv.new_tcp()
client:connect("127.0.0.1", 8080, function (err)
-- check error and carry on.
@@ -1755,7 +1755,7 @@ uv.socketpair([{socktype}, [{protocol}, [{flags1}, [{flags2}]]]])
Returns: `table` or `fail`
- `[1, 2]` : `integer` (file descriptor)
>
>lua
-- Simple read/write with tcp
local fds = uv.socketpair(nil, nil, {nonblock=true}, {nonblock=true})
@@ -1780,7 +1780,7 @@ uv.socketpair([{socktype}, [{protocol}, [{flags1}, [{flags2}]]]])
Pipe handles provide an abstraction over local domain sockets on Unix and
named pipes on Windows.
>
>lua
local pipe = uv.new_pipe(false)
pipe:bind('/tmp/sock.test')
@@ -1959,7 +1959,7 @@ uv.pipe({read_flags}, {write_flags}) *uv.pipe()*
- `read` : `integer` (file descriptor)
- `write` : `integer` (file descriptor)
>
>lua
-- Simple read/write with pipe_open
local fds = uv.pipe({nonblock=true}, {nonblock=true})
@@ -1983,7 +1983,7 @@ uv.pipe({read_flags}, {write_flags}) *uv.pipe()*
TTY handles represent a stream for the console.
>
>lua
-- Simple echo program
local stdin = uv.new_tty(0, true)
local stdout = uv.new_tty(1, false)
@@ -2537,7 +2537,7 @@ FS call.
Synchronous and asynchronous versions of `readFile` (with naive error
handling) are implemented below as an example:
>
>lua
local function readFileSync(path)
local fd = assert(uv.fs_open(path, "r", 438))
local stat = assert(uv.fs_fstat(fd))
@@ -2550,7 +2550,7 @@ handling) are implemented below as an example:
print("synchronous read", data)
<
>
>lua
local function readFile(path, callback)
uv.fs_open(path, "r", 438, function(err, fd)
assert(not err, err)
@@ -3253,7 +3253,7 @@ Libuv provides a threadpool which can be used to run user code and get
notified in the loop thread. This threadpool is internally used to run all
file system operations, as well as `getaddrinfo` and `getnameinfo` requests.
>
>lua
local function work_callback(a, b)
return a + b
end

10
runtime/doc/news.txt
View File

@@ -39,6 +39,16 @@ NEW FEATURES *news-features*
The following new APIs or features were added.
• Treesitter syntax highlighting for `help` files now supports highlighted
code examples. To enable, create a `.config/nvim/ftplugin/help.lua` with
the contents >lua
vim.treesitter.start()
<
Note: Highlighted code examples are only available in the Nvim manual, not
in help files taken from Vim. The treesitter `help` parser is also work in
progress and not guaranteed to correctly highlight every help file in the
wild.
• |vim.secure.trust()|, |:trust| allows the user to manage files in trust
database.

14
runtime/doc/nvim.txt
View File

@@ -9,7 +9,7 @@ Nvim *nvim* *nvim-intro*
Nvim is based on Vim by Bram Moolenaar.
If you already use Vim see |nvim-from-vim| for a quickstart.
If you are new to Vim, try the 30-minute tutorial: >
If you are new to Vim, try the 30-minute tutorial: >vim
:Tutor<Enter>
@@ -22,12 +22,12 @@ Nvim is emphatically a fork of Vim, not a clone: compatibility with Vim
==============================================================================
Transitioning from Vim *nvim-from-vim*
1. To start the transition, create your |init.vim| (user config) file: >
1. To start the transition, create your |init.vim| (user config) file: >vim
:call mkdir(stdpath('config'), 'p')
:exe 'edit '.stdpath('config').'/init.vim'
2. Add these contents to the file: >
2. Add these contents to the file: >vim
set runtimepath^=~/.vim runtimepath+=~/.vim/after
let &packpath = &runtimepath
@@ -43,19 +43,19 @@ Your Vim configuration might not be entirely Nvim-compatible (see
because mouse support is always enabled if possible. If you use the same
|vimrc| for Vim and Nvim you could guard |'ttymouse'| in your configuration
like so:
>
>vim
if !has('nvim')
set ttymouse=xterm2
endif
And for Nvim-specific configuration, you can do this:
>
>vim
if has('nvim')
tnoremap <Esc> <C-\><C-n>
endif
For a more granular approach use |exists()|:
>
>vim
if exists(':tnoremap')
tnoremap <Esc> <C-\><C-n>
endif
@@ -67,7 +67,7 @@ for more information.
Because Nvim follows the XDG |base-directories| standard, configuration on
Windows is stored in ~/AppData instead of ~/.config. But you can still share
the same Nvim configuration on all of your machines, by creating
~/AppData/Local/nvim/init.vim containing just this line: >
~/AppData/Local/nvim/init.vim containing just this line: >vim
source ~/.config/nvim/init.vim
==============================================================================

78
runtime/doc/nvim_terminal_emulator.txt
View File

@@ -27,12 +27,12 @@ There are several ways to create a terminal buffer:
- Run the |:terminal| command.
- Call the |nvim_open_term()| or |termopen()| function.
- Edit a "term://" buffer. Examples: >
- Edit a "term://" buffer. Examples: >vim
:edit term://bash
:vsplit term://top
< Note: To open a "term://" buffer from an autocmd, the |autocmd-nested|
modifier is required. >
modifier is required. >vim
autocmd VimEnter * ++nested split term://sh
< (This is only mentioned for reference; use |:terminal| instead.)
@@ -62,13 +62,13 @@ Terminal-mode forces these local options:
Terminal-mode has its own |:tnoremap| namespace for mappings, this can be used
to automate any terminal interaction.
To map <Esc> to exit terminal-mode: >
To map <Esc> to exit terminal-mode: >vim
:tnoremap <Esc> <C-\><C-n>
To simulate |i_CTRL-R| in terminal-mode: >
To simulate |i_CTRL-R| in terminal-mode: >vim
:tnoremap <expr> <C-R> '<C-\><C-N>"'.nr2char(getchar()).'pi'
To use `ALT+{h,j,k,l}` to navigate windows from any mode: >
To use `ALT+{h,j,k,l}` to navigate windows from any mode: >vim
:tnoremap <A-h> <C-\><C-N><C-w>h
:tnoremap <A-j> <C-\><C-N><C-w>j
:tnoremap <A-k> <C-\><C-N><C-w>k
@@ -109,7 +109,7 @@ global configuration.
- 'list' is disabled
- 'wrap' is disabled
You can change the defaults with a TermOpen autocommand: >
You can change the defaults with a TermOpen autocommand: >vim
au TermOpen * setlocal list
TERMINAL COLORS ~
@@ -117,7 +117,7 @@ TERMINAL COLORS ~
The `{g,b}:terminal_color_x` variables control the terminal color palette,
where `x` is the color index between 0 and 255 inclusive. The variables are
read during |TermOpen|. The value must be a color name or hexadecimal string.
Example: >
Example: >vim
let g:terminal_color_4 = '#ff0000'
let g:terminal_color_5 = 'green'
Only works for RGB UIs (see 'termguicolors'); for 256-color terminals the
@@ -131,7 +131,7 @@ Status Variables *terminal-status*
Terminal buffers maintain some buffer-local variables and options. The values
are initialized before TermOpen, so you can use them in a local 'statusline'.
Example: >
Example: >vim
:autocmd TermOpen * setlocal statusline=%{b:term_title}
- *b:term_title* Terminal title (user-writable), typically displayed in the
@@ -141,10 +141,10 @@ Example: >
input to the terminal.
- The |TermClose| event gives the terminal job exit code in the |v:event|
"status" field. For example, this autocmd closes terminal buffers if the job
exited without error: >
exited without error: >vim
autocmd TermClose * if !v:event.status | exe 'bdelete! '..expand('<abuf>') | endif
Use |jobwait()| to check if the terminal job has finished: >
Use |jobwait()| to check if the terminal job has finished: >vim
let running = jobwait([&channel], 0)[0] == -1
==============================================================================
@@ -156,11 +156,11 @@ Vim this also works remotely over an ssh connection.
Starting ~
*termdebug-starting*
Load the plugin with this command: >
Load the plugin with this command: >vim
packadd termdebug
< *:Termdebug*
To start debugging use `:Termdebug` or `:TermdebugCommand` followed by the
command name, for example: >
command name, for example: >vim
:Termdebug vim
This opens two windows:
@@ -189,16 +189,16 @@ Only one debugger can be active at a time.
*:TermdebugCommand*
If you want to give specific commands to the command being debugged, you can
use the `:TermdebugCommand` command followed by the command name and
additional parameters. >
additional parameters. >vim
:TermdebugCommand vim --clean -c ':set nu'
Both the `:Termdebug` and `:TermdebugCommand` support an optional "!" bang
argument to start the command right away, without pausing at the gdb window
(and cursor will be in the debugged window). For example: >
(and cursor will be in the debugged window). For example: >vim
:TermdebugCommand! vim --clean
To attach gdb to an already running executable or use a core file, pass extra
arguments. E.g.: >
arguments. E.g.: >vim
:Termdebug vim core
:Termdebug vim 98343
@@ -212,7 +212,7 @@ Start in the Vim "src" directory and build Vim: >
% make
Start Vim: >
% ./vim
Load the termdebug plugin and start debugging Vim: >
Load the termdebug plugin and start debugging Vim: >vim
:packadd termdebug
:Termdebug vim
You should now have three windows:
@@ -223,7 +223,7 @@ You should now have three windows:
Put focus on the gdb window and type: >
break ex_help
run
Vim will start running in the program window. Put focus there and type: >
Vim will start running in the program window. Put focus there and type: >vim
:help gui
Gdb will run into the ex_help breakpoint. The source window now shows the
ex_cmds.c file. A red "1 " marker will appear in the signcolumn where the
@@ -329,7 +329,7 @@ Other commands ~
Events ~
*termdebug-events*
Four autocommands can be used: >
Four autocommands can be used: >vim
au User TermdebugStartPre echomsg 'debugging starting'
au User TermdebugStartPost echomsg 'debugging started'
au User TermdebugStopPre echomsg 'debugging stopping'
@@ -360,7 +360,7 @@ Customizing ~
In the past several global variables were used for configuration. These are
deprecated and using the g:termdebug_config dictionary is preferred. When
g:termdebug_config exists the other global variables will NOT be used.
The recommended way is to start with an empty dictionary: >
The recommended way is to start with an empty dictionary: >vim
let g:termdebug_config = {}
Then you can add entries to the dictionary as mentioned below. The
@@ -380,23 +380,23 @@ This works slightly differently:
- A separate :terminal window will be opened to run the debugged program in.
*termdebug_use_prompt*
Prompt mode can be used with: >
Prompt mode can be used with: >vim
let g:termdebug_config['use_prompt'] = 1
If there is no g:termdebug_config you can use: >
If there is no g:termdebug_config you can use: >vim
let g:termdebug_use_prompt = 1
<
*termdebug_map_K*
The K key is normally mapped to :Evaluate. If you do not want this use: >
The K key is normally mapped to :Evaluate. If you do not want this use: >vim
let g:termdebug_config['map_K'] = 0
If there is no g:termdebug_config you can use: >
If there is no g:termdebug_config you can use: >vim
let g:termdebug_map_K = 0
<
*termdebug_disasm_window*
If you want the Asm window shown by default, set the flag to 1.
the "disasm_window_height" entry can be used to set the window height: >
the "disasm_window_height" entry can be used to set the window height: >vim
let g:termdebug_config['disasm_window'] = 1
let g:termdebug_config['disasm_window_height'] = 15
If there is no g:termdebug_config you can use: >
If there is no g:termdebug_config you can use: >vim
let g:termdebug_disasm_window = 15
Any value greater than 1 will set the Asm window height to that value.
@@ -418,34 +418,34 @@ GDB command ~
*g:termdebugger*
To change the name of the gdb command, set "debugger" entry in
g:termdebug_config or the "g:termdebugger" variable before invoking
`:Termdebug`: >
`:Termdebug`: >vim
let g:termdebug_config['command'] = "mygdb"
If there is no g:termdebug_config you can use: >
If there is no g:termdebug_config you can use: >vim
let g:termdebugger = "mygdb"
If the command needs an argument use a List: >
If the command needs an argument use a List: >vim
let g:termdebug_config['command'] = ['rr', 'replay', '--']
If there is no g:termdebug_config you can use: >
If there is no g:termdebug_config you can use: >vim
let g:termdebugger = ['rr', 'replay', '--']
To not use neovim floating windows for previewing variable evaluation, set the
`g:termdebug_useFloatingHover` variable like this: >
`g:termdebug_useFloatingHover` variable like this: >vim
let g:termdebug_useFloatingHover = 0
If you are a mouse person, you can also define a mapping using your right
click to one of the terminal command like evaluate the variable under the
cursor: >
cursor: >vim
nnoremap <RightMouse> :Evaluate<CR>
or set/unset a breakpoint: >
or set/unset a breakpoint: >vim
nnoremap <RightMouse> :Break<CR>
Several arguments will be added to make gdb work well for the debugger.
If you want to modify them, add a function to filter the argument list: >
If you want to modify them, add a function to filter the argument list: >vim
let g:termdebug_config['command_filter'] = MyDebugFilter
If you do not want the arguments to be added, but you do need to set the
"pty", use a function to add the necessary arguments: >
"pty", use a function to add the necessary arguments: >vim
let g:termdebug_config['command_add_args'] = MyAddArguments
The function will be called with the list of arguments so far, and a second
argument that is the name of the pty.
@@ -475,7 +475,7 @@ When 'background' is "dark":
Shortcuts ~
*termdebug_shortcuts*
You can define your own shortcuts (mappings) to control gdb, that can work in
any window, using the TermDebugSendCommand() function. Example: >
any window, using the TermDebugSendCommand() function. Example: >vim
map ,w :call TermDebugSendCommand('where')<CR>
The argument is the gdb command.
@@ -487,18 +487,18 @@ these entries to the popup menu:
Set breakpoint `:Break`
Clear breakpoint `:Clear`
Evaluate `:Evaluate`
If you don't want this then disable it with: >
If you don't want this then disable it with: >vim
let g:termdebug_config['popup'] = 0
If there is no g:termdebug_config you can use: >
If there is no g:termdebug_config you can use: >vim
let g:termdebug_popup = 0
Vim window width ~
*termdebug_wide*
To change the width of the Vim window when debugging starts and use a vertical
split: >
split: >vim
let g:termdebug_config['wide'] = 163
If there is no g:termdebug_config you can use: >
If there is no g:termdebug_config you can use: >vim
let g:termdebug_wide = 163
This will set 'columns' to 163 when `:Termdebug` is used. The value is

43
runtime/doc/provider.txt
View File

@@ -36,7 +36,7 @@ itself).
For Python 3 plugins:
1. Make sure Python 3.4+ is available in your $PATH.
2. Install the module (try "python" if "python3" is missing): >
2. Install the module (try "python" if "python3" is missing): >bash
python3 -m pip install --user --upgrade pynvim
The pip `--upgrade` flag ensures that you get the latest version even if
@@ -46,7 +46,7 @@ See also |python-virtualenv|.
Note: The old "neovim" module was renamed to "pynvim".
https://github.com/neovim/neovim/wiki/Following-HEAD#20181118
If you run into problems, uninstall _both_ then install "pynvim" again: >
If you run into problems, uninstall _both_ then install "pynvim" again: >bash
python -m pip uninstall neovim pynvim
python -m pip install --user --upgrade pynvim
@@ -55,11 +55,11 @@ PYTHON PROVIDER CONFIGURATION ~
*g:python3_host_prog*
Command to start Python 3 (executable, not directory). Setting this makes
startup faster. Useful for working with virtualenvs. Must be set before any
check for has("python3"). >
check for has("python3"). >vim
let g:python3_host_prog = '/path/to/python3'
<
*g:loaded_python3_provider*
To disable Python 3 support: >
To disable Python 3 support: >vim
let g:loaded_python3_provider = 0
@@ -70,13 +70,13 @@ virtualenv for Neovim and hard-code the interpreter path via
|g:python3_host_prog| so that the "pynvim" package is not required
for each virtualenv.
Example using pyenv: >
Example using pyenv: >bash
pyenv install 3.4.4
pyenv virtualenv 3.4.4 py3nvim
pyenv activate py3nvim
python3 -m pip install pynvim
pyenv which python # Note the path
The last command reports the interpreter path, add it to your init.vim: >
The last command reports the interpreter path, add it to your init.vim: >vim
let g:python3_host_prog = '/path/to/py3nvim/bin/python'
See also: https://github.com/zchee/deoplete-jedi/wiki/Setting-up-Python-for-Neovim
@@ -90,7 +90,7 @@ Nvim supports Ruby |remote-plugin|s and the Vim legacy |ruby-vim| interface
RUBY QUICKSTART ~
To use Ruby plugins with Nvim, install the latest "neovim" RubyGem: >
To use Ruby plugins with Nvim, install the latest "neovim" RubyGem: >bash
gem install neovim
Run |:checkhealth| to see if your system is up-to-date.
@@ -98,7 +98,7 @@ Run |:checkhealth| to see if your system is up-to-date.
RUBY PROVIDER CONFIGURATION ~
*g:loaded_ruby_provider*
To disable Ruby support: >
To disable Ruby support: >vim
let g:loaded_ruby_provider = 0
<
*g:ruby_host_prog*
@@ -106,10 +106,10 @@ Command to start the Ruby host. By default this is "neovim-ruby-host". With
project-local Ruby versions (via tools like RVM or rbenv) setting this can
avoid the need to install the "neovim" gem in every project.
To use an absolute path (e.g. to an rbenv installation): >
To use an absolute path (e.g. to an rbenv installation): >vim
let g:ruby_host_prog = '~/.rbenv/versions/2.4.1/bin/neovim-ruby-host'
To use the RVM "system" Ruby installation: >
To use the RVM "system" Ruby installation: >vim
let g:ruby_host_prog = 'rvm system do neovim-ruby-host'
==============================================================================
@@ -125,7 +125,7 @@ Note: Only perl versions from 5.22 onward are supported.
PERL QUICKSTART~
To use perl remote-plugins with Nvim, install the "Neovim::Ext" cpan package: >
To use perl remote-plugins with Nvim, install the "Neovim::Ext" cpan package: >bash
cpanm -n Neovim::Ext
Run |:checkhealth| to see if your system is up-to-date.
@@ -133,12 +133,12 @@ Run |:checkhealth| to see if your system is up-to-date.
PERL PROVIDER CONFIGURATION~
*g:loaded_perl_provider*
To disable Perl support: >
To disable Perl support: >vim
:let g:loaded_perl_provider = 0
<
*g:perl_host_prog*
Command to start the Perl executable. Must be set before any
check for has("perl"). >
check for has("perl"). >vim
let g:perl_host_prog = '/path/to/perl'
<
==============================================================================
@@ -150,7 +150,7 @@ https://github.com/neovim/node-client/
NODEJS QUICKSTART~
To use javascript remote-plugins with Nvim, install the "neovim" npm package: >
To use javascript remote-plugins with Nvim, install the "neovim" npm package: >bash
npm install -g neovim
Run |:checkhealth| to see if your system is up-to-date.
@@ -158,14 +158,14 @@ Run |:checkhealth| to see if your system is up-to-date.
NODEJS PROVIDER CONFIGURATION~
*g:loaded_node_provider*
To disable Node.js support: >
To disable Node.js support: >vim
:let g:loaded_node_provider = 0
<
*g:node_host_prog*
Command to start the Node.js host. Setting this makes startup faster.
By default, Nvim searches for "neovim-node-host" using "npm root -g", which
can be slow. To avoid this, set g:node_host_prog to the host path: >
can be slow. To avoid this, set g:node_host_prog to the host path: >vim
let g:node_host_prog = '/usr/local/bin/neovim-node-host'
<
==============================================================================
@@ -176,7 +176,7 @@ a |provider| which transparently uses shell commands to communicate with the
system clipboard or any other clipboard "backend".
To ALWAYS use the clipboard for ALL operations (instead of interacting with
the '+' and/or '*' registers explicitly): >
the '+' and/or '*' registers explicitly): >vim
set clipboard+=unnamedplus
See 'clipboard' for details and options.
@@ -199,7 +199,7 @@ registers. Nvim looks for these clipboard tools, in order of priority:
*g:clipboard*
To configure a custom clipboard tool, set g:clipboard to a dictionary.
For example this configuration integrates the tmux clipboard: >
For example this configuration integrates the tmux clipboard: >vim
let g:clipboard = {
\ 'name': 'myClipboard',
@@ -219,7 +219,8 @@ the selection until the copy command process dies. When pasting, if the copy
process has not died the cached selection is applied.
g:clipboard can also use functions (see |lambda|) instead of strings.
For example this configuration uses the g:foo variable as a fake clipboard: >
For example this configuration uses the g:foo variable as a fake clipboard:
>vim
let g:clipboard = {
\ 'name': 'myClipboard',
@@ -239,7 +240,7 @@ a list of lines and `regtype` is a register type conforming to |setreg()|.
*clipboard-wsl*
For Windows WSL, try this g:clipboard definition:
>
>vim
let g:clipboard = {
\ 'name': 'WslClipboard',
\ 'copy': {
@@ -283,7 +284,7 @@ many commands. Use the |cmdline-window| if you really want to paste multiple
lines to the cmdline.
You can implement a custom paste handler by redefining |vim.paste()|.
Example: >
Example: >lua
vim.paste = (function(lines, phase)
vim.api.nvim_put(lines, 'c', true, true)

18
runtime/doc/term.txt
View File

@@ -76,7 +76,7 @@ supplying an external one with entries for the terminal type.
Settings depending on terminal *term-dependent-settings*
If you want to set terminal-dependent options or mappings, you can do this in
your init.vim. Example: >
your init.vim. Example: >vim
if $TERM =~ '^\(rxvt\|screen\|interix\|putty\)\(-.*\)\?$'
set notermguicolors
@@ -222,9 +222,9 @@ are not in terminfo you must add them by setting "terminal-overrides" in
~/.tmux.conf .
See the tmux(1) manual page for the details of how and what to do in the tmux
configuration file. It will look something like: >
configuration file. It will look something like: >bash
set -ga terminal-overrides '*:Ss=\E[%p1%d q:Se=\E[ q'
<or (alas!) for Konsole 18.07.70 or older, something more complex like: >
<or (alas!) for Konsole 18.07.70 or older, something more complex like: >bash
set -ga terminal-overrides 'xterm*:\E]50;CursorShape=%?%p1%{3}%<%t%{0}%e%{1}%;%d\007'
<
==============================================================================
@@ -262,7 +262,7 @@ See the "Options" chapter |options|.
If you are using a color terminal that is slow when displaying lines beyond
the end of a buffer, this is because Nvim is drawing the whitespace twice, in
two sets of colours and attributes. To prevent this, use this command: >
two sets of colours and attributes. To prevent this, use this command: >vim
hi NonText cterm=NONE ctermfg=NONE
This draws the spaces with the default colours and attributes, which allows the
second pass of drawing to be optimized away. Note: Although in theory the
@@ -372,7 +372,7 @@ that has a match selects until that match (like using "v%"). If the match is
an #if/#else/#endif block, the selection becomes linewise.
For MS-Windows and xterm the time for double clicking can be set with the
'mousetime' option. For the other systems this time is defined outside of Vim.
An example, for using a double click to jump to the tag under the cursor: >
An example, for using a double click to jump to the tag under the cursor: >vim
:map <2-LeftMouse> :exe "tag " .. expand("<cword>")<CR>
Dragging the mouse with a double click (button-down, button-up, button-down
@@ -410,23 +410,23 @@ The X1 and X2 buttons refer to the extra buttons found on some mice. The
'Microsoft Explorer' mouse has these buttons available to the right thumb.
Currently X1 and X2 only work on Win32 and X11 environments.
Examples: >
Examples: >vim
:noremap <MiddleMouse> <LeftMouse><MiddleMouse>
Paste at the position of the middle mouse button click (otherwise the paste
would be done at the cursor position). >
would be done at the cursor position). >vim
:noremap <LeftRelease> <LeftRelease>y
Immediately yank the selection, when using Visual mode.
Note the use of ":noremap" instead of "map" to avoid a recursive mapping.
>
>vim
:map <X1Mouse> <C-O>
:map <X2Mouse> <C-I>
Map the X1 and X2 buttons to go forwards and backwards in the jump list, see
|CTRL-O| and |CTRL-I|.
*mouse-swap-buttons*
To swap the meaning of the left and right mouse buttons: >
To swap the meaning of the left and right mouse buttons: >vim
:noremap <LeftMouse> <RightMouse>
:noremap <LeftDrag> <RightDrag>
:noremap <LeftRelease> <RightRelease>

16
runtime/doc/treesitter.txt
View File

@@ -24,7 +24,7 @@ via a plugin like https://github.com/nvim-treesitter/nvim-treesitter.
Parsers are searched for as `parser/{lang}.*` in any 'runtimepath' directory.
If multiple parsers for the same language are found, the first one is used.
(This typically implies the priority "user config > plugins > bundled".
A parser can also be loaded manually using a full path: >
A parser can also be loaded manually using a full path: >lua
vim.treesitter.require_language("python", "/path/to/python.so")
<
@@ -37,7 +37,7 @@ file), multiple parsers may be needed to parse the full buffer. These are
combined in a |LanguageTree| object.
To create a LanguageTree (parser object) for a buffer and a given language,
use >
use >lua
tsparser = vim.treesitter.get_parser(bufnr, lang)
<
@@ -46,7 +46,7 @@ Currently, the parser will be retained for the lifetime of a buffer but this
is subject to change. A plugin should keep a reference to the parser object as
long as 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
tstree = tsparser:parse()
<
@@ -366,10 +366,10 @@ queries that make them available.
As an additional rule, capture highlights can always be specialized by
language, by appending the language name after an additional dot. For
instance, to highlight comments differently per language: >
instance, to highlight comments differently per language: >vim
hi @comment.c guifg=Blue
hi @comment.lua @guifg=DarkBlue
hi @comment.lua guifg=DarkBlue
hi link @comment.doc.java String
<
The following captures are linked by default to standard |group-name|s:
@@ -605,7 +605,7 @@ start({bufnr}, {lang}) *start()*
required for some plugins. In this case, add `vim.bo.syntax = 'on'` after
the call to `start`.
Example: >
Example: >lua
vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex',
callback = function(args)
@@ -770,7 +770,7 @@ Query:iter_captures({self}, {node}, {source}, {start}, {stop})
The iterator returns three values: a numeric id identifying the capture,
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: >lua
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
@@ -802,7 +802,7 @@ Query:iter_matches({self}, {node}, {source}, {start}, {stop})
(1-based) index of the pattern in the query, a table mapping capture
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
and e.g. `pairs()` method should be used over `ipairs` . Here is an example iterating over all captures in every match: >
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

6
runtime/doc/ui.txt
View File

@@ -119,7 +119,7 @@ for forward-compatibility. |api-contract|
UI startup *ui-startup*
UI embedders (clients that start Nvim with |--embed| and later call
|nvim_ui_attach()|) must start Nvim without |--headless|: >
|nvim_ui_attach()|) must start Nvim without |--headless|: >bash
nvim --embed
Nvim will pause before loading startup files and reading buffers, so the UI
has a chance to invoke requests and do early initialization. Startup will
@@ -138,7 +138,7 @@ procedure:
to set |g:| variables visible to init.vim
3. If the UI wants to do additional setup after user config is loaded,
register a VimEnter autocmd: >
register a VimEnter autocmd: >vim
nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')")
4. Now invoke |nvim_ui_attach()|. The UI must handle user input by now:
@@ -722,7 +722,7 @@ For command-line 'wildmenu' UI events, activate |ui-popupmenu|.
["cmdline_block_show", lines] ~
Show a block of context to the current command line. For example if
the user defines a |:function| interactively: >
the user defines a |:function| interactively: >vim
:function Foo()
: echo "foo"
:

18
runtime/doc/vim_diff.txt
View File

@@ -73,7 +73,7 @@ centralized reference of the differences.
- 'wildoptions' defaults to "pum,tagfile"
- |man.lua| plugin is enabled, so |:Man| is available by default.
- |matchit| plugin is enabled. To disable it in your config: >
- |matchit| plugin is enabled. To disable it in your config: >vim
:let loaded_matchit = 1
- |g:vimsyn_embed| defaults to "l" to enable Lua highlighting
@@ -88,11 +88,11 @@ typing ":".
If you don't like this you can disable the mouse in your |config| using any of
the following:
- Disable mouse completely by unsetting the 'mouse' option: >
- Disable mouse completely by unsetting the 'mouse' option: >vim
set mouse=
- Pressing <RightMouse> extends selection instead of showing popup-menu: >
- Pressing <RightMouse> extends selection instead of showing popup-menu: >vim
set mousemodel=extend
- Pressing <A-LeftMouse> releases mouse until the cursor moves: >
- Pressing <A-LeftMouse> releases mouse until the cursor moves: >vim
nnoremap <A-LeftMouse> <Cmd>
\ set mouse=<Bar>
\ echo 'mouse OFF until next cursor-move'<Bar>
@@ -104,7 +104,7 @@ Default Mappings ~
*default-mappings*
Nvim creates the following default mappings at |startup|. You can disable any
of these in your config by simply removing the mapping, e.g. ":unmap Y".
>
>vim
nnoremap Y y$
nnoremap <C-L> <Cmd>nohlsearch<Bar>diffupdate<Bar>normal! <C-L><CR>
inoremap <C-U> <C-G>u<C-U>
@@ -302,7 +302,7 @@ are always available and may be used simultaneously. See |provider-python|.
structures.
2. |string()| fails immediately on nested containers, not when recursion limit
was exceeded.
2. When |:echo| encounters duplicate containers like >
2. When |:echo| encounters duplicate containers like >vim
let l = []
echo [l, l]
@@ -462,7 +462,7 @@ TUI:
<
*'term'* *E529* *E530* *E531*
'term' reflects the terminal type derived from |$TERM| and other environment
checks. For debugging only; not reliable during startup. >
checks. For debugging only; not reliable during startup. >vim
:echo &term
< "builtin_x" means one of the |builtin-terms| was chosen, because the expected
terminfo file was not found on the system.
@@ -568,7 +568,7 @@ Events:
Highlight groups:
*hl-StatusLineTerm* *hl-StatusLineTermNC* are unnecessary because Nvim
supports 'winhighlight' window-local highlights.
For example, to mimic Vim's StatusLineTerm: >
For example, to mimic Vim's StatusLineTerm: >vim
hi StatusLineTerm ctermfg=black ctermbg=green
hi StatusLineTermNC ctermfg=green
autocmd TermOpen,WinEnter * if &buftype=='terminal'
@@ -604,7 +604,7 @@ Options:
*'imactivatekey'* *'imak'*
*'imstatusfunc'* *'imsf'*
*'insertmode'* *'im'* Use the following script to emulate 'insertmode':
>
>vim
autocmd BufWinEnter * startinsert
inoremap <Esc> <C-X><C-Z><C-]>
inoremap <C-C> <C-X><C-Z>

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

@@ -123,7 +123,7 @@ do
--- (such as the |TUI|) pastes text into the editor.
---
--- Example: To remove ANSI color codes when pasting:
--- <pre>
--- <pre>lua
--- vim.paste = (function(overridden)
--- return function(lines, phase)
--- for i,line in ipairs(lines) do
@@ -280,7 +280,7 @@ end
--- command.
---
--- Example:
--- <pre>
--- <pre>lua
--- vim.cmd('echo 42')
--- vim.cmd([[
--- augroup My_group
@@ -746,7 +746,7 @@ end
---Prints given arguments in human-readable format.
---Example:
---<pre>
---<pre>lua
--- -- Print highlight group Normal and store it's contents in a variable.
--- local hl_normal = vim.pretty_print(vim.api.nvim_get_hl_by_name("Normal", true))
---</pre>

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

@@ -579,12 +579,12 @@ end
--- followed by namespace configuration, and finally global configuration.
---
--- For example, if a user enables virtual text globally with
--- <pre>
--- <pre>lua
--- vim.diagnostic.config({ virtual_text = true })
--- </pre>
---
--- and a diagnostic producer sets diagnostics with
--- <pre>
--- <pre>lua
--- vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false })
--- </pre>
---
@@ -621,13 +621,13 @@ end
--- * format: (function) A function that takes a diagnostic as input and
--- returns a string. The return value is the text used to display
--- the diagnostic. Example:
--- <pre>
--- function(diagnostic)
--- if diagnostic.severity == vim.diagnostic.severity.ERROR then
--- return string.format("E: %s", diagnostic.message)
--- <pre>lua
--- function(diagnostic)
--- if diagnostic.severity == vim.diagnostic.severity.ERROR then
--- return string.format("E: %s", diagnostic.message)
--- end
--- return diagnostic.message
--- end
--- return diagnostic.message
--- end
--- </pre>
--- - signs: (default true) Use signs for diagnostics. Options:
--- * severity: Only show signs for diagnostics matching the given severity
@@ -1577,11 +1577,11 @@ end
---
--- This can be parsed into a diagnostic |diagnostic-structure|
--- with:
--- <pre>
--- local s = "WARNING filename:27:3: Variable 'foo' does not exist"
--- local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
--- local groups = { "severity", "lnum", "col", "message" }
--- vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
--- <pre>lua
--- local s = "WARNING filename:27:3: Variable 'foo' does not exist"
--- local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
--- local groups = { "severity", "lnum", "col", "message" }
--- vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
--- </pre>
---
---@param str string String to parse diagnostics from.

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

@@ -2308,7 +2308,7 @@ end
--- See $VIMRUNTIME/lua/vim/filetype.lua for more examples.
---
--- Example:
--- <pre>
--- <pre>lua
--- vim.filetype.add({
--- extension = {
--- foo = 'fooscript',
@@ -2344,7 +2344,7 @@ end
--- </pre>
---
--- To add a fallback match on contents, use
--- <pre>
--- <pre>lua
--- vim.filetype.add {
--- pattern = {
--- ['.*'] = {
@@ -2456,7 +2456,7 @@ end
--- Each of the three options is specified using a key to the single argument of this function.
--- Example:
---
--- <pre>
--- <pre>lua
--- -- Using a buffer number
--- vim.filetype.match({ buf = 42 })
---

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

@@ -5,7 +5,7 @@ local iswin = vim.loop.os_uname().sysname == 'Windows_NT'
--- Iterate over all the parents of the given file or directory.
---
--- Example:
--- <pre>
--- <pre>lua
--- local root_dir
--- for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do
--- if vim.fn.isdirectory(dir .. "/.git") == 1 then
@@ -119,8 +119,7 @@ end
--- - limit (number, default 1): Stop the search after
--- finding this many matches. Use `math.huge` to
--- place no limit on the number of matches.
---
---@return (table) The normalized paths |vim.fs.normalize()| of all matching files or directories
---@return (table) Normalized paths |vim.fs.normalize()| of all matching files or directories
function M.find(names, opts)
opts = opts or {}
vim.validate({
@@ -235,15 +234,15 @@ end
--- variables are also expanded.
---
--- Examples:
--- <pre>
--- <pre>lua
--- vim.fs.normalize('C:\\Users\\jdoe')
--- => 'C:/Users/jdoe'
--- --> 'C:/Users/jdoe'
---
--- vim.fs.normalize('~/src/neovim')
--- => '/home/jdoe/src/neovim'
--- --> '/home/jdoe/src/neovim'
---
--- vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim')
--- => '/Users/jdoe/.config/nvim/init.vim'
--- --> '/Users/jdoe/.config/nvim/init.vim'
--- </pre>
---
---@param path (string) Path to normalize

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

@@ -2,7 +2,7 @@ local keymap = {}
--- Add a new |mapping|.
--- Examples:
--- <pre>
--- <pre>lua
--- -- Can add mapping to Lua functions
--- vim.keymap.set('n', 'lhs', function() print("real lua function") end)
---
@@ -21,13 +21,13 @@ local keymap = {}
--- </pre>
---
--- Note that in a mapping like:
--- <pre>
--- <pre>lua
--- vim.keymap.set('n', 'asdf', require('jkl').my_fun)
--- </pre>
---
--- the ``require('jkl')`` gets evaluated during this call in order to access the function.
--- If you want to avoid this cost at startup you can wrap it in a function, for example:
--- <pre>
--- <pre>lua
--- vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
--- </pre>
---
@@ -93,7 +93,7 @@ end
--- Remove an existing mapping.
--- Examples:
--- <pre>
--- <pre>lua
--- vim.keymap.del('n', 'lhs')
---
--- vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buffer = 5 })

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

@@ -813,8 +813,7 @@ end
--- Attaches the current buffer to the client.
---
--- Example:
---
--- <pre>
--- <pre>lua
--- vim.lsp.start({
--- name = 'my-server-name',
--- cmd = {'name-of-language-server-executable'},
@@ -1754,8 +1753,7 @@ end
---
--- You can also use the `stop()` function on a |vim.lsp.client| object.
--- To stop all clients:
---
--- <pre>
--- <pre>lua
--- vim.lsp.stop_client(vim.lsp.get_active_clients())
--- </pre>
---
@@ -2239,7 +2237,7 @@ end
---@param fn function Function to run on each client attached to buffer
--- {bufnr}. The function takes the client, client ID, and
--- buffer number as arguments. Example:
--- <pre>
--- <pre>lua
--- vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr)
--- print(vim.inspect(client))
--- end)

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

@@ -162,11 +162,11 @@ end
--- Predicate used to filter clients. Receives a client as argument and must return a
--- boolean. Clients matching the predicate are included. Example:
---
--- <pre>
--- -- Never request typescript-language-server for formatting
--- vim.lsp.buf.format {
--- filter = function(client) return client.name ~= "tsserver" end
--- }
--- <pre>lua
--- -- Never request typescript-language-server for formatting
--- vim.lsp.buf.format {
--- filter = function(client) return client.name ~= "tsserver" end
--- }
--- </pre>
---
--- - async boolean|nil
@@ -555,11 +555,10 @@ end
--- 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
--- by events such as `CursorHold`, e.g.:
---
--- <pre>
--- autocmd CursorHold <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()
--- <pre>vim
--- autocmd CursorHold <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()
--- </pre>
---
--- Note: Usage of |vim.lsp.buf.document_highlight()| requires the following highlight groups

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

@@ -241,7 +241,8 @@ end
---
--- It is recommended to trigger this using an autocmd or via keymap.
---
--- <pre>
--- Example:
--- <pre>vim
--- autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
--- </pre>
---

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

@@ -150,7 +150,7 @@ end
---
--- See |vim.diagnostic.config()| for configuration options. Handler-specific
--- configuration can be set using |vim.lsp.with()|:
--- <pre>
--- <pre>lua
--- vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
--- vim.lsp.diagnostic.on_publish_diagnostics, {
--- -- Enable underline, use default values

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

@@ -313,15 +313,15 @@ M['textDocument/completion'] = function(_, result, _, _)
end
--- |lsp-handler| for the method "textDocument/hover"
--- <pre>
--- vim.lsp.handlers["textDocument/hover"] = vim.lsp.with(
--- vim.lsp.handlers.hover, {
--- -- Use a sharp border with `FloatBorder` highlights
--- border = "single",
--- -- add the title in hover float window
--- title = "hover"
--- }
--- )
--- <pre>lua
--- vim.lsp.handlers["textDocument/hover"] = vim.lsp.with(
--- vim.lsp.handlers.hover, {
--- -- Use a sharp border with `FloatBorder` highlights
--- border = "single",
--- -- add the title in hover float window
--- title = "hover"
--- }
--- )
--- </pre>
---@param config table Configuration table.
--- - border: (default=nil)
@@ -399,13 +399,13 @@ M['textDocument/implementation'] = location_handler
--- |lsp-handler| for the method "textDocument/signatureHelp".
--- The active parameter is highlighted with |hl-LspSignatureActiveParameter|.
--- <pre>
--- vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
--- vim.lsp.handlers.signature_help, {
--- -- Use a sharp border with `FloatBorder` highlights
--- border = "single"
--- }
--- )
--- <pre>lua
--- vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
--- vim.lsp.handlers.signature_help, {
--- -- Use a sharp border with `FloatBorder` highlights
--- border = "single"
--- }
--- )
--- </pre>
---@param config table Configuration table.
--- - border: (default=nil)

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

@@ -102,11 +102,11 @@ end
--- Splits a string at each instance of a separator.
---
--- Examples:
--- <pre>
--- split(":aa::b:", ":") => {'','aa','','b',''}
--- split("axaby", "ab?") => {'','x','y'}
--- split("x*yz*o", "*", {plain=true}) => {'x','yz','o'}
--- split("|x|y|z|", "|", {trimempty=true}) => {'x', 'y', 'z'}
--- <pre>lua
--- split(":aa::b:", ":") --> {'','aa','','b',''}
--- split("axaby", "ab?") --> {'','x','y'}
--- split("x*yz*o", "*", {plain=true}) --> {'x','yz','o'}
--- split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'}
--- </pre>
---
---@see |vim.gsplit()|
@@ -383,7 +383,7 @@ end
--- Return `nil` if the key does not exist.
---
--- Examples:
--- <pre>
--- <pre>lua
--- vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true
--- vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil
--- </pre>
@@ -495,9 +495,9 @@ end
--- Counts the number of non-nil values in table `t`.
---
--- <pre>
--- vim.tbl_count({ a=1, b=2 }) => 2
--- vim.tbl_count({ 1, 2 }) => 2
--- <pre>lua
--- vim.tbl_count({ a=1, b=2 }) --> 2
--- vim.tbl_count({ 1, 2 }) --> 2
--- </pre>
---
---@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua
@@ -571,7 +571,7 @@ end
--- Validates a parameter specification (types and values).
---
--- Usage example:
--- <pre>
--- <pre>lua
--- function user.new(name, age, hobbies)
--- vim.validate{
--- name={name, 'string'},
@@ -583,24 +583,24 @@ end
--- </pre>
---
--- Examples with explicit argument values (can be run directly):
--- <pre>
--- <pre>lua
--- vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
--- => NOP (success)
--- --> NOP (success)
---
--- vim.validate{arg1={1, 'table'}}
--- => error('arg1: expected table, got number')
--- --> error('arg1: expected table, got number')
---
--- vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}}
--- => error('arg1: expected even number, got 3')
--- --> error('arg1: expected even number, got 3')
--- </pre>
---
--- If multiple types are valid they can be given as a list.
--- <pre>
--- <pre>lua
--- vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}}
--- => NOP (success)
--- --> NOP (success)
---
--- vim.validate{arg1={1, {'string', table'}}}
--- => error('arg1: expected string|table, got number')
--- --> error('arg1: expected string|table, got number')
---
--- </pre>
---
@@ -735,7 +735,7 @@ end
--- If {create} is `nil`, this will create a defaulttable whose constructor function is
--- this function, effectively allowing to create nested tables on the fly:
---
--- <pre>
--- <pre>lua
--- local a = vim.defaulttable()
--- a.b.c = 1
--- </pre>

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

@@ -313,7 +313,7 @@ end
--- In this case, add ``vim.bo.syntax = 'on'`` after the call to `start`.
---
--- Example:
--- <pre>
--- <pre>lua
--- vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex',
--- callback = function(args)
--- vim.treesitter.start(args.buf, 'latex')

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

@@ -549,7 +549,7 @@ end
--- The iterator returns three values: a numeric id identifying the capture,
--- the captured node, and metadata from any directives processing the match.
--- The following example shows how to get captures by name:
--- <pre>
--- <pre>lua
--- 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
--- -- typically useful info about the node:
@@ -603,7 +603,7 @@ end
--- 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:
--- <pre>
--- <pre>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]

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

@@ -21,7 +21,7 @@ local M = {}
---
---
--- Example:
--- <pre>
--- <pre>lua
--- vim.ui.select({ 'tabs', 'spaces' }, {
--- prompt = 'Select tabs or spaces:',
--- format_item = function(item)
@@ -78,7 +78,7 @@ end
--- `nil` if the user aborted the dialog.
---
--- Example:
--- <pre>
--- <pre>lua
--- vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input)
--- vim.o.shiftwidth = tonumber(input)
--- end)

2
runtime/queries/help/highlights.scm
View File

@@ -17,7 +17,7 @@
text: (_) @text.literal)
(codeblock) @text.literal
(codeblock
">" @conceal (#set! conceal ""))
[">" (language)] @conceal (#set! conceal ""))
(block
"<" @conceal (#set! conceal ""))
(argument) @parameter

3
runtime/queries/help/injections.scm Normal file
View File

@@ -0,0 +1,3 @@
(codeblock
(language) @language
(code) @content)

5
runtime/syntax/help.vim
View File

@@ -14,10 +14,11 @@ set cpo&vim
syn match helpHeadline "^[A-Z.][-A-Z0-9 .,()_']*?\=\ze\(\s\+\*\|$\)"
syn match helpSectionDelim "^===.*===$"
syn match helpSectionDelim "^---.*--$"
" Neovim: support language annotation in codeblocks
if has("conceal")
syn region helpExample matchgroup=helpIgnore start=" >$" start="^>$" end="^[^ \t]"me=e-1 end="^<" concealends
syn region helpExample matchgroup=helpIgnore start=" >[a-z0-9]*$" start="^[a-z0-9]*>$" end="^[^ \t]"me=e-1 end="^<" concealends
else
syn region helpExample matchgroup=helpIgnore start=" >$" start="^>$" end="^[^ \t]"me=e-1 end="^<"
syn region helpExample matchgroup=helpIgnore start=" >[a-z0-9]*$" start="^[a-z0-9]*>$" end="^[^ \t]"me=e-1 end="^<"
endif
syn match helpHyperTextJump "\\\@<!|[#-)!+-~]\+|" contains=helpBar
syn match helpHyperTextEntry "\*[#-)!+-~]\+\*\s"he=e-1 contains=helpStar

20
scripts/gen_help_html.lua
View File

@@ -35,6 +35,7 @@ local spell_dict = {
lua = 'Lua',
VimL = 'Vimscript',
}
local language = nil
local M = {}
@@ -489,7 +490,7 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
end
return string.format('<div class="help-para">\n%s\n</div>\n', text)
elseif node_name == 'line' then
if parent ~= 'codeblock' and (is_blank(text) or is_noise(text, stats.noise_lines)) then
if (parent ~= 'codeblock' or parent ~= 'code') and (is_blank(text) or is_noise(text, stats.noise_lines)) then
return '' -- Discard common "noise" lines.
end
-- XXX: Avoid newlines (too much whitespace) after block elements in old (preformatted) layout.
@@ -536,10 +537,22 @@ local function visit_node(root, level, lang_tree, headings, opt, stats)
elseif node_name == 'argument' then
return ('%s<code>{%s}</code>'):format(ws(), text)
elseif node_name == 'codeblock' then
return text
elseif node_name == 'language' then
language = node_text(root)
return ''
elseif node_name == 'code' then
if is_blank(text) then
return ''
end
return ('<pre>%s</pre>'):format(trim(trim_indent(text), 2))
local code
if language then
code = ('<pre><code class="language-%s">%s</code></pre>'):format(language,trim(trim_indent(text), 2))
language = nil
else
code = ('<pre>%s</pre>'):format(trim(trim_indent(text), 2))
end
return code
elseif node_name == 'tag' then -- anchor
if root:has_error() then
return text
@@ -685,6 +698,9 @@ local function gen_one(fname, to_fname, old, commit)
<link href="/css/bootstrap.css" rel="stylesheet">
<link href="/css/main.css" rel="stylesheet">
<link href="help.css" rel="stylesheet">
<link href="/highlight/styles/neovim.min.css" rel="stylesheet">
<script src="/highlight/highlight.min.js"></script>
<script>hljs.highlightAll();</script>
<title>%s - Neovim docs</title>
</head>
<body>

7
scripts/gen_vimdoc.py
View File

@@ -496,7 +496,12 @@ def render_node(n, text, prefix='', indent='', width=text_width - indentation,
if n.nodeName == 'preformatted':
o = get_text(n, preformatted=True)
ensure_nl = '' if o[-1] == '\n' else '\n'
text += '>{}{}\n<'.format(ensure_nl, o)
if o[0:4] == 'lua\n':
text += '>lua{}{}\n<'.format(ensure_nl, o[3:-1])
elif o[0:4] == 'vim\n':
text += '>vim{}{}\n<'.format(ensure_nl, o[3:-1])
else:
text += '>{}{}\n<'.format(ensure_nl, o)
elif is_inline(n):
text = doc_wrap(get_text(n), indent=indent, width=width)

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

@@ -47,7 +47,7 @@ static int64_t next_autocmd_id = 1;
/// Get all autocommands that match the corresponding {opts}.
///
/// These examples will get autocommands matching ALL the given criteria:
/// <pre>
/// <pre>lua
/// -- Matches all criteria
/// autocommands = vim.api.nvim_get_autocmds({
/// group = "MyGroup",
@@ -367,7 +367,7 @@ cleanup:
/// triggers: a callback function (Lua or Vimscript), or a command (like regular autocommands).
///
/// Example using callback:
/// <pre>
/// <pre>lua
/// -- Lua function
/// local myluafun = function() print("This buffer enters") end
///
@@ -383,8 +383,7 @@ cleanup:
/// Lua functions receive a table with information about the autocmd event as an argument. To use
/// a function which itself accepts another (optional) parameter, wrap the function
/// in a lambda:
///
/// <pre>
/// <pre>lua
/// -- Lua function with an optional parameter.
/// -- The autocmd callback would pass a table as argument but this
/// -- function expects number|nil
@@ -397,7 +396,7 @@ cleanup:
/// </pre>
///
/// Example using command:
/// <pre>
/// <pre>lua
/// vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
/// pattern = {"*.c", "*.h"},
/// command = "echo 'Entering a C or C++ file'",
@@ -405,7 +404,7 @@ cleanup:
/// </pre>
///
/// Example values for pattern:
/// <pre>
/// <pre>lua
/// pattern = "*.py"
/// pattern = { "*.py", "*.pyi" }
/// </pre>
@@ -413,14 +412,14 @@ cleanup:
/// Note: The `pattern` is passed to callbacks and commands as a literal string; environment
/// variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|.
/// Instead, |expand()| such variables explicitly:
/// <pre>
/// <pre>lua
/// pattern = vim.fn.expand("~") .. "/some/path/*.py"
/// </pre>
///
/// Example values for event:
/// <pre>
/// "BufWritePre"
/// {"CursorHold", "BufWritePre", "BufWritePost"}
/// <pre>lua
/// event = "BufWritePre"
/// event = {"CursorHold", "BufWritePre", "BufWritePost"}
/// </pre>
///
/// @param event (string|array) The event or events to register this autocommand
@@ -703,7 +702,7 @@ cleanup:
/// Create or get an autocommand group |autocmd-groups|.
///
/// To get an existing group id, do:
/// <pre>
/// <pre>lua
/// local id = vim.api.nvim_create_augroup("MyGroup", {
/// clear = false
/// })

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

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

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

@@ -889,7 +889,7 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin
/// {command} is the replacement text or Lua function to execute.
///
/// Example:
/// <pre>
/// <pre>vim
/// :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
/// :SayHello
/// Hello world!

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

@@ -255,8 +255,7 @@ 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
/// positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1)
/// respectively, thus the following are equivalent:
///
/// <pre>
/// <pre>lua
/// nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
/// nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {})
/// </pre>
@@ -265,8 +264,7 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
/// with `limit`, to get the first marks prior to a given position.)
///
/// Example:
///
/// <pre>
/// <pre>lua
/// local a = vim.api
/// local pos = a.nvim_win_get_cursor(0)
/// local ns = a.nvim_create_namespace('my-plugin')

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

@@ -229,7 +229,7 @@ void nvim_set_hl_ns_fast(Integer ns_id, Error *err)
/// nvim_feedkeys().
///
/// Example:
/// <pre>
/// <pre>vim
/// :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true)
/// :call nvim_feedkeys(key, 'n', v:false)
/// </pre>
@@ -1295,7 +1295,7 @@ void nvim_unsubscribe(uint64_t channel_id, String event)
/// "#rrggbb" hexadecimal string.
///
/// Example:
/// <pre>
/// <pre>vim
/// :echo nvim_get_color_by_name("Pink")
/// :echo nvim_get_color_by_name("#cbcbcb")
/// </pre>
@@ -1437,12 +1437,12 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode)
/// Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual.
///
/// Example:
/// <pre>
/// <pre>vim
/// call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})
/// </pre>
///
/// is equivalent to:
/// <pre>
/// <pre>vim
/// nmap <nowait> <Space><NL> <Nop>
/// </pre>
///

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

@@ -55,13 +55,13 @@
/// this should not be used to specify arbitrary WM screen positions.
///
/// Example (Lua): window-relative float
/// <pre>
/// <pre>lua
/// vim.api.nvim_open_win(0, false,
/// {relative='win', row=3, col=3, width=12, height=3})
/// </pre>
///
/// Example (Lua): buffer-relative float (travels as buffer is scrolled)
/// <pre>
/// <pre>lua
/// vim.api.nvim_open_win(0, false,
/// {relative='win', width=12, height=3, bufpos={100,10}})
/// </pre>