Mercurial > vim

annotate runtime/doc/userfunc.txt @ 35298:3cefa0d2b54d default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added tag v9.1.0452 for changeset 5418b0e3a0c108bea0f914b5eed49778e1b694cf
author Christian Brabandt <cb@256bit.org>
date Thu, 30 May 2024 19:45:22 +0200
parents 4635e43f2c6f
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
34057
4635e43f2c6f patch 9.1.0000: Vim 9.1 release
Christian Brabandt <cb@256bit.org>
parents: 33636
diff changeset
1 *userfunc.txt* For Vim version 9.1. Last change: 2023 May 23
32670
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: