Mercurial > vim

comparison runtime/doc/if_pyth.txt @ 4496:ebd94eabfd80 v7.3.996

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
updated for version 7.3.996 Problem: Python: Can't check types of what is returned by bindeval(). Solution: Add vim.List, vim.Dictionary and vim.Function types. (ZyX)
author Bram Moolenaar <bram@vim.org>
date Tue, 21 May 2013 19:50:34 +0200
parents eb6ab7e78925
children 605c9ce57ec3
comparison
equal deleted inserted replaced
4495:fe5605ef4d72 4496:ebd94eabfd80
9 1. Commands |python-commands| 9 1. Commands |python-commands|
10 2. The vim module |python-vim| 10 2. The vim module |python-vim|
11 3. Buffer objects |python-buffer| 11 3. Buffer objects |python-buffer|
12 4. Range objects |python-range| 12 4. Range objects |python-range|
13 5. Window objects |python-window| 13 5. Window objects |python-window|
14 6. pyeval(), py3eval() Vim functions |python-pyeval| 14 6. Tab page objects |python-tabpage|
15 7. Dynamic loading |python-dynamic| 15 7. pyeval(), py3eval() Vim functions |python-pyeval|
16 8. Python 3 |python3| 16 8. Dynamic loading |python-dynamic|
17 9. Python 3 |python3|
17 18
18 {Vi does not have any of these commands} 19 {Vi does not have any of these commands}
19 20
20 The Python 2.x interface is available only when Vim was compiled with the 21 The Python 2.x interface is available only when Vim was compiled with the
21 |+python| feature. 22 |+python| feature.
174 1. if expression evaluates to |List| or |Dictionary| it is returned as 175 1. if expression evaluates to |List| or |Dictionary| it is returned as
175 vimlist or vimdictionary python type that are connected to original 176 vimlist or vimdictionary python type that are connected to original
176 list or dictionary. Thus modifications to these objects imply 177 list or dictionary. Thus modifications to these objects imply
177 modifications of the original. 178 modifications of the original.
178 179
179 Additionally, vimlist and vimdictionary type have read-write 180 Additionally, vim.List and vim.Dictionary type have read-write
180 `.locked` attribute that returns 181 `.locked` attribute that returns
181 Value Meaning ~ 182 Value Meaning ~
182 zero Variable is not locked 183 zero Variable is not locked
183 vim.VAR_LOCKED Variable is locked, but can be unlocked 184 vim.VAR_LOCKED Variable is locked, but can be unlocked
184 vim.VAR_FIXED Variable is locked and can't be unlocked 185 vim.VAR_FIXED Variable is locked and can't be unlocked
187 There is no recursive locking like |:lockvar|! does. There is also 188 There is no recursive locking like |:lockvar|! does. There is also
188 no way to lock a specific key or check whether it is locked (in any 189 no way to lock a specific key or check whether it is locked (in any
189 case these locks are ignored by anything except |:let|: |extend()| 190 case these locks are ignored by anything except |:let|: |extend()|
190 does not care, neither does python interface). 191 does not care, neither does python interface).
191 192
192 Vimdictionary type also supports `.scope` attribute which is one of 193 vim.Dictionary type also supports `.scope` attribute which is one
194 of
193 Value Meaning ~ 195 Value Meaning ~
194 zero Dictionary is not a scope one 196 zero Dictionary is not a scope one
195 vim.VAR_DEF_SCOPE Function-local or global scope dictionary 197 vim.VAR_DEF_SCOPE Function-local or global scope dictionary
196 vim.VAR_SCOPE Other scope dictionary 198 vim.VAR_SCOPE Other scope dictionary
197 199
198 2. if expression evaluates to a function reference, then it returns 200 2. if expression evaluates to a function reference, then it returns
199 callable vimfunction object. Use self keyword argument to assign 201 callable vim.Function object. Use self keyword argument to assign
200 |self| object for dictionary functions. 202 |self| object for dictionary functions.
201 203
202 Note: this function has the same behavior as |lua-eval| (except that 204 Note: this function has the same behavior as |lua-eval| (except that
203 lua does not support running vim functions), |python-eval| is 205 lua does not support running vim functions), |python-eval| is
204 kept for backwards compatibility in order not to make scripts 206 kept for backwards compatibility in order not to make scripts
205 relying on outputs of vim.eval() being a copy of original or 207 relying on outputs of vim.eval() being a copy of original or
206 vim.eval("1") returning a string. 208 vim.eval("1") returning a string.
207 209
210 You can use "List", "Dictionary" and "Function" vim module attributes
211 to test whether object has given type. These types are currently not
212 subclassable, neither they contain constructors, so you can use them
213 only for checks like `isinstance(obj, vim.List)`.
208 214
209 215
210 Error object of the "vim" module 216 Error object of the "vim" module
211 217
212 vim.error *python-error* 218 vim.error *python-error*
300 |global-local| options and global only options, but does for window- 306 |global-local| options and global only options, but does for window-
301 and buffer-local ones). Use |python-buffer| objects to access to 307 and buffer-local ones). Use |python-buffer| objects to access to
302 buffer-local options and |python-window| objects to access to 308 buffer-local options and |python-window| objects to access to
303 window-local options. 309 window-local options.
304 310
311 Type of this object is available via "Options" attribute of vim
312 module.
313
305 Output from Python *python-output* 314 Output from Python *python-output*
306 Vim displays all Python code output in the Vim message area. Normal 315 Vim displays all Python code output in the Vim message area. Normal
307 output appears as information messages, and error output appears as 316 output appears as information messages, and error output appears as
308 error messages. 317 error messages.
309 318
368 numbers s and e |inclusive|. 377 numbers s and e |inclusive|.
369 378
370 Note that when adding a line it must not contain a line break character '\n'. 379 Note that when adding a line it must not contain a line break character '\n'.
371 A trailing '\n' is allowed and ignored, so that you can do: > 380 A trailing '\n' is allowed and ignored, so that you can do: >
372 :py b.append(f.readlines()) 381 :py b.append(f.readlines())
382
383 Buffer object type is available using "Buffer" attribute of vim module.
373 384
374 Examples (assume b is the current buffer) > 385 Examples (assume b is the current buffer) >
375 :py print b.name # write the buffer file name 386 :py print b.name # write the buffer file name
376 :py b[0] = "hello!!!" # replace the top line 387 :py b[0] = "hello!!!" # replace the top line
377 :py b[:] = None # delete the whole buffer 388 :py b[:] = None # delete the whole buffer
409 r.append(list) Append a list of lines to the range 420 r.append(list) Append a list of lines to the range
410 Note that the option of supplying a list of strings to 421 Note that the option of supplying a list of strings to
411 the append method differs from the equivalent method 422 the append method differs from the equivalent method
412 for Python's built-in list objects. 423 for Python's built-in list objects.
413 r.append(list, nr) Idem, after line "nr" 424 r.append(list, nr) Idem, after line "nr"
425
426 Range object type is available using "Range" attribute of vim module.
414 427
415 Example (assume r is the current range): 428 Example (assume r is the current range):
416 # Send all lines in a range to the default printer 429 # Send all lines in a range to the default printer
417 vim.command("%d,%dhardcopy!" % (r.start+1,r.end+1)) 430 vim.command("%d,%dhardcopy!" % (r.start+1,r.end+1))
418 431
454 tabpage (read-only) Window tab page. 467 tabpage (read-only) Window tab page.
455 468
456 The height attribute is writable only if the screen is split horizontally. 469 The height attribute is writable only if the screen is split horizontally.
457 The width attribute is writable only if the screen is split vertically. 470 The width attribute is writable only if the screen is split vertically.
458 471
472 Window object type is available using "Window" attribute of vim module.
473
459 ============================================================================== 474 ==============================================================================
460 6. Tab page objects *python-tabpage* 475 6. Tab page objects *python-tabpage*
461 476
462 Tab page objects represent vim tab pages. You can obtain them in a number of 477 Tab page objects represent vim tab pages. You can obtain them in a number of
463 ways: 478 ways:
472 |tabpagenr()|. 487 |tabpagenr()|.
473 windows Like |python-windows|, but for current tab page. 488 windows Like |python-windows|, but for current tab page.
474 vars The tab page |t:| variables. 489 vars The tab page |t:| variables.
475 window Current tabpage window. 490 window Current tabpage window.
476 491
477 ============================================================================== 492 TabPage object type is available using "TabPage" attribute of vim module.
478 6. pyeval() and py3eval() Vim functions *python-pyeval* 493
494 ==============================================================================
495 7. pyeval() and py3eval() Vim functions *python-pyeval*
479 496
480 To facilitate bi-directional interface, you can use |pyeval()| and |py3eval()| 497 To facilitate bi-directional interface, you can use |pyeval()| and |py3eval()|
481 functions to evaluate Python expressions and pass their values to VimL. 498 functions to evaluate Python expressions and pass their values to VimL.
482 499
483 ============================================================================== 500 ==============================================================================
484 7. Dynamic loading *python-dynamic* 501 8. Dynamic loading *python-dynamic*
485 502
486 On MS-Windows the Python library can be loaded dynamically. The |:version| 503 On MS-Windows the Python library can be loaded dynamically. The |:version|
487 output then includes |+python/dyn|. 504 output then includes |+python/dyn|.
488 505
489 This means that Vim will search for the Python DLL file only when needed. 506 This means that Vim will search for the Python DLL file only when needed.
496 The name of the DLL must match the Python version Vim was compiled with. 513 The name of the DLL must match the Python version Vim was compiled with.
497 Currently the name is "python24.dll". That is for Python 2.4. To know for 514 Currently the name is "python24.dll". That is for Python 2.4. To know for
498 sure edit "gvim.exe" and search for "python\d*.dll\c". 515 sure edit "gvim.exe" and search for "python\d*.dll\c".
499 516
500 ============================================================================== 517 ==============================================================================
501 8. Python 3 *python3* 518 9. Python 3 *python3*
502 519
503 *:py3* *:python3* 520 *:py3* *:python3*
504 The `:py3` and `:python3` commands work similar to `:python`. A simple check 521 The `:py3` and `:python3` commands work similar to `:python`. A simple check
505 if the `:py3` command is working: > 522 if the `:py3` command is working: >
506 :py3 print("Hello") 523 :py3 print("Hello")