vim: runtime/doc/userfunc.txt annotate

annotate runtime/doc/userfunc.txt @ 33738:2172872dfbcd v9.0.2096

patch 9.0.2096: Vim9: confusing usage of private Commit: https://github.com/vim/vim/commit/03042a2753e3e6ac971045a8ce256d709214710e Author: Ernie Rael <errael@raelity.com> Date: Sat Nov 11 08:53:32 2023 +0100 patch 9.0.2096: Vim9: confusing usage of private Problem: Vim9: confusing usage of private Solution: clarify and use protected keyword instead [vim9class] document `_` as protected instead of private fixes #13504 closes: #13520 Signed-off-by: Ernie Rael <errael@raelity.com> Signed-off-by: Christian Brabandt <cb@256bit.org>

author	Christian Brabandt <cb@256bit.org>
date	Sat, 11 Nov 2023 09:00:06 +0100
parents	53416c49a7ab
children	4635e43f2c6f

rev	line source
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1 userfunc.txt For Vim version 9.0. Last change: 2023 May 23
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4 VIM REFERENCE MANUAL by Bram Moolenaar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	5
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	6
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	7 Defining and using functions.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	8
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	9 This is introduced in section \|41.7\| of the user manual.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	10
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	11 1. Defining a function \|define-function\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	12 2. Calling a function \|:call\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	13 3. Cleaning up in a function \|:defer\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	14 4. Automatically loading functions \|autoload-functions\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	15
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	16 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	17
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	18 1. Defining a function ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	19 define-function
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	20 New functions can be defined. These can be called just like builtin
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	21 functions. The function executes a sequence of Ex commands. Normal mode
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	22 commands can be executed with the \|:normal\| command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	23
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	24 The function name must start with an uppercase letter, to avoid confusion with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	25 builtin functions. To prevent from using the same name in different scripts
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	26 make them script-local. If you do use a global function then avoid obvious,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	27 short names. A good habit is to start the function name with the name of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	28 script, e.g., "HTMLcolor()".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	29
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	30 In legacy script it is also possible to use curly braces, see
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	31 \|curly-braces-names\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	32
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	33 The \|autoload\| facility is useful to define a function only when it's called.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	34
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	35 local-function
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	36 A function local to a legacy script must start with "s:". A local script
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	37 function can only be called from within the script and from functions, user
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	38 commands and autocommands defined in the script. It is also possible to call
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	39 the function from a mapping defined in the script, but then \|<SID>\| must be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	40 used instead of "s:" when the mapping is expanded outside of the script.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	41 There are only script-local functions, no buffer-local or window-local
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	42 functions.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	43
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	44 In \|Vim9\| script functions are local to the script by default, prefix "g:" to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	45 define a global function.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	46
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	47 :fu :function E128 E129 E123 E454
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	48 :fu[nction] List all functions and their arguments.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	49
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	50 :fu[nction] {name} List function {name}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	51 {name} can also be a \|Dictionary\| entry that is a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	52 \|Funcref\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	53 :function dict.init
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	54 < Note that {name} is not an expression, you cannot use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	55 a variable that is a function reference. You can use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	56 this dirty trick to list the function referred to with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	57 variable "Funcref": >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	58 let g:MyFuncref = Funcref
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	59 func g:MyFuncref
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	60 unlet g:MyFuncref
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	61
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	62 :fu[nction] /{pattern} List functions with a name matching {pattern}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	63 Example that lists all functions ending with "File": >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	64 :function /File$
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	65 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	66 :function-verbose
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	67 When 'verbose' is non-zero, listing a function will also display where it was
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	68 last defined. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	69
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	70 :verbose function SetFileTypeSH
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	71 function SetFileTypeSH(name)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	72 Last set from /usr/share/vim/vim-7.0/filetype.vim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	73 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	74 See \|:verbose-cmd\| for more information.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	75
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	76 E124 E125 E853 E884
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	77 :fu[nction][!] {name}([arguments]) [range] [abort] [dict] [closure]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	78 Define a new function by the name {name}. The body of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	79 the function follows in the next lines, until the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	80 matching \|:endfunction\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	81 E1267
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	82 The name must be made of alphanumeric characters and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	83 '_', and must start with a capital or "s:" (see
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	84 above). Note that using "b:" or "g:" is not allowed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	85 (since patch 7.4.260 E884 is given if the function
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	86 name has a colon in the name, e.g. for "foo:bar()".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	87 Before that patch no error was given).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	88
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	89 {name} can also be a \|Dictionary\| entry that is a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	90 \|Funcref\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	91 :function dict.init(arg)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	92 < "dict" must be an existing dictionary. The entry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	93 "init" is added if it didn't exist yet. Otherwise [!]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	94 is required to overwrite an existing function. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	95 result is a \|Funcref\| to a numbered function. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	96 function can only be used with a \|Funcref\| and will be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	97 deleted if there are no more references to it.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	98 E127 E122
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	99 When a function by this name already exists and [!] is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	100 not used an error message is given. There is one
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	101 exception: When sourcing a script again, a function
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	102 that was previously defined in that script will be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	103 silently replaced.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	104 When [!] is used, an existing function is silently
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	105 replaced. Unless it is currently being executed, that
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	106 is an error.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	107 NOTE: Use ! wisely. If used without care it can cause
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	108 an existing function to be replaced unexpectedly,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	109 which is hard to debug.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	110 NOTE: In Vim9 script script-local functions cannot be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	111 deleted or redefined.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	112
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	113 For the {arguments} see \|function-argument\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	114
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	115 :func-range a:firstline a:lastline
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	116 When the [range] argument is added, the function is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	117 expected to take care of a range itself. The range is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	118 passed as "a:firstline" and "a:lastline". If [range]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	119 is excluded, ":{range}call" will call the function for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	120 each line in the range, with the cursor on the start
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	121 of each line. See \|function-range-example\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	122 The cursor is still moved to the first line of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	123 range, as is the case with all Ex commands.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	124 :func-abort
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	125 When the [abort] argument is added, the function will
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	126 abort as soon as an error is detected.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	127 :func-dict
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	128 When the [dict] argument is added, the function must
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	129 be invoked through an entry in a \|Dictionary\|. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	130 local variable "self" will then be set to the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	131 dictionary. See \|Dictionary-function\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	132 :func-closure E932
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	133 When the [closure] argument is added, the function
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	134 can access variables and arguments from the outer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	135 scope. This is usually called a closure. In this
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	136 example Bar() uses "x" from the scope of Foo(). It
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	137 remains referenced even after Foo() returns: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	138 :function! Foo()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	139 : let x = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	140 : function! Bar() closure
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	141 : let x += 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	142 : return x
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	143 : endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	144 : return funcref('Bar')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	145 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	146
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	147 :let F = Foo()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	148 :echo F()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	149 < 1 >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	150 :echo F()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	151 < 2 >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	152 :echo F()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	153 < 3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	154
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	155 function-search-undo
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	156 The last used search pattern and the redo command "."
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	157 will not be changed by the function. This also
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	158 implies that the effect of \|:nohlsearch\| is undone
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	159 when the function returns.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	160
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	161 :endf :endfunction E126 E193 W22 E1151
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	162 :endf[unction] [argument]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	163 The end of a function definition. Best is to put it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	164 on a line by its own, without [argument].
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	165
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	166 [argument] can be:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	167 \| command command to execute next
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	168 \n command command to execute next
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	169 " comment always ignored
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	170 anything else ignored, warning given when
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	171 'verbose' is non-zero
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	172 The support for a following command was added in Vim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	173 8.0.0654, before that any argument was silently
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	174 ignored.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	175
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	176 To be able to define a function inside an `:execute`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	177 command, use line breaks instead of \|:bar\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	178 :exe "func Foo()\necho 'foo'\nendfunc"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	179 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	180 :delf :delfunction E131 E933 E1084
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	181 :delf[unction][!] {name}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	182 Delete function {name}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	183 {name} can also be a \|Dictionary\| entry that is a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	184 \|Funcref\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	185 :delfunc dict.init
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	186 < This will remove the "init" entry from "dict". The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	187 function is deleted if there are no more references to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	188 it.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	189 With the ! there is no error if the function does not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	190 exist.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	191 :retu :return E133
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	192 :retu[rn] [expr] Return from a function. When "[expr]" is given, it is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	193 evaluated and returned as the result of the function.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	194 If "[expr]" is not given, the number 0 is returned.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	195 When a function ends without an explicit ":return",
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	196 the number 0 is returned.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	197
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	198 In a :def function E1095 is given if unreachable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	199 code follows after the `:return`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	200 In legacy script there is no check for unreachable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	201 lines, thus there is no warning if commands follow
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	202 `:return`. Also, there is no check if the following
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	203 line contains a valid command. Forgetting the line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	204 continuation backslash may go unnoticed: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	205 return 'some text'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	206 .. ' some more text'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	207 < Will happily return "some text" without an error. It
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	208 should have been: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	209 return 'some text'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	210 \ .. ' some more text'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	211 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	212 If the ":return" is used after a \|:try\| but before the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	213 matching \|:finally\| (if present), the commands
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	214 following the ":finally" up to the matching \|:endtry\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	215 are executed first. This process applies to all
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	216 nested ":try"s inside the function. The function
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	217 returns at the outermost ":endtry".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	218
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	219 function-argument a:var
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	220 An argument can be defined by giving its name. In the function this can then
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	221 be used as "a:name" ("a:" for argument) (in a `:def` function "a:" is not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	222 used).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	223 a:0 a:1 a:000 E740 ...
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	224 Up to 20 arguments can be given, separated by commas. After the named
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	225 arguments an argument "..." can be specified, which means that more arguments
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	226 may optionally be following. In the function the extra arguments can be used
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	227 as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	228 can be 0). "a:000" is set to a \|List\| that contains these arguments. Note
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	229 that "a:1" is the same as "a:000[0]".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	230 E742 E1090
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	231 The a: scope and the variables in it cannot be changed, they are fixed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	232 However, if a composite type is used, such as \|List\| or \|Dictionary\| , you can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	233 change their contents. Thus you can pass a \|List\| to a function and have the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	234 function add an item to it. If you want to make sure the function cannot
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	235 change a \|List\| or \|Dictionary\| use \|:lockvar\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	236
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	237 It is also possible to define a function without any arguments. You must
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	238 still supply the () then.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	239
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	240 It is allowed to define another function inside a function body.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	241
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	242 optional-function-argument
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	243 You can provide default values for positional named arguments. This makes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	244 them optional for function calls. When a positional argument is not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	245 specified at a call, the default expression is used to initialize it.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	246 This only works for functions declared with `:function` or `:def`, not for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	247 lambda expressions \|expr-lambda\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	248
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	249 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	250 function Something(key, value = 10)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	251 echo a:key .. ": " .. a:value
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	252 endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	253 call Something('empty') "empty: 10"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	254 call Something('key', 20) "key: 20"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	255
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	256 The argument default expressions are evaluated at the time of the function
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	257 call, not when the function is defined. Thus it is possible to use an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	258 expression which is invalid the moment the function is defined. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	259 expressions are also only evaluated when arguments are not specified during a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	260 call.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	261 none-function_argument
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	262 You can pass \|v:none\| to use the default expression. Note that this means you
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	263 cannot pass v:none as an ordinary value when an argument has a default
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	264 expression.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	265
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	266 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	267 function Something(a = 10, b = 20, c = 30)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	268 endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	269 call Something(1, v:none, 3) " b = 20
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	270 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	271 E989
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	272 Optional arguments with default expressions must occur after any mandatory
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	273 arguments. You can use "..." after all optional named arguments.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	274
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	275 It is possible for later argument defaults to refer to prior arguments,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	276 but not the other way around. They must be prefixed with "a:", as with all
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	277 arguments.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	278
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	279 Example that works: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	280 :function Okay(mandatory, optional = a:mandatory)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	281 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	282 Example that does NOT work: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	283 :function NoGood(first = a:second, second = 10)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	284 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	285 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	286 When not using "...", the number of arguments in a function call must be at
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	287 least equal to the number of mandatory named arguments. When using "...", the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	288 number of arguments may be larger than the total of mandatory and optional
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	289 arguments.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	290
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	291 local-variables
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	292 Inside a function local variables can be used. These will disappear when the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	293 function returns. Global variables need to be accessed with "g:".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	294 Inside functions local variables are accessed without prepending anything.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	295 But you can also prepend "l:" if you like. This is required for some reserved
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	296 names, such as "count".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	297
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	298 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	299 :function Table(title, ...)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	300 : echohl Title
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	301 : echo a:title
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	302 : echohl None
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	303 : echo a:0 .. " items:"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	304 : for s in a:000
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	305 : echon ' ' .. s
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	306 : endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	307 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	308
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	309 This function can then be called with: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	310 call Table("Table", "line1", "line2")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	311 call Table("Empty Table")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	312
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	313 To return more than one value, return a \|List\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	314 :function Compute(n1, n2)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	315 : if a:n2 == 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	316 : return ["fail", 0]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	317 : endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	318 : return ["ok", a:n1 / a:n2]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	319 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	320
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	321 This function can then be called with: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	322 :let [success, div] = Compute(102, 6)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	323 :if success == "ok"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	324 : echo div
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	325 :endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	326 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	327 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	328
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	329 2. Calling a function ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	330 :cal :call E107
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	331 :[range]cal[l] {name}([arguments])
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	332 Call a function. The name of the function and its arguments
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	333 are as specified with `:function`. Up to 20 arguments can be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	334 used. The returned value is discarded.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	335 In \|Vim9\| script using `:call` is optional, these two lines do
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	336 the same thing: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	337 call SomeFunc(arg)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	338 SomeFunc(arg)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	339 < Without a range and for functions that accept a range, the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	340 function is called once. When a range is given the cursor is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	341 positioned at the start of the first line before executing the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	342 function.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	343 When a range is given and the function doesn't handle it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	344 itself, the function is executed for each line in the range,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	345 with the cursor in the first column of that line. The cursor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	346 is left at the last line (possibly moved by the last function
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	347 call). The arguments are re-evaluated for each line. Thus
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	348 this works:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	349 function-range-example >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	350 :function Mynumber(arg)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	351 : echo line(".") .. " " .. a:arg
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	352 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	353 :1,5call Mynumber(getline("."))
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	354 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	355 The "a:firstline" and "a:lastline" are defined anyway, they
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	356 can be used to do something different at the start or end of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	357 the range.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	358
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	359 Example of a function that handles the range itself: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	360
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	361 :function Cont() range
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	362 : execute (a:firstline + 1) .. "," .. a:lastline .. 's/^/\t\\ '
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	363 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	364 :4,8call Cont()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	365 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	366 This function inserts the continuation character "\" in front
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	367 of all the lines in the range, except the first one.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	368
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	369 When the function returns a composite value it can be further
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	370 dereferenced, but the range will not be used then. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	371 :4,8call GetDict().method()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	372 < Here GetDict() gets the range but method() does not.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	373
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	374 E117
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	375 When a function cannot be found the error "E117: Unknown function" will be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	376 given. If the function was using an autoload path or an autoload import and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	377 the script is a \|Vim9\| script, this may also be caused by the function not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	378 being exported.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	379
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	380 E132
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	381 The recursiveness of user functions is restricted with the \|'maxfuncdepth'\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	382 option.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	383
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	384 It is also possible to use `:eval`. It does not support a range, but does
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	385 allow for method chaining, e.g.: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	386 eval GetList()->Filter()->append('$')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	387
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	388 A function can also be called as part of evaluating an expression or when it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	389 is used as a method: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	390 let x = GetList()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	391 let y = GetList()->Filter()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	392
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	393 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	394
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	395 3. Cleaning up in a function ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	396 :defer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	397 :defer {func}({args}) Call {func} when the current function is done.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	398 {args} are evaluated here.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	399
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	400 Quite often a command in a function has a global effect, which must be undone
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	401 when the function finishes. Handling this in all kinds of situations can be a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	402 hassle. Especially when an unexpected error is encountered. This can be done
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	403 with `try` / `finally` blocks, but this gets complicated when there is more
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	404 than one.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	405
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	406 A much simpler solution is using `defer`. It schedules a function call when
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	407 the function is returning, no matter if there is an error. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	408 func Filter(text) abort
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	409 call writefile(a:text, 'Tempfile')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	410 call system('filter < Tempfile > Outfile')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	411 call Handle('Outfile')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	412 call delete('Tempfile')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	413 call delete('Outfile')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	414 endfunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	415
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	416 Here 'Tempfile' and 'Outfile' will not be deleted if something causes the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	417 function to abort. `:defer` can be used to avoid that: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	418 func Filter(text) abort
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	419 call writefile(a:text, 'Tempfile')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	420 defer delete('Tempfile')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	421 defer delete('Outfile')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	422 call system('filter < Tempfile > Outfile')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	423 call Handle('Outfile')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	424 endfunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	425
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	426 Note that deleting "Outfile" is scheduled before calling `system()`, since it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	427 can be created even when `system()` fails.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	428
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	429 The deferred functions are called in reverse order, the last one added is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	430 executed first. A useless example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	431 func Useless() abort
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	432 for s in range(3)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	433 defer execute('echomsg "number ' .. s .. '"')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	434 endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	435 endfunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	436
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	437 Now `:messages` shows:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	438 number 2
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	439 number 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	440 number 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	441
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	442 Any return value of the deferred function is discarded. The function cannot
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	443 be followed by anything, such as "->func" or ".member". Currently `:defer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	444 GetArg()->TheFunc()` does not work, it may work in a later version.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	445
33636 53416c49a7ab patch 9.0.2059: outstanding exceptions may be skipped Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	446 Errors are reported but do not cause aborting execution of deferred functions
53416c49a7ab patch 9.0.2059: outstanding exceptions may be skipped Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	447 or altering execution outside of deferred functions.
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	448
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	449 No range is accepted. The function can be a partial with extra arguments, but
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	450 not with a dictionary. E1300
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	451
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	452 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	453
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	454 4. Automatically loading functions ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	455 autoload-functions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	456 When using many or large functions, it's possible to automatically define them
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	457 only when they are used. There are two methods: with an autocommand and with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	458 the "autoload" directory in 'runtimepath'.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	459
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	460 In \|Vim9\| script there is also an autoload mechanism for imported scripts, see
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	461 \|import-autoload\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	462
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	463
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	464 Using an autocommand ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	465
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	466 This is introduced in the user manual, section \|51.4\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	467
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	468 The autocommand is useful if you have a plugin that is a long Vim script file.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	469 You can define the autocommand and quickly quit the script with `:finish`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	470 That makes Vim startup faster. The autocommand should then load the same file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	471 again, setting a variable to skip the `:finish` command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	472
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	473 Use the FuncUndefined autocommand event with a pattern that matches the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	474 function(s) to be defined. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	475
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	476 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	477
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	478 The file "~/vim/bufnetfuncs.vim" should then define functions that start with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	479 "BufNet". Also see \|FuncUndefined\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	480
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	481
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	482 Using an autoload script ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	483 autoload E746
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	484 This is introduced in the user manual, section \|52.2\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	485
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	486 Using a script in the "autoload" directory is simpler, but requires using
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	487 exactly the right file name. A function that can be autoloaded has a name
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	488 like this: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	489
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	490 :call filename#funcname()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	491
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	492 These functions are always global, in Vim9 script "g:" needs to be used: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	493 :call g:filename#funcname()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	494
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	495 When such a function is called, and it is not defined yet, Vim will search the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	496 "autoload" directories in 'runtimepath' for a script file called
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	497 "filename.vim". For example "~/.vim/autoload/filename.vim". That file should
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	498 then define the function like this: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	499
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	500 function filename#funcname()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	501 echo "Done!"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	502 endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	503
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	504 If the file doesn't exist, Vim will also search in 'packpath' (under "start")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	505 to allow calling packages' functions from your .vimrc when the packages have
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	506 not been added to 'runtimepath' yet (see \|packages\|).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	507
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	508 The file name and the name used before the # in the function must match
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	509 exactly, and the defined function must have the name exactly as it will be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	510 called. In Vim9 script the "g:" prefix must be used: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	511 function g:filename#funcname()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	512
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	513 or for a compiled function: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	514 def g:filename#funcname()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	515
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	516 It is possible to use subdirectories. Every # in the function name works like
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	517 a path separator. Thus when calling a function: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	518
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	519 :call foo#bar#func()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	520
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	521 Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	522
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	523 This also works when reading a variable that has not been set yet: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	524
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	525 :let l = foo#bar#lvar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	526
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	527 However, when the autoload script was already loaded it won't be loaded again
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	528 for an unknown variable.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	529
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	530 When assigning a value to such a variable nothing special happens. This can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	531 be used to pass settings to the autoload script before it's loaded: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	532
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	533 :let foo#bar#toggle = 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	534 :call foo#bar#func()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	535
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	536 Note that when you make a mistake and call a function that is supposed to be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	537 defined in an autoload script, but the script doesn't actually define the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	538 function, you will get an error message for the missing function. If you fix
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	539 the autoload script it won't be automatically loaded again. Either restart
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	540 Vim or manually source the script.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	541
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	542 Also note that if you have two script files, and one calls a function in the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	543 other and vice versa, before the used function is defined, it won't work.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	544 Avoid using the autoload functionality at the toplevel.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	545
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	546 In \|Vim9\| script you will get error E1263 if you define a function with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	547 a "#" character in the name. You should use a name without "#" and use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	548 `:export`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	549
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	550 Hint: If you distribute a bunch of scripts you can pack them together with the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	551 \|vimball\| utility. Also read the user manual \|distribute-script\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	552
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	553
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	554 vim:tw=78:ts=8:noet:ft=help:norl:

Mercurial > vim

annotate runtime/doc/userfunc.txt @ 33738:2172872dfbcd v9.0.2096