annotate runtime/doc/if_pyth.txt @ 2154:7c8c7c95a865 vim73

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