diff options
Diffstat (limited to 'runtime')
50 files changed, 3066 insertions, 1341 deletions
diff --git a/runtime/autoload/dist/ft.vim b/runtime/autoload/dist/ft.vim index 160cdcff64..6ed39cb9f1 100644 --- a/runtime/autoload/dist/ft.vim +++ b/runtime/autoload/dist/ft.vim @@ -1,7 +1,7 @@ " Vim functions for file type detection " " Maintainer: Bram Moolenaar <Bram@vim.org> -" Last Change: 2017 Dec 05 +" Last Change: 2019 Jan 18 " These functions are moved here from runtime/filetype.vim to make startup " faster. @@ -197,7 +197,7 @@ func dist#ft#FTe() exe 'setf ' . g:filetype_euphoria else let n = 1 - while n < 100 && n < line("$") + while n < 100 && n <= line("$") if getline(n) =~ "^\\s*\\(<'\\|'>\\)\\s*$" setf specman return @@ -211,7 +211,7 @@ endfunc " Distinguish between HTML, XHTML and Django func dist#ft#FThtml() let n = 1 - while n < 10 && n < line("$") + while n < 10 && n <= line("$") if getline(n) =~ '\<DTD\s\+XHTML\s' setf xhtml return @@ -222,13 +222,13 @@ func dist#ft#FThtml() endif let n = n + 1 endwhile - setf html + setf FALLBACK html endfunc " Distinguish between standard IDL and MS-IDL func dist#ft#FTidl() let n = 1 - while n < 50 && n < line("$") + while n < 50 && n <= line("$") if getline(n) =~ '^\s*import\s\+"\(unknwn\|objidl\)\.idl"' setf msidl return @@ -484,6 +484,10 @@ endfunc " Called from filetype.vim and scripts.vim. func dist#ft#SetFileTypeSH(name) + if did_filetype() + " Filetype was already detected + return + endif if expand("<amatch>") =~ g:ft_ignore_pat return endif @@ -531,6 +535,10 @@ endfunc " as used for Tcl. " Also called from scripts.vim, thus can't be local to this script. func dist#ft#SetFileTypeShell(name) + if did_filetype() + " Filetype was already detected + return + endif if expand("<amatch>") =~ g:ft_ignore_pat return endif @@ -551,6 +559,10 @@ func dist#ft#SetFileTypeShell(name) endfunc func dist#ft#CSH() + if did_filetype() + " Filetype was already detected + return + endif if exists("g:filetype_csh") call dist#ft#SetFileTypeShell(g:filetype_csh) elseif &shell =~ "tcsh" @@ -687,7 +699,7 @@ endfunc func dist#ft#FTxml() let n = 1 - while n < 100 && n < line("$") + while n < 100 && n <= line("$") let line = getline(n) " DocBook 4 or DocBook 5. let is_docbook4 = line =~ '<!DOCTYPE.*DocBook' @@ -713,7 +725,7 @@ endfunc func dist#ft#FTy() let n = 1 - while n < 100 && n < line("$") + while n < 100 && n <= line("$") let line = getline(n) if line =~ '^\s*%' setf yacc 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/provider/clipboard.vim b/runtime/autoload/provider/clipboard.vim index 2fb9d74d8d..2b06ee8c48 100644 --- a/runtime/autoload/provider/clipboard.vim +++ b/runtime/autoload/provider/clipboard.vim @@ -73,9 +73,9 @@ function! provider#clipboard#Executable() abort let s:cache_enabled = 0 return 'pbcopy' elseif exists('$WAYLAND_DISPLAY') && executable('wl-copy') && executable('wl-paste') - let s:copy['+'] = 'wl-copy --foreground' + let s:copy['+'] = 'wl-copy --foreground --type text/plain' let s:paste['+'] = 'wl-paste --no-newline' - let s:copy['*'] = 'wl-copy --foreground --primary' + let s:copy['*'] = 'wl-copy --foreground --primary --type text/plain' let s:paste['*'] = 'wl-paste --no-newline --primary' return 'wl-copy' elseif exists('$DISPLAY') && executable('xclip') 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 c9d526d9aa..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,15 +222,52 @@ 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) + + +============================================================================== +Floating windows *api-floatwin* + +Nvim supports floating windows, windows that are displayed on top of ordinary +windows. This is useful to implement simple widgets, such as tooltips +displaying information next to cursor text. Floating windows are fully +functional buffer windows and support user editing. They support the standard +|api-window| calls and almost all window options (with some exceptions such as +'statusline' is not supported currently). + +Floating windows are created either by |nvim_open_win()| to open a new window, +or |nvim_win_set_config()| to reconfigure a normal window into a float. +Currently the position can either be grid coordinates relative to the top-left +of some window, or a position relative to the current window cursor. The +parameters for positioning are described in detail at |nvim_open_win()|. + +|nvim_open_win()| assumes an existing buffer to display in the window. To create +a scratch buffer for the float, |nvim_create_buf()| can be used. The text in +the buffer can be highlighted using standard functionality, such as syntax +highlighting, or |api-highlights|. + +By default, floats will use |hl-NormalFloat| as normal highlight, which +links to |hl-Pmenu| in the builtin color scheme. The 'winhighlight' option can +be used to override it. Currently, floating windows don't support any visual +decorations like a border or additional widgets like scrollbar. + +Here is an example for creating a float with scratch buffer: > + + let buf = nvim_create_buf(v:false, v:true) + call nvim_buf_set_lines(buf, 0, -1, v:true, ["test", "text"]) + let opts = {'relative': 'cursor', 'width': 10, 'height': 2, 'col': 0, + \ 'row': 1, 'anchor': 'NW'} + let win = nvim_open_win(buf, 0, opts) + " optional: change highlight, otherwise Pmenu is used + call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight') > +To close the float, |nvim_win_close()| can be used. ============================================================================== Global Functions *api-global* @@ -255,6 +290,9 @@ nvim_get_hl_by_name({name}, {rgb}) *nvim_get_hl_by_name()* Return: ~ Highlight definition map + See also: ~ + nvim_get_hl_by_id + nvim_get_hl_by_id({hl_id}, {rgb}) *nvim_get_hl_by_id()* Gets a highlight definition by id. |hlID()| @@ -265,6 +303,9 @@ nvim_get_hl_by_id({hl_id}, {rgb}) *nvim_get_hl_by_id()* Return: ~ Highlight definition map + See also: ~ + nvim_get_hl_by_name + nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* Sends input-keys to Nvim, subject to various quirks controlled by `mode` flags. This is a blocking call, unlike @@ -278,6 +319,10 @@ nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* {escape_csi} If true, escape K_SPECIAL/CSI bytes in `keys` + See also: ~ + feedkeys() + vim_strsave_escape_csi + nvim_input({keys}) *nvim_input()* Queues raw user-input. Unlike |nvim_feedkeys()|, this uses a low-level input buffer and the call is non-blocking (input is @@ -288,7 +333,6 @@ nvim_input({keys}) *nvim_input()* Note: |keycodes| like <CR> are translated, so "<" is special. To input a literal "<", send <LT>. - Note: For mouse events use |nvim_input_mouse()|. The pseudokey form "<LeftMouse><col,row>" is deprecated since @@ -308,9 +352,8 @@ nvim_input({keys}) *nvim_input()* nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) Send mouse event from GUI. - The call is non-blocking. It doesn't wait on any resulting - action, but queues the event to be processed soon by the event - loop. + Non-blocking: does not wait on any result, but queues the + event to be processed soon by the event loop. Note: Currently this doesn't support "scripting" multiple mouse @@ -354,6 +397,10 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) {special} Replace |keycodes|, e.g. <CR> becomes a "\n" char. + See also: ~ + replace_termcodes + cpoptions + nvim_command_output({command}) *nvim_command_output()* Executes an ex-command and returns its (non-error) output. Shell |:!| output is not captured. @@ -382,7 +429,7 @@ nvim_execute_lua({code}, {args}) *nvim_execute_lua()* inside the chunk. The chunk can return a value. Only statements are executed. To evaluate an expression, - prefix it with `return`: return my_function(...) + prefix it with `return` : return my_function(...) Parameters: ~ {code} lua code to execute @@ -420,7 +467,7 @@ nvim_call_dict_function({dict}, {fn}, {args}) *nvim_call_dict_function()* Result of the function call nvim_strwidth({text}) *nvim_strwidth()* - Calculates the number of display cells occupied by `text`. + Calculates the number of display cells occupied by `text` . <Tab> counts as one cell. Parameters: ~ @@ -444,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 @@ -458,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. @@ -537,11 +580,14 @@ nvim_err_writeln({str}) *nvim_err_writeln()* Parameters: ~ {str} Message + See also: ~ + nvim_err_write() + nvim_list_bufs() *nvim_list_bufs()* Gets the current list of buffer handles - Includes unlisted (unloaded/deleted) buffers, like `:ls!`. Use - |nvim_buf_is_loaded()| to check if a buffer is loaded. + Includes unlisted (unloaded/deleted) buffers, like `:ls!` . + Use |nvim_buf_is_loaded()| to check if a buffer is loaded. Return: ~ List of buffer handles @@ -576,6 +622,93 @@ nvim_set_current_win({window}) *nvim_set_current_win()* Parameters: ~ {window} Window handle +nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* + Creates a new, empty, unnamed buffer. + + Parameters: ~ + {listed} Sets 'buflisted' + {scratch} Creates a "throwaway" |scratch-buffer| for + temporary work (always 'nomodified') + + Return: ~ + Buffer handle, or 0 on error + + See also: ~ + buf_open_scratch + +nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* + Open a new window. + + Currently this is used to open floating and external windows. + Floats are windows that are drawn above the split layout, at + some anchor position in some other window. Floats can be draw + internally or by external GUI with the |ui-multigrid| + extension. External windows are only supported with multigrid + GUIs, and are displayed as separate top-level windows. + + 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 + the bottom-right corner. Floating point values are allowed, + but the builtin implementation (used by TUI and GUIs without + multigrid support) will always round down to nearest integer. + + Out-of-bounds values, and configurations that make the float + not fit inside the main editor, are allowed. The builtin + implementation will truncate values so floats are completely + within the main screen grid. External GUIs could let floats + hover outside of the main window like a tooltip, but this + should not be used to specify arbitrary WM screen positions. + + Parameters: ~ + {buffer} handle of buffer to be displayed in the window + {enter} whether the window should be entered (made the + current window) + {config} Dictionary for the window configuration accepts + these keys: + - `relative` : If set, the window becomes a floating + window. The window will be placed with row,col + coordinates relative to one of the following: + - "editor" the global editor grid + - "win" a window. Use `win` to specify a + window id, or the current window will be + used by default. "cursor" the cursor + position in current window. + + - `win` : When using relative='win', window id + of the window where the position is defined. + - `anchor` : The corner of the float that the row,col + position defines: + - "NW" north-west (default) + - "NE" north-east + - "SW" south-west + - "SE" south-east + + - `height` : window height (in character cells). + Minimum of 1. + - `width` : window width (in character cells). + Minimum of 1. + - `row` : row position. Screen cell height are + used as unit. Can be floating point. + - `col` : column position. Screen cell width is + used as unit. Can be floating point. + - `focusable` : Whether window can be focused by + wincmds and mouse events. Defaults to true. + Even if set to false, the window can still be + entered using |nvim_set_current_win()| API + call. + - `external` : GUI should display the window as + an external top-level window. Currently + accepts no other positioning configuration + together with this. + + Return: ~ + Window handle, or 0 on error + nvim_list_tabpages() *nvim_list_tabpages()* Gets the current list of tabpage handles. @@ -630,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 @@ -656,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. @@ -682,67 +869,87 @@ nvim_get_api_info() *nvim_get_api_info()* *nvim_set_client_info()* nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) - Identify the client for nvim. Can be called more than once, - but subsequent calls will remove earlier info, which should be - resent if it is still valid. (This could happen if a library - first identifies the channel, and a plugin using that library - later overrides that info) - - Parameters: ~ - {name} short name for the connected client - {version} Dictionary describing the version, with the - following possible keys (all optional) - "major" major version (defaults to 0 if not - set, for no release yet) "minor" minor - version "patch" patch number "prerelease" - string describing a prerelease, like "dev" - or "beta1" "commit" hash or similar - identifier of commit - {type} Must be one of the following values. A - client library should use "remote" if the - library user hasn't specified other value. - "remote" remote client that connected to - nvim. "ui" gui frontend "embedder" - application using nvim as a component, for - instance IDE/editor implementing a vim mode. - "host" plugin host, typically started by - nvim "plugin" single plugin, started by - nvim + Identifies the client. Can be called more than once; + subsequent calls remove earlier info, which should be included + by the caller if it is still valid. (E.g. if a library first + identifies the channel, then a plugin using that library later + overrides that info) + + Parameters: ~ + {name} Short name for the connected client + {version} Dictionary describing the version, with + these (optional) keys: + - "major" major version (defaults to 0 if + not set, for no release yet) + - "minor" minor version + - "patch" patch number + - "prerelease" string describing a + prerelease, like "dev" or "beta1" + - "commit" hash or similar identifier of + commit + {type} Must be one of the following values. Client + libraries should default to "remote" unless + overridden by the user. + - "remote" remote client connected to Nvim. + - "ui" gui frontend + - "embedder" application using Nvim as a + component (for example, IDE/editor + implementing a vim mode). + - "host" plugin host, typically started by + nvim + - "plugin" single plugin, started by nvim {methods} Builtin methods in the client. For a host, this does not include plugin methods which will be discovered later. The key should be the method name, the values are dicts with - the following (optional) keys: "async" if - true, send as a notification. If false or - unspecified, use a blocking request "nargs" - Number of arguments. Could be a single - integer or an array two integers, minimum - and maximum inclusive. Further keys might be - added in later versions of nvim and unknown - keys are thus ignored. Clients must only use - keys defined in this or later versions of - nvim! - {attributes} Informal attributes describing the client. - Clients might define their own keys, but the - following are suggested: "website" Website - of client (for instance github repository) - "license" Informal description of the - license, such as "Apache 2", "GPLv3" or - "MIT" "logo" URI or path to image, - preferably small logo or icon. .png or .svg - format is preferred. + these (optional) keys (more keys may be + added in future versions of Nvim, thus + unknown keys are ignored. Clients must only + use keys defined in this or later versions + of Nvim): + - "async" if true, send as a notification. + If false or unspecified, use a blocking + request + - "nargs" Number of arguments. Could be a + single integer or an array of two + integers, minimum and maximum inclusive. + {attributes} Arbitrary string:string map of informal + client properties. Suggested keys: + - "website": Client homepage URL (e.g. + GitHub repository) + - "license": License description ("Apache + 2", "GPLv3", "MIT", …) + - "logo": URI or path to image, preferably + small logo or icon. .png or .svg format is + preferred. nvim_get_chan_info({chan}) *nvim_get_chan_info()* Get information about a channel. Return: ~ - a Dictionary, describing a channel with the following - keys: "stream" the stream underlying the channel - "stdio" stdin and stdout of this Nvim instance "stderr" - stderr of this Nvim instance "socket" TCP/IP socket or - named pipe "job" job with communication over its stdio - - "mode" how data received on the channel is interpreted "bytes" send and recieve raw bytes "terminal" a |terminal| instance interprets ASCII sequences "rpc" |RPC| communication on the channel is active "pty" Name of pseudoterminal, if one is used (optional). On a POSIX system, this will be a device path like /dev/pts/1. Even if the name is unknown, the key will still be present to indicate a pty is used. This is currently the case when using winpty on windows. "buffer" buffer with connected |terminal| instance (optional) "client" information about the client on the other end of the RPC channel, if it has added it using |nvim_set_client_info()|. (optional) + Dictionary describing a channel, with these keys: + - "stream" the stream underlying the channel + - "stdio" stdin and stdout of this Nvim instance + - "stderr" stderr of this Nvim instance + - "socket" TCP/IP socket or named pipe + - "job" job with communication over its stdio + + - "mode" how data received on the channel is interpreted + - "bytes" send and receive raw bytes + - "terminal" a |terminal| instance interprets ASCII + sequences + - "rpc" |RPC| communication on the channel is active + + - "pty" Name of pseudoterminal, if one is used (optional). + On a POSIX system, this will be a device path like + /dev/pts/1. Even if the name is unknown, the key will + still be present to indicate a pty is used. This is + currently the case when using winpty on windows. + - "buffer" buffer with connected |terminal| instance + (optional) + - "client" information about the client on the other end + of the RPC channel, if it has added it using + |nvim_set_client_info()|. (optional) nvim_list_chans() *nvim_list_chans()* Get information about all open channels. @@ -755,7 +962,13 @@ nvim_call_atomic({calls}) *nvim_call_atomic()* Calls many API methods atomically. This has two main usages: - To perform several requests from an async context atomically, i.e. without interleaving redraws, RPC requests from other clients, or user interactions (however API methods may trigger autocommands or event processing which have such side-effects, e.g. |:sleep| may wake timers). To minimize RPC overhead (roundtrips) of a sequence of many requests. + 1. To perform several requests from an async context + atomically, i.e. without interleaving redraws, RPC requests + from other clients, or user interactions (however API + methods may trigger autocommands or event processing which + have such side-effects, e.g. |:sleep| may wake timers). + 2. To minimize RPC overhead (roundtrips) of a sequence of many + requests. Parameters: ~ {calls} an array of calls, where each call is described @@ -763,13 +976,13 @@ nvim_call_atomic({calls}) *nvim_call_atomic()* and an array of arguments. Return: ~ - an array with two elements. The first is an array of - return values. The second is NIL if all calls succeeded. - If a call resulted in an error, it is a three-element - array with the zero-based index of the call which resulted - in an error, the error type and the error message. If an - error occurred, the values from all preceding calls will - still be returned. + Array of two elements. The first is an array of return + values. The second is NIL if all calls succeeded. If a + call resulted in an error, it is a three-element array + with the zero-based index of the call which resulted in an + error, the error type and the error message. If an error + occurred, the values from all preceding calls will still + be returned. *nvim_parse_expression()* nvim_parse_expression({expr}, {flags}, {highlight}) @@ -779,20 +992,24 @@ nvim_parse_expression({expr}, {flags}, {highlight}) {async} Parameters: ~ - {expr} Expression to parse. Is always treated as a + {expr} Expression to parse. Always treated as a single line. - {flags} Flags: - "m" if multiple expressions in a - row are allowed (only the first one will be - parsed), - "E" if EOC tokens are not allowed - (determines whether they will stop parsing - process or be recognized as an - operator/space, though also yielding an - error). - "l" when needing to start parsing - with lvalues for ":let" or ":for". Common - flag sets: - "m" to parse like for ":echo". - - "E" to parse like for "<C-r>=". - empty - string for ":call". - "lm" to parse for - ":let". + {flags} Flags: + - "m" if multiple expressions in a row are + allowed (only the first one will be + parsed), + - "E" if EOC tokens are not allowed + (determines whether they will stop parsing + process or be recognized as an + operator/space, though also yielding an + error). + - "l" when needing to start parsing with + lvalues for ":let" or ":for". Common flag + sets: + - "m" to parse like for ":echo". + - "E" to parse like for "<C-r>=". + - empty string for ":call". + - "lm" to parse for ":let". {highlight} If true, return value will also include "highlight" key containing array of 4-tuples (arrays) (Integer, Integer, Integer, String), @@ -803,51 +1020,66 @@ nvim_parse_expression({expr}, {flags}, {highlight}) [start_col, end_col)). Return: ~ - AST: top-level dictionary with these keys: "error": - Dictionary with error, present only if parser saw some - error. Contains the following keys: "message": String, - error message in printf format, translated. Must contain - exactly one "%.*s". "arg": String, error message argument. - "len": Amount of bytes successfully parsed. With flags - equal to "" that should be equal to the length of expr - string. @note: “Sucessfully parsed” here means - “participated in AST creation”, not “till the first - error”. "ast": AST, either nil or a dictionary with these - keys: "type": node type, one of the value names from - ExprASTNodeType stringified without "kExprNode" prefix. - "start": a pair [line, column] describing where node is - “started” where "line" is always 0 (will not be 0 if you - will be using nvim_parse_viml() on e.g. ":let", but that - is not present yet). Both elements are Integers. "len": - “length” of the node. This and "start" are there for - debugging purposes primary (debugging parser and providing - debug information). "children": a list of nodes described - in top/"ast". There always is zero, one or two children, - key will not be present if node has no children. Maximum - number of children may be found in node_maxchildren array. - Local values (present only for certain nodes): "scope": a - single Integer, specifies scope for "Option" and - "PlainIdentifier" nodes. For "Option" it is one of - ExprOptScope values, for "PlainIdentifier" it is one of - ExprVarScope values. "ident": identifier (without scope, - if any), present for "Option", "PlainIdentifier", - "PlainKey" and "Environment" nodes. "name": Integer, - register name (one character) or -1. Only present for - "Register" nodes. "cmp_type": String, comparison type, one - of the value names from ExprComparisonType, stringified - without "kExprCmp" prefix. Only present for "Comparison" - nodes. "ccs_strategy": String, case comparison strategy, - one of the value names from ExprCaseCompareStrategy, - stringified without "kCCStrategy" prefix. Only present for - "Comparison" nodes. "augmentation": String, augmentation - type for "Assignment" nodes. Is either an empty string, - "Add", "Subtract" or "Concat" for "=", "+=", "-=" or ".=" - respectively. "invert": Boolean, true if result of - comparison needs to be inverted. Only present for - "Comparison" nodes. "ivalue": Integer, integer value for - "Integer" nodes. "fvalue": Float, floating-point value for - "Float" nodes. "svalue": String, value for - "SingleQuotedString" and "DoubleQuotedString" nodes. + + - AST: top-level dictionary with these keys: + - "error": Dictionary with error, present only if parser + saw some error. Contains the following keys: + - "message": String, error message in printf format, + translated. Must contain exactly one "%.*s". + - "arg": String, error message argument. + + - "len": Amount of bytes successfully parsed. With flags + equal to "" that should be equal to the length of expr + string. (“Sucessfully parsed” here means “participated + in AST creation”, not “till the first error”.) + - "ast": AST, either nil or a dictionary with these + keys: + - "type": node type, one of the value names from + ExprASTNodeType stringified without "kExprNode" + prefix. + - "start": a pair [line, column] describing where node + is "started" where "line" is always 0 (will not be 0 + if you will be using nvim_parse_viml() on e.g. + ":let", but that is not present yet). Both elements + are Integers. + - "len": “length” of the node. This and "start" are + there for debugging purposes primary (debugging + parser and providing debug information). + - "children": a list of nodes described in top/"ast". + There always is zero, one or two children, key will + not be present if node has no children. Maximum + number of children may be found in node_maxchildren + array. + + - Local values (present only for certain nodes): + - "scope": a single Integer, specifies scope for + "Option" and "PlainIdentifier" nodes. For "Option" it + is one of ExprOptScope values, for "PlainIdentifier" + it is one of ExprVarScope values. + - "ident": identifier (without scope, if any), present + for "Option", "PlainIdentifier", "PlainKey" and + "Environment" nodes. + - "name": Integer, register name (one character) or -1. + Only present for "Register" nodes. + - "cmp_type": String, comparison type, one of the value + names from ExprComparisonType, stringified without + "kExprCmp" prefix. Only present for "Comparison" + nodes. + - "ccs_strategy": String, case comparison strategy, one + of the value names from ExprCaseCompareStrategy, + stringified without "kCCStrategy" prefix. Only present + for "Comparison" nodes. + - "augmentation": String, augmentation type for + "Assignment" nodes. Is either an empty string, "Add", + "Subtract" or "Concat" for "=", "+=", "-=" or ".=" + respectively. + - "invert": Boolean, true if result of comparison needs + to be inverted. Only present for "Comparison" nodes. + - "ivalue": Integer, integer value for "Integer" nodes. + - "fvalue": Float, floating-point value for "Float" + nodes. + - "svalue": String, value for "SingleQuotedString" and + "DoubleQuotedString" nodes. nvim__id({obj}) *nvim__id()* Returns object given as argument. @@ -907,18 +1139,22 @@ nvim_list_uis() *nvim_list_uis()* Gets a list of dictionaries representing attached UIs. Return: ~ - Array of UI dictionaries - Each dictionary has the following keys: - "height" requested height of the UI "width" requested width of the UI "rgb" whether the UI uses rgb colors (false implies cterm colors) "ext_..." Requested UI extensions, see |ui-options| "chan" Channel id of remote UI (not present for TUI) + Array of UI dictionaries, each with these keys: + - "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-option| + - "chan" Channel id of remote UI (not present for TUI) nvim_get_proc_children({pid}) *nvim_get_proc_children()* - Gets the immediate children of process `pid`. + Gets the immediate children of process `pid` . Return: ~ Array of child process ids, empty if process not found. nvim_get_proc({pid}) *nvim_get_proc()* - Gets info describing process `pid`. + Gets info describing process `pid` . Return: ~ Map of process properties, or NIL if process not found. @@ -940,7 +1176,7 @@ nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts}) {insert} Whether the selection should be inserted in the buffer. {finish} Finish the completion and dismiss the popupmenu. - Implies `insert`. + Implies `insert` . {opts} Optional parameters. Reserved for future use. nvim__inspect_cell({row}, {col}) *nvim__inspect_cell()* @@ -967,20 +1203,20 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()* Gets the buffer line count Parameters: ~ - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer Return: ~ 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} The buffer handle + {buffer} Buffer handle, or 0 for current buffer {send_buffer} Set to true if the initial notification should contain the whole buffer. If so, the first notification will be a - `nvim_buf_lines_event`. Otherwise, the + `nvim_buf_lines_event` . Otherwise, the first notification will be a `nvim_buf_changedtick_event` {opts} Optional parameters. Reserved for future @@ -988,14 +1224,14 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* Return: ~ False when updates couldn't be enabled because the buffer - isn't loaded or optscontained an invalid key; otherwise + isn't loaded or `opts` contained an invalid key; otherwise 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} The buffer handle + {buffer} Buffer handle, or 0 for current buffer Return: ~ False when updates couldn't be disabled because the buffer @@ -1013,7 +1249,7 @@ nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) unless `strict_indexing` is set. Parameters: ~ - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer {start} First line index {end} Last line index (exclusive) {strict_indexing} Whether out-of-bounds should be an @@ -1040,7 +1276,7 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, unless `strict_indexing` is set. Parameters: ~ - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer {start} First line index {end} Last line index (exclusive) {strict_indexing} Whether out-of-bounds should be an @@ -1060,7 +1296,7 @@ nvim_buf_get_offset({buffer}, {index}) *nvim_buf_get_offset()* Returns -1 for unloaded buffer. Parameters: ~ - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer {index} Line index Return: ~ @@ -1070,7 +1306,7 @@ nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()* Gets a buffer-scoped (b:) variable. Parameters: ~ - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer {name} Variable name Return: ~ @@ -1080,27 +1316,46 @@ nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()* Gets a changed tick of a buffer Parameters: ~ - {buffer} Buffer handle. + {buffer} Buffer handle, or 0 for current buffer Return: ~ - b:changedtickvalue. + `b:changedtick` value. nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()* Gets a list of buffer-local |mapping| definitions. Parameters: ~ {mode} Mode short-name ("n", "i", "v", ...) - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer Return: ~ 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|. Parameters: ~ - {buffer} Buffer handle. + {buffer} Buffer handle, or 0 for current buffer {opts} Optional parameters. Currently not used. Return: ~ @@ -1110,7 +1365,7 @@ nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* Sets a buffer-scoped (b:) variable Parameters: ~ - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer {name} Variable name {value} Variable value @@ -1118,14 +1373,14 @@ nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()* Removes a buffer-scoped (b:) variable Parameters: ~ - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer {name} Variable name nvim_buf_get_option({buffer}, {name}) *nvim_buf_get_option()* Gets a buffer option value Parameters: ~ - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer {name} Option name Return: ~ @@ -1136,7 +1391,7 @@ nvim_buf_set_option({buffer}, {name}, {value}) *nvim_buf_set_option()* option (only works if there's a global fallback) Parameters: ~ - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer {name} Option name {value} Option value @@ -1144,7 +1399,7 @@ nvim_buf_get_name({buffer}) *nvim_buf_get_name()* Gets the full file name for the buffer Parameters: ~ - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer Return: ~ Buffer name @@ -1153,7 +1408,7 @@ nvim_buf_set_name({buffer}, {name}) *nvim_buf_set_name()* Sets the full file name for a buffer Parameters: ~ - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer {name} Buffer name nvim_buf_is_loaded({buffer}) *nvim_buf_is_loaded()* @@ -1161,7 +1416,7 @@ nvim_buf_is_loaded({buffer}) *nvim_buf_is_loaded()* more info about unloaded buffers. Parameters: ~ - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer Return: ~ true if the buffer is valid and loaded, false otherwise. @@ -1174,7 +1429,7 @@ nvim_buf_is_valid({buffer}) *nvim_buf_is_valid()* |api-buffer| for more info about unloaded buffers. Parameters: ~ - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer Return: ~ true if the buffer is valid, false otherwise. @@ -1184,7 +1439,7 @@ nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()* named mark Parameters: ~ - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer {name} Mark name Return: ~ @@ -1208,7 +1463,7 @@ nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, `ns_id` to add highlights to the namespace. All highlights in the same namespace can then be cleared with single call to |nvim_buf_clear_namespace|. If the highlight never will be - deleted by an API call, pass `ns_id = -1`. + deleted by an API call, pass `ns_id = -1` . As a shorthand, `ns_id = 0` can be used to create a new namespace for the highlight, the allocated id is then @@ -1218,7 +1473,7 @@ nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, |nvim_create_namespace| to create a new empty namespace. Parameters: ~ - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer {ns_id} namespace to use or -1 for ungrouped highlight {hl_group} Name of the highlight group to use @@ -1240,7 +1495,7 @@ nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end}) to line_start and line_end respectively. Parameters: ~ - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer {ns_id} Namespace to clear, or -1 to clear all namespaces. {line_start} Start of range of lines to clear @@ -1264,14 +1519,14 @@ nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts}) both virtual text and highlights added by |nvim_buf_add_highlight|, both can then be cleared with a single call to |nvim_buf_clear_namespace|. If the virtual text - never will be cleared by an API call, pass `ns_id = -1`. + never will be cleared by an API call, pass `ns_id = -1` . As a shorthand, `ns_id = 0` can be used to create a new namespace for the virtual text, the allocated id is then returned. Parameters: ~ - {buffer} Buffer handle + {buffer} Buffer handle, or 0 for current buffer {ns_id} Namespace to use or 0 to create a namespace, or -1 for a ungrouped annotation {line} Line to annotate with virtual text @@ -1436,6 +1691,50 @@ nvim_win_is_valid({window}) *nvim_win_is_valid()* Return: ~ true if the window is valid, false otherwise +nvim_win_set_config({window}, {config}) *nvim_win_set_config()* + Configure window position. Currently this is only used to + configure floating and external windows (including changing a + split window to these types). + + See documentation at |nvim_open_win()|, for the meaning of + parameters. + + When reconfiguring a floating window, absent option keys will + not be changed. The following restriction apply: `row` , `col` + and `relative` must be reconfigured together. Only changing a + subset of these is an error. + + Parameters: ~ + {window} Window handle + {config} Dictionary of window configuration + +nvim_win_get_config({window}) *nvim_win_get_config()* + Return window configuration. + + Return a dictionary containing the same config that can be + given to |nvim_open_win()|. + + `relative` will be an empty string for normal windows. + + Parameters: ~ + {window} Window handle + + Return: ~ + Window configuration + +nvim_win_close({window}, {force}) *nvim_win_close()* + Close a window. + + This is equivalent to |:close| with count except that it takes + a window id. + + Parameters: ~ + {window} Window handle + {force} Behave like `:close!` The last window of a + buffer with unwritten changes can be closed. The + buffer will become hidden, even if 'hidden' is + not set. + ============================================================================== Tabpage Functions *api-tabpage* @@ -1447,7 +1746,7 @@ nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()* {tabpage} Tabpage Return: ~ - List of windows in tabpage + List of windows in `tabpage` nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()* Gets a tab-scoped (t:) variable @@ -1506,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/autocmd.txt b/runtime/doc/autocmd.txt index 203584e280..4cc1f53cca 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -40,17 +40,17 @@ effects. Be careful not to destroy your text. 2. Defining autocommands *autocmd-define* *:au* *:autocmd* -:au[tocmd] [group] {event} {pat} [once] [nested] {cmd} +:au[tocmd] [group] {event} {pat} [++once] [++nested] {cmd} Add {cmd} to the list of commands that Vim will execute automatically on {event} for a file matching - {pat} |autocmd-patterns|. + {pat} |autocmd-pattern|. Note: A quote character is seen as argument to the :autocmd and won't start a comment. Nvim always adds {cmd} after existing autocommands so they execute in the order in which they were defined. - See |autocmd-nested| for [nested]. + See |autocmd-nested| for [++nested]. *autocmd-once* - If [once] is supplied the command is executed once, + If [++once] is supplied the command is executed once, then removed ("one shot"). The special pattern <buffer> or <buffer=N> defines a buffer-local autocommand. @@ -119,11 +119,11 @@ prompt. When one command outputs two messages this can happen anyway. ============================================================================== 3. Removing autocommands *autocmd-remove* -:au[tocmd]! [group] {event} {pat} [once] [nested] {cmd} +:au[tocmd]! [group] {event} {pat} [++once] [++nested] {cmd} Remove all autocommands associated with {event} and {pat}, and add the command {cmd}. - See |autocmd-once| for [once]. - See |autocmd-nested| for [nested]. + See |autocmd-once| for [++once]. + See |autocmd-nested| for [++nested]. :au[tocmd]! [group] {event} {pat} Remove all autocommands associated with {event} and @@ -354,10 +354,11 @@ Name triggered by ~ |SessionLoadPost| after loading a session file |MenuPopup| just before showing the popup menu +|CompleteChanged| after popup menu changed, not fired on popup menu hide |CompleteDone| after Insert mode completion is done |User| to be used in combination with ":doautocmd" -|Signal| after the nvim process received a signal +|Signal| after Nvim receives a signal @@ -588,6 +589,22 @@ CompleteDone After Insert mode completion is done. Either The |v:completed_item| variable contains the completed item. +CompleteChanged *CompleteChanged* + After each time popup menu changed, not fired + on popup menu hide, use |CompleteDone| for popup + menu hide. + + Sets these |v:event| keys: + completed_item + height + width + row + col + size + scrollbar + + It is not allowed to change the text |textlock|. + *CursorHold* CursorHold When the user doesn't press a key for the time specified with 'updatetime'. Not re-triggered @@ -623,8 +640,9 @@ CursorHoldI Just like CursorHold, but in Insert mode. *CursorMoved* CursorMoved After the cursor was moved in Normal or Visual - mode. Also when the text of the cursor line - has been changed, e.g., with "x", "rx" or "p". + mode or to another window. Also when the text + of the cursor line has been changed, e.g. with + "x", "rx" or "p". Not triggered when there is typeahead or when an operator is pending. For an example see |match-parens|. @@ -809,20 +827,25 @@ InsertCharPre When a character is typed in Insert mode, a different character. When |v:char| is set to more than one character this text is inserted literally. - It is not allowed to change the text |textlock|. - The event is not triggered when 'paste' is - set. + + Cannot change the text. |textlock| + Not triggered when 'paste' is set. *TextYankPost* TextYankPost Just after a |yank| or |deleting| command, but not if the black hole register |quote_| is used nor for |setreg()|. Pattern must be *. Sets these |v:event| keys: + inclusive operator regcontents regname regtype + The `inclusive` flag combined with the |'[| + and |']| marks can be used to calculate the + precise region of the operation. + Recursion is ignored. - It is not allowed to change the text |textlock|. + Cannot change the text. |textlock| *InsertEnter* InsertEnter Just before starting Insert mode. Also for Replace mode and Virtual Replace mode. The @@ -848,27 +871,27 @@ MenuPopup Just before showing the popup menu (under the i Insert c Command line *OptionSet* -OptionSet After setting an option. The pattern is - matched against the long option name. - The |v:option_old| variable indicates the - old option value, |v:option_new| variable - indicates the newly set value, the - |v:option_type| variable indicates whether - it's global or local scoped and |<amatch>| - indicates what option has been set. +OptionSet After setting an option (except during + |startup|). The |autocmd-pattern| is matched + against the long option name. + |v:option_old| indicates the old option value, + |v:option_new| indicates the new value, + |v:option_type| indicates whether it's global + or local scoped and |<amatch>| indicates which + option was set. Usage example: Check for the existence of the directory in the 'backupdir' and 'undodir' options, create the directory if it doesn't exist yet. - Note: It's a bad idea to reset an option - during this autocommand, this may break a - plugin. You can always use `:noa` to prevent - triggering this autocommand. + Note: Do not reset the same option during this + autocommand, that may break plugins. You can + always use |:noautocmd| to prevent triggering + OptionSet. - When using |:set| in the autocommand the event - is not triggered again. + Recursion is ignored, thus |:set| in the + autocommand does not trigger OptionSet again. *QuickFixCmdPre* QuickFixCmdPre Before a quickfix command is run (|:make|, @@ -921,10 +944,11 @@ ShellCmdPost After executing a shell command with |:!cmd|, For non-blocking shell commands, see |job-control|. *Signal* -Signal After the nvim process received a signal. - The pattern is matched against the name of the - received signal. Only "SIGUSR1" is supported. - *ShellFilterPost* +Signal After Nvim receives a signal. The pattern is + matched against the signal name. Only + "SIGUSR1" is supported. Example: > + autocmd Signal SIGUSR1 call some#func() +< *ShellFilterPost* ShellFilterPost After executing a shell command with ":{range}!cmd", ":w !cmd" or ":r !cmd". Can be used to check for any changed files. @@ -972,7 +996,6 @@ SwapExists Detected an existing swap file when starting It is not allowed to change to another buffer, change a buffer name or change directory here. - {only available with the +eval feature} *Syntax* Syntax When the 'syntax' option has been set. The pattern is matched against the syntax name. @@ -1102,7 +1125,7 @@ WinNew When a new window was created. Not done for Before a WinEnter event. ============================================================================== -6. Patterns *autocmd-patterns* *{pat}* +6. Patterns *autocmd-pattern* *{pat}* The {pat} argument can be a comma separated list. This works as if the command was given with each pattern separately. Thus this command: > @@ -1442,9 +1465,9 @@ instead of ":q!". *autocmd-nested* *E218* By default, autocommands do not nest. If you use ":e" or ":w" in an autocommand, Vim does not execute the BufRead and BufWrite autocommands for -those commands. If you do want this, use the "nested" flag for those commands -in which you want nesting. For example: > - :autocmd FileChangedShell *.c nested e! +those commands. If you do want this, use the "++nested" flag for those +commands in which you want nesting. For example: > + :autocmd FileChangedShell *.c ++nested e! The nesting is limited to 10 levels to get out of recursive loops. It's possible to use the ":au" command in an autocommand. This can be a diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt index c73b460767..912231bfcd 100644 --- a/runtime/doc/change.txt +++ b/runtime/doc/change.txt @@ -939,8 +939,6 @@ This replaces each 'E' character with a euro sign. Read more in |<Char->|. this (that's a good habit anyway). `:retab!` may also change a sequence of spaces by <Tab> characters, which can mess up a printf(). - Not available when |+ex_extra| feature was disabled at - compile time. *retab-example* Example for using autocommands and ":retab" to edit a file which is stored @@ -1291,21 +1289,15 @@ The next three commands always work on whole lines. :[range]ce[nter] [width] *:ce* *:center* Center lines in [range] between [width] columns (default 'textwidth' or 80 when 'textwidth' is 0). - Not available when |+ex_extra| feature was disabled at - compile time. :[range]ri[ght] [width] *:ri* *:right* Right-align lines in [range] at [width] columns (default 'textwidth' or 80 when 'textwidth' is 0). - Not available when |+ex_extra| feature was disabled at - compile time. *:le* *:left* :[range]le[ft] [indent] Left-align lines in [range]. Sets the indent in the lines to [indent] (default 0). - Not available when |+ex_extra| feature was disabled at - compile time. *gq* gq{motion} Format the lines that {motion} moves over. @@ -1635,6 +1627,17 @@ j Where it makes sense, remove a comment leader when joining lines. For // in the list ~ Becomes: int i; // the index in the list ~ +p Don't break lines at single spaces that follow periods. This is + intended to complement 'joinspaces' and |cpo-J|, for prose with + sentences separated by two spaces. For example, with 'textwidth' set + to 28: > + Surely you're joking, Mr. Feynman! +< Becomes: > + Surely you're joking, + Mr. Feynman! +< Instead of: > + Surely you're joking, Mr. + Feynman! With 't' and 'c' you can specify when Vim performs auto-wrapping: diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt index 47c4677b20..81b0e17322 100644 --- a/runtime/doc/cmdline.txt +++ b/runtime/doc/cmdline.txt @@ -789,7 +789,6 @@ function |expand()|. #<n (where n is a number > 0) is replaced with old *:_#<* *c_#<* file name n. See |:oldfiles| or |v:oldfiles| to get the number. *E809* - {only when compiled with the |+eval| and |+shada| features} Note that these, except "#<n", give the file name as it was typed. If an absolute path is needed (when using the file name from a different directory), @@ -858,8 +857,6 @@ Note: these are typed literally, they are not special keys! *%:8* *%:p* *%:.* *%:~* *%:h* *%:t* *%:r* *%:e* *%:s* *%:gs* *%:S* The file name modifiers can be used after "%", "#", "#n", "<cfile>", "<sfile>", "<afile>" or "<abuf>". They are also used with the |fnamemodify()| function. -These are not available when Vim has been compiled without the |+modify_fname| -feature. These modifiers can be given, in this order: :p Make file name a full path. Must be the first modifier. Also changes "~/" (and "~user/" for Unix) to the path for the home 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 4369ad7894..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. @@ -62,6 +65,14 @@ Options ~ *'langnoremap'* Deprecated alias to 'nolangremap'. *'vi'* *'viminfo'* Deprecated alias to 'shada' option. +*'viminfofile'* Deprecated alias to 'shadafile' option. + +UI extensions~ +*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"] Variables~ *b:terminal_job_pid* PID of the top-level process in a |:terminal|. diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 4b1cbe2cce..843e23ee54 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -123,7 +123,7 @@ autoload/provider/python.vim script; the provider#python#Call function is only defined if a valid external Python host is found. That works well with the `has('python')` expression (normally used by Python plugins) because if the Python host isn't installed then the plugin will "think" it is running in -a Vim compiled without the |+python| feature. +a Vim compiled without the "+python" feature. DOCUMENTATION *dev-doc* @@ -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/digraph.txt b/runtime/doc/digraph.txt index f05c73d737..95bc3722d0 100644 --- a/runtime/doc/digraph.txt +++ b/runtime/doc/digraph.txt @@ -32,9 +32,6 @@ An alternative is using the 'keymap' option. first character, it has a special meaning in the future. -Vim is normally compiled with the |+digraphs| feature. If the feature is -disabled, the ":digraph" command will display an error message. - Example of the output of ":digraphs": > TH Þ 222 ss ß 223 a! à 224 a' á 225 a> â 226 a? ã 227 a: ä 228 @@ -53,19 +50,6 @@ conversion to be available, it might fail. For the NUL character you will see "10". That's because NUL characters are internally represented with a NL character. When you write the file it will become a NUL character. -When Vim was compiled without the |+multi_byte| feature, you need to specify -the character in the encoding given with 'encoding'. You might want to use -something like this: > - - if has("multi_byte") - digraph oe 339 - elseif &encoding == "iso-8859-15" - digraph oe 189 - endif - -This defines the "oe" digraph for a character that is number 339 in Unicode -and 189 in latin9 (iso-8859-15). - ============================================================================== 2. Using digraphs *digraphs-use* @@ -155,8 +139,7 @@ a standard meaning: Example: a: is ä and o: is ö These are the RFC1345 digraphs for the one-byte characters. See the output of -":digraphs" for the others. The characters above 255 are only available when -Vim was compiled with the |+multi_byte| feature. +":digraphs" for the others. EURO diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt index 34fb779fe7..f4d3164dbc 100644 --- a/runtime/doc/editing.txt +++ b/runtime/doc/editing.txt @@ -1170,9 +1170,8 @@ If you want to always use ":confirm", set the 'confirm' option. and |:qall| if 'confirm' is set. {only in Win32 GUI} When ":browse" is not possible you get an error - message. If the |+browse| feature is missing or the - {command} doesn't support browsing, the {command} is - executed without a dialog. + message. If {command} doesn't support browsing, the + {command} is executed without a dialog. ":browse set" works like |:options|. See also |:oldfiles| for ":browse oldfiles". @@ -1460,8 +1459,6 @@ problem goes away the next day. ============================================================================== 11. File Searching *file-searching* -{not available when compiled without the |+path_extra| feature} - The file searching is currently used for the 'path', 'cdpath' and 'tags' options, for |finddir()| and |findfile()|. Other commands use |wildcards| which is slightly different. diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index da17faaaf6..22157206a4 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -8,10 +8,6 @@ Expression evaluation *expression* *expr* *E15* *eval* Using expressions is introduced in chapter 41 of the user manual |usr_41.txt|. -Note: Expression evaluation can be disabled at compile time. If this has been -done, the features in this document are not available. See |+eval| and -|no-eval-feature|. - Type |gO| to see the table of contents. ============================================================================== @@ -22,8 +18,6 @@ done, the features in this document are not available. See |+eval| and There are six types of variables: Number A 32 or 64 bit signed number. |expr-number| *Number* - 64-bit Number is available only when compiled with the - |+num64| feature. Examples: -123 0x10 0177 0b1011 Float A floating point number. |floating-point-format| *Float* @@ -1307,8 +1301,7 @@ is deleted when the window is closed. *tabpage-variable* *t:var* *t:* A variable name that is preceded with "t:" is local to the current tab page, -It is deleted when the tab page is closed. {not available when compiled -without the |+windows| feature} +It is deleted when the tab page is closed. *global-variable* *g:var* *g:* Inside functions global variables are accessed with "g:". Omitting this will @@ -1419,7 +1412,7 @@ v:beval_text The text under or after the mouse pointer. Usually a word as but a dot and "->" before the position is included. When on a ']' the text before it is used, including the matching '[' and word before it. When on a Visual area within one line the - highlighted text is used. + highlighted text is used. Also see |<cexpr>|. Only valid while evaluating the 'balloonexpr' option. *v:beval_winnr* *beval_winnr-variable* @@ -1509,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 @@ -1539,6 +1533,7 @@ v:event Dictionary of event data for the current |autocommand|. Valid cmdlevel Level of cmdline. cmdtype Type of cmdline, |cmdline-char|. cwd Current working directory. + inclusive Motion is |inclusive|, else exclusive. scope Event-specific scope name. operator Current |operator|. Also set for Ex commands (unlike |v:operator|). For @@ -1552,6 +1547,19 @@ v:event Dictionary of event data for the current |autocommand|. Valid operation. regtype Type of register as returned by |getregtype()|. + completed_item Current selected complete item on + |CompleteChanged|, Is `{}` when no complete + item selected. + height Height of popup menu on |CompleteChanged| + width width of popup menu on |CompleteChanged| + row Row count of popup menu on |CompleteChanged|, + relative to screen. + col Col count of popup menu on |CompleteChanged|, + relative to screen. + size Total number of completion items on + |CompleteChanged|. + scrollbar Is |v:true| if popup menu have scrollbar, or + |v:false| if not. *v:exception* *exception-variable* v:exception The value of the exception most recently caught and not @@ -1731,7 +1739,6 @@ v:oldfiles List of file names that is loaded from the |shada| file on The List can be modified, but this has no effect on what is stored in the |shada| file later. If you use values other than String this will cause trouble. - {only when compiled with the |+shada| feature} *v:option_new* v:option_new New value of the option. Valid while executing an |OptionSet| @@ -1821,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; @@ -1882,15 +1890,14 @@ v:termresponse The escape sequence returned by the terminal for the DA is the terminal type: 0 for vt100 and 1 for vt220. Pv is the patch level (since this was introduced in patch 95, it's always 95 or bigger). Pc is always zero. - {only when compiled with |+termresponse| feature} *v:testing* *testing-variable* 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 @@ -1917,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 @@ -1956,11 +1961,12 @@ and({expr}, {expr}) Number bitwise AND api_info() Dict api metadata append({lnum}, {string}) Number append {string} below line {lnum} append({lnum}, {list}) Number append lines {list} below line {lnum} -argc() Number number of files in the argument list +argc([{winid}]) Number number of files in the argument list argidx() Number current index in the argument list arglistid([{winnr} [, {tabnr}]]) Number argument list id -argv({nr}) String {nr} entry of the argument list -argv() List the argument list +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}]) @@ -2007,6 +2013,7 @@ col({expr}) Number column nr of cursor or mark complete({startcol}, {matches}) none set Insert mode completion complete_add({expr}) Number add completion match complete_check() Number check for key typed during completion +complete_info([{what}]) Dict get current completion information confirm({msg} [, {choices} [, {default} [, {type}]]]) Number number of choice picked by user copy({expr}) any make a shallow copy of {expr} @@ -2090,6 +2097,8 @@ getfperm({fname}) String file permissions of file {fname} getfsize({fname}) Number size in bytes of file {fname} getftime({fname}) Number last modification time of file getftype({fname}) String description of type of file {fname} +getjumplist([{winnr} [, {tabnr}]]) + List list of jump list items getline({lnum}) String line {lnum} of current buffer getline({lnum}, {end}) List lines {lnum} to {end} of current buffer getloclist({nr} [, {what}]) List list of location list items @@ -2105,10 +2114,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}]]]) @@ -2270,6 +2280,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}]) @@ -2314,6 +2326,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} @@ -2431,8 +2445,15 @@ append({lnum}, {text}) *append()* :let failed = append(0, ["Chapter 1", "the beginning"]) < *argc()* -argc() The result is the number of files in the argument list of the - current window. See |arglist|. +argc([{winid}]) + The result is the number of files in the argument list. See + |arglist|. + If {winid} is not supplied, the argument list of the current + window is used. + If {winid} is -1, the global argument list is used. + Otherwise {winid} specifies the window of which the argument + list is used: either the window number or the window ID. + Returns -1 if the {winid} argument is invalid. *argidx()* argidx() The result is the current index in the argument list. 0 is @@ -2443,7 +2464,7 @@ arglistid([{winnr} [, {tabnr}]]) Return the argument list ID. This is a number which identifies the argument list being used. Zero is used for the global argument list. See |arglist|. - Return -1 if the arguments are invalid. + Returns -1 if the arguments are invalid. Without arguments use the current window. With {winnr} only use this window in the current tab page. @@ -2452,17 +2473,24 @@ arglistid([{winnr} [, {tabnr}]]) {winnr} can be the window number or the |window-ID|. *argv()* -argv([{nr}]) The result is the {nr}th file in the argument list of the - current window. See |arglist|. "argv(0)" is the first one. - Example: > +argv([{nr} [, {winid}]) + The result is the {nr}th file in the argument list. See + |arglist|. "argv(0)" is the first one. Example: > :let i = 0 :while i < argc() : let f = escape(fnameescape(argv(i)), '.') : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>' : let i = i + 1 :endwhile -< Without the {nr} argument a |List| with the whole |arglist| is - returned. +< Without the {nr} argument, or when {nr} is -1, a |List| with + the whole |arglist| is returned. + + 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}]) @@ -2496,6 +2524,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 @@ -2830,8 +2860,8 @@ cindent({lnum}) *cindent()* See |C-indenting|. clearmatches() *clearmatches()* - Clears all matches previously defined by |matchadd()| and the - |:match| commands. + Clears all matches previously defined for the current window + by |matchadd()| and the |:match| commands. *col()* col({expr}) The result is a Number, which is the byte index of the column @@ -2916,6 +2946,55 @@ complete_check() *complete_check()* Only to be used by the function specified with the 'completefunc' option. + *complete_info()* +complete_info([{what}]) + Returns a Dictionary with information about Insert mode + completion. See |ins-completion|. + The items are: + mode Current completion mode name string. + See |completion_info_mode| for the values. + pum_visible |TRUE| if popup menu is visible. + See |pumvisible()|. + items List of completion matches. Each item is a + dictionary containing the entries "word", + "abbr", "menu", "kind", "info" and "user_data". + See |complete-items|. + selected Selected item index. First index is zero. + Index is -1 if no item is selected (showing + typed text only) + inserted Inserted string. [NOT IMPLEMENT YET] + + *complete_info_mode* + mode values are: + "" Not in completion mode + "keyword" Keyword completion |i_CTRL-X_CTRL-N| + "ctrl_x" Just pressed CTRL-X |i_CTRL-X| + "whole_line" Whole lines |i_CTRL-X_CTRL-L| + "files" File names |i_CTRL-X_CTRL-F| + "tags" Tags |i_CTRL-X_CTRL-]| + "path_defines" Definition completion |i_CTRL-X_CTRL-D| + "path_patterns" Include completion |i_CTRL-X_CTRL-I| + "dictionary" Dictionary |i_CTRL-X_CTRL-K| + "thesaurus" Thesaurus |i_CTRL-X_CTRL-T| + "cmdline" Vim Command line |i_CTRL-X_CTRL-V| + "function" User defined completion |i_CTRL-X_CTRL-U| + "omni" Omni completion |i_CTRL-X_CTRL-O| + "spell" Spelling suggestions |i_CTRL-X_s| + "eval" |complete()| completion + "unknown" Other internal modes + + If the optional {what} list argument is supplied, then only + the items listed in {what} are returned. Unsupported items in + {what} are silently ignored. + + Examples: > + " Get all items + call complete_info() + " Get only 'mode' + call complete_info(['mode']) + " Get only 'mode' and 'pum_visible' + call complete_info(['mode', 'pum_visible']) +< *confirm()* confirm({msg} [, {choices} [, {default} [, {type}]]]) Confirm() offers the user a dialog, from which a choice can be @@ -3206,7 +3285,7 @@ escape({string}, {chars}) *escape()* :echo escape('c:\program files\vim', ' \') < results in: > c:\\program\ files\\vim -< Also see |shellescape()|. +< Also see |shellescape()| and |fnameescape()|. *eval()* eval({string}) Evaluate {string} and return the result. Especially useful to @@ -3600,8 +3679,6 @@ finddir({name} [, {path} [, {count}]]) *finddir()* {name} in {path} instead of the first one. When {count} is negative return all the matches in a |List|. This is quite similar to the ex-command |:find|. - {only available when compiled with the |+file_in_path| - feature} findfile({name} [, {path} [, {count}]]) *findfile()* Just like |finddir()|, but find a file instead of a directory. @@ -3618,7 +3695,7 @@ float2nr({expr}) *float2nr()* When the value of {expr} is out of range for a |Number| the result is truncated to 0x7fffffff or -0x7fffffff (or when 64-bit Number support is enabled, 0x7fffffffffffffff or - -0x7fffffffffffffff. NaN results in -0x80000000 (or when + -0x7fffffffffffffff). NaN results in -0x80000000 (or when 64-bit Number support is enabled, -0x8000000000000000). Examples: > echo float2nr(3.95) @@ -3722,7 +3799,6 @@ foldtext() Returns a String, to be displayed for a closed fold. This is When used to draw the actual foldtext, the rest of the line will be filled with the fold char from the 'fillchars' setting. - {not available when compiled without the |+folding| feature} foldtextresult({lnum}) *foldtextresult()* Returns the text that is displayed for the closed fold at line @@ -3732,7 +3808,6 @@ foldtextresult({lnum}) *foldtextresult()* {lnum} is used like with |getline()|. Thus "." is the current line, "'m" mark m, etc. Useful when exporting folded text, e.g., to HTML. - {not available when compiled without the |+folding| feature} *foreground()* foreground() Move the Vim window to the foreground. Useful when sent from @@ -3768,7 +3843,7 @@ function({name} [, {arglist}] [, {dict}]) same function. When {arglist} or {dict} is present this creates a partial. - That mans the argument list and/or the dictionary is stored in + That means the argument list and/or the dictionary is stored in the Funcref and will be used when the Funcref is called. The arguments are passed to the function in front of other @@ -3947,14 +4022,14 @@ getchar([expr]) *getchar()* not consumed. Return zero if no character available. Without [expr] and when [expr] is 0 a whole character or - special key is returned. If it is an 8-bit character, the + special key is returned. If it is a single character, the result is a number. Use nr2char() to convert it to a String. Otherwise a String is returned with the encoded character. - For a special key it's a sequence of bytes starting with 0x80 - (decimal: 128). This is the same value as the string - "\<Key>", e.g., "\<Left>". The returned value is also a - String when a modifier (shift, control, alt) was used that is - not included in the character. + For a special key it's a String with a sequence of bytes + starting with 0x80 (decimal: 128). This is the same value as + the String "\<Key>", e.g., "\<Left>". The returned value is + also a String when a modifier (shift, control, alt) was used + that is not included in the character. When [expr] is 0 and Esc is typed, there will be a short delay while Vim waits to see if this is the start of an escape @@ -4226,6 +4301,26 @@ getftype({fname}) *getftype()* systems that support it. On some systems only "dir" and "file" are returned. + *getjumplist()* +getjumplist([{winnr} [, {tabnr}]]) + Returns the |jumplist| for the specified window. + + Without arguments use the current window. + With {winnr} only use this window in the current tab page. + {winnr} can also be a |window-ID|. + With {winnr} and {tabnr} use the window in the specified tab + page. + + The returned list contains two entries: a list with the jump + locations and the last used jump position number in the list. + Each entry in the jump location list is a dictionary with + the following entries: + bufnr buffer number + col column number + coladd column offset for 'virtualedit' + filename filename if available + lnum line number + *getline()* getline({lnum} [, {end}]) Without {end} the result is a String, which is line {lnum} @@ -4265,10 +4360,11 @@ getloclist({nr},[, {what}]) *getloclist()* |getqflist()| for the supported items in {what}. getmatches() *getmatches()* - Returns a |List| with all matches previously defined by - |matchadd()| and the |:match| commands. |getmatches()| is - useful in combination with |setmatches()|, as |setmatches()| - can restore a list of matches saved by |getmatches()|. + Returns a |List| with all matches previously defined for the + current window by |matchadd()| and the |:match| commands. + |getmatches()| is useful in combination with |setmatches()|, + as |setmatches()| can restore a list of matches saved by + |getmatches()|. Example: > :echo getmatches() < [{'group': 'MyGroup1', 'pattern': 'TODO', @@ -4481,6 +4577,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 @@ -4609,10 +4740,47 @@ globpath({path}, {expr} [, {nosuf} [, {list} [, {allinks}]]]) supported, thus using 'path' will not always work properly. *has()* -has({feature}) The result is a Number, which is 1 if the feature {feature} is - supported, zero otherwise. The {feature} argument is a - string. See |feature-list| below. - Also see |exists()|. +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 + recognized because Nvim is always compiled with all possible + features. |feature-compile| + + Feature names can be: + 1. Nvim version. For example the "nvim-0.2.1" feature means + that Nvim is version 0.2.1 or later: > + :if has("nvim-0.2.1") + +< 2. Runtime condition or other pseudo-feature. For example the + "win32" feature checks if the current system is Windows: > + :if has("win32") +< *feature-list* + List of supported pseudo-feature names: + acl |ACL| support + iconv Can use |iconv()| for conversion. + +shellslash Can use backslashes in filenames (Windows) + clipboard |clipboard| provider is available. + nvim This is Nvim. + python2 Legacy Vim |python2| interface. |has-python| + python3 Legacy Vim |python3| interface. |has-python| + pythonx Legacy Vim |python_x| interface. |has-pythonx| + ttyin input is a terminal (tty) + ttyout output is a terminal (tty) + unix Unix system. + *vim_starting* True during |startup|. + win32 Windows system (32 or 64 bit). + wsl WSL (Windows Subsystem for Linux) system + + *has-patch* + 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") + +< 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") has_key({dict}, {key}) *has_key()* @@ -5489,7 +5657,7 @@ match({expr}, {pat} [, {start} [, {count}]]) *match()* the pattern. 'smartcase' is NOT used. The matching is always done like 'magic' is set and 'cpoptions' is empty. - *matchadd()* *E798* *E799* *E801* + *matchadd()* *E798* *E799* *E801* *E957* matchadd({group}, {pattern}[, {priority}[, {id} [, {dict}]]]) Defines a pattern to be highlighted in the current window (a "match"). It will be highlighted with {group}. Returns an @@ -5528,6 +5696,8 @@ matchadd({group}, {pattern}[, {priority}[, {id} [, {dict}]]]) conceal Special character to show instead of the match (only for |hl-Conceal| highlighed matches, see |:syn-cchar|) + window Instead of the current window use the + window with this number or window ID. The number of matches is not limited, as it is the case with the |:match| commands. @@ -6831,6 +7001,7 @@ setline({lnum}, {text}) *setline()* :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']] : call setline(n, l) :endfor + < Note: The '[ and '] marks are not set. setloclist({nr}, {list} [, {action}[, {what}]]) *setloclist()* @@ -6848,9 +7019,10 @@ setloclist({nr}, {list} [, {action}[, {what}]]) *setloclist()* for the list of supported keys in {what}. setmatches({list}) *setmatches()* - Restores a list of matches saved by |getmatches()|. Returns 0 - if successful, otherwise -1. All current matches are cleared - before the list is restored. See example for |getmatches()|. + Restores a list of matches saved by |getmatches() for the + current window|. Returns 0 if successful, otherwise -1. All + current matches are cleared before the list is restored. See + example for |getmatches()|. *setpos()* setpos({expr}, {list}) @@ -6914,6 +7086,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 @@ -6958,9 +7132,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 @@ -7034,16 +7205,17 @@ setreg({regname}, {value} [, {options}]) :call setreg('a', "1\n2\n3", 'b5') < This example shows using the functions to save and restore a - register (note: you may not reliably restore register value - without using the third argument to |getreg()| as without it - newlines are represented as newlines AND Nul bytes are - represented as newlines as well, see |NL-used-for-Nul|). > + register: > :let var_a = getreg('a', 1, 1) :let var_amode = getregtype('a') .... :call setreg('a', var_a, var_amode) +< Note: you may not reliably restore register value + without using the third argument to |getreg()| as without it + newlines are represented as newlines AND Nul bytes are + represented as newlines as well, see |NL-used-for-Nul|. -< You can also change the type of a register by appending + You can also change the type of a register by appending nothing: > :call setreg('a', '', 'al') @@ -7070,6 +7242,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: > @@ -7640,6 +7844,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. @@ -7762,7 +7991,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.: > @@ -7779,7 +8008,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')) @@ -7993,6 +8222,10 @@ timer_start({time}, {callback} [, {options}]) "repeat" Number of times to repeat calling the callback. -1 means forever. When not present the callback will be called once. + If the timer causes an error three times in a + row the repeat is cancelled. This avoids that + Vim becomes unusable because of all the error + messages. Example: > func MyHandler(timer) @@ -8236,7 +8469,7 @@ win_getid([{win} [, {tab}]]) *win_getid()* Get the |window-ID| for the specified window. When {win} is missing use the current window. With {win} this is the window number. The top window has - number 1. + number 1. Use `win_getid(winnr())` for the current window. Without {tab} use the current tab, otherwise the tab with number {tab}. The first tab has number one. Return zero if the window cannot be found. @@ -8298,17 +8531,30 @@ winline() The result is a Number, which is the screen line of the cursor *winnr()* winnr([{arg}]) The result is a Number, which is the number of the current window. The top window has number 1. - When the optional argument is "$", the number of the - last window is returned (the window count). > - let window_count = winnr('$') -< When the optional argument is "#", the number of the last - accessed window is returned (where |CTRL-W_p| goes to). - If there is no previous window or it is in another tab page 0 - is returned. + + The optional argument {arg} supports the following values: + $ the number of the last window (the window + count). + # the number of the last accessed window (where + |CTRL-W_p| goes to). If there is no previous + window or it is in another tab page 0 is + returned. + {N}j the number of the Nth window below the + current window (where |CTRL-W_j| goes to). + {N}k the number of the Nth window above the current + window (where |CTRL-W_k| goes to). + {N}h the number of the Nth window left of the + current window (where |CTRL-W_h| goes to). + {N}l the number of the Nth window right of the + current window (where |CTRL-W_l| goes to). The number can be used with |CTRL-W_w| and ":wincmd w" |:wincmd|. Also see |tabpagewinnr()| and |win_getid()|. - + Examples: > + let window_count = winnr('$') + let prev_window = winnr('#') + let wnum = winnr('3k') +< *winrestcmd()* winrestcmd() Returns a sequence of |:resize| commands that should restore the current window sizes. Only works properly when no windows @@ -8437,154 +8683,6 @@ xor({expr}, {expr}) *xor()* < - *feature-list* -There are four types of features: -1. Features that are only supported when they have been enabled when Vim - was compiled |+feature-list|. Example: > - :if has("cindent") -2. Features that are only supported when certain conditions have been met. - Example: > - :if has("win32") -< *has-patch* -3. Nvim version. The "nvim-0.2.1" feature means that the Nvim version is - 0.2.1 or later. Example: > - :if has("nvim-0.2.1") -< -4. Included patches. The "patch123" feature means that patch 123 has been - included. Note that this form does not check the version of Vim, you need - to inspect |v:version| for that. - Example (checking version 6.2.148 or later): > - :if v:version > 602 || v:version == 602 && has("patch148") -< Note that it's possible for patch 147 to be omitted even though 148 is - included. - -5. Beyond a certain version or at a certain version and including a specific - patch. The "patch-7.4.237" feature means that the Vim version is 7.5 or - later, or it is version 7.4 and patch 237 was included. - Note that this only works for patch 7.4.237 and later, before that you - need to use the example above that checks v:version. Example: > - :if has("patch-7.4.248") -< Note that it's possible for patch 147 to be omitted even though 148 is - included. - -Hint: To find out if Vim supports backslashes in a file name (MS-Windows), -use: `if exists('+shellslash')` - - -acl Compiled with |ACL| support. -arabic Compiled with Arabic support |Arabic|. -autocmd Compiled with autocommand support. |autocommand| -browse Compiled with |:browse| support, and browse() will - work. -browsefilter Compiled with support for |browsefilter|. -byte_offset Compiled with support for 'o' in 'statusline' -cindent Compiled with 'cindent' support. -clipboard Compiled with 'clipboard' support. -cmdline_compl Compiled with |cmdline-completion| support. -cmdline_hist Compiled with |cmdline-history| support. -cmdline_info Compiled with 'showcmd' and 'ruler' support. -comments Compiled with |'comments'| support. -cscope Compiled with |cscope| support. -debug Compiled with "DEBUG" defined. -dialog_con Compiled with console dialog support. -digraphs Compiled with support for digraphs. -eval Compiled with expression evaluation support. Always - true, of course! -ex_extra |+ex_extra|, always true now -extra_search Compiled with support for |'incsearch'| and - |'hlsearch'| -file_in_path Compiled with support for |gf| and |<cfile>| -filterpipe When 'shelltemp' is off pipes are used for shell - read/write/filter commands -find_in_path Compiled with support for include file searches - |+find_in_path|. -float Compiled with support for |Float|. -fname_case Case in file names matters (for Windows this is not - present). -folding Compiled with |folding| support. -gettext Compiled with message translation |multi-lang| -iconv Can use iconv() for conversion. -insert_expand Compiled with support for CTRL-X expansion commands in - Insert mode. -jumplist Compiled with |jumplist| support. -keymap Compiled with 'keymap' support. -lambda Compiled with |lambda| support. -langmap Compiled with 'langmap' support. -libcall Compiled with |libcall()| support. -linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and - 'breakindent' support. -lispindent Compiled with support for lisp indenting. -listcmds Compiled with commands for the buffer list |:files| - and the argument list |arglist|. -localmap Compiled with local mappings and abbr. |:map-local| -mac macOS version of Nvim. -menu Compiled with support for |:menu|. -mksession Compiled with support for |:mksession|. -modify_fname Compiled with file name modifiers. |filename-modifiers| -mouse Compiled with support mouse. -mouseshape Compiled with support for 'mouseshape'. -multi_byte Compiled with support for 'encoding' -multi_byte_encoding 'encoding' is set to a multi-byte encoding. -multi_lang Compiled with support for multiple languages. -num64 Compiled with 64-bit |Number| support. -nvim This is Nvim. |has-patch| -path_extra Compiled with up/downwards search in 'path' and 'tags' -persistent_undo Compiled with support for persistent undo history. -postscript Compiled with PostScript file printing. -printer Compiled with |:hardcopy| support. -profile Compiled with |:profile| support. -python Legacy Vim Python 2.x API is available. |has-python| -python3 Legacy Vim Python 3.x API is available. |has-python| -pythonx Compiled with |python_x| interface. |has-pythonx| -quickfix Compiled with |quickfix| support. -reltime Compiled with |reltime()| support. -rightleft Compiled with 'rightleft' support. -scrollbind Compiled with 'scrollbind' support. -shada Compiled with shada support. -showcmd Compiled with 'showcmd' support. -signs Compiled with |:sign| support. -smartindent Compiled with 'smartindent' support. -spell Compiled with spell checking support |spell|. -startuptime Compiled with |--startuptime| support. -statusline Compiled with support for 'statusline', 'rulerformat' - and special formats of 'titlestring' and 'iconstring'. -syntax Compiled with syntax highlighting support |syntax|. -syntax_items There are active syntax highlighting items for the - current buffer. -tablineat 'tabline' option accepts %@Func@ items. -tag_binary Compiled with binary searching in tags files - |tag-binary-search|. -tag_old_static Compiled with support for old static tags - |tag-old-static|. -tag_any_white Compiled with support for any white characters in tags - files |tag-any-white|. -termresponse Compiled with support for t_RV and |v:termresponse|. -textobjects Compiled with support for |text-objects|. -timers Compiled with |timer_start()| support. -title Compiled with window title support |'title'|. -ttyin input is a terminal (tty) -ttyout output is a terminal (tty) -unix Unix version of Vim. -unnamedplus Compiled with support for "unnamedplus" in 'clipboard' -user_commands User-defined commands. -vertsplit Compiled with vertically split windows |:vsplit|. -vim_starting True while initial source'ing takes place. |startup| - *vim_starting* -virtualedit Compiled with 'virtualedit' option. -visual Compiled with Visual mode. -visualextra Compiled with extra Visual mode commands. - |blockwise-operators|. -vreplace Compiled with |gR| and |gr| commands. -vtp Compiled for vcon support |+vtp| (check vcon to find - out if it works in the current console)). -wildignore Compiled with 'wildignore' option. -wildmenu Compiled with 'wildmenu' option. -win32 Windows version of Vim (32 or 64 bit). -winaltkeys Compiled with 'winaltkeys' option. -windows Compiled with support for more than one window. -writebackup Compiled with 'writebackup' default on. -wsl WSL (Windows Subsystem for Linux) version of Vim. - *string-match* Matching a pattern in a String diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt index c36aeffa1a..7f90074ff0 100644 --- a/runtime/doc/if_lua.txt +++ b/runtime/doc/if_lua.txt @@ -16,11 +16,11 @@ an idea of what lurks beneath: > :lua print(vim.inspect(package.loaded)) -Nvim includes a "standard library" |lua-stdlib| for Lua. This library -complements the Nvim editor |functions| and Ex commands (the editor "stdlib"), -which can also be used from Lua code. +Nvim includes a "standard library" |lua-stdlib| for Lua. It complements the +"editor stdlib" (|functions| and Ex commands) and the |API|, all of which can +be used from Lua code. -Nvim resolves module conflicts by "last wins". For example if both of these +Module conflicts are resolved by "last wins". For example if both of these are on 'runtimepath': runtime/lua/foo.lua ~/.config/nvim/lua/foo.lua @@ -30,7 +30,7 @@ finds and loads Lua modules. The conventions are similar to VimL plugins, with some extra features. See |lua-require-example| for a walkthrough. ============================================================================== -Importing modules *lua-require* +Importing Lua modules *lua-require* Nvim automatically adjusts `package.path` and `package.cpath` according to effective 'runtimepath' value. Adjustment happens whenever 'runtimepath' is @@ -258,11 +258,81 @@ position are restricted when the command is executed in the |sandbox|. ============================================================================== -vim.* *lua-vim* *lua-stdlib* +luaeval() *lua-luaeval* *lua-eval* + *luaeval()* + +The (dual) equivalent of "vim.eval" for passing Lua values to Nvim is +"luaeval". "luaeval" takes an expression string and an optional argument used +for _A inside expression and returns the result of the expression. It is +semantically equivalent in Lua to: +> + local chunkheader = "local _A = select(1, ...) return " + function luaeval (expstr, arg) + local chunk = assert(loadstring(chunkheader .. expstr, "luaeval")) + return chunk(arg) -- return typval + end + +Lua nils, numbers, strings, tables and booleans are converted to their +respective VimL types. An error is thrown if conversion of any other Lua types +is attempted. + +The magic global "_A" contains the second argument to luaeval(). + +Example: > + :echo luaeval('_A[1] + _A[2]', [40, 2]) + 42 + :echo luaeval('string.match(_A, "[a-z]+")', 'XYXfoo123') + foo + +Lua tables are used as both dictionaries and lists, so it is impossible to +determine whether empty table is meant to be empty list or empty dictionary. +Additionally lua does not have integer numbers. To distinguish between these +cases there is the following agreement: + +0. Empty table is empty list. +1. Table with N incrementally growing integral numbers, starting from 1 and + ending with N is considered to be a list. +2. Table with string keys, none of which contains NUL byte, is considered to + be a dictionary. +3. Table with string keys, at least one of which contains NUL byte, is also + considered to be a dictionary, but this time it is converted to + a |msgpack-special-map|. + *lua-special-tbl* +4. Table with `vim.type_idx` key may be a dictionary, a list or floating-point + value: + - `{[vim.type_idx]=vim.types.float, [vim.val_idx]=1}` is converted to + a floating-point 1.0. Note that by default integral lua numbers are + converted to |Number|s, non-integral are converted to |Float|s. This + variant allows integral |Float|s. + - `{[vim.type_idx]=vim.types.dictionary}` is converted to an empty + dictionary, `{[vim.type_idx]=vim.types.dictionary, [42]=1, a=2}` is + converted to a dictionary `{'a': 42}`: non-string keys are ignored. + Without `vim.type_idx` key tables with keys not fitting in 1., 2. or 3. + are errors. + - `{[vim.type_idx]=vim.types.list}` is converted to an empty list. As well + as `{[vim.type_idx]=vim.types.list, [42]=1}`: integral keys that do not + form a 1-step sequence from 1 to N are ignored, as well as all + non-integral keys. + +Examples: > + + :echo luaeval('math.pi') + :function Rand(x,y) " random uniform between x and y + : return luaeval('(_A.y-_A.x)*math.random()+_A.x', {'x':a:x,'y':a:y}) + : endfunction + :echo Rand(1,10) + +Note that currently second argument to `luaeval` undergoes VimL to lua +conversion, so changing containers in lua do not affect values in VimL. Return +value is also always converted. When converting, |msgpack-special-dict|s are +treated specially. + +============================================================================== +Lua standard modules *lua-stdlib* -The "standard library" (stdlib) of Nvim Lua is the `vim` module, which exposes -various functions and sub-modules. The module is implicitly loaded, thus -require("vim") is unnecessary. +The Nvim Lua "standard library" (stdlib) is the `vim` module, which exposes +various functions and sub-modules. It is always loaded, thus require("vim") +is unnecessary. You can peek at the module properties: > @@ -288,11 +358,11 @@ To find documentation on e.g. the "deepcopy" function: > :help vim.deepcopy -Note: Underscore-prefixed functions (e.g. "_os_proc_children") are +Note that underscore-prefixed functions (e.g. "_os_proc_children") are internal/private and must not be used by plugins. ------------------------------------------------------------------------------ -vim.api.* functions +VIM.API *lua-api* `vim.api` exposes the full Nvim |API| as a table of Lua functions. @@ -302,55 +372,18 @@ For example, to use the "nvim_get_current_line()" API function, call print(tostring(vim.api.nvim_get_current_line())) ------------------------------------------------------------------------------ -vim.* builtin functions - -vim.deepcopy({object}) *vim.deepcopy* - Performs a deep copy of the given object, and returns that copy. - For a non-table object, that just means a usual copy of the object, - while for a table all subtables are copied recursively. - -vim.gsplit({s}, {sep}, {plain}) *vim.gsplit* - Split a given string by a separator. Returns an iterator of the - split components. The separator can be a lua pattern, see - https://www.lua.org/pil/20.2.html - Setting {plain} to `true` turns off pattern matching, as it is passed - to `string:find`, see - http://lua-users.org/wiki/StringLibraryTutorial - - Parameters:~ - {s} String: String to split - {sep} String: Separator pattern. If empty, split by chars. - {plain} Boolean: If false, match {sep} verbatim - - Return:~ - Iterator of strings, which are the components of {s} after - splitting - -vim.split({s}, {sep}, {plain}) *vim.split* - Split a given string by a separator. Returns a table containing the - split components. The separator can be a lua pattern, see - https://www.lua.org/pil/20.2.html - Setting {plain} to `true` turns off pattern matching, as it is passed - to `string:find`, see - http://lua-users.org/wiki/StringLibraryTutorial - - Parameters:~ - {s} String: String to split - {sep} String: Separator pattern. If empty, split by chars. - {plain} Boolean: If false, match {sep} verbatim - - Return:~ - Table of strings, which are the components of {s} after - splitting +VIM *lua-util* + +vim.inspect({object}, {options}) *vim.inspect* + Return a human-readable representation of the passed object. See + https://github.com/kikito/inspect.lua + for details and possible options. vim.stricmp(a, b) *lua-vim.stricmp* Function used for case-insensitive string comparison. Takes two string arguments and returns 0, 1 or -1 if strings are equal, a is greater then b or a is lesser then b respectively. -vim.trim({string}) *vim.trim* - Returns the string with all leading and trailing whitespace removed. - vim.type_idx *lua-vim.type_idx* Type index for use in |lua-special-tbl|. Specifying one of the values from |lua-vim.types| allows typing the empty table (it is @@ -386,86 +419,106 @@ vim.types *lua-vim.types* `vim.types.dictionary` will not change or that `vim.types` table will only contain values for these three types. ------------------------------------------------------------------------------- -vim.* runtime functions +============================================================================== +Lua module: vim *lua-vim* -Those functions are only available after the runtime files have been loaded. -In particular, they are not available when using `nvim -u NONE`. +trim({s}) *vim.trim()* + Trim whitespace (Lua pattern "%%s") from both sides of a + string. -vim.inspect({object}, {options}) *vim.inspect* - Return a human-readable representation of the passed object. See - https://github.com/kikito/inspect.lua - for details and possible options. + Parameters: ~ + {s} String to trim -============================================================================== -luaeval() *lua-luaeval* *lua-eval* - *luaeval()* + Return: ~ + String with whitespace removed from its beginning and end -The (dual) equivalent of "vim.eval" for passing Lua values to Nvim is -"luaeval". "luaeval" takes an expression string and an optional argument used -for _A inside expression and returns the result of the expression. It is -semantically equivalent in Lua to: -> - local chunkheader = "local _A = select(1, ...) return " - function luaeval (expstr, arg) - local chunk = assert(loadstring(chunkheader .. expstr, "luaeval")) - return chunk(arg) -- return typval - end + See also: ~ + https://www.lua.org/pil/20.2.html -Lua nils, numbers, strings, tables and booleans are converted to their -respective VimL types. An error is thrown if conversion of any other Lua types -is attempted. -The magic global "_A" contains the second argument to luaeval(). -Example: > - :echo luaeval('_A[1] + _A[2]', [40, 2]) - 42 - :echo luaeval('string.match(_A, "[a-z]+")', 'XYXfoo123') - foo -Lua tables are used as both dictionaries and lists, so it is impossible to -determine whether empty table is meant to be empty list or empty dictionary. -Additionally lua does not have integer numbers. To distinguish between these -cases there is the following agreement: +deepcopy({orig}) *vim.deepcopy()* + Returns a deep copy of the given object. Non-table objects are + copied as in a typical Lua assignment, whereas table objects + are copied recursively. -0. Empty table is empty list. -1. Table with N incrementally growing integral numbers, starting from 1 and - ending with N is considered to be a list. -2. Table with string keys, none of which contains NUL byte, is considered to - be a dictionary. -3. Table with string keys, at least one of which contains NUL byte, is also - considered to be a dictionary, but this time it is converted to - a |msgpack-special-map|. - *lua-special-tbl* -4. Table with `vim.type_idx` key may be a dictionary, a list or floating-point - value: - - `{[vim.type_idx]=vim.types.float, [vim.val_idx]=1}` is converted to - a floating-point 1.0. Note that by default integral lua numbers are - converted to |Number|s, non-integral are converted to |Float|s. This - variant allows integral |Float|s. - - `{[vim.type_idx]=vim.types.dictionary}` is converted to an empty - dictionary, `{[vim.type_idx]=vim.types.dictionary, [42]=1, a=2}` is - converted to a dictionary `{'a': 42}`: non-string keys are ignored. - Without `vim.type_idx` key tables with keys not fitting in 1., 2. or 3. - are errors. - - `{[vim.type_idx]=vim.types.list}` is converted to an empty list. As well - as `{[vim.type_idx]=vim.types.list, [42]=1}`: integral keys that do not - form a 1-step sequence from 1 to N are ignored, as well as all - non-integral keys. + Parameters: ~ + {orig} Table to copy -Examples: > + Return: ~ + New table of copied keys and (nested) values. - :echo luaeval('math.pi') - :function Rand(x,y) " random uniform between x and y - : return luaeval('(_A.y-_A.x)*math.random()+_A.x', {'x':a:x,'y':a:y}) - : endfunction - :echo Rand(1,10) +gsplit({s}, {sep}, {plain}) *vim.gsplit()* + Splits a string at each instance of a separator. -Note that currently second argument to `luaeval` undergoes VimL to lua -conversion, so changing containers in lua do not affect values in VimL. Return -value is also always converted. When converting, |msgpack-special-dict|s are -treated specially. + Parameters: ~ + {s} String to split + {sep} Separator string or pattern + {plain} If `true` use `sep` literally (passed to + String.find) -============================================================================== - vim:tw=78:ts=8:et:ft=help:norl: + Return: ~ + Iterator over the split components + + See also: ~ + |vim.split()| + https://www.lua.org/pil/20.2.html + http://lua-users.org/wiki/StringLibraryTutorial + +split({s}, {sep}, {plain}) *vim.split()* + Splits a string at each instance of a separator. + + Examples: > + split(":aa::b:", ":") --> {'','aa','','bb',''} + split("axaby", "ab?") --> {'','x','y'} + split(x*yz*o, "*", true) --> {'x','yz','o'} +< + + Parameters: ~ + {s} String to split + {sep} Separator string or pattern + {plain} If `true` use `sep` literally (passed to + String.find) + + Return: ~ + List-like table of the split components. + + See also: ~ + |vim.gsplit()| + +tbl_contains({t}, {value}) *vim.tbl_contains()* + Checks if a list-like (vector) table contains `value` . + + Parameters: ~ + {t} Table to check + {value} Value to compare + + Return: ~ + true if `t` contains `value` + +tbl_extend({behavior}, {...}) *vim.tbl_extend()* + Merges two or more map-like tables. + + Parameters: ~ + {behavior} Decides what to do if a key is found in more + than one map: + - "error": raise an error + - "keep": use value from the leftmost map + - "force": use value from the rightmost map + {...} Two or more map-like tables. + + See also: ~ + |extend()| + +tbl_flatten({t}) *vim.tbl_flatten()* + Creates a copy of a list-like table such that any nested + tables are "unrolled" and appended to the result. + + Parameters: ~ + {t} List-like table + + Return: ~ + Flattened copy of the given list-like table. + + vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/indent.txt b/runtime/doc/indent.txt index aae091aa99..6820b9c240 100644 --- a/runtime/doc/indent.txt +++ b/runtime/doc/indent.txt @@ -56,12 +56,13 @@ typing certain characters or commands in certain contexts. Note that this not only triggers C-indenting. When 'indentexpr' is not empty 'indentkeys' is used instead. The format of 'cinkeys' and 'indentkeys' is equal. -The default is "0{,0},0),:,0#,!^F,o,O,e" which specifies that indenting occurs -as follows: +The default is "0{,0},0),0],:,0#,!^F,o,O,e" which specifies that indenting +occurs as follows: "0{" if you type '{' as the first character in a line "0}" if you type '}' as the first character in a line "0)" if you type ')' as the first character in a line + "0]" if you type ']' as the first character in a line ":" if you type ':' after a label or case statement "0#" if you type '#' as the first character in a line "!^F" if you type CTRL-F (which is not inserted) diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt index f22f90548b..fce4d8628e 100644 --- a/runtime/doc/insert.txt +++ b/runtime/doc/insert.txt @@ -359,8 +359,8 @@ CTRL-\ CTRL-O like CTRL-O but don't move the cursor *i_CTRL-\_CTRL-O* CTRL-L when 'insertmode' is set: go to Normal mode *i_CTRL-L* CTRL-G u break undo sequence, start new change *i_CTRL-G_u* CTRL-G U don't break undo with next left/right cursor *i_CTRL-G_U* - movement (but only if the cursor stays - within same the line) + movement, if the cursor stays within + same the line ----------------------------------------------------------------------- The CTRL-O command sometimes has a side effect: If the cursor was beyond the @@ -617,6 +617,7 @@ and one of the CTRL-X commands. You exit CTRL-X mode by typing a key that is not a valid CTRL-X mode command. Valid keys are the CTRL-X command itself, CTRL-N (next), and CTRL-P (previous). +To get the current completion information, |complete_info()| can be used. Also see the 'infercase' option if you want to adjust the case of the match. *complete_CTRL-E* @@ -1074,6 +1075,9 @@ items: icase when non-zero case is to be ignored when comparing items to be equal; when omitted zero is used, thus items that only differ in case are added + equal when non-zero, always treat this item to be equal when + comparing. Which means, "equal=1" disables filtering + of this item. dup when non-zero this match will be added even when an item with the same word is already present. empty when non-zero this match will be added even when it is @@ -1081,10 +1085,10 @@ items: user_data custom data which is associated with the item and available in |v:completed_item| -All of these except "icase", "dup" and "empty" must be a string. If an item -does not meet these requirements then an error message is given and further -items in the list are not used. You can mix string and Dictionary items in -the returned list. +All of these except "icase", "equal", "dup" and "empty" must be a string. If +an item does not meet these requirements then an error message is given and +further items in the list are not used. You can mix string and Dictionary +items in the returned list. The "menu" item is used in the popup menu and may be truncated, thus it should be relatively short. The "info" item can be longer, it will be displayed in @@ -1840,7 +1844,8 @@ NOTE: These commands cannot be used with |:global| or |:vglobal|. ":endif", ":for" and ":endfor", ":while" and ":endwhile". *:start* *:startinsert* -:star[tinsert][!] Start Insert mode just after executing this command. +:star[tinsert][!] Start Insert mode (or |Terminal-mode| in a |terminal| + buffer) just after executing this command. Works like typing "i" in Normal mode. When the ! is included it works like "A", append to the line. Otherwise insertion starts at the cursor position. @@ -1850,8 +1855,8 @@ NOTE: These commands cannot be used with |:global| or |:vglobal|. This command does not work from |:normal|. *:stopi* *:stopinsert* -:stopi[nsert] Stop Insert mode as soon as possible. Works like - typing <Esc> in Insert mode. +:stopi[nsert] Stop Insert mode or |Terminal-mode| as soon as + possible. Works like typing <Esc> in Insert mode. Can be used in an autocommand, example: > :au BufEnter scratch stopinsert < diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt index fee7d9aa69..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. @@ -359,16 +360,24 @@ notation meaning equivalent decimal value(s) ~ <End> end *end* <PageUp> page-up *page_up* *page-up* <PageDown> page-down *page_down* *page-down* +<kUp> keypad cursor-up *keypad-cursor-up* +<kDown> keypad cursor-down *keypad-cursor-down* +<kLeft> keypad cursor-left *keypad-cursor-left* +<kRight> keypad cursor-right *keypad-cursor-right* <kHome> keypad home (upper left) *keypad-home* <kEnd> keypad end (lower left) *keypad-end* +<kOrigin> keypad origin (middle) *keypad-origin* <kPageUp> keypad page-up (upper right) *keypad-page-up* <kPageDown> keypad page-down (lower right) *keypad-page-down* +<kDel> keypad delete *keypad-delete* <kPlus> keypad + *keypad-plus* <kMinus> keypad - *keypad-minus* <kMultiply> keypad * *keypad-multiply* <kDivide> keypad / *keypad-divide* +<kPoint> keypad . *keypad-point* +<kComma> keypad , *keypad-comma* +<kEqual> keypad = *keypad-equal* <kEnter> keypad Enter *keypad-enter* -<kPoint> keypad Decimal point *keypad-point* <k0> - <k9> keypad 0 to 9 *keypad-0* *keypad-9* <S-...> shift-key *shift* *<S-* <C-...> control-key *control* *ctrl* *<C-* @@ -392,6 +401,9 @@ recognized as the non-keypad code. For example, when <kHome> sends the same code as <Home>, when pressing <kHome> Vim will think <Home> was pressed. Mapping <kHome> will not work then. +Note: If numlock is on, the |TUI| receives plain ASCII values, so +mappings to <k0> - <k9> and <kPoint> will not work. + *<>* Examples are often given in the <> notation. Sometimes this is just to make clear what you need to type, but often it can be typed literally, e.g., with diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt index fa5e10b5e5..eac42df791 100644 --- a/runtime/doc/map.txt +++ b/runtime/doc/map.txt @@ -227,14 +227,14 @@ should not either insert or change the v:char. Be very careful about side effects! The expression is evaluated while obtaining characters, you may very well make the command dysfunctional. -For this reason the following is blocked: +Therefore the following is blocked for <expr> mappings: - Changing the buffer text |textlock|. - Editing another buffer. - The |:normal| command. - Moving the cursor is allowed, but it is restored afterwards. - If the cmdline is changed, the old text and cursor position are restored. If you want the mapping to do any of these let the returned characters do -that. Or use a |<Cmd>| mapping (which doesn't have these restrictions). +that. (Or use a |<Cmd>| mapping instead.) You can use getchar(), it consumes typeahead if there is any. E.g., if you have these mappings: > @@ -274,9 +274,9 @@ Using 0x80 as a single byte before other text does not work, it will be seen as a special key. *<Cmd>* *:map-cmd* -The <Cmd> pseudokey may be used to define a "command mapping", which executes -the command directly (without changing modes, etc.). Where you might use -":...<CR>" in the {lhs} of a mapping, you can instead use "<Cmd>...<CR>". +The <Cmd> pseudokey begins a "command mapping", which executes the command +directly (without changing modes). Where you might use ":...<CR>" in the +{lhs} of a mapping, you can instead use "<Cmd>...<CR>". Example: > noremap x <Cmd>echo mode(1)<cr> < @@ -284,17 +284,19 @@ This is more flexible than `:<C-U>` in visual and operator-pending mode, or `<C-O>:` in insert-mode, because the commands are executed directly in the current mode (instead of always going to normal-mode). Visual-mode is preserved, so tricks with |gv| are not needed. Commands can be invoked -directly in cmdline-mode (which otherwise would require timer hacks). - -Because <Cmd> avoids mode-changes (unlike ":") it does not trigger -|CmdlineEnter| and |CmdlineLeave| events. This helps performance. +directly in cmdline-mode (which would otherwise require timer hacks). Unlike <expr> mappings, there are no special restrictions on the <Cmd> command: it is executed as if an (unrestricted) |autocmd| was invoked or an async event event was processed. -In select-mode, |:map| and |:vmap| command mappings are executed in -visual-mode. Use |:smap| to handle select-mode. +Note: +- Because <Cmd> avoids mode-changes (unlike ":") it does not trigger + |CmdlineEnter| and |CmdlineLeave| events. This helps performance. +- For the same reason, |keycodes| like <C-R><C-W> are interpreted as plain, + unmapped keys. +- In select-mode, |:map| and |:vmap| command mappings are executed in + visual-mode. Use |:smap| to handle select-mode. *E5520* <Cmd> commands must terminate, that is, they must be followed by <CR> in the diff --git a/runtime/doc/message.txt b/runtime/doc/message.txt index a46648119e..205db12f3b 100644 --- a/runtime/doc/message.txt +++ b/runtime/doc/message.txt @@ -740,11 +740,10 @@ You tried to set an option after startup that only allows changes during startup. *E943* > - Command table needs to be updated, run 'make cmdidxs' + Command table needs to be updated, run 'make' -This can only happen when changing the source code, when adding a command in -src/ex_cmds.h. The lookup table then needs to be updated, by running: > - make cmdidxs +This can only happen when changing the source code, after adding a command in +src/ex_cmds.lua. Update the lookup table by re-running the build. > ============================================================================== 3. Messages *messages* diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt index 84867318a4..d5a123e3ea 100644 --- a/runtime/doc/motion.txt +++ b/runtime/doc/motion.txt @@ -66,10 +66,11 @@ and end position. Generally, motions that move between lines affect lines characterwise). However, there are some exceptions. *exclusive* *inclusive* -A character motion is either inclusive or exclusive. When inclusive, the +Character motion is either inclusive or exclusive. When inclusive, the start and end position of the motion are included in the operation. When exclusive, the last character towards the end of the buffer is not included. -Linewise motions always include the start and end position. +Linewise motions always include the start and end position. Plugins can +check the v:event.inclusive flag of the |TextYankPost| event. Which motions are linewise, inclusive or exclusive is mentioned with the command. There are however, two general exceptions: 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.txt b/runtime/doc/nvim.txt index 07eb48aea3..513d27ccad 100644 --- a/runtime/doc/nvim.txt +++ b/runtime/doc/nvim.txt @@ -8,14 +8,14 @@ Nvim *nvim* *nvim-intro* Nvim is based on Vim by Bram Moolenaar. +If you already use Vim see |nvim-from-vim| for a quickstart. If you are new to Vim, try the 30-minute tutorial: > - :Tutor<Enter> -If you already use Vim see |nvim-from-vim| for a quickstart. + :Tutor<Enter> -Nvim is emphatically a fork of Vim, not a clone: compatibility with Vim is -maintained where possible. See |vim_diff.txt| for the complete reference of -differences from Vim. +Nvim is emphatically a fork of Vim, not a clone: compatibility with Vim +(especially editor and VimL features) is maintained where possible. See +|vim-differences| for the complete reference of differences from Vim. Type |gO| to see the table of contents. diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt index cdcb61404f..aba0571dc0 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 @@ -35,7 +35,7 @@ There are 3 ways to create a terminal buffer: < Note: The "term://" pattern is handled by a BufReadCmd handler, so the |autocmd-nested| modifier is required to use it in an autocmd. > - autocmd VimEnter * nested split term://sh + autocmd VimEnter * ++nested split term://sh < This is only mentioned for reference; use |:terminal| instead. When the terminal starts, the buffer contents are updated and the buffer is @@ -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* @@ -124,4 +131,257 @@ a local 'statusline'. Example: > :autocmd TermOpen * setlocal statusline=%{b:term_title} < ============================================================================== +5. Debugging *terminal-debug* *terminal-debugger* + +The Terminal debugging plugin can be used to debug a program with gdb and view +the source code in a Vim window. Since this is completely contained inside +Vim this also works remotely over an ssh connection. + +Starting ~ + *termdebug-starting* +Load the plugin with this command: > + packadd termdebug +< *:Termdebug* +To start debugging use `:Termdebug` or `:TermdebugCommand` followed by the +command name, for example: > + :Termdebug vim + +This opens two windows: + +gdb window A terminal window in which "gdb vim" is executed. Here you + can directly interact with gdb. The buffer name is "!gdb". + +program window A terminal window for the executed program. When "run" is + used in gdb the program I/O will happen in this window, so + that it does not interfere with controlling gdb. The buffer + name is "gdb program". + +The current window is used to show the source code. When gdb pauses the +source file location will be displayed, if possible. A sign is used to +highlight the current position, using highlight group debugPC. + +If the buffer in the current window is modified, another window will be opened +to display the current gdb position. + +Focus the terminal of the executed program to interact with it. This works +the same as any command running in a terminal window. + +When the debugger ends, typically by typing "quit" in the gdb window, the two +opened windows are closed. + +Only one debugger can be active at a time. + *:TermdebugCommand* +If you want to give specific commands to the command being debugged, you can +use the `:TermdebugCommand` command followed by the command name and +additional parameters. > + :TermdebugCommand vim --clean -c ':set nu' + +Both the `:Termdebug` and `:TermdebugCommand` support an optional "!" bang +argument to start the command right away, without pausing at the gdb window +(and cursor will be in the debugged window). For example: > + :TermdebugCommand! vim --clean + +To attach gdb to an already running executable or use a core file, pass extra +arguments. E.g.: > + :Termdebug vim core + :Termdebug vim 98343 + +If no argument is given, you'll end up in a gdb window, in which you need to +specify which command to run using e.g. the gdb `file` command. + + +Example session ~ + *termdebug-example* +Start in the Vim "src" directory and build Vim: > + % make +Start Vim: > + % ./vim +Load the termdebug plugin and start debugging Vim: > + :packadd termdebug + :Termdebug vim +You should now have three windows: + source - where you started + gdb - you can type gdb commands here + program - the executed program will use this window + +Put focus on the gdb window and type: > + break ex_help + run +Vim will start running in the program window. Put focus there and type: > + :help gui +Gdb will run into the ex_help breakpoint. The source window now shows the +ex_cmds.c file. A red "1 " marker will appear in the signcolumn where the +breakpoint was set. The line where the debugger stopped is highlighted. You +can now step through the program. You will see the highlighting move as the +debugger executes a line of source code. + +Run ":Next" a few times until the for loop is highlighted. Put the cursor on +the end of "eap->arg", then call ":Eval". You will see this displayed: + "eap->arg": 0x555555e68855 "gui" ~ +This way you can inspect the value of local variables. You can also focus the +gdb window and use a "print" command, e.g.: > + print *eap +If mouse pointer movements are working, Vim will also show a balloon when the +mouse rests on text that can be evaluated by gdb. +You can also use the "K" mapping that will either use neovim floating windows +if available to show the results or print below the status bar. + +Now go back to the source window and put the cursor on the first line after +the for loop, then type: > + :Break +You will see a "1" marker appear, this indicates the new breakpoint. Now +run ":Cont" command and the code until the breakpoint will be executed. + +You can type more advanced commands in the gdb window. For example, type: > + watch curbuf +Now run ":Cont" (or type "cont" in the gdb window). Execution +will now continue until the value of "curbuf" changes, which is in do_ecmd(). +To remove this watchpoint again type in the gdb window: > + delete 3 + +You can see the stack by typing in the gdb window: > + where +Move through the stack frames, e.g. with: > + frame 3 +The source window will show the code, at the point where the call was made to +a deeper level. + + +Stepping through code ~ + *termdebug-stepping* +Put focus on the gdb window to type commands there. Some common ones are: +- CTRL-C interrupt the program +- next execute the current line and stop at the next line +- step execute the current line and stop at the next statement, + entering functions +- finish execute until leaving the current function +- where show the stack +- frame N go to the Nth stack frame +- continue continue execution + + *:Run* *:Arguments* +In the window showing the source code these commands can be used to control +gdb: + `:Run` [args] run the program with [args] or the previous arguments + `:Arguments` {args} set arguments for the next `:Run` + + *:Break* set a breakpoint at the current line; a sign will be displayed + *:Clear* delete the breakpoint at the current line + + *:Step* execute the gdb "step" command + *:Over* execute the gdb "next" command (`:Next` is a Vim command) + *:Finish* execute the gdb "finish" command + *:Continue* execute the gdb "continue" command + *:Stop* interrupt the program + +If gdb stops at a source line and there is no window currently showing the +source code, a new window will be created for the source code. This also +happens if the buffer in the source code window has been modified and can't be +abandoned. + +Gdb gives each breakpoint a number. In Vim the number shows up in the sign +column, with a red background. You can use these gdb commands: +- info break list breakpoints +- delete N delete breakpoint N +You can also use the `:Clear` command if the cursor is in the line with the +breakpoint, or use the "Clear breakpoint" right-click menu entry. + + +Inspecting variables ~ + *termdebug-variables* *:Evaluate* + `:Evaluate` evaluate the expression under the cursor + `K` same + `:Evaluate` {expr} evaluate {expr} + `:'<,'>Evaluate` evaluate the Visually selected text + +This is similar to using "print" in the gdb window. +You can usually shorten `:Evaluate` to `:Ev`. + + +Other commands ~ + *termdebug-commands* + *:Gdb* jump to the gdb window + *:Program* jump to the window with the running program + *:Source* jump to the window with the source code, create it if there + isn't one + + +Communication ~ + *termdebug-communication* +There is another, hidden, buffer, which is used for Vim to communicate with +gdb. The buffer name is "gdb communication". Do not delete this buffer, it +will break the debugger. + +Gdb has some weird behavior, the plugin does its best to work around that. +For example, after typing "continue" in the gdb window a CTRL-C can be used to +interrupt the running program. But after using the MI command +"-exec-continue" pressing CTRL-C does not interrupt. Therefore you will see +"continue" being used for the `:Continue` command, instead of using the +communication channel. + + +Customizing ~ + +GDB command *termdebug-customizing* + +To change the name of the gdb command, set the "termdebugger" variable before +invoking `:Termdebug`: > + let termdebugger = "mygdb" + +To not use neovim floating windows for previewing variable evaluation, set the +`g:termdebug_useFloatingHover` variable like this: > + let g:termdebug_useFloatingHover = 0 + +If you are a mouse person, you can also define a mapping using your right +click to one of the terminal command like evaluate the variable under the +cursor: > + nnoremap <RightMouse> :Evaluate<CR> +or set/unset a breakpoint: > + nnoremap <RightMouse> :Break<CR> + +< *gdb-version* +Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI +interface. The "new-ui" command requires gdb version 7.12 or later. if you +get this error: + Undefined command: "new-ui". Try "help".~ +Then your gdb is too old. + + +Colors *hl-debugPC* *hl-debugBreakpoint* + +The color of the signs can be adjusted with these highlight groups: +- debugPC the current position +- debugBreakpoint a breakpoint + +The defaults are, when 'background' is "light": + hi debugPC term=reverse ctermbg=lightblue guibg=lightblue + hi debugBreakpoint term=reverse ctermbg=red guibg=red + +When 'background' is "dark": + hi debugPC term=reverse ctermbg=darkblue guibg=darkblue + hi debugBreakpoint term=reverse ctermbg=red guibg=red + + +Shorcuts *termdebug_shortcuts* + +You can define your own shortcuts (mappings) to control gdb, that can work in +any window, using the TermDebugSendCommand() function. Example: > + map ,w :call TermDebugSendCommand('where')<CR> +The argument is the gdb command. + + +Vim window width *termdebug_wide* + +To change the width of the Vim window when debugging starts, and use a +vertical split: > + let g:termdebug_wide = 163 +This will set &columns to 163 when `:Termdebug` is used. The value is restored +when quitting the debugger. +If g:termdebug_wide is set and &columns is already larger than +g:termdebug_wide then a vertical split will be used without changing &columns. +Set it to 1 to get a vertical split without every changing &columns (useful +for when the terminal can't be resized by Vim). + + + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 505c0c5ea0..cce9f681f9 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -694,8 +694,9 @@ A jump table for the options with a short description can be found at |Q_op|. *'background'* *'bg'* 'background' 'bg' string (default "dark") global - When set to "dark" or "light", Nvim will adjust the default color - groups for a dark or light background, respectively. + When set to "dark" or "light", adjusts the default color groups for + that background type. The |TUI| or other UI sets this on startup + (triggering |OptionSet|) if it can detect the background color. This option does NOT change the background color, it tells Nvim what the "inherited" (terminal/GUI) background looks like. @@ -878,7 +879,7 @@ A jump table for the options with a short description can be found at |Q_op|. A list of file patterns. When one of the patterns matches with the name of the file which is written, no backup file is created. Both the specified file name and the full path name of the file are used. - The pattern is used like with |:autocmd|, see |autocmd-patterns|. + The pattern is used like with |:autocmd|, see |autocmd-pattern|. Watch out for special characters, see |option-backslash|. When $TMPDIR, $TMP or $TEMP is not defined, it is not used for the default value. "/tmp/*" is only used for Unix. @@ -1214,7 +1215,7 @@ A jump table for the options with a short description can be found at |Q_op|. This option is not used when 'paste' is set. *'cinkeys'* *'cink'* -'cinkeys' 'cink' string (default "0{,0},0),:,0#,!^F,o,O,e") +'cinkeys' 'cink' string (default "0{,0},0),0],:,0#,!^F,o,O,e") local to buffer A list of keys that, when typed in Insert mode, cause reindenting of the current line. Only used if 'cindent' is on and 'indentexpr' is @@ -1831,9 +1832,9 @@ A jump table for the options with a short description can be found at |Q_op|. name. See |option-backslash| about using backslashes. This has nothing to do with the |Dictionary| variable type. Where to find a list of words? - - On FreeBSD, there is the file "/usr/share/dict/words". - - In the Simtel archive, look in the "msdos/linguist" directory. - - In "miscfiles" of the GNU collection. + - BSD/macOS include the "/usr/share/dict/words" file. + - Try "apt install spell" to get the "/usr/share/dict/words" file on + apt-managed systems (Debian/Ubuntu). The use of |:set+=| and |:set-=| is preferred when adding or removing directories from the list. This avoids problems when a future version uses another default. @@ -3265,7 +3266,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'indentkeys'* *'indk'* -'indentkeys' 'indk' string (default "0{,0},:,0#,!^F,o,O,e") +'indentkeys' 'indk' string (default "0{,0},0),0],:,0#,!^F,o,O,e") local to buffer A list of keys that, when typed in Insert mode, cause reindenting of the current line. Only happens if 'indentexpr' isn't empty. @@ -4527,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) @@ -4658,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, … @@ -4671,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| @@ -4693,25 +4696,27 @@ A jump table for the options with a short description can be found at |Q_op|. pack/ packages |:packadd| plugin/ plugin scripts |write-plugin| print/ files for printing |postscript-print-encoding| + rplugin/ |remote-plugin| scripts spell/ spell checking files |spell| syntax/ syntax files |mysyntaxfile| tutor/ tutorial files |:Tutor| 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 @@ -4998,9 +5003,9 @@ A jump table for the options with a short description can be found at |Q_op|. has been used since the last search command. *shada-n* n Name of the shada file. The name must immediately follow - the 'n'. Must be at the end of the option! If the "-i" - argument was given when starting Vim, that file name overrides - the one given here with 'shada'. Environment variables are + the 'n'. Must be at the end of the option! If the + 'shadafile' option is set, that file name overrides the one + given here with 'shada'. Environment variables are expanded when opening the file, not when setting the option. *shada-r* r Removable media. The argument is a string (up to the next @@ -5042,6 +5047,14 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. + *'shadafile'* *'sdf'* +'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. + This option can be set with the |-i| command line flag. The |--clean| + command line flag sets it to "NONE". + *'shell'* *'sh'* *E91* 'shell' 'sh' string (default $SHELL or "sh", Windows: "cmd.exe") @@ -5403,10 +5416,14 @@ A jump table for the options with a short description can be found at |Q_op|. *'signcolumn'* *'scl'* 'signcolumn' 'scl' string (default "auto") local to window - Whether or not to draw the signcolumn. Valid values are: + When and how to draw the signcolumn. Valid values are: "auto" only when there is a sign to display + "auto:[1-9]" resize to accommodate multiple signs up to the + given number (maximum 9), e.g. "auto:4" "no" never "yes" always + "yes:[1-9]" always, with fixed space for signs up to the given + number (maximum 9), e.g. "yes:3" *'smartcase'* *'scs'* *'nosmartcase'* *'noscs'* @@ -5555,7 +5572,7 @@ A jump table for the options with a short description can be found at |Q_op|. After this option has been set successfully, Vim will source the files "spell/LANG.vim" in 'runtimepath'. "LANG" is the value of 'spelllang' - up to the first comma, dot or underscore. + up to the first character that is not an ASCII letter and not a dash. Also see |set-spc-auto|. @@ -5816,7 +5833,7 @@ A jump table for the options with a short description can be found at |Q_op|. Watch out for errors in expressions. They may render Vim unusable! If you are stuck, hold down ':' or 'Q' to get a prompt, then quit and - edit your vimrc or whatever with "vim -u NONE" to get it right. + edit your vimrc or whatever with "vim --clean" to get it right. Examples: Emulate standard status line with 'ruler' set > @@ -6114,17 +6131,16 @@ 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) global When set: Add 's' flag to 'shortmess' option (this makes the message for a search that hits the start or end of the file not being - displayed). When reset: Remove 's' flag from 'shortmess' option. {Vi - shortens a lot of messages} + displayed). When reset: Remove 's' flag from 'shortmess' option. *'textwidth'* *'tw'* 'textwidth' 'tw' number (default 0) @@ -6146,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. @@ -6502,7 +6516,7 @@ A jump table for the options with a short description can be found at |Q_op|. patterns is ignored when expanding |wildcards|, completing file or directory names, and influences the result of |expand()|, |glob()| and |globpath()| unless a flag is passed to disable this. - The pattern is used like with |:autocmd|, see |autocmd-patterns|. + The pattern is used like with |:autocmd|, see |autocmd-pattern|. Also see 'suffixes'. Example: > :set wildignore=*.o,*.obj @@ -6599,12 +6613,13 @@ A jump table for the options with a short description can be found at |Q_op|. 'wildoptions' 'wop' string (default "") global A list of words that change how command line completion is done. - Currently only one word is allowed: tagfile When using CTRL-D to list matching tags, the kind of tag and the file of the tag is listed. Only one match is displayed per line. Often used tag kinds are: d #define f function + pum Display the completion matches using the popupmenu + in the same style as the |ins-completion-menu|. Also see |cmdline-completion|. *'winaltkeys'* *'wak'* diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt index 09fdc6872b..364fbac351 100644 --- a/runtime/doc/provider.txt +++ b/runtime/doc/provider.txt @@ -26,29 +26,34 @@ Nvim supports Python |remote-plugin|s and the Vim legacy |python2| and Note: Only the Vim 7.3 legacy interface is supported, not later features such as |python-bindeval| (Vim 7.4); use the Nvim API instead. + PYTHON QUICKSTART ~ -Install the "pynvim" Python package: +To use Python plugins, you need the "pynvim" module. Run |:checkhealth| to see +if you already have it (some package managers install the module with Nvim +itself). + +For Python 3 plugins: +1. Make sure Python 3.4+ is available in your $PATH. +2. Install the module (try "python" if "python3" is missing): > + python3 -m pip install --user --upgrade pynvim + +For Python 2 plugins: +1. Make sure Python 2.7 is available in your $PATH. +2. Install the module (try "python" if "python2" is missing): > + python2 -m pip install --user --upgrade pynvim -- Run |:checkhealth| to see if you already have the package (some package - managers install the "pynvim" Python package with Nvim itself). +The pip `--upgrade` flag ensures that you get the latest version even if +a previous version was already installed. -- For Python 2 plugins, make sure Python 2.7 is available in your $PATH, then - install the package systemwide: > - sudo pip2 install --upgrade pynvim -< or for the current user: > - pip2 install --user --upgrade pynvim -< If "pip2" is missing, try "pip". +See also |python-virtualenv|. -- For Python 3 plugins, make sure Python 3.4+ is available in your $PATH, then - install the package systemwide: > - sudo pip3 install --upgrade pynvim -< or for the current user: > - pip3 install --user --upgrade pynvim -< If "pip3" is missing, try "pip". +Note: The old "neovim" module was renamed to "pynvim". +https://github.com/neovim/neovim/wiki/Following-HEAD#20181118 +If you run into problems, uninstall _both_ then install "pynvim" again: > + python -m pip uninstall neovim pynvim + python -m pip install --user --upgrade pynvim -- The `--upgrade` flag ensures you have the latest version even if a previous - version was already installed. PYTHON PROVIDER CONFIGURATION ~ *g:python_host_prog* @@ -69,8 +74,9 @@ To disable Python 2 support: > To disable Python 3 support: > let g:loaded_python3_provider = 1 -PYTHON VIRTUALENVS ~ +PYTHON VIRTUALENVS ~ + *python-virtualenv* If you plan to use per-project virtualenvs often, you should assign one virtualenv for Neovim and hard-code the interpreter path via |g:python3_host_prog| (or |g:python_host_prog|) so that the "pynvim" package @@ -93,6 +99,7 @@ Ruby integration *provider-ruby* Nvim supports Ruby |remote-plugin|s and the Vim legacy |ruby-vim| interface (which is itself implemented as a Nvim remote-plugin). + RUBY QUICKSTART ~ To use Ruby plugins with Nvim, install the latest "neovim" RubyGem: > @@ -100,6 +107,7 @@ To use Ruby plugins with Nvim, install the latest "neovim" RubyGem: > Run |:checkhealth| to see if your system is up-to-date. + RUBY PROVIDER CONFIGURATION ~ *g:loaded_ruby_provider* To disable Ruby support: > @@ -122,6 +130,7 @@ Node.js integration *provider-nodejs* Nvim supports Node.js |remote-plugin|s. https://github.com/neovim/node-client/ + NODEJS QUICKSTART~ To use javascript remote-plugins with Nvim, install the "neovim" npm package: > @@ -129,6 +138,7 @@ To use javascript remote-plugins with Nvim, install the "neovim" npm package: > Run |:checkhealth| to see if your system is up-to-date. + NODEJS PROVIDER CONFIGURATION~ *g:loaded_node_provider* To disable Node.js support: > 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/quickref.txt b/runtime/doc/quickref.txt index da064ab89b..d3d9303d3c 100644 --- a/runtime/doc/quickref.txt +++ b/runtime/doc/quickref.txt @@ -857,7 +857,7 @@ Short explanation of each option: *option-list* 'showtabline' 'stal' tells when the tab pages line is displayed 'sidescroll' 'ss' minimum number of columns to scroll horizontal 'sidescrolloff' 'siso' min. nr. of columns to left and right of cursor -'signcolumn' 'scl' when to display the sign column +'signcolumn' 'scl' when and how to display the sign column 'smartcase' 'scs' no ignore case when pattern has uppercase 'smartindent' 'si' smart autoindenting for C programs 'smarttab' 'sta' use 'shiftwidth' when inserting <Tab> diff --git a/runtime/doc/remote_plugin.txt b/runtime/doc/remote_plugin.txt index 6a9874660b..4cdcbed250 100644 --- a/runtime/doc/remote_plugin.txt +++ b/runtime/doc/remote_plugin.txt @@ -122,10 +122,10 @@ the example, say the Java plugin is a semantic completion engine for Java code. If it defines the autocommand "BufEnter *.java", then the Java host is spawned only when Nvim loads a buffer matching "*.java". -If the explicit call to |:UpdateRemotePlugins| seems incovenient, try to see it -like this: It's a way to provide IDE capabilities in Nvim while still keeping -it fast and lightweight for general use. It's also analogous to the |:helptags| -command. +If the explicit call to |:UpdateRemotePlugins| seems inconvenient, try to see +it like this: It's a way to provide IDE capabilities in Nvim while still +keeping it fast and lightweight for general use. It's also analogous to the +|:helptags| command. *$NVIM_RPLUGIN_MANIFEST* Unless $NVIM_RPLUGIN_MANIFEST is set the manifest will be written to a file 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 88aa4121e4..2a230d9449 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -86,6 +86,11 @@ argument. |:version| command. See |info-message| about capturing the text. + *--clean* +--clean Equivalent to "-u NONE -i NONE": + - Skips initializations from files and environment variables. + - No 'shada' file is read or written. + *--noplugin* --noplugin Skip loading plugins. Resets the 'loadplugins' option. Note that the |-u| argument may also disable loading plugins: @@ -190,33 +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|). - |$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' @@ -255,7 +260,7 @@ argument. {not available when compiled without the |+eval| feature} *-n* --n No swap file will be used. Recovery after a crash will be +-n No |swap-file| will be used. Recovery after a crash will be impossible. Handy if you want to view or edit a file on a very slow medium (e.g., a floppy). Can also be done with ":set updatecount=0". You can switch it @@ -294,19 +299,21 @@ argument. *-u* *E282* -u {vimrc} The file {vimrc} is read for initializations. Most other - initializations are skipped; see |initialization|. This can - be used to start Vim in a special mode, with special + initializations are skipped; see |initialization|. + + This can be used to start Vim in a special mode, with special mappings and settings. A shell alias can be used to make this easy to use. For example: > alias vimc vim -u ~/.config/nvim/c_init.vim !* < Also consider using autocommands; see |autocommand|. - When {vimrc} is equal to "NONE" (all uppercase), all - initializations from files and environment variables are - skipped, including reading the |ginit.vim| file when the GUI - starts. Plugins and syntax highlighting are also skipped. - When {vimrc} is equal to "NORC" (all uppercase), this has the - same effect as "NONE", but plugins and syntax highlighting are - not skipped. + + When {vimrc} is "NONE" (all uppercase), all initializations + from files and environment variables are skipped. Plugins and + syntax highlighting are also skipped. + + When {vimrc} is "NORC" (all uppercase), this has the same + effect as "NONE", but plugins and syntax highlighting are not + skipped. *-i* -i {shada} The file {shada} is used instead of the default ShaDa @@ -347,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. > @@ -481,6 +486,7 @@ accordingly. Vim proceeds in this order: Loading plugins won't be done when: - The 'loadplugins' option was reset in a vimrc file. - The |--noplugin| command line argument is used. + - The |--clean| command line argument is used. - The "-u NONE" command line argument is used |-u|. - When Vim was compiled without the |+eval| feature. Note that using "-c 'set noloadplugins'" doesn't work, because the @@ -1075,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/syntax.txt b/runtime/doc/syntax.txt index 684830b78d..b60a952def 100644 --- a/runtime/doc/syntax.txt +++ b/runtime/doc/syntax.txt @@ -4953,6 +4953,8 @@ NonText '@' at the end of the window, characters from 'showbreak' fit at the end of the line). See also |hl-EndOfBuffer|. *hl-Normal* Normal normal text + *hl-NormalFloat* +NormalFloat Normal text in floating windows. *hl-NormalNC* NormalNC normal text in non-current windows *hl-Pmenu* diff --git a/runtime/doc/tagsrch.txt b/runtime/doc/tagsrch.txt index 367da7750e..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. @@ -498,28 +501,21 @@ gnatxref For Ada. See http://www.gnuada.org/. gnatxref is part of the gnat package. -The lines in the tags file must have one of these three formats: +The lines in the tags file must have one of these two formats: 1. {tagname} {TAB} {tagfile} {TAB} {tagaddress} -2. {tagfile}:{tagname} {TAB} {tagfile} {TAB} {tagaddress} -3. {tagname} {TAB} {tagfile} {TAB} {tagaddress} {term} {field} .. +2. {tagname} {TAB} {tagfile} {TAB} {tagaddress} {term} {field} .. + +Previously an old format was supported, see |tag-old-static|. -The first is a normal tag, which is completely compatible with Vi. It is the -only format produced by traditional ctags implementations. This is often used -for functions that are global, also referenced in other files. +The first format is a normal tag, which is completely compatible with Vi. It +is the only format produced by traditional ctags implementations. This is +often used for functions that are global, also referenced in other files. The lines in the tags file can end in <LF> or <CR><LF>. On the Macintosh <CR> also works. The <CR> and <NL> characters can never appear inside a line. - *tag-old-static* -The second format is for a static tag only. It is obsolete now, replaced by -the third format. It is only supported by Elvis 1.x and Vim and a few -versions of ctags. A static tag is often used for functions that are local, -only referenced in the file {tagfile}. Note that for the static tag, the two -occurrences of {tagfile} must be exactly the same. Also see |tags-option| -below, for how static tags are used. - -The third format is new. It includes additional information in optional +The second format is new. It includes additional information in optional fields at the end of each line. It is backwards compatible with Vi. It is only supported by new versions of ctags (such as Exuberant ctags). @@ -561,6 +557,7 @@ only supported by new versions of ctags (such as Exuberant ctags). The only other field currently recognized by Vim is "file:" (with an empty value). It is used for a static tag. + The first lines in the tags file can contain lines that start with !_TAG_ These are sorted to the first lines, only rare tags that start with "!" can @@ -613,6 +610,21 @@ If the command is a normal search command (it starts and ends with "/" or followed by white space and a '('. This will find macro names and function names with a type prepended. + + *tag-old-static* +Until March 2019 (patch 8.1.1092) an outdated format was supported: + {tagfile}:{tagname} {TAB} {tagfile} {TAB} {tagaddress} + +This format is for a static tag only. It is obsolete now, replaced by +the second format. It is only supported by Elvis 1.x, older Vim versions and +a few versions of ctags. A static tag is often used for functions that are +local, only referenced in the file {tagfile}. Note that for the static tag, +the two occurrences of {tagfile} must be exactly the same. Also see +|tags-option| below, for how static tags are used. + +The support was removed, since when you can update to the new Vim version you +should also be able to update ctags to one that supports the second format. + ============================================================================== 6. Include file searches *include-search* *definition-search* *E387* *E388* *E389* diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt index 270c4fb556..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. |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` @@ -325,9 +349,13 @@ numerical highlight `id`:s to the actual attributes. indicates the visible cursor position. ["grid_scroll", grid, top, bot, left, right, rows, cols] - Scroll the text in the a region of `grid`. The diagrams below illustrate - what will happen, depending on the scroll direction. "=" is used to - represent the SR(scroll region) boundaries and "-" the moved rectangles. + Scroll a region of `grid`. This is semantically unrelated to editor + |scrolling|, rather this is an optimized way to say "copy these screen + cells". + + The following diagrams show what happens per scroll direction. + "===" represents the SR (scroll region) boundaries. + "---" represents the moved rectangles. Note that dst and src share a common region. If `rows` is bigger than 0, move a rectangle in the SR up, this can @@ -368,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. @@ -403,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. @@ -458,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 @@ -472,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. @@ -493,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. @@ -528,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] @@ -547,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 @@ -564,7 +592,9 @@ Only sent if `ext_popupmenu` option is set in |ui-options| index into the array of items (-1 if no item is selected). `row` and `col` give the anchor position, where the first character of the completed word will be. When |ui-multigrid| is used, `grid` is the - grid for the anchor position. + grid for the anchor position. When `ext_cmdline` is active, `grid` is + set to -1 to indicate the popupmenu should be anchored to the external + cmdline. Then `col` will be a byte position in the cmdline text. ["popupmenu_select", selected] Select an item in the current popupmenu. `selected` is a zero-based @@ -577,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 @@ -588,7 +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|. +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] @@ -644,64 +677,49 @@ Only sent if `ext_cmdline` option is set in |ui-options|. Hide the block. ============================================================================== -Wildmenu Events *ui-wildmenu* - -Only sent if `ext_wildmenu` option is set in |ui-options| - -["wildmenu_show", items] - Activate the wildmenu (command-line completion). `items` is an array - with the completion items. - -["wildmenu_select", selected] - Select an item in the current wildmenu. `selected` is a zero-based - index into the array of items from the last wildmenu_show event, or -1 - if no item is selected. - -["wildmenu_hide"] - Hide the wildmenu. - -============================================================================== -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_40.txt b/runtime/doc/usr_40.txt index e5d55fb857..9a1fe50f31 100644 --- a/runtime/doc/usr_40.txt +++ b/runtime/doc/usr_40.txt @@ -453,15 +453,15 @@ matching BufWritePre autocommands and executes them, and then it performs the ":write". The general form of the :autocmd command is as follows: > - :autocmd [group] {events} {file_pattern} [nested] {command} + :autocmd [group] {events} {file_pattern} [++nested] {command} The [group] name is optional. It is used in managing and calling the commands (more on this later). The {events} parameter is a list of events (comma separated) that trigger the command. {file_pattern} is a filename, usually with wildcards. For example, using "*.txt" makes the autocommand be used for all files whose name end in ".txt". -The optional [nested] flag allows for nesting of autocommands (see below), and -finally, {command} is the command to be executed. +The optional [++nested] flag allows for nesting of autocommands (see below), +and finally, {command} is the command to be executed. EVENTS @@ -576,9 +576,9 @@ NESTING Generally, commands executed as the result of an autocommand event will not trigger any new events. If you read a file in response to a FileChangedShell event, it will not trigger the autocommands that would set the syntax, for -example. To make the events triggered, add the "nested" argument: > +example. To make the events triggered, add the "++nested" flag: > - :autocmd FileChangedShell * nested edit + :autocmd FileChangedShell * ++nested edit EXECUTING AUTOCOMMANDS diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt index 4adb69aaee..87164c8d90 100644 --- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -806,6 +806,7 @@ Buffers, windows and the argument list: getbufinfo() get a list with buffer information gettabinfo() get a list with tab page information getwininfo() get a list with window information + getjumplist() get a list of jump list entries Command line: *command-line-functions* getcmdline() get the current command line @@ -825,6 +826,7 @@ Insert mode completion: *completion-functions* complete() set found matches complete_add() add to found matches complete_check() check if completion should be aborted + complete_info() get current completion information pumvisible() check if the popup menu is displayed Folding: *folding-functions* @@ -956,6 +958,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/usr_43.txt b/runtime/doc/usr_43.txt index 04e9f9c000..15c94cd15e 100644 --- a/runtime/doc/usr_43.txt +++ b/runtime/doc/usr_43.txt @@ -94,7 +94,7 @@ unless it was set already. This will make sure that 'filetype' isn't set twice. You can use many different patterns to match the name of your file. Directory -names can also be included. See |autocmd-patterns|. For example, the files +names can also be included. See |autocmd-pattern|. For example, the files under "/usr/share/scripts/" are all "ruby" files, but don't have the expected file name extension. Adding this to the example above: > diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt index 2b8ba56c28..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,143 +270,15 @@ 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}". *:ve* *:version* -:ve[rsion] Print the version number of the editor. The following - lines contain information about which features were - enabled when Vim was compiled. When there is a - preceding '+', the feature is included, when there is - a '-' it is excluded. To change this, you have to - edit feature.h and recompile Vim. To check for this - in an expression, see |has()|. Here is an overview of - the features. The first column shows the smallest - version in which they are included: - T tiny - S small - N normal - B big - H huge - m manually enabled or depends on other features - (none) system dependent - Thus if a feature is marked with "N", it is included - in the normal, big and huge versions of Vim. - - *+feature-list* - *+acl* |ACL| support included -B *+arabic* |Arabic| language support -N *+autocmd* |:autocmd|, automatic commands -N *+browse* |:browse| command -N *+byte_offset* support for 'o' flag in 'statusline' option, "go" - and ":goto" commands. -N *+cindent* |'cindent'|, C indenting -N *+clientserver* Unix and Win32: Remote invocation |clientserver| - *+clipboard* |clipboard| support -N *+cmdline_compl* command line completion |cmdline-completion| -S *+cmdline_hist* command line history |cmdline-history| -N *+cmdline_info* |'showcmd'| and |'ruler'| -N *+comments* |'comments'| support -B *+conceal* "conceal" support, see |conceal| |:syn-conceal| etc. -B *+cscope* |cscope| support -m *+cursorbind* |'cursorbind'| support -m *+debug* Compiled for debugging. -N *+dialog_gui* Support for |:confirm| with GUI dialog. -N *+dialog_con* Support for |:confirm| with console dialog. -N *+dialog_con_gui* Support for |:confirm| with GUI and console dialog. -N *+digraphs* |digraphs| *E196* -N *+eval* expression evaluation |eval.txt| -N *+ex_extra* always on now, used to be for Vim's extra Ex commands -N *+extra_search* |'hlsearch'| and |'incsearch'| options. -N *+file_in_path* |gf|, |CTRL-W_f| and |<cfile>| -N *+find_in_path* include file searches: |[I|, |:isearch|, - |CTRL-W_CTRL-I|, |:checkpath|, etc. -N *+folding* |folding| -N *+gettext* message translations |multi-lang| - *+iconv* Compiled with the |iconv()| function - *+iconv/dyn* Likewise |iconv-dynamic| |/dyn| -N *+insert_expand* |insert_expand| Insert mode completion -S *+jumplist* |jumplist| -B *+keymap* |'keymap'| -N *+lambda* |lambda| and |closure| -B *+langmap* |'langmap'| -N *+libcall* |libcall()| -N *+linebreak* |'linebreak'|, |'breakat'| and |'showbreak'| -N *+lispindent* |'lisp'| -N *+listcmds* Vim commands for the list of buffers |buffer-hidden| - and argument list |:argdelete| -N *+localmap* Support for mappings local to a buffer |:map-local| -N *+menu* |:menu| -N *+mksession* |:mksession| -N *+modify_fname* |filename-modifiers| -N *+mouse* Mouse handling |mouse-using| -N *+mouseshape* |'mouseshape'| -N *+multi_byte* 16 and 32 bit characters |multibyte| - *+multi_byte_ime* Win32 input method for multibyte chars |multibyte-ime| -N *+multi_lang* non-English language support |multi-lang| - *+num64* 64-bit Number support |Number| -N *+path_extra* Up/downwards search in 'path' and 'tags' -N *+persistent_undo* Persistent undo |undo-persistence| - *+postscript* |:hardcopy| writes a PostScript file -N *+printer* |:hardcopy| command -H *+profile* |:profile| command -m *+python* Python 2 interface |python| -m *+python3* Python 3 interface |python| -N *+quickfix* |:make| and |quickfix| commands -N *+reltime* |reltime()| function, 'hlsearch'/'incsearch' timeout, - 'redrawtime' option -B *+rightleft* Right to left typing |'rightleft'| -N *+scrollbind* |'scrollbind'| -N *+shada* |'shada'| -B *+signs* |:sign| -N *+smartindent* |'smartindent'| -N *+startuptime* |--startuptime| argument -N *+statusline* Options 'statusline', 'rulerformat' and special - formats of 'titlestring' and 'iconstring' -N *+syntax* Syntax highlighting |syntax| -N *+tablineat* 'tabline' option recognizing %@Func@ items. -T *+tag_binary* binary searching in tags file |tag-binary-search| -N *+tag_old_static* old method for static tags |tag-old-static| -m *+tag_any_white* any white space allowed in tags file |tag-any-white| -B *+termguicolors* 24-bit color in xterm-compatible terminals support -N *+termresponse* support for t_RV and |v:termresponse| -N *+textobjects* |text-objects| selection -N *+timers* the |timer_start()| function -N *+title* Setting the window 'title' and 'icon' -N *+toolbar* |gui-toolbar| -N *+user_commands* User-defined commands. |user-commands| - *+vertsplit* Vertically split windows |:vsplit| -N *+virtualedit* |'virtualedit'| -S *+visual* Visual mode |Visual-mode| Always enabled since 7.4.200. -N *+visualextra* extra Visual mode commands |blockwise-operators| -N *+vreplace* |gR| and |gr| - *+vtp* on MS-Windows console: support for 'termguicolors' -N *+wildignore* |'wildignore'| -N *+wildmenu* |'wildmenu'| - *+windows* more than one window -m *+writebackup* |'writebackup'| is default on -m *+xim* X input method |xim| - *+xfontset* X fontset support |xfontset| - *+xpm* pixmap support - - */dyn* *E370* *E448* - To some of the features "/dyn" is added when the - feature is only available when the related library can - be dynamically loaded. - -:ve[rsion] {nr} Is now ignored. This was previously used to check the - version number of a .vimrc file. It was removed, - because you can now use the ":if" command for - version-dependent behavior. +:ve[rsion] Print editor version and build information. + See also |feature-compile|. *:redi* *:redir* :redi[r][!] > {file} Redirect messages to file {file}. The messages which diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index 25ca2974bc..b7974aa735 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -6,8 +6,9 @@ Differences between Nvim and Vim *vim-differences* -Nvim differs from Vim in many ways, big and small. This document is -a complete and centralized reference of those differences. +Nvim differs from Vim in many ways, although editor and VimL features are +mostly identical. This document is a complete and centralized reference of +the differences. Type |gO| to see the table of contents. @@ -133,7 +134,7 @@ Command-line highlighting: removed in the future). Commands: - |:autocmd| accepts the `once` flag + |:autocmd| accepts the `++once` flag |:checkhealth| |:cquit| can use [count] to set the exit code |:drop| is always available @@ -161,6 +162,7 @@ Functions: Highlight groups: |expr-highlight| highlight groups (prefixed with "Nvim") + |hl-NormalFloat| highlights floating window |hl-NormalNC| highlights non-current windows |hl-MsgSeparator| highlights separator for scrolled messages |hl-QuickFixLine| @@ -192,10 +194,15 @@ Options: 'listchars' local to window 'pumblend' pseudo-transparent popupmenu 'scrollback' + 'signcolumn' supports up to 9 dynamic/fixed columns 'statusline' supports unlimited alignment sections 'tabline' %@Func@foo%X can call any function on mouse-click + 'wildoptions' `pum` flag to use popupmenu for wildmode completion 'winhighlight' window-local highlights +Signs: + Signs are removed if the associated line is deleted. + Variables: |v:event| |v:exiting| @@ -312,6 +319,9 @@ Macro/|recording| behavior macros and 'keymap' at the same time. This also means you can use |:imap| on the results of keys from 'keymap'. +Motion: + The |jumplist| avoids useless/phantom jumps. + Normal commands: |Q| is the same as |gQ| @@ -336,7 +346,10 @@ Shell: Startup: |-e| and |-es| invoke the same "improved Ex mode" as -E and -Es. - |-E| and |-Es| reads stdin as text (into buffer 1). + |-E| and |-Es| read stdin as text (into buffer 1). + |-es| and |-Es| have improved behavior: + - Quits automatically, don't need "-c qa!". + - Skips swap-file dialog. |-s| reads Normal commands from stdin if the script name is "-". Reading text (instead of commands) from stdin |--|: - works by default: "-" file is optional diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt index 6e1ad0f1f4..63ffd91bfc 100644 --- a/runtime/doc/windows.txt +++ b/runtime/doc/windows.txt @@ -880,15 +880,15 @@ CTRL-W g } *CTRL-W_g}* cursor. This is less clever than using |:ptag|, but you don't need a tags file and it will also find matches in system include files. Example: > - :au! CursorHold *.[ch] nested exe "silent! psearch " . expand("<cword>") + :au! CursorHold *.[ch] ++nested exe "silent! psearch " . expand("<cword>") < Warning: This can be slow. Example *CursorHold-example* > - :au! CursorHold *.[ch] nested exe "silent! ptag " . expand("<cword>") + :au! CursorHold *.[ch] ++nested exe "silent! ptag " . expand("<cword>") This will cause a ":ptag" to be executed for the keyword under the cursor, -when the cursor hasn't moved for the time set with 'updatetime'. The "nested" +when the cursor hasn't moved for the time set with 'updatetime'. "++nested" makes other autocommands be executed, so that syntax highlighting works in the preview window. The "silent!" avoids an error message when the tag could not be found. Also see |CursorHold|. To disable this again: > @@ -898,7 +898,7 @@ be found. Also see |CursorHold|. To disable this again: > A nice addition is to highlight the found tag, avoid the ":ptag" when there is no word under the cursor, and a few other things: > - :au! CursorHold *.[ch] nested call PreviewWord() + :au! CursorHold *.[ch] ++nested call PreviewWord() :func PreviewWord() : if &previewwindow " don't do this in the preview window : return diff --git a/runtime/filetype.vim b/runtime/filetype.vim index a4d46fd842..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 @@ -1458,9 +1458,11 @@ au BufNewFile,BufRead sgml.catalog* call s:StarSetf('catalog') " Shell scripts (sh, ksh, bash, bash2, csh); Allow .profile_foo etc. " Gentoo ebuilds and Arch Linux PKGBUILDs are actually bash scripts -au BufNewFile,BufRead .bashrc*,bashrc,bash.bashrc,.bash[_-]profile*,.bash[_-]logout*,.bash[_-]aliases*,bash-fc[-.]*,*.bash,*/{,.}bash[_-]completion{,.d,.sh}{,/*},*.ebuild,*.eclass,PKGBUILD* call dist#ft#SetFileTypeSH("bash") -au BufNewFile,BufRead .kshrc*,*.ksh call dist#ft#SetFileTypeSH("ksh") -au BufNewFile,BufRead */etc/profile,.profile*,*.sh,*.env call dist#ft#SetFileTypeSH(getline(1)) +" NOTE: Patterns ending in a star are further down, these have lower priority. +au BufNewFile,BufRead .bashrc,bashrc,bash.bashrc,.bash[_-]profile,.bash[_-]logout,.bash[_-]aliases,bash-fc[-.],*.bash,*/{,.}bash[_-]completion{,.d,.sh}{,/*},*.ebuild,*.eclass,PKGBUILD call dist#ft#SetFileTypeSH("bash") +au BufNewFile,BufRead .kshrc,*.ksh call dist#ft#SetFileTypeSH("ksh") +au BufNewFile,BufRead */etc/profile,.profile,*.sh,*.env call dist#ft#SetFileTypeSH(getline(1)) + " Shell script (Arch Linux) or PHP file (Drupal) au BufNewFile,BufRead *.install @@ -1470,15 +1472,16 @@ au BufNewFile,BufRead *.install \ call dist#ft#SetFileTypeSH("bash") | \ endif -" tcsh scripts -au BufNewFile,BufRead .tcshrc*,*.tcsh,tcsh.tcshrc,tcsh.login call dist#ft#SetFileTypeShell("tcsh") +" tcsh scripts (patterns ending in a star further below) +au BufNewFile,BufRead .tcshrc,*.tcsh,tcsh.tcshrc,tcsh.login call dist#ft#SetFileTypeShell("tcsh") " csh scripts, but might also be tcsh scripts (on some systems csh is tcsh) -au BufNewFile,BufRead .login*,.cshrc*,csh.cshrc,csh.login,csh.logout,*.csh,.alias call dist#ft#CSH() +" (patterns ending in a start further below) +au BufNewFile,BufRead .login,.cshrc,csh.cshrc,csh.login,csh.logout,*.csh,.alias call dist#ft#CSH() -" Z-Shell script +" Z-Shell script (patterns ending in a star further below) au BufNewFile,BufRead .zprofile,*/etc/zprofile,.zfbfmarks setf zsh -au BufNewFile,BufRead .zsh*,.zlog*,.zcompdump* call s:StarSetf('zsh') +au BufNewFile,BufRead .zshrc,.zshenv,.zlogin,.zlogout,.zcompdump setf zsh au BufNewFile,BufRead *.zsh setf zsh " Scheme @@ -1691,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 @@ -2073,6 +2079,17 @@ au BufRead,BufNewFile *.rdf call dist#ft#Redif() " Remind au BufNewFile,BufRead .reminders* call s:StarSetf('remind') +" Shell scripts ending in a star +au BufNewFile,BufRead .bashrc*,.bash[_-]profile*,.bash[_-]logout*,.bash[_-]aliases*,bash-fc[-.]*,,PKGBUILD* call dist#ft#SetFileTypeSH("bash") +au BufNewFile,BufRead .kshrc* call dist#ft#SetFileTypeSH("ksh") +au BufNewFile,BufRead .profile* call dist#ft#SetFileTypeSH(getline(1)) + +" tcsh scripts ending in a star +au BufNewFile,BufRead .tcshrc* call dist#ft#SetFileTypeShell("tcsh") + +" csh scripts ending in a star +au BufNewFile,BufRead .login*,.cshrc* call dist#ft#CSH() + " Vim script au BufNewFile,BufRead *vimrc* call s:StarSetf('vim') @@ -2100,7 +2117,8 @@ au BufNewFile,BufRead */etc/xinetd.d/* call s:StarSetf('xinetd') " yum conf (close enough to dosini) au BufNewFile,BufRead */etc/yum.repos.d/* call s:StarSetf('dosini') -" Z-Shell script +" Z-Shell script ending in a star +au BufNewFile,BufRead .zsh*,.zlog*,.zcompdump* call s:StarSetf('zsh') au BufNewFile,BufRead zsh*,zlog* call s:StarSetf('zsh') 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/lua/vim/shared.lua b/runtime/lua/vim/shared.lua new file mode 100644 index 0000000000..07145c6e3f --- /dev/null +++ b/runtime/lua/vim/shared.lua @@ -0,0 +1,179 @@ +-- Functions shared by Nvim and its test-suite. +-- +-- The singular purpose of this module is to share code with the Nvim +-- test-suite. If, in the future, Nvim itself is used to run the test-suite +-- instead of "vanilla Lua", these functions could move to src/nvim/lua/vim.lua + + +--- Returns a deep copy of the given object. Non-table objects are copied as +--- in a typical Lua assignment, whereas table objects are copied recursively. +--- +--@param orig Table to copy +--@returns New table of copied keys and (nested) values. +local function deepcopy(orig) + error(orig) +end +local function _id(v) + return v +end +local deepcopy_funcs = { + table = function(orig) + local copy = {} + for k, v in pairs(orig) do + copy[deepcopy(k)] = deepcopy(v) + end + return copy + end, + number = _id, + string = _id, + ['nil'] = _id, + boolean = _id, +} +deepcopy = function(orig) + return deepcopy_funcs[type(orig)](orig) +end + +--- Splits a string at each instance of a separator. +--- +--@see |vim.split()| +--@see https://www.lua.org/pil/20.2.html +--@see http://lua-users.org/wiki/StringLibraryTutorial +--- +--@param s String to split +--@param sep Separator string or pattern +--@param plain If `true` use `sep` literally (passed to String.find) +--@returns Iterator over the split components +local function gsplit(s, sep, plain) + assert(type(s) == "string") + assert(type(sep) == "string") + assert(type(plain) == "boolean" or type(plain) == "nil") + + local start = 1 + local done = false + + local function _pass(i, j, ...) + if i then + assert(j+1 > start, "Infinite loop detected") + local seg = s:sub(start, i - 1) + start = j + 1 + return seg, ... + else + done = true + return s:sub(start) + end + end + + return function() + if done then + return + end + if sep == '' then + if start == #s then + done = true + end + return _pass(start+1, start) + end + return _pass(s:find(sep, start, plain)) + end +end + +--- Splits a string at each instance of a separator. +--- +--- Examples: +--- <pre> +--- split(":aa::b:", ":") --> {'','aa','','bb',''} +--- split("axaby", "ab?") --> {'','x','y'} +--- split(x*yz*o, "*", true) --> {'x','yz','o'} +--- </pre> +-- +--@see |vim.gsplit()| +--- +--@param s String to split +--@param sep Separator string or pattern +--@param plain If `true` use `sep` literally (passed to String.find) +--@returns List-like table of the split components. +local function split(s,sep,plain) + local t={} for c in gsplit(s, sep, plain) do table.insert(t,c) end + return t +end + +--- Checks if a list-like (vector) table contains `value`. +--- +--@param t Table to check +--@param value Value to compare +--@returns true if `t` contains `value` +local function tbl_contains(t, value) + if type(t) ~= 'table' then + error('t must be a table') + end + for _,v in ipairs(t) do + if v == value then + return true + end + end + return false +end + +--- Merges two or more map-like tables. +--- +--@see |extend()| +--- +--@param behavior Decides what to do if a key is found in more than one map: +--- - "error": raise an error +--- - "keep": use value from the leftmost map +--- - "force": use value from the rightmost map +--@param ... Two or more map-like tables. +local function tbl_extend(behavior, ...) + if (behavior ~= 'error' and behavior ~= 'keep' and behavior ~= 'force') then + error('invalid "behavior": '..tostring(behavior)) + end + local ret = {} + for i = 1, select('#', ...) do + local tbl = select(i, ...) + if tbl then + for k, v in pairs(tbl) do + if behavior ~= 'force' and ret[k] ~= nil then + if behavior == 'error' then + error('key found in more than one map: '..k) + end -- Else behavior is "keep". + else + ret[k] = v + end + end + end + end + return ret +end + +--- Creates a copy of a list-like table such that any nested tables are +--- "unrolled" and appended to the result. +--- +--@param t List-like table +--@returns Flattened copy of the given list-like table. +local function tbl_flatten(t) + -- From https://github.com/premake/premake-core/blob/master/src/base/table.lua + local result = {} + local function _tbl_flatten(_t) + local n = #_t + for i = 1, n do + local v = _t[i] + if type(v) == "table" then + _tbl_flatten(v) + elseif v then + table.insert(result, v) + end + end + end + _tbl_flatten(t) + return result +end + +local module = { + deepcopy = deepcopy, + gsplit = gsplit, + split = split, + tbl_contains = tbl_contains, + tbl_extend = tbl_extend, + tbl_flatten = tbl_flatten, +} +return module 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/nvim.png b/runtime/nvim.png Binary files differindex dbc65ef363..5d6cee3b49 100644 --- a/runtime/nvim.png +++ b/runtime/nvim.png diff --git a/runtime/pack/dist/opt/termdebug/plugin/termdebug.vim b/runtime/pack/dist/opt/termdebug/plugin/termdebug.vim index 506179297a..04d940948a 100644 --- a/runtime/pack/dist/opt/termdebug/plugin/termdebug.vim +++ b/runtime/pack/dist/opt/termdebug/plugin/termdebug.vim @@ -1,133 +1,890 @@ " Debugger plugin using gdb. " -" WORK IN PROGRESS - much doesn't work yet +" Author: Bram Moolenaar +" Copyright: Vim license applies, see ":help license" +" Last Update: 2018 Jun 3 +" +" WORK IN PROGRESS - Only the basics work +" Note: On MS-Windows you need a recent version of gdb. The one included with +" MingW is too old (7.6.1). +" I used version 7.12 from http://www.equation.com/servlet/equation.cmd?fa=gdb +" +" There are two ways to run gdb: +" - In a terminal window; used if possible, does not work on MS-Windows +" Not used when g:termdebug_use_prompt is set to 1. +" - Using a "prompt" buffer; may use a terminal window for the program " -" Open two visible terminal windows: -" 1. run a pty, as with ":term NONE" -" 2. run gdb, passing the pty -" The current window is used to view source code and follows gdb. +" For both the current window is used to view source code and shows the +" current statement from gdb. " +" USING A TERMINAL WINDOW +" +" Opens two visible terminal windows: +" 1. runs a pty for the debugged program, as with ":term NONE" +" 2. runs gdb, passing the pty of the debugged program " A third terminal window is hidden, it is used for communication with gdb. " +" USING A PROMPT BUFFER +" +" Opens a window with a prompt buffer to communicate with gdb. +" Gdb is run as a job with callbacks for I/O. +" On Unix another terminal window is opened to run the debugged program +" On MS-Windows a separate console is opened to run the debugged program +" " The communication with gdb uses GDB/MI. See: " https://sourceware.org/gdb/current/onlinedocs/gdb/GDB_002fMI.html " +" For neovim compatibility, the vim specific calls were replaced with neovim +" specific calls: +" term_start -> term_open +" term_sendkeys -> jobsend +" term_getline -> getbufline +" job_info && term_getjob -> using linux command ps to get the tty +" balloon -> nvim floating window +" +" The code for opening the floating window was taken from the beautiful +" implementation of LanguageClient-Neovim: +" https://github.com/autozimu/LanguageClient-neovim/blob/0ed9b69dca49c415390a8317b19149f97ae093fa/autoload/LanguageClient.vim#L304 +" +" Neovim terminal also works seamlessly on windows, which is why the ability +" to use the prompt buffer was removed. +" " Author: Bram Moolenaar " Copyright: Vim license applies, see ":help license" -" In case this gets loaded twice. +" In case this gets sourced twice. if exists(':Termdebug') finish endif + +let s:keepcpo = &cpo +set cpo&vim + " The command that starts debugging, e.g. ":Termdebug vim". " To end type "quit" in the gdb window. -command -nargs=* -complete=file Termdebug call s:StartDebug(<q-args>) +command -nargs=* -complete=file -bang Termdebug call s:StartDebug(<bang>0, <f-args>) +command -nargs=+ -complete=file -bang TermdebugCommand call s:StartDebugCommand(<bang>0, <f-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 -if &background == 'light' - hi debugPC term=reverse ctermbg=lightblue guibg=lightblue -else - hi debugPC term=reverse ctermbg=darkblue guibg=darkblue -endif let s:pc_id = 12 +let s:break_id = 13 " breakpoint number is added to this +let s:stopped = 1 + +" Take a breakpoint number as used by GDB and turn it into an integer. +" The breakpoint may contain a dot: 123.4 -> 123004 +" The main breakpoint has a zero subid. +func s:Breakpoint2SignNumber(id, subid) + return s:break_id + a:id * 1000 + a:subid +endfunction -func s:StartDebug(cmd) - let s:startwin = win_getid(winnr()) +func s:Highlight(init, old, new) + let default = a:init ? 'default ' : '' + if a:new ==# 'light' && a:old !=# 'light' + exe "hi " . default . "debugPC term=reverse ctermbg=lightblue guibg=lightblue" + elseif a:new ==# 'dark' && a:old !=# 'dark' + exe "hi " . default . "debugPC term=reverse ctermbg=darkblue guibg=darkblue" + endif +endfunc + +call s:Highlight(1, '', &background) +hi default debugBreakpoint term=reverse ctermbg=red guibg=red + +func s:StartDebug(bang, ...) + " First argument is the command to debug, second core file or process ID. + call s:StartDebug_internal({'gdb_args': a:000, 'bang': a:bang}) +endfunc + +func s:StartDebugCommand(bang, ...) + " First argument is the command to debug, rest are run arguments. + call s:StartDebug_internal({'gdb_args': [a:1], 'proc_args': a:000[1:], 'bang': a:bang}) +endfunc + +func s:StartDebug_internal(dict) + if exists('s:gdbwin') + echoerr 'Terminal debugger already running' + return + endif + let s:ptywin = 0 + let s:pid = 0 + + " Uncomment this line to write logging in "debuglog". + " call ch_logfile('debuglog', 'w') + + let s:sourcewin = win_getid(winnr()) let s:startsigncolumn = &signcolumn - " Open a terminal window without a job, to run the debugged program - let s:ptybuf = term_start('NONE', { - \ 'term_name': 'gdb program', - \ }) - if s:ptybuf == 0 + let s:save_columns = 0 + if exists('g:termdebug_wide') + if &columns < g:termdebug_wide + let s:save_columns = &columns + let &columns = g:termdebug_wide + endif + let s:vertical = 1 + else + let s:vertical = 0 + endif + + call s:StartDebug_term(a:dict) +endfunc + +" Use when debugger didn't start or ended. +func s:CloseBuffers() + exe 'bwipe! ' . s:ptybuf + unlet! s:gdbwin +endfunc + +func s:StartDebug_term(dict) + " Open a terminal window without a job, to run the debugged program in. + execute 'new' + let s:pty_job_id = termopen('tail -f /dev/null;#gdb program') + if s:pty_job_id == 0 + echoerr 'invalid argument (or job table is full) while opening terminal window' + return + elseif s:pty_job_id == -1 echoerr 'Failed to open the program terminal window' return endif - let pty = job_info(term_getjob(s:ptybuf))['tty_out'] + let pty_job_info = nvim_get_chan_info(s:pty_job_id) + let s:ptybuf = pty_job_info['buffer'] + let pty = pty_job_info['pty'] + let s:ptywin = win_getid(winnr()) + if s:vertical + " Assuming the source code window will get a signcolumn, use two more + " columns for that, thus one less for the terminal window. + exe (&columns / 2 - 1) . "wincmd |" + endif " Create a hidden terminal window to communicate with gdb - let s:commbuf = term_start('NONE', { - \ 'term_name': 'gdb communication', - \ 'out_cb': function('s:CommOutput'), - \ 'hidden': 1, - \ }) - if s:commbuf == 0 + let s:comm_job_id = jobstart('tail -f /dev/null;#gdb communication', { + \ 'on_stdout': function('s:CommOutput'), + \ 'pty': v:true, + \ }) + " hide terminal buffer + if s:comm_job_id == 0 + echoerr 'invalid argument (or job table is full) while opening communication terminal window' + exe 'bwipe! ' . s:ptybuf + return + elseif s:comm_job_id == -1 echoerr 'Failed to open the communication terminal window' exe 'bwipe! ' . s:ptybuf return endif - let commpty = job_info(term_getjob(s:commbuf))['tty_out'] + let comm_job_info = nvim_get_chan_info(s:comm_job_id) + let commpty = comm_job_info['pty'] " Open a terminal window to run the debugger. - let cmd = [g:debugger, '-tty', pty, a:cmd] - echomsg 'executing "' . join(cmd) . '"' - let gdbbuf = term_start(cmd, { - \ 'exit_cb': function('s:EndDebug'), - \ 'term_finish': 'close', - \ }) - if gdbbuf == 0 - echoerr 'Failed to open the gdb terminal window' + " Add -quiet to avoid the intro message causing a hit-enter prompt. + let gdb_args = get(a:dict, 'gdb_args', []) + let proc_args = get(a:dict, 'proc_args', []) + + let cmd = [g:termdebugger, '-quiet', '-tty', pty] + gdb_args + "call ch_log('executing "' . join(cmd) . '"') + execute 'new' + let s:gdb_job_id = termopen(cmd, {'on_exit': function('s:EndTermDebug')}) + if s:gdb_job_id == 0 + echoerr 'invalid argument (or job table is full) while opening gdb terminal window' exe 'bwipe! ' . s:ptybuf - exe 'bwipe! ' . s:commbuf return + elseif s:gdb_job_id == -1 + echoerr 'Failed to open the gdb terminal window' + call s:CloseBuffers() + return + endif + let gdb_job_info = nvim_get_chan_info(s:gdb_job_id) + let s:gdbbuf = gdb_job_info['buffer'] + let s:gdbwin = win_getid(winnr()) + + " Set arguments to be run + if len(proc_args) + call jobsend(s:gdb_job_id, 'set args ' . join(proc_args) . "\r") endif " Connect gdb to the communication pty, using the GDB/MI interface - call term_sendkeys(gdbbuf, 'new-ui mi ' . commpty . "\r") + call jobsend(s:gdb_job_id, 'new-ui mi ' . commpty . "\r") + + " Wait for the response to show up, users may not notice the error and wonder + " why the debugger doesn't work. + let try_count = 0 + while 1 + if nvim_get_chan_info(s:gdb_job_id) == {} + echoerr string(g:termdebugger) . ' exited unexpectedly' + call s:CloseBuffers() + return + endif + + let response = '' + for lnum in range(1,200) + if len(getbufline(s:gdbbuf, lnum)) > 0 && getbufline(s:gdbbuf, lnum)[0] =~ 'new-ui mi ' + " response can be in the same line or the next line + let response = getbufline(s:gdbbuf, lnum)[0] . getbufline(s:gdbbuf, lnum + 1)[0] + if response =~ 'Undefined command' + echoerr 'Sorry, your gdb is too old, gdb 7.12 is required' + call s:CloseBuffers() + return + endif + if response =~ 'New UI allocated' + " Success! + break + endif + endif + endfor + if response =~ 'New UI allocated' + break + endif + let try_count += 1 + if try_count > 100 + echoerr 'Cannot check if your gdb works, continuing anyway' + break + endif + sleep 10m + endwhile + + " Interpret commands while the target is running. This should usualy only be + " exec-interrupt, since many commands don't work properly while the target is + " running. + call s:SendCommand('-gdb-set mi-async on') + " Older gdb uses a different command. + call s:SendCommand('-gdb-set target-async on') + + " Disable pagination, it causes everything to stop at the gdb + " "Type <return> to continue" prompt. + call s:SendCommand('set pagination off') + + call s:StartDebugCommon(a:dict) endfunc -func s:EndDebug(job, status) - exe 'bwipe! ' . s:ptybuf - exe 'bwipe! ' . s:commbuf - call setwinvar(s:startwin, '&signcolumn', s:startsigncolumn) + +func s:StartDebugCommon(dict) + " Sign used to highlight the line where the program has stopped. + " There can be only one. + sign define debugPC linehl=debugPC + + " Install debugger commands in the text window. + call win_gotoid(s:sourcewin) + call s:InstallCommands() + call win_gotoid(s:gdbwin) + + " Contains breakpoints that have been placed, key is a string with the GDB + " breakpoint number. + " Each entry is a dict, containing the sub-breakpoints. Key is the subid. + " For a breakpoint that is just a number the subid is zero. + " For a breakpoint "123.4" the id is "123" and subid is "4". + " Example, when breakpoint "44", "123", "123.1" and "123.2" exist: + " {'44': {'0': entry}, '123': {'0': entry, '1': entry, '2': entry}} + let s:breakpoints = {} + + " Contains breakpoints by file/lnum. The key is "fname:lnum". + " Each entry is a list of breakpoint IDs at that position. + let s:breakpoint_locations = {} + + augroup TermDebug + au BufRead * call s:BufRead() + au BufUnload * call s:BufUnloaded() + au OptionSet background call s:Highlight(0, v:option_old, v:option_new) + augroup END + + " Run the command if the bang attribute was given and got to the debug + " window. + if get(a:dict, 'bang', 0) + call s:SendCommand('-exec-run') + call win_gotoid(s:ptywin) + endif +endfunc + +" Send a command to gdb. "cmd" is the string without line terminator. +func s:SendCommand(cmd) + "call ch_log('sending to gdb: ' . a:cmd) + call jobsend(s:comm_job_id, a:cmd . "\r") +endfunc + +" This is global so that a user can create their mappings with this. +func TermDebugSendCommand(cmd) + let do_continue = 0 + if !s:stopped + let do_continue = 1 + call s:SendCommand('-exec-interrupt') + sleep 10m + endif + call jobsend(s:gdb_job_id, a:cmd . "\r") + if do_continue + Continue + endif +endfunc + +" Decode a message from gdb. quotedText starts with a ", return the text up +" to the next ", unescaping characters. +func s:DecodeMessage(quotedText) + if a:quotedText[0] != '"' + echoerr 'DecodeMessage(): missing quote in ' . a:quotedText + return + endif + let result = '' + let i = 1 + while a:quotedText[i] != '"' && i < len(a:quotedText) + if a:quotedText[i] == '\' + let i += 1 + if a:quotedText[i] == 'n' + " drop \n + let i += 1 + continue + endif + endif + let result .= a:quotedText[i] + let i += 1 + endwhile + return result +endfunc + +" Extract the "name" value from a gdb message with fullname="name". +func s:GetFullname(msg) + if a:msg !~ 'fullname' + return '' + endif + let name = s:DecodeMessage(substitute(a:msg, '.*fullname=', '', '')) + if has('win32') && name =~ ':\\\\' + " sometimes the name arrives double-escaped + let name = substitute(name, '\\\\', '\\', 'g') + endif + return name +endfunc + +function s:EndTermDebug(job_id, exit_code, event) + unlet s:gdbwin + + call s:EndDebugCommon() endfunc -" Handle a message received from gdb on the GDB/MI interface. -func s:CommOutput(chan, msg) - let msgs = split(a:msg, "\r") +func s:EndDebugCommon() + let curwinid = win_getid(winnr()) - for msg in msgs + if exists('s:ptybuf') && s:ptybuf + exe 'bwipe! ' . s:ptybuf + endif + + call win_gotoid(s:sourcewin) + let &signcolumn = s:startsigncolumn + call s:DeleteCommands() + + call win_gotoid(curwinid) + + if s:save_columns > 0 + let &columns = s:save_columns + endif + + au! TermDebug +endfunc + +func s:CommOutput(job_id, msgs, event) + + for msg in a:msgs " remove prefixed NL if msg[0] == "\n" let msg = msg[1:] 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 - else - exe 'sign unplace ' . s:pc_id - endif - - call win_gotoid(wid) - endif + if msg =~ '^\(\*stopped\|\*running\|=thread-selected\)' + 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 =~ '^=thread-group-started' + call s:HandleProgramRun(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() + let save_cpo = &cpo + set cpo&vim + + command Break call s:SetBreakpoint() + command Clear call s:ClearBreakpoint() + command Step call s:SendCommand('-exec-step') + command Over call s:SendCommand('-exec-next') + command Finish call s:SendCommand('-exec-finish') + command -nargs=* Run call s:Run(<q-args>) + command -nargs=* Arguments call s:SendCommand('-exec-arguments ' . <q-args>) + command Stop call s:SendCommand('-exec-interrupt') + + " using -exec-continue results in CTRL-C in gdb window not working + command Continue call jobsend(s:gdb_job_id, "continue\r") + + command -range -nargs=* Evaluate call s:Evaluate(<range>, <q-args>) + command Gdb call win_gotoid(s:gdbwin) + command Program call win_gotoid(s:ptywin) + command Source call s:GotoSourcewinOrCreateIt() + command Winbar call s:InstallWinbar() + + " TODO: can the K mapping be restored? + nnoremap K :Evaluate<CR> + + let &cpo = save_cpo +endfunc + +let s:winbar_winids = [] + +" Delete installed debugger commands in the current window. +func s:DeleteCommands() + delcommand Break + delcommand Clear + delcommand Step + delcommand Over + delcommand Finish + delcommand Run + delcommand Arguments + delcommand Stop + delcommand Continue + delcommand Evaluate + delcommand Gdb + delcommand Program + delcommand Source + delcommand Winbar + + nunmap K + + exe 'sign unplace ' . s:pc_id + for [id, entries] in items(s:breakpoints) + for subid in keys(entries) + exe 'sign unplace ' . s:Breakpoint2SignNumber(id, subid) + endfor + endfor + unlet s:breakpoints + unlet s:breakpoint_locations + + sign undefine debugPC + for val in s:BreakpointSigns + exe "sign undefine debugBreakpoint" . val + endfor + let s:BreakpointSigns = [] +endfunc + +" :Break - Set a breakpoint at the cursor position. +func s:SetBreakpoint() + " Setting a breakpoint may not work while the program is running. + " Interrupt to make it work. + let do_continue = 0 + if !s:stopped + let do_continue = 1 + call s:SendCommand('-exec-interrupt') + sleep 10m + endif + " Use the fname:lnum format, older gdb can't handle --source. + call s:SendCommand('-break-insert ' + \ . fnameescape(expand('%:p')) . ':' . line('.')) + if do_continue + call s:SendCommand('-exec-continue') + endif +endfunc + +" :Clear - Delete a breakpoint at the cursor position. +func s:ClearBreakpoint() + let fname = fnameescape(expand('%:p')) + let lnum = line('.') + let bploc = printf('%s:%d', fname, lnum) + if has_key(s:breakpoint_locations, bploc) + let idx = 0 + for id in s:breakpoint_locations[bploc] + if has_key(s:breakpoints, id) + " Assume this always works, the reply is simply "^done". + call s:SendCommand('-break-delete ' . id) + for subid in keys(s:breakpoints[id]) + exe 'sign unplace ' . s:Breakpoint2SignNumber(id, subid) + endfor + unlet s:breakpoints[id] + unlet s:breakpoint_locations[bploc][idx] + break + else + let idx += 1 + endif + endfor + if empty(s:breakpoint_locations[bploc]) + unlet s:breakpoint_locations[bploc] + endif + endif +endfunc + +func s:Run(args) + if a:args != '' + call s:SendCommand('-exec-arguments ' . a:args) + endif + call s:SendCommand('-exec-run') +endfunc + +func s:SendEval(expr) + call s:SendCommand('-data-evaluate-expression "' . a:expr . '"') + let s:evalexpr = a:expr +endfunc + +" :Evaluate - evaluate what is under the cursor +func s:Evaluate(range, arg) + if a:arg != '' + let expr = a:arg + let s:evalFromBalloonExpr = 0 + 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) + let s:evalFromBalloonExpr = 1 + else + let expr = expand('<cexpr>') + let s:evalFromBalloonExpr = 1 + endif + let s:ignoreEvalError = 0 + call s:SendEval(expr) +endfunc + +let s:ignoreEvalError = 0 +let s:evalFromBalloonExpr = 0 +let s:evalFromBalloonExprResult = '' + +" Handle the result of data-evaluate-expression +func s:HandleEvaluate(msg) + let value = substitute(a:msg, '.*value="\(.*\)"', '\1', '') + let value = substitute(value, '\\"', '"', 'g') + let value = substitute(value, '
', '\1', '') + if s:evalFromBalloonExpr + if s:evalFromBalloonExprResult == '' + let s:evalFromBalloonExprResult = s:evalexpr . ': ' . value + else + let s:evalFromBalloonExprResult .= ' = ' . value + endif + let s:evalFromBalloonExprResult = split(s:evalFromBalloonExprResult, '\\n') + call s:OpenHoverPreview(s:evalFromBalloonExprResult, v:null) + else + echomsg '"' . s:evalexpr . '": ' . value + endif + + if s:evalexpr[0] != '*' && value =~ '^0x' && value != '0x0' && value !~ '"$' + " Looks like a pointer, also display what it points to. + let s:ignoreEvalError = 1 + call s:SendEval('*' . s:evalexpr) + else + let s:evalFromBalloonExprResult = '' + endif +endfunc + +function! s:ShouldUseFloatWindow() abort + if exists('*nvim_open_win') && (get(g:, 'termdebug_useFloatingHover', 1) == 1) + return v:true + else + return v:false + endif +endfunction + +function! s:CloseFloatingHoverOnCursorMove(win_id, opened) abort + if getpos('.') == a:opened + " Just after opening floating window, CursorMoved event is run. + " To avoid closing floating window immediately, check the cursor + " was really moved + return + endif + autocmd! nvim_termdebug_close_hover + let winnr = win_id2win(a:win_id) + if winnr == 0 + return + endif + call nvim_win_close(a:win_id, v:true) +endfunction + +function! s:CloseFloatingHoverOnBufEnter(win_id, bufnr) abort + let winnr = win_id2win(a:win_id) + if winnr == 0 + " Float window was already closed + autocmd! nvim_termdebug_close_hover + return + endif + if winnr == winnr() + " Cursor is moving into floating window. Do not close it + return + endif + if bufnr('%') == a:bufnr + " When current buffer opened hover window, it's not another buffer. Skipped + return + endif + autocmd! nvim_termdebug_close_hover + call nvim_win_close(a:win_id, v:true) + endfunction + +" Open preview window. Window is open in: +" - Floating window on Neovim (0.4.0 or later) +" - Preview window on Neovim (0.3.0 or earlier) or Vim +function! s:OpenHoverPreview(lines, filetype) abort + " Use local variable since parameter is not modifiable + let lines = a:lines + let bufnr = bufnr('%') + + let use_float_win = s:ShouldUseFloatWindow() + if use_float_win + let pos = getpos('.') + + " Calculate width and height + let width = 0 + for index in range(len(lines)) + let line = lines[index] + let lw = strdisplaywidth(line) + if lw > width + let width = lw + endif + let lines[index] = line + endfor + + let height = len(lines) + + " Calculate anchor + " Prefer North, but if there is no space, fallback into South + let bottom_line = line('w0') + winheight(0) - 1 + if pos[1] + height <= bottom_line + let vert = 'N' + let row = 1 + else + let vert = 'S' + let row = 0 + endif + + " Prefer West, but if there is no space, fallback into East + if pos[2] + width <= &columns + let hor = 'W' + let col = 0 + else + let hor = 'E' + let col = 1 + endif + + let buf = nvim_create_buf(v:false, v:true) + call nvim_buf_set_lines(buf, 0, -1, v:true, lines) + " using v:true for second argument of nvim_open_win make the floating + " window disappear + let float_win_id = nvim_open_win(buf, v:false, { + \ 'relative': 'cursor', + \ 'anchor': vert . hor, + \ 'row': row, + \ 'col': col, + \ 'width': width, + \ 'height': height, + \ }) + call nvim_win_set_option(float_win_id, 'relativenumber', v:false) + call nvim_win_set_option(float_win_id, 'signcolumn', 'no') + call nvim_win_set_option(float_win_id, 'signcolumn', 'no') + if a:filetype isnot v:null + call nvim_win_set_option(float_win_id, 'filetype', a:filetype) + endif + + call nvim_buf_set_option(buf, 'modified', v:false) + call nvim_buf_set_option(buf, 'modifiable', v:false) + + " Unlike preview window, :pclose does not close window. Instead, close + " hover window automatically when cursor is moved. + let call_after_move = printf('<SID>CloseFloatingHoverOnCursorMove(%d, %s)', float_win_id, string(pos)) + let call_on_bufenter = printf('<SID>CloseFloatingHoverOnBufEnter(%d, %d)', float_win_id, bufnr) + augroup nvim_termdebug_close_hover + execute 'autocmd CursorMoved,CursorMovedI,InsertEnter <buffer> call ' . call_after_move + execute 'autocmd BufEnter * call ' . call_on_bufenter + augroup END + else + echomsg a:lines[0] + endif +endfunction + +" Handle an error. +func s:HandleError(msg) + if s:ignoreEvalError + " Result of s:SendEval() failed, ignore. + let s:ignoreEvalError = 0 + let s:evalFromBalloonExpr = 0 + return + endif + echoerr substitute(a:msg, '.*msg="\(.*\)"', '\1', '') +endfunc + +func s:GotoSourcewinOrCreateIt() + if !win_gotoid(s:sourcewin) + new + let s:sourcewin = win_getid(winnr()) + call s:InstallWinbar() + endif +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 a:msg =~ '^\*stopped' + "call ch_log('program stopped') + let s:stopped = 1 + elseif a:msg =~ '^\*running' + "call ch_log('program running') + let s:stopped = 0 + endif + + if a:msg =~ 'fullname=' + let fname = s:GetFullname(a:msg) + else + let fname = '' + endif + if a:msg =~ '^\(\*stopped\|=thread-selected\)' && filereadable(fname) + let lnum = substitute(a:msg, '.*line="\([^"]*\)".*', '\1', '') + if lnum =~ '^[0-9]*$' + call s:GotoSourcewinOrCreateIt() + if expand('%:p') != fnamemodify(fname, ':p') + if &modified + " TODO: find existing window + exe 'split ' . fnameescape(fname) + let s:sourcewin = win_getid(winnr()) + call s:InstallWinbar() + else + exe 'edit ' . fnameescape(fname) + endif endif + exe lnum + exe 'sign unplace ' . s:pc_id + exe 'sign place ' . s:pc_id . ' line=' . lnum . ' name=debugPC file=' . fname + setlocal signcolumn=yes + endif + elseif !s:stopped || fname != '' + exe 'sign unplace ' . s:pc_id + endif + + call win_gotoid(wid) +endfunc + +let s:BreakpointSigns = [] + +func s:CreateBreakpoint(id, subid) + let nr = printf('%d.%d', a:id, a:subid) + if index(s:BreakpointSigns, nr) == -1 + call add(s:BreakpointSigns, nr) + exe "sign define debugBreakpoint" . nr . " text=" . substitute(nr, '\..*', '', '') . " texthl=debugBreakpoint" + endif +endfunc + +func! s:SplitMsg(s) + return split(a:s, '{.\{-}}\zs') +endfunction + +" Handle setting a breakpoint +" Will update the sign that shows the breakpoint +func s:HandleNewBreakpoint(msg) + if a:msg !~ 'fullname=' + " a watch does not have a file name + return + endif + for msg in s:SplitMsg(a:msg) + let fname = s:GetFullname(msg) + if empty(fname) + continue + endif + let nr = substitute(msg, '.*number="\([0-9.]*\)\".*', '\1', '') + if empty(nr) + return + endif + + " If "nr" is 123 it becomes "123.0" and subid is "0". + " If "nr" is 123.4 it becomes "123.4.0" and subid is "4"; "0" is discarded. + let [id, subid; _] = map(split(nr . '.0', '\.'), 'v:val + 0') + call s:CreateBreakpoint(id, subid) + + if has_key(s:breakpoints, id) + let entries = s:breakpoints[id] + else + let entries = {} + let s:breakpoints[id] = entries + endif + if has_key(entries, subid) + let entry = entries[subid] + else + let entry = {} + let entries[subid] = entry endif + + let lnum = substitute(msg, '.*line="\([^"]*\)".*', '\1', '') + let entry['fname'] = fname + let entry['lnum'] = lnum + + let bploc = printf('%s:%d', fname, lnum) + if !has_key(s:breakpoint_locations, bploc) + let s:breakpoint_locations[bploc] = [] + endif + let s:breakpoint_locations[bploc] += [id] + + if bufloaded(fname) + call s:PlaceSign(id, subid, entry) + endif + endfor +endfunc + +func s:PlaceSign(id, subid, entry) + let nr = printf('%d.%d', a:id, a:subid) + exe 'sign place ' . s:Breakpoint2SignNumber(a:id, a:subid) . ' line=' . a:entry['lnum'] . ' name=debugBreakpoint' . nr . ' file=' . a:entry['fname'] + let a:entry['placed'] = 1 +endfunc + +" Handle deleting a breakpoint +" Will remove the sign that shows the breakpoint +func s:HandleBreakpointDelete(msg) + let id = substitute(a:msg, '.*id="\([0-9]*\)\".*', '\1', '') + 0 + if empty(id) + return + endif + if has_key(s:breakpoints, id) + for [subid, entry] in items(s:breakpoints[id]) + if has_key(entry, 'placed') + exe 'sign unplace ' . s:Breakpoint2SignNumber(id, subid) + unlet entry['placed'] + endif + endfor + unlet s:breakpoints[id] + endif +endfunc + +" Handle the debugged program starting to run. +" Will store the process ID in s:pid +func s:HandleProgramRun(msg) + let nr = substitute(a:msg, '.*pid="\([0-9]*\)\".*', '\1', '') + 0 + if nr == 0 + return + endif + let s:pid = nr + "call ch_log('Detected process ID: ' . s:pid) +endfunc + +" Handle a BufRead autocommand event: place any signs. +func s:BufRead() + let fname = expand('<afile>:p') + for [id, entries] in items(s:breakpoints) + for [subid, entry] in items(entries) + if entry['fname'] == fname + call s:PlaceSign(id, subid, entry) + endif + endfor + endfor +endfunc + +" Handle a BufUnloaded autocommand event: unplace any signs. +func s:BufUnloaded() + let fname = expand('<afile>:p') + for [id, entries] in items(s:breakpoints) + for [subid, entry] in items(entries) + if entry['fname'] == fname + let entry['placed'] = 0 + endif + endfor endfor 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 |
