Mercurial > hg > RemoteEditor > vim7

comparison runtime/doc/if_pyth.txt @ 0:76efa0be13f1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial revision
author atsuki
date Sat, 10 Nov 2007 15:07:22 +0900
parents
children e170173ecb68
comparison
equal deleted inserted replaced
-1:000000000000 0:76efa0be13f1
1 *if_pyth.txt* For Vim version 7.1. Last change: 2006 Apr 30
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|
14 6. Dynamic loading |python-dynamic|
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
89 |python-output| below) via the "vim" module. The vim module implements two
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 >
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
112
113
114 Methods of the "vim" module
115
116 vim.command(str) *python-command*
117 Executes the vim (ex-mode) command str. Returns None.
118 Examples: >
119 :py vim.command("set tw=72")
120 :py vim.command("%s/aaa/bbb/g")
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: >
130 :py vim.command("python print 'Hello again Python'")
131
132 vim.eval(str) *python-eval*
133 Evaluates the expression str using the vim internal expression
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
137 - a dictionary if the Vim expression evaluates to a Vim dictionary
138 Dictionaries and lists are recursively expanded.
139 Examples: >
140 :py text_width = vim.eval("&tw")
141 :py str = vim.eval("12+12") # NB result is a string! Use
142 # string.atoi() to convert to
143 # a number.
144
145 :py tagList = vim.eval('taglist("eval_expr")')
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
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*
170 A sequence object providing access to the list of vim buffers. The
171 object supports the following operations: >
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
176 <
177 vim.windows *python-windows*
178 A sequence object providing access to the list of vim windows. The
179 object supports the following operations: >
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
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
193 The last case deserves a little explanation. When the :python or
194 :pyfile command specifies a range, this range of lines becomes the
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.
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
211 supported, and may cause the program to crash. This should probably be
212 fixed.
213
214 ==============================================================================
215 3. Buffer objects *python-buffer*
216
217 Buffer objects represent vim buffers. You can obtain them in a number of ways:
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
223 the buffer. They also have three methods (append, mark, and range; see below).
224
225 You can also treat buffer objects as sequence objects. In this context, they
226 act as if they were lists (yes, they are mutable) of strings, with each
227 element being a line of the buffer. All of the usual sequence operations,
228 including indexing, index assignment, slicing and slice assignment, work as
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
232 "b = None" merely updates the variable b, with no effect on the buffer.
233
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
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
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
254 Examples (assume b is the current buffer) >
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
265
266 ==============================================================================
267 4. Range objects *python-range*
268
269 Range objects represent a part of a vim buffer. You can obtain them in a
270 number of ways:
271 - via vim.current.range (|python-current|)
272 - from a buffer's range() method (|python-buffer|)
273
274 A range object is almost identical in operation to a buffer object. However,
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
297 Window objects represent vim windows. You can obtain them in a number of ways:
298 - via vim.current.window (|python-current|)
299 - from indexing vim.windows (|python-windows|)
300
301 You can manipulate window objects only through their attributes. They have no
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 ==============================================================================
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 ==============================================================================
331 vim:tw=78:ts=8:ft=help:norl: