|
874
|
1 *if_pyth.txt* For Vim version 7.0. Last change: 2006 Apr 30
|
|
7
|
2
|
|
|
3
|
|
|
4 VIM REFERENCE MANUAL by Paul Moore
|
|
|
5
|
|
|
6
|
|
|
7 The Python Interface to Vim *python* *Python*
|
|
|
8
|
|
|
9 1. Commands |python-commands|
|
|
|
10 2. The vim module |python-vim|
|
|
|
11 3. Buffer objects |python-buffer|
|
|
|
12 4. Range objects |python-range|
|
|
|
13 5. Window objects |python-window|
|
|
557
|
14 6. Dynamic loading |python-dynamic|
|
|
7
|
15
|
|
|
16 {Vi does not have any of these commands}
|
|
|
17
|
|
|
18 The Python interface is available only when Vim was compiled with the
|
|
|
19 |+python| feature.
|
|
|
20
|
|
|
21 ==============================================================================
|
|
|
22 1. Commands *python-commands*
|
|
|
23
|
|
|
24 *:python* *:py* *E205* *E263* *E264*
|
|
|
25 :[range]py[thon] {stmt}
|
|
|
26 Execute Python statement {stmt}.
|
|
|
27
|
|
|
28 :[range]py[thon] << {endmarker}
|
|
|
29 {script}
|
|
|
30 {endmarker}
|
|
|
31 Execute Python script {script}.
|
|
|
32 Note: This command doesn't work when the Python
|
|
|
33 feature wasn't compiled in. To avoid errors, see
|
|
|
34 |script-here|.
|
|
|
35
|
|
|
36 {endmarker} must NOT be preceded by any white space. If {endmarker} is
|
|
|
37 omitted from after the "<<", a dot '.' must be used after {script}, like
|
|
|
38 for the |:append| and |:insert| commands.
|
|
|
39 This form of the |:python| command is mainly useful for including python code
|
|
|
40 in Vim scripts.
|
|
|
41
|
|
|
42 Example: >
|
|
|
43 function! IcecreamInitialize()
|
|
|
44 python << EOF
|
|
|
45 class StrawberryIcecream:
|
|
|
46 def __call__(self):
|
|
|
47 print 'EAT ME'
|
|
|
48 EOF
|
|
|
49 endfunction
|
|
|
50 <
|
|
|
51 Note: Python is very sensitive to the indenting. Also make sure the "class"
|
|
|
52 line and "EOF" do not have any indent.
|
|
|
53
|
|
|
54 *:pyfile* *:pyf*
|
|
|
55 :[range]pyf[ile] {file}
|
|
|
56 Execute the Python script in {file}. The whole
|
|
|
57 argument is used as a single file name. {not in Vi}
|
|
|
58
|
|
|
59 Both of these commands do essentially the same thing - they execute a piece of
|
|
|
60 Python code, with the "current range" |python-range| set to the given line
|
|
|
61 range.
|
|
|
62
|
|
|
63 In the case of :python, the code to execute is in the command-line.
|
|
|
64 In the case of :pyfile, the code to execute is the contents of the given file.
|
|
|
65
|
|
|
66 Python commands cannot be used in the |sandbox|.
|
|
|
67
|
|
|
68 To pass arguments you need to set sys.argv[] explicitly. Example: >
|
|
|
69
|
|
|
70 :python import sys
|
|
|
71 :python sys.argv = ["foo", "bar"]
|
|
|
72 :pyfile myscript.py
|
|
|
73
|
|
|
74 Here are some examples *python-examples* >
|
|
|
75
|
|
|
76 :python from vim import *
|
|
|
77 :python from string import upper
|
|
|
78 :python current.line = upper(current.line)
|
|
|
79 :python print "Hello"
|
|
|
80 :python str = current.buffer[42]
|
|
|
81
|
|
|
82 (Note that changes - like the imports - persist from one command to the next,
|
|
|
83 just like in the Python interpreter.)
|
|
|
84
|
|
|
85 ==============================================================================
|
|
|
86 2. The vim module *python-vim*
|
|
|
87
|
|
|
88 Python code gets all of its access to vim (with one exception - see
|
|
236
|
89 |python-output| below) via the "vim" module. The vim module implements two
|
|
7
|
90 methods, three constants, and one error object. You need to import the vim
|
|
|
91 module before using it: >
|
|
|
92 :python import vim
|
|
|
93
|
|
|
94 Overview >
|
|
20
|
95 :py print "Hello" # displays a message
|
|
|
96 :py vim.command(cmd) # execute an ex command
|
|
|
97 :py w = vim.windows[n] # gets window "n"
|
|
|
98 :py cw = vim.current.window # gets the current window
|
|
|
99 :py b = vim.buffers[n] # gets buffer "n"
|
|
|
100 :py cb = vim.current.buffer # gets the current buffer
|
|
|
101 :py w.height = lines # sets the window height
|
|
|
102 :py w.cursor = (row, col) # sets the window cursor position
|
|
|
103 :py pos = w.cursor # gets a tuple (row, col)
|
|
|
104 :py name = b.name # gets the buffer file name
|
|
|
105 :py line = b[n] # gets a line from the buffer
|
|
|
106 :py lines = b[n:m] # gets a list of lines
|
|
|
107 :py num = len(b) # gets the number of lines
|
|
|
108 :py b[n] = str # sets a line in the buffer
|
|
|
109 :py b[n:m] = [str1, str2, str3] # sets a number of lines at once
|
|
|
110 :py del b[n] # deletes a line
|
|
|
111 :py del b[n:m] # deletes a number of lines
|
|
7
|
112
|
|
|
113
|
|
|
114 Methods of the "vim" module
|
|
|
115
|
|
|
116 vim.command(str) *python-command*
|
|
236
|
117 Executes the vim (ex-mode) command str. Returns None.
|
|
7
|
118 Examples: >
|
|
20
|
119 :py vim.command("set tw=72")
|
|
|
120 :py vim.command("%s/aaa/bbb/g")
|
|
7
|
121 < The following definition executes Normal mode commands: >
|
|
|
122 def normal(str):
|
|
|
123 vim.command("normal "+str)
|
|
|
124 # Note the use of single quotes to delimit a string containing
|
|
|
125 # double quotes
|
|
|
126 normal('"a2dd"aP')
|
|
|
127 < *E659*
|
|
|
128 The ":python" command cannot be used recursively with Python 2.2 and
|
|
|
129 older. This only works with Python 2.3 and later: >
|
|
20
|
130 :py vim.command("python print 'Hello again Python'")
|
|
7
|
131
|
|
|
132 vim.eval(str) *python-eval*
|
|
|
133 Evaluates the expression str using the vim internal expression
|
|
633
|
134 evaluator (see |expression|). Returns the expression result as:
|
|
|
135 - a string if the Vim expression evaluates to a string or number
|
|
|
136 - a list if the Vim expression evaluates to a Vim list
|
|
856
|
137 - a dictionary if the Vim expression evaluates to a Vim dictionary
|
|
633
|
138 Dictionaries and lists are recursively expanded.
|
|
7
|
139 Examples: >
|
|
20
|
140 :py text_width = vim.eval("&tw")
|
|
|
141 :py str = vim.eval("12+12") # NB result is a string! Use
|
|
7
|
142 # string.atoi() to convert to
|
|
|
143 # a number.
|
|
|
144
|
|
856
|
145 :py tagList = vim.eval('taglist("eval_expr")')
|
|
633
|
146 < The latter will return a python list of python dicts, for instance:
|
|
|
147 [{'cmd': '/^eval_expr(arg, nextcmd)$/', 'static': 0, 'name':
|
|
|
148 'eval_expr', 'kind': 'f', 'filename': './src/eval.c'}]
|
|
|
149
|
|
|
150
|
|
|
151
|
|
7
|
152 Error object of the "vim" module
|
|
|
153
|
|
|
154 vim.error *python-error*
|
|
|
155 Upon encountering a Vim error, Python raises an exception of type
|
|
|
156 vim.error.
|
|
|
157 Example: >
|
|
|
158 try:
|
|
|
159 vim.command("put a")
|
|
|
160 except vim.error:
|
|
|
161 # nothing in register a
|
|
|
162
|
|
|
163 Constants of the "vim" module
|
|
|
164
|
|
|
165 Note that these are not actually constants - you could reassign them.
|
|
|
166 But this is silly, as you would then lose access to the vim objects
|
|
|
167 to which the variables referred.
|
|
|
168
|
|
|
169 vim.buffers *python-buffers*
|
|
236
|
170 A sequence object providing access to the list of vim buffers. The
|
|
7
|
171 object supports the following operations: >
|
|
20
|
172 :py b = vim.buffers[i] # Indexing (read-only)
|
|
|
173 :py b in vim.buffers # Membership test
|
|
|
174 :py n = len(vim.buffers) # Number of elements
|
|
|
175 :py for b in vim.buffers: # Sequential access
|
|
7
|
176 <
|
|
|
177 vim.windows *python-windows*
|
|
236
|
178 A sequence object providing access to the list of vim windows. The
|
|
7
|
179 object supports the following operations: >
|
|
20
|
180 :py w = vim.windows[i] # Indexing (read-only)
|
|
|
181 :py w in vim.windows # Membership test
|
|
|
182 :py n = len(vim.windows) # Number of elements
|
|
|
183 :py for w in vim.windows: # Sequential access
|
|
7
|
184 <
|
|
|
185 vim.current *python-current*
|
|
|
186 An object providing access (via specific attributes) to various
|
|
|
187 "current" objects available in vim:
|
|
|
188 vim.current.line The current line (RW) String
|
|
|
189 vim.current.buffer The current buffer (RO) Buffer
|
|
|
190 vim.current.window The current window (RO) Window
|
|
|
191 vim.current.range The current line range (RO) Range
|
|
|
192
|
|
236
|
193 The last case deserves a little explanation. When the :python or
|
|
7
|
194 :pyfile command specifies a range, this range of lines becomes the
|
|
236
|
195 "current range". A range is a bit like a buffer, but with all access
|
|
|
196 restricted to a subset of lines. See |python-range| for more details.
|
|
7
|
197
|
|
|
198
|
|
|
199 Output from Python *python-output*
|
|
|
200 Vim displays all Python code output in the Vim message area. Normal
|
|
|
201 output appears as information messages, and error output appears as
|
|
|
202 error messages.
|
|
|
203
|
|
|
204 In implementation terms, this means that all output to sys.stdout
|
|
|
205 (including the output from print statements) appears as information
|
|
|
206 messages, and all output to sys.stderr (including error tracebacks)
|
|
|
207 appears as error messages.
|
|
|
208
|
|
|
209 *python-input*
|
|
|
210 Input (via sys.stdin, including input() and raw_input()) is not
|
|
236
|
211 supported, and may cause the program to crash. This should probably be
|
|
7
|
212 fixed.
|
|
|
213
|
|
|
214 ==============================================================================
|
|
|
215 3. Buffer objects *python-buffer*
|
|
|
216
|
|
236
|
217 Buffer objects represent vim buffers. You can obtain them in a number of ways:
|
|
7
|
218 - via vim.current.buffer (|python-current|)
|
|
|
219 - from indexing vim.buffers (|python-buffers|)
|
|
|
220 - from the "buffer" attribute of a window (|python-window|)
|
|
|
221
|
|
|
222 Buffer objects have one read-only attribute - name - the full file name for
|
|
236
|
223 the buffer. They also have three methods (append, mark, and range; see below).
|
|
7
|
224
|
|
236
|
225 You can also treat buffer objects as sequence objects. In this context, they
|
|
7
|
226 act as if they were lists (yes, they are mutable) of strings, with each
|
|
236
|
227 element being a line of the buffer. All of the usual sequence operations,
|
|
7
|
228 including indexing, index assignment, slicing and slice assignment, work as
|
|
236
|
229 you would expect. Note that the result of indexing (slicing) a buffer is a
|
|
|
230 string (list of strings). This has one unusual consequence - b[:] is different
|
|
|
231 from b. In particular, "b[:] = None" deletes the whole of the buffer, whereas
|
|
7
|
232 "b = None" merely updates the variable b, with no effect on the buffer.
|
|
|
233
|
|
236
|
234 Buffer indexes start at zero, as is normal in Python. This differs from vim
|
|
|
235 line numbers, which start from 1. This is particularly relevant when dealing
|
|
7
|
236 with marks (see below) which use vim line numbers.
|
|
|
237
|
|
|
238 The buffer object methods are:
|
|
|
239 b.append(str) Append a line to the buffer
|
|
|
240 b.append(list) Append a list of lines to the buffer
|
|
|
241 Note that the option of supplying a list of strings to
|
|
|
242 the append method differs from the equivalent method
|
|
|
243 for Python's built-in list objects.
|
|
|
244 b.mark(name) Return a tuple (row,col) representing the position
|
|
|
245 of the named mark (can also get the []"<> marks)
|
|
|
246 b.range(s,e) Return a range object (see |python-range|) which
|
|
|
247 represents the part of the given buffer between line
|
|
|
248 numbers s and e |inclusive|.
|
|
|
249
|
|
20
|
250 Note that when adding a line it must not contain a line break character '\n'.
|
|
|
251 A trailing '\n' is allowed and ignored, so that you can do: >
|
|
|
252 :py b.append(f.readlines())
|
|
|
253
|
|
7
|
254 Examples (assume b is the current buffer) >
|
|
20
|
255 :py print b.name # write the buffer file name
|
|
|
256 :py b[0] = "hello!!!" # replace the top line
|
|
|
257 :py b[:] = None # delete the whole buffer
|
|
|
258 :py del b[:] # delete the whole buffer
|
|
|
259 :py b[0:0] = [ "a line" ] # add a line at the top
|
|
|
260 :py del b[2] # delete a line (the third)
|
|
|
261 :py b.append("bottom") # add a line at the bottom
|
|
|
262 :py n = len(b) # number of lines
|
|
|
263 :py (row,col) = b.mark('a') # named mark
|
|
|
264 :py r = b.range(1,5) # a sub-range of the buffer
|
|
7
|
265
|
|
|
266 ==============================================================================
|
|
|
267 4. Range objects *python-range*
|
|
|
268
|
|
236
|
269 Range objects represent a part of a vim buffer. You can obtain them in a
|
|
7
|
270 number of ways:
|
|
|
271 - via vim.current.range (|python-current|)
|
|
|
272 - from a buffer's range() method (|python-buffer|)
|
|
|
273
|
|
236
|
274 A range object is almost identical in operation to a buffer object. However,
|
|
7
|
275 all operations are restricted to the lines within the range (this line range
|
|
|
276 can, of course, change as a result of slice assignments, line deletions, or
|
|
|
277 the range.append() method).
|
|
|
278
|
|
|
279 The range object attributes are:
|
|
|
280 r.start Index of first line into the buffer
|
|
|
281 r.end Index of last line into the buffer
|
|
|
282
|
|
|
283 The range object methods are:
|
|
|
284 r.append(str) Append a line to the range
|
|
|
285 r.append(list) Append a list of lines to the range
|
|
|
286 Note that the option of supplying a list of strings to
|
|
|
287 the append method differs from the equivalent method
|
|
|
288 for Python's built-in list objects.
|
|
|
289
|
|
|
290 Example (assume r is the current range):
|
|
|
291 # Send all lines in a range to the default printer
|
|
|
292 vim.command("%d,%dhardcopy!" % (r.start+1,r.end+1))
|
|
|
293
|
|
|
294 ==============================================================================
|
|
|
295 5. Window objects *python-window*
|
|
|
296
|
|
236
|
297 Window objects represent vim windows. You can obtain them in a number of ways:
|
|
7
|
298 - via vim.current.window (|python-current|)
|
|
|
299 - from indexing vim.windows (|python-windows|)
|
|
|
300
|
|
236
|
301 You can manipulate window objects only through their attributes. They have no
|
|
7
|
302 methods, and no sequence or other interface.
|
|
|
303
|
|
|
304 Window attributes are:
|
|
|
305 buffer (read-only) The buffer displayed in this window
|
|
|
306 cursor (read-write) The current cursor position in the window
|
|
|
307 This is a tuple, (row,col).
|
|
|
308 height (read-write) The window height, in rows
|
|
|
309 width (read-write) The window width, in columns
|
|
|
310 The height attribute is writable only if the screen is split horizontally.
|
|
|
311 The width attribute is writable only if the screen is split vertically.
|
|
|
312
|
|
|
313 ==============================================================================
|
|
557
|
314 6. Dynamic loading *python-dynamic*
|
|
|
315
|
|
|
316 On MS-Windows the Python library can be loaded dynamically. The |:version|
|
|
|
317 output then includes |+python/dyn|.
|
|
|
318
|
|
|
319 This means that Vim will search for the Python DLL file only when needed.
|
|
|
320 When you don't use the Python interface you don't need it, thus you can use
|
|
|
321 Vim without this DLL file.
|
|
|
322
|
|
|
323 To use the Python interface the Python DLL must be in your search path. In a
|
|
|
324 console window type "path" to see what directories are used.
|
|
|
325
|
|
|
326 The name of the DLL must match the Python version Vim was compiled with.
|
|
|
327 Currently the name is "python24.dll". That is for Python 2.4. To know for
|
|
|
328 sure edit "gvim.exe" and search for "python\d*.dll\c".
|
|
|
329
|
|
|
330 ==============================================================================
|
|
7
|
331 vim:tw=78:ts=8:ft=help:norl:
|
