Mercurial > vim
diff runtime/doc/eval.txt @ 16615:1a911bd57f11 v8.1.1310
patch 8.1.1310: named function arguments are never optional
commit https://github.com/vim/vim/commit/42ae78cfff171fbd7412306083fe200245d7a7a6
Author: Bram Moolenaar <Bram@vim.org>
Date: Thu May 9 21:08:58 2019 +0200
patch 8.1.1310: named function arguments are never optional
Problem: Named function arguments are never optional.
Solution: Support optional function arguments with a default value. (Andy
Massimino, closes #3952)
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Thu, 09 May 2019 21:15:05 +0200 |
parents | 1eaf34420bb3 |
children | 4790302965fc |
line wrap: on
line diff
--- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -10920,15 +10920,58 @@ change their contents. Thus you can pas 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 -may be larger. - 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 .. ": " .. 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 definition. Thus it is possible to use an expression which is +invalid the moment the function is defined. The expressions are are also only +evaluated when arguments are not specified during a call. + +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 equal +to the number of mandatory named arguments. When using "...", the number of +arguments may be larger. + *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:".