if_pyth.cnx

Vim 中文文档

*if_pyth.txt*   For Vim version 6.3.  最近更新：2004年6月


		  VIM REFERENCE MANUAL    by Paul Moore
		  (译者：lang2 http://vimcdoc.sf.net)


Vim 的 Python 编程界面					*python* *Python*

1. 命令				|python-commands|
2. vim 模块			|python-vim|
3. 缓冲对象			|python-buffer|
4. 范围对象			|python-range|
5. 窗口对象			|python-window|

{Vi does not have any of these commands}

Vim 的 Python 界面仅当 |+python| 特性被编译进 Vim 时才有效。

==============================================================================
1. 命令							*python-commands*

					*:python* *:py* *E205* *E263* *E264*
:[range]py[thon] {stmt}
			执行 Python 语句 {stmt}.

:[range]py[thon] << {endmarker}
{script}
{endmarker}
			执行 Python 脚本 {script}.
			Note: 此命令在没有编译进 Python 特性时无效。为了
			避免这样的错误，参阅 |script-here|.

{endmarker} 前面 不能 有任何空白字符。如果在 "<<" 之后省略了 {endmarker}，
在 {script} 之后一定要有一个点 '.'。这和 |:append| 及 |:insert| 命令的道理是
一样的。这种形成的 |:python| 命令主要用于在 Vim 脚本中嵌入 Python 代码。

例子: >
	function! IcecreamInitialize()
	python << EOF
	class StrawberryIcecream:
		def __call__(self):
			print 'EAT ME'
	EOF
	endfunction
<
Note: Python 对于缩进是非常敏感的。要确保 "class" 所在行及 "EOF" 没有任何缩进。

							*:pyfile* *:pyf*
:[range]pyf[ile] {file}	
			执行 {file} 文件中包含的 Python 脚本。整个
			参数被用作一个文件名。 {not in Vi}

这些命令根本上都差不多 － 它们都将当前范围 |python-range| 设定为指定的行范围，
并对其执行 Python 代码。

:python 的情况所执行的代码来自命令行。
:pyfile 的情况所执行的代码来自一个指定的文件。

Python 命令不能用于 |sandbox|。

需要传递参数的话，你得使用 sys.argv[]。例如： >

	:python import sys
	:python sys.argv = ["foo", "bar"]
	:pyfile myscript.py

下面是一些例子						*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 如同导入 (import) 模块一样，变动对后续命令持续有效。这和 Python 的解释
程序是一样的。)

==============================================================================
2. vim 模块						*python-vim*

Python 的代码所有对 Vim 的操作 (只有一个例外 － 看下面的 |python-output|) 都是
通过 "vim" 模块来进行的。该模块包括两个方法，三个常量，以及一个异常对象。在使用
它们之前你得先导入 (import) vim 模块。

总揽 >
	print "Hello"			# 显示信息
	vim.command(cmd)		# 执行 ex 命令
	w = vim.windows[n]		# 获取窗口 "n"
	cw = vim.current.window		# 获取当前窗口
	b = vim.buffers[n]		# 获取缓冲 "n"
	cb = vim.current.buffer		# 获取当前缓冲
	w.height = lines		# 设定窗口高度
	w.cursor = (row, col)		# 设定光标位置
	pos = w.cursor			# 获取 tuple (行, 列)
	name = b.name			# 获取缓冲的文件名
	line = b[n]			# 获取缓冲内的一行
	lines = b[n:m]			# 获取数行
	num = len(b)			# 获取统计的行数
	b[n] = str			# sets a line in the buffer
	b[n:m] = [str1, str2, str3]	# sets a number of lines at once
	del b[n]			# 删除一行
	del b[n:m]			# 删除数行

"vim" 模块中的方法

vim.command(str)					*python-command*
	执行 vim (ex-模式) 命令 str. 无返回值.
	例如: >
		vim.command("set tw=72")
		vim.command("%s/aaa/bbb/g")
<	下面的定义可以执行普通模式命令: >
		def normal(str):
			vim.command("normal "+str)
		# Note the use of single quotes to delimit a string containing
		# double quotes
		normal('"a2dd"aP')
<
<								*E659*
	":python" 在 Python 2.2 及之前版本上不能嵌套使用。下面命令只对
	Python 2.3 之后版本适用: >
		:python vim.command("python print 'Hello again Python'")


vim.eval(str)						*python-eval*
	使用 vim 内部的表达式处理器来对表达式 str 求值。(参阅 |expression|).
	返回结果的字符串。
	例: >
		text_width = vim.eval("&tw")
		str = vim.eval("12+12")		# NB result is a string! Use
						# string.atoi() to convert to
						# a number.

"vim" 模块中的异常对象
	vim.error					*python-error*
	当遇到 Vim 的错误时，Python 引起一个 vim.error 类的异常。
	例: >
		try:
			vim.command("put a")
		except vim.error:
			# nothing in register a

"vim" 模块中的常量
	Note 这些其实并非真正的常量 － 你还是可以对它们符值。但这好无意义，因为
	你会丢失该 vim 对象本来代表的值。

vim.buffers						*python-buffers*
	A sequence 对象，用来提供对 vim 缓冲的操作。该对象支持以下操作: >
		b = vim.buffers[i]	# Indexing (read-only)
		b in vim.buffers	# 成员测试
		n = len(vim.buffers)	# 成员个数
		for b in vim.buffers:	# 顺序存取
<
vim.windows						*python-windows*
	A sequence 对象，用来提供对 vim 窗口的操作。该对象支持以下操作: >
		w = vim.windows[i]	# Indexing (read-only)
		w in vim.windows	# 成员测试
		n = len(vim.windows)	# 成员个数
		for w in vim.windows:	# 顺序存取
<
vim.current						*python-current*
	一个用来提供对各种各样当前 "current" 对象进行操作的对象。它包括一些特定
	的属性:
		vim.current.line	当前行(读写)			字串
		vim.current.buffer	当前缓冲(只读)			缓冲
		vim.current.window	当前窗口(只读)			窗口
		vim.current.range	当前行范围(只读)		范围

	最后一种情况需要一些额外的解释。当用 :python 或 :pyfile 命令指定一个
	范围之后，该范围将成为 "当前范围"。一个范围就如同一个缓冲，只不过所
	操作的对象界限于一个行的子集。请参阅 |python-range|。


Python 的输出						*python-output*
	Vim 将所有 Python 代码的输出都显示在信息区。普通的输出会以一般信息
	出现,错误会以出错信息出现.

	用具体实现的属于来讲,这表示所有 sys.stdout (包括 print 语句的输出)
	以一般信息形式出现，而所有 sys.stderr (包括 error tracebacks) 都会
	被显示成出错信息。

							*python-input*
	Vim 并不支持用 Python 来输入 (通过 sys.stdin, 包括 input() 和
	raw_input())。这些调用可能会导致崩溃。可能以后会修正。

==============================================================================
3. 缓冲对象						*python-buffer*

缓冲对象代表缓冲。你又一下这几种办法来获取缓冲的列表:
	- 通过 vim.current.buffer (|python-current|)
	- from indexing vim.buffers (|python-buffers|)
	- 通过一个窗口的 "buffer" 属性 (|python-window|)

缓冲对象只有一个属性 -- 缓冲的文件全名。该对象还包括三个方法 (append, mark,
及 range; 见下)。

你也可以将缓冲对象视为顺序对象。这样的话，它们就可以被像一个字符串序列一样
取存 (它们是可变的)。每一个元素是缓冲中的一行。所有的顺序存取操作，包括索引
索引赋值，切片及切片赋值，等等，都可以被使用。Note 索引(切片)操作的结果是一
个字符串(字符串序列)。这产生了一个意想不到的结果 - b[:] 和 b 是不同的。确切
一些，"b[:] = None" 会清空整个缓冲，而 "b = None" 仅仅更新变量 b 的值，完全
不会影响到缓冲。

缓冲索引从 0 开始算起，这与通常的 Python 语法一致。但这和 Vim 的行号从 1 算
起有分歧。这一点在处理标记 (见下) 是要特别留意，因为标记是以行号区分的。

缓冲对象的方法有:
	b.append(str)	对缓冲附加一行
	b.append(list)	对缓冲附加一系列行
			Note append 方法可以带一个字符串序列作为参数，这和
			Python 中对应的方法是不同的。
	b.mark(name)	返回一个 tuple (行,列) 用来代表该位置上的一个有名的
			标记 (也可以用于 []"<> 等标记)
	b.range(s,e)	返回一个范围对象 (参见 |python-range|) 用来代表指定
			缓冲中行 s 与 行 e 之间的部分 (包含 s 和 e |inclusive|).

例如 (假定 b 是当前缓冲) >
	print b.name		# 输出缓冲的名字
	b[0] = "hello!!!"	# 替换最顶上的一行
	b[:] = None		# 删除整个缓冲
	del b[:]		# 删除整个缓冲 (同上)
	b[0:0] = [ "a line" ]	# 在第一行前添加一行
	del b[2]		# 删除一行 (第三行)
	b.append("bottom")	# 在缓冲结尾添加一行
	n = len(b)		# 总行数
	(row,col) = b.mark('a') # 有名的标记
	r = b.range(1,5)	# 缓冲内的一个范围

==============================================================================
4. 范围对象						*python-range*

范围对象代表一个 vim 缓冲内的一个部分。你可以用一下的方法之一来获取一个缓冲
对象:
	- 通过 vim.current.range (|python-current|)
	- 通过一个缓冲的 range() 方法 (|python-buffer|)

一个范围对象在操作上几乎合一个缓冲对象完全一样。不过，其操作的目标仅显于范围
指定的行 (当然，这个行范围会随着切片赋值，行删除，或者 range.append() 等等操作而
改变).

范围对象的属性有:
	r.start		首行在缓冲内的索引
	r.end		尾行在缓冲内的索引

==============================================================================
5. 窗口对象						*python-window*

窗口对象代表一个 vim 窗口。你可以用一下几种方法来获取一个窗口对象:
	- 通过 vim.current.window (|python-current|)
	- 通过对 vim.windows 的索引操作 (|python-windows|)

你只能通过窗口对象的属性来控制它。这些对象没有方法，也没有序列等其它界面。

窗口的属性包括:
	buffer (只读)		窗口中显示的缓冲
	cursor (读写)		窗口中的当前光标位置
				这是一个 tuple, (行,列).
	height (读写)		行数表示的窗口高度
	width (读写)		列数表示的窗口宽度
height 属性只有当屏幕被水平分割时才可写。
width  属性只有当屏幕被垂直分割时才可写。

==============================================================================
 vim:tw=78:ts=8:ft=help:norl: