1 *if_python.txt* For Vim version 5.8. Last change: 1999 Oct 28
4 VIM REFERENCE MANUAL by Paul Moore
7 The Python Interface to Vim *python* *Python*
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|
15 {Vi does not have any of these commands}
17 The Python interface only works when Vim was compiled with the |+python|
20 ==============================================================================
21 1. Commands *python-commands*
24 :[range]py[thon] {stmt} Execute Python statement {stmt}. {not in Vi}
27 :[range]pyf[ile] {file} Execute the Python script in {file}. {not in Vi}
29 Both of these commands do essentially the same thing - they execute a piece of
30 Python code, with the "current range" |python-range| set to the given line
33 In the case of :python, the code to execute is specified on the command-line.
34 In the case of :pyfile, the code to execute is the contents of the given file.
36 Here are some examples *python-examples*
38 > :python from vim import *
39 > :python from string import upper
40 > :python current.line = upper(current.line)
41 > :python print "Hello"
42 > :python str = current.buffer[42]
44 (Note that changes - like the imports - persist from one command to the next,
45 just like in the Python interpreter).
47 ==============================================================================
48 2. The vim module *python-vim*
50 Python code gets all of its access to vim (with one exception - see
51 |python-output| below) via the "vim" module. The vim module implements two
52 methods, three constants, and one error object.
55 > print "Hello" # displays a message
56 > vim.command(cmd) # execute an ex command
57 > w = vim.windows[n] # gets window "n"
58 > cw = vim.current.window # gets the current window
59 > b = vim.buffers[n] # gets buffer "n"
60 > cb = vim.current.buffer # gets the current buffer
61 > w.height = lines # sets the window height
62 > w.cursor = (row, col) # sets the window cursor position
63 > pos = w.cursor # gets a tuple (row, col)
64 > name = b.name # gets the buffer file name
65 > line = b[n] # gets a line from the buffer
66 > lines = b[n:m] # gets a list of lines
67 > num = len(b) # gets the number of lines
68 > b[n] = str # sets a line in the buffer
69 > b[n:m] = [str1, str2, str3] # sets a number of lines at once
70 > del b[n] # deletes a line
71 > del b[n:m] # deletes a number of lines
74 vim.command(str) *python-command*
75 Executes the vim (ex-mode) command str. Returns None.
77 > vim.command("set tw=72")
78 > vim.command("%s/aaa/bbb/g")
79 To execute normal-mode commands, the following definition could be
82 > vim.command("normal "+str)
83 > # Note the use of '...' to delimit a string containing double
87 vim.eval(str) *python-eval*
88 Evaluates the expression str using the vim internal expression
89 evaluator (see |expression|). Returns the expression result as a
92 > text_width = vim.eval("'tw'")
93 > str = vim.eval("12+12") # NB result is a string! Use
94 > # string.atoi() to convert to
98 vim.error *python-error*
99 All vim errors encountered by Python are raised as exceptions of type
103 > vim.command("put a")
105 > # nothing in register a
108 Note that these are not actually constants - in theory you could
109 reassign them. But this is silly, as you would then lose access to the
110 vim objects referred to by the variables.
112 vim.buffers *python-buffers*
113 A sequence object providing access to the list of vim buffers. The
114 following operations are supported:
115 > b = vim.buffers[i] # Indexing (read-only)
116 > b in vim.buffers # Membership test
117 > n = len(vim.buffers) # Number of elements
118 > for b in vim.buffers: # Sequential access
120 vim.windows *python-windows*
121 A sequence object providing access to the list of vim windows. The
122 following operations are supported:
123 > w = vim.windows[i] # Indexing (read-only)
124 > w in vim.windows # Membership test
125 > n = len(vim.windows) # Number of elements
126 > for w in vim.windows: # Sequential access
128 vim.current *python-current*
129 An object providing access (via specific attributes) to various
130 "current" objects available in vim:
131 vim.current.line The current line (RW) String
132 vim.current.buffer The current buffer (RO) Buffer
133 vim.current.window The current window (RO) Window
134 vim.current.range The current line range (RO) Range
136 The last case deserves a little explanation. When a range is specified
137 in the :python or :pyfile command, this range of lines is treated as
138 the "current range". A range is a bit like a buffer, but with all
139 access restricted to a subset of lines. See |python-range| for more
142 Output from Python *python-output*
143 All output from Python code is displayed in the Vim message area.
144 Normal output is displayed as information messages, and error output
145 is displayed as error messages.
147 In implementation terms, this means that all output directed to
148 sys.stdout (including the output from print statements) is displayed
149 by vim as an information message, and all output directed to
150 sys.stderr (including error tracebacks) is displayed by vim as an
154 Input (via sys.stdin, including input() and raw_input()) is not
155 supported, and may cause the program to crash. This should probably be
158 ==============================================================================
159 3. Buffer objects *python-buffer*
161 Buffer objects represent vim buffers. They can be obtained in a number of
163 - via vim.current.buffer (|python-current|)
164 - from indexing vim.buffers (|python-buffers|)
165 - from the "buffer" attribute of a window (|python-window|)
167 Buffer objects have one read-only attribute - name - the full file name for
168 the buffer. They also have three methods (append, mark, and range) which are
171 Buffer objects can also be treated as sequence objects. In this context, they
172 act as if they were lists (yes, they are mutable) of strings, with each
173 element being a line of the buffer. All of the usual sequence operations,
174 including indexing, index assignment, slicing and slice assignment, work as
175 you would expect. Note that the result of indexing (slicing) a buffer is a
176 string (list of strings). This has one unusual consequence - b[:] is different
177 from b. In particular, "b[:] = None" deletes the whole of the buffer, whereas
178 "b = None" merely updates the variable b, with no effect on the buffer.
180 Buffer indexes start at zero, as is normal in Python. This differs from vim
181 line numbers, which start from 1. This is particularly relevant when dealing
182 with marks (see below) which use vim line numbers.
184 The buffer object methods are:
185 b.append(str) Append a line to the buffer
186 b.append(list) Append a list of lines to the buffer
187 Note that the option of supplying a list of strings to
188 the append method differs from the equivalent method
189 for Python's built-in list objects.
190 b.mark(name) Return a tuple (row,col) representing the position
191 of the named mark (can also get the []"<> marks)
192 b.range(s,e) Return a range object (see |python-range|) which
193 represents the part of the given buffer between line
194 numbers s and e (inclusive).
196 Examples (assume b is the current buffer)
197 > print b.name # write the buffer file name
198 > b[0] = "hello!!!" # replace the top line
199 > b[:] = None # delete the whole buffer
200 > del b[:] # delete the whole buffer (same as above)
201 > b[0:0] = "add a line" # add a line at the top
202 > del b[2] # delete a line (the third)
203 > b.append("bottom") # add a line at the bottom
204 > n = len(b) # number of lines
205 > (row,col) = b.mark('a') # named mark
206 > r = b.range(1,5) # a sub-range of the buffer
208 ==============================================================================
209 4. Range objects *python-range*
211 Range objects represent a part of a vim buffer. They can be obtained in a
213 - via vim.current.range (|python-current|)
214 - from a buffer's range() method (|python-buffer|)
216 A range object is almost identical in operation to a buffer object. However,
217 all operations are restricted to the lines within the range (this line range
218 can, of course, change as a result of slice assignments, line deletions, or
219 the range.append() method).
221 Unlike buffers, ranges do not have a "name" attribute, nor do they have mark()
222 or range() methods. They do have an append() method, however, which adds
223 line(s) to the end of the range.
225 ==============================================================================
226 5. Window objects *python-window*
228 Window objects represent vim windows. They can be obtained in a number of
230 - via vim.current.window (|python-current|)
231 - from indexing vim.windows (|python-windows|)
233 Window objects can only be manipulated through their attributes. They have no
234 methods, and no sequence or other interface.
236 Window attributes are
237 buffer (read-only) The buffer displayed in this window
238 cursor (read-write) The current cursor position in the window
239 This is a tuple, (row,col).
240 height (read-write) The window height, in rows
242 ==============================================================================