annotate runtime/doc/usr_41.txt @ 13280:fbda23eb0996 v8.0.1514

patch 8.0.1514: getting the list of changes is not easy commit https://github.com/vim/vim/commit/07ad816525da67cab3c0db21d1286d221dbc7477 Author: Bram Moolenaar <Bram@vim.org> Date: Tue Feb 13 13:59:59 2018 +0100 patch 8.0.1514: getting the list of changes is not easy Problem: Getting the list of changes is not easy. Solution: Add the getchangelist() function. (Yegappan Lakshmanan, closes #2634)
author Christian Brabandt <cb@256bit.org>
date Tue, 13 Feb 2018 14:15:05 +0100
parents dd3b2ecf91f6
children acd7eaa13d2b
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
13051
a6d3e2081544 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12909
diff changeset
1 *usr_41.txt* For Vim version 8.0. Last change: 2017 Dec 02
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
3 VIM USER MANUAL - by Bram Moolenaar
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
4
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
5 Write a Vim script
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
6
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
8 The Vim script language is used for the startup vimrc file, syntax files, and
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
9 many other things. This chapter explains the items that can be used in a Vim
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
10 script. There are a lot of them, thus this is a long chapter.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
11
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
12 |41.1| Introduction
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
13 |41.2| Variables
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
14 |41.3| Expressions
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
15 |41.4| Conditionals
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
16 |41.5| Executing an expression
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
17 |41.6| Using functions
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
18 |41.7| Defining a function
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
19 |41.8| Lists and Dictionaries
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
20 |41.9| Exceptions
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
21 |41.10| Various remarks
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
22 |41.11| Writing a plugin
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
23 |41.12| Writing a filetype plugin
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
24 |41.13| Writing a compiler plugin
170
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
25 |41.14| Writing a plugin that loads quickly
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
26 |41.15| Writing library scripts
793
8c0b00d50acf updated for version 7.0231
vimboss
parents: 681
diff changeset
27 |41.16| Distributing Vim scripts
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
28
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
29 Next chapter: |usr_42.txt| Add new menus
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
30 Previous chapter: |usr_40.txt| Make new commands
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
31 Table of contents: |usr_toc.txt|
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
32
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
33 ==============================================================================
129
2983cde45542 updated for version 7.0044
vimboss
parents: 112
diff changeset
34 *41.1* Introduction *vim-script-intro* *script*
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
35
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
36 Your first experience with Vim scripts is the vimrc file. Vim reads it when
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
37 it starts up and executes the commands. You can set options to values you
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
38 prefer. And you can use any colon command in it (commands that start with a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
39 ":"; these are sometimes referred to as Ex commands or command-line commands).
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
40 Syntax files are also Vim scripts. As are files that set options for a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
41 specific file type. A complicated macro can be defined by a separate Vim
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
42 script file. You can think of other uses yourself.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
43
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
44 Let's start with a simple example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
45
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
46 :let i = 1
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
47 :while i < 5
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
48 : echo "count is" i
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
49 : let i += 1
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
50 :endwhile
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
51 <
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
52 Note:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
53 The ":" characters are not really needed here. You only need to use
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
54 them when you type a command. In a Vim script file they can be left
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
55 out. We will use them here anyway to make clear these are colon
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
56 commands and make them stand out from Normal mode commands.
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
57 Note:
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
58 You can try out the examples by yanking the lines from the text here
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
59 and executing them with :@"
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
60
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
61 The output of the example code is:
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
62
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
63 count is 1 ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
64 count is 2 ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
65 count is 3 ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
66 count is 4 ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
67
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
68 In the first line the ":let" command assigns a value to a variable. The
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
69 generic form is: >
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
70
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
71 :let {variable} = {expression}
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
72
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
73 In this case the variable name is "i" and the expression is a simple value,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
74 the number one.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
75 The ":while" command starts a loop. The generic form is: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
76
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
77 :while {condition}
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
78 : {statements}
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
79 :endwhile
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
80
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
81 The statements until the matching ":endwhile" are executed for as long as the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
82 condition is true. The condition used here is the expression "i < 5". This
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
83 is true when the variable i is smaller than five.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
84 Note:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
85 If you happen to write a while loop that keeps on running, you can
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
86 interrupt it by pressing CTRL-C (CTRL-Break on MS-Windows).
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
87
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
88 The ":echo" command prints its arguments. In this case the string "count is"
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
89 and the value of the variable i. Since i is one, this will print:
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
90
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
91 count is 1 ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
92
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
93 Then there is the ":let i += 1" command. This does the same thing as
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
94 ":let i = i + 1". This adds one to the variable i and assigns the new value
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
95 to the same variable.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
96
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
97 The example was given to explain the commands, but would you really want to
11062
1218c5353e2b Runtime file updates.
Christian Brabandt <cb@256bit.org>
parents: 10734
diff changeset
98 make such a loop, it can be written much more compact: >
112
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
99
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
100 :for i in range(1, 4)
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
101 : echo "count is" i
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
102 :endfor
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
103
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
104 We won't explain how |:for| and |range()| work until later. Follow the links
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
105 if you are impatient.
112
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
106
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
107
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
108 THREE KINDS OF NUMBERS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
109
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
110 Numbers can be decimal, hexadecimal or octal. A hexadecimal number starts
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
111 with "0x" or "0X". For example "0x1f" is decimal 31. An octal number starts
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
112 with a zero. "017" is decimal 15. Careful: don't put a zero before a decimal
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
113 number, it will be interpreted as an octal number!
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
114 The ":echo" command always prints decimal numbers. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
115
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
116 :echo 0x7f 036
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
117 < 127 30 ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
118
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
119 A number is made negative with a minus sign. This also works for hexadecimal
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
120 and octal numbers. A minus sign is also used for subtraction. Compare this
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
121 with the previous example: >
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
122
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
123 :echo 0x7f -036
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
124 < 97 ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
125
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
126 White space in an expression is ignored. However, it's recommended to use it
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
127 for separating items, to make the expression easier to read. For example, to
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
128 avoid the confusion with a negative number above, put a space between the
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
129 minus sign and the following number: >
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
130
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
131 :echo 0x7f - 036
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
132
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
133 ==============================================================================
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
134 *41.2* Variables
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
135
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
136 A variable name consists of ASCII letters, digits and the underscore. It
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
137 cannot start with a digit. Valid variable names are:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
138
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
139 counter
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
140 _aap3
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
141 very_long_variable_name_with_underscores
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
142 FuncLength
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
143 LENGTH
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
144
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
145 Invalid names are "foo+bar" and "6var".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
146 These variables are global. To see a list of currently defined variables
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
147 use this command: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
148
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
149 :let
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
150
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
151 You can use global variables everywhere. This also means that when the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
152 variable "count" is used in one script file, it might also be used in another
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
153 file. This leads to confusion at least, and real problems at worst. To avoid
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
154 this, you can use a variable local to a script file by prepending "s:". For
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
155 example, one script contains this code: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
156
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
157 :let s:count = 1
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
158 :while s:count < 5
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
159 : source other.vim
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
160 : let s:count += 1
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
161 :endwhile
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
162
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
163 Since "s:count" is local to this script, you can be sure that sourcing the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
164 "other.vim" script will not change this variable. If "other.vim" also uses an
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
165 "s:count" variable, it will be a different copy, local to that script. More
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
166 about script-local variables here: |script-variable|.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
167
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
168 There are more kinds of variables, see |internal-variables|. The most often
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
169 used ones are:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
170
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
171 b:name variable local to a buffer
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
172 w:name variable local to a window
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
173 g:name global variable (also in a function)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
174 v:name variable predefined by Vim
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
175
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
176
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
177 DELETING VARIABLES
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
178
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
179 Variables take up memory and show up in the output of the ":let" command. To
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
180 delete a variable use the ":unlet" command. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
181
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
182 :unlet s:count
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
183
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
184 This deletes the script-local variable "s:count" to free up the memory it
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
185 uses. If you are not sure if the variable exists, and don't want an error
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
186 message when it doesn't, append !: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
187
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
188 :unlet! s:count
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
189
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
190 When a script finishes, the local variables used there will not be
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
191 automatically freed. The next time the script executes, it can still use the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
192 old value. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
193
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
194 :if !exists("s:call_count")
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
195 : let s:call_count = 0
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
196 :endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
197 :let s:call_count = s:call_count + 1
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
198 :echo "called" s:call_count "times"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
199
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
200 The "exists()" function checks if a variable has already been defined. Its
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
201 argument is the name of the variable you want to check. Not the variable
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
202 itself! If you would do this: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
203
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
204 :if !exists(s:call_count)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
205
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
206 Then the value of s:call_count will be used as the name of the variable that
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
207 exists() checks. That's not what you want.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
208 The exclamation mark ! negates a value. When the value was true, it
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
209 becomes false. When it was false, it becomes true. You can read it as "not".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
210 Thus "if !exists()" can be read as "if not exists()".
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
211 What Vim calls true is anything that is not zero. Zero is false.
856
8cd729851562 updated for version 7.0g
vimboss
parents: 842
diff changeset
212 Note:
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
213 Vim automatically converts a string to a number when it is looking for
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
214 a number. When using a string that doesn't start with a digit the
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
215 resulting number is zero. Thus look out for this: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
216 :if "true"
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
217 < The "true" will be interpreted as a zero, thus as false!
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
218
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
219
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
220 STRING VARIABLES AND CONSTANTS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
221
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
222 So far only numbers were used for the variable value. Strings can be used as
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
223 well. Numbers and strings are the basic types of variables that Vim supports.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
224 The type is dynamic, it is set each time when assigning a value to the
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
225 variable with ":let". More about types in |41.8|.
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
226 To assign a string value to a variable, you need to use a string constant.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
227 There are two types of these. First the string in double quotes: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
228
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
229 :let name = "peter"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
230 :echo name
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
231 < peter ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
232
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
233 If you want to include a double quote inside the string, put a backslash in
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
234 front of it: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
235
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
236 :let name = "\"peter\""
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
237 :echo name
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
238 < "peter" ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
239
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
240 To avoid the need for a backslash, you can use a string in single quotes: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
241
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
242 :let name = '"peter"'
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
243 :echo name
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
244 < "peter" ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
245
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
246 Inside a single-quote string all the characters are as they are. Only the
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
247 single quote itself is special: you need to use two to get one. A backslash
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
248 is taken literally, thus you can't use it to change the meaning of the
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
249 character after it.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
250 In double-quote strings it is possible to use special characters. Here are
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
251 a few useful ones:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
252
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
253 \t <Tab>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
254 \n <NL>, line break
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
255 \r <CR>, <Enter>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
256 \e <Esc>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
257 \b <BS>, backspace
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
258 \" "
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
259 \\ \, backslash
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
260 \<Esc> <Esc>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
261 \<C-W> CTRL-W
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
262
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
263 The last two are just examples. The "\<name>" form can be used to include
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
264 the special key "name".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
265 See |expr-quote| for the full list of special items in a string.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
266
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
267 ==============================================================================
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
268 *41.3* Expressions
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
269
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
270 Vim has a rich, yet simple way to handle expressions. You can read the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
271 definition here: |expression-syntax|. Here we will show the most common
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
272 items.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
273 The numbers, strings and variables mentioned above are expressions by
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
274 themselves. Thus everywhere an expression is expected, you can use a number,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
275 string or variable. Other basic items in an expression are:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
276
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
277 $NAME environment variable
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
278 &name option
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
279 @r register
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
280
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
281 Examples: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
282
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
283 :echo "The value of 'tabstop' is" &ts
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
284 :echo "Your home directory is" $HOME
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
285 :if @a > 5
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
286
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
287 The &name form can be used to save an option value, set it to a new value,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
288 do something and restore the old value. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
289
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
290 :let save_ic = &ic
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
291 :set noic
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
292 :/The Start/,$delete
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
293 :let &ic = save_ic
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
294
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
295 This makes sure the "The Start" pattern is used with the 'ignorecase' option
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
296 off. Still, it keeps the value that the user had set. (Another way to do
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
297 this would be to add "\C" to the pattern, see |/\C|.)
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
298
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
299
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
300 MATHEMATICS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
301
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
302 It becomes more interesting if we combine these basic items. Let's start with
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
303 mathematics on numbers:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
304
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
305 a + b add
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
306 a - b subtract
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
307 a * b multiply
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
308 a / b divide
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
309 a % b modulo
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
310
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
311 The usual precedence is used. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
312
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
313 :echo 10 + 5 * 2
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
314 < 20 ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
315
2709
b01a37ab556b Runtime file updates.
Bram Moolenaar <bram@vim.org>
parents: 2698
diff changeset
316 Grouping is done with parentheses. No surprises here. Example: >
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
317
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
318 :echo (10 + 5) * 2
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
319 < 30 ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
320
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
321 Strings can be concatenated with ".". Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
322
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
323 :echo "foo" . "bar"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
324 < foobar ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
325
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
326 When the ":echo" command gets multiple arguments, it separates them with a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
327 space. In the example the argument is a single expression, thus no space is
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
328 inserted.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
329
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
330 Borrowed from the C language is the conditional expression:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
331
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
332 a ? b : c
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
333
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
334 If "a" evaluates to true "b" is used, otherwise "c" is used. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
335
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
336 :let i = 4
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
337 :echo i > 5 ? "i is big" : "i is small"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
338 < i is small ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
339
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
340 The three parts of the constructs are always evaluated first, thus you could
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
341 see it work as:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
342
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
343 (a) ? (b) : (c)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
344
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
345 ==============================================================================
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
346 *41.4* Conditionals
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
347
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
348 The ":if" commands executes the following statements, until the matching
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
349 ":endif", only when a condition is met. The generic form is:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
350
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
351 :if {condition}
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
352 {statements}
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
353 :endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
354
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
355 Only when the expression {condition} evaluates to true (non-zero) will the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
356 {statements} be executed. These must still be valid commands. If they
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
357 contain garbage, Vim won't be able to find the ":endif".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
358 You can also use ":else". The generic form for this is:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
359
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
360 :if {condition}
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
361 {statements}
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
362 :else
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
363 {statements}
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
364 :endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
365
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
366 The second {statements} is only executed if the first one isn't.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
367 Finally, there is ":elseif":
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
368
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
369 :if {condition}
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
370 {statements}
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
371 :elseif {condition}
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
372 {statements}
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
373 :endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
374
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
375 This works just like using ":else" and then "if", but without the need for an
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
376 extra ":endif".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
377 A useful example for your vimrc file is checking the 'term' option and
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
378 doing something depending upon its value: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
379
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
380 :if &term == "xterm"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
381 : " Do stuff for xterm
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
382 :elseif &term == "vt100"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
383 : " Do stuff for a vt100 terminal
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
384 :else
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
385 : " Do something for other terminals
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
386 :endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
387
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
388
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
389 LOGIC OPERATIONS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
390
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
391 We already used some of them in the examples. These are the most often used
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
392 ones:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
393
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
394 a == b equal to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
395 a != b not equal to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
396 a > b greater than
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
397 a >= b greater than or equal to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
398 a < b less than
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
399 a <= b less than or equal to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
400
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
401 The result is one if the condition is met and zero otherwise. An example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
402
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
403 :if v:version >= 700
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
404 : echo "congratulations"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
405 :else
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
406 : echo "you are using an old version, upgrade!"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
407 :endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
408
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
409 Here "v:version" is a variable defined by Vim, which has the value of the Vim
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
410 version. 600 is for version 6.0. Version 6.1 has the value 601. This is
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
411 very useful to write a script that works with multiple versions of Vim.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
412 |v:version|
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
413
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
414 The logic operators work both for numbers and strings. When comparing two
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
415 strings, the mathematical difference is used. This compares byte values,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
416 which may not be right for some languages.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
417 When comparing a string with a number, the string is first converted to a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
418 number. This is a bit tricky, because when a string doesn't look like a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
419 number, the number zero is used. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
420
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
421 :if 0 == "one"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
422 : echo "yes"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
423 :endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
424
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
425 This will echo "yes", because "one" doesn't look like a number, thus it is
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
426 converted to the number zero.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
427
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
428 For strings there are two more items:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
429
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
430 a =~ b matches with
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
431 a !~ b does not match with
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
432
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
433 The left item "a" is used as a string. The right item "b" is used as a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
434 pattern, like what's used for searching. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
435
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
436 :if str =~ " "
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
437 : echo "str contains a space"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
438 :endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
439 :if str !~ '\.$'
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
440 : echo "str does not end in a full stop"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
441 :endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
442
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
443 Notice the use of a single-quote string for the pattern. This is useful,
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
444 because backslashes would need to be doubled in a double-quote string and
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
445 patterns tend to contain many backslashes.
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
446
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
447 The 'ignorecase' option is used when comparing strings. When you don't want
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
448 that, append "#" to match case and "?" to ignore case. Thus "==?" compares
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
449 two strings to be equal while ignoring case. And "!~#" checks if a pattern
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
450 doesn't match, also checking the case of letters. For the full table see
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
451 |expr-==|.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
452
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
453
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
454 MORE LOOPING
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
455
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
456 The ":while" command was already mentioned. Two more statements can be used
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
457 in between the ":while" and the ":endwhile":
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
458
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
459 :continue Jump back to the start of the while loop; the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
460 loop continues.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
461 :break Jump forward to the ":endwhile"; the loop is
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
462 discontinued.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
463
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
464 Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
465
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
466 :while counter < 40
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
467 : call do_something()
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
468 : if skip_flag
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
469 : continue
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
470 : endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
471 : if finished_flag
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
472 : break
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
473 : endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
474 : sleep 50m
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
475 :endwhile
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
476
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
477 The ":sleep" command makes Vim take a nap. The "50m" specifies fifty
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
478 milliseconds. Another example is ":sleep 4", which sleeps for four seconds.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
479
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
480 Even more looping can be done with the ":for" command, see below in |41.8|.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
481
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
482 ==============================================================================
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
483 *41.5* Executing an expression
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
484
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
485 So far the commands in the script were executed by Vim directly. The
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
486 ":execute" command allows executing the result of an expression. This is a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
487 very powerful way to build commands and execute them.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
488 An example is to jump to a tag, which is contained in a variable: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
489
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
490 :execute "tag " . tag_name
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
491
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
492 The "." is used to concatenate the string "tag " with the value of variable
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
493 "tag_name". Suppose "tag_name" has the value "get_cmd", then the command that
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
494 will be executed is: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
495
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
496 :tag get_cmd
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
497
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
498 The ":execute" command can only execute colon commands. The ":normal" command
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
499 executes Normal mode commands. However, its argument is not an expression but
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
500 the literal command characters. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
501
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
502 :normal gg=G
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
503
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
504 This jumps to the first line and formats all lines with the "=" operator.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
505 To make ":normal" work with an expression, combine ":execute" with it.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
506 Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
507
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
508 :execute "normal " . normal_commands
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
509
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
510 The variable "normal_commands" must contain the Normal mode commands.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
511 Make sure that the argument for ":normal" is a complete command. Otherwise
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
512 Vim will run into the end of the argument and abort the command. For example,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
513 if you start Insert mode, you must leave Insert mode as well. This works: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
514
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
515 :execute "normal Inew text \<Esc>"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
516
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
517 This inserts "new text " in the current line. Notice the use of the special
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
518 key "\<Esc>". This avoids having to enter a real <Esc> character in your
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
519 script.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
520
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
521 If you don't want to execute a string but evaluate it to get its expression
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
522 value, you can use the eval() function: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
523
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
524 :let optname = "path"
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
525 :let optval = eval('&' . optname)
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
526
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
527 A "&" character is prepended to "path", thus the argument to eval() is
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
528 "&path". The result will then be the value of the 'path' option.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
529 The same thing can be done with: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
530 :exe 'let optval = &' . optname
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
531
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
532 ==============================================================================
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
533 *41.6* Using functions
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
534
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
535 Vim defines many functions and provides a large amount of functionality that
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
536 way. A few examples will be given in this section. You can find the whole
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
537 list here: |functions|.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
538
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
539 A function is called with the ":call" command. The parameters are passed in
2709
b01a37ab556b Runtime file updates.
Bram Moolenaar <bram@vim.org>
parents: 2698
diff changeset
540 between parentheses separated by commas. Example: >
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
541
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
542 :call search("Date: ", "W")
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
543
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
544 This calls the search() function, with arguments "Date: " and "W". The
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
545 search() function uses its first argument as a search pattern and the second
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
546 one as flags. The "W" flag means the search doesn't wrap around the end of
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
547 the file.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
548
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
549 A function can be called in an expression. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
550
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
551 :let line = getline(".")
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
552 :let repl = substitute(line, '\a', "*", "g")
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
553 :call setline(".", repl)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
554
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
555 The getline() function obtains a line from the current buffer. Its argument
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
556 is a specification of the line number. In this case "." is used, which means
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
557 the line where the cursor is.
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
558 The substitute() function does something similar to the ":substitute"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
559 command. The first argument is the string on which to perform the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
560 substitution. The second argument is the pattern, the third the replacement
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
561 string. Finally, the last arguments are the flags.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
562 The setline() function sets the line, specified by the first argument, to a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
563 new string, the second argument. In this example the line under the cursor is
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
564 replaced with the result of the substitute(). Thus the effect of the three
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
565 statements is equal to: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
566
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
567 :substitute/\a/*/g
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
568
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
569 Using the functions becomes more interesting when you do more work before and
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
570 after the substitute() call.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
571
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
572
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
573 FUNCTIONS *function-list*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
574
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
575 There are many functions. We will mention them here, grouped by what they are
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
576 used for. You can find an alphabetical list here: |functions|. Use CTRL-] on
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
577 the function name to jump to detailed help on it.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
578
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
579 String manipulation: *string-functions*
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
580 nr2char() get a character by its ASCII value
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
581 char2nr() get ASCII value of a character
1620
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
582 str2nr() convert a string to a Number
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
583 str2float() convert a string to a Float
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
584 printf() format a string according to % items
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
585 escape() escape characters in a string with a '\'
1620
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
586 shellescape() escape a string for use with a shell command
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
587 fnameescape() escape a file name for use with a Vim command
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
588 tr() translate characters from one set to another
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
589 strtrans() translate a string to make it printable
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
590 tolower() turn a string to lowercase
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
591 toupper() turn a string to uppercase
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
592 match() position where a pattern matches in a string
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
593 matchend() position where a pattern match ends in a string
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
594 matchstr() match of a pattern in a string
9644
9f7bcc2c3b97 commit https://github.com/vim/vim/commit/6f1d9a096bf22d50c727dca73abbfb8e3ff55176
Christian Brabandt <cb@256bit.org>
parents: 9464
diff changeset
595 matchstrpos() match and positions of a pattern in a string
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
596 matchlist() like matchstr() and also return submatches
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
597 stridx() first index of a short string in a long string
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
598 strridx() last index of a short string in a long string
5618
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
599 strlen() length of a string in bytes
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
600 strchars() length of a string in characters
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
601 strwidth() size of string when displayed
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
602 strdisplaywidth() size of string when displayed, deals with tabs
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
603 substitute() substitute a pattern match with a string
2908
fd09a9c8468e Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2725
diff changeset
604 submatch() get a specific match in ":s" and substitute()
9286
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
605 strpart() get part of a string using byte index
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
606 strcharpart() get part of a string using char index
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
607 strgetchar() get character from a string using char index
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
608 expand() expand special keywords
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
609 iconv() convert text from one encoding to another
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
610 byteidx() byte index of a character in a string
5618
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
611 byteidxcomp() like byteidx() but count composing characters
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
612 repeat() repeat a string multiple times
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
613 eval() evaluate a string expression
9464
be72f4201a1d commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents: 9319
diff changeset
614 execute() execute an Ex command and get the output
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
615
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
616 List manipulation: *list-functions*
112
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
617 get() get an item without error for wrong index
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
618 len() number of items in a List
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
619 empty() check if List is empty
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
620 insert() insert an item somewhere in a List
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
621 add() append an item to a List
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
622 extend() append a List to a List
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
623 remove() remove one or more items from a List
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
624 copy() make a shallow copy of a List
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
625 deepcopy() make a full copy of a List
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
626 filter() remove selected items from a List
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
627 map() change each List item
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
628 sort() sort a List
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
629 reverse() reverse the order of a List
5763
c52a655d927d Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5618
diff changeset
630 uniq() remove copies of repeated adjacent items
112
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
631 split() split a String into a List
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
632 join() join List items into a String
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
633 range() return a List with a sequence of numbers
112
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
634 string() String representation of a List
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
635 call() call a function with List as arguments
323
03b3684919e3 updated for version 7.0084
vimboss
parents: 270
diff changeset
636 index() index of a value in a List
112
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
637 max() maximum value in a List
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
638 min() minimum value in a List
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
639 count() count number of times a value appears in a List
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
640 repeat() repeat a List multiple times
112
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
641
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
642 Dictionary manipulation: *dict-functions*
323
03b3684919e3 updated for version 7.0084
vimboss
parents: 270
diff changeset
643 get() get an entry without an error for a wrong key
112
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
644 len() number of entries in a Dictionary
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
645 has_key() check whether a key appears in a Dictionary
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
646 empty() check if Dictionary is empty
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
647 remove() remove an entry from a Dictionary
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
648 extend() add entries from one Dictionary to another
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
649 filter() remove selected entries from a Dictionary
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
650 map() change each Dictionary entry
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
651 keys() get List of Dictionary keys
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
652 values() get List of Dictionary values
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
653 items() get List of Dictionary key-value pairs
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
654 copy() make a shallow copy of a Dictionary
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
655 deepcopy() make a full copy of a Dictionary
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
656 string() String representation of a Dictionary
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
657 max() maximum value in a Dictionary
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
658 min() minimum value in a Dictionary
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
659 count() count number of times a value appears
195c94b60e54 updated for version 7.0041
vimboss
parents: 48
diff changeset
660
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
661 Floating point computation: *float-functions*
1620
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
662 float2nr() convert Float to Number
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
663 abs() absolute value (also works for Number)
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
664 round() round off
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
665 ceil() round up
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
666 floor() round down
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
667 trunc() remove value after decimal point
5618
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
668 fmod() remainder of division
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
669 exp() exponential
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
670 log() natural logarithm (logarithm to base e)
1620
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
671 log10() logarithm to base 10
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
672 pow() value of x to the exponent y
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
673 sqrt() square root
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
674 sin() sine
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
675 cos() cosine
2725
6f63330ec225 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2709
diff changeset
676 tan() tangent
6f63330ec225 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2709
diff changeset
677 asin() arc sine
6f63330ec225 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2709
diff changeset
678 acos() arc cosine
1620
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
679 atan() arc tangent
2725
6f63330ec225 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2709
diff changeset
680 atan2() arc tangent
6f63330ec225 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2709
diff changeset
681 sinh() hyperbolic sine
6f63330ec225 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2709
diff changeset
682 cosh() hyperbolic cosine
6f63330ec225 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2709
diff changeset
683 tanh() hyperbolic tangent
9286
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
684 isnan() check for not a number
1620
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
685
3237
91e53bcb7946 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2908
diff changeset
686 Other computation: *bitwise-function*
91e53bcb7946 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2908
diff changeset
687 and() bitwise AND
91e53bcb7946 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2908
diff changeset
688 invert() bitwise invert
91e53bcb7946 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2908
diff changeset
689 or() bitwise OR
91e53bcb7946 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2908
diff changeset
690 xor() bitwise XOR
5618
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
691 sha256() SHA-256 hash
3237
91e53bcb7946 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2908
diff changeset
692
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
693 Variables: *var-functions*
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
694 type() type of a variable
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
695 islocked() check if a variable is locked
11062
1218c5353e2b Runtime file updates.
Christian Brabandt <cb@256bit.org>
parents: 10734
diff changeset
696 funcref() get a Funcref for a function reference
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
697 function() get a Funcref for a function name
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
698 getbufvar() get a variable value from a specific buffer
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
699 setbufvar() set a variable in a specific buffer
831
f24a95dae8ee updated for version 7.0d05
vimboss
parents: 825
diff changeset
700 getwinvar() get a variable from specific window
2207
b17bbfa96fa0 Add the settabvar() and gettabvar() functions.
Bram Moolenaar <bram@vim.org>
parents: 2154
diff changeset
701 gettabvar() get a variable from specific tab page
831
f24a95dae8ee updated for version 7.0d05
vimboss
parents: 825
diff changeset
702 gettabwinvar() get a variable from specific window & tab page
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
703 setwinvar() set a variable in a specific window
2207
b17bbfa96fa0 Add the settabvar() and gettabvar() functions.
Bram Moolenaar <bram@vim.org>
parents: 2154
diff changeset
704 settabvar() set a variable in a specific tab page
831
f24a95dae8ee updated for version 7.0d05
vimboss
parents: 825
diff changeset
705 settabwinvar() set a variable in a specific window & tab page
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
706 garbagecollect() possibly free memory
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
707
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
708 Cursor and mark position: *cursor-functions* *mark-functions*
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
709 col() column number of the cursor or a mark
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
710 virtcol() screen column of the cursor or a mark
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
711 line() line number of the cursor or mark
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
712 wincol() window column number of the cursor
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
713 winline() window line number of the cursor
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
714 cursor() position the cursor at a line/column
5618
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
715 screencol() get screen column of the cursor
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
716 screenrow() get screen row of the cursor
5968
92751673cc37 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5942
diff changeset
717 getcurpos() get position of the cursor
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
718 getpos() get position of cursor, mark, etc.
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
719 setpos() set position of cursor, mark, etc.
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
720 byte2line() get line number at a specific byte count
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
721 line2byte() byte count at a specific line
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
722 diff_filler() get the number of filler lines above a line
5618
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
723 screenattr() get attribute at a screen line/row
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
724 screenchar() get character code at a screen line/row
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
725
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
726 Working with text in the current buffer: *text-functions*
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
727 getline() get a line or list of lines from the buffer
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
728 setline() replace a line in the buffer
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
729 append() append line or list of lines in the buffer
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
730 indent() indent of a specific line
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
731 cindent() indent according to C indenting
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
732 lispindent() indent according to Lisp indenting
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
733 nextnonblank() find next non-blank line
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
734 prevnonblank() find previous non-blank line
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
735 search() find a match for a pattern
667
9090f866cd57 updated for version 7.0197
vimboss
parents: 647
diff changeset
736 searchpos() find a match for a pattern
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
737 searchpair() find the other end of a start/skip/end
667
9090f866cd57 updated for version 7.0197
vimboss
parents: 647
diff changeset
738 searchpairpos() find the other end of a start/skip/end
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
739 searchdecl() search for the declaration of a name
9286
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
740 getcharsearch() return character search information
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
741 setcharsearch() set character search information
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
742
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
743 *system-functions* *file-functions*
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
744 System functions and manipulation of files:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
745 glob() expand wildcards
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
746 globpath() expand wildcards in a number of directories
9286
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
747 glob2regpat() convert a glob pattern into a search pattern
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
748 findfile() find a file in a list of directories
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
749 finddir() find a directory in a list of directories
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
750 resolve() find out where a shortcut points to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
751 fnamemodify() modify a file name
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
752 pathshorten() shorten directory names in a path
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
753 simplify() simplify a path without changing its meaning
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
754 executable() check if an executable program exists
5814
755931e042e4 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5763
diff changeset
755 exepath() full path of an executable program
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
756 filereadable() check if a file can be read
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
757 filewritable() check if a file can be written to
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
758 getfperm() get the permissions of a file
9286
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
759 setfperm() set the permissions of a file
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
760 getftype() get the kind of a file
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
761 isdirectory() check if a directory exists
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
762 getfsize() get the size of a file
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
763 getcwd() get the current working directory
1104
d75027183cf4 updated for version 7.0-230
vimboss
parents: 874
diff changeset
764 haslocaldir() check if current window used |:lcd|
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
765 tempname() get the name of a temporary file
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
766 mkdir() create a new directory
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
767 delete() delete a file
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
768 rename() rename a file
5814
755931e042e4 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5763
diff changeset
769 system() get the result of a shell command as a string
755931e042e4 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5763
diff changeset
770 systemlist() get the result of a shell command as a list
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
771 hostname() name of the system
158
78423945b251 updated for version 7.0048
vimboss
parents: 129
diff changeset
772 readfile() read a file into a List of lines
78423945b251 updated for version 7.0048
vimboss
parents: 129
diff changeset
773 writefile() write a List of lines into a file
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
774
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
775 Date and Time: *date-functions* *time-functions*
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
776 getftime() get last modification time of a file
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
777 localtime() get current time in seconds
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
778 strftime() convert time to a string
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
779 reltime() get the current or elapsed time accurately
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
780 reltimestr() convert reltime() result to a string
8876
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf
Christian Brabandt <cb@256bit.org>
parents: 8795
diff changeset
781 reltimefloat() convert reltime() result to a Float
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
782
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
783 *buffer-functions* *window-functions* *arg-functions*
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
784 Buffers, windows and the argument list:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
785 argc() number of entries in the argument list
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
786 argidx() current position in the argument list
5942
66eead134d68 updated for version 7.4.312
Bram Moolenaar <bram@vim.org>
parents: 5814
diff changeset
787 arglistid() get id of the argument list
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
788 argv() get one entry from the argument list
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
789 bufexists() check if a buffer exists
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
790 buflisted() check if a buffer exists and is listed
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
791 bufloaded() check if a buffer exists and is loaded
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
792 bufname() get the name of a specific buffer
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
793 bufnr() get the buffer number of a specific buffer
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
794 tabpagebuflist() return List of buffers in a tab page
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
795 tabpagenr() get the number of a tab page
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
796 tabpagewinnr() like winnr() for a specified tab page
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
797 winnr() get the window number for the current window
9227
ecb621205ed1 commit https://github.com/vim/vim/commit/82af8710bf8d1caeeceafb1370a052cb7d92f076
Christian Brabandt <cb@256bit.org>
parents: 8876
diff changeset
798 bufwinid() get the window ID of a specific buffer
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
799 bufwinnr() get the window number of a specific buffer
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
800 winbufnr() get the buffer number of a specific window
434
9595cf1d80a7 updated for version 7.0112
vimboss
parents: 323
diff changeset
801 getbufline() get a list of lines from the specified buffer
9286
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
802 win_findbuf() find windows containing a buffer
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
803 win_getid() get window ID of a window
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
804 win_gotoid() go to window with ID
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
805 win_id2tabwin() get tab and window nr from window ID
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
806 win_id2win() get window nr from window ID
9858
3e96d9ed2ca1 commit https://github.com/vim/vim/commit/b5ae48e9ffd3b8eb6ca4057de11f1bddcde8ce6f
Christian Brabandt <cb@256bit.org>
parents: 9644
diff changeset
807 getbufinfo() get a list with buffer information
3e96d9ed2ca1 commit https://github.com/vim/vim/commit/b5ae48e9ffd3b8eb6ca4057de11f1bddcde8ce6f
Christian Brabandt <cb@256bit.org>
parents: 9644
diff changeset
808 gettabinfo() get a list with tab page information
3e96d9ed2ca1 commit https://github.com/vim/vim/commit/b5ae48e9ffd3b8eb6ca4057de11f1bddcde8ce6f
Christian Brabandt <cb@256bit.org>
parents: 9644
diff changeset
809 getwininfo() get a list with window information
13280
fbda23eb0996 patch 8.0.1514: getting the list of changes is not easy
Christian Brabandt <cb@256bit.org>
parents: 13246
diff changeset
810 getchangelist() get a list of change list entries
13246
dd3b2ecf91f6 patch 8.0.1497: getting the jump list requires parsing the output of :jumps
Christian Brabandt <cb@256bit.org>
parents: 13051
diff changeset
811 getjumplist() get a list of jump list entries
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
812
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
813 Command line: *command-line-functions*
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
814 getcmdline() get the current command line
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
815 getcmdpos() get position of the cursor in the command line
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
816 setcmdpos() set position of the cursor in the command line
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
817 getcmdtype() return the current command-line type
6153
1e8ebf870720 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5979
diff changeset
818 getcmdwintype() return the current command-line window type
9644
9f7bcc2c3b97 commit https://github.com/vim/vim/commit/6f1d9a096bf22d50c727dca73abbfb8e3ff55176
Christian Brabandt <cb@256bit.org>
parents: 9464
diff changeset
819 getcompletion() list of command-line completion matches
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
820
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
821 Quickfix and location lists: *quickfix-functions*
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
822 getqflist() list of quickfix errors
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
823 setqflist() modify a quickfix list
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
824 getloclist() list of location list items
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
825 setloclist() modify a location list
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
826
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
827 Insert mode completion: *completion-functions*
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
828 complete() set found matches
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
829 complete_add() add to found matches
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
830 complete_check() check if completion should be aborted
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
831 pumvisible() check if the popup menu is displayed
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
832
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
833 Folding: *folding-functions*
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
834 foldclosed() check for a closed fold at a specific line
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
835 foldclosedend() like foldclosed() but return the last line
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
836 foldlevel() check for the fold level at a specific line
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
837 foldtext() generate the line displayed for a closed fold
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
838 foldtextresult() get the text displayed for a closed fold
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
839
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
840 Syntax and highlighting: *syntax-functions* *highlighting-functions*
1326
22886f3d882d updated for version 7.1-040
vimboss
parents: 1252
diff changeset
841 clearmatches() clear all matches defined by |matchadd()| and
22886f3d882d updated for version 7.1-040
vimboss
parents: 1252
diff changeset
842 the |:match| commands
22886f3d882d updated for version 7.1-040
vimboss
parents: 1252
diff changeset
843 getmatches() get all matches defined by |matchadd()| and
22886f3d882d updated for version 7.1-040
vimboss
parents: 1252
diff changeset
844 the |:match| commands
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
845 hlexists() check if a highlight group exists
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
846 hlID() get ID of a highlight group
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
847 synID() get syntax ID at a specific position
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
848 synIDattr() get a specific attribute of a syntax ID
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
849 synIDtrans() get translated syntax ID
2642
840c3cadb842 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
850 synstack() get list of syntax IDs at a specific position
2662
916c90b37ea9 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2642
diff changeset
851 synconcealed() get info about concealing
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
852 diff_hlID() get highlight ID for diff mode at a position
1326
22886f3d882d updated for version 7.1-040
vimboss
parents: 1252
diff changeset
853 matchadd() define a pattern to highlight (a "match")
5979
f9fa2e506b9f updated for version 7.4.330
Bram Moolenaar <bram@vim.org>
parents: 5968
diff changeset
854 matchaddpos() define a list of positions to highlight
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
855 matcharg() get info about |:match| arguments
1326
22886f3d882d updated for version 7.1-040
vimboss
parents: 1252
diff changeset
856 matchdelete() delete a match defined by |matchadd()| or a
22886f3d882d updated for version 7.1-040
vimboss
parents: 1252
diff changeset
857 |:match| command
22886f3d882d updated for version 7.1-040
vimboss
parents: 1252
diff changeset
858 setmatches() restore a list of matches saved by
22886f3d882d updated for version 7.1-040
vimboss
parents: 1252
diff changeset
859 |getmatches()|
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
860
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
861 Spelling: *spell-functions*
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
862 spellbadword() locate badly spelled word at or after cursor
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
863 spellsuggest() return suggested spelling corrections
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
864 soundfold() return the sound-a-like equivalent of a word
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
865
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
866 History: *history-functions*
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
867 histadd() add an item to a history
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
868 histdel() delete an item from a history
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
869 histget() get an item from a history
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
870 histnr() get highest index of a history list
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
871
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
872 Interactive: *interactive-functions*
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
873 browse() put up a file requester
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
874 browsedir() put up a directory requester
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
875 confirm() let the user make a choice
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
876 getchar() get a character from the user
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
877 getcharmod() get modifiers for the last typed character
1620
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
878 feedkeys() put characters in the typeahead queue
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
879 input() get a line from the user
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
880 inputlist() let the user pick an entry from a list
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
881 inputsecret() get a line from the user without showing it
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
882 inputdialog() get a line from the user in a dialog
230
9281a51ca7a2 updated for version 7.0064
vimboss
parents: 211
diff changeset
883 inputsave() save and clear typeahead
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
884 inputrestore() restore typeahead
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
885
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
886 GUI: *gui-functions*
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
887 getfontname() get name of current font being used
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
888 getwinposx() X position of the GUI Vim window
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
889 getwinposy() Y position of the GUI Vim window
11062
1218c5353e2b Runtime file updates.
Christian Brabandt <cb@256bit.org>
parents: 10734
diff changeset
890 balloon_show() set the balloon content
12909
1578c0ba0dd1 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 12756
diff changeset
891 balloon_split() split a message for a balloon
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
892
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
893 Vim server: *server-functions*
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
894 serverlist() return the list of server names
12756
3b26420fc639 Long overdue runtime update.
Christian Brabandt <cb@256bit.org>
parents: 12254
diff changeset
895 remote_startserver() run a server
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
896 remote_send() send command characters to a Vim server
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
897 remote_expr() evaluate an expression in a Vim server
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
898 server2client() send a reply to a client of a Vim server
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
899 remote_peek() check if there is a reply from a Vim server
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
900 remote_read() read a reply from a Vim server
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
901 foreground() move the Vim window to the foreground
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
902 remote_foreground() move the Vim server window to the foreground
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
903
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
904 Window size and position: *window-size-functions*
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
905 winheight() get height of a specific window
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
906 winwidth() get width of a specific window
13051
a6d3e2081544 Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 12909
diff changeset
907 win_screenpos() get screen position of a window
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
908 winrestcmd() return command to restore window sizes
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
909 winsaveview() get view of current window
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
910 winrestview() restore saved view of current window
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
911
4159
8b86b69546a9 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 3893
diff changeset
912 Mappings: *mapping-functions*
8b86b69546a9 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 3893
diff changeset
913 hasmapto() check if a mapping exists
8b86b69546a9 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 3893
diff changeset
914 mapcheck() check if a matching mapping exists
8b86b69546a9 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 3893
diff changeset
915 maparg() get rhs of a mapping
8b86b69546a9 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 3893
diff changeset
916 wildmenumode() check if the wildmode is active
8b86b69546a9 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 3893
diff changeset
917
7279
b5e9810b389d commit https://github.com/vim/vim/commit/683fa185a4b4ed7595e5942901548b8239ed5cdb
Christian Brabandt <cb@256bit.org>
parents: 6153
diff changeset
918 Testing: *test-functions*
8673
ed7251c3e2d3 commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
919 assert_equal() assert that two expressions values are equal
8876
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf
Christian Brabandt <cb@256bit.org>
parents: 8795
diff changeset
920 assert_notequal() assert that two expressions values are not equal
9644
9f7bcc2c3b97 commit https://github.com/vim/vim/commit/6f1d9a096bf22d50c727dca73abbfb8e3ff55176
Christian Brabandt <cb@256bit.org>
parents: 9464
diff changeset
921 assert_inrange() assert that an expression is inside a range
8795
aba2d0a01290 commit https://github.com/vim/vim/commit/7db8f6f4f85e5d0526d23107b2a5e2334dc23354
Christian Brabandt <cb@256bit.org>
parents: 8793
diff changeset
922 assert_match() assert that a pattern matches the value
8876
47f17f66da3d commit https://github.com/vim/vim/commit/03413f44167c4b5cd0012def9bb331e2518c83cf
Christian Brabandt <cb@256bit.org>
parents: 8795
diff changeset
923 assert_notmatch() assert that a pattern does not match the value
7279
b5e9810b389d commit https://github.com/vim/vim/commit/683fa185a4b4ed7595e5942901548b8239ed5cdb
Christian Brabandt <cb@256bit.org>
parents: 6153
diff changeset
924 assert_false() assert that an expression is false
b5e9810b389d commit https://github.com/vim/vim/commit/683fa185a4b4ed7595e5942901548b8239ed5cdb
Christian Brabandt <cb@256bit.org>
parents: 6153
diff changeset
925 assert_true() assert that an expression is true
8673
ed7251c3e2d3 commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
926 assert_exception() assert that a command throws an exception
ed7251c3e2d3 commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07
Christian Brabandt <cb@256bit.org>
parents: 8061
diff changeset
927 assert_fails() assert that a function call fails
11229
146a1e213b60 Update runtime files. Add Rust support.
Christian Brabandt <cb@256bit.org>
parents: 11160
diff changeset
928 assert_report() report a test failure
9286
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
929 test_alloc_fail() make memory allocation fail
9644
9f7bcc2c3b97 commit https://github.com/vim/vim/commit/6f1d9a096bf22d50c727dca73abbfb8e3ff55176
Christian Brabandt <cb@256bit.org>
parents: 9464
diff changeset
930 test_autochdir() enable 'autochdir' during startup
11160
d0a20101ecb2 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 11062
diff changeset
931 test_override() test with Vim internal overrides
d0a20101ecb2 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 11062
diff changeset
932 test_garbagecollect_now() free memory right now
11062
1218c5353e2b Runtime file updates.
Christian Brabandt <cb@256bit.org>
parents: 10734
diff changeset
933 test_ignore_error() ignore a specific error message
9286
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
934 test_null_channel() return a null Channel
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
935 test_null_dict() return a null Dict
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
936 test_null_job() return a null Job
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
937 test_null_list() return a null List
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
938 test_null_partial() return a null Partial function
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
939 test_null_string() return a null String
11062
1218c5353e2b Runtime file updates.
Christian Brabandt <cb@256bit.org>
parents: 10734
diff changeset
940 test_settime() set the time Vim uses internally
9286
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
941
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
942 Inter-process communication: *channel-functions*
10449
222b1432814e commit https://github.com/vim/vim/commit/5162822914372fc916a93f85848c0c82209e7cec
Christian Brabandt <cb@256bit.org>
parents: 10198
diff changeset
943 ch_canread() check if there is something to read
7924
00d64eb49ce1 commit https://github.com/vim/vim/commit/681baaf4a4c81418693dcafb81421a8614832e91
Christian Brabandt <cb@256bit.org>
parents: 7790
diff changeset
944 ch_open() open a channel
00d64eb49ce1 commit https://github.com/vim/vim/commit/681baaf4a4c81418693dcafb81421a8614832e91
Christian Brabandt <cb@256bit.org>
parents: 7790
diff changeset
945 ch_close() close a channel
10140
b11ceef7116e commit https://github.com/vim/vim/commit/64d8e25bf6efe5f18b032563521c3ce278c316ab
Christian Brabandt <cb@256bit.org>
parents: 9858
diff changeset
946 ch_close_in() close the in part of a channel
9286
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
947 ch_read() read a message from a channel
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
948 ch_readraw() read a raw message from a channel
7924
00d64eb49ce1 commit https://github.com/vim/vim/commit/681baaf4a4c81418693dcafb81421a8614832e91
Christian Brabandt <cb@256bit.org>
parents: 7790
diff changeset
949 ch_sendexpr() send a JSON message over a channel
00d64eb49ce1 commit https://github.com/vim/vim/commit/681baaf4a4c81418693dcafb81421a8614832e91
Christian Brabandt <cb@256bit.org>
parents: 7790
diff changeset
950 ch_sendraw() send a raw message over a channel
9286
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
951 ch_evalexpr() evaluates an expression over channel
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
952 ch_evalraw() evaluates a raw string over channel
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
953 ch_status() get status of a channel
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
954 ch_getbufnr() get the buffer number of a channel
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
955 ch_getjob() get the job associated with a channel
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
956 ch_info() get channel information
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
957 ch_log() write a message in the channel log file
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
958 ch_logfile() set the channel log file
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
959 ch_setoptions() set the options for a channel
9319
1472ed67c36f commit https://github.com/vim/vim/commit/a02a551e18209423584fcb923e93c6be18f3aa45
Christian Brabandt <cb@256bit.org>
parents: 9286
diff changeset
960 json_encode() encode an expression to a JSON string
1472ed67c36f commit https://github.com/vim/vim/commit/a02a551e18209423584fcb923e93c6be18f3aa45
Christian Brabandt <cb@256bit.org>
parents: 9286
diff changeset
961 json_decode() decode a JSON string to Vim types
9286
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
962 js_encode() encode an expression to a JSON string
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
963 js_decode() decode a JSON string to Vim types
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
964
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
965 Jobs: *job-functions*
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
966 job_start() start a job
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
967 job_stop() stop a job
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
968 job_status() get the status of a job
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
969 job_getchannel() get the channel used by a job
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
970 job_info() get information about a job
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
971 job_setoptions() set options for a job
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
972
12254
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
973 Terminal window: *terminal-functions*
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
974 term_start() open a terminal window and run a job
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
975 term_list() get the list of terminal buffers
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
976 term_sendkeys() send keystrokes to a terminal
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
977 term_wait() wait for screen to be updated
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
978 term_getjob() get the job associated with a terminal
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
979 term_scrape() get row of a terminal screen
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
980 term_getline() get a line of text from a terminal
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
981 term_getattr() get the value of attribute {what}
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
982 term_getcursor() get the cursor position of a terminal
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
983 term_getscrolled() get the scroll count of a terminal
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
984 term_getaltscreen() get the alternate screen flag
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
985 term_getsize() get the size of a terminal
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
986 term_getstatus() get the status of a terminal
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
987 term_gettitle() get the title of a terminal
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
988 term_gettty() get the tty name of a terminal
8d76a56861ec Update runtime files
Christian Brabandt <cb@256bit.org>
parents: 11763
diff changeset
989
9286
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
990 Timers: *timer-functions*
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
991 timer_start() create a timer
9858
3e96d9ed2ca1 commit https://github.com/vim/vim/commit/b5ae48e9ffd3b8eb6ca4057de11f1bddcde8ce6f
Christian Brabandt <cb@256bit.org>
parents: 9644
diff changeset
992 timer_pause() pause or unpause a timer
9286
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
993 timer_stop() stop a timer
9858
3e96d9ed2ca1 commit https://github.com/vim/vim/commit/b5ae48e9ffd3b8eb6ca4057de11f1bddcde8ce6f
Christian Brabandt <cb@256bit.org>
parents: 9644
diff changeset
994 timer_stopall() stop all timers
3e96d9ed2ca1 commit https://github.com/vim/vim/commit/b5ae48e9ffd3b8eb6ca4057de11f1bddcde8ce6f
Christian Brabandt <cb@256bit.org>
parents: 9644
diff changeset
995 timer_info() get information about timers
7790
ca19726d5e83 commit https://github.com/vim/vim/commit/298b440930ecece38d6ea0505a3e582dc817e79b
Christian Brabandt <cb@256bit.org>
parents: 7651
diff changeset
996
2301
6f63294a1781 Avoid use of the GTK mail_loop() so that the GtkFileChooser can be used.
Bram Moolenaar <bram@vim.org>
parents: 2207
diff changeset
997 Various: *various-functions*
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
998 mode() get current editing mode
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
999 visualmode() last visual mode used
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1000 exists() check if a variable, function, etc. exists
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1001 has() check if a feature is supported in Vim
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
1002 changenr() return number of most recent change
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1003 cscope_connection() check if a cscope connection exists
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1004 did_filetype() check if a FileType autocommand was used
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1005 eventhandler() check if invoked by an event handler
1620
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
1006 getpid() get process ID of Vim
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
1007
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1008 libcall() call a function in an external library
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1009 libcallnr() idem, returning a number
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
1010
5618
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
1011 undofile() get the name of the undo file
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
1012 undotree() return the state of the undo tree
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
1013
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1014 getreg() get contents of a register
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1015 getregtype() get type of a register
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1016 setreg() set contents and type of a register
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
1017
5618
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
1018 shiftwidth() effective value of 'shiftwidth'
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
1019
9464
be72f4201a1d commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents: 9319
diff changeset
1020 wordcount() get byte/word/char count of buffer
be72f4201a1d commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents: 9319
diff changeset
1021
211
79c3648993c3 updated for version 7.0060
vimboss
parents: 170
diff changeset
1022 taglist() get list of matching tags
824
8dd456c1e283 updated for version 7.0c13
vimboss
parents: 810
diff changeset
1023 tagfiles() get a list of tags files
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1024
5618
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
1025 luaeval() evaluate Lua expression
2050
afcf9db31561 updated for version 7.2.336
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
1026 mzeval() evaluate |MzScheme| expression
7651
c7575b07de98 commit https://github.com/vim/vim/commit/e9b892ebcd8596bf813793a1eed5a460a9495a28
Christian Brabandt <cb@256bit.org>
parents: 7480
diff changeset
1027 perleval() evaluate Perl expression (|+perl|)
5618
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
1028 py3eval() evaluate Python expression (|+python3|)
350272cbf1fd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 5294
diff changeset
1029 pyeval() evaluate Python expression (|+python|)
10734
523cd59d6db0 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 10449
diff changeset
1030 pyxeval() evaluate |python_x| expression
2050
afcf9db31561 updated for version 7.2.336
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
1031
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1032 ==============================================================================
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1033 *41.7* Defining a function
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1034
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1035 Vim enables you to define your own functions. The basic function declaration
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1036 begins as follows: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1037
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1038 :function {name}({var1}, {var2}, ...)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1039 : {body}
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1040 :endfunction
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1041 <
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1042 Note:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1043 Function names must begin with a capital letter.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1044
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1045 Let's define a short function to return the smaller of two numbers. It starts
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1046 with this line: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1047
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1048 :function Min(num1, num2)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1049
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1050 This tells Vim that the function is named "Min" and it takes two arguments:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1051 "num1" and "num2".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1052 The first thing you need to do is to check to see which number is smaller:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1053 >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1054 : if a:num1 < a:num2
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1055
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1056 The special prefix "a:" tells Vim that the variable is a function argument.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1057 Let's assign the variable "smaller" the value of the smallest number: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1058
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1059 : if a:num1 < a:num2
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1060 : let smaller = a:num1
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1061 : else
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1062 : let smaller = a:num2
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1063 : endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1064
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1065 The variable "smaller" is a local variable. Variables used inside a function
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1066 are local unless prefixed by something like "g:", "a:", or "s:".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1067
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1068 Note:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1069 To access a global variable from inside a function you must prepend
1620
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
1070 "g:" to it. Thus "g:today" inside a function is used for the global
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
1071 variable "today", and "today" is another variable, local to the
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1072 function.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1073
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1074 You now use the ":return" statement to return the smallest number to the user.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1075 Finally, you end the function: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1076
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1077 : return smaller
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1078 :endfunction
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1079
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1080 The complete function definition is as follows: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1081
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1082 :function Min(num1, num2)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1083 : if a:num1 < a:num2
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1084 : let smaller = a:num1
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1085 : else
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1086 : let smaller = a:num2
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1087 : endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1088 : return smaller
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1089 :endfunction
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1090
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1091 For people who like short functions, this does the same thing: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1092
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1093 :function Min(num1, num2)
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1094 : if a:num1 < a:num2
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1095 : return a:num1
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1096 : endif
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1097 : return a:num2
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1098 :endfunction
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1099
681
9364d114ed8d updated for version 7.0204
vimboss
parents: 667
diff changeset
1100 A user defined function is called in exactly the same way as a built-in
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1101 function. Only the name is different. The Min function can be used like
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1102 this: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1103
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1104 :echo Min(5, 8)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1105
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1106 Only now will the function be executed and the lines be interpreted by Vim.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1107 If there are mistakes, like using an undefined variable or function, you will
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1108 now get an error message. When defining the function these errors are not
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1109 detected.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1110
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1111 When a function reaches ":endfunction" or ":return" is used without an
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1112 argument, the function returns zero.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1113
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1114 To redefine a function that already exists, use the ! for the ":function"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1115 command: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1116
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1117 :function! Min(num1, num2, num3)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1118
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1119
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1120 USING A RANGE
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1121
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1122 The ":call" command can be given a line range. This can have one of two
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1123 meanings. When a function has been defined with the "range" keyword, it will
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1124 take care of the line range itself.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1125 The function will be passed the variables "a:firstline" and "a:lastline".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1126 These will have the line numbers from the range the function was called with.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1127 Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1128
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1129 :function Count_words() range
1620
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
1130 : let lnum = a:firstline
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
1131 : let n = 0
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
1132 : while lnum <= a:lastline
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
1133 : let n = n + len(split(getline(lnum)))
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
1134 : let lnum = lnum + 1
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1135 : endwhile
1620
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
1136 : echo "found " . n . " words"
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1137 :endfunction
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1138
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1139 You can call this function with: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1140
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1141 :10,30call Count_words()
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1142
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1143 It will be executed once and echo the number of words.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1144 The other way to use a line range is by defining a function without the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1145 "range" keyword. The function will be called once for every line in the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1146 range, with the cursor in that line. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1147
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1148 :function Number()
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1149 : echo "line " . line(".") . " contains: " . getline(".")
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1150 :endfunction
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1151
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1152 If you call this function with: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1153
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1154 :10,15call Number()
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1155
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1156 The function will be called six times.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1157
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1158
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1159 VARIABLE NUMBER OF ARGUMENTS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1160
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1161 Vim enables you to define functions that have a variable number of arguments.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1162 The following command, for instance, defines a function that must have 1
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1163 argument (start) and can have up to 20 additional arguments: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1164
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1165 :function Show(start, ...)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1166
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1167 The variable "a:1" contains the first optional argument, "a:2" the second, and
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1168 so on. The variable "a:0" contains the number of extra arguments.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1169 For example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1170
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1171 :function Show(start, ...)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1172 : echohl Title
2709
b01a37ab556b Runtime file updates.
Bram Moolenaar <bram@vim.org>
parents: 2698
diff changeset
1173 : echo "start is " . a:start
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1174 : echohl None
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1175 : let index = 1
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1176 : while index <= a:0
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1177 : echo " Arg " . index . " is " . a:{index}
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1178 : let index = index + 1
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1179 : endwhile
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1180 : echo ""
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1181 :endfunction
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1182
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1183 This uses the ":echohl" command to specify the highlighting used for the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1184 following ":echo" command. ":echohl None" stops it again. The ":echon"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1185 command works like ":echo", but doesn't output a line break.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1186
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1187 You can also use the a:000 variable, it is a List of all the "..." arguments.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1188 See |a:000|.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1189
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1190
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1191 LISTING FUNCTIONS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1192
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1193 The ":function" command lists the names and arguments of all user-defined
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1194 functions: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1195
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1196 :function
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1197 < function Show(start, ...) ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1198 function GetVimIndent() ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1199 function SetSyn(name) ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1200
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1201 To see what a function does, use its name as an argument for ":function": >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1202
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1203 :function SetSyn
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1204 < 1 if &syntax == '' ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1205 2 let &syntax = a:name ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1206 3 endif ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1207 endfunction ~
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1208
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1209
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1210 DEBUGGING
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1211
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1212 The line number is useful for when you get an error message or when debugging.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1213 See |debug-scripts| about debugging mode.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1214 You can also set the 'verbose' option to 12 or higher to see all function
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1215 calls. Set it to 15 or higher to see every executed line.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1216
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1217
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1218 DELETING A FUNCTION
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1219
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1220 To delete the Show() function: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1221
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1222 :delfunction Show
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1223
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1224 You get an error when the function doesn't exist.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1225
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1226
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1227 FUNCTION REFERENCES
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1228
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1229 Sometimes it can be useful to have a variable point to one function or
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1230 another. You can do it with the function() function. It turns the name of a
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1231 function into a reference: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1232
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1233 :let result = 0 " or 1
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1234 :function! Right()
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1235 : return 'Right!'
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1236 :endfunc
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1237 :function! Wrong()
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1238 : return 'Wrong!'
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1239 :endfunc
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1240 :
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1241 :if result == 1
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1242 : let Afunc = function('Right')
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1243 :else
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1244 : let Afunc = function('Wrong')
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1245 :endif
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1246 :echo call(Afunc, [])
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1247 < Wrong! ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1248
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1249 Note that the name of a variable that holds a function reference must start
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1250 with a capital. Otherwise it could be confused with the name of a builtin
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1251 function.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1252 The way to invoke a function that a variable refers to is with the call()
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1253 function. Its first argument is the function reference, the second argument
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1254 is a List with arguments.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1255
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1256 Function references are most useful in combination with a Dictionary, as is
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1257 explained in the next section.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1258
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1259 ==============================================================================
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1260 *41.8* Lists and Dictionaries
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1261
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1262 So far we have used the basic types String and Number. Vim also supports two
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1263 composite types: List and Dictionary.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1264
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1265 A List is an ordered sequence of things. The things can be any kind of value,
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1266 thus you can make a List of numbers, a List of Lists and even a List of mixed
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1267 items. To create a List with three strings: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1268
856
8cd729851562 updated for version 7.0g
vimboss
parents: 842
diff changeset
1269 :let alist = ['aap', 'mies', 'noot']
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1270
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1271 The List items are enclosed in square brackets and separated by commas. To
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1272 create an empty List: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1273
856
8cd729851562 updated for version 7.0g
vimboss
parents: 842
diff changeset
1274 :let alist = []
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1275
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1276 You can add items to a List with the add() function: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1277
856
8cd729851562 updated for version 7.0g
vimboss
parents: 842
diff changeset
1278 :let alist = []
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1279 :call add(alist, 'foo')
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1280 :call add(alist, 'bar')
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1281 :echo alist
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1282 < ['foo', 'bar'] ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1283
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1284 List concatenation is done with +: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1285
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1286 :echo alist + ['foo', 'bar']
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1287 < ['foo', 'bar', 'foo', 'bar'] ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1288
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1289 Or, if you want to extend a List directly: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1290
856
8cd729851562 updated for version 7.0g
vimboss
parents: 842
diff changeset
1291 :let alist = ['one']
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1292 :call extend(alist, ['two', 'three'])
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1293 :echo alist
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1294 < ['one', 'two', 'three'] ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1295
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1296 Notice that using add() will have a different effect: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1297
856
8cd729851562 updated for version 7.0g
vimboss
parents: 842
diff changeset
1298 :let alist = ['one']
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1299 :call add(alist, ['two', 'three'])
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1300 :echo alist
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1301 < ['one', ['two', 'three']] ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1302
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1303 The second argument of add() is added as a single item.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1304
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1305
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1306 FOR LOOP
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1307
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1308 One of the nice things you can do with a List is iterate over it: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1309
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1310 :let alist = ['one', 'two', 'three']
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1311 :for n in alist
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1312 : echo n
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1313 :endfor
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1314 < one ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1315 two ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1316 three ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1317
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1318 This will loop over each element in List "alist", assigning the value to
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1319 variable "n". The generic form of a for loop is: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1320
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1321 :for {varname} in {listexpression}
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1322 : {commands}
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1323 :endfor
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1324
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1325 To loop a certain number of times you need a List of a specific length. The
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1326 range() function creates one for you: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1327
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1328 :for a in range(3)
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1329 : echo a
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1330 :endfor
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1331 < 0 ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1332 1 ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1333 2 ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1334
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1335 Notice that the first item of the List that range() produces is zero, thus the
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1336 last item is one less than the length of the list.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1337 You can also specify the maximum value, the stride and even go backwards: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1338
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1339 :for a in range(8, 4, -2)
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1340 : echo a
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1341 :endfor
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1342 < 8 ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1343 6 ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1344 4 ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1345
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1346 A more useful example, looping over lines in the buffer: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1347
856
8cd729851562 updated for version 7.0g
vimboss
parents: 842
diff changeset
1348 :for line in getline(1, 20)
8cd729851562 updated for version 7.0g
vimboss
parents: 842
diff changeset
1349 : if line =~ "Date: "
8cd729851562 updated for version 7.0g
vimboss
parents: 842
diff changeset
1350 : echo matchstr(line, 'Date: \zs.*')
8cd729851562 updated for version 7.0g
vimboss
parents: 842
diff changeset
1351 : endif
8cd729851562 updated for version 7.0g
vimboss
parents: 842
diff changeset
1352 :endfor
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1353
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1354 This looks into lines 1 to 20 (inclusive) and echoes any date found in there.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1355
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1356
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1357 DICTIONARIES
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1358
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1359 A Dictionary stores key-value pairs. You can quickly lookup a value if you
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1360 know the key. A Dictionary is created with curly braces: >
856
8cd729851562 updated for version 7.0g
vimboss
parents: 842
diff changeset
1361
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1362 :let uk2nl = {'one': 'een', 'two': 'twee', 'three': 'drie'}
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1363
164
8b0ee9d57d7f updated for version 7.0050
vimboss
parents: 161
diff changeset
1364 Now you can lookup words by putting the key in square brackets: >
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1365
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1366 :echo uk2nl['two']
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1367 < twee ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1368
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1369 The generic form for defining a Dictionary is: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1370
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1371 {<key> : <value>, ...}
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1372
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1373 An empty Dictionary is one without any keys: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1374
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1375 {}
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1376
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1377 The possibilities with Dictionaries are numerous. There are various functions
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1378 for them as well. For example, you can obtain a list of the keys and loop
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1379 over them: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1380
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1381 :for key in keys(uk2nl)
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1382 : echo key
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1383 :endfor
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1384 < three ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1385 one ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1386 two ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1387
1620
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
1388 You will notice the keys are not ordered. You can sort the list to get a
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1389 specific order: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1390
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1391 :for key in sort(keys(uk2nl))
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1392 : echo key
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1393 :endfor
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1394 < one ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1395 three ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1396 two ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1397
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1398 But you can never get back the order in which items are defined. For that you
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1399 need to use a List, it stores items in an ordered sequence.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1400
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1401
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1402 DICTIONARY FUNCTIONS
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1403
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1404 The items in a Dictionary can normally be obtained with an index in square
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1405 brackets: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1406
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1407 :echo uk2nl['one']
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1408 < een ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1409
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1410 A method that does the same, but without so many punctuation characters: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1411
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1412 :echo uk2nl.one
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1413 < een ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1414
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1415 This only works for a key that is made of ASCII letters, digits and the
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1416 underscore. You can also assign a new value this way: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1417
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1418 :let uk2nl.four = 'vier'
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1419 :echo uk2nl
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1420 < {'three': 'drie', 'four': 'vier', 'one': 'een', 'two': 'twee'} ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1421
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1422 And now for something special: you can directly define a function and store a
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1423 reference to it in the dictionary: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1424
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1425 :function uk2nl.translate(line) dict
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1426 : return join(map(split(a:line), 'get(self, v:val, "???")'))
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1427 :endfunction
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1428
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1429 Let's first try it out: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1430
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1431 :echo uk2nl.translate('three two five one')
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1432 < drie twee ??? een ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1433
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1434 The first special thing you notice is the "dict" at the end of the ":function"
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1435 line. This marks the function as being used from a Dictionary. The "self"
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1436 local variable will then refer to that Dictionary.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1437 Now let's break up the complicated return command: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1438
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1439 split(a:line)
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1440
2709
b01a37ab556b Runtime file updates.
Bram Moolenaar <bram@vim.org>
parents: 2698
diff changeset
1441 The split() function takes a string, chops it into whitespace separated words
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1442 and returns a list with these words. Thus in the example it returns: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1443
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1444 :echo split('three two five one')
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1445 < ['three', 'two', 'five', 'one'] ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1446
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1447 This list is the first argument to the map() function. This will go through
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1448 the list, evaluating its second argument with "v:val" set to the value of each
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1449 item. This is a shortcut to using a for loop. This command: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1450
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1451 :let alist = map(split(a:line), 'get(self, v:val, "???")')
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1452
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1453 Is equivalent to: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1454
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1455 :let alist = split(a:line)
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1456 :for idx in range(len(alist))
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1457 : let alist[idx] = get(self, alist[idx], "???")
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1458 :endfor
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1459
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1460 The get() function checks if a key is present in a Dictionary. If it is, then
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1461 the value is retrieved. If it isn't, then the default value is returned, in
164
8b0ee9d57d7f updated for version 7.0050
vimboss
parents: 161
diff changeset
1462 the example it's '???'. This is a convenient way to handle situations where a
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1463 key may not be present and you don't want an error message.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1464
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1465 The join() function does the opposite of split(): it joins together a list of
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1466 words, putting a space in between.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1467 This combination of split(), map() and join() is a nice way to filter a line
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1468 of words in a very compact way.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1469
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1470
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1471 OBJECT ORIENTED PROGRAMMING
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1472
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1473 Now that you can put both values and functions in a Dictionary, you can
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1474 actually use a Dictionary like an object.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1475 Above we used a Dictionary for translating Dutch to English. We might want
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1476 to do the same for other languages. Let's first make an object (aka
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1477 Dictionary) that has the translate function, but no words to translate: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1478
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1479 :let transdict = {}
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1480 :function transdict.translate(line) dict
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1481 : return join(map(split(a:line), 'get(self.words, v:val, "???")'))
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1482 :endfunction
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1483
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1484 It's slightly different from the function above, using 'self.words' to lookup
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1485 word translations. But we don't have a self.words. Thus you could call this
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1486 an abstract class.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1487
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1488 Now we can instantiate a Dutch translation object: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1489
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1490 :let uk2nl = copy(transdict)
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1491 :let uk2nl.words = {'one': 'een', 'two': 'twee', 'three': 'drie'}
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1492 :echo uk2nl.translate('three one')
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1493 < drie een ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1494
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1495 And a German translator: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1496
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1497 :let uk2de = copy(transdict)
9286
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
1498 :let uk2de.words = {'one': 'eins', 'two': 'zwei', 'three': 'drei'}
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1499 :echo uk2de.translate('three one')
9286
64035abb986b commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents: 9227
diff changeset
1500 < drei eins ~
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1501
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1502 You see that the copy() function is used to make a copy of the "transdict"
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1503 Dictionary and then the copy is changed to add the words. The original
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1504 remains the same, of course.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1505
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1506 Now you can go one step further, and use your preferred translator: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1507
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1508 :if $LANG =~ "de"
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1509 : let trans = uk2de
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1510 :else
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1511 : let trans = uk2nl
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1512 :endif
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1513 :echo trans.translate('one two three')
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1514 < een twee drie ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1515
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1516 Here "trans" refers to one of the two objects (Dictionaries). No copy is
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1517 made. More about List and Dictionary identity can be found at |list-identity|
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1518 and |dict-identity|.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1519
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1520 Now you might use a language that isn't supported. You can overrule the
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1521 translate() function to do nothing: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1522
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1523 :let uk2uk = copy(transdict)
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1524 :function! uk2uk.translate(line)
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1525 : return a:line
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1526 :endfunction
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1527 :echo uk2uk.translate('three one wladiwostok')
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1528 < three one wladiwostok ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1529
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1530 Notice that a ! was used to overwrite the existing function reference. Now
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1531 use "uk2uk" when no recognized language is found: >
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1532
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1533 :if $LANG =~ "de"
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1534 : let trans = uk2de
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1535 :elseif $LANG =~ "nl"
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1536 : let trans = uk2nl
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1537 :else
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1538 : let trans = uk2uk
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1539 :endif
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1540 :echo trans.translate('one two three')
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1541 < one two three ~
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1542
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1543 For further reading see |Lists| and |Dictionaries|.
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1544
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1545 ==============================================================================
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1546 *41.9* Exceptions
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1547
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1548 Let's start with an example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1549
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1550 :try
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1551 : read ~/templates/pascal.tmpl
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1552 :catch /E484:/
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1553 : echo "Sorry, the Pascal template file cannot be found."
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1554 :endtry
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1555
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1556 The ":read" command will fail if the file does not exist. Instead of
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1557 generating an error message, this code catches the error and gives the user a
2709
b01a37ab556b Runtime file updates.
Bram Moolenaar <bram@vim.org>
parents: 2698
diff changeset
1558 nice message.
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1559
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1560 For the commands in between ":try" and ":endtry" errors are turned into
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1561 exceptions. An exception is a string. In the case of an error the string
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1562 contains the error message. And every error message has a number. In this
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1563 case, the error we catch contains "E484:". This number is guaranteed to stay
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1564 the same (the text may change, e.g., it may be translated).
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1565
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1566 When the ":read" command causes another error, the pattern "E484:" will not
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1567 match in it. Thus this exception will not be caught and result in the usual
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1568 error message.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1569
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1570 You might be tempted to do this: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1571
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1572 :try
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1573 : read ~/templates/pascal.tmpl
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1574 :catch
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1575 : echo "Sorry, the Pascal template file cannot be found."
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1576 :endtry
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1577
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1578 This means all errors are caught. But then you will not see errors that are
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1579 useful, such as "E21: Cannot make changes, 'modifiable' is off".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1580
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1581 Another useful mechanism is the ":finally" command: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1582
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1583 :let tmp = tempname()
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1584 :try
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1585 : exe ".,$write " . tmp
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1586 : exe "!filter " . tmp
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1587 : .,$delete
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1588 : exe "$read " . tmp
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1589 :finally
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1590 : call delete(tmp)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1591 :endtry
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1592
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1593 This filters the lines from the cursor until the end of the file through the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1594 "filter" command, which takes a file name argument. No matter if the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1595 filtering works, something goes wrong in between ":try" and ":finally" or the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1596 user cancels the filtering by pressing CTRL-C, the "call delete(tmp)" is
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1597 always executed. This makes sure you don't leave the temporary file behind.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1598
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1599 More information about exception handling can be found in the reference
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1600 manual: |exception-handling|.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1601
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1602 ==============================================================================
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1603 *41.10* Various remarks
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1604
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1605 Here is a summary of items that apply to Vim scripts. They are also mentioned
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1606 elsewhere, but form a nice checklist.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1607
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1608 The end-of-line character depends on the system. For Unix a single <NL>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1609 character is used. For MS-DOS, Windows, OS/2 and the like, <CR><LF> is used.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1610 This is important when using mappings that end in a <CR>. See |:source_crnl|.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1611
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1612
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1613 WHITE SPACE
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1614
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1615 Blank lines are allowed and ignored.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1616
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1617 Leading whitespace characters (blanks and TABs) are always ignored. The
11062
1218c5353e2b Runtime file updates.
Christian Brabandt <cb@256bit.org>
parents: 10734
diff changeset
1618 whitespaces between parameters (e.g. between the "set" and the "cpoptions" in
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1619 the example below) are reduced to one blank character and plays the role of a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1620 separator, the whitespaces after the last (visible) character may or may not
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1621 be ignored depending on the situation, see below.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1622
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1623 For a ":set" command involving the "=" (equal) sign, such as in: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1624
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1625 :set cpoptions =aABceFst
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1626
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1627 the whitespace immediately before the "=" sign is ignored. But there can be
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1628 no whitespace after the "=" sign!
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1629
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1630 To include a whitespace character in the value of an option, it must be
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1631 escaped by a "\" (backslash) as in the following example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1632
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1633 :set tags=my\ nice\ file
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1634
2709
b01a37ab556b Runtime file updates.
Bram Moolenaar <bram@vim.org>
parents: 2698
diff changeset
1635 The same example written as: >
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1636
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1637 :set tags=my nice file
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1638
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1639 will issue an error, because it is interpreted as: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1640
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1641 :set tags=my
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1642 :set nice
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1643 :set file
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1644
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1645
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1646 COMMENTS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1647
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1648 The character " (the double quote mark) starts a comment. Everything after
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1649 and including this character until the end-of-line is considered a comment and
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1650 is ignored, except for commands that don't consider comments, as shown in
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1651 examples below. A comment can start on any character position on the line.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1652
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1653 There is a little "catch" with comments for some commands. Examples: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1654
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1655 :abbrev dev development " shorthand
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1656 :map <F3> o#include " insert include
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1657 :execute cmd " do it
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1658 :!ls *.c " list C files
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1659
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1660 The abbreviation 'dev' will be expanded to 'development " shorthand'. The
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1661 mapping of <F3> will actually be the whole line after the 'o# ....' including
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1662 the '" insert include'. The "execute" command will give an error. The "!"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1663 command will send everything after it to the shell, causing an error for an
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1664 unmatched '"' character.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1665 There can be no comment after ":map", ":abbreviate", ":execute" and "!"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1666 commands (there are a few more commands with this restriction). For the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1667 ":map", ":abbreviate" and ":execute" commands there is a trick: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1668
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1669 :abbrev dev development|" shorthand
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1670 :map <F3> o#include|" insert include
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1671 :execute cmd |" do it
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1672
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1673 With the '|' character the command is separated from the next one. And that
1146
0e8da252bda1 updated for version 7.1a
vimboss
parents: 1104
diff changeset
1674 next command is only a comment. For the last command you need to do two
0e8da252bda1 updated for version 7.1a
vimboss
parents: 1104
diff changeset
1675 things: |:execute| and use '|': >
0e8da252bda1 updated for version 7.1a
vimboss
parents: 1104
diff changeset
1676 :exe '!ls *.c' |" list C files
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1677
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1678 Notice that there is no white space before the '|' in the abbreviation and
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1679 mapping. For these commands, any character until the end-of-line or '|' is
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1680 included. As a consequence of this behavior, you don't always see that
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1681 trailing whitespace is included: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1682
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1683 :map <F4> o#include
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1684
1146
0e8da252bda1 updated for version 7.1a
vimboss
parents: 1104
diff changeset
1685 To spot these problems, you can set the 'list' option when editing vimrc
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1686 files.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1687
1146
0e8da252bda1 updated for version 7.1a
vimboss
parents: 1104
diff changeset
1688 For Unix there is one special way to comment a line, that allows making a Vim
0e8da252bda1 updated for version 7.1a
vimboss
parents: 1104
diff changeset
1689 script executable: >
0e8da252bda1 updated for version 7.1a
vimboss
parents: 1104
diff changeset
1690 #!/usr/bin/env vim -S
0e8da252bda1 updated for version 7.1a
vimboss
parents: 1104
diff changeset
1691 echo "this is a Vim script"
0e8da252bda1 updated for version 7.1a
vimboss
parents: 1104
diff changeset
1692 quit
0e8da252bda1 updated for version 7.1a
vimboss
parents: 1104
diff changeset
1693
0e8da252bda1 updated for version 7.1a
vimboss
parents: 1104
diff changeset
1694 The "#" command by itself lists a line with the line number. Adding an
0e8da252bda1 updated for version 7.1a
vimboss
parents: 1104
diff changeset
1695 exclamation mark changes it into doing nothing, so that you can add the shell
0e8da252bda1 updated for version 7.1a
vimboss
parents: 1104
diff changeset
1696 command to execute the rest of the file. |:#!| |-S|
0e8da252bda1 updated for version 7.1a
vimboss
parents: 1104
diff changeset
1697
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1698
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1699 PITFALLS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1700
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1701 Even bigger problem arises in the following example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1702
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1703 :map ,ab o#include
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1704 :unmap ,ab
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1705
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1706 Here the unmap command will not work, because it tries to unmap ",ab ". This
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1707 does not exist as a mapped sequence. An error will be issued, which is very
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1708 hard to identify, because the ending whitespace character in ":unmap ,ab " is
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1709 not visible.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1710
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1711 And this is the same as what happens when one uses a comment after an 'unmap'
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1712 command: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1713
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1714 :unmap ,ab " comment
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1715
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1716 Here the comment part will be ignored. However, Vim will try to unmap
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1717 ',ab ', which does not exist. Rewrite it as: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1718
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1719 :unmap ,ab| " comment
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1720
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1721
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1722 RESTORING THE VIEW
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1723
3893
c3036f1dca68 Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 3830
diff changeset
1724 Sometimes you want to make a change and go back to where the cursor was.
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1725 Restoring the relative position would also be nice, so that the same line
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1726 appears at the top of the window.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1727 This example yanks the current line, puts it above the first line in the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1728 file and then restores the view: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1729
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1730 map ,p ma"aYHmbgg"aP`bzt`a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1731
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1732 What this does: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1733 ma"aYHmbgg"aP`bzt`a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1734 < ma set mark a at cursor position
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1735 "aY yank current line into register a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1736 Hmb go to top line in window and set mark b there
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1737 gg go to first line in file
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1738 "aP put the yanked line above it
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1739 `b go back to top line in display
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1740 zt position the text in the window as before
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1741 `a go back to saved cursor position
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1742
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1743
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1744 PACKAGING
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1745
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1746 To avoid your function names to interfere with functions that you get from
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1747 others, use this scheme:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1748 - Prepend a unique string before each function name. I often use an
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1749 abbreviation. For example, "OW_" is used for the option window functions.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1750 - Put the definition of your functions together in a file. Set a global
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1751 variable to indicate that the functions have been loaded. When sourcing the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1752 file again, first unload the functions.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1753 Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1754
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1755 " This is the XXX package
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1756
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1757 if exists("XXX_loaded")
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1758 delfun XXX_one
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1759 delfun XXX_two
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1760 endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1761
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1762 function XXX_one(a)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1763 ... body of function ...
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1764 endfun
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1765
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1766 function XXX_two(b)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1767 ... body of function ...
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1768 endfun
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1769
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1770 let XXX_loaded = 1
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1771
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1772 ==============================================================================
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
1773 *41.11* Writing a plugin *write-plugin*
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1774
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1775 You can write a Vim script in such a way that many people can use it. This is
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1776 called a plugin. Vim users can drop your script in their plugin directory and
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1777 use its features right away |add-plugin|.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1778
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1779 There are actually two types of plugins:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1780
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1781 global plugins: For all types of files.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1782 filetype plugins: Only for files of a specific type.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1783
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1784 In this section the first type is explained. Most items are also relevant for
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1785 writing filetype plugins. The specifics for filetype plugins are in the next
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1786 section |write-filetype-plugin|.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1787
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1788
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1789 NAME
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1790
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1791 First of all you must choose a name for your plugin. The features provided
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1792 by the plugin should be clear from its name. And it should be unlikely that
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1793 someone else writes a plugin with the same name but which does something
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1794 different. And please limit the name to 8 characters, to avoid problems on
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1795 old Windows systems.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1796
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1797 A script that corrects typing mistakes could be called "typecorr.vim". We
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1798 will use it here as an example.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1799
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1800 For the plugin to work for everybody, it should follow a few guidelines. This
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1801 will be explained step-by-step. The complete example plugin is at the end.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1802
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1803
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1804 BODY
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1805
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1806 Let's start with the body of the plugin, the lines that do the actual work: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1807
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1808 14 iabbrev teh the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1809 15 iabbrev otehr other
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1810 16 iabbrev wnat want
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1811 17 iabbrev synchronisation
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1812 18 \ synchronization
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1813 19 let s:count = 4
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1814
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1815 The actual list should be much longer, of course.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1816
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1817 The line numbers have only been added to explain a few things, don't put them
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1818 in your plugin file!
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1819
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1820
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1821 HEADER
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1822
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1823 You will probably add new corrections to the plugin and soon have several
3830
04592728474a Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 3445
diff changeset
1824 versions lying around. And when distributing this file, people will want to
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1825 know who wrote this wonderful plugin and where they can send remarks.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1826 Therefore, put a header at the top of your plugin: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1827
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1828 1 " Vim global plugin for correcting typing mistakes
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1829 2 " Last Change: 2000 Oct 15
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1830 3 " Maintainer: Bram Moolenaar <Bram@vim.org>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1831
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1832 About copyright and licensing: Since plugins are very useful and it's hardly
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1833 worth restricting their distribution, please consider making your plugin
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1834 either public domain or use the Vim |license|. A short note about this near
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1835 the top of the plugin should be sufficient. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1836
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1837 4 " License: This file is placed in the public domain.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1838
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1839
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1840 LINE CONTINUATION, AVOIDING SIDE EFFECTS *use-cpo-save*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1841
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1842 In line 18 above, the line-continuation mechanism is used |line-continuation|.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1843 Users with 'compatible' set will run into trouble here, they will get an error
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1844 message. We can't just reset 'compatible', because that has a lot of side
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1845 effects. To avoid this, we will set the 'cpoptions' option to its Vim default
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1846 value and restore it later. That will allow the use of line-continuation and
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1847 make the script work for most people. It is done like this: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1848
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1849 11 let s:save_cpo = &cpo
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1850 12 set cpo&vim
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1851 ..
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1852 42 let &cpo = s:save_cpo
3445
2cfb68fa26cd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 3237
diff changeset
1853 43 unlet s:save_cpo
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1854
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1855 We first store the old value of 'cpoptions' in the s:save_cpo variable. At
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1856 the end of the plugin this value is restored.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1857
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1858 Notice that a script-local variable is used |s:var|. A global variable could
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1859 already be in use for something else. Always use script-local variables for
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1860 things that are only used in the script.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1861
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1862
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1863 NOT LOADING
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1864
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1865 It's possible that a user doesn't always want to load this plugin. Or the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1866 system administrator has dropped it in the system-wide plugin directory, but a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1867 user has his own plugin he wants to use. Then the user must have a chance to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1868 disable loading this specific plugin. This will make it possible: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1869
2325
f177a6431514 Better implementation of creating the Color Scheme menu. (Juergen Kraemer)
Bram Moolenaar <bram@vim.org>
parents: 2301
diff changeset
1870 6 if exists("g:loaded_typecorr")
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1871 7 finish
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1872 8 endif
2325
f177a6431514 Better implementation of creating the Color Scheme menu. (Juergen Kraemer)
Bram Moolenaar <bram@vim.org>
parents: 2301
diff changeset
1873 9 let g:loaded_typecorr = 1
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1874
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1875 This also avoids that when the script is loaded twice it would cause error
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1876 messages for redefining functions and cause trouble for autocommands that are
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1877 added twice.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1878
2325
f177a6431514 Better implementation of creating the Color Scheme menu. (Juergen Kraemer)
Bram Moolenaar <bram@vim.org>
parents: 2301
diff changeset
1879 The name is recommended to start with "loaded_" and then the file name of the
f177a6431514 Better implementation of creating the Color Scheme menu. (Juergen Kraemer)
Bram Moolenaar <bram@vim.org>
parents: 2301
diff changeset
1880 plugin, literally. The "g:" is prepended just to avoid mistakes when using
f177a6431514 Better implementation of creating the Color Scheme menu. (Juergen Kraemer)
Bram Moolenaar <bram@vim.org>
parents: 2301
diff changeset
1881 the variable in a function (without "g:" it would be a variable local to the
f177a6431514 Better implementation of creating the Color Scheme menu. (Juergen Kraemer)
Bram Moolenaar <bram@vim.org>
parents: 2301
diff changeset
1882 function).
f177a6431514 Better implementation of creating the Color Scheme menu. (Juergen Kraemer)
Bram Moolenaar <bram@vim.org>
parents: 2301
diff changeset
1883
f177a6431514 Better implementation of creating the Color Scheme menu. (Juergen Kraemer)
Bram Moolenaar <bram@vim.org>
parents: 2301
diff changeset
1884 Using "finish" stops Vim from reading the rest of the file, it's much quicker
f177a6431514 Better implementation of creating the Color Scheme menu. (Juergen Kraemer)
Bram Moolenaar <bram@vim.org>
parents: 2301
diff changeset
1885 than using if-endif around the whole file.
f177a6431514 Better implementation of creating the Color Scheme menu. (Juergen Kraemer)
Bram Moolenaar <bram@vim.org>
parents: 2301
diff changeset
1886
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1887
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1888 MAPPING
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1889
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1890 Now let's make the plugin more interesting: We will add a mapping that adds a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1891 correction for the word under the cursor. We could just pick a key sequence
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1892 for this mapping, but the user might already use it for something else. To
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1893 allow the user to define which keys a mapping in a plugin uses, the <Leader>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1894 item can be used: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1895
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1896 22 map <unique> <Leader>a <Plug>TypecorrAdd
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1897
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1898 The "<Plug>TypecorrAdd" thing will do the work, more about that further on.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1899
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1900 The user can set the "mapleader" variable to the key sequence that he wants
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1901 this mapping to start with. Thus if the user has done: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1902
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1903 let mapleader = "_"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1904
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1905 the mapping will define "_a". If the user didn't do this, the default value
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1906 will be used, which is a backslash. Then a map for "\a" will be defined.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1907
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1908 Note that <unique> is used, this will cause an error message if the mapping
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1909 already happened to exist. |:map-<unique>|
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1910
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1911 But what if the user wants to define his own key sequence? We can allow that
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1912 with this mechanism: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1913
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1914 21 if !hasmapto('<Plug>TypecorrAdd')
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1915 22 map <unique> <Leader>a <Plug>TypecorrAdd
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1916 23 endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1917
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1918 This checks if a mapping to "<Plug>TypecorrAdd" already exists, and only
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1919 defines the mapping from "<Leader>a" if it doesn't. The user then has a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1920 chance of putting this in his vimrc file: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1921
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1922 map ,c <Plug>TypecorrAdd
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1923
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1924 Then the mapped key sequence will be ",c" instead of "_a" or "\a".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1925
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1926
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1927 PIECES
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1928
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1929 If a script gets longer, you often want to break up the work in pieces. You
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1930 can use functions or mappings for this. But you don't want these functions
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1931 and mappings to interfere with the ones from other scripts. For example, you
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1932 could define a function Add(), but another script could try to define the same
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1933 function. To avoid this, we define the function local to the script by
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1934 prepending it with "s:".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1935
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1936 We will define a function that adds a new typing correction: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1937
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1938 30 function s:Add(from, correct)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1939 31 let to = input("type the correction for " . a:from . ": ")
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1940 32 exe ":iabbrev " . a:from . " " . to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1941 ..
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1942 36 endfunction
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1943
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1944 Now we can call the function s:Add() from within this script. If another
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1945 script also defines s:Add(), it will be local to that script and can only
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1946 be called from the script it was defined in. There can also be a global Add()
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1947 function (without the "s:"), which is again another function.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1948
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1949 <SID> can be used with mappings. It generates a script ID, which identifies
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1950 the current script. In our typing correction plugin we use it like this: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1951
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1952 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1953 ..
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1954 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1955
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1956 Thus when a user types "\a", this sequence is invoked: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1957
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1958 \a -> <Plug>TypecorrAdd -> <SID>Add -> :call <SID>Add()
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1959
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1960 If another script would also map <SID>Add, it would get another script ID and
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1961 thus define another mapping.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1962
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1963 Note that instead of s:Add() we use <SID>Add() here. That is because the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1964 mapping is typed by the user, thus outside of the script. The <SID> is
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1965 translated to the script ID, so that Vim knows in which script to look for
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1966 the Add() function.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1967
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1968 This is a bit complicated, but it's required for the plugin to work together
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1969 with other plugins. The basic rule is that you use <SID>Add() in mappings and
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1970 s:Add() in other places (the script itself, autocommands, user commands).
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1971
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1972 We can also add a menu entry to do the same as the mapping: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1973
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1974 26 noremenu <script> Plugin.Add\ Correction <SID>Add
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1975
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1976 The "Plugin" menu is recommended for adding menu items for plugins. In this
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1977 case only one item is used. When adding more items, creating a submenu is
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1978 recommended. For example, "Plugin.CVS" could be used for a plugin that offers
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1979 CVS operations "Plugin.CVS.checkin", "Plugin.CVS.checkout", etc.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1980
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1981 Note that in line 28 ":noremap" is used to avoid that any other mappings cause
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1982 trouble. Someone may have remapped ":call", for example. In line 24 we also
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1983 use ":noremap", but we do want "<SID>Add" to be remapped. This is why
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1984 "<script>" is used here. This only allows mappings which are local to the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1985 script. |:map-<script>| The same is done in line 26 for ":noremenu".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1986 |:menu-<script>|
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1987
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1988
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1989 <SID> AND <Plug> *using-<Plug>*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1990
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1991 Both <SID> and <Plug> are used to avoid that mappings of typed keys interfere
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1992 with mappings that are only to be used from other mappings. Note the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1993 difference between using <SID> and <Plug>:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1994
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1995 <Plug> is visible outside of the script. It is used for mappings which the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1996 user might want to map a key sequence to. <Plug> is a special code
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1997 that a typed key will never produce.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1998 To make it very unlikely that other plugins use the same sequence of
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
1999 characters, use this structure: <Plug> scriptname mapname
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2000 In our example the scriptname is "Typecorr" and the mapname is "Add".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2001 This results in "<Plug>TypecorrAdd". Only the first character of
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2002 scriptname and mapname is uppercase, so that we can see where mapname
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2003 starts.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2004
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2005 <SID> is the script ID, a unique identifier for a script.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2006 Internally Vim translates <SID> to "<SNR>123_", where "123" can be any
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2007 number. Thus a function "<SID>Add()" will have a name "<SNR>11_Add()"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2008 in one script, and "<SNR>22_Add()" in another. You can see this if
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2009 you use the ":function" command to get a list of functions. The
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2010 translation of <SID> in mappings is exactly the same, that's how you
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2011 can call a script-local function from a mapping.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2012
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2013
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2014 USER COMMAND
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2015
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2016 Now let's add a user command to add a correction: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2017
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2018 38 if !exists(":Correct")
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2019 39 command -nargs=1 Correct :call s:Add(<q-args>, 0)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2020 40 endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2021
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2022 The user command is defined only if no command with the same name already
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2023 exists. Otherwise we would get an error here. Overriding the existing user
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2024 command with ":command!" is not a good idea, this would probably make the user
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2025 wonder why the command he defined himself doesn't work. |:command|
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2026
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2027
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2028 SCRIPT VARIABLES
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2029
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2030 When a variable starts with "s:" it is a script variable. It can only be used
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2031 inside a script. Outside the script it's not visible. This avoids trouble
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2032 with using the same variable name in different scripts. The variables will be
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2033 kept as long as Vim is running. And the same variables are used when sourcing
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2034 the same script again. |s:var|
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2035
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2036 The fun is that these variables can also be used in functions, autocommands
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2037 and user commands that are defined in the script. In our example we can add
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2038 a few lines to count the number of corrections: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2039
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2040 19 let s:count = 4
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2041 ..
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2042 30 function s:Add(from, correct)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2043 ..
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2044 34 let s:count = s:count + 1
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2045 35 echo s:count . " corrections now"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2046 36 endfunction
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2047
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2048 First s:count is initialized to 4 in the script itself. When later the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2049 s:Add() function is called, it increments s:count. It doesn't matter from
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2050 where the function was called, since it has been defined in the script, it
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2051 will use the local variables from this script.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2052
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2053
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2054 THE RESULT
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2055
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2056 Here is the resulting complete example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2057
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2058 1 " Vim global plugin for correcting typing mistakes
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2059 2 " Last Change: 2000 Oct 15
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2060 3 " Maintainer: Bram Moolenaar <Bram@vim.org>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2061 4 " License: This file is placed in the public domain.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2062 5
2325
f177a6431514 Better implementation of creating the Color Scheme menu. (Juergen Kraemer)
Bram Moolenaar <bram@vim.org>
parents: 2301
diff changeset
2063 6 if exists("g:loaded_typecorr")
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2064 7 finish
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2065 8 endif
2325
f177a6431514 Better implementation of creating the Color Scheme menu. (Juergen Kraemer)
Bram Moolenaar <bram@vim.org>
parents: 2301
diff changeset
2066 9 let g:loaded_typecorr = 1
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2067 10
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2068 11 let s:save_cpo = &cpo
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2069 12 set cpo&vim
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2070 13
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2071 14 iabbrev teh the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2072 15 iabbrev otehr other
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2073 16 iabbrev wnat want
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2074 17 iabbrev synchronisation
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2075 18 \ synchronization
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2076 19 let s:count = 4
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2077 20
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2078 21 if !hasmapto('<Plug>TypecorrAdd')
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2079 22 map <unique> <Leader>a <Plug>TypecorrAdd
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2080 23 endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2081 24 noremap <unique> <script> <Plug>TypecorrAdd <SID>Add
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2082 25
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2083 26 noremenu <script> Plugin.Add\ Correction <SID>Add
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2084 27
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2085 28 noremap <SID>Add :call <SID>Add(expand("<cword>"), 1)<CR>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2086 29
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2087 30 function s:Add(from, correct)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2088 31 let to = input("type the correction for " . a:from . ": ")
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2089 32 exe ":iabbrev " . a:from . " " . to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2090 33 if a:correct | exe "normal viws\<C-R>\" \b\e" | endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2091 34 let s:count = s:count + 1
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2092 35 echo s:count . " corrections now"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2093 36 endfunction
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2094 37
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2095 38 if !exists(":Correct")
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2096 39 command -nargs=1 Correct :call s:Add(<q-args>, 0)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2097 40 endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2098 41
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2099 42 let &cpo = s:save_cpo
3445
2cfb68fa26cd Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 3237
diff changeset
2100 43 unlet s:save_cpo
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2101
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2102 Line 33 wasn't explained yet. It applies the new correction to the word under
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2103 the cursor. The |:normal| command is used to use the new abbreviation. Note
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2104 that mappings and abbreviations are expanded here, even though the function
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2105 was called from a mapping defined with ":noremap".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2106
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2107 Using "unix" for the 'fileformat' option is recommended. The Vim scripts will
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2108 then work everywhere. Scripts with 'fileformat' set to "dos" do not work on
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2109 Unix. Also see |:source_crnl|. To be sure it is set right, do this before
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2110 writing the file: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2111
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2112 :set fileformat=unix
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2113
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2114
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2115 DOCUMENTATION *write-local-help*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2116
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2117 It's a good idea to also write some documentation for your plugin. Especially
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2118 when its behavior can be changed by the user. See |add-local-help| for how
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2119 they are installed.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2120
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2121 Here is a simple example for a plugin help file, called "typecorr.txt": >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2122
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2123 1 *typecorr.txt* Plugin for correcting typing mistakes
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2124 2
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2125 3 If you make typing mistakes, this plugin will have them corrected
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2126 4 automatically.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2127 5
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2128 6 There are currently only a few corrections. Add your own if you like.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2129 7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2130 8 Mappings:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2131 9 <Leader>a or <Plug>TypecorrAdd
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2132 10 Add a correction for the word under the cursor.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2133 11
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2134 12 Commands:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2135 13 :Correct {word}
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2136 14 Add a correction for {word}.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2137 15
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2138 16 *typecorr-settings*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2139 17 This plugin doesn't have any settings.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2140
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2141 The first line is actually the only one for which the format matters. It will
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2142 be extracted from the help file to be put in the "LOCAL ADDITIONS:" section of
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2143 help.txt |local-additions|. The first "*" must be in the first column of the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2144 first line. After adding your help file do ":help" and check that the entries
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2145 line up nicely.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2146
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2147 You can add more tags inside ** in your help file. But be careful not to use
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2148 existing help tags. You would probably use the name of your plugin in most of
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2149 them, like "typecorr-settings" in the example.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2150
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2151 Using references to other parts of the help in || is recommended. This makes
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2152 it easy for the user to find associated help.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2153
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2154
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2155 FILETYPE DETECTION *plugin-filetype*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2156
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2157 If your filetype is not already detected by Vim, you should create a filetype
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2158 detection snippet in a separate file. It is usually in the form of an
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2159 autocommand that sets the filetype when the file name matches a pattern.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2160 Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2161
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2162 au BufNewFile,BufRead *.foo set filetype=foofoo
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2163
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2164 Write this single-line file as "ftdetect/foofoo.vim" in the first directory
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2165 that appears in 'runtimepath'. For Unix that would be
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2166 "~/.vim/ftdetect/foofoo.vim". The convention is to use the name of the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2167 filetype for the script name.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2168
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2169 You can make more complicated checks if you like, for example to inspect the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2170 contents of the file to recognize the language. Also see |new-filetype|.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2171
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2172
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2173 SUMMARY *plugin-special*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2174
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2175 Summary of special things to use in a plugin:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2176
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2177 s:name Variables local to the script.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2178
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2179 <SID> Script-ID, used for mappings and functions local to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2180 the script.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2181
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2182 hasmapto() Function to test if the user already defined a mapping
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2183 for functionality the script offers.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2184
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2185 <Leader> Value of "mapleader", which the user defines as the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2186 keys that plugin mappings start with.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2187
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2188 :map <unique> Give a warning if a mapping already exists.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2189
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2190 :noremap <script> Use only mappings local to the script, not global
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2191 mappings.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2192
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2193 exists(":Cmd") Check if a user command already exists.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2194
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2195 ==============================================================================
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
2196 *41.12* Writing a filetype plugin *write-filetype-plugin* *ftplugin*
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2197
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2198 A filetype plugin is like a global plugin, except that it sets options and
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2199 defines mappings for the current buffer only. See |add-filetype-plugin| for
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2200 how this type of plugin is used.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2201
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
2202 First read the section on global plugins above |41.11|. All that is said there
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2203 also applies to filetype plugins. There are a few extras, which are explained
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2204 here. The essential thing is that a filetype plugin should only have an
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2205 effect on the current buffer.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2206
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2207
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2208 DISABLING
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2209
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2210 If you are writing a filetype plugin to be used by many people, they need a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2211 chance to disable loading it. Put this at the top of the plugin: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2212
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2213 " Only do this when not done yet for this buffer
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2214 if exists("b:did_ftplugin")
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2215 finish
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2216 endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2217 let b:did_ftplugin = 1
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2218
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2219 This also needs to be used to avoid that the same plugin is executed twice for
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2220 the same buffer (happens when using an ":edit" command without arguments).
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2221
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2222 Now users can disable loading the default plugin completely by making a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2223 filetype plugin with only this line: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2224
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2225 let b:did_ftplugin = 1
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2226
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2227 This does require that the filetype plugin directory comes before $VIMRUNTIME
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2228 in 'runtimepath'!
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2229
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2230 If you do want to use the default plugin, but overrule one of the settings,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2231 you can write the different setting in a script: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2232
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2233 setlocal textwidth=70
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2234
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2235 Now write this in the "after" directory, so that it gets sourced after the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2236 distributed "vim.vim" ftplugin |after-directory|. For Unix this would be
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2237 "~/.vim/after/ftplugin/vim.vim". Note that the default plugin will have set
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2238 "b:did_ftplugin", but it is ignored here.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2239
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2240
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2241 OPTIONS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2242
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2243 To make sure the filetype plugin only affects the current buffer use the >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2244
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2245 :setlocal
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2246
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2247 command to set options. And only set options which are local to a buffer (see
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2248 the help for the option to check that). When using |:setlocal| for global
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2249 options or options local to a window, the value will change for many buffers,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2250 and that is not what a filetype plugin should do.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2251
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2252 When an option has a value that is a list of flags or items, consider using
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2253 "+=" and "-=" to keep the existing value. Be aware that the user may have
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2254 changed an option value already. First resetting to the default value and
2698
b6471224d2af Updated runtime files and translations.
Bram Moolenaar <bram@vim.org>
parents: 2662
diff changeset
2255 then changing it is often a good idea. Example: >
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2256
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2257 :setlocal formatoptions& formatoptions+=ro
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2258
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2259
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2260 MAPPINGS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2261
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2262 To make sure mappings will only work in the current buffer use the >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2263
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2264 :map <buffer>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2265
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2266 command. This needs to be combined with the two-step mapping explained above.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2267 An example of how to define functionality in a filetype plugin: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2268
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2269 if !hasmapto('<Plug>JavaImport')
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2270 map <buffer> <unique> <LocalLeader>i <Plug>JavaImport
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2271 endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2272 noremap <buffer> <unique> <Plug>JavaImport oimport ""<Left><Esc>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2273
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2274 |hasmapto()| is used to check if the user has already defined a map to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2275 <Plug>JavaImport. If not, then the filetype plugin defines the default
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2276 mapping. This starts with |<LocalLeader>|, which allows the user to select
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2277 the key(s) he wants filetype plugin mappings to start with. The default is a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2278 backslash.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2279 "<unique>" is used to give an error message if the mapping already exists or
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2280 overlaps with an existing mapping.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2281 |:noremap| is used to avoid that any other mappings that the user has defined
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2282 interferes. You might want to use ":noremap <script>" to allow remapping
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2283 mappings defined in this script that start with <SID>.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2284
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2285 The user must have a chance to disable the mappings in a filetype plugin,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2286 without disabling everything. Here is an example of how this is done for a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2287 plugin for the mail filetype: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2288
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2289 " Add mappings, unless the user didn't want this.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2290 if !exists("no_plugin_maps") && !exists("no_mail_maps")
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2291 " Quote text by inserting "> "
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2292 if !hasmapto('<Plug>MailQuote')
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2293 vmap <buffer> <LocalLeader>q <Plug>MailQuote
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2294 nmap <buffer> <LocalLeader>q <Plug>MailQuote
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2295 endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2296 vnoremap <buffer> <Plug>MailQuote :s/^/> /<CR>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2297 nnoremap <buffer> <Plug>MailQuote :.,$s/^/> /<CR>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2298 endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2299
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2300 Two global variables are used:
11262
214f228718cf Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 11229
diff changeset
2301 |no_plugin_maps| disables mappings for all filetype plugins
214f228718cf Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 11229
diff changeset
2302 |no_mail_maps| disables mappings for the "mail" filetype
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2303
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2304
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2305 USER COMMANDS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2306
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2307 To add a user command for a specific file type, so that it can only be used in
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2308 one buffer, use the "-buffer" argument to |:command|. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2309
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2310 :command -buffer Make make %:r.s
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2311
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2312
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2313 VARIABLES
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2314
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2315 A filetype plugin will be sourced for each buffer of the type it's for. Local
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2316 script variables |s:var| will be shared between all invocations. Use local
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2317 buffer variables |b:var| if you want a variable specifically for one buffer.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2318
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2319
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2320 FUNCTIONS
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2321
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2322 When defining a function, this only needs to be done once. But the filetype
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2323 plugin will be sourced every time a file with this filetype will be opened.
2207
b17bbfa96fa0 Add the settabvar() and gettabvar() functions.
Bram Moolenaar <bram@vim.org>
parents: 2154
diff changeset
2324 This construct makes sure the function is only defined once: >
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2325
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2326 :if !exists("*s:Func")
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2327 : function s:Func(arg)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2328 : ...
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2329 : endfunction
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2330 :endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2331 <
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2332
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7924
diff changeset
2333 UNDO *undo_indent* *undo_ftplugin*
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2334
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2335 When the user does ":setfiletype xyz" the effect of the previous filetype
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2336 should be undone. Set the b:undo_ftplugin variable to the commands that will
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2337 undo the settings in your filetype plugin. Example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2338
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2339 let b:undo_ftplugin = "setlocal fo< com< tw< commentstring<"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2340 \ . "| unlet b:match_ignorecase b:match_words b:match_skip"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2341
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2342 Using ":setlocal" with "<" after the option name resets the option to its
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2343 global value. That is mostly the best way to reset the option value.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2344
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2345 This does require removing the "C" flag from 'cpoptions' to allow line
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2346 continuation, as mentioned above |use-cpo-save|.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2347
8061
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7924
diff changeset
2348 For undoing the effect of an indent script, the b:undo_indent variable should
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7924
diff changeset
2349 be set accordingly.
abd64cf67bcf commit https://github.com/vim/vim/commit/38a55639d603823efcf2d2fdf542dbffdeb60b75
Christian Brabandt <cb@256bit.org>
parents: 7924
diff changeset
2350
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2351
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2352 FILE NAME
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2353
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2354 The filetype must be included in the file name |ftplugin-name|. Use one of
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2355 these three forms:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2356
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2357 .../ftplugin/stuff.vim
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2358 .../ftplugin/stuff_foo.vim
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2359 .../ftplugin/stuff/bar.vim
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2360
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2361 "stuff" is the filetype, "foo" and "bar" are arbitrary names.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2362
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2363
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2364 SUMMARY *ftplugin-special*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2365
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2366 Summary of special things to use in a filetype plugin:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2367
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2368 <LocalLeader> Value of "maplocalleader", which the user defines as
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2369 the keys that filetype plugin mappings start with.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2370
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2371 :map <buffer> Define a mapping local to the buffer.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2372
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2373 :noremap <script> Only remap mappings defined in this script that start
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2374 with <SID>.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2375
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2376 :setlocal Set an option for the current buffer only.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2377
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2378 :command -buffer Define a user command local to the buffer.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2379
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2380 exists("*s:Func") Check if a function was already defined.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2381
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2382 Also see |plugin-special|, the special things used for all plugins.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2383
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2384 ==============================================================================
161
6df0106fc595 updated for version 7.0049
vimboss
parents: 158
diff changeset
2385 *41.13* Writing a compiler plugin *write-compiler-plugin*
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2386
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2387 A compiler plugin sets options for use with a specific compiler. The user can
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2388 load it with the |:compiler| command. The main use is to set the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2389 'errorformat' and 'makeprg' options.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2390
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2391 Easiest is to have a look at examples. This command will edit all the default
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2392 compiler plugins: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2393
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2394 :next $VIMRUNTIME/compiler/*.vim
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2395
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2396 Use |:next| to go to the next plugin file.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2397
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2398 There are two special items about these files. First is a mechanism to allow
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2399 a user to overrule or add to the default file. The default files start with: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2400
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2401 :if exists("current_compiler")
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2402 : finish
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2403 :endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2404 :let current_compiler = "mine"
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2405
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2406 When you write a compiler file and put it in your personal runtime directory
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2407 (e.g., ~/.vim/compiler for Unix), you set the "current_compiler" variable to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2408 make the default file skip the settings.
570
27d1ec742f17 updated for version 7.0162
vimboss
parents: 434
diff changeset
2409 *:CompilerSet*
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2410 The second mechanism is to use ":set" for ":compiler!" and ":setlocal" for
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2411 ":compiler". Vim defines the ":CompilerSet" user command for this. However,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2412 older Vim versions don't, thus your plugin should define it then. This is an
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2413 example: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2414
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2415 if exists(":CompilerSet") != 2
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2416 command -nargs=* CompilerSet setlocal <args>
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2417 endif
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2418 CompilerSet errorformat& " use the default 'errorformat'
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2419 CompilerSet makeprg=nmake
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2420
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2421 When you write a compiler plugin for the Vim distribution or for a system-wide
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2422 runtime directory, use the mechanism mentioned above. When
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2423 "current_compiler" was already set by a user plugin nothing will be done.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2424
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2425 When you write a compiler plugin to overrule settings from a default plugin,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2426 don't check "current_compiler". This plugin is supposed to be loaded
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2427 last, thus it should be in a directory at the end of 'runtimepath'. For Unix
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2428 that could be ~/.vim/after/compiler.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2429
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2430 ==============================================================================
170
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2431 *41.14* Writing a plugin that loads quickly *write-plugin-quickload*
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2432
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2433 A plugin may grow and become quite long. The startup delay may become
1620
73fe8baea242 updated for version 7.2a
vimboss
parents: 1326
diff changeset
2434 noticeable, while you hardly ever use the plugin. Then it's time for a
170
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2435 quickload plugin.
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2436
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2437 The basic idea is that the plugin is loaded twice. The first time user
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2438 commands and mappings are defined that offer the functionality. The second
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2439 time the functions that implement the functionality are defined.
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2440
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2441 It may sound surprising that quickload means loading a script twice. What we
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2442 mean is that it loads quickly the first time, postponing the bulk of the
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2443 script to the second time, which only happens when you actually use it. When
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2444 you always use the functionality it actually gets slower!
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2445
793
8c0b00d50acf updated for version 7.0231
vimboss
parents: 681
diff changeset
2446 Note that since Vim 7 there is an alternative: use the |autoload|
8c0b00d50acf updated for version 7.0231
vimboss
parents: 681
diff changeset
2447 functionality |41.15|.
8c0b00d50acf updated for version 7.0231
vimboss
parents: 681
diff changeset
2448
170
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2449 The following example shows how it's done: >
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2450
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2451 " Vim global plugin for demonstrating quick loading
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2452 " Last Change: 2005 Feb 25
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2453 " Maintainer: Bram Moolenaar <Bram@vim.org>
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2454 " License: This file is placed in the public domain.
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2455
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2456 if !exists("s:did_load")
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2457 command -nargs=* BNRead call BufNetRead(<f-args>)
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2458 map <F19> :call BufNetWrite('something')<CR>
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2459
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2460 let s:did_load = 1
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2461 exe 'au FuncUndefined BufNet* source ' . expand('<sfile>')
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2462 finish
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2463 endif
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2464
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2465 function BufNetRead(...)
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2466 echo 'BufNetRead(' . string(a:000) . ')'
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2467 " read functionality here
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2468 endfunction
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2469
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2470 function BufNetWrite(...)
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2471 echo 'BufNetWrite(' . string(a:000) . ')'
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2472 " write functionality here
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2473 endfunction
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2474
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2475 When the script is first loaded "s:did_load" is not set. The commands between
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2476 the "if" and "endif" will be executed. This ends in a |:finish| command, thus
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2477 the rest of the script is not executed.
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2478
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2479 The second time the script is loaded "s:did_load" exists and the commands
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2480 after the "endif" are executed. This defines the (possible long)
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2481 BufNetRead() and BufNetWrite() functions.
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2482
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2483 If you drop this script in your plugin directory Vim will execute it on
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2484 startup. This is the sequence of events that happens:
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2485
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2486 1. The "BNRead" command is defined and the <F19> key is mapped when the script
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2487 is sourced at startup. A |FuncUndefined| autocommand is defined. The
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2488 ":finish" command causes the script to terminate early.
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2489
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2490 2. The user types the BNRead command or presses the <F19> key. The
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2491 BufNetRead() or BufNetWrite() function will be called.
856
8cd729851562 updated for version 7.0g
vimboss
parents: 842
diff changeset
2492
170
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2493 3. Vim can't find the function and triggers the |FuncUndefined| autocommand
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2494 event. Since the pattern "BufNet*" matches the invoked function, the
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2495 command "source fname" will be executed. "fname" will be equal to the name
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2496 of the script, no matter where it is located, because it comes from
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2497 expanding "<sfile>" (see |expand()|).
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2498
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2499 4. The script is sourced again, the "s:did_load" variable exists and the
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2500 functions are defined.
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2501
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2502 Notice that the functions that are loaded afterwards match the pattern in the
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2503 |FuncUndefined| autocommand. You must make sure that no other plugin defines
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2504 functions that match this pattern.
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2505
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2506 ==============================================================================
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2507 *41.15* Writing library scripts *write-library-script*
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2508
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2509 Some functionality will be required in several places. When this becomes more
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2510 than a few lines you will want to put it in one script and use it from many
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2511 scripts. We will call that one script a library script.
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2512
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2513 Manually loading a library script is possible, so long as you avoid loading it
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2514 when it's already done. You can do this with the |exists()| function.
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2515 Example: >
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2516
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2517 if !exists('*MyLibFunction')
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2518 runtime library/mylibscript.vim
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2519 endif
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2520 call MyLibFunction(arg)
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2521
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2522 Here you need to know that MyLibFunction() is defined in a script
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2523 "library/mylibscript.vim" in one of the directories in 'runtimepath'.
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2524
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2525 To make this a bit simpler Vim offers the autoload mechanism. Then the
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2526 example looks like this: >
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2527
270
a20218704019 updated for version 7.0072
vimboss
parents: 230
diff changeset
2528 call mylib#myfunction(arg)
170
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2529
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2530 That's a lot simpler, isn't it? Vim will recognize the function name and when
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2531 it's not defined search for the script "autoload/mylib.vim" in 'runtimepath'.
270
a20218704019 updated for version 7.0072
vimboss
parents: 230
diff changeset
2532 That script must define the "mylib#myfunction()" function.
170
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2533
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2534 You can put many other functions in the mylib.vim script, you are free to
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2535 organize your functions in library scripts. But you must use function names
323
03b3684919e3 updated for version 7.0084
vimboss
parents: 270
diff changeset
2536 where the part before the '#' matches the script name. Otherwise Vim would
03b3684919e3 updated for version 7.0084
vimboss
parents: 270
diff changeset
2537 not know what script to load.
170
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2538
681
9364d114ed8d updated for version 7.0204
vimboss
parents: 667
diff changeset
2539 If you get really enthusiastic and write lots of library scripts, you may
170
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2540 want to use subdirectories. Example: >
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2541
270
a20218704019 updated for version 7.0072
vimboss
parents: 230
diff changeset
2542 call netlib#ftp#read('somefile')
170
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2543
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2544 For Unix the library script used for this could be:
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2545
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2546 ~/.vim/autoload/netlib/ftp.vim
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2547
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2548 Where the function is defined like this: >
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2549
270
a20218704019 updated for version 7.0072
vimboss
parents: 230
diff changeset
2550 function netlib#ftp#read(fname)
170
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2551 " Read the file fname through ftp
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2552 endfunction
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2553
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2554 Notice that the name the function is defined with is exactly the same as the
323
03b3684919e3 updated for version 7.0084
vimboss
parents: 270
diff changeset
2555 name used for calling the function. And the part before the last '#'
170
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2556 exactly matches the subdirectory and script name.
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2557
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2558 You can use the same mechanism for variables: >
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2559
270
a20218704019 updated for version 7.0072
vimboss
parents: 230
diff changeset
2560 let weekdays = dutch#weekdays
170
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2561
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2562 This will load the script "autoload/dutch.vim", which should contain something
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2563 like: >
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2564
270
a20218704019 updated for version 7.0072
vimboss
parents: 230
diff changeset
2565 let dutch#weekdays = ['zondag', 'maandag', 'dinsdag', 'woensdag',
170
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2566 \ 'donderdag', 'vrijdag', 'zaterdag']
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2567
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2568 Further reading: |autoload|.
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2569
8c60f65311fa updated for version 7.0052
vimboss
parents: 164
diff changeset
2570 ==============================================================================
793
8c0b00d50acf updated for version 7.0231
vimboss
parents: 681
diff changeset
2571 *41.16* Distributing Vim scripts *distribute-script*
8c0b00d50acf updated for version 7.0231
vimboss
parents: 681
diff changeset
2572
8c0b00d50acf updated for version 7.0231
vimboss
parents: 681
diff changeset
2573 Vim users will look for scripts on the Vim website: http://www.vim.org.
8c0b00d50acf updated for version 7.0231
vimboss
parents: 681
diff changeset
2574 If you made something that is useful for others, share it!
8c0b00d50acf updated for version 7.0231
vimboss
parents: 681
diff changeset
2575
8c0b00d50acf updated for version 7.0231
vimboss
parents: 681
diff changeset
2576 Vim scripts can be used on any system. There might not be a tar or gzip
8c0b00d50acf updated for version 7.0231
vimboss
parents: 681
diff changeset
2577 command. If you want to pack files together and/or compress them the "zip"
8c0b00d50acf updated for version 7.0231
vimboss
parents: 681
diff changeset
2578 utility is recommended.
8c0b00d50acf updated for version 7.0231
vimboss
parents: 681
diff changeset
2579
8c0b00d50acf updated for version 7.0231
vimboss
parents: 681
diff changeset
2580 For utmost portability use Vim itself to pack scripts together. This can be
8c0b00d50acf updated for version 7.0231
vimboss
parents: 681
diff changeset
2581 done with the Vimball utility. See |vimball|.
8c0b00d50acf updated for version 7.0231
vimboss
parents: 681
diff changeset
2582
799
6beb2c667935 updated for version 7.0b
vimboss
parents: 793
diff changeset
2583 It's good if you add a line to allow automatic updating. See |glvs-plugins|.
6beb2c667935 updated for version 7.0b
vimboss
parents: 793
diff changeset
2584
793
8c0b00d50acf updated for version 7.0231
vimboss
parents: 681
diff changeset
2585 ==============================================================================
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2586
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2587 Next chapter: |usr_42.txt| Add new menus
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2588
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2589 Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: