doc [ci skip] #11656

This commit is contained in:
Justin M. Keyes 2020-01-12 23:41:55 -08:00 committed by GitHub
parent dfb676fe0d
commit 9231684986
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 152 additions and 108 deletions

View File

@ -65,10 +65,11 @@ Pull requests (PRs)
Pull requests have three stages: `[WIP]` (Work In Progress), `[RFC]` (Request Pull requests have three stages: `[WIP]` (Work In Progress), `[RFC]` (Request
For Comment) and `[RDY]` (Ready). For Comment) and `[RDY]` (Ready).
- `[RFC]` is assumed by default, i.e. you are requesting a review. 1. `[RFC]` is assumed by default, **do not** put "RFC" in the PR title (it adds
- Add `[WIP]` to the PR title if you are _not_ requesting feedback and the work noise to merge commit messages).
is still in flux. 2. Add `[WIP]` to the PR title if you are _not_ requesting feedback and the work
- Add `[RDY]` if you are _done_ and only waiting on merge. is still in flux.
3. Add `[RDY]` to the PR title if you are _done_ and only waiting on merge.
### Commit messages ### Commit messages

View File

@ -183,21 +183,17 @@ External programs (clients) can use the metadata to discover the API, using
any of these approaches: any of these approaches:
1. Connect to a running Nvim instance and call |nvim_get_api_info()| via 1. Connect to a running Nvim instance and call |nvim_get_api_info()| via
msgpack-rpc. This is best for clients written in dynamic languages which msgpack-RPC. This is best for clients written in dynamic languages which
can define functions at runtime. can define functions at runtime.
2. Start Nvim with the |--api-info| option. Useful for clients written in 2. Start Nvim with |--api-info|. Useful for statically-compiled clients.
statically-compiled languages. Example (requires Python "pyyaml" and "msgpack-python" modules): >
nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))'
3. Use the |api_info()| Vimscript function.
Example: To get a human-readable list of API functions: >
:new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name')
<
Example: To get a formatted dump of the API using python (requires the
"pyyaml" and "msgpack-python" modules): >
nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))'
< <
3. Use the |api_info()| Vimscript function. >
:lua print(vim.inspect(vim.fn.api_info()))
< Example using |filter()| to exclude non-deprecated API functions: >
:new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name')
============================================================================== ==============================================================================
API contract *api-contract* API contract *api-contract*

View File

@ -251,7 +251,6 @@ Name triggered by ~
Buffers Buffers
|BufAdd| just after adding a buffer to the buffer list |BufAdd| just after adding a buffer to the buffer list
|BufCreate| just after adding a buffer to the buffer list
|BufDelete| before deleting a buffer from the buffer list |BufDelete| before deleting a buffer from the buffer list
|BufWipeout| before completely deleting a buffer |BufWipeout| before completely deleting a buffer
@ -367,32 +366,29 @@ Name triggered by ~
The alphabetical list of autocommand events: *autocmd-events-abc* The alphabetical list of autocommand events: *autocmd-events-abc*
*BufCreate* *BufAdd* *BufAdd*
BufAdd or BufCreate Just after creating a new buffer which is BufAdd Just after creating a new buffer which is
added to the buffer list, or adding a buffer added to the buffer list, or adding a buffer
to the buffer list. to the buffer list, a buffer in the buffer
Also used just after a buffer in the buffer list was renamed.
list has been renamed. Before |BufEnter|.
The BufCreate event is for historic reasons. NOTE: Current buffer "%" may be different from
NOTE: When this autocommand is executed, the the buffer being created "<afile>".
current buffer "%" may be different from the
buffer being created "<afile>".
*BufDelete* *BufDelete*
BufDelete Before deleting a buffer from the buffer list. BufDelete Before deleting a buffer from the buffer list.
The BufUnload may be called first (if the The BufUnload may be called first (if the
buffer was loaded). buffer was loaded).
Also used just before a buffer in the buffer Also used just before a buffer in the buffer
list is renamed. list is renamed.
NOTE: When this autocommand is executed, the NOTE: Current buffer "%" may be different from
current buffer "%" may be different from the the buffer being deleted "<afile>" and "<abuf>".
buffer being deleted "<afile>" and "<abuf>". Do not change to another buffer.
Don't change to another buffer, it will cause
problems.
*BufEnter* *BufEnter*
BufEnter After entering a buffer. Useful for setting BufEnter After entering a buffer. Useful for setting
options for a file type. Also executed when options for a file type. Also executed when
starting to edit a buffer, after the starting to edit a buffer, after the
BufReadPost autocommands. After |BufAdd|.
After |BufReadPost|.
*BufFilePost* *BufFilePost*
BufFilePost After changing the name of the current buffer BufFilePost After changing the name of the current buffer
with the ":file" or ":saveas" command. with the ":file" or ":saveas" command.
@ -405,9 +401,8 @@ BufHidden Just before a buffer becomes hidden. That is,
the buffer, but the buffer is not unloaded or the buffer, but the buffer is not unloaded or
deleted. Not used for ":qa" or ":q" when deleted. Not used for ":qa" or ":q" when
exiting Vim. exiting Vim.
NOTE: When this autocommand is executed, the NOTE: current buffer "%" may be different from
current buffer "%" may be different from the the buffer being unloaded "<afile>".
buffer being unloaded "<afile>".
*BufLeave* *BufLeave*
BufLeave Before leaving to another buffer. Also when BufLeave Before leaving to another buffer. Also when
leaving or closing the current window and the leaving or closing the current window and the
@ -418,9 +413,8 @@ BufNew Just after creating a new buffer. Also used
just after a buffer has been renamed. When just after a buffer has been renamed. When
the buffer is added to the buffer list BufAdd the buffer is added to the buffer list BufAdd
will be triggered too. will be triggered too.
NOTE: When this autocommand is executed, the NOTE: Current buffer "%" may be different from
current buffer "%" may be different from the the buffer being created "<afile>".
buffer being created "<afile>".
*BufNewFile* *BufNewFile*
BufNewFile When starting to edit a file that doesn't BufNewFile When starting to edit a file that doesn't
exist. Can be used to read in a skeleton exist. Can be used to read in a skeleton
@ -451,13 +445,11 @@ BufUnload Before unloading a buffer. This is when the
may be after a BufWritePost and before a may be after a BufWritePost and before a
BufDelete. Also used for all buffers that are BufDelete. Also used for all buffers that are
loaded when Vim is going to exit. loaded when Vim is going to exit.
NOTE: When this autocommand is executed, the NOTE: Current buffer "%" may be different from
current buffer "%" may be different from the the buffer being unloaded "<afile>".
buffer being unloaded "<afile>". Do not change to another buffer or window!
Don't change to another buffer or window, it Not triggered when exiting and v:dying is 2 or
will cause problems! more.
When exiting and v:dying is 2 or more this
event is not triggered.
*BufWinEnter* *BufWinEnter*
BufWinEnter After a buffer is displayed in a window. This BufWinEnter After a buffer is displayed in a window. This
can be when the buffer is loaded (after can be when the buffer is loaded (after
@ -476,11 +468,10 @@ BufWinLeave Before a buffer is removed from a window.
Not when it's still visible in another window. Not when it's still visible in another window.
Also triggered when exiting. It's triggered Also triggered when exiting. It's triggered
before BufUnload or BufHidden. before BufUnload or BufHidden.
NOTE: When this autocommand is executed, the NOTE: Current buffer "%" may be different from
current buffer "%" may be different from the the buffer being unloaded "<afile>".
buffer being unloaded "<afile>". Not triggered when exiting and v:dying is 2 or
When exiting and v:dying is 2 or more this more.
event is not triggered.
*BufWipeout* *BufWipeout*
BufWipeout Before completely deleting a buffer. The BufWipeout Before completely deleting a buffer. The
BufUnload and BufDelete events may be called BufUnload and BufDelete events may be called
@ -488,11 +479,9 @@ BufWipeout Before completely deleting a buffer. The
buffer list). Also used just before a buffer buffer list). Also used just before a buffer
is renamed (also when it's not in the buffer is renamed (also when it's not in the buffer
list). list).
NOTE: When this autocommand is executed, the NOTE: Current buffer "%" may be different from
current buffer "%" may be different from the the buffer being deleted "<afile>".
buffer being deleted "<afile>". Do not change to another buffer.
Don't change to another buffer, it will cause
problems.
*BufWrite* *BufWritePre* *BufWrite* *BufWritePre*
BufWrite or BufWritePre Before writing the whole buffer to a file. BufWrite or BufWritePre Before writing the whole buffer to a file.
*BufWriteCmd* *BufWriteCmd*

View File

@ -28,6 +28,7 @@ Environment Variables ~
$NVIM_LISTEN_ADDRESS is ignored. $NVIM_LISTEN_ADDRESS is ignored.
Events ~ Events ~
*BufCreate* Use |BufAdd| instead.
*EncodingChanged* Never fired; 'encoding' is always "utf-8". *EncodingChanged* Never fired; 'encoding' is always "utf-8".
*FileEncoding* Never fired; equivalent to |EncodingChanged|. *FileEncoding* Never fired; equivalent to |EncodingChanged|.
*GUIEnter* Never fired; use |UIEnter| instead. *GUIEnter* Never fired; use |UIEnter| instead.

View File

@ -2520,6 +2520,9 @@ and({expr}, {expr}) *and()*
api_info() *api_info()* api_info() *api_info()*
Returns Dictionary of |api-metadata|. Returns Dictionary of |api-metadata|.
View it in a nice human-readable format: >
:lua print(vim.inspect(vim.fn.api_info()))
append({lnum}, {text}) *append()* append({lnum}, {text}) *append()*
When {text} is a |List|: Append each item of the |List| as a When {text} is a |List|: Append each item of the |List| as a
text line below line {lnum} in the current buffer. text line below line {lnum} in the current buffer.
@ -5453,35 +5456,41 @@ jobstart({cmd}[, {opts}]) *jobstart()*
*jobstart-options* *jobstart-options*
{opts} is a dictionary with these keys: {opts} is a dictionary with these keys:
|on_stdout|: stdout event handler (function name or |Funcref|) clear_env: (boolean) `env` defines the job environment
stdout_buffered : read stdout in |channel-buffered| mode. exactly, instead of merging current environment.
|on_stderr|: stderr event handler (function name or |Funcref|) cwd: (string, default=|current-directory|) Working
stderr_buffered : read stderr in |channel-buffered| mode. directory of the job.
|on_exit| : exit event handler (function name or |Funcref|) detach: (boolean) Detach the job process: it will not be
cwd : Working directory of the job; defaults to killed when Nvim exits. If the process exits
|current-directory|. before Nvim, `on_exit` will be invoked.
env : A dict of strings to append (or replace see env: (dict) Map of environment variable name:value
|clear_env|) to the current environment. pairs extending (or replacing if |clear_env|)
clear_env: If set, use the exact values passed in |env| the current environment.
rpc : If set, |msgpack-rpc| will be used to communicate height: (number) Height of the `pty` terminal.
with the job over stdin and stdout. "on_stdout" is |on_exit|: (function) Callback invoked when the job exits.
then ignored, but "on_stderr" can still be used. |on_stdout|: (function) Callback invoked when the job emits
pty : If set, the job will be connected to a new pseudo stdout data.
terminal and the job streams are connected to the |on_stderr|: (function) Callback invoked when the job emits
master file descriptor. "on_stderr" is ignored, stderr data.
"on_stdout" receives all output. pty: (boolean) Connect the job to a new pseudo
terminal, and its streams to the master file
width : (pty only) Width of the terminal screen descriptor. Then `on_stderr` is ignored,
height : (pty only) Height of the terminal screen `on_stdout` receives all output.
TERM : (pty only) $TERM environment variable rpc: (boolean) Use |msgpack-rpc| to communicate with
detach : (non-pty only) Detach the job process: it will the job over stdio. Then `on_stdout` is ignored,
not be killed when Nvim exits. If the process but `on_stderr` can still be used.
exits before Nvim, "on_exit" will be invoked. stderr_buffered: (boolean) Collect data until EOF (stream closed)
before invoking `on_stderr`. |channel-buffered|
stdout_buffered: (boolean) Collect data until EOF (stream
closed) before invoking `on_stdout`. |channel-buffered|
TERM: (string) Sets the `pty` $TERM environment variable.
width: (number) Width of the `pty` terminal.
{opts} is passed as |self| dictionary to the callback; the {opts} is passed as |self| dictionary to the callback; the
caller may set other keys to pass application-specific data. caller may set other keys to pass application-specific data.
Returns: Returns:
- The channel ID on success - |channel-id| on success
- 0 on invalid arguments - 0 on invalid arguments
- -1 if {cmd}[0] is not executable. - -1 if {cmd}[0] is not executable.
See also |job-control|, |channel|, |msgpack-rpc|. See also |job-control|, |channel|, |msgpack-rpc|.

View File

@ -137,6 +137,7 @@ Special issues ~
Programming language support ~ Programming language support ~
|indent.txt| automatic indenting for C and other languages |indent.txt| automatic indenting for C and other languages
|lsp.txt| Language Server Protocol (LSP)
|syntax.txt| syntax highlighting |syntax.txt| syntax highlighting
|filetype.txt| settings done specifically for a type of file |filetype.txt| settings done specifically for a type of file
|quickfix.txt| commands for a quick edit-compile-fix cycle |quickfix.txt| commands for a quick edit-compile-fix cycle
@ -169,7 +170,7 @@ Versions ~
Standard plugins ~ Standard plugins ~
|pi_gzip.txt| Reading and writing compressed files |pi_gzip.txt| Reading and writing compressed files
|pi_health.txt| Healthcheck framework |pi_health.txt| Healthcheck framework
|pi_matchit.txt| Extended "%" matching |pi_matchit.txt| Extended |%| matching
|pi_msgpack.txt| msgpack utilities |pi_msgpack.txt| msgpack utilities
|pi_netrw.txt| Reading and writing files over a network |pi_netrw.txt| Reading and writing files over a network
|pi_paren.txt| Highlight matching parens |pi_paren.txt| Highlight matching parens

View File

@ -10,7 +10,7 @@ short description. The lists are sorted on ASCII value.
Tip: When looking for certain functionality, use a search command. E.g., Tip: When looking for certain functionality, use a search command. E.g.,
to look for deleting something, use: "/delete". to look for deleting something, use: "/delete".
For an overview of options see help.txt |option-list|. For an overview of options see |option-list|.
For an overview of built-in functions see |functions|. For an overview of built-in functions see |functions|.
For a list of Vim variables see |vim-variable|. For a list of Vim variables see |vim-variable|.
For a complete listing of all help items see |help-tags|. For a complete listing of all help items see |help-tags|.

View File

@ -49,9 +49,9 @@ go-to-definition, hover, etc. Example config: >
nnoremap <silent> 1gD <cmd>lua vim.lsp.buf.type_definition()<CR> nnoremap <silent> 1gD <cmd>lua vim.lsp.buf.type_definition()<CR>
nnoremap <silent> gr <cmd>lua vim.lsp.buf.references()<CR> nnoremap <silent> gr <cmd>lua vim.lsp.buf.references()<CR>
Nvim provides the vim.lsp.omnifunc 'omnifunc' handler which allows Nvim provides the |vim.lsp.omnifunc| 'omnifunc' handler which allows
|i_CTRL-X_CTRL-O| to consume LSP completion features. Example config (note the |i_CTRL-X_CTRL-O| to consume LSP completion. Example config (note the use of
use of |v:lua| to call Lua from Vimscript): > |v:lua| to call Lua from Vimscript): >
" Use LSP omni-completion in Python files. " Use LSP omni-completion in Python files.
autocmd Filetype python setlocal omnifunc=v:lua.vim.lsp.omnifunc autocmd Filetype python setlocal omnifunc=v:lua.vim.lsp.omnifunc
@ -477,7 +477,23 @@ notify({...}) *vim.lsp.notify()*
TODO: Documentation TODO: Documentation
omnifunc({findstart}, {base}) *vim.lsp.omnifunc()* omnifunc({findstart}, {base}) *vim.lsp.omnifunc()*
TODO: Documentation Implements 'omnifunc' compatible LSP completion.
Parameters: ~
{findstart} 0 or 1, decides behavior
{base} If findstart=0, text to match against
Return: ~
(number) Decided by`findstart`:
• findstart=0: column where the completion starts, or -2
or -3
• findstart=1: list of matches (actually just calls
|complete()|)
See also: ~
|complete-functions|
|complete-items|
|CompleteDone|
on_error({code}, {err}) *vim.lsp.on_error()* on_error({code}, {err}) *vim.lsp.on_error()*
TODO: Documentation TODO: Documentation

View File

@ -885,6 +885,16 @@ deepcopy({orig}) *vim.deepcopy()*
Return: ~ Return: ~
New table of copied keys and (nested) values. New table of copied keys and (nested) values.
endswith({s}, {suffix}) *vim.endswith()*
Tests if `s` ends with `suffix` .
Parameters: ~
{s} (string) a string
{suffix} (string) a suffix
Return: ~
(boolean) true if `suffix` is a suffix of s
gsplit({s}, {sep}, {plain}) *vim.gsplit()* gsplit({s}, {sep}, {plain}) *vim.gsplit()*
Splits a string at each instance of a separator. Splits a string at each instance of a separator.
@ -962,6 +972,16 @@ split({s}, {sep}, {plain}) *vim.split()*
See also: ~ See also: ~
|vim.gsplit()| |vim.gsplit()|
startswith({s}, {prefix}) *vim.startswith()*
Tests if `s` starts with `prefix` .
Parameters: ~
{s} (string) a string
{prefix} (string) a prefix
Return: ~
(boolean) true if `prefix` is a prefix of s
tbl_add_reverse_lookup({o}) *vim.tbl_add_reverse_lookup()* tbl_add_reverse_lookup({o}) *vim.tbl_add_reverse_lookup()*
Add the reverse lookup values to an existing table. For Add the reverse lookup values to an existing table. For
example: `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = example: `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A =

View File

@ -190,6 +190,9 @@ gt *i_CTRL-<PageDown>* *i_<C-PageDown>*
{count}<C-PageDown> {count}<C-PageDown>
{count}gt Go to tab page {count}. The first tab page has number one. {count}gt Go to tab page {count}. The first tab page has number one.
CTRL-<Tab> *CTRL-<Tab>*
CTRL-W g<Tab> *g<Tab>* *CTRL-W_g<Tab>*
g<Tab> Go to previous (last accessed) tab page.
:tabp[revious] *:tabp* *:tabprevious* *gT* *:tabN* :tabp[revious] *:tabp* *:tabprevious* *gT* *:tabN*
:tabN[ext] *:tabNext* *CTRL-<PageUp>* :tabN[ext] *:tabNext* *CTRL-<PageUp>*

View File

@ -270,11 +270,6 @@ are always available and may be used simultaneously. See |provider-python|.
|json_encode()| behaviour slightly changed: now |msgpack-special-dict| values |json_encode()| behaviour slightly changed: now |msgpack-special-dict| values
are accepted, but |v:none| is not. are accepted, but |v:none| is not.
*v:none* variable is absent. In Vim it represents “no value” in “js” strings
like "[,]" parsed as "[v:none]" by |js_decode()|.
*js_encode()* and *js_decode()* functions are also absent.
Viminfo text files were replaced with binary (messagepack) ShaDa files. Viminfo text files were replaced with binary (messagepack) ShaDa files.
Additional differences: Additional differences:
@ -443,6 +438,11 @@ Compile-time features:
Emacs tags support Emacs tags support
X11 integration (see |x11-selection|) X11 integration (see |x11-selection|)
Eval:
*js_encode()*
*js_decode()*
*v:none* (used by Vim to represent JavaScript "undefined"); use |v:null| instead.
Highlight groups: Highlight groups:
*hl-StatusLineTerm* *hl-StatusLineTermNC* are unnecessary because Nvim *hl-StatusLineTerm* *hl-StatusLineTermNC* are unnecessary because Nvim
supports 'winhighlight' window-local highlights. supports 'winhighlight' window-local highlights.

View File

@ -914,7 +914,18 @@ function lsp.buf_notify(bufnr, method, params)
end) end)
end end
--- Function which can be called to generate omnifunc compatible completion. --- Implements 'omnifunc' compatible LSP completion.
---
--@see |complete-functions|
--@see |complete-items|
--@see |CompleteDone|
---
--@param findstart 0 or 1, decides behavior
--@param base If findstart=0, text to match against
---
--@return (number) Decided by `findstart`:
--- - findstart=0: column where the completion starts, or -2 or -3
--- - findstart=1: list of matches (actually just calls |complete()|)
function lsp.omnifunc(findstart, base) function lsp.omnifunc(findstart, base)
local _ = log.debug() and log.debug("omnifunc.findstart", { findstart = findstart, base = base }) local _ = log.debug() and log.debug("omnifunc.findstart", { findstart = findstart, base = base })
@ -936,7 +947,7 @@ function lsp.omnifunc(findstart, base)
local line_to_cursor = line:sub(1, pos[2]) local line_to_cursor = line:sub(1, pos[2])
local _ = log.trace() and log.trace("omnifunc.line", pos, line) local _ = log.trace() and log.trace("omnifunc.line", pos, line)
-- Get the start postion of the current keyword -- Get the start position of the current keyword
local textMatch = vim.fn.match(line_to_cursor, '\\k*$') local textMatch = vim.fn.match(line_to_cursor, '\\k*$')
local params = util.make_position_params() local params = util.make_position_params()

View File

@ -331,21 +331,21 @@ function vim.pesc(s)
return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1') return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1')
end end
--- Test if `prefix` is a prefix of `s` for strings. --- Tests if `s` starts with `prefix`.
-- ---
-- @param s String to check --@param s (string) a string
-- @param prefix Potential prefix --@param prefix (string) a prefix
-- @return boolean True if prefix is a prefix of s --@return (boolean) true if `prefix` is a prefix of s
function vim.startswith(s, prefix) function vim.startswith(s, prefix)
vim.validate { s = {s, 's'}; prefix = {prefix, 's'}; } vim.validate { s = {s, 's'}; prefix = {prefix, 's'}; }
return s:sub(1, #prefix) == prefix return s:sub(1, #prefix) == prefix
end end
--- Test if `suffix` is a suffix of `s` for strings. --- Tests if `s` ends with `suffix`.
-- ---
-- @param s String to check --@param s (string) a string
-- @param suffix Potential suffix --@param suffix (string) a suffix
-- @return boolean True if suffix is a suffix of s --@return (boolean) true if `suffix` is a suffix of s
function vim.endswith(s, suffix) function vim.endswith(s, suffix)
vim.validate { s = {s, 's'}; suffix = {suffix, 's'}; } vim.validate { s = {s, 's'}; suffix = {suffix, 's'}; }
return #suffix == 0 or s:sub(-#suffix) == suffix return #suffix == 0 or s:sub(-#suffix) == suffix

View File

@ -167,10 +167,7 @@ CONFIG = {
# HACK. TODO(justinmk): class/structure support in lua2dox # HACK. TODO(justinmk): class/structure support in lua2dox
if 'lsp.client' == f'{fstem}.{name}' if 'lsp.client' == f'{fstem}.{name}'
else f'*vim.lsp.{fstem}.{name}()*')), else f'*vim.lsp.{fstem}.{name}()*')),
'module_override': { 'module_override': {},
# Combine are exposed on the `vim` module.
'shared': 'vim',
},
'append_only': [], 'append_only': [],
}, },
} }
@ -821,7 +818,7 @@ def main(config):
stdin=subprocess.PIPE, stdin=subprocess.PIPE,
# silence warnings # silence warnings
# runtime/lua/vim/lsp.lua:209: warning: argument 'foo' not found # runtime/lua/vim/lsp.lua:209: warning: argument 'foo' not found
stderr=subprocess.DEVNULL) stderr=(subprocess.STDOUT if DEBUG else subprocess.DEVNULL))
p.communicate( p.communicate(
config.format( config.format(
input=CONFIG[target]['files'], input=CONFIG[target]['files'],