| *if_pyth.txt* For Vim version 7.0. Last change: 2006 Apr 30 |
| |
| |
| VIM REFERENCE MANUAL by Paul Moore |
| |
| |
| The Python Interface to Vim *python* *Python* |
| |
| 1. Commands |python-commands| |
| 2. The vim module |python-vim| |
| 3. Buffer objects |python-buffer| |
| 4. Range objects |python-range| |
| 5. Window objects |python-window| |
| 6. Dynamic loading |python-dynamic| |
| |
| {Vi does not have any of these commands} |
| |
| The Python interface is available only when Vim was compiled with the |
| |+python| feature. |
| |
| ============================================================================== |
| 1. Commands *python-commands* |
| |
| *:python* *:py* *E205* *E263* *E264* |
| :[range]py[thon] {stmt} |
| Execute Python statement {stmt}. |
| |
| :[range]py[thon] << {endmarker} |
| {script} |
| {endmarker} |
| Execute Python script {script}. |
| Note: This command doesn't work when the Python |
| feature wasn't compiled in. To avoid errors, see |
| |script-here|. |
| |
| {endmarker} must NOT be preceded by any white space. If {endmarker} is |
| omitted from after the "<<", a dot '.' must be used after {script}, like |
| for the |:append| and |:insert| commands. |
| This form of the |:python| command is mainly useful for including python code |
| in Vim scripts. |
| |
| Example: > |
| function! IcecreamInitialize() |
| python << EOF |
| class StrawberryIcecream: |
| def __call__(self): |
| print 'EAT ME' |
| EOF |
| endfunction |
| < |
| Note: Python is very sensitive to the indenting. Also make sure the "class" |
| line and "EOF" do not have any indent. |
| |
| *:pyfile* *:pyf* |
| :[range]pyf[ile] {file} |
| Execute the Python script in {file}. The whole |
| argument is used as a single file name. {not in Vi} |
| |
| Both of these commands do essentially the same thing - they execute a piece of |
| Python code, with the "current range" |python-range| set to the given line |
| range. |
| |
| In the case of :python, the code to execute is in the command-line. |
| In the case of :pyfile, the code to execute is the contents of the given file. |
| |
| Python commands cannot be used in the |sandbox|. |
| |
| To pass arguments you need to set sys.argv[] explicitly. Example: > |
| |
| :python import sys |
| :python sys.argv = ["foo", "bar"] |
| :pyfile myscript.py |
| |
| Here are some examples *python-examples* > |
| |
| :python from vim import * |
| :python from string import upper |
| :python current.line = upper(current.line) |
| :python print "Hello" |
| :python str = current.buffer[42] |
| |
| (Note that changes - like the imports - persist from one command to the next, |
| just like in the Python interpreter.) |
| |
| ============================================================================== |
| 2. The vim module *python-vim* |
| |
| Python code gets all of its access to vim (with one exception - see |
| |python-output| below) via the "vim" module. The vim module implements two |
| methods, three constants, and one error object. You need to import the vim |
| module before using it: > |
| :python import vim |
| |
| Overview > |
| :py print "Hello" # displays a message |
| :py vim.command(cmd) # execute an ex command |
| :py w = vim.windows[n] # gets window "n" |
| :py cw = vim.current.window # gets the current window |
| :py b = vim.buffers[n] # gets buffer "n" |
| :py cb = vim.current.buffer # gets the current buffer |
| :py w.height = lines # sets the window height |
| :py w.cursor = (row, col) # sets the window cursor position |
| :py pos = w.cursor # gets a tuple (row, col) |
| :py name = b.name # gets the buffer file name |
| :py line = b[n] # gets a line from the buffer |
| :py lines = b[n:m] # gets a list of lines |
| :py num = len(b) # gets the number of lines |
| :py b[n] = str # sets a line in the buffer |
| :py b[n:m] = [str1, str2, str3] # sets a number of lines at once |
| :py del b[n] # deletes a line |
| :py del b[n:m] # deletes a number of lines |
| |
| |
| Methods of the "vim" module |
| |
| vim.command(str) *python-command* |
| Executes the vim (ex-mode) command str. Returns None. |
| Examples: > |
| :py vim.command("set tw=72") |
| :py vim.command("%s/aaa/bbb/g") |
| < The following definition executes Normal mode commands: > |
| def normal(str): |
| vim.command("normal "+str) |
| # Note the use of single quotes to delimit a string containing |
| # double quotes |
| normal('"a2dd"aP') |
| < *E659* |
| The ":python" command cannot be used recursively with Python 2.2 and |
| older. This only works with Python 2.3 and later: > |
| :py vim.command("python print 'Hello again Python'") |
| |
| vim.eval(str) *python-eval* |
| Evaluates the expression str using the vim internal expression |
| evaluator (see |expression|). Returns the expression result as: |
| - a string if the Vim expression evaluates to a string or number |
| - a list if the Vim expression evaluates to a Vim list |
| - a dictionary if the Vim expression evaluates to a Vim dictionary |
| Dictionaries and lists are recursively expanded. |
| Examples: > |
| :py text_width = vim.eval("&tw") |
| :py str = vim.eval("12+12") # NB result is a string! Use |
| # string.atoi() to convert to |
| # a number. |
| |
| :py tagList = vim.eval('taglist("eval_expr")') |
| < The latter will return a python list of python dicts, for instance: |
| [{'cmd': '/^eval_expr(arg, nextcmd)$/', 'static': 0, 'name': |
| 'eval_expr', 'kind': 'f', 'filename': './src/eval.c'}] |
| |
| |
| |
| Error object of the "vim" module |
| |
| vim.error *python-error* |
| Upon encountering a Vim error, Python raises an exception of type |
| vim.error. |
| Example: > |
| try: |
| vim.command("put a") |
| except vim.error: |
| # nothing in register a |
| |
| Constants of the "vim" module |
| |
| Note that these are not actually constants - you could reassign them. |
| But this is silly, as you would then lose access to the vim objects |
| to which the variables referred. |
| |
| vim.buffers *python-buffers* |
| A sequence object providing access to the list of vim buffers. The |
| object supports the following operations: > |
| :py b = vim.buffers[i] # Indexing (read-only) |
| :py b in vim.buffers # Membership test |
| :py n = len(vim.buffers) # Number of elements |
| :py for b in vim.buffers: # Sequential access |
| < |
| vim.windows *python-windows* |
| A sequence object providing access to the list of vim windows. The |
| object supports the following operations: > |
| :py w = vim.windows[i] # Indexing (read-only) |
| :py w in vim.windows # Membership test |
| :py n = len(vim.windows) # Number of elements |
| :py for w in vim.windows: # Sequential access |
| < |
| vim.current *python-current* |
| An object providing access (via specific attributes) to various |
| "current" objects available in vim: |
| vim.current.line The current line (RW) String |
| vim.current.buffer The current buffer (RO) Buffer |
| vim.current.window The current window (RO) Window |
| vim.current.range The current line range (RO) Range |
| |
| The last case deserves a little explanation. When the :python or |
| :pyfile command specifies a range, this range of lines becomes the |
| "current range". A range is a bit like a buffer, but with all access |
| restricted to a subset of lines. See |python-range| for more details. |
| |
| |
| Output from Python *python-output* |
| Vim displays all Python code output in the Vim message area. Normal |
| output appears as information messages, and error output appears as |
| error messages. |
| |
| In implementation terms, this means that all output to sys.stdout |
| (including the output from print statements) appears as information |
| messages, and all output to sys.stderr (including error tracebacks) |
| appears as error messages. |
| |
| *python-input* |
| Input (via sys.stdin, including input() and raw_input()) is not |
| supported, and may cause the program to crash. This should probably be |
| fixed. |
| |
| ============================================================================== |
| 3. Buffer objects *python-buffer* |
| |
| Buffer objects represent vim buffers. You can obtain them in a number of ways: |
| - via vim.current.buffer (|python-current|) |
| - from indexing vim.buffers (|python-buffers|) |
| - from the "buffer" attribute of a window (|python-window|) |
| |
| Buffer objects have one read-only attribute - name - the full file name for |
| the buffer. They also have three methods (append, mark, and range; see below). |
| |
| You can also treat buffer objects as sequence objects. In this context, they |
| act as if they were lists (yes, they are mutable) of strings, with each |
| element being a line of the buffer. All of the usual sequence operations, |
| including indexing, index assignment, slicing and slice assignment, work as |
| you would expect. Note that the result of indexing (slicing) a buffer is a |
| string (list of strings). This has one unusual consequence - b[:] is different |
| from b. In particular, "b[:] = None" deletes the whole of the buffer, whereas |
| "b = None" merely updates the variable b, with no effect on the buffer. |
| |
| Buffer indexes start at zero, as is normal in Python. This differs from vim |
| line numbers, which start from 1. This is particularly relevant when dealing |
| with marks (see below) which use vim line numbers. |
| |
| The buffer object methods are: |
| b.append(str) Append a line to the buffer |
| b.append(list) Append a list of lines to the buffer |
| Note that the option of supplying a list of strings to |
| the append method differs from the equivalent method |
| for Python's built-in list objects. |
| b.mark(name) Return a tuple (row,col) representing the position |
| of the named mark (can also get the []"<> marks) |
| b.range(s,e) Return a range object (see |python-range|) which |
| represents the part of the given buffer between line |
| numbers s and e |inclusive|. |
| |
| Note that when adding a line it must not contain a line break character '\n'. |
| A trailing '\n' is allowed and ignored, so that you can do: > |
| :py b.append(f.readlines()) |
| |
| Examples (assume b is the current buffer) > |
| :py print b.name # write the buffer file name |
| :py b[0] = "hello!!!" # replace the top line |
| :py b[:] = None # delete the whole buffer |
| :py del b[:] # delete the whole buffer |
| :py b[0:0] = [ "a line" ] # add a line at the top |
| :py del b[2] # delete a line (the third) |
| :py b.append("bottom") # add a line at the bottom |
| :py n = len(b) # number of lines |
| :py (row,col) = b.mark('a') # named mark |
| :py r = b.range(1,5) # a sub-range of the buffer |
| |
| ============================================================================== |
| 4. Range objects *python-range* |
| |
| Range objects represent a part of a vim buffer. You can obtain them in a |
| number of ways: |
| - via vim.current.range (|python-current|) |
| - from a buffer's range() method (|python-buffer|) |
| |
| A range object is almost identical in operation to a buffer object. However, |
| all operations are restricted to the lines within the range (this line range |
| can, of course, change as a result of slice assignments, line deletions, or |
| the range.append() method). |
| |
| The range object attributes are: |
| r.start Index of first line into the buffer |
| r.end Index of last line into the buffer |
| |
| The range object methods are: |
| r.append(str) Append a line to the range |
| r.append(list) Append a list of lines to the range |
| Note that the option of supplying a list of strings to |
| the append method differs from the equivalent method |
| for Python's built-in list objects. |
| |
| Example (assume r is the current range): |
| # Send all lines in a range to the default printer |
| vim.command("%d,%dhardcopy!" % (r.start+1,r.end+1)) |
| |
| ============================================================================== |
| 5. Window objects *python-window* |
| |
| Window objects represent vim windows. You can obtain them in a number of ways: |
| - via vim.current.window (|python-current|) |
| - from indexing vim.windows (|python-windows|) |
| |
| You can manipulate window objects only through their attributes. They have no |
| methods, and no sequence or other interface. |
| |
| Window attributes are: |
| buffer (read-only) The buffer displayed in this window |
| cursor (read-write) The current cursor position in the window |
| This is a tuple, (row,col). |
| height (read-write) The window height, in rows |
| width (read-write) The window width, in columns |
| The height attribute is writable only if the screen is split horizontally. |
| The width attribute is writable only if the screen is split vertically. |
| |
| ============================================================================== |
| 6. Dynamic loading *python-dynamic* |
| |
| On MS-Windows the Python library can be loaded dynamically. The |:version| |
| output then includes |+python/dyn|. |
| |
| This means that Vim will search for the Python DLL file only when needed. |
| When you don't use the Python interface you don't need it, thus you can use |
| Vim without this DLL file. |
| |
| To use the Python interface the Python DLL must be in your search path. In a |
| console window type "path" to see what directories are used. |
| |
| The name of the DLL must match the Python version Vim was compiled with. |
| Currently the name is "python24.dll". That is for Python 2.4. To know for |
| sure edit "gvim.exe" and search for "python\d*.dll\c". |
| |
| ============================================================================== |
| vim:tw=78:ts=8:ft=help:norl: |