💾 Archived View for gmi.noulin.net › vim › userfunc.gmi captured on 2024-05-12 at 16:15:04. Gemini links have been rewritten to link to archived content
View Raw
More Information
⬅️ Previous capture (2024-02-05)
-=-=-=-=-=-=-
- userfunc.txt* For Vim version 9.1. Last change: 2023 May 23
VIM REFERENCE MANUAL by Bram Moolenaar
Defining and using functions.
This is introduced in section |41.7| of the user manual.
1. Defining a function |define-function|
2. Calling a function |:call|
3. Cleaning up in a function |:defer|
4. Automatically loading functions |autoload-functions|
==============================================================================
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()".
In legacy script 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 legacy 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.
In |Vim9| script functions are local to the script by default, prefix "g:" to
define a global function.
*:fu* *:function* *E128* *E129* *E123* *E454*
:fu[nction] List all functions and their arguments.
:fu[nction] {name} List function {name}.
{name} can also be a |Dictionary| entry that is a
|Funcref|: >
:function dict.init
< Note that {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
<
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|.
*E1267*
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.
NOTE: In Vim9 script script-local functions cannot be
deleted or redefined.
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* *E1151*
: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* *E1084*
: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.
In a :def function *E1095* is given if unreachable
code follows after the `:return`.
In legacy script 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) (in a `:def` function "a:" is not
used).
*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* *E1090*
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` or `:def`, 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.
*none-function_argument*
You can pass |v:none| to use the default expression. Note that this means you
cannot pass v:none as an ordinary value when an argument has a default
expression.
Example: >
function Something(a = 10, b = 20, c = 30)
endfunction
call Something(1, v:none, 3) " b = 20
<
*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 "count".
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*
:[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.
In |Vim9| script using `:call` is optional, these two lines do
the same thing: >
call SomeFunc(arg)
SomeFunc(arg)
< 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.
*E117*
When a function cannot be found the error "E117: Unknown function" will be
given. If the function was using an autoload path or an autoload import and
the script is a |Vim9| script, this may also be caused by the function not
being exported.
*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('