Mercurial > hg > RemoteEditor > vim7
annotate runtime/doc/if_pyth.txt @ 34:e170173ecb68 current-release
before ack base protocol.
| author | Shinji KONO <kono@ie.u-ryukyu.ac.jp> |
|---|---|
| date | Wed, 26 Nov 2008 15:02:10 +0900 |
| parents | 76efa0be13f1 |
| children | c16898406ff2 |
| rev | line source |
|---|---|
|
34
e170173ecb68
before ack base protocol.
Shinji KONO <kono@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
1 *if_pyth.txt* For Vim version 7.2. Last change: 2006 Apr 30 |
| 0 | 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: |