diff options
Diffstat (limited to 'runtime')
26 files changed, 920 insertions, 478 deletions
diff --git a/runtime/autoload/health/nvim.vim b/runtime/autoload/health/nvim.vim index efa3292801..8fcea2e941 100644 --- a/runtime/autoload/health/nvim.vim +++ b/runtime/autoload/health/nvim.vim @@ -170,6 +170,17 @@ function! s:check_tmux() abort \ ["Set default-terminal in ~/.tmux.conf:\nset-option -g default-terminal \"screen-256color\"", \ s:suggest_faq]) endif + + " check for RGB capabilities + let info = system('tmux server-info') + let has_tc = stridx(info, " Tc: (flag) true") != -1 + let has_rgb = stridx(info, " RGB: (flag) true") != -1 + if !has_tc && !has_rgb + call health#report_warn( + \ "Neither Tc nor RGB capability set. True colors are disabled. |'termguicolors'| won't work properly.", + \ ["Put this in your ~/.tmux.conf and replace XXX by your $TERM outside of tmux:\nset-option -sa terminal-overrides ',XXX:RGB'", + \ "For older tmux versions use this instead:\nset-option -ga terminal-overrides ',XXX:Tc'"]) + endif endfunction function! s:check_terminal() abort diff --git a/runtime/autoload/health/provider.vim b/runtime/autoload/health/provider.vim index 8f364a2ace..29bbee4888 100644 --- a/runtime/autoload/health/provider.vim +++ b/runtime/autoload/health/provider.vim @@ -106,7 +106,8 @@ endfunction " Fetch the contents of a URL. function! s:download(url) abort - if executable('curl') + let has_curl = executable('curl') + if has_curl && system(['curl', '-V']) =~# 'Protocols:.*https' let rv = s:system(['curl', '-sL', a:url], '', 1, 1) return s:shell_error ? 'curl error with '.a:url.': '.s:shell_error : rv elseif executable('python') @@ -124,7 +125,9 @@ function! s:download(url) abort \ ? 'python urllib.request error: '.s:shell_error \ : rv endif - return 'missing `curl` and `python`, cannot make pypi request' + return 'missing `curl` ' + \ .(has_curl ? '(with HTTPS support) ' : '') + \ .'and `python`, cannot make web request' endfunction " Check for clipboard tools. diff --git a/runtime/autoload/spellfile.vim b/runtime/autoload/spellfile.vim index 9ec6091218..c0ef51cdfe 100644 --- a/runtime/autoload/spellfile.vim +++ b/runtime/autoload/spellfile.vim @@ -195,16 +195,6 @@ function! spellfile#GetDirChoices() endfunc function! spellfile#WritableSpellDir() - " Always use the $XDG_DATA_HOME/nvim/site directory - if exists('$XDG_DATA_HOME') - return $XDG_DATA_HOME . "/nvim/site/spell" - elseif !(has('win32') || has('win64')) - return $HOME . "/.local/share/nvim/site/spell" - endif - for dir in split(&rtp, ',') - if filewritable(dir) == 2 - return dir . "/spell" - endif - endfor - return '' + " Always use the $XDG_DATA_HOME/…/site directory + return stdpath('data').'/site/spell' endfunction diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index c8b9dd5fad..ed6e4905b4 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -46,7 +46,7 @@ version.api_prerelease Declares the API as unstable/unreleased > (version.api_prerelease && fn.since == version.api_level) functions API function signatures ui_events UI event signatures |ui| -ui_options Supported |ui-options| +ui_options Supported |ui-option|s {fn}.since API level where function {fn} was introduced {fn}.deprecated_since API level where function {fn} was deprecated types Custom handle types defined by Nvim @@ -206,17 +206,15 @@ Highlights are registered using the |nvim_buf_add_highlight()| function. If an external highlighter plugin wants to add many highlights in a batch, performance can be improved by calling |nvim_buf_add_highlight()| as an asynchronous notification, after first (synchronously) reqesting a source id. -Example using the Nvim python-client: + +Example using the Python API client (|pynvim|): > src = vim.new_highlight_source() - buf = vim.current.buffer for i in range(5): buf.add_highlight("String",i,0,-1,src_id=src) - - # some time later - - buf.clear_highlight(src) + # some time later ... + buf.clear_namespace(src) < If the highlights don't need to be deleted or updated, just pass -1 as src_id (this is the default in python). Use |nvim_buf_clear_namespace()| to @@ -224,13 +222,12 @@ 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). -An example of calling the api from vimscript: > +Example using the API from Vimscript: > call nvim_buf_set_lines(0, 0, 0, v:true, ["test text"]) let src = nvim_buf_add_highlight(0, 0, "String", 1, 0, 4) call nvim_buf_add_highlight(0, src, "Identifier", 0, 5, -1) - - " later + " some time later ... call nvim_buf_clear_namespace(0, src, 0, -1) @@ -494,8 +491,6 @@ nvim_set_current_dir({dir}) *nvim_set_current_dir()* nvim_get_current_line() *nvim_get_current_line()* Gets the current line. - Parameters: ~ - Return: ~ Current line string @@ -508,8 +503,6 @@ nvim_set_current_line({line}) *nvim_set_current_line()* nvim_del_current_line() *nvim_del_current_line()* Deletes the current line. - Parameters: ~ - nvim_get_var({name}) *nvim_get_var()* Gets a global (g:) variable. @@ -656,6 +649,7 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* For a general overview of floats, see |api-floatwin|. Exactly one of `external` and `relative` must be specified. + The `width` and `height` of the new window must be specified. With editor positioning row=0, col=0 refers to the top-left corner of the screen-grid and row=Lines-1, Columns-1 refers to @@ -697,7 +691,7 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* - `height` : window height (in character cells). Minimum of 1. - `width` : window width (in character cells). - Minimum of 2. + Minimum of 1. - `row` : row position. Screen cell height are used as unit. Can be floating point. - `col` : column position. Screen cell width is @@ -769,10 +763,28 @@ nvim_unsubscribe({event}) *nvim_unsubscribe()* {event} Event type string nvim_get_color_by_name({name}) *nvim_get_color_by_name()* - TODO: Documentation + Returns the 24-bit RGB value of a |nvim_get_color_map()| color + name or "#rrggbb" hexadecimal string. + + Example: > + :echo nvim_get_color_by_name("Pink") + :echo nvim_get_color_by_name("#cbcbcb") +< + + Parameters: ~ + {name} Color name or "#rrggbb" string + + Return: ~ + 24-bit RGB value, or -1 for invalid argument. nvim_get_color_map() *nvim_get_color_map()* - TODO: Documentation + Returns a map of color names and RGB values. + + Keys are color names (e.g. "Aqua") and values are 24-bit RGB + color values (e.g. 65535). + + Return: ~ + Map of color names and RGB values. nvim_get_mode() *nvim_get_mode()* Gets the current mode. |mode()| "blocking" is true if Nvim is @@ -795,6 +807,42 @@ nvim_get_keymap({mode}) *nvim_get_keymap()* Array of maparg()-like dictionaries describing mappings. The "buffer" key is always zero. +nvim_set_keymap({mode}, {lhs}, {rhs}, {opts}) *nvim_set_keymap()* + Sets a global |mapping| for the given mode. + + To set a buffer-local mapping, use |nvim_buf_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: > + call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true}) +< + + is equivalent to: > + nmap <nowait> <Space><NL> <Nop> +< + + Parameters: ~ + {mode} Mode short-name (map command prefix: "n", "i", + "v", "x", …) or "!" for |:map!|, or empty string + for |:map|. + {lhs} Left-hand-side |{lhs}| of the mapping. + {rhs} Right-hand-side |{rhs}| of the mapping. + {opts} Optional parameters map. Accepts all + |:map-arguments| as keys excluding |<buffer>| but + including |noremap|. Values are Booleans. Unknown + key is an error. + +nvim_del_keymap({mode}, {lhs}) *nvim_del_keymap()* + Unmaps a global |mapping| for the given mode. + + To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|. + + See also: ~ + |nvim_set_keymap()| + nvim_get_commands({opts}) *nvim_get_commands()* Gets a map of global (non-buffer-local) Ex commands. @@ -1092,11 +1140,11 @@ nvim_list_uis() *nvim_list_uis()* Return: ~ Array of UI dictionaries, each with these keys: - - "height" requested height of the UI - - "width" requested width of the UI + - "height" Requested height of the UI + - "width" Requested width of the UI - "rgb" true if the UI uses RGB colors (false implies |cterm-colors|) - - "ext_..." Requested UI extensions, see |ui-options| + - "ext_..." Requested UI extensions, see |ui-option| - "chan" Channel id of remote UI (not present for TUI) nvim_get_proc_children({pid}) *nvim_get_proc_children()* @@ -1161,7 +1209,7 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()* Line count, or 0 for unloaded buffer. |api-buffer| nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* - Activate updates from this buffer to the current channel. + Activates buffer-update events on the channel. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer @@ -1180,7 +1228,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* True. nvim_buf_detach({buffer}) *nvim_buf_detach()* - Deactivate updates from this buffer to the current channel. + Deactivates buffer-update events on the channel. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer @@ -1284,6 +1332,25 @@ nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()* Array of maparg()-like dictionaries describing mappings. The "buffer" key holds the associated buffer handle. + *nvim_buf_set_keymap()* +nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {opts}) + Sets a buffer-local |mapping| for the given mode. + + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + + See also: ~ + |nvim_set_keymap()| + +nvim_buf_del_keymap({buffer}, {mode}, {lhs}) *nvim_buf_del_keymap()* + Unmaps a buffer-local |mapping| for the given mode. + + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + + See also: ~ + |nvim_del_keymap()| + nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()* Gets a map of buffer-local |user-commands|. @@ -1738,10 +1805,27 @@ nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()* UI Functions *api-ui* nvim_ui_attach({width}, {height}, {options}) *nvim_ui_attach()* - TODO: Documentation + Activates UI events on the channel. + + Entry point of all UI clients. Allows |--embed| to continue + startup. Implies that the client is ready to show the UI. Adds + the client to the list of UIs. |nvim_list_uis()| + + Note: + If multiple UI clients are attached, the global screen + dimensions degrade to the smallest client. E.g. if client + A requests 80x40 but client B requests 200x100, the global + screen has size 80x40. + + Parameters: ~ + {width} Requested screen columns + {height} Requested screen rows + {options} |ui-option| map nvim_ui_detach() *nvim_ui_detach()* - TODO: Documentation + Deactivates UI events on the channel. + + Removes the client from the list of UIs. |nvim_list_uis()| nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()* TODO: Documentation diff --git a/runtime/doc/debug.txt b/runtime/doc/debug.txt index 835b35b388..7b08e61655 100644 --- a/runtime/doc/debug.txt +++ b/runtime/doc/debug.txt @@ -76,15 +76,10 @@ matches the EXE (same date). If you built the executable yourself with the Microsoft Visual C++ compiler, then the PDB was built with the EXE. -Alternatively, if you have the source files, you can import Make_ivc.mak into -Visual Studio as a workspace. Then select a debug configuration, build and -you can do all kinds of debugging (set breakpoints, watch variables, etc.). - If you have Visual Studio, use that instead of the VC Toolkit and WinDbg. -For other compilers, you should always use the corresponding debugger: TD for -a Vim executable compiled with the Borland compiler; gdb (see above -|debug-gcc|) for the Cygwin and MinGW compilers. +For other compilers, you should always use the corresponding debugger: gdb +(see above |debug-gcc|) for the Cygwin and MinGW compilers. *debug-vs2005* @@ -112,7 +107,7 @@ line numbers. Double-click one of the lines and the Find Source dialog will appear. Navigate to the directory where the Vim source is (if you have it.) If you don't know how to debug this any further, follow the instructions -at ":help bug-reports". Paste the call stack into the bug report. +at ":help bug-report". Paste the call stack into the bug report. If you have a non-free version of Visual Studio, you can save a minidump via the Debug menu and send it with the bug report. A minidump is a small file diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index 9e74efabe0..b56240353f 100644 --- a/runtime/doc/deprecated.txt +++ b/runtime/doc/deprecated.txt @@ -12,6 +12,9 @@ updated. ============================================================================== +API ~ +*nvim_buf_clear_highlight()* Use |nvim_buf_clear_namespace()| instead. + Commands ~ *:rv* *:rviminfo* Deprecated alias to |:rshada| command. @@ -65,10 +68,8 @@ Options ~ *'viminfofile'* Deprecated alias to 'shadafile' option. UI extensions~ -*ui-wildmenu* Use `ext_cmdline` and `ext_popupmenu` instead. - Enabled by `ext_wildmenu` |ui-options|. - If `ext_wildmenu` is set, these events are emitted for - backwards-compatibility: +*ui-wildmenu* Use |ui-cmdline| with |ui-popupmenu| instead. Enabled + by the `ext_wildmenu` |ui-option|. Emits these events: ["wildmenu_show", items] ["wildmenu_select", selected] ["wildmenu_hide"] diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index a6ba7ee9c5..843e23ee54 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -157,28 +157,32 @@ with a {thing} that groups functions under a common concept). Use existing common {action} names if possible: add Append to, or insert into, a collection - get Get a thing (or subset of things by some query) - set Set a thing + get Get a thing (or group of things by query) + set Set a thing (or group of things) del Delete a thing (or group of things) list Get all things Use consistent names for {thing} in all API functions. E.g. a buffer is called "buf" everywhere, not "buffer" in some places and "buf" in others. -Example: `nvim_get_current_line` acts on the global editor state; the common -{action} "get" is used but {thing} is omitted. +Example: + `nvim_get_current_line` acts on the global editor state; the common + {action} "get" is used but {thing} is omitted. -Example: `nvim_buf_add_highlight` acts on a `Buffer` object (the first -parameter) and uses the common {action} "add". +Example: + `nvim_buf_add_highlight` acts on a `Buffer` object (the first parameter) + and uses the common {action} "add". -Example: `nvim_list_bufs` operates in a global context (first parameter is -_not_ a Buffer). The common {action} "list" indicates that it lists all -bufs (plural) in the global context. +Example: + `nvim_list_bufs` operates in a global context (first parameter is not + a Buffer). The common {action} "list" indicates that it lists all bufs + (plural) in the global context. Use this template to name new API events: nvim_{thing}_{event}_event -Example: `nvim_buf_changedtick_event`. +Example: + `nvim_buf_changedtick_event` API-CLIENT *dev-api-client* diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index d400df6b7d..8eca463c7f 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1502,7 +1502,8 @@ v:dying Normally zero. When a deadly signal is caught it's set to v:exiting Exit code, or |v:null| if not exiting. |VimLeave| *v:errmsg* *errmsg-variable* -v:errmsg Last given error message. It's allowed to set this variable. +v:errmsg Last given error message. + Modifiable (can be set). Example: > :let v:errmsg = "" :silent! next @@ -1827,7 +1828,8 @@ v:shell_error Result of the last shell command. When non-zero, the last :endif < *v:statusmsg* *statusmsg-variable* -v:statusmsg Last given status message. It's allowed to set this variable. +v:statusmsg Last given status message. + Modifiable (can be set). *v:stderr* *stderr-variable* v:stderr |channel-id| corresponding to stderr. The value is always 2; @@ -1893,9 +1895,9 @@ v:termresponse The escape sequence returned by the terminal for the DA v:testing Must be set before using `test_garbagecollect_now()`. *v:this_session* *this_session-variable* -v:this_session Full filename of the last loaded or saved session file. See - |:mksession|. It is allowed to set this variable. When no - session file has been saved, this variable is empty. +v:this_session Full filename of the last loaded or saved session file. + Empty when no session file has been saved. See |:mksession|. + Modifiable (can be set). *v:throwpoint* *throwpoint-variable* v:throwpoint The point where the exception most recently caught and not @@ -1922,22 +1924,20 @@ v:val Value of the current item of a |List| or |Dictionary|. Only |filter()|. Read-only. *v:version* *version-variable* -v:version Version number of Vim: Major version number times 100 plus - minor version number. Version 5.0 is 500. Version 5.1 (5.01) - is 501. Read-only. "version" also works, for backwards - compatibility. - Use |has()| to check if a certain patch was included, e.g.: > - if has("patch-7.4.123") -< Note that patch numbers are specific to the version, thus both - version 5.0 and 5.1 may have a patch 123, but these are - completely different. +v:version Vim version number: major version times 100 plus minor + version. Vim 5.0 is 500, Vim 5.1 is 501. + Read-only. + Use |has()| to check the Nvim (not Vim) version: > + :if has("nvim-0.2.1") +< *v:vim_did_enter* *vim_did_enter-variable* -v:vim_did_enter Zero until most of startup is done. It is set to one just - before |VimEnter| autocommands are triggered. +v:vim_did_enter 0 during startup, 1 just before |VimEnter|. + Read-only. *v:warningmsg* *warningmsg-variable* -v:warningmsg Last given warning message. It's allowed to set this variable. +v:warningmsg Last given warning message. + Modifiable (can be set). *v:windowid* *windowid-variable* v:windowid Application-specific window "handle" which may be set by any @@ -1966,6 +1966,7 @@ argidx() Number current index in the argument list arglistid([{winnr} [, {tabnr}]]) Number argument list id argv({nr} [, {winid}]) String {nr} entry of the argument list argv([-1, {winid}]) List the argument list +assert_beeps({cmd}) none assert {cmd} causes a beep assert_equal({exp}, {act} [, {msg}]) none assert {exp} is equal to {act} assert_exception({error} [, {msg}]) @@ -2111,10 +2112,11 @@ gettabvar({nr}, {varname} [, {def}]) any variable {varname} in tab {nr} or {def} gettabwinvar({tabnr}, {winnr}, {name} [, {def}]) any {name} in {winnr} in tab page {tabnr} +gettagstack([{nr}]) Dict get the tag stack of window {nr} getwininfo([{winid}]) List list of windows getwinpos([{timeout}]) List X and Y coord in pixels of the Vim window -getwinposx() Number X coord in pixels of GUI Vim window -getwinposy() Number Y coord in pixels of GUI Vim window +getwinposx() Number X coord in pixels of Vim window +getwinposy() Number Y coord in pixels of Vim window getwinvar({nr}, {varname} [, {def}]) any variable {varname} in window {nr} glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) @@ -2276,6 +2278,8 @@ setreg({n}, {v}[, {opt}]) Number set register to value and type settabvar({nr}, {varname}, {val}) set {varname} in tab page {nr} to {val} settabwinvar({tabnr}, {winnr}, {varname}, {val}) set {varname} in window {winnr} in tab page {tabnr} to {val} +settagstack({nr}, {dict} [, {action}]) + Number modify tag stack using {dict} setwinvar({nr}, {varname}, {val}) set {varname} in window {nr} to {val} sha256({string}) String SHA256 checksum of {string} shellescape({string} [, {special}]) @@ -2320,6 +2324,8 @@ submatch({nr} [, {list}]) String or List specific match in ":s" or substitute() substitute({expr}, {pat}, {sub}, {flags}) String all {pat} in {expr} replaced with {sub} +swapinfo({fname}) Dict information about swap file {fname} +swapname({expr}) String swap file of buffer {expr} synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col} synIDattr({synID}, {what} [, {mode}]) String attribute {what} of syntax ID {synID} @@ -2479,6 +2485,11 @@ argv([{nr} [, {winid}]) The {winid} argument specifies the window ID, see |argc()|. +assert_beeps({cmd}) *assert_beeps()* + Run {cmd} and add an error message to |v:errors| if it does + NOT produce a beep or visual bell. + Also see |assert_fails()|. + *assert_equal()* assert_equal({expected}, {actual}, [, {msg}]) When {expected} and {actual} are not equal an error message is @@ -2511,6 +2522,8 @@ assert_fails({cmd} [, {error} [, {msg}]]) *assert_fails()* Run {cmd} and add an error message to |v:errors| if it does NOT produce an error. When {error} is given it must match in |v:errmsg|. + Note that beeping is not considered an error, and some failing + commands only beep. Use |assert_beeps()| for those. assert_false({actual} [, {msg}]) *assert_false()* When {actual} is not false an error message is added to @@ -4542,6 +4555,41 @@ gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* To obtain all window-local variables use: > gettabwinvar({tabnr}, {winnr}, '&') +gettagstack([{nr}]) *gettagstack()* + The result is a Dict, which is the tag stack of window {nr}. + {nr} can be the window number or the |window-ID|. + When {nr} is not specified, the current window is used. + When window {nr} doesn't exist, an empty Dict is returned. + + The returned dictionary contains the following entries: + curidx Current index in the stack. When at + top of the stack, set to (length + 1). + Index of bottom of the stack is 1. + items List of items in the stack. Each item + is a dictionary containing the + entries described below. + length Number of entries in the stack. + + Each item in the stack is a dictionary with the following + entries: + bufnr buffer number of the current jump + from cursor position before the tag jump. + See |getpos()| for the format of the + returned list. + matchnr current matching tag number. Used when + multiple matching tags are found for a + name. + tagname name of the tag + + See |tagstack| for more information about the tag stack. + +getwinpos([{timeout}]) *getwinpos()* + The result is a list with two numbers, the result of + getwinposx() and getwinposy() combined: + [x-pos, y-pos] + {timeout} can be used to specify how long to wait in msec for + a response from the terminal. When omitted 100 msec is used. + *getwinposx()* getwinposx() The result is a Number, which is the X coordinate in pixels of the left hand side of the GUI Vim window. The result will be @@ -4674,8 +4722,8 @@ has({feature}) Returns 1 if {feature} is supported, 0 otherwise. The {feature} argument is a feature name like "nvim-0.2.1" or "win32", see below. See also |exists()|. - Vim's compile-time feature names (prefixed with "+") are not - supported because Nvim is always compiled with ALL possible + Vim's compile-time feature-names (prefixed with "+") are not + recognized because Nvim is always compiled with all possible features. |feature-compile| Feature names can be: @@ -4704,14 +4752,12 @@ has({feature}) Returns 1 if {feature} is supported, 0 otherwise. The wsl WSL (Windows Subsystem for Linux) system *has-patch* - 3. Vim patches. The "patch123" feature means that Vim patch - 123 has been included. This does not check the Vim - version, you could check |v:version| for that. - Example: > + 3. Vim patch. For example the "patch123" feature means that + Vim patch 123 at the current |v:version| was included: > :if v:version > 602 || v:version == 602 && has("patch148") -< 5. Vim version. For example the "patch-7.4.237" feature means - that the Vim version is 7.4.237 or later. > +< 4. Vim version. For example the "patch-7.4.237" feature means + that Nvim is Vim-compatible to version 7.4.237 or later. > :if has("patch-7.4.237") @@ -7018,6 +7064,8 @@ setqflist({list} [, {action}[, {what}]]) *setqflist()* buffer filename name of a file; only used when "bufnr" is not present or it is invalid. + module name of a module; if given it will be used in + quickfix error window instead of the filename lnum line number in the file pattern search pattern used to locate the error col column number @@ -7062,9 +7110,6 @@ setqflist({list} [, {action}[, {what}]]) *setqflist()* freed. To add a new quickfix list at the end of the stack, set "nr" in {what} to "$". - If {title} is given, it will be used to set |w:quickfix_title| - after opening the quickfix window. - If the optional {what} dictionary argument is supplied, then only the items listed in {what} are set. The first {list} argument is ignored. The following items can be specified in @@ -7175,6 +7220,38 @@ settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()* :call settabwinvar(3, 2, "myvar", "foobar") < This function is not available in the |sandbox|. +settagstack({nr}, {dict} [, {action}]) *settagstack()* + Modify the tag stack of the window {nr} using {dict}. + {nr} can be the window number or the |window-ID|. + + For a list of supported items in {dict}, refer to + |gettagstack()| + *E962* + If {action} is not present or is set to 'r', then the tag + stack is replaced. If {action} is set to 'a', then new entries + from {dict} are pushed onto the tag stack. + + Returns zero for success, -1 for failure. + + Examples: + Set current index of the tag stack to 4: > + call settagstack(1005, {'curidx' : 4}) + +< Empty the tag stack of window 3: > + call settagstack(3, {'items' : []}) + +< Push a new item onto the tag stack: > + let pos = [bufnr('myfile.txt'), 10, 1, 0] + let newtag = [{'tagname' : 'mytag', 'from' : pos}] + call settagstack(2, {'items' : newtag}, 'a') + +< Save and restore the tag stack: > + let stack = gettagstack(1003) + " do something else + call settagstack(1003, stack) + unlet stack +< + setwinvar({nr}, {varname}, {val}) *setwinvar()* Like |settabwinvar()| for the current tab page. Examples: > @@ -7745,6 +7822,31 @@ substitute({expr}, {pat}, {sub}, {flags}) *substitute()* |submatch()| returns. Example: > :echo substitute(s, '\(\x\x\)', {m -> '0x' . m[1]}, 'g') +swapinfo({fname}) *swapinfo()* + The result is a dictionary, which holds information about the + swapfile {fname}. The available fields are: + version VIM version + user user name + host host name + fname original file name + pid PID of the VIM process that created the swap + file + mtime last modification time in seconds + inode Optional: INODE number of the file + dirty 1 if file was modified, 0 if not + In case of failure an "error" item is added with the reason: + Cannot open file: file not found or in accessible + Cannot read file: cannot read first block + Not a swap file: does not contain correct block ID + Magic number mismatch: Info in first block is invalid + +swapname({expr}) *swapname()* + The result is the swap file path of the buffer {expr}. + For the use of {expr}, see |bufname()| above. + If buffer {expr} is the current buffer, the result is equal to + |:swapname| (unless no swap file). + If buffer {expr} has no swap file, returns an empty string. + synID({lnum}, {col}, {trans}) *synID()* The result is a Number, which is the syntax ID at the position {lnum} and {col} in the current window. @@ -7867,7 +7969,7 @@ system({cmd} [, {input}]) *system()* *E677* items converted to NULs). When {input} is given and is a valid buffer id, the content of the buffer is written to the file line by line, each line - terminated by a NL (and NUL where the text has NL). + terminated by NL (and NUL where the text has NL). *E5677* Note: system() cannot write to or read from backgrounded ("&") shell commands, e.g.: > @@ -7884,7 +7986,7 @@ system({cmd} [, {input}]) *system()* *E677* The characters in 'shellquote' and 'shellxquote' may also cause trouble. - The result is a String. Example: > + Result is a String. Example: > :let files = system("ls " . shellescape(expand('%:h'))) :let files = system('ls ' . expand('%:h:S')) diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt index 1d2cca3073..1fb06e169c 100644 --- a/runtime/doc/intro.txt +++ b/runtime/doc/intro.txt @@ -58,7 +58,7 @@ For more information try one of these: ============================================================================== Nvim on the interwebs *internet* - *www* *WWW* *faq* *FAQ* *distribution* *download* + *www* *faq* *distribution* *download* Nvim home page: https://neovim.io/ Nvim FAQ: https://github.com/neovim/neovim/wiki/FAQ @@ -67,9 +67,10 @@ Nvim on the interwebs *internet* Vim home page: https://www.vim.org/ -Bug reports: *bugs* *bug-reports* *bugreport.vim* + *bugs* *bug-report* *bugreport.vim* *feature-request* -Report bugs on GitHub: https://github.com/neovim/neovim/issues +Report bugs and request features here: +https://github.com/neovim/neovim/issues Be brief, yet complete. Always give a reproducible example and try to find out which settings or other things trigger the bug. diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 862aa7b750..91a4a3c267 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -114,17 +114,18 @@ You can also embed an Nvim instance via |jobstart()|, and communicate using ============================================================================== 4. Implementing API clients *rpc-api-client* *api-client* -"API clients" wrap the Nvim API to provide idiomatic "SDKs" for their -respective platforms (see |dev-jargon|). You can build a new API client for -your favorite platform or programming language. +API clients wrap the Nvim API to provide idiomatic "SDKs" for their respective +platforms (see |jargon|). You can build a new API client for your favorite +platform or programming language. -Existing API clients are listed here: +API clients are listed here: https://github.com/neovim/neovim/wiki/Related-projects#api-clients + *pynvim* The Python client is the reference implementation for API clients. It is always up-to-date with the Nvim API, so its source code and test suite are authoritative references. - https://github.com/neovim/python-client + https://github.com/neovim/pynvim API client implementation guidelines ~ diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt index af94c60629..cfaec12520 100644 --- a/runtime/doc/nvim_terminal_emulator.txt +++ b/runtime/doc/nvim_terminal_emulator.txt @@ -7,8 +7,8 @@ Terminal emulator *terminal* *terminal-emulator* Nvim embeds a VT220/xterm terminal emulator based on libvterm. The terminal is -presented as a special buffer type, asynchronously updated from the virtual -terminal as data is received from the program connected to it. +presented as a special 'buftype', asynchronously updated as data is received +from the connected program. Terminal buffers behave like normal buffers, except: - With 'modifiable', lines can be edited but not deleted. @@ -23,11 +23,11 @@ Terminal buffers behave like normal buffers, except: ============================================================================== Start *terminal-start* -There are 3 ways to create a terminal buffer: +There are several ways to create a terminal buffer: -- By invoking the |:terminal| ex command. -- By calling the |termopen()| function. -- By editing a file with a name matching `term://(.{-}//(\d+:)?)?\zs.*`. +- Invoke the |:terminal| command. +- Call the |termopen()| function. +- Edit a file with a name matching `term://(.{-}//(\d+:)?)?\zs.*`. For example: > :edit term://bash @@ -98,14 +98,21 @@ global configuration. - 'wrap' is disabled You can change the defaults with a TermOpen autocommand: > - au TermOpen * setlocal list + au TermOpen * setlocal list TERMINAL COLORS ~ -The `{g,b}:terminal_color_$NUM` variables control the terminal color palette, -where `$NUM` is the color index between 0 and 255 inclusive. This setting only -affects UIs with RGB capabilities; for normal terminals the color index is -just forwarded. The variables are read only during |TermOpen|. +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: > + let g:terminal_color_4 = '#ff0000' + let g:terminal_color_5 = 'green' +Only works for RGB UIs (see 'termguicolors'); for 256-color terminals the +color index is just forwarded. + +Editor highlighting (|syntax-highlighting|, |highlight-groups|, etc.) has +higher precedence: it is applied after terminal colors are resolved. ============================================================================== Status Variables *terminal-status* diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 171fff8547..cce9f681f9 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -4528,10 +4528,14 @@ A jump table for the options with a short description can be found at |Q_op|. 'redrawtime' 'rdt' number (default 2000) global Time in milliseconds for redrawing the display. Applies to - 'hlsearch', 'inccommand' and |:match| highlighting. + 'hlsearch', 'inccommand', |:match| highlighting and syntax + highlighting. When redrawing takes more than this many milliseconds no further - matches will be highlighted. This is used to avoid that Vim hangs - when using a very complicated pattern. + matches will be highlighted. + For syntax highlighting the time applies per window. When over the + limit syntax highlighting is disabled until |CTRL-L| is used. + This is used to avoid that Vim hangs when using a very complicated + pattern. *'regexpengine'* *'re'* 'regexpengine' 're' number (default 0) @@ -4659,12 +4663,11 @@ A jump table for the options with a short description can be found at |Q_op|. :set rulerformat=%15(%c%V\ %p%%%) < *'runtimepath'* *'rtp'* *vimfiles* -'runtimepath' 'rtp' string (default: - Unix: "$XDG_CONFIG_HOME/nvim, +'runtimepath' 'rtp' string (default: "$XDG_CONFIG_HOME/nvim, $XDG_CONFIG_DIRS[1]/nvim, $XDG_CONFIG_DIRS[2]/nvim, … - $XDG_DATA_HOME/nvim/site, + $XDG_DATA_HOME/nvim[-data]/site, $XDG_DATA_DIRS[1]/nvim/site, $XDG_DATA_DIRS[2]/nvim/site, … @@ -4672,14 +4675,13 @@ A jump table for the options with a short description can be found at |Q_op|. … $XDG_DATA_DIRS[2]/nvim/site/after, $XDG_DATA_DIRS[1]/nvim/site/after, - $XDG_DATA_HOME/nvim/site/after, + $XDG_DATA_HOME/nvim[-data]/site/after, … $XDG_CONFIG_DIRS[2]/nvim/after, $XDG_CONFIG_DIRS[1]/nvim/after, $XDG_CONFIG_HOME/nvim/after") global - This is a list of directories which will be searched for runtime - files: + List of directories to be searched for these runtime files: filetype.vim filetypes by file name |new-filetype| scripts.vim filetypes by file contents |new-filetype-scripts| autoload/ automatically loaded scripts |autoload-functions| @@ -4701,19 +4703,20 @@ A jump table for the options with a short description can be found at |Q_op|. And any other file searched for with the |:runtime| command. - The defaults for most systems are setup to search these locations: - 1. In your home directory (XDG_CONFIG_HOME defaults to $HOME/.config), - for your personal preferences. - 2. In directories which must contain configuration files according to - XDG ($XDG_CONFIG_DIRS). This also contains preferences from system - administrator (XDG_CONFIG_DIRS defaults to /etc/xdg). - 3. In data home directory, for plugins installed by user. - 4. In nvim/site subdirectories for each directory in $XDG_DATA_DIRS. - This is for plugins which were installed by system administrator, - but are not part of the Neovim distribution. XDG_DATA_DIRS defaults - to /usr/local/share/:/usr/share/, so system administrators are + Defaults are setup to search these locations: + 1. Your home directory, for personal preferences. + Given by `stdpath("config")`. |$XDG_CONFIG_HOME| + 2. Directories which must contain configuration files according to + |xdg| ($XDG_CONFIG_DIRS, defaults to /etc/xdg). This also contains + preferences from system administrator. + 3. Data home directory, for plugins installed by user. + Given by `stdpath("data")`. |$XDG_DATA_HOME| + 4. nvim/site subdirectories for each directory in $XDG_DATA_DIRS. + This is for plugins which were installed by system administrator, + but are not part of the Nvim distribution. XDG_DATA_DIRS defaults + to /usr/local/share/:/usr/share/, so system administrators are expected to install site plugins to /usr/share/nvim/site. - 5. In $VIMRUNTIME, for files distributed with Neovim. + 5. $VIMRUNTIME, for files distributed with Neovim. *after-directory* 6, 7, 8, 9. In after/ subdirectories of 1, 2, 3 and 4, with reverse ordering. This is for preferences to overrule or add to the @@ -5045,7 +5048,7 @@ A jump table for the options with a short description can be found at |Q_op|. security reasons. *'shadafile'* *'sdf'* -'shadafile' 'vif' string (default: "") +'shadafile' 'sdf' string (default: "") global When non-empty, overrides the file name used for |shada| (viminfo). When equal to "NONE" no shada file will be read or written. @@ -6128,9 +6131,9 @@ A jump table for the options with a short description can be found at |Q_op|. *'termguicolors'* *'tgc'* 'termguicolors' 'tgc' boolean (default off) global - When on, uses |highlight-guifg| and |highlight-guibg| attributes in - the terminal (thus using 24-bit color). Requires a ISO-8613-3 - compatible terminal. + Enables 24-bit RGB color in the |TUI|. Uses "gui" |:highlight| + attributes instead of "cterm" attributes. |highlight-guifg| + Requires an ISO-8613-3 compatible terminal. *'terse'* *'noterse'* 'terse' boolean (default off) @@ -6159,9 +6162,7 @@ A jump table for the options with a short description can be found at |Q_op|. the file should contain words with similar meaning, separated by non-keyword characters (white space is preferred). Maximum line length is 510 bytes. - To obtain a file to be used here, check out this ftp site: - [Sorry this link doesn't work anymore, do you know the right one?] - ftp://ftp.ox.ac.uk/pub/wordlists/ First get the README file. + To include a comma in a file name precede it with a backslash. Spaces after a comma are ignored, otherwise spaces are included in the file name. See |option-backslash| about using backslashes. diff --git a/runtime/doc/quickfix.txt b/runtime/doc/quickfix.txt index 7aa81f612b..d20a91dc2d 100644 --- a/runtime/doc/quickfix.txt +++ b/runtime/doc/quickfix.txt @@ -1204,6 +1204,7 @@ you want to match case, add "\C" to the pattern |/\C|. Basic items %f file name (finds a string) + %o module name (finds a string) %l line number (finds a number) %c column number (finds a number representing character column of the error, (1 <tab> == 1 character column)) @@ -1248,6 +1249,11 @@ conversion can be used to locate lines without a line number in the error output. Like the output of the "grep" shell command. When the pattern is present the line number will not be used. +The "%o" conversion specifies the module name in quickfix entry. If present +it will be used in quickfix error window instead of the filename. The module +name is used only for displaying purposes, the file name is used when jumping +to the file. + Changing directory The following uppercase conversion characters specify the type of special diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt index 23ae3458ea..0a552a1309 100644 --- a/runtime/doc/repeat.txt +++ b/runtime/doc/repeat.txt @@ -432,6 +432,16 @@ flag when defining the function, it is not relevant when executing it. > . :endfunction :set cpo-=C +< + *line-continuation-comment* +To add a comment in between the lines start with '\" '. Notice the space +after the double quote. Example: > + let array = [ + "\ first entry comment + \ 'first', + "\ second entry comment + \ 'second', + \ ] Rationale: Most programs work with a trailing backslash to indicate line @@ -440,6 +450,14 @@ Rationale: :map xx asdf\ < Therefore the unusual leading backslash is used. + Starting a comment in a continuation line results in all following + continuation lines to be part of the comment. Since it was like this + for a long time, when making it possible to add a comment halfway a + sequence of continuation lines, it was not possible to use \", since + that was a valid continuation line. Using '"\ ' comes closest, even + though it may look a bit weird. Requiring the space after the + backslash is to make it very unlikely this is a normal comment line. + ============================================================================== 5. Using Vim packages *packages* diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index a8ba64fda8..2a230d9449 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -195,34 +195,33 @@ argument. -E Start Nvim in Ex mode |gQ|. If stdin is not a TTY: - -e reads stdin as Ex commands. + -e reads/executes stdin as Ex commands. -E reads stdin as text (into buffer 1). - *-es* *-Es* --es *-s-ex* *silent-mode* --Es Silent or batch mode: execute Ex commands from a file instead - of a terminal. Special case of |-s| (which takes an argument - while "-es" doesn't). Disables most prompts, messages, - warnings and errors. - Output of these commands is displayed (to stdout): +-es *-es* *-Es* *-s-ex* *silent-mode* +-Es Silent or batch mode. Special case of |-s| (which takes an + argument while "-es" doesn't). Disables most prompts, + messages, warnings and errors. + + -es reads/executes stdin as Ex commands. > + printf "put ='foo'\n%%print\n" | nvim -es + +< -Es reads stdin as text (into buffer 1). Use |-c| or "+" to + send commands. > + printf "foo\n" | nvim -Es +"%print" + +< Output of these commands is displayed (to stdout): :print :list :number - :set to display option values. - When 'verbose' is set messages are printed to stderr, e.g.: > + :set (to display option values) + When 'verbose' is set messages are printed to stderr. > echo foo | nvim -V1 -es -< - User |init.vim| is skipped (unless given with |-u|). - Swap file is skipped (like |-n|). - |$TERM| is not used. - If stdin is not a TTY: - -es reads stdin as Ex commands. - -Es reads stdin as text (into buffer 1). +< User |init.vim| is skipped (unless given with |-u|). + Swap file is skipped (like |-n|). + User |shada| is loaded (unless "-i NONE" is given). - Example: > - printf "put ='foo'\n%%print\n" | nvim -es -< *-b* -b Binary mode. File I/O will only recognize <NL> to separate lines. The 'expandtab' option will be reset. The 'textwidth' @@ -355,35 +354,33 @@ argument. --embed Use stdin/stdout as a msgpack-RPC channel, so applications can embed and control Nvim via the |rpc-api|. - By default nvim will wait for the embedding process to call - `nvim_ui_attach` before sourcing startup files and reading - buffers. This is so that UI can show startup messages and - possible swap file dialog for the first loaded file. The - process can do requests before the `nvim_ui_attach`, for - instance a `nvim_get_api_info` call so that UI features can be - safely detected by the UI before attaching. - - See |ui-startup| for more information about UI startup. - - To embed nvim without using the UI protocol, `--headless` should - be supplied together with `--embed`. Then initialization is - performed without waiting for an UI. This is also equivalent - to the following alternative: > - nvim --headless --cmd "call stdioopen({'rpc': v:true})" -< - See also |channel-stdio|. + Waits for the client ("embedder") to call |nvim_ui_attach()| + before sourcing startup files and reading buffers, so that UIs + can deterministically handle (display) early messages, + dialogs, etc. The client can do other requests before + `nvim_ui_attach` (e.g. `nvim_get_api_info` for feature-detection). + During this pre-startup phase the user config is of course not + available (similar to `--cmd`). + + Embedders _not_ using the UI protocol must pass |--headless|: > + nvim --embed --headless + +< Then startup will continue without waiting for `nvim_ui_attach`. + This is equivalent to: > + nvim --headless --cmd "call stdioopen({'rpc': v:true})" + +< See also: |ui-startup| |channel-stdio| *--headless* ---headless Start nvim without an UI. The TUI is not used, so stdio - can be used as an arbitrary communication channel. - |channel-stdio| When used together with `--embed`, do not wait - for the embedder to attach an UI. +--headless Start without UI, and do not wait for `nvim_ui_attach`. The + builtin TUI is not used, so stdio works as an arbitrary + communication channel. |channel-stdio| Also useful for scripting (tests) to see messages that would not be printed by |-es|. To detect if a UI is available, check if |nvim_list_uis()| is - empty in or after |VimEnter|. + empty during or after |VimEnter|. To read stdin as text, "-" must be given explicitly: --headless cannot assume that stdin is just text. > @@ -1084,15 +1081,16 @@ even if other entries (with known name/type/etc) are merged. |shada-merging| SHADA FILE NAME *shada-file-name* -- The default name of the ShaDa file is "$XDG_DATA_HOME/nvim/shada/main.shada" - for Unix. Default for $XDG_DATA_HOME is ~/.local/share. |base-directories| -- The 'n' flag in the 'shada' option can be used to specify another ShaDa - file name |'shada'|. -- The "-i" Vim argument can be used to set another file name, |-i|. When the - file name given is "NONE" (all uppercase), no ShaDa file is ever read or - written. Also not for the commands below! -- The 'viminfofile' option can be used like the "-i" argument. In fact, the - value form the "-i" argument is stored in the 'viminfofile' option. +- Default name of the |shada| file is: + Unix: "$XDG_DATA_HOME/nvim/shada/main.shada" + Windows: "$XDG_DATA_HOME/nvim-data/shada/main.shada" + See also |base-directories|. +- To choose a different file name you can use: + - The "n" flag in the 'shada' option. + - The |-i| startup argument. "NONE" means no shada file is ever read or + written. Also not for the commands below! + - The 'shadafile' option. The value from the "-i" argument (if any) is + stored in the 'shadafile' option. - For the commands below, another file name can be given, overriding the default and the name given with 'shada' or "-i" (unless it's NONE). diff --git a/runtime/doc/tagsrch.txt b/runtime/doc/tagsrch.txt index 08abcf2594..a4526a7f2c 100644 --- a/runtime/doc/tagsrch.txt +++ b/runtime/doc/tagsrch.txt @@ -173,6 +173,9 @@ commands explained above the tag stack will look like this: 1 1 main 1 harddisk2:text/vim/test 2 1 FuncB 59 harddisk2:text/vim/src/main.c +The gettagstack() function returns the tag stack of a specified window. The +settagstack() function modifies the tag stack of a window. + *E73* When you try to use the tag stack while it doesn't contain anything you will get an error message. diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt index 98476ea8fa..60d55bda61 100644 --- a/runtime/doc/ui.txt +++ b/runtime/doc/ui.txt @@ -11,70 +11,98 @@ Nvim UI protocol *ui* ============================================================================== UI Events *ui-events* -GUIs can be implemented as external processes communicating with Nvim over the -RPC API. The default UI model consists of a terminal-like grid with a single, -monospace font size. The UI can opt-in to have windows drawn on separate -grids, as well as to have some elements (UI "widgets") be drawn by the UI -itself rather than by nvim ("externalized"). - - - *ui-options* -The |nvim_ui_attach()| API method is used to tell Nvim that your program wants to -draw the Nvim screen grid with a size of width × height cells. This is typically -done by an embedder, see |ui-startup| below for details, but an UI can also -connect to a running nvim instance and invoke this method. `options` must be -a dictionary with these (optional) keys: - `rgb` Decides the color format. *ui-rgb* - Set true (default) for 24-bit RGB colors. - Set false for terminal colors (max of 256). - *ui-ext-options* - `ext_popupmenu` Externalize the popupmenu. |ui-popupmenu| - `ext_tabline` Externalize the tabline. |ui-tabline| +UIs can be implemented as external client processes communicating with Nvim +over the RPC API. The default UI model is a terminal-like grid with a single, +monospace font. The UI can opt-in to have windows drawn on separate grids, and +have some elements ("widgets") presented by the UI itself rather than by Nvim +("externalized"). + + *ui-option* +Call |nvim_ui_attach()| to tell Nvim that your program wants to draw the Nvim +screen grid with a size of width × height cells. This is typically done by an +embedder at startup (see |ui-startup|), but UIs can also connect to a running +Nvim instance and invoke nvim_ui_attach(). The `options` parameter is a map +with these (optional) keys: + *ui-rgb* + `rgb` Decides the color format. + true: (default) 24-bit RGB colors + false: Terminal colors (8-bit, max 256) + *ui-override* + `override` Decides how UI capabilities are resolved. + true: Enable requested UI capabilities, even + if not supported by all connected UIs + (including |TUI|). + false: (default) Disable UI capabilities not + supported by all connected UIs + (including TUI). + *ui-ext-options* `ext_cmdline` Externalize the cmdline. |ui-cmdline| - `ext_wildmenu` Externalize the wildmenu (deprecated). |ui-wildmenu| + `ext_hlstate` Detailed highlight state. |ui-hlstate| + Sets `ext_linegrid` implicitly. + `ext_linegrid` Line-based grid events. |ui-linegrid| + Deactivates |ui-grid-old| implicitly. `ext_messages` Externalize messages. |ui-messages| - `ext_linegrid` Use new revision of the grid events. |ui-linegrid| - `ext_multigrid` Use per-window grid based events. |ui-multigrid| - `ext_hlstate` Use detailed highlight state. |ui-hlstate| + Sets `ext_linegrid` and `ext_cmdline` implicitly. + `ext_multigrid` Per-window grid events. |ui-multigrid| + Sets `ext_linegrid` implicitly. + `ext_popupmenu` Externalize |popupmenu-completion| and + 'wildmenu'. |ui-popupmenu| + `ext_tabline` Externalize the tabline. |ui-tabline| `ext_termcolors` Use external default colors. -Specifying a non-existent option is an error. UIs can check the |api-metadata| -`ui_options` key for supported options. Additionally Nvim (currently) requires -that all connected UIs use the same set of widgets. Therefore the active -widgets will be the intersection of the requested widget sets of all connected -UIs. The "option_set" event announces which widgets actually are active. - -Nvim sends msgpack-rpc notifications to all attached UIs, with method name -"redraw" and a single argument: an array (batch) of screen "update events". -Each update event is itself an array whose first element is the event name and -remaining elements are event-parameter tuples. This allows multiple events of -the same kind to be sent in a row without the event name being repeated. This -batching is mostly used for "grid_line", because each "grid_line" event puts -contents in one grid line, but clients must be prepared for multiple argument -sets being batched for all event kinds. - -Events must be handled in-order. A "flush" event is sent when nvim is done -redrawing the entire screen (so that all windows have a consistent view of -buffer state, options etc). Clients should be prepared that several "redraw" -batches are sent before the entire screen has been redrawn, and only the last -batch will end in "flush". The user should only see the final state when -"flush" is sent, and not any intermediate state after processing only part of -the batch array, nor after a batch not ending with "flush". - -By default, Nvim sends |ui-global| and |ui-grid-old| events; these suffice to -implement a terminal-like interface. However there are two revisions of the -grid part of the protocol. The newer revision |ui-linegrid|, enabled by -`ext_linegrid` option, has a more effecient representation of text (especially -highlighted text), and allows extensions that use multiple grids. - -The older revision is available and used by default only for backwards -compatibility reasons. New UIs are strongly recommended to use |ui-linegrid|, -as further protocol extensions require it. The |ui-multigrid| extension -enables |ui-linegrid| implicitly. - -Nvim optionally sends screen elements "semantically" as structured events -instead of raw grid-lines, controlled by |ui-ext-options|. The UI must present -those elements itself; Nvim will not draw those elements on the grid. +Specifying an unknown option is an error; UIs can check the |api-metadata| +`ui_options` key for supported options. + +By default Nvim requires all connected UIs to support the same capabilities, +thus the active capabilities are the intersection of those requested. UIs may +specify |ui-override| to invert this behavior (useful for debugging). The +"option_set" event announces which capabilities are active. + +Nvim sends RPC notifications to all attached UIs, with method name "redraw" +and a single argument: an array (batch) of screen "update events". Each update +event is itself an array whose first element is the event name and remaining +elements are event-parameter tuples. Thus multiple events of the same kind can +be sent contiguously without repeating the event name. + +Example of a typical "redraw" batch in a single RPC notification: > + + ['notification', 'redraw', + [ + ['grid_resize', [2, 77, 36]], + ['grid_line', + [2, 0, 0, [[' ' , 0, 77]]], + [2, 1, 0, [['~', 7], [' ', 7, 76]]], + [2, 9, 0, [['~', 7], [' ', 7, 76]]], + ... + [2, 35, 0, [['~', 7], [' ', 7, 76]]], + [1, 36, 0, [['[', 9], ['N'], ['o'], [' '], ['N'], ['a'], ['m'], ['e'], [']']]], + [1, 36, 9, [[' ', 9, 50]]], + [1, 36, 59, [['0', 9], [','], ['0'], ['-' ], ['1'], [' ', 9, 10], ['A'], ['l', 9, 2]]] + ], + ['msg_showmode', [[]]], + ['win_pos', [2, 1000, 0, 0, 77, 36]], + ['grid_cursor_goto', [2, 0, 0]], + ['flush', []] + ] + ] + +Events must be handled in-order. Nvim sends a "flush" event when it has +completed a redraw of the entire screen (so all windows have a consistent view +of buffer state, options, etc.). Multiple "redraw" batches may be sent before +the entire screen has been redrawn, with "flush" following only the last +batch. The user should only see the final state (when "flush" is sent), not +any intermediate state while processing part of the batch array, nor after +a batch not ending with "flush". + +By default, Nvim sends |ui-global| and |ui-grid-old| events (for backwards +compatibility); these suffice to implement a terminal-like interface. However +the new |ui-linegrid| represents text more efficiently (especially highlighted +text), and allows UI capabilities requiring multiple grids. New UIs should +implement |ui-linegrid| instead of |ui-grid-old|. + +Nvim optionally sends various screen elements "semantically" as structured +events instead of raw grid-lines, as specified by |ui-ext-options|. The UI +must present such elements itself, Nvim will not draw them on the grid. Future versions of Nvim may add new update kinds and may append new parameters to existing update kinds. Clients must be prepared to ignore such extensions, @@ -83,40 +111,36 @@ for forward-compatibility. |api-contract| ============================================================================== UI startup *ui-startup* -Nvim defines a standard procedure for how an embedding UI should interact with -the startup phase of Nvim. When spawning the nvim process, use the |--embed| flag -but not the |--headless| flag. The started Nvim process will pause before loading -startup files and reading buffers, and give the UI a chance to invoke requests -to do early initialization. As soon as the UI invokes |nvim_ui_attach()|, the -startup will continue. +UI embedders (clients that start Nvim with |--embed| and later call +|nvim_ui_attach()|) must start Nvim without |--headless|: > + 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 +continue as soon as the UI invokes |nvim_ui_attach()|. -A simple UI only need to do a single |nvim_ui_attach()| request and then -be prepared to handle any UI event. A more featureful UI, which might need -additional configuration of the nvim process, should use the following startup +A simple UI only needs to do a single |nvim_ui_attach()| request and then +prepare to handle any UI event. A more featureful UI, which might need +additional configuration of the Nvim process, should use the following startup procedure: -1. Invoke |nvim_get_api_info()|, if this is needed to setup the client library - and/or to get the list of supported UI extensions. -2. At this time, any configuration that should be happen before init.vim - loading should be done. Buffers and windows are not available at this - point, but this could be used to set |g:| variables visible to init.vim -3. If the UI wants to do additional setup after the init.vim file was loaded - register an autocmd for VimEnter at this point: > - - nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')") - -<4. Now invoke |nvim_ui_attach()|. The UI will need to handle keyboard input - at this point, as sourcing init.vim and loading buffers might lead to - blocking prompts. -5. If step 3 was used, nvim will send a blocking "vimenter" request to the - UI. Inside this request handler, the UI can safely do any initialization - before entering normal mode, for instance reading variables set by - init.vim. +1. Invoke |nvim_get_api_info()|, if needed to setup the client library and/or + to get the list of supported UI extensions. +2. Do any configuration that should be happen before user config is loaded. + Buffers and windows are not available at this point, but this could be used + 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: > + nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')") +<4. Now invoke |nvim_ui_attach()|. The UI must handle user input by now: + sourcing init.vim and loading buffers might lead to blocking prompts. +5. If step 3 was used, Nvim will send a blocking "vimenter" request to the UI. + Inside this request handler, the UI can safely do any initialization before + entering normal mode, for example reading variables set by init.vim. ============================================================================== Global Events *ui-global* -The following events will always be available, and describe global state of +The following UI events are always emitted, and describe global state of the editor. ["set_title", title] @@ -189,7 +213,7 @@ the editor. ["mouse_off"] Tells the client whether mouse support, as determined by |'mouse'| option, is considered to be active in the current mode. This is mostly - useful for a terminal frontend, or other situations where nvim mouse + useful for a terminal frontend, or other situations where Nvim mouse would conflict with other usages of the mouse. It is safe for a client to ignore this and always send mouse events. @@ -218,20 +242,20 @@ the editor. ============================================================================== Grid Events (line-based) *ui-linegrid* -These events are used if `ext_linegrid` option is set (recommended for all new -UIs). The biggest change compared to previous revision is to use a single -event `grid_line` to update the contents of a screen line (where the old -protocol used a combination of cursor, highlight and text events) +Activated by the `ext_linegrid` |ui-option|. Recommended for all new UIs. +Deactivates |ui-grid-old| implicitly. + +The biggest change compared to |ui-grid-old| is to use a single `grid_line` +event to update the contents of a screen line (whereas the old protocol used +a combination of cursor, highlight and text events) Most of these events take a `grid` index as first parameter. Grid 1 is the -global grid used by default for the entire editor screen state. Grids other -than that will be defined by future extensions. Just activating the -`ext_linegrid` option by itself will never cause any additional grids to be -created. To enable per-window grids, `ext_multigrid` option should be set (see -|ui-multigrid|). +global grid used by default for the entire editor screen state. The +`ext_linegrid` capability by itself will never cause any additional grids to +be created; to enable per-window grids, activate |ui-multigrid|. Highlight attribute groups are predefined. UIs should maintain a table to map -numerical highlight `id`:s to the actual attributes. +numerical highlight ids to the actual attributes. ["grid_resize", grid, width, height] Resize a `grid`. If `grid` wasn't seen by the client before, a new grid is @@ -242,16 +266,16 @@ numerical highlight `id`:s to the actual attributes. special colors respectively. `cterm_fg` and `cterm_bg` specifies the default color codes to use in a 256-color terminal. - The rgb values will always be valid colors, by default. If no + The RGB values will always be valid colors, by default. If no colors have been set, they will default to black and white, depending on 'background'. By setting the `ext_termcolors` option, instead - -1 will be used for unset colors. This is mostly useful for a - TUI implementation, where using the terminal emulators builitn - defaults are expected. + -1 will be used for unset colors. This is mostly useful for a TUI + implementation, where using the terminal builtin ("ANSI") defaults + are expected. - Note: unlike the corresponding events in the first revision, the - screen is not always cleared after sending this event. The GUI has to - repaint the screen with changed background color itself. + Note: Unlike the corresponding |ui-grid-old| events, the screen is not + always cleared after sending this event. The UI must repaint the + screen with changed background color itself. *ui-event-hl_attr_define* ["hl_attr_define", id, rgb_attr, cterm_attr, info] @@ -275,7 +299,7 @@ numerical highlight `id`:s to the actual attributes. All boolean keys default to false, and will only be sent when they are true. - Highlights are always transmitted both for both the rgb format and as + Highlights are always transmitted both for both the RGB format and as terminal 256-color codes, as the `rgb_attr` and `cterm_attr` parameters respectively. The |ui-rgb| option has no effect effect anymore. Most external UIs will only need to store and use the `rgb_attr` @@ -284,17 +308,17 @@ numerical highlight `id`:s to the actual attributes. `id` 0 will always be used for the default highlight with colors defined by `default_colors_set` and no styles applied. - Note: `id`:s can be reused if Nvim's internal highlight table is full. - In this case, Nvim will always issue redraws of screen cells that are - affected by redefined `id`:s, so UIs do not need to keep track of this + Note: Nvim may reuse `id` values if its internal highlight table is full. + In that case Nvim will always issue redraws of screen cells that are + affected by redefined ids, so UIs do not need to keep track of this themselves. - `info` is an empty array per default, and will be used by the - |ui-hlstate| extension explaned below. + `info` is an empty array by default, and will be used by the + |ui-hlstate| extension explained below. *ui-event-grid_line* ["grid_line", grid, row, col_start, cells] - Redraw a continous part of a `row` on a `grid`, starting at the column + Redraw a continuous part of a `row` on a `grid`, starting at the column `col_start`. `cells` is an array of arrays each with 1 to 3 items: `[text(, hl_id, repeat)]` . `text` is the UTF-8 text that should be put in a cell, with the highlight `hl_id` defined by a previous `hl_attr_define` @@ -372,10 +396,10 @@ numerical highlight `id`:s to the actual attributes. part of handling the scroll event. ============================================================================== -Legacy Grid Events (cell based) *ui-grid-old* +Grid Events (cell-based) *ui-grid-old* -This is an older representation of the screen grid, used if `ext_linegrid` -option is not set. New UIs should use |ui-linegrid|. +This is the legacy representation of the screen grid, emitted if |ui-linegrid| +is not active. New UIs should implement |ui-linegrid| instead. ["resize", width, height] The grid is resized to `width` and `height` cells. @@ -407,7 +431,7 @@ option is not set. New UIs should use |ui-linegrid|. updates. All boolean keys default to false. `foreground`: foreground color. - `background`: backround color. + `background`: background color. `special`: color to use for underline and undercurl, when present. `reverse`: reverse video. Foreground and background colors are switched. @@ -462,13 +486,13 @@ option is not set. New UIs should use |ui-linegrid|. ============================================================================== Detailed highlight state Extension *ui-hlstate* -Only sent if `ext_hlstate` option is set in |ui-options|. `ext_hlstate` implies -`ext_linegrid`. +Activated by the `ext_hlstate` |ui-option|. +Activates |ui-linegrid| implicitly. -By default, nvim will only describe grid cells using the final calculated -higlight attributes, as described by the dict keys in |ui-event-highlight_set|. +By default Nvim will only describe grid cells using the final calculated +highlight attributes, as described by the dict keys in |ui-event-highlight_set|. The `ext_hlstate` extension allows to the UI to also receive a semantic -describtion of the higlights active in a cell. In this mode highlights will be +description of the highlights active in a cell. In this mode highlights will be predefined in a table, see |ui-event-hl_attr_define| and |ui-event-grid_line|. The `info` parameter in `hl_attr_define` will contain a semantic description of the highlights. As highlight groups can be combined, this will be an array @@ -476,14 +500,13 @@ of items, with the item with highest priority last. Each item is a dictionary with the following possible keys: `kind`: always present. One of the following values: - "ui": A builtin ui highlight. - "syntax": highlight applied to a buffer by a syntax declaration or - other runtime/plugin functionallity such as + "ui": Builtin UI highlight. |highlight-groups| + "syntax": Highlight applied to a buffer by a syntax declaration or + other runtime/plugin functionality such as |nvim_buf_add_highlight()| "terminal": highlight from a process running in a |terminal-emulator|. - Contains no futher semantic information. - `ui_name`: Name of the builtin highlight. See |highlight-groups| for - possible values. Only present for "ui". + Contains no further semantic information. + `ui_name`: Highlight name from |highlight-groups|. Only for "ui" kind. `hi_name`: Name of the final |:highlight| group where the used attributes are defined. `id`: Unique numeric id representing this item. @@ -497,30 +520,32 @@ screen elements, even if no attributes have been applied. ============================================================================== Multigrid Events *ui-multigrid* -Only sent if `ext_multigrid` option is set in |ui-options|. Enables the -`ext_linegrid` extension implicitly. +Activated by the `ext_multigrid` |ui-option|. +Activates |ui-linegrid| implicitly. -The multigrid extension gives the UIs more control over how windows are -displayed. The UIs receive updates on a separate grid for each window. The UIs -can set the grid size independently of how much space the window occupies on -the global layout. This enables the UIs to set a different font size for each -window if the UI so desires. The UI can also reserve space around the border -of the window for its own elements, for instance scrollbars from the UI -toolkit. - -By default, the grid size is handled by nvim and set to the outer grid size -(i.e. the size of the window frame in nvim) whenever the split is created. -Once a UI sets a grid size, nvim does not handle the size for that grid and +See |ui-linegrid| for grid events. +See |nvim_ui_try_resize_grid()| to request changing the grid size. +See |nvim_input_mouse()| for sending mouse events to Nvim. + +The multigrid extension gives UIs more control over how windows are displayed: +- UIs receive updates on a separate grid for each window. +- UIs can set the grid size independently of how much space the window + occupies on the global layout. So the UI could use a different font size + per-window. Or reserve space around the border of the window for its own + elements, such as scrollbars from the UI toolkit. + +By default, the grid size is handled by Nvim and set to the outer grid size +(i.e. the size of the window frame in Nvim) whenever the split is created. +Once a UI sets a grid size, Nvim does not handle the size for that grid and the UI must change the grid size whenever the outer size is changed. To -delegate the handling of grid size back to nvim, the UIs should request the -size (0, 0). +delegate grid-size handling back to Nvim, request the size (0, 0). A window can be hidden and redisplayed without its grid being deallocated. This can happen multiple times for the same window, for instance when switching tabs. ["win_pos", grid, win, start_row, start_col, width, height] - Set the position and size of the grid in nvim (i.e. the outer grid + Set the position and size of the grid in Nvim (i.e. the outer grid size). If the window was previously hidden, it should now be shown again. @@ -532,7 +557,7 @@ tabs. ["win_external_pos", grid, win] Display or reconfigure external window `win`. The window should be - displayed as a separate top-level window in the desktop envirionment, + displayed as a separate top-level window in the desktop environment, or something similar. ["win_hide", grid] @@ -551,14 +576,13 @@ tabs. ["win_close", grid] Close the window. -See |ui-linegrid| for grid events. -See |nvim_ui_try_resize_grid| in |api-ui| to request changing the grid size. -See |nvim_input_mouse| for sending mouse events to Nvim. - ============================================================================== Popupmenu Events *ui-popupmenu* -Only sent if `ext_popupmenu` option is set in |ui-options|. +Activated by the `ext_popupmenu` |ui-option|. + +This UI extension delegates presentation of the |popupmenu-completion| and +command-line 'wildmenu'. ["popupmenu_show", items, selected, row, col, grid] Show |popupmenu-completion|. `items` is an array of completion items @@ -583,7 +607,7 @@ Only sent if `ext_popupmenu` option is set in |ui-options|. ============================================================================== Tabline Events *ui-tabline* -Only sent if `ext_tabline` option is set in |ui-options| +Activated by the `ext_tabline` |ui-option|. ["tabline_update", curtab, tabs] Tabline was updated. UIs should present this data in a custom tabline @@ -594,10 +618,10 @@ Only sent if `ext_tabline` option is set in |ui-options| ============================================================================== Cmdline Events *ui-cmdline* -Only sent if `ext_cmdline` option is set in |ui-options|. To handle -command-line completion (wildmenu), use |ui-popupmenu| events activated by -|ext_popupmenu| option. (The `ext_wildmenu` option only exists for backwards -compatibility). +Activated by the `ext_cmdline` |ui-option|. + +This UI extension delegates presentation of the |cmdline| (except 'wildmenu'). +For command-line 'wildmenu' UI events, activate |ui-popupmenu|. ["cmdline_show", content, pos, firstc, prompt, indent, level] content: List of [attrs, string] @@ -653,47 +677,49 @@ compatibility). Hide the block. ============================================================================== -Message Events *ui-messages* +Message/Dialog Events *ui-messages* -Only sent if `ext_messages` option is set in |ui-options|. This option implies -`ext_linegrid` and `ext_cmdline` also being set. |ui-linegrid| and |ui-cmdline| events -will thus also be sent. +Activated by the `ext_messages` |ui-option|. +Activates |ui-linegrid| and |ui-cmdline| implicitly. -This extension allows the UI to control the display of messages that otherwise -would have been displayed in the message/cmdline area in the bottom of the -screen. +This UI extension delegates presentation of messages and dialogs. Messages +that would otherwise render in the message/cmdline screen space, are emitted +as UI events. -Activating this extension means that Nvim will allocate no screen space for -the cmdline or messages, and 'cmdheight' will be set to zero. Attempting to -change 'cmdheight' will silently be ignored. |ui-cmdline| events will be used -to represent the state of the cmdline. +Nvim will not allocate screen space for the cmdline or messages, and +'cmdheight' will be forced zero. Cmdline state is emitted as |ui-cmdline| +events, which the UI must handle. ["msg_show", kind, content, replace_last] Display a message to the user. - `kind` will be one of the following - `emsg`: Internal error message - `echo`: temporary message from plugin (|:echo|) - `echomsg`: ordinary message from plugin (|:echomsg|) - `echoerr`: error message from plugin (|:echoerr|) - `return_prompt`: |press-enter| prompt after a group of messages - `quickfix`: Quickfix navigation message - `kind` can also be the empty string. The message is then some internal - informative or warning message, that hasn't yet been assigned a kind. - New message kinds can be added in later versions; clients should - handle messages of an unknown kind just like empty kind. - - `content` will be an array of `[attr_id, text_chunk]` tuples, - building up the message text of chunks of different highlights. - No extra spacing should be added between chunks, the `text_chunk` by - itself should contain any necessary whitespace. Messages can contain - line breaks `"\n"`. - - `replace_last` controls how multiple messages should be displayed. - If `replace_last` is false, this message should be displayed together - with all previous messages that are still visible. If `replace_last` - is true, this message should replace the message in the most recent - `msg_show` call, but any other visible message should still remain. + kind + Name indicating the message kind: + "" (empty) Unknown, report a |feature-request| + "confirm" |confirm()| or |:confirm| dialog + "confirm_sub" |:substitute| confirm dialog |:s_c| + "emsg" Error (|errors|, internal error, |:throw|, …) + "echo" |:echo| message + "echomsg" |:echomsg| message + "echoerr" |:echoerr| message + "return_prompt" |press-enter| prompt after a multiple messages + "quickfix" Quickfix navigation message + "wmsg" Warning ("search hit BOTTOM", |W10|, …) + New kinds may be added in the future; clients should treat unknown + kinds as the empty kind. + + content + Array of `[attr_id, text_chunk]` tuples, building up the message + text of chunks of different highlights. No extra spacing should be + added between chunks, the `text_chunk` by itself contains any + necessary whitespace. Messages can contain line breaks "\n". + + replace_last + Decides how multiple messages should be displayed: + false: Display the message together with all previous messages + that are still visible. + true: Replace the message in the most-recent `msg_show` call, + but any other visible message should still remain. ["msg_clear"] Clear all messages currently displayed by "msg_show". (Messages sent diff --git a/runtime/doc/usr_11.txt b/runtime/doc/usr_11.txt index e5591ac1d1..42b564e962 100644 --- a/runtime/doc/usr_11.txt +++ b/runtime/doc/usr_11.txt @@ -205,6 +205,13 @@ something wrong. It may be one of these two situations. NEWER than swap file! ~ +NOTE that in the following situation Vim knows the swap file is not useful and +will automatically delete it: +- The file is a valid swap file (Magic number is correct). +- The flag that the file was modified is not set. +- The process is not running. + + UNREADABLE SWAP FILE Sometimes the line diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt index 32923f6b25..53bdb5e8fe 100644 --- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -957,6 +957,8 @@ Various: *various-functions* taglist() get list of matching tags tagfiles() get a list of tags files + gettagstack() get the tag stack + settagstack() modify the tag stack luaeval() evaluate Lua expression py3eval() evaluate Python expression (|+python3|) diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt index 6f809af387..a0b2846b2b 100644 --- a/runtime/doc/various.txt +++ b/runtime/doc/various.txt @@ -235,35 +235,32 @@ g8 Print the hex values of the bytes used in the *:!cmd* *:!* *E34* :!{cmd} Execute {cmd} with 'shell'. See also |:terminal|. - Any '!' in {cmd} is replaced with the previous - external command (see also 'cpoptions'). But not when - there is a backslash before the '!', then that - backslash is removed. Example: ":!ls" followed by + The command runs in a non-interactive shell connected + to a pipe (not a terminal). Use |:terminal| to run an + interactive shell connected to a terminal. + + Backgrounded ("&") commands must not write to stdout + or stderr, the streams are closed immediately. |E5677| + Use |jobstart()| instead. > + :call jobstart('foo', {'detach':1}) +< + Any "!" in {cmd} is replaced with the previous + external command (see also 'cpoptions'), unless + escaped by a backslash. Example: ":!ls" followed by ":!echo ! \! \\!" executes "echo ls ! \!". - A '|' in {cmd} is passed to the shell, you cannot use - it to append a Vim command. See |:bar|. + Any "|" in {cmd} is passed to the shell, you cannot + use it to append a Vim command. See |:bar|. - If {cmd} contains "%" it is expanded to the current - file name. Special characters are not escaped, use - quotes to avoid their special meaning: > + Any "%" in {cmd} is expanded to the current file name. + Special characters are not escaped, use quotes or + |shellescape()|: > :!ls "%" -< If the file name contains a "$" single quotes might - work better (but a single quote causes trouble): > - :!ls '%' -< This should always work, but it's more typing: > :exe "!ls " . shellescape(expand("%")) < - A newline character ends {cmd}, what follows is - interpreted as a following ":" command. However, if - there is a backslash before the newline it is removed - and {cmd} continues. It doesn't matter how many - backslashes are before the newline, only one is - removed. - - The command runs in a non-interactive shell connected - to a pipe (not a terminal). Use |:terminal| to run an - interactive shell connected to a terminal. + Newline character ends {cmd} unless a backslash + precedes the newline. What follows is interpreted as + another |:| command. After the command has been executed, the timestamp and size of the current file is checked |timestamp|. @@ -273,15 +270,9 @@ g8 Print the hex values of the bytes used in the data is lost, this only affects the display. The last few lines are always displayed (never skipped). - Vim redraws the screen after the command is finished, - because it may have printed any text. This requires a - hit-enter prompt, so that you can read any messages. - To avoid this use: > + To avoid the hit-enter prompt use: > :silent !{cmd} -< The screen is not redrawn then, thus you have to use - CTRL-L or ":redraw!" if the command did display - something. - +< *:!!* :!! Repeat last ":!{cmd}". @@ -289,10 +280,6 @@ g8 Print the hex values of the bytes used in the :ve[rsion] Print editor version and build information. See also |feature-compile|. -:ve[rsion] {nr} Ignored. Previously used to check the version number - of a .vimrc file. You can now use the ":if" command - for version-dependent behavior. - *:redi* *:redir* :redi[r][!] > {file} Redirect messages to file {file}. The messages which are the output of commands are written to that file, diff --git a/runtime/filetype.vim b/runtime/filetype.vim index 1a08f5675f..a670f54898 100644 --- a/runtime/filetype.vim +++ b/runtime/filetype.vim @@ -707,8 +707,8 @@ au BufNewFile,BufRead *.erb,*.rhtml setf eruby " HTML with M4 au BufNewFile,BufRead *.html.m4 setf htmlm4 -" HTML Cheetah template -au BufNewFile,BufRead *.tmpl setf htmlcheetah +" Some template. Used to be HTML Cheetah. +au BufNewFile,BufRead *.tmpl setf template " Host config au BufNewFile,BufRead */etc/host.conf setf hostconf @@ -1694,6 +1694,9 @@ au BufNewFile,BufReadPost *.tutor setf tutor " TWIG files au BufNewFile,BufReadPost *.twig setf twig +" Typescript +au BufNewFile,BufReadPost *.ts setf typescript + " Motif UIT/UIL files au BufNewFile,BufRead *.uit,*.uil setf uil diff --git a/runtime/indent/vim.vim b/runtime/indent/vim.vim index 8ebfa12caf..cd735c3a3c 100644 --- a/runtime/indent/vim.vim +++ b/runtime/indent/vim.vim @@ -10,7 +10,7 @@ endif let b:did_indent = 1 setlocal indentexpr=GetVimIndent() -setlocal indentkeys+==end,=else,=cat,=fina,=END,0\\ +setlocal indentkeys+==end,=else,=cat,=fina,=END,0\\,0=\"\\\ let b:undo_indent = "setl indentkeys< indentexpr<" @@ -31,15 +31,17 @@ function GetVimIndent() endtry endfunc +let s:lineContPat = '^\s*\(\\\|"\\ \)' + function GetVimIndentIntern() " Find a non-blank line above the current line. let lnum = prevnonblank(v:lnum - 1) - " If the current line doesn't start with '\' and below a line that starts - " with '\', use the indent of the line above it. + " If the current line doesn't start with '\' or '"\ ' and below a line that + " starts with '\' or '"\ ', use the indent of the line above it. let cur_text = getline(v:lnum) - if cur_text !~ '^\s*\\' - while lnum > 0 && getline(lnum) =~ '^\s*\\' + if cur_text !~ s:lineContPat + while lnum > 0 && getline(lnum) =~ s:lineContPat let lnum = lnum - 1 endwhile endif @@ -51,10 +53,10 @@ function GetVimIndentIntern() let prev_text = getline(lnum) " Add a 'shiftwidth' after :if, :while, :try, :catch, :finally, :function - " and :else. Add it three times for a line that starts with '\' after - " a line that doesn't (or g:vim_indent_cont if it exists). + " and :else. Add it three times for a line that starts with '\' or '"\ ' + " after a line that doesn't (or g:vim_indent_cont if it exists). let ind = indent(lnum) - if cur_text =~ '^\s*\\' && v:lnum > 1 && prev_text !~ '^\s*\\' + if cur_text =~ s:lineContPat && v:lnum > 1 && prev_text !~ s:lineContPat if exists("g:vim_indent_cont") let ind = ind + g:vim_indent_cont else diff --git a/runtime/nvim.appdata.xml b/runtime/nvim.appdata.xml index 095e6c6fa8..fb409ff0b8 100644 --- a/runtime/nvim.appdata.xml +++ b/runtime/nvim.appdata.xml @@ -8,6 +8,7 @@ --> <component type="desktop-application"> <id>nvim</id> + <translation type="gettext">nvim</translation> <project_license>Apache-2.0</project_license> <metadata_license>CC0-1.0</metadata_license> <name>Neovim</name> @@ -24,6 +25,16 @@ </screenshot> </screenshots> + <releases> + <release date="2019-04-29" version="0.3.5"/> + <release date="2019-01-13" version="0.3.4"/> + <release date="2019-01-05" version="0.3.3"/> + <release date="2018-12-31" version="0.3.2"/> + <release date="2018-07-19" version="0.3.1"/> + <release date="2018-07-11" version="0.3.0"/> + </releases> + + <content_rating type="oars-1.1"/> <launchable type="desktop-id">nvim.desktop</launchable> <url type="homepage">https://neovim.io/</url> <url type="bugtracker">https://github.com/neovim/neovim/issues</url> diff --git a/runtime/pack/dist/opt/termdebug/plugin/termdebug.vim b/runtime/pack/dist/opt/termdebug/plugin/termdebug.vim index 506179297a..78b1ae8ce8 100644 --- a/runtime/pack/dist/opt/termdebug/plugin/termdebug.vim +++ b/runtime/pack/dist/opt/termdebug/plugin/termdebug.vim @@ -25,32 +25,44 @@ endif command -nargs=* -complete=file Termdebug call s:StartDebug(<q-args>) " Name of the gdb command, defaults to "gdb". -if !exists('debugger') - let debugger = 'gdb' +if !exists('termdebugger') + let termdebugger = 'gdb' endif -" Sign used to highlight the line where the program has stopped. -sign define debugPC linehl=debugPC +let s:pc_id = 12 +let s:break_id = 13 + if &background == 'light' - hi debugPC term=reverse ctermbg=lightblue guibg=lightblue + hi default debugPC term=reverse ctermbg=lightblue guibg=lightblue else - hi debugPC term=reverse ctermbg=darkblue guibg=darkblue + hi default debugPC term=reverse ctermbg=darkblue guibg=darkblue endif -let s:pc_id = 12 +hi default debugBreakpoint term=reverse ctermbg=red guibg=red func s:StartDebug(cmd) let s:startwin = win_getid(winnr()) let s:startsigncolumn = &signcolumn + if exists('g:termdebug_wide') && &columns < g:termdebug_wide + let s:save_columns = &columns + let &columns = g:termdebug_wide + let vertical = 1 + else + let s:save_columns = 0 + let vertical = 0 + endif + " Open a terminal window without a job, to run the debugged program let s:ptybuf = term_start('NONE', { \ 'term_name': 'gdb program', + \ 'vertical': vertical, \ }) if s:ptybuf == 0 echoerr 'Failed to open the program terminal window' return endif let pty = job_info(term_getjob(s:ptybuf))['tty_out'] + let s:ptywin = win_getid(winnr()) " Create a hidden terminal window to communicate with gdb let s:commbuf = term_start('NONE', { @@ -66,7 +78,7 @@ func s:StartDebug(cmd) let commpty = job_info(term_getjob(s:commbuf))['tty_out'] " Open a terminal window to run the debugger. - let cmd = [g:debugger, '-tty', pty, a:cmd] + let cmd = [g:termdebugger, '-tty', pty, a:cmd] echomsg 'executing "' . join(cmd) . '"' let gdbbuf = term_start(cmd, { \ 'exit_cb': function('s:EndDebug'), @@ -78,15 +90,41 @@ func s:StartDebug(cmd) exe 'bwipe! ' . s:commbuf return endif + let s:gdbwin = win_getid(winnr()) " Connect gdb to the communication pty, using the GDB/MI interface call term_sendkeys(gdbbuf, 'new-ui mi ' . commpty . "\r") + + " Sign used to highlight the line where the program has stopped. + " There can be only one. + sign define debugPC linehl=debugPC + + " Sign used to indicate a breakpoint. + " Can be used multiple times. + sign define debugBreakpoint text=>> texthl=debugBreakpoint + + " Install debugger commands in the text window. + call win_gotoid(s:startwin) + call s:InstallCommands() + call win_gotoid(s:gdbwin) + + let s:breakpoints = {} endfunc func s:EndDebug(job, status) exe 'bwipe! ' . s:ptybuf exe 'bwipe! ' . s:commbuf - call setwinvar(s:startwin, '&signcolumn', s:startsigncolumn) + + let curwinid = win_getid(winnr()) + + call win_gotoid(s:startwin) + let &signcolumn = s:startsigncolumn + call s:DeleteCommands() + + call win_gotoid(curwinid) + if s:save_columns > 0 + let &columns = s:save_columns + endif endfunc " Handle a message received from gdb on the GDB/MI interface. @@ -100,34 +138,175 @@ func s:CommOutput(chan, msg) endif if msg != '' if msg =~ '^\*\(stopped\|running\)' - let wid = win_getid(winnr()) - - if win_gotoid(s:startwin) - if msg =~ '^\*stopped' - " TODO: proper parsing - let fname = substitute(msg, '.*fullname="\([^"]*\)".*', '\1', '') - let lnum = substitute(msg, '.*line="\([^"]*\)".*', '\1', '') - if lnum =~ '^[0-9]*$' - if expand('%:h') != fname - if &modified - " TODO: find existing window - exe 'split ' . fnameescape(fname) - let s:startwin = win_getid(winnr()) - else - exe 'edit ' . fnameescape(fname) - endif - endif - exe lnum - exe 'sign place ' . s:pc_id . ' line=' . lnum . ' name=debugPC file=' . fnameescape(fname) - setlocal signcolumn=yes - endif + call s:HandleCursor(msg) + elseif msg =~ '^\^done,bkpt=' || msg =~ '^=breakpoint-created,' + call s:HandleNewBreakpoint(msg) + elseif msg =~ '^=breakpoint-deleted,' + call s:HandleBreakpointDelete(msg) + elseif msg =~ '^\^done,value=' + call s:HandleEvaluate(msg) + elseif msg =~ '^\^error,msg=' + call s:HandleError(msg) + endif + endif + endfor +endfunc + +" Install commands in the current window to control the debugger. +func s:InstallCommands() + command Break call s:SetBreakpoint() + command Delete call s:DeleteBreakpoint() + command Step call s:SendCommand('-exec-step') + command Over call s:SendCommand('-exec-next') + command Finish call s:SendCommand('-exec-finish') + command Continue call s:SendCommand('-exec-continue') + command -range -nargs=* Evaluate call s:Evaluate(<range>, <q-args>) + command Gdb call win_gotoid(s:gdbwin) + command Program call win_gotoid(s:ptywin) + + " TODO: can the K mapping be restored? + nnoremap K :Evaluate<CR> +endfunc + +" Delete installed debugger commands in the current window. +func s:DeleteCommands() + delcommand Break + delcommand Delete + delcommand Step + delcommand Over + delcommand Finish + delcommand Continue + delcommand Evaluate + delcommand Gdb + delcommand Program + + nunmap K + exe 'sign unplace ' . s:pc_id + for key in keys(s:breakpoints) + exe 'sign unplace ' . (s:break_id + key) + endfor + sign undefine debugPC + sign undefine debugBreakpoint + unlet s:breakpoints +endfunc + +" :Break - Set a breakpoint at the cursor position. +func s:SetBreakpoint() + call term_sendkeys(s:commbuf, '-break-insert --source ' + \ . fnameescape(expand('%:p')) . ' --line ' . line('.') . "\r") +endfunc + +" :Delete - Delete a breakpoint at the cursor position. +func s:DeleteBreakpoint() + let fname = fnameescape(expand('%:p')) + let lnum = line('.') + for [key, val] in items(s:breakpoints) + if val['fname'] == fname && val['lnum'] == lnum + call term_sendkeys(s:commbuf, '-break-delete ' . key . "\r") + " Assume this always wors, the reply is simply "^done". + exe 'sign unplace ' . (s:break_id + key) + unlet s:breakpoints[key] + break + endif + endfor +endfunc + +" :Next, :Continue, etc - send a command to gdb +func s:SendCommand(cmd) + call term_sendkeys(s:commbuf, a:cmd . "\r") +endfunc + +" :Evaluate - evaluate what is under the cursor +func s:Evaluate(range, arg) + if a:arg != '' + let expr = a:arg + elseif a:range == 2 + let pos = getcurpos() + let reg = getreg('v', 1, 1) + let regt = getregtype('v') + normal! gv"vy + let expr = @v + call setpos('.', pos) + call setreg('v', reg, regt) + else + let expr = expand('<cexpr>') + endif + call term_sendkeys(s:commbuf, '-data-evaluate-expression "' . expr . "\"\r") + let s:evalexpr = expr +endfunc + +" Handle the result of data-evaluate-expression +func s:HandleEvaluate(msg) + echomsg '"' . s:evalexpr . '": ' . substitute(a:msg, '.*value="\(.*\)"', '\1', '') +endfunc + +" Handle an error. +func s:HandleError(msg) + echoerr substitute(a:msg, '.*msg="\(.*\)"', '\1', '') +endfunc + +" Handle stopping and running message from gdb. +" Will update the sign that shows the current position. +func s:HandleCursor(msg) + let wid = win_getid(winnr()) + + if win_gotoid(s:startwin) + let fname = substitute(a:msg, '.*fullname="\([^"]*\)".*', '\1', '') + if a:msg =~ '^\*stopped' && filereadable(fname) + let lnum = substitute(a:msg, '.*line="\([^"]*\)".*', '\1', '') + if lnum =~ '^[0-9]*$' + if expand('%:h') != fname + if &modified + " TODO: find existing window + exe 'split ' . fnameescape(fname) + let s:startwin = win_getid(winnr()) else - exe 'sign unplace ' . s:pc_id + exe 'edit ' . fnameescape(fname) endif - - call win_gotoid(wid) endif + exe lnum + exe 'sign place ' . s:pc_id . ' line=' . lnum . ' name=debugPC file=' . fnameescape(fname) + setlocal signcolumn=yes endif + else + exe 'sign unplace ' . s:pc_id endif - endfor + + call win_gotoid(wid) + endif +endfunc + +" Handle setting a breakpoint +" Will update the sign that shows the breakpoint +func s:HandleNewBreakpoint(msg) + let nr = substitute(a:msg, '.*number="\([0-9]\)*\".*', '\1', '') + 0 + if nr == 0 + return + endif + + if has_key(s:breakpoints, nr) + let entry = s:breakpoints[nr] + else + let entry = {} + let s:breakpoints[nr] = entry + endif + + let fname = substitute(a:msg, '.*fullname="\([^"]*\)".*', '\1', '') + let lnum = substitute(a:msg, '.*line="\([^"]*\)".*', '\1', '') + + exe 'sign place ' . (s:break_id + nr) . ' line=' . lnum . ' name=debugBreakpoint file=' . fnameescape(fname) + + let entry['fname'] = fname + let entry['lnum'] = lnum +endfunc + +" Handle deleting a breakpoint +" Will remove the sign that shows the breakpoint +func s:HandleBreakpointDelete(msg) + let nr = substitute(a:msg, '.*id="\([0-9]*\)\".*', '\1', '') + 0 + if nr == 0 + return + endif + exe 'sign unplace ' . (s:break_id + nr) + unlet s:breakpoints[nr] endfunc diff --git a/runtime/syntax/tutor.vim b/runtime/syntax/tutor.vim index cb101ee9a7..6305eef734 100644 --- a/runtime/syntax/tutor.vim +++ b/runtime/syntax/tutor.vim @@ -49,29 +49,29 @@ syn match tutorInlineType /{\(normal\|vim\)}/ contained conceal syn match tutorInlineOK /✓/ syn match tutorInlineX /✗/ -hi! tutorLink cterm=underline gui=underline ctermfg=lightblue guifg=#0088ff -hi! link tutorLinkBands Delimiter -hi! link tutorLinkAnchor Underlined -hi! link tutorInternalAnchor Underlined -hi! link tutorURL tutorLink -hi! link tutorEmail tutorLink +hi def tutorLink cterm=underline gui=underline ctermfg=lightblue guifg=#0088ff +hi def link tutorLinkBands Delimiter +hi def link tutorLinkAnchor Underlined +hi def link tutorInternalAnchor Underlined +hi def link tutorURL tutorLink +hi def link tutorEmail tutorLink -hi! link tutorSection Title -hi! link tutorSectionBullet Delimiter +hi def link tutorSection Title +hi def link tutorSectionBullet Delimiter -hi! link tutorTOC Directory +hi def link tutorTOC Directory -hi! tutorMarks cterm=bold gui=bold +hi def tutorMarks cterm=bold gui=bold -hi! tutorEmphasis gui=italic cterm=italic -hi! tutorBold gui=bold cterm=bold +hi def tutorEmphasis gui=italic cterm=italic +hi def tutorBold gui=bold cterm=bold -hi! link tutorExpect Special -hi! tutorOK ctermfg=green guifg=#00ff88 cterm=bold gui=bold -hi! tutorX ctermfg=red guifg=#ff2000 cterm=bold gui=bold -hi! link tutorInlineOK tutorOK -hi! link tutorInlineX tutorX +hi def link tutorExpect Special +hi def tutorOK ctermfg=green guifg=#00ff88 cterm=bold gui=bold +hi def tutorX ctermfg=red guifg=#ff2000 cterm=bold gui=bold +hi def link tutorInlineOK tutorOK +hi def link tutorInlineX tutorX -hi! link tutorShellPrompt Delimiter +hi def link tutorShellPrompt Delimiter let b:current_syntax = "tutor" diff --git a/runtime/tutor/en/vim-01-beginner.tutor b/runtime/tutor/en/vim-01-beginner.tutor index 2b30ccb5f8..4e6154b24a 100644 --- a/runtime/tutor/en/vim-01-beginner.tutor +++ b/runtime/tutor/en/vim-01-beginner.tutor @@ -159,9 +159,9 @@ There is also some text missing here. 2. At the shell prompt type this command: ~~~ sh - $ vim tutor + $ nvim tutor ~~~ - 'vim' is the command to start the Vim editor, 'tutor' is the name of + 'nvim' is the command to start the Nvim editor, 'tutor' is the name of the file you wish to edit. Use a file that may be changed. 3. Insert and delete text as you learned in the previous lessons. @@ -186,7 +186,7 @@ There is also some text missing here. 2. To start Vim from the shell prompt type: ~~~ sh - $ vim FILENAME + $ nvim FILENAME ~~~ 3. To exit Vim type: `<Esc>`{normal} `:q!`{vim} `<Enter>`{normal} to trash |