diff options
| -rw-r--r-- | CONTRIBUTING.md | 9 | ||||
| -rw-r--r-- | runtime/doc/api.txt | 20 | ||||
| -rw-r--r-- | runtime/doc/autocmd.txt | 67 | ||||
| -rw-r--r-- | runtime/doc/deprecated.txt | 1 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 59 | ||||
| -rw-r--r-- | runtime/doc/help.txt | 3 | ||||
| -rw-r--r-- | runtime/doc/index.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/lsp.txt | 24 | ||||
| -rw-r--r-- | runtime/doc/lua.txt | 20 | ||||
| -rw-r--r-- | runtime/doc/tabpage.txt | 3 | ||||
| -rw-r--r-- | runtime/doc/vim_diff.txt | 10 | ||||
| -rw-r--r-- | runtime/lua/vim/lsp.lua | 15 | ||||
| -rw-r--r-- | runtime/lua/vim/shared.lua | 20 | ||||
| -rwxr-xr-x | scripts/gen_vimdoc.py | 7 |
14 files changed, 152 insertions, 108 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 04b4d23a2e..750d853158 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -65,10 +65,11 @@ Pull requests (PRs) Pull requests have three stages: `[WIP]` (Work In Progress), `[RFC]` (Request For Comment) and `[RDY]` (Ready). -- `[RFC]` is assumed by default, i.e. you are requesting a review. -- Add `[WIP]` to the PR title if you are _not_ requesting feedback and the work - is still in flux. -- Add `[RDY]` if you are _done_ and only waiting on merge. +1. `[RFC]` is assumed by default, **do not** put "RFC" in the PR title (it adds + noise to merge commit messages). +2. Add `[WIP]` to the PR title if you are _not_ requesting feedback and the work + is still in flux. +3. Add `[RDY]` to the PR title if you are _done_ and only waiting on merge. ### Commit messages diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index f8fdd64a9b..39b6c6417d 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -183,21 +183,17 @@ External programs (clients) can use the metadata to discover the API, using any of these approaches: 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. - 2. Start Nvim with the |--api-info| option. Useful for clients written in - statically-compiled languages. - - 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()))' + 2. Start Nvim with |--api-info|. Useful for statically-compiled clients. + 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. > + :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* diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 97379bfa27..45bead968d 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -251,7 +251,6 @@ Name triggered by ~ Buffers |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 |BufWipeout| before completely deleting a buffer @@ -367,32 +366,29 @@ Name triggered by ~ The alphabetical list of autocommand events: *autocmd-events-abc* - *BufCreate* *BufAdd* -BufAdd or BufCreate Just after creating a new buffer which is + *BufAdd* +BufAdd Just after creating a new buffer which is added to the buffer list, or adding a buffer - to the buffer list. - Also used just after a buffer in the buffer - list has been renamed. - The BufCreate event is for historic reasons. - NOTE: When this autocommand is executed, the - current buffer "%" may be different from the - buffer being created "<afile>". + to the buffer list, a buffer in the buffer + list was renamed. + Before |BufEnter|. + NOTE: Current buffer "%" may be different from + the buffer being created "<afile>". *BufDelete* BufDelete Before deleting a buffer from the buffer list. The BufUnload may be called first (if the buffer was loaded). Also used just before a buffer in the buffer list is renamed. - NOTE: When this autocommand is executed, the - current buffer "%" may be different from the - buffer being deleted "<afile>" and "<abuf>". - Don't change to another buffer, it will cause - problems. + NOTE: Current buffer "%" may be different from + the buffer being deleted "<afile>" and "<abuf>". + Do not change to another buffer. *BufEnter* BufEnter After entering a buffer. Useful for setting options for a file type. Also executed when starting to edit a buffer, after the - BufReadPost autocommands. + After |BufAdd|. + After |BufReadPost|. *BufFilePost* BufFilePost After changing the name of the current buffer 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 deleted. Not used for ":qa" or ":q" when exiting Vim. - NOTE: When this autocommand is executed, the - current buffer "%" may be different from the - buffer being unloaded "<afile>". + NOTE: current buffer "%" may be different from + the buffer being unloaded "<afile>". *BufLeave* BufLeave Before leaving to another buffer. Also when 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 the buffer is added to the buffer list BufAdd will be triggered too. - NOTE: When this autocommand is executed, the - current buffer "%" may be different from the - buffer being created "<afile>". + NOTE: Current buffer "%" may be different from + the buffer being created "<afile>". *BufNewFile* BufNewFile When starting to edit a file that doesn't 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 BufDelete. Also used for all buffers that are loaded when Vim is going to exit. - NOTE: When this autocommand is executed, the - current buffer "%" may be different from the - buffer being unloaded "<afile>". - Don't change to another buffer or window, it - will cause problems! - When exiting and v:dying is 2 or more this - event is not triggered. + NOTE: Current buffer "%" may be different from + the buffer being unloaded "<afile>". + Do not change to another buffer or window! + Not triggered when exiting and v:dying is 2 or + more. *BufWinEnter* BufWinEnter After a buffer is displayed in a window. This 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. Also triggered when exiting. It's triggered before BufUnload or BufHidden. - NOTE: When this autocommand is executed, the - current buffer "%" may be different from the - buffer being unloaded "<afile>". - When exiting and v:dying is 2 or more this - event is not triggered. + NOTE: Current buffer "%" may be different from + the buffer being unloaded "<afile>". + Not triggered when exiting and v:dying is 2 or + more. *BufWipeout* BufWipeout Before completely deleting a buffer. The 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 is renamed (also when it's not in the buffer list). - NOTE: When this autocommand is executed, the - current buffer "%" may be different from the - buffer being deleted "<afile>". - Don't change to another buffer, it will cause - problems. + NOTE: Current buffer "%" may be different from + the buffer being deleted "<afile>". + Do not change to another buffer. *BufWrite* *BufWritePre* BufWrite or BufWritePre Before writing the whole buffer to a file. *BufWriteCmd* diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index 7c6b9ad1d3..ce075e1bee 100644 --- a/runtime/doc/deprecated.txt +++ b/runtime/doc/deprecated.txt @@ -28,6 +28,7 @@ Environment Variables ~ $NVIM_LISTEN_ADDRESS is ignored. Events ~ +*BufCreate* Use |BufAdd| instead. *EncodingChanged* Never fired; 'encoding' is always "utf-8". *FileEncoding* Never fired; equivalent to |EncodingChanged|. *GUIEnter* Never fired; use |UIEnter| instead. diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 67277d19dd..cd02449475 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -2520,6 +2520,9 @@ and({expr}, {expr}) *and()* api_info() *api_info()* 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()* When {text} is a |List|: Append each item of the |List| as a text line below line {lnum} in the current buffer. @@ -5453,35 +5456,41 @@ jobstart({cmd}[, {opts}]) *jobstart()* *jobstart-options* {opts} is a dictionary with these keys: - |on_stdout|: stdout event handler (function name or |Funcref|) - stdout_buffered : read stdout in |channel-buffered| mode. - |on_stderr|: stderr event handler (function name or |Funcref|) - stderr_buffered : read stderr in |channel-buffered| mode. - |on_exit| : exit event handler (function name or |Funcref|) - cwd : Working directory of the job; defaults to - |current-directory|. - env : A dict of strings to append (or replace see - |clear_env|) to the current environment. - clear_env: If set, use the exact values passed in |env| - rpc : If set, |msgpack-rpc| will be used to communicate - with the job over stdin and stdout. "on_stdout" is - then ignored, but "on_stderr" can still be used. - pty : If set, the job will be connected to a new pseudo - terminal and the job streams are connected to the - master file descriptor. "on_stderr" is ignored, - "on_stdout" receives all output. - - width : (pty only) Width of the terminal screen - height : (pty only) Height of the terminal screen - TERM : (pty only) $TERM environment variable - detach : (non-pty only) Detach the job process: it will - not be killed when Nvim exits. If the process - exits before Nvim, "on_exit" will be invoked. + clear_env: (boolean) `env` defines the job environment + exactly, instead of merging current environment. + cwd: (string, default=|current-directory|) Working + directory of the job. + detach: (boolean) Detach the job process: it will not be + killed when Nvim exits. If the process exits + before Nvim, `on_exit` will be invoked. + env: (dict) Map of environment variable name:value + pairs extending (or replacing if |clear_env|) + the current environment. + height: (number) Height of the `pty` terminal. + |on_exit|: (function) Callback invoked when the job exits. + |on_stdout|: (function) Callback invoked when the job emits + stdout data. + |on_stderr|: (function) Callback invoked when the job emits + stderr data. + pty: (boolean) Connect the job to a new pseudo + terminal, and its streams to the master file + descriptor. Then `on_stderr` is ignored, + `on_stdout` receives all output. + rpc: (boolean) Use |msgpack-rpc| to communicate with + the job over stdio. Then `on_stdout` is ignored, + but `on_stderr` can still be used. + 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 caller may set other keys to pass application-specific data. + Returns: - - The channel ID on success + - |channel-id| on success - 0 on invalid arguments - -1 if {cmd}[0] is not executable. See also |job-control|, |channel|, |msgpack-rpc|. diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt index 6090fa96bb..a384b5f876 100644 --- a/runtime/doc/help.txt +++ b/runtime/doc/help.txt @@ -137,6 +137,7 @@ Special issues ~ Programming language support ~ |indent.txt| automatic indenting for C and other languages +|lsp.txt| Language Server Protocol (LSP) |syntax.txt| syntax highlighting |filetype.txt| settings done specifically for a type of file |quickfix.txt| commands for a quick edit-compile-fix cycle @@ -169,7 +170,7 @@ Versions ~ Standard plugins ~ |pi_gzip.txt| Reading and writing compressed files |pi_health.txt| Healthcheck framework -|pi_matchit.txt| Extended "%" matching +|pi_matchit.txt| Extended |%| matching |pi_msgpack.txt| msgpack utilities |pi_netrw.txt| Reading and writing files over a network |pi_paren.txt| Highlight matching parens diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt index 3b057575a8..bdab10c0e4 100644 --- a/runtime/doc/index.txt +++ b/runtime/doc/index.txt @@ -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., 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 a list of Vim variables see |vim-variable|. For a complete listing of all help items see |help-tags|. diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index c173ecead3..016a8be7e6 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -49,9 +49,9 @@ go-to-definition, hover, etc. Example config: > nnoremap <silent> 1gD <cmd>lua vim.lsp.buf.type_definition()<CR> nnoremap <silent> gr <cmd>lua vim.lsp.buf.references()<CR> -Nvim provides the vim.lsp.omnifunc 'omnifunc' handler which allows -|i_CTRL-X_CTRL-O| to consume LSP completion features. Example config (note the -use of |v:lua| to call Lua from Vimscript): > +Nvim provides the |vim.lsp.omnifunc| 'omnifunc' handler which allows +|i_CTRL-X_CTRL-O| to consume LSP completion. Example config (note the use of +|v:lua| to call Lua from Vimscript): > " Use LSP omni-completion in Python files. autocmd Filetype python setlocal omnifunc=v:lua.vim.lsp.omnifunc @@ -477,7 +477,23 @@ notify({...}) *vim.lsp.notify()* TODO: Documentation 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()* TODO: Documentation diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index d1f244c76f..af1f4a8c1f 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -885,6 +885,16 @@ deepcopy({orig}) *vim.deepcopy()* Return: ~ 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()* Splits a string at each instance of a separator. @@ -962,6 +972,16 @@ split({s}, {sep}, {plain}) *vim.split()* See also: ~ |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()* Add the reverse lookup values to an existing table. For example: `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = diff --git a/runtime/doc/tabpage.txt b/runtime/doc/tabpage.txt index d0a5678179..1407fdd968 100644 --- a/runtime/doc/tabpage.txt +++ b/runtime/doc/tabpage.txt @@ -190,6 +190,9 @@ gt *i_CTRL-<PageDown>* *i_<C-PageDown>* {count}<C-PageDown> {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* :tabN[ext] *:tabNext* *CTRL-<PageUp>* diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index c988756154..2bb798a6e6 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -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 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. Additional differences: @@ -443,6 +438,11 @@ Compile-time features: Emacs tags support 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: *hl-StatusLineTerm* *hl-StatusLineTermNC* are unnecessary because Nvim supports 'winhighlight' window-local highlights. diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua index c193fad6a4..cfa208f21c 100644 --- a/runtime/lua/vim/lsp.lua +++ b/runtime/lua/vim/lsp.lua @@ -914,7 +914,18 @@ function lsp.buf_notify(bufnr, method, params) 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) 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 _ = 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 params = util.make_position_params() diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua index 6df9bf1c2f..a71e9878bb 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -331,21 +331,21 @@ function vim.pesc(s) return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1') end ---- Test if `prefix` is a prefix of `s` for strings. --- --- @param s String to check --- @param prefix Potential prefix --- @return boolean True if prefix is a prefix of s +--- Tests if `s` starts with `prefix`. +--- +--@param s (string) a string +--@param prefix (string) a prefix +--@return (boolean) true if `prefix` is a prefix of s function vim.startswith(s, prefix) vim.validate { s = {s, 's'}; prefix = {prefix, 's'}; } return s:sub(1, #prefix) == prefix end ---- Test if `suffix` is a suffix of `s` for strings. --- --- @param s String to check --- @param suffix Potential suffix --- @return boolean True if suffix is a suffix of s +--- Tests if `s` ends with `suffix`. +--- +--@param s (string) a string +--@param suffix (string) a suffix +--@return (boolean) true if `suffix` is a suffix of s function vim.endswith(s, suffix) vim.validate { s = {s, 's'}; suffix = {suffix, 's'}; } return #suffix == 0 or s:sub(-#suffix) == suffix diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index bdfe52addb..3c51b2aa81 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -167,10 +167,7 @@ CONFIG = { # HACK. TODO(justinmk): class/structure support in lua2dox if 'lsp.client' == f'{fstem}.{name}' else f'*vim.lsp.{fstem}.{name}()*')), - 'module_override': { - # Combine are exposed on the `vim` module. - 'shared': 'vim', - }, + 'module_override': {}, 'append_only': [], }, } @@ -821,7 +818,7 @@ def main(config): stdin=subprocess.PIPE, # silence warnings # runtime/lua/vim/lsp.lua:209: warning: argument 'foo' not found - stderr=subprocess.DEVNULL) + stderr=(subprocess.STDOUT if DEBUG else subprocess.DEVNULL)) p.communicate( config.format( input=CONFIG[target]['files'], |