vim: runtime/doc/userfunc.txt annotate

annotate runtime/doc/userfunc.txt @ 33299:4c975fa0a442 v9.0.1915

patch 9.0.1915: r_CTRL-C works differently in visual mode Commit: https://github.com/vim/vim/commit/476733f3d06876c7ac105e064108c973a57984d3 Author: Christian Brabandt <cb@256bit.org> Date: Tue Sep 19 20:41:51 2023 +0200 patch 9.0.1915: r_CTRL-C works differently in visual mode Problem: r_CTRL-C works differently in visual mode Solution: Make r_CTRL-C behave consistent in visual mode in terminal and Windows GUI in visual mode, r CTRL-C behaves strange in Unix like environments. It seems to end visual mode, but still is waiting for few more chars, however it never seems to replace it by any characters and eventually just returns back into normal mode. In contrast in Windows GUI mode, r_CTRL-C replaces in the selected area all characters by a literal CTRL-C. Not sure why it behaves like this. It seems in the Windows GUI, got_int is not set and therefore behaves as if any other normal character has been pressed. So remove the special casing of what happens when got_int is set and make it always behave like in Windows GUI mode. Add a test to verify it always behaves like replacing in the selected area each selected character by a literal CTRL-C. closes: #13091 closes: #13112 Signed-off-by: Christian Brabandt <cb@256bit.org>

author	Christian Brabandt <cb@256bit.org>
date	Tue, 19 Sep 2023 21:00:03 +0200
parents	695b50472e85
children	53416c49a7ab

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
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	446 Errors are reported but do not cause aborting execution of deferred functions.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	447
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	448 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	449 not with a dictionary. E1300
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	450
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 4. Automatically loading functions ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	454 autoload-functions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	455 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	456 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	457 the "autoload" directory in 'runtimepath'.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	458
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	459 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	460 \|import-autoload\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	461
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 Using an autocommand ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	464
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	465 This is introduced in the user manual, section \|51.4\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	466
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	467 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	468 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	469 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	470 again, setting a variable to skip the `:finish` command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	471
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	472 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	473 function(s) to be defined. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	474
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	475 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	476
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	477 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	478 "BufNet". Also see \|FuncUndefined\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	479
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 Using an autoload script ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	482 autoload E746
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	483 This is introduced in the user manual, section \|52.2\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	484
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	485 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	486 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	487 like this: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	488
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	489 :call filename#funcname()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	490
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	491 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	492 :call g:filename#funcname()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	493
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	494 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	495 "autoload" directories in 'runtimepath' for a script file called
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	496 "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	497 then define the function like this: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	498
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	499 function filename#funcname()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	500 echo "Done!"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	501 endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	502
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	503 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	504 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	505 not been added to 'runtimepath' yet (see \|packages\|).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	506
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	507 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	508 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	509 called. In Vim9 script the "g:" prefix must be used: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	510 function g:filename#funcname()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	511
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	512 or for a compiled function: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	513 def g:filename#funcname()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	514
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	515 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	516 a path separator. Thus when calling a function: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	517
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	518 :call foo#bar#func()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	519
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	520 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	521
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	522 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	523
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	524 :let l = foo#bar#lvar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	525
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	526 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	527 for an unknown variable.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	528
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	529 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	530 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	531
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	532 :let foo#bar#toggle = 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	533 :call foo#bar#func()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	534
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	535 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	536 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	537 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	538 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	539 Vim or manually source the script.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	540
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	541 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	542 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	543 Avoid using the autoload functionality at the toplevel.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	544
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	545 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	546 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	547 `:export`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	548
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	549 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	550 \|vimball\| utility. Also read the user manual \|distribute-script\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	551
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 vim:tw=78:ts=8:noet:ft=help:norl:

Mercurial > vim

annotate runtime/doc/userfunc.txt @ 33299:4c975fa0a442 v9.0.1915