*if_python.txt* For Vim version 5.0f.  Last modification: 1997 Apr 7

		  VIM REFERENCE MANUAL    by Bram Moolenaar


COMPILING VIM WITH THE PYTHON INTERFACE		*python-compiling*

To compile Vim with the Python interface, you need Python 1.4 or later. (It is
possible that an earlier version will work, but this has not been tested).

The Python interface has only been built and tested on Windows 95, to date.

The Python patches for Vim were made by Paul Moore
<gustav@morpheus.demon.co.uk>

INSTALLATION NOTES

A binary distribution is only available for Windows 95/NT. The source
distribution includes build procedures (a makefile) for Windows 95/NT, but
should also work on Unix and other platforms, if you roll your own build
procedures. Anyone willing to volounteer to integrate this lot with Unix
autoconf?

To build under Win32, use the command line
    nmake /s/f makefile.w32 "PYTHON_BASE=<python source dist root>"

Under Win32, Vim needs to be able to find the Python DLL, PYTHON14.DLL. If you
have a standard Python distribution installed, this should be stored in your
WINDOWS\SYSTEM directory.

It is also useful to have the Python library available (this is also part of a
standard Python distribution).

To get Python, check out http://www.python.org/
To get Vim 5.0, check out ftp://ftp.oce.nl/pub/misc/vim/beta-test


USING PYTHON IN VIM					*python-using*

							*:python* *:py*
:py[thon] {stmt}	Execute Python statement {stmt}.  {not in Vi}

							*:pyfile* *:pyf*
:pyf[ile] {file}	Execute the Python script in {file}.  {not in Vi}

							*:pysubst* *:pys*
:[range]pys[ubst] {stmt}
			Execute the Python statement {stmt} for each line
			in the [range] (default the current line). The line
			being processed is available in the Python global
			variable "line", and the value of "line" after the
			statement is complete replaces the existing line (if
			"line" is None, the existing line is deleted).
			{not in Vi}

Here are some examples

:python import string
:%pysubst line = string.upper(line)
:python print "Hello"
:python import vim
:python str = vim.buffers.current[42]

(Note that changes - like the imports - persist from one command to the next,
just like in the Python interpreter).

More examples of :pysubst

:pys line = string.upper(line)		# An ":upper" command
:pys line = None			# The equivalent of ":delete"

The :pysubst command is undo-able as a single operation.

ACCESS TO VIM FROM PYTHON CODE

							*python-overview*
Here is an overview (assuming you have imported the "vim" module)

python print "Hello"			# displays a message
python vim.command(cmd)			# execute an ex command
python w = vim.windows[n]		# gets window "n"
python cw = vim.windows.current		# gets the current window
python b = vim.buffers[n]		# gets buffer "n"
python cb = vim.buffers.current		# gets the current buffer
python w.height = lines			# sets the window height
python w.cursor = (row, col)		# sets the window cursor position
python pos = w.cursor			# gets a tuple (row, col)
python name = b.name			# gets the buffer filename
python line = b[n]			# gets a line from the buffer
python lines = b[n:m]			# gets a list of lines
python num = len(b)			# gets the number of lines
python b[n] = str			# sets a line in the buffer
python b[n:m] = [str1, str2, str3]	# sets a number of lines at once
python del b[n]				# deletes a line
python del b[n:m]			# deletes a number of lines

							*python-IO*
OUTPUT FROM PYTHON

print {msg}		Displays the message {msg}.
sys.stdout.write({msg})	Same as print.
sys.stderr.write({msg})	Displays the error message {msg}.

The system output files sys.stdout and sys.stderr write to the vim message
line (as information and error messages, respectively). In particular, this
means that the Python "print" statement displays a message in the vim message
area, and Python error reports are displayed there.


							*python-vim*
THE VIM MODULE

vim.error
	An error string, raised on any vim-related problem.

vim.command(cmd)
	Execute the ex command "cmd" in vim.

vim.buffers
	The list of vim buffers - see below. |python-buffers|

vim.windows
	The list of vim windows - see below. |python-windows|

vim.register
	Vim's registers - see below. |python-registers|

							*python-buffers*
The module variable vim.buffers is a list of all of vim's buffers. You can use
it just like a built-in (immutable) list:

    b = vim.buffers[i]
    l = len(vim.buffers)
    for b in vim.buffers:

Furthermore, vim.buffers.current gives the current buffer.

See |python-types| for details of objects of type BUFFER.

							*python-windows*
The module variable vim.windows is the equivalent of vim.buffers, but for
windows. So you have

   w = vim.windows[i]
   l = len(vim.windows)
   for w in vim.windows:
   w = vim.windows.current

See |python-types| for details of objects of type WINDOW.

							*python-types*
WINDOW AND BUFFER TYPES

A variable which is a window has a number of attributes

    w.buffer (read-only) = the buffer currently displayed in the window
    w.cursor (read-write) = the cursor position as a tuple (line, col)
    w.height (read-write) = the window height in lines

Note that the line and column numbers in a cursor position start from 1,
as is normal for vim.

A variable which is a buffer has just one read-only attribute, the buffer file
name b.name. However, it also has two methods

    b.mark('a') = the mark position as a tuple (line, col) (None if not set)
    b.append(str) = append the string "str" to the end of the buffer

Furthermore, a buffer appears as a list of its lines. Thus, you can do all of
the standard list operations on a buffer (but not list METHODS, such as
sort(), except for append() mentioned above). So you can have

    len(b)        : number of lines in b
    b[i]          : contents of line i (NB this is 0-based as is normal in
                    Python, rather than a 1-based line number!)
    b[i:j]        : a list containing lines i-j
    b[i] = str    : set buffer line i to str
    b[i:j] = list : set lines i-j to the list of strings
    del b[i]      : remove line i
    del b[i:j]    : remove lines i-j
    for str in b  : iterate through the lines in a buffer
    str in b      : look for a particular line in a buffer (could be slow!)

All operations which change the buffer are undo-able.

							*python-registers*
REGISTERS

[NB: This interface is under review!!!]

Vim's registers (yank buffers) are available in Python as the dictionary-like
object vim.registers. The normal features are available

	vim.registers['a']		# get the contents of a register
	vim.registers['a'] = str	# set the contents of a register
	vim.registers.keys()		# list of all registers which are set
	vim.registers.values()		# list of all register values
	vim.registers.items()		# list of register (name, value) pairs
	vim.registers.has_key(r)	# is this register set?
	len(vim.registers)		# number of registers which are set

The contents of a register is always a (possibly multi-line) string. A
linewise or blockwise register ends in a newline ('\n') but a characterwise
register does not.

When a register is set, it is set as linewise if the string contains a
newline, otherwise it is set as characterwise.

 vim:tw=78:ts=8:sw=8: