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)
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index d5ba286..a8109d9 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -10920,15 +10920,58 @@
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:".