mirror of
https://github.com/neovim/neovim.git
synced 2024-12-20 03:05:11 -07:00
ee26b227e1
Update runtime files.
938ae280c7
Partially skip autocmd.txt: needs patch 8.2.5011.
Partially skip builtin.txt: needs patch 9.0.0411.
Partially skip eval.txt: needs patch 8.2.3783.
Cherry-pick :map-meta-keys from patch 9.0.1276.
Co-authored-by: Bram Moolenaar <Bram@vim.org>
442 lines
16 KiB
Plaintext
442 lines
16 KiB
Plaintext
*userfunc.txt* Nvim
|
|
|
|
|
|
VIM REFERENCE MANUAL by Bram Moolenaar
|
|
|
|
|
|
Defining and using functions.
|
|
|
|
This is introduced in section |41.7| of the user manual.
|
|
|
|
Type |gO| to see the table of contents.
|
|
|
|
==============================================================================
|
|
|
|
1. Defining a function ~
|
|
*define-function*
|
|
New functions can be defined. These can be called just like builtin
|
|
functions. The function executes a sequence of Ex commands. Normal mode
|
|
commands can be executed with the |:normal| command.
|
|
|
|
The function name must start with an uppercase letter, to avoid confusion with
|
|
builtin functions. To prevent from using the same name in different scripts
|
|
make them script-local. If you do use a global function then avoid obvious,
|
|
short names. A good habit is to start the function name with the name of the
|
|
script, e.g., "HTMLcolor()".
|
|
|
|
It is also possible to use curly braces, see |curly-braces-names|.
|
|
|
|
The |autoload| facility is useful to define a function only when it's called.
|
|
|
|
*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.
|
|
|
|
*:fu* *:function* *E128* *E129* *E123*
|
|
:fu[nction] List all functions and their arguments.
|
|
|
|
:fu[nction][!] {name} List function {name}, annotated with line numbers
|
|
unless "!" is given.
|
|
{name} may be a |Dictionary| |Funcref| entry: >
|
|
:function dict.init
|
|
|
|
: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
|
|
<
|
|
See |:verbose-cmd| for more information.
|
|
|
|
*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|.
|
|
|
|
The name must be made of alphanumeric characters and
|
|
'_', and must start with a capital or "s:" (see
|
|
above). Note that using "b:" or "g:" is not allowed.
|
|
(since patch 7.4.260 E884 is given if the function
|
|
name has a colon in the name, e.g. for "foo:bar()".
|
|
Before that patch no error was given).
|
|
|
|
{name} can also be a |Dictionary| entry that is a
|
|
|Funcref|: >
|
|
:function dict.init(arg)
|
|
< "dict" must be an existing dictionary. The entry
|
|
"init" is added if it didn't exist yet. Otherwise [!]
|
|
is required to overwrite an existing function. The
|
|
result is a |Funcref| to a numbered function. The
|
|
function can only be used with a |Funcref| and will be
|
|
deleted if there are no more references to it.
|
|
*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.
|
|
|
|
For the {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()
|
|
< 1 >
|
|
:echo F()
|
|
< 2 >
|
|
:echo F()
|
|
< 3
|
|
|
|
*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].
|
|
|
|
[argument] can be:
|
|
| command command to execute next
|
|
\n command command to execute next
|
|
" comment always ignored
|
|
anything else ignored, warning given when
|
|
'verbose' is non-zero
|
|
The support for a following command was added in Vim
|
|
8.0.0654, before that any argument was silently
|
|
ignored.
|
|
|
|
To be able to define a function inside an `: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
|
|
< This will remove the "init" entry from "dict". The
|
|
function is deleted if there are no more references to
|
|
it.
|
|
With the ! there is no error if the function does not
|
|
exist.
|
|
*: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'
|
|
< Will happily return "some text" without an error. It
|
|
should have been: >
|
|
return 'some text'
|
|
\ .. ' some more text'
|
|
<
|
|
If the ":return" is used after a |:try| but before the
|
|
matching |:finally| (if present), the commands
|
|
following the ":finally" up to the matching |:endtry|
|
|
are executed first. This process applies to all
|
|
nested ":try"s inside the function. The function
|
|
returns at the outermost ":endtry".
|
|
|
|
*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|.
|
|
|
|
It is also possible to define a function without any arguments. You must
|
|
still supply the () then.
|
|
|
|
It is allowed to define another function inside a function body.
|
|
|
|
*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|.
|
|
|
|
Example: >
|
|
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.
|
|
|
|
It is possible for later argument defaults to refer to prior arguments,
|
|
but not the other way around. They must be prefixed with "a:", as with all
|
|
arguments.
|
|
|
|
Example that works: >
|
|
:function Okay(mandatory, optional = a:mandatory)
|
|
:endfunction
|
|
Example that does NOT work: >
|
|
:function NoGood(first = a:second, second = 10)
|
|
:endfunction
|
|
<
|
|
When not using "...", the number of arguments in a function call must be at
|
|
least equal to the number of mandatory named arguments. When using "...", the
|
|
number of arguments may be larger than the total of mandatory and optional
|
|
arguments.
|
|
|
|
*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".
|
|
|
|
Example: >
|
|
:function Table(title, ...)
|
|
: echohl Title
|
|
: echo a:title
|
|
: echohl None
|
|
: echo a:0 .. " items:"
|
|
: for s in a:000
|
|
: echon ' ' .. s
|
|
: endfor
|
|
:endfunction
|
|
|
|
This 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]
|
|
:endfunction
|
|
|
|
This function can then be called with: >
|
|
:let [success, div] = Compute(102, 6)
|
|
:if success == "ok"
|
|
: echo div
|
|
:endif
|
|
<
|
|
==============================================================================
|
|
|
|
2. Calling a function ~
|
|
*: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("."))
|
|
<
|
|
The "a:firstline" and "a:lastline" are defined anyway, they
|
|
can be used to do something different at the start or end of
|
|
the range.
|
|
|
|
Example of a function that handles the range itself: >
|
|
|
|
:function Cont() range
|
|
: execute (a:firstline + 1) .. "," .. a:lastline .. 's/^/\t\\ '
|
|
:endfunction
|
|
:4,8call Cont()
|
|
<
|
|
This function inserts the continuation character "\" in front
|
|
of all the lines in the range, except the first one.
|
|
|
|
When the function returns a composite value it can be further
|
|
dereferenced, but the range will not be used then. Example: >
|
|
:4,8call GetDict().method()
|
|
< Here GetDict() gets the range but method() does not.
|
|
|
|
*E132*
|
|
The recursiveness of user functions is restricted with the |'maxfuncdepth'|
|
|
option.
|
|
|
|
It is also possible to use `: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()
|
|
|
|
|
|
==============================================================================
|
|
3. Automatically loading functions ~
|
|
*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'.
|
|
|
|
|
|
Using an autocommand ~
|
|
|
|
This is introduced in the user manual, section |41.14|.
|
|
|
|
The autocommand is useful if you have a plugin that is a long Vim script file.
|
|
You can define the autocommand and quickly quit the script with `:finish`.
|
|
That makes Vim startup faster. The autocommand should then load the same file
|
|
again, setting a variable to skip the `:finish` command.
|
|
|
|
Use the FuncUndefined autocommand event with a pattern that matches the
|
|
function(s) to be defined. Example: >
|
|
|
|
:au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
|
|
|
|
The file "~/vim/bufnetfuncs.vim" should then define functions that start with
|
|
"BufNet". Also see |FuncUndefined|.
|
|
|
|
|
|
Using an autoload script ~
|
|
*autoload* *E746*
|
|
This is introduced in the user manual, section |41.15|.
|
|
|
|
Using a script in the "autoload" directory is simpler, but requires using
|
|
exactly the right file name. A function that can be autoloaded has a name
|
|
like this: >
|
|
|
|
: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!"
|
|
endfunction
|
|
|
|
If 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|).
|
|
|
|
The file name and the name used before the # in the function must match
|
|
exactly, and the defined function must have the name exactly as it will be
|
|
called.
|
|
|
|
It is possible to use subdirectories. Every # in the function name works like
|
|
a path separator. Thus when calling a function: >
|
|
|
|
:call foo#bar#func()
|
|
|
|
Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
|
|
|
|
This also works when reading a variable that has not been set yet: >
|
|
|
|
:let l = foo#bar#lvar
|
|
|
|
However, when the autoload script was already loaded it won't be loaded again
|
|
for an unknown variable.
|
|
|
|
When assigning a value to such a variable nothing special happens. This can
|
|
be used to pass settings to the autoload script before it's loaded: >
|
|
|
|
: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.
|
|
|
|
Also note that if you have two script files, and one calls a function in the
|
|
other and vice versa, before the used function is defined, it won't work.
|
|
Avoid using the autoload functionality at the toplevel.
|
|
|
|
Hint: If you distribute a bunch of scripts read |distribute-script|.
|
|
|
|
|
|
vim:tw=78:ts=8:noet:ft=help:norl:
|