Nvim :help
pages, generated
from source
using the tree-sitter-vimdoc parser.
local-function
A function local to a script must start with "s:". A local script function
can only be called from within the script and from functions, user commands
and autocommands defined in the script. It is also possible to call the
function from a mapping defined in the script, but then <SID> must be used
instead of "s:" when the mapping is expanded outside of the script.
There are only script-local functions, no buffer-local or window-local
functions.{name}
List function {name}
, annotated with line numbers
unless "!" is given.
{name}
may be a Dictionary Funcref entry::function dict.init
{name}
is not an expression, you cannot use
a variable that is a function reference. You can use
this dirty trick to list the function referred to with
variable "Funcref":let g:MyFuncref = Funcref func g:MyFuncref unlet g:MyFuncref:fu[nction] /{pattern} List functions with a name matching
{pattern}
.
Example that lists all functions ending with "File"::function /File$
:function-verbose
When 'verbose' is non-zero, listing a function will also display where it was
last defined. Example::verbose function SetFileTypeSH function SetFileTypeSH(name) Last set from /usr/share/vim/vim-7.0/filetype.vim
E124
E125
E853
E884
:fu[nction][!] {name}
([arguments]) [range] [abort] [dict] [closure]
Define a new function by the name {name}
. The body of
the function follows in the next lines, until the
matching :endfunction.E127
E122
When a function by this name already exists and [!] is
not used an error message is given. There is one
exception: When sourcing a script again, a function
that was previously defined in that script will be
silently replaced.
When [!] is used, an existing function is silently
replaced. Unless it is currently being executed, that
is an error.
NOTE: Use ! wisely. If used without care it can cause
an existing function to be replaced unexpectedly,
which is hard to debug.{arguments}
see function-argument.:func-range
a:firstline
a:lastline
When the [range] argument is added, the function is
expected to take care of a range itself. The range is
passed as "a:firstline" and "a:lastline". If [range]
is excluded, ":{range}call" will call the function for
each line in the range, with the cursor on the start
of each line. See function-range-example.
The cursor is still moved to the first line of the
range, as is the case with all Ex commands.
:func-abort
When the [abort] argument is added, the function will
abort as soon as an error is detected.
:func-dict
When the [dict] argument is added, the function must
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 funcref('Bar') :endfunction :let F = Foo() :echo F()
:echo F()
:echo F()
function-search-undo
The last used search pattern and the redo command "."
will not be changed by the function. This also
implies that the effect of :nohlsearch is undone
when the function returns.:endf
:endfunction
E126
E193
W22
:endf[unction] [argument]
The end of a function definition. Best is to put it
on a line by its own, without [argument].:execute
command, use line breaks instead of :bar::exe "func Foo()\necho 'foo'\nendfunc"
:delf
:delfunction
E131
E933
:delf[unction][!] {name}
Delete function {name}
.
{name}
can also be a Dictionary entry that is a
Funcref::delfunc dict.init
:retu
:return
E133
:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
evaluated and returned as the result of the function.
If "[expr]" is not given, the number 0 is returned.
When a function ends without an explicit ":return",
the number 0 is returned.
Note that there is no check for unreachable lines,
thus there is no warning if commands follow ":return".
Also, there is no check if the following
line contains a valid command. Forgetting the line
continuation backslash may go unnoticed:return 'some text' .. ' some more text'
return 'some text' \ .. ' some more text'
function-argument
a:var
An argument can be defined by giving its name. In the function this can then
be used as "a:name" ("a:" for argument).
a:0
a:1
a:000
E740
...
Up to 20 arguments can be given, separated by commas. After the named
arguments an argument "..." can be specified, which means that more arguments
may optionally be following. In the function the extra arguments can be used
as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
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 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.optional-function-argument
You can provide default values for positional named arguments. This makes
them optional for function calls. When a positional argument is not
specified at a call, the default expression is used to initialize it.
This only works for functions declared with :function
, not for
lambda expressions expr-lambda.function Something(key, value = 10) echo a:key .. ": " .. a:value endfunction call Something('empty') "empty: 10" call Something('key', 20) "key: 20"The argument default expressions are evaluated at the time of the function call, not when the function is defined. Thus it is possible to use an expression which is invalid the moment the function is defined. The expressions are also only evaluated when arguments are not specified during a call.
E989
Optional arguments with default expressions must occur after any mandatory
arguments. You can use "..." after all optional named arguments.:function Okay(mandatory, optional = a:mandatory) :endfunctionExample that does NOT work:
:function NoGood(first = a:second, second = 10) :endfunction
local-variables
Inside a function local variables can be used. These will disappear when the
function returns. Global variables need to be accessed with "g:". Inside
functions local variables are accessed without prepending anything. But you
can also prepend "l:" if you like. This is required for some reserved names,
such as "version".:function Table(title, ...) : echohl Title : echo a:title : echohl None : echo a:0 .. " items:" : for s in a:000 : echon ' ' .. s : endfor :endfunctionThis function can then be called with:
call Table("Table", "line1", "line2") call Table("Empty Table")To return more than one value, return a List:
:function Compute(n1, n2) : if a:n2 == 0 : return ["fail", 0] : endif : return ["ok", a:n1 / a:n2] :endfunctionThis function can then be called with:
:let [success, div] = Compute(102, 6) :if success == "ok" : echo div :endif
:cal
:call
E107
E117
:[range]cal[l] {name}
([arguments])
Call a function. The name of the function and its arguments
are as specified with :function
. Up to 20 arguments can be
used. The returned value is discarded.
Without a range and for functions that accept a range, the
function is called once. When a range is given the cursor is
positioned at the start of the first line before executing the
function.
When a range is given and the function doesn't handle it
itself, the function is executed for each line in the range,
with the cursor in the first column of that line. The cursor
is left at the last line (possibly moved by the last function
call). The arguments are re-evaluated for each line. Thus
this works:
function-range-example
:function Mynumber(arg) : echo line(".") .. " " .. a:arg :endfunction :1,5call Mynumber(getline("."))
:function Cont() range : execute (a:firstline + 1) .. "," .. a:lastline .. 's/^/\t\\ ' :endfunction :4,8call Cont()
:4,8call GetDict().method()
E132
The recursiveness of user functions is restricted with the 'maxfuncdepth'
option.:eval
. It does not support a range, but does
allow for method chaining, e.g.:eval GetList()->Filter()->append('$')A function can also be called as part of evaluating an expression or when it is used as a method:
let x = GetList() let y = GetList()->Filter()
:defer
:defer {func}
({args}
) Call {func}
when the current function is done.
{args}
are evaluated here.try
/ finally
blocks, but this gets complicated when there is more
than one.defer
. It schedules a function call when
the function is returning, no matter if there is an error. Example:func Filter(text) abort call writefile(a:text, 'Tempfile') call system('filter < Tempfile > Outfile') call Handle('Outfile') call delete('Tempfile') call delete('Outfile') endfuncHere 'Tempfile' and 'Outfile' will not be deleted if something causes the function to abort.
:defer
can be used to avoid that:func Filter(text) abort call writefile(a:text, 'Tempfile') defer delete('Tempfile') defer delete('Outfile') call system('filter < Tempfile > Outfile') call Handle('Outfile') endfuncNote that deleting "Outfile" is scheduled before calling
system()
, since it
can be created even when system()
fails.func Useless() abort for s in range(3) defer execute('echomsg "number ' .. s .. '"') endfor endfuncNow
:messages
shows:
number 2
number 1
number 0E1300
autoload-functions
When using many or large functions, it's possible to automatically define them
only when they are used. There are two methods: with an autocommand and with
the "autoload" directory in 'runtimepath'.:finish
.
That makes Vim startup faster. The autocommand should then load the same file
again, setting a variable to skip the :finish
command.:au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vimThe file "~/vim/bufnetfuncs.vim" should then define functions that start with "BufNet". Also see FuncUndefined.
:call filename#funcname()When such a function is called, and it is not defined yet, Vim will search the "autoload" directories in 'runtimepath' for a script file called "filename.vim". For example "~/.config/nvim/autoload/filename.vim". That file should then define the function like this:
function filename#funcname() echo "Done!" endfunctionIf the file doesn't exist, Vim will also search in 'packpath' (under "start") to allow calling packages' functions from your vimrc when the packages have not been added to 'runtimepath' yet (see packages).
:call foo#bar#func()Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
:let l = foo#bar#lvarHowever, when the autoload script was already loaded it won't be loaded again for an unknown variable.
:let foo#bar#toggle = 1 :call foo#bar#func()Note that when you make a mistake and call a function that is supposed to be defined in an autoload script, but the script doesn't actually define the function, you will get an error message for the missing function. If you fix the autoload script it won't be automatically loaded again. Either restart Vim or manually source the script.