aboutsummaryrefslogtreecommitdiff
path: root/runtime
diff options
context:
space:
mode:
Diffstat (limited to 'runtime')
-rw-r--r--runtime/autoload/health/provider.vim56
-rw-r--r--runtime/doc/eval.txt263
-rw-r--r--runtime/doc/insert.txt3
-rw-r--r--runtime/doc/nvim_terminal_emulator.txt100
-rw-r--r--runtime/doc/options.txt27
-rw-r--r--runtime/doc/provider.txt23
-rw-r--r--runtime/doc/quickref.txt1
-rw-r--r--runtime/doc/tagsrch.txt44
-rw-r--r--runtime/doc/term.txt4
-rw-r--r--runtime/doc/various.txt16
-rw-r--r--runtime/doc/vim_diff.txt3
-rw-r--r--runtime/optwin.vim2
12 files changed, 355 insertions, 187 deletions
diff --git a/runtime/autoload/health/provider.vim b/runtime/autoload/health/provider.vim
index bc6b2c074c..57dd508f96 100644
--- a/runtime/autoload/health/provider.vim
+++ b/runtime/autoload/health/provider.vim
@@ -221,20 +221,26 @@ endfunction
function! s:check_python(version) abort
call health#report_start('Python ' . a:version . ' provider')
- let python_bin_name = 'python'.(a:version == 2 ? '' : '3')
+ let pyname = 'python'.(a:version == 2 ? '' : '3')
let pyenv = resolve(exepath('pyenv'))
let pyenv_root = exists('$PYENV_ROOT') ? resolve($PYENV_ROOT) : 'n'
let venv = exists('$VIRTUAL_ENV') ? resolve($VIRTUAL_ENV) : ''
- let host_prog_var = python_bin_name.'_host_prog'
+ let host_prog_var = pyname.'_host_prog'
+ let loaded_var = 'g:loaded_'.pyname.'_provider'
let python_bin = ''
let python_multiple = []
+ if exists(loaded_var) && !exists('*provider#'.pyname.'#Call')
+ call health#report_info('Disabled. '.loaded_var.'='.eval(loaded_var))
+ return
+ endif
+
if exists('g:'.host_prog_var)
call health#report_info(printf('Using: g:%s = "%s"', host_prog_var, get(g:, host_prog_var)))
endif
- let [python_bin_name, pythonx_errs] = provider#pythonx#Detect(a:version)
- if empty(python_bin_name)
+ let [pyname, pythonx_errs] = provider#pythonx#Detect(a:version)
+ if empty(pyname)
call health#report_warn('No Python interpreter was found with the neovim '
\ . 'module. Using the first available for diagnostics.')
if !empty(pythonx_errs)
@@ -242,21 +248,21 @@ function! s:check_python(version) abort
endif
endif
- if !empty(python_bin_name)
+ if !empty(pyname)
if exists('g:'.host_prog_var)
- let python_bin = exepath(python_bin_name)
+ let python_bin = exepath(pyname)
endif
- let python_bin_name = fnamemodify(python_bin_name, ':t')
+ let pyname = fnamemodify(pyname, ':t')
endif
if !empty(pythonx_errs)
call health#report_error('Python provider error', pythonx_errs)
endif
- if !empty(python_bin_name) && empty(python_bin) && empty(pythonx_errs)
+ if !empty(pyname) && empty(python_bin) && empty(pythonx_errs)
if !exists('g:'.host_prog_var)
call health#report_info(printf('`g:%s` is not set. Searching for '
- \ . '%s in the environment.', host_prog_var, python_bin_name))
+ \ . '%s in the environment.', host_prog_var, pyname))
endif
if !empty(pyenv)
@@ -269,19 +275,19 @@ function! s:check_python(version) abort
call health#report_ok(printf('pyenv found: "%s"', pyenv))
endif
- let python_bin = s:trim(s:system([pyenv, 'which', python_bin_name], '', 1))
+ let python_bin = s:trim(s:system([pyenv, 'which', pyname], '', 1))
if empty(python_bin)
- call health#report_warn(printf('pyenv could not find %s.', python_bin_name))
+ call health#report_warn(printf('pyenv could not find %s.', pyname))
endif
endif
if empty(python_bin)
- let python_bin = exepath(python_bin_name)
+ let python_bin = exepath(pyname)
if exists('$PATH')
for path in split($PATH, has('win32') ? ';' : ':')
- let path_bin = path.'/'.python_bin_name
+ let path_bin = path.'/'.pyname
if path_bin != python_bin && index(python_multiple, path_bin) == -1
\ && executable(path_bin)
call add(python_multiple, path_bin)
@@ -292,7 +298,7 @@ function! s:check_python(version) abort
" This is worth noting since the user may install something
" that changes $PATH, like homebrew.
call health#report_info(printf('Multiple %s executables found. '
- \ . 'Set `g:%s` to avoid surprises.', python_bin_name, host_prog_var))
+ \ . 'Set `g:%s` to avoid surprises.', pyname, host_prog_var))
endif
if python_bin =~# '\<shims\>'
@@ -333,9 +339,9 @@ function! s:check_python(version) abort
endif
endif
- if empty(python_bin) && !empty(python_bin_name)
+ if empty(python_bin) && !empty(pyname)
" An error message should have already printed.
- call health#report_error(printf('`%s` was not found.', python_bin_name))
+ call health#report_error(printf('`%s` was not found.', pyname))
elseif !empty(python_bin) && !s:check_bin(python_bin)
let python_bin = ''
endif
@@ -349,7 +355,7 @@ function! s:check_python(version) abort
if $VIRTUAL_ENV != pyenv_prefix
let virtualenv_inactive = 1
endif
- elseif !empty(python_bin_name) && exepath(python_bin_name) !~# '^'.$VIRTUAL_ENV.'/'
+ elseif !empty(pyname) && exepath(pyname) !~# '^'.$VIRTUAL_ENV.'/'
let virtualenv_inactive = 1
endif
endif
@@ -381,9 +387,9 @@ function! s:check_python(version) abort
call health#report_info('Python'.a:version.' version: ' . pyversion)
if s:is_bad_response(status)
- call health#report_info(printf('%s-neovim version: %s (%s)', python_bin_name, current, status))
+ call health#report_info(printf('%s-neovim version: %s (%s)', pyname, current, status))
else
- call health#report_info(printf('%s-neovim version: %s', python_bin_name, current))
+ call health#report_info(printf('%s-neovim version: %s', pyname, current))
endif
if s:is_bad_response(current)
@@ -397,10 +403,10 @@ function! s:check_python(version) abort
call health#report_error('HTTP request failed: '.latest)
elseif s:is_bad_response(status)
call health#report_warn(printf('Latest %s-neovim is NOT installed: %s',
- \ python_bin_name, latest))
+ \ pyname, latest))
elseif !s:is_bad_response(current)
call health#report_ok(printf('Latest %s-neovim is installed: %s',
- \ python_bin_name, latest))
+ \ pyname, latest))
endif
endif
@@ -409,6 +415,12 @@ endfunction
function! s:check_ruby() abort
call health#report_start('Ruby provider')
+ let loaded_var = 'g:loaded_ruby_provider'
+ if exists(loaded_var) && !exists('*provider#ruby#Call')
+ call health#report_info('Disabled. '.loaded_var.'='.eval(loaded_var))
+ return
+ endif
+
if !executable('ruby') || !executable('gem')
call health#report_warn(
\ "`ruby` and `gem` must be in $PATH.",
@@ -451,7 +463,7 @@ function! s:check_ruby() abort
\ current_gem, latest_gem),
\ ['Run in shell: gem update neovim'])
else
- call health#report_ok('Gem "neovim" is up-to-date: '. current_gem)
+ call health#report_ok('Latest "neovim" gem is installed: '. current_gem)
endif
endfunction
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index a14221a656..1105601a0e 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -112,9 +112,10 @@ You will not get an error if you try to change the type of a variable.
1.2 Function references ~
*Funcref* *E695* *E718*
-A Funcref variable is obtained with the |function()| function. It can be used
-in an expression in the place of a function name, before the parenthesis
-around the arguments, to invoke the function it refers to. Example: >
+A Funcref variable is obtained with the |function()| function or created with
+the lambda expression |expr-lambda|. It can be used in an expression in the
+place of a function name, before the parenthesis around the arguments, to
+invoke the function it refers to. Example: >
:let Fn = function("MyFunc")
:echo Fn()
@@ -667,6 +668,7 @@ Expression syntax summary, from least to most significant:
@r contents of register 'r'
function(expr1, ...) function call
func{ti}on(expr1, ...) function call with curly braces
+ {args -> expr1} lambda expression
".." indicates that the operations in this level can be concatenated.
@@ -1174,6 +1176,62 @@ function(expr1, ...) function call
See below |functions|.
+lambda expression *expr-lambda* *lambda*
+-----------------
+{args -> expr1} lambda expression
+
+A lambda expression creates a new unnamed function which returns the result of
+evaluating |expr1|. Lambda expressions are differ from |user-functions| in
+the following ways:
+
+1. The body of the lambda expression is an |expr1| and not a sequence of |Ex|
+ commands.
+2. The prefix "a:" should not be used for arguments. E.g.: >
+ :let F = {arg1, arg2 -> arg1 - arg2}
+ :echo F(5, 2)
+< 3
+
+The arguments are optional. Example: >
+ :let F = {-> 'error function'}
+ :echo F()
+< error function
+ *closure*
+Lambda expressions can access outer scope variables and arguments. This is
+often called a closure. Example where "i" a and "a:arg" are used in a lambda
+while they exists in the function scope. They remain valid even after the
+function returns: >
+ :function Foo(arg)
+ : let i = 3
+ : return {x -> x + i - a:arg}
+ :endfunction
+ :let Bar = Foo(4)
+ :echo Bar(6)
+< 5
+See also |:func-closure|. Lambda and closure support can be checked with: >
+ if has('lambda')
+
+Examples for using a lambda expression with |sort()|, |map()| and |filter()|: >
+ :echo map([1, 2, 3], {idx, val -> val + 1})
+< [2, 3, 4] >
+ :echo sort([3,7,2,1,4], {a, b -> a - b})
+< [1, 2, 3, 4, 7]
+
+The lambda expression is also useful for Channel, Job and timer: >
+ :let timer = timer_start(500,
+ \ {-> execute("echo 'Handler called'", "")},
+ \ {'repeat': 3})
+< Handler called
+ Handler called
+ Handler called
+
+Note how execute() is used to execute an Ex command. That's ugly though.
+
+
+Lambda expressions have internal names like '<lambda>42'. If you get an error
+for a lambda expression, you can find what it is with the following command: >
+ :function {'<lambda>42'}
+See also: |numbered-function|
+
==============================================================================
3. Internal variable *internal-variables* *E461*
@@ -1481,7 +1539,7 @@ v:false Special value used to put "false" in JSON and msgpack. See
|json_encode()|. This value is converted to "v:false" when used
as a String (e.g. in |expr5| with string concatenation
operator) and to zero when used as a Number (e.g. in |expr5|
- or |expr7| when used with numeric operators).
+ or |expr7| when used with numeric operators). Read-only.
*v:fcs_reason* *fcs_reason-variable*
v:fcs_reason The reason why the |FileChangedShell| event was triggered.
@@ -1631,7 +1689,7 @@ v:null Special value used to put "null" in JSON and NIL in msgpack.
See |json_encode()|. This value is converted to "v:null" when
used as a String (e.g. in |expr5| with string concatenation
operator) and to zero when used as a Number (e.g. in |expr5|
- or |expr7| when used with numeric operators).
+ or |expr7| when used with numeric operators). Read-only.
*v:oldfiles* *oldfiles-variable*
v:oldfiles List of file names that is loaded from the |shada| file on
@@ -1791,6 +1849,9 @@ v:termresponse The escape sequence returned by the terminal for the |t_RV|
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
@@ -1814,7 +1875,7 @@ v:true Special value used to put "true" in JSON and msgpack. See
|json_encode()|. This value is converted to "v:true" when used
as a String (e.g. in |expr5| with string concatenation
operator) and to one when used as a Number (e.g. in |expr5| or
- |expr7| when used with numeric operators).
+ |expr7| when used with numeric operators). Read-only.
*v:val* *val-variable*
v:val Value of the current item of a |List| or |Dictionary|. Only
@@ -1954,8 +2015,10 @@ foldlevel({lnum}) Number fold level at {lnum}
foldtext() String line displayed for closed fold
foldtextresult({lnum}) String text for closed fold at {lnum}
foreground() Number bring the Vim window to the foreground
-function({name} [, {arglist}] [, {dict}])
+funcref({name} [, {arglist}] [, {dict}])
Funcref reference to function {name}
+function({name} [, {arglist}] [, {dict}])
+ Funcref named reference to function {name}
garbagecollect([{atexit}]) none free memory, breaking cyclic references
get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
@@ -2215,6 +2278,7 @@ tagfiles() List tags files used
tan({expr}) Float tangent of {expr}
tanh({expr}) Float hyperbolic tangent of {expr}
tempname() String name for a temporary file
+test_garbagecollect_now() none free memory right now for testing
timer_start({time}, {callback} [, {options}])
Number create a timer
timer_stop({timer}) none stop a timer
@@ -3369,31 +3433,47 @@ filewritable({file}) *filewritable()*
directory, and we can write to it, the result is 2.
-filter({expr}, {string}) *filter()*
- {expr} must be a |List| or a |Dictionary|.
- For each item in {expr} evaluate {string} and when the result
+filter({expr1}, {expr2}) *filter()*
+ {expr1} must be a |List| or a |Dictionary|.
+ For each item in {expr1} evaluate {expr2} and when the result
is zero remove the item from the |List| or |Dictionary|.
- Inside {string} |v:val| has the value of the current item.
+ {expr2} must be a |string| or |Funcref|.
+
+ if {expr2} is a |string|, inside {expr2} |v:val| has the value
+ of the current item. For a |Dictionary| |v:key| has the key
+ of the current item.
For a |Dictionary| |v:key| has the key of the current item.
Examples: >
- :call filter(mylist, 'v:val !~ "OLD"')
+ call filter(mylist, 'v:val !~ "OLD"')
< Removes the items where "OLD" appears. >
- :call filter(mydict, 'v:key >= 8')
+ call filter(mydict, 'v:key >= 8')
< Removes the items with a key below 8. >
- :call filter(var, 0)
+ call filter(var, 0)
< Removes all the items, thus clears the |List| or |Dictionary|.
- Note that {string} is the result of expression and is then
+ Note that {expr2} is the result of expression and is then
used as an expression again. Often it is good to use a
|literal-string| to avoid having to double backslashes.
+ If {expr2} is a |Funcref| it must take two arguments:
+ 1. the key or the index of the current item.
+ 2. the value of the current item.
+ The function must return TRUE if the item should be kept.
+ Example that keeps the odd items of a list: >
+ func Odd(idx, val)
+ return a:idx % 2 == 1
+ endfunc
+ call filter(mylist, function('Odd'))
+<
The operation is done in-place. If you want a |List| or
|Dictionary| to remain unmodified make a copy first: >
:let l = filter(copy(mylist), 'v:val =~ "KEEP"')
-< Returns {expr}, the |List| or |Dictionary| that was filtered.
- When an error is encountered while evaluating {string} no
- further items in {expr} are processed.
+< Returns {expr1}, the |List| or |Dictionary| that was filtered.
+ When an error is encountered while evaluating {expr2} no
+ further items in {expr1} are processed. When {expr2} is a
+ Funcref errors inside a function are ignored, unless it was
+ defined with the "abort" flag.
finddir({name}[, {path}[, {count}]]) *finddir()*
@@ -3545,12 +3625,31 @@ foreground() Move the Vim window to the foreground. Useful when sent from
|remote_foreground()| instead.
{only in the Win32 GUI and console version}
+ *funcref()*
+funcref({name} [, {arglist}] [, {dict}])
+ Just like |function()|, but the returned Funcref will lookup
+ the function by reference, not by name. This matters when the
+ function {name} is redefined later.
+
+ Unlike |function()|, {name} must be an existing user function.
+ Also for autoloaded functions. {name} cannot be a builtin
+ function.
*function()* *E700* *E922* *E923*
function({name} [, {arglist}] [, {dict}])
Return a |Funcref| variable that refers to function {name}.
{name} can be a user defined function or an internal function.
+ {name} can also be a Funcref or a partial. When it is a
+ partial the dict stored in it will be used and the {dict}
+ argument is not allowed. E.g.: >
+ let FuncWithArg = function(dict.Func, [arg])
+ let Broken = function(dict.Func, [arg], dict)
+<
+ When using the Funcref the function will be found by {name},
+ also when it was redefined later. Use |funcref()| to keep the
+ same function.
+
When {arglist} or {dict} is present this creates a partial.
That mans the argument list and/or the dictionary is stored in
the Funcref and will be used when the Funcref is called.
@@ -3589,18 +3688,25 @@ function({name} [, {arglist}] [, {dict}])
garbagecollect([{atexit}]) *garbagecollect()*
Cleanup unused |Lists| and |Dictionaries| that have circular
- references. There is hardly ever a need to invoke this
- function, as it is automatically done when Vim runs out of
- memory or is waiting for the user to press a key after
- 'updatetime'. Items without circular references are always
- freed when they become unused.
+ references.
+
+ There is hardly ever a need to invoke this function, as it is
+ automatically done when Vim runs out of memory or is waiting
+ for the user to press a key after 'updatetime'. Items without
+ circular references are always freed when they become unused.
This is useful if you have deleted a very big |List| and/or
|Dictionary| with circular references in a script that runs
for a long time.
+
When the optional {atexit} argument is one, garbage
collection will also be done when exiting Vim, if it wasn't
done before. This is useful when checking for memory leaks.
+ The garbage collection is not done immediately but only when
+ it's safe to perform. This is when waiting for the user to
+ type a character. To force garbage collection immediately use
+ |test_garbagecollect_now()|.
+
get({list}, {idx} [, {default}]) *get()*
Get item {idx} from |List| {list}. When this item is not
available return {default}. Return zero when {default} is
@@ -4937,29 +5043,43 @@ log10({expr}) *log10()*
< -2.0
-map({expr}, {string}) *map()*
- {expr} must be a |List| or a |Dictionary|.
- Replace each item in {expr} with the result of evaluating
- {string}.
- Inside {string} |v:val| has the value of the current item.
- For a |Dictionary| |v:key| has the key of the current item
- and for a |List| |v:key| has the index of the current item.
+map({expr1}, {expr2}) *map()*
+ {expr1} must be a |List| or a |Dictionary|.
+ Replace each item in {expr1} with the result of evaluating
+ {expr2}. {expr2} must be a |string| or |Funcref|.
+
+ If {expr2} is a |string|, inside {expr2} |v:val| has the value
+ of the current item. For a |Dictionary| |v:key| has the key
+ of the current item and for a |List| |v:key| has the index of
+ the current item.
Example: >
:call map(mylist, '"> " . v:val . " <"')
< This puts "> " before and " <" after each item in "mylist".
- Note that {string} is the result of an expression and is then
+ Note that {expr2} is the result of an expression and is then
used as an expression again. Often it is good to use a
|literal-string| to avoid having to double backslashes. You
still have to double ' quotes
+ If {expr2} is a |Funcref| it is called with two arguments:
+ 1. The key or the index of the current item.
+ 2. the value of the current item.
+ The function must return the new value of the item. Example
+ that changes each value by "key-value": >
+ func KeyValue(key, val)
+ return a:key . '-' . a:val
+ endfunc
+ call map(myDict, function('KeyValue'))
+<
The operation is done in-place. If you want a |List| or
|Dictionary| to remain unmodified make a copy first: >
:let tlist = map(copy(mylist), ' v:val . "\t"')
-< Returns {expr}, the |List| or |Dictionary| that was filtered.
- When an error is encountered while evaluating {string} no
- further items in {expr} are processed.
+< Returns {expr1}, the |List| or |Dictionary| that was filtered.
+ When an error is encountered while evaluating {expr2} no
+ further items in {expr1} are processed. When {expr2} is a
+ Funcref errors inside a function are ignored, unless it was
+ defined with the "abort" flag.
maparg({name}[, {mode} [, {abbr} [, {dict}]]]) *maparg()*
@@ -6003,6 +6123,7 @@ screenrow() *screenrow()*
The result is a Number, which is the current screen row of the
cursor. The top line has number one.
This function is mainly used for testing.
+ Alternatively you can use |winline()|.
Note: Same restrictions as with |screencol()|.
@@ -7029,6 +7150,14 @@ substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
:echo substitute(s, '%\(\x\x\)',
\ '\=nr2char("0x" . submatch(1))', 'g')
+< When {sub} is a Funcref that function is called, with one
+ optional argument. Example: >
+ :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
+< The optional argument is a list which contains the whole
+ matched string and up to nine submatches,like what
+ |submatch()| returns. Example: >
+ :echo substitute(s, '\(\x\x\)', {m -> '0x' . m[1]}, 'g')
+
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.
@@ -7288,6 +7417,12 @@ termopen({cmd}[, {opts}]) {Nvim} *termopen()*
See |terminal-emulator| for more information.
+test_garbagecollect_now() *test_garbagecollect_now()*
+ Like garbagecollect(), but executed right away. This must
+ only be called directly to avoid any structure to exist
+ internally, and |v:testing| must have been set before calling
+ any function.
+
tan({expr}) *tan()*
Return the tangent of {expr}, measured in radians, as a |Float|
in the range [-inf, inf].
@@ -7379,16 +7514,18 @@ trunc({expr}) *trunc()*
< 4.0
type({expr}) *type()*
- The result is a Number, depending on the type of {expr}:
- Number: 0
- String: 1
- Funcref: 2
- List: 3
- Dictionary: 4
- Float: 5
+ The result is a Number representing the type of {expr}.
+ Instead of using the number directly, it is better to use the
+ v:t_ variable that has the value:
+ Number: 0 (|v:t_number|)
+ String: 1 (|v:t_string|)
+ Funcref: 2 (|v:t_func|)
+ List: 3 (|v:t_list|)
+ Dictionary: 4 (|v:t_dict|)
+ Float: 5 (|v:t_float|)
Boolean: 6 (|v:true| and |v:false|)
Null: 7 (|v:null|)
- To avoid the magic numbers it should be used this way: >
+ For backward compatibility, this method can be used: >
:if type(myvar) == type(0)
:if type(myvar) == type("")
:if type(myvar) == type(function("tr"))
@@ -7399,6 +7536,8 @@ type({expr}) *type()*
< In place of checking for |v:null| type it is better to check
for |v:null| directly as it is the only value of this type: >
:if myvar is v:null
+< To check if the v:t_ variables exist use this: >
+ :if exists('v:t_number')
undofile({name}) *undofile()*
Return the name of the undo file that would be used for a file
@@ -7806,6 +7945,7 @@ 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
@@ -7957,7 +8097,7 @@ last defined. Example: >
See |:verbose-cmd| for more information.
*E124* *E125* *E853* *E884*
-:fu[nction][!] {name}([arguments]) [range] [abort] [dict]
+:fu[nction][!] {name}([arguments]) [range] [abort] [dict] [closure]
Define a new function by the name {name}. The name
must be made of alphanumeric characters and '_', and
must start with a capital or "s:" (see above). Note
@@ -8000,6 +8140,28 @@ See |:verbose-cmd| for more information.
be invoked through an entry in a |Dictionary|. The
local variable "self" will then be set to the
dictionary. See |Dictionary-function|.
+ *:func-closure* *E932*
+ When the [closure] argument is added, the function
+ can access variables and arguments from the outer
+ scope. This is usually called a closure. In this
+ example Bar() uses "x" from the scope of Foo(). It
+ remains referenced even after Foo() returns: >
+ :function! Foo()
+ : let x = 0
+ : function! Bar() closure
+ : let x += 1
+ : return x
+ : endfunction
+ : return function('Bar')
+ :endfunction
+
+ :let F = Foo()
+ :echo F()
+< 1 >
+ :echo F()
+< 2 >
+ :echo F()
+< 3
*function-search-undo*
The last used search pattern and the redo command "."
@@ -8011,7 +8173,7 @@ See |:verbose-cmd| for more information.
:endf[unction] The end of a function definition. Must be on a line
by its own, without other commands.
- *:delf* *:delfunction* *E130* *E131*
+ *:delf* *:delfunction* *E130* *E131* *E933*
:delf[unction] {name} Delete function {name}.
{name} can also be a |Dictionary| entry that is a
|Funcref|: >
@@ -8047,10 +8209,10 @@ can be 0). "a:000" is set to a |List| that contains these arguments. Note
that "a:1" is the same as "a:000[0]".
*E742*
The a: scope and the variables in it cannot be changed, they are fixed.
-However, if a |List| or |Dictionary| is used, you can change their contents.
-Thus you can pass a |List| to a function and have the function add an item to
-it. If you want to make sure the function cannot change a |List| or
-|Dictionary| use |:lockvar|.
+However, if a composite type is used, such as |List| or |Dictionary| , you can
+change their contents. Thus you can pass a |List| to a function and have the
+function add an item to it. If you want to make sure the function cannot
+change a |List| or |Dictionary| use |:lockvar|.
When not using "...", the number of arguments in a function call must be equal
to the number of named arguments. When using "...", the number of arguments
@@ -8062,9 +8224,8 @@ until the matching |:endfunction|. It is allowed to define another function
inside a function body.
*local-variables*
-Inside a function variables can be used. These are local variables, which
-will disappear when the function returns. Global variables need to be
-accessed with "g:".
+Inside a function local variables can be used. These will disappear when the
+function returns. Global variables need to be accessed with "g:".
Example: >
:function Table(title, ...)
diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt
index a82e17c857..2d3eaafe63 100644
--- a/runtime/doc/insert.txt
+++ b/runtime/doc/insert.txt
@@ -370,9 +370,6 @@ CTRL-G U don't break undo with next left/right cursor *i_CTRL-G_U*
within same the line)
-----------------------------------------------------------------------
-Note: If the cursor keys take you out of Insert mode, check the 'noesckeys'
-option.
-
The CTRL-O command sometimes has a side effect: If the cursor was beyond the
end of the line, it will be put on the last character in the line. In
mappings it's often better to use <Esc> (first put an "x" in the text, <Esc>
diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt
index 8f7dc0dbf0..0954dcb5a7 100644
--- a/runtime/doc/nvim_terminal_emulator.txt
+++ b/runtime/doc/nvim_terminal_emulator.txt
@@ -4,28 +4,19 @@
NVIM REFERENCE MANUAL by Thiago de Arruda
-Embedded terminal emulator *terminal-emulator*
+Terminal emulator *terminal-emulator*
-1. Introduction |terminal-emulator-intro|
-2. Spawning |terminal-emulator-spawning|
-3. Input |terminal-emulator-input|
-4. Configuration |terminal-emulator-configuration|
-5. Status Variables |terminal-emulator-status|
+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.
-==============================================================================
-1. Introduction *terminal-emulator-intro*
-
-Nvim offers a mostly complete VT220/xterm terminal emulator. The terminal is
-presented as a special buffer type, asynchronously updated to mirror the
-virtual terminal display as data is received from the program connected to it.
-For most purposes, terminal buffers behave a lot like normal buffers with
-'nomodifiable' set.
-
-The implementation is powered by libvterm, a powerful abstract terminal
-emulation library. http://www.leonerd.org.uk/code/libvterm/
+Terminal buffers behave mostly like normal 'nomodifiable' buffers, except:
+- Plugins can set 'modifiable' to modify text, but lines cannot be deleted.
+- 'scrollback' controls how many off-screen lines are kept.
+- Terminal output is followed if the cursor is on the last line.
==============================================================================
-2. Spawning *terminal-emulator-spawning*
+Spawning *terminal-emulator-spawning*
There are 3 ways to create a terminal buffer:
@@ -40,34 +31,27 @@ 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
-< This is only mentioned for reference; you should use the |:terminal|
- command instead.
+< This is only mentioned for reference; use |:terminal| instead.
When the terminal spawns the program, the buffer will start to mirror the
-terminal display and change its name to `term://$CWD//$PID:$COMMAND`.
-Note that |:mksession| will "save" the terminal buffers by restarting all
-programs when the session is restored.
+terminal display and change its name to `term://{cwd}//{pid}:{cmd}`.
+The "term://..." scheme enables |:mksession| to "restore" a terminal buffer by
+restarting the {cmd} when the session is loaded.
==============================================================================
-3. Input *terminal-emulator-input*
-
-Sending input is possible by entering terminal mode, which is achieved by
-pressing any key that would enter insert mode in a normal buffer (|i| or |a|
-for example). The |:terminal| ex command will automatically enter terminal
-mode once it's spawned. While in terminal mode, Nvim will forward all keys to
-the underlying program. The only exception is the <C-\><C-n> key combo,
-which will exit back to normal mode.
-
-Terminal mode has its own namespace for mappings, which is accessed with the
-"t" prefix. It's possible to use terminal mappings to customize interaction
-with the terminal. For example, here's how to map <Esc> to exit terminal mode:
->
+Input *terminal-emulator-input*
+
+To send input, enter terminal mode using any command that would enter "insert
+mode" in a normal buffer, such as |i| or |:startinsert|. In this mode all keys
+except <C-\><C-N> are sent to the underlying program. Use <C-\><C-N> to return
+to normal mode. |CTRL-\_CTRL-N|
+
+Terminal mode has its own |:tnoremap| namespace for mappings, this can be used
+to automate any terminal interaction. To map <Esc> to exit terminal mode: >
:tnoremap <Esc> <C-\><C-n>
<
-Navigating to other windows is only possible by exiting to normal mode, which
-can be cumbersome with <C-\><C-n> keys. To improve the navigation experience,
-you could use the following mappings:
->
+Navigating to other windows is only possible in normal mode. For convenience,
+you could use these mappings: >
:tnoremap <A-h> <C-\><C-n><C-w>h
:tnoremap <A-j> <C-\><C-n><C-w>j
:tnoremap <A-k> <C-\><C-n><C-w>k
@@ -77,11 +61,9 @@ you could use the following mappings:
:nnoremap <A-k> <C-w>k
:nnoremap <A-l> <C-w>l
<
-This configuration allows using `Alt+{h,j,k,l}` to navigate between windows no
-matter if they are displaying a normal buffer or a terminal buffer in terminal
-mode.
+Then you can use `Alt+{h,j,k,l}` to navigate between windows from any mode.
-Mouse input is also fully supported, and has the following behavior:
+Mouse input is supported, and has the following behavior:
- If the program has enabled mouse events, the corresponding events will be
forwarded to the program.
@@ -93,28 +75,23 @@ Mouse input is also fully supported, and has the following behavior:
the terminal wont lose focus and the hovered window will be scrolled.
==============================================================================
-4. Configuration *terminal-emulator-configuration*
+Configuration *terminal-emulator-configuration*
+
+Options: 'scrollback'
+Events: |TermOpen|, |TermClose|
+Highlight groups: |hl-TermCursor|, |hl-TermCursorNC|
-Terminal buffers can be customized through the following global/buffer-local
-variables (set via the |TermOpen| autocmd):
+Terminal colors can be customized with these variables:
-- `{g,b}:terminal_scrollback_buffer_size`: Scrollback buffer size, between 1
- and 100000 inclusive. The default is 1000.
- `{g,b}:terminal_color_$NUM`: 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 simply forwarded.
-The configuration variables are only processed when the terminal starts, which
-is why it needs to be done with the |TermOpen| autocmd or setting global
-variables before the terminal is started.
-
-There is also a corresponding |TermClose| event.
-
-The terminal cursor can be highlighted via |hl-TermCursor| and
-|hl-TermCursorNC|.
+The `{g,b}:terminal_color_$NUM` variables are processed only when the terminal
+starts (after |TermOpen|).
==============================================================================
-5. Status Variables *terminal-emulator-status*
+Status Variables *terminal-emulator-status*
Terminal buffers maintain some information about the terminal in buffer-local
variables:
@@ -127,11 +104,8 @@ variables:
- *b:terminal_job_pid* The PID of the top-level process running in the
terminal.
-These variables will have a value by the time the TermOpen autocmd runs, and
-will continue to have a value for the lifetime of the terminal buffer, making
-them suitable for use in 'statusline'. For example, to show the terminal title
-as the status line:
->
+These variables are initialized before TermOpen, so you can use them in
+a local 'statusline'. Example: >
:autocmd TermOpen * setlocal statusline=%{b:term_title}
<
==============================================================================
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 97d56af369..25dca5fb51 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -2209,18 +2209,6 @@ A jump table for the options with a short description can be found at |Q_op|.
Scanf-like description of the format for the lines in the error file
(see |errorformat|).
- *'esckeys'* *'ek'* *'noesckeys'* *'noek'*
-'esckeys' 'ek' boolean (Vim default: on, Vi default: off)
- global
- Function keys that start with an <Esc> are recognized in Insert
- mode. When this option is off, the cursor and function keys cannot be
- used in Insert mode if they start with an <Esc>. The advantage of
- this is that the single <Esc> is recognized immediately, instead of
- after one second. Instead of resetting this option, you might want to
- try changing the values for 'timeoutlen' and 'ttimeoutlen'. Note that
- when 'esckeys' is off, you can still map anything, but the cursor keys
- won't work by default.
-
*'eventignore'* *'ei'*
'eventignore' 'ei' string (default "")
global
@@ -4961,6 +4949,16 @@ A jump table for the options with a short description can be found at |Q_op|.
be used as the new value for 'scroll'. Reset to half the window
height with ":set scroll=0".
+ *'scrollback'* *'scbk'*
+'scrollback' 'scbk' number (default: 1000
+ in normal buffers: -1)
+ local to buffer
+ Maximum number of lines kept beyond the visible screen. Lines at the
+ top are deleted if new lines exceed this limit.
+ Only in |terminal-emulator| buffers. 'buftype'
+ -1 means "unlimited" for normal buffers, 100000 otherwise.
+ Minimum is 1.
+
*'scrollbind'* *'scb'* *'noscrollbind'* *'noscb'*
'scrollbind' 'scb' boolean (default off)
local to window
@@ -6285,6 +6283,9 @@ A jump table for the options with a short description can be found at |Q_op|.
By default, tag searches are case-sensitive. Case is ignored when
'ignorecase' is set and 'tagcase' is "followic", or when 'tagcase' is
"ignore".
+ Also when 'tagcase' is "followscs" and 'smartcase' is set, or
+ 'tagcase' is "smart", and the pattern contains only lowercase
+ characters.
When 'tagbsearch' is off, tags searching is slower when a full match
exists, but faster when no full match exists. Tags in unsorted tags
@@ -6302,8 +6303,10 @@ A jump table for the options with a short description can be found at |Q_op|.
This option specifies how case is handled when searching the tags
file:
followic Follow the 'ignorecase' option
+ followscs Follow the 'smartcase' and 'ignorecase' options
ignore Ignore case
match Match case
+ smart Ignore case unless an upper case letter is used
*'taglength'* *'tl'*
'taglength' 'tl' number (default 0)
diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
index 3cd53e3e50..ac4d7361f4 100644
--- a/runtime/doc/provider.txt
+++ b/runtime/doc/provider.txt
@@ -49,7 +49,8 @@ Note: The `--upgrade` flag ensures you have the latest version even if
PYTHON PROVIDER CONFIGURATION ~
*g:python_host_prog*
*g:python3_host_prog*
-Program to use for evaluating Python code. Setting this makes startup faster. >
+Program to use for evaluating Python code. Setting this makes startup faster.
+Also useful for working with virtualenvs. >
let g:python_host_prog = '/path/to/python'
let g:python3_host_prog = '/path/to/python3'
<
@@ -61,6 +62,23 @@ To disable Python 2 support: >
To disable Python 3 support: >
let g:loaded_python3_provider = 1
+PYTHON VIRTUALENVS ~
+
+If you plan to use per-project virtualenvs often, you should assign
+a virtualenv for Neovim and hard-code the interpreter path via
+|g:python_host_prog| (or |g:python3_host_prog|) so that the "neovim" python
+package is not required for each Environment. Example using pyenv: >
+ pyenv install 3.4.4
+ pyenv virtualenv 3.4.4 py3neovim
+ pyenv activate py3neovim
+ pip install neovim
+ pyenv which python # Note the path
+
+The last command reports the interpreter path. Add it to your init.vim: >
+ let g:python3_host_prog = '/full/path/to/py3neovim/bin/python'
+
+More information:
+https://github.com/zchee/deoplete-jedi/wiki/Setting-up-Python-for-Neovim
==============================================================================
Ruby integration *provider-ruby*
@@ -80,7 +98,6 @@ RUBY PROVIDER CONFIGURATION ~
To disable Ruby support: >
let g:loaded_ruby_provider = 1
-
==============================================================================
Clipboard integration *provider-clipboard* *clipboard*
@@ -93,7 +110,7 @@ are found in your `$PATH`.
- xclip
- xsel (newer alternative to xclip)
- - pbcopy/pbpaste (Mac OS X)
+ - pbcopy/pbpaste (macOS)
- lemonade (for SSH) https://github.com/pocke/lemonade
- doitclient (for SSH) http://www.chiark.greenend.org.uk/~sgtatham/doit/
diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt
index a7644fab84..2e2bec7637 100644
--- a/runtime/doc/quickref.txt
+++ b/runtime/doc/quickref.txt
@@ -678,7 +678,6 @@ Short explanation of each option: *option-list*
'errorbells' 'eb' ring the bell for error messages
'errorfile' 'ef' name of the errorfile for the QuickFix mode
'errorformat' 'efm' description of the lines in the error file
-'esckeys' 'ek' recognize function keys in Insert mode
'eventignore' 'ei' autocommand events that are ignored
'expandtab' 'et' use spaces when <Tab> is inserted
'exrc' 'ex' read .nvimrc and .exrc in the current directory
diff --git a/runtime/doc/tagsrch.txt b/runtime/doc/tagsrch.txt
index 75d820d072..047abb42cc 100644
--- a/runtime/doc/tagsrch.txt
+++ b/runtime/doc/tagsrch.txt
@@ -83,14 +83,23 @@ Note that when the current file changes, the priority list is mostly not
changed, to avoid confusion when using ":tnext". It is changed when using
":tag {ident}".
-The ignore-case matches are not found for a ":tag" command when the
-'ignorecase' option is off and 'tagcase' is "followic" or when 'tagcase' is
-"match". They are found when a pattern is used (starting with a "/") and for
-":tselect", also when 'ignorecase' is off and 'tagcase' is "followic" or when
-'tagcase' is "match". Note that using ignore-case tag searching disables
-binary searching in the tags file, which causes a slowdown. This can be
-avoided by fold-case sorting the tag file. See the 'tagbsearch' option for an
-explanation.
+The ignore-case matches are not found for a ":tag" command when:
+- the 'ignorecase' option is off and 'tagcase' is "followic"
+- 'tagcase' is "match"
+- 'tagcase' is "smart" and the pattern contains an upper case character.
+- 'tagcase' is "followscs" and 'smartcase' option is on and the pattern
+ contains an upper case character.
+
+The gnore-case matches are found when:
+- a pattern is used (starting with a "/")
+- for ":tselect"
+- when 'tagcase' is "followic" and 'ignorecase' is off
+- when 'tagcase' is "match"
+- when 'tagcase' is "followscs" and the 'smartcase' option is off
+
+Note that using ignore-case tag searching disables binary searching in the
+tags file, which causes a slowdown. This can be avoided by fold-case sorting
+the tag file. See the 'tagbsearch' option for an explanation.
==============================================================================
2. Tag stack *tag-stack* *tagstack* *E425*
@@ -420,13 +429,18 @@ file "tags". It can also be used to access a common tags file.
The next file in the list is not used when:
- A matching static tag for the current buffer has been found.
- A matching global tag has been found.
-This also depends on whether case is ignored. Case is ignored when
-'ignorecase' is set and 'tagcase' is "followic", or when 'tagcase' is
-"ignore". If case is not ignored, and the tags file only has a match without
-matching case, the next tags file is searched for a match with matching case.
-If no tag with matching case is found, the first match without matching case
-is used. If case is ignored, and a matching global tag with or without
-matching case is found, this one is used, no further tags files are searched.
+This also depends on whether case is ignored. Case is ignored when:
+- 'tagcase' is "followic" and 'ignorecase' is set
+- 'tagcase' is "ignore"
+- 'tagcase' is "smart" and and the pattern only contains lower case
+ characters.
+- 'tagcase' is "followscs" and 'smartcase' is set and and the pattern only
+ contains lower case characters.
+If case is not ignored, and the tags file only has a match without matching
+case, the next tags file is searched for a match with matching case. If no
+tag with matching case is found, the first match without matching case is
+used. If case is ignored, and a matching global tag with or without matching
+case is found, this one is used, no further tags files are searched.
When a tag file name starts with "./", the '.' is replaced with the path of
the current file. This makes it possible to use a tags file in the directory
diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt
index 08ffee7a2f..137d3a06db 100644
--- a/runtime/doc/term.txt
+++ b/runtime/doc/term.txt
@@ -70,9 +70,7 @@ for a next character to arrive. If it does not arrive within one second a
single <Esc> is assumed. On very slow systems this may fail, causing cursor
keys not to work sometimes. If you discover this problem reset the 'timeout'
option. Vim will wait for the next character to arrive after an <Esc>. If
-you want to enter a single <Esc> you must type it twice. Resetting the
-'esckeys' option avoids this problem in Insert mode, but you lose the
-possibility to use cursor and function keys in Insert mode.
+you want to enter a single <Esc> you must type it twice.
Some terminals have confusing codes for the cursor keys. The televideo 925 is
such a terminal. It sends a CTRL-H for cursor-left. This would make it
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index 7d08a6f32a..9a2472e394 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -207,23 +207,15 @@ g8 Print the hex values of the bytes used in the
:sh[ell] Removed. |vim-differences| {Nvim}
*:terminal* *:te*
-:te[rminal][!] {cmd} Spawns {cmd} using the current value of 'shell' and
- 'shellcmdflag' in a new terminal buffer. This is
- equivalent to: >
-
+:te[rminal][!] {cmd} Execute {cmd} with 'shell' in a |terminal-emulator|
+ buffer. Equivalent to: >
:enew
:call termopen('{cmd}')
:startinsert
<
- If no {cmd} is given, 'shellcmdflag' will not be sent
- to |termopen()|.
-
- Like |:enew|, it will fail if the current buffer is
- modified, but can be forced with "!". See |termopen()|
- and |terminal-emulator|.
+ See |jobstart()|.
- To switch to terminal mode automatically:
->
+ To enter terminal mode automatically: >
autocmd BufEnter term://* startinsert
<
*:!cmd* *:!* *E34*
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index eeb5e85036..bcc5d03ff0 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -238,6 +238,8 @@ newly allocated memory all over the place) and fail on types which cannot be
coerced to strings. See |id()| for more details, currently it uses
`printf("%p", {expr})` internally.
+|c_CTRL-R| pasting a non-special register into |cmdline| omits the last <CR>.
+
==============================================================================
5. Missing legacy features *nvim-features-missing*
*if_lua* *if_perl* *if_mzscheme* *if_tcl*
@@ -298,6 +300,7 @@ Other options:
'antialias'
'cpoptions' ("g", "w", "H", "*", "-", "j", and all POSIX flags were removed)
'encoding' ("utf-8" is always used)
+ 'esckeys'
'guioptions' "t" flag was removed
*'guipty'* (Nvim uses pipes and PTYs consistently on all platforms.)
*'imactivatefunc'* *'imaf'*
diff --git a/runtime/optwin.vim b/runtime/optwin.vim
index a7b94d73d4..64726937a0 100644
--- a/runtime/optwin.vim
+++ b/runtime/optwin.vim
@@ -524,8 +524,6 @@ endif
call <SID>Header("terminal")
-call append("$", "esckeys\trecognize keys that start with <Esc> in Insert mode")
-call <SID>BinOptionG("ek", &ek)
call append("$", "scrolljump\tminimal number of lines to scroll at a time")
call append("$", " \tset sj=" . &sj)
if has("gui") || has("msdos") || has("win32")
generated by cgit (git 2.34.1) at 2025-12-29 17:29:08 +0000