IF_PYTH

*if_pyth.txt*   For Vim version 7.0.  最近更新：2006年4月


                  VIM REFERENCE MANUAL    by Paul Moore
                  译者: lang2, Willis http://vimcdoc.sf.net


Vim 的 Python 编程接口                                  *python* *Python*

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

{Vi 无此功能}

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}.
                        备注: 此命令在没有编译进 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

备注: 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]

(注意 如同导入 (import) 模块一样，变动对后续命令持续有效。这和 Python 的解释
程序是一样的。)

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

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

"vim" 模块中的方法

vim.command(str)                                        *python-command*
        执行 vim (ex-模式) 命令 str。无返回值。
        例如:
                :py vim.command("set tw=72")
                :py vim.command("%s/aaa/bbb/g")
        下面的定义可以执行普通模式命令:
                def normal(str):
                        vim.command("normal "+str)
                # 注意使用单引号标识出含有双引号的字符串
                normal('"a2dd"aP')
                                                                *E659*
        ":python" 在 Python 2.2 及之前版本上不能嵌套使用。下面命令只对
        Python 2.3 之后版本适用:
                :py vim.command("python print 'Hello again Python'")


vim.eval(str)                                           *python-eval*
        使用 vim 内部的表达式处理器来对表达式 str 求值。(参阅 |expression|)。
        返回表达式的结果：
        -如果 Vim 表达式计算结果是字符串或者数字，那么返回一个字符串。
        -如果 Vim 表达式计算结果是 Vim 列表，那么返回一个列表
        -如果 Vim 表达式计算结果是 Vim 字典，那么返回一个字典
        例:
            :py text_width = vim.eval("&tw")
            :py str = vim.eval("12+12")         # 注意：结果是个字符串！
                                                # 使用 string.atoi()
                                                # 把它转换成数字

            :py tagList = vim.eval('taglist("eval_expr")')
        后一个将返回一个 python 类型的字典列表，例如：
        [{'cmd': '/^eval_expr(arg, nextcmd)$/', 'static': 0, 'name':
        'eval_expr', 'kind': 'f', 'filename': './src/eval.c'}]



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

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

vim.buffers                                             *python-buffers*
        一个序列对象，用来提供对 vim 缓冲的操作。该对象支持以下操作:
            :py b = vim.buffers[i]      # Indexing (read-only)
            :py b in vim.buffers        # 成员测试
            :py n = len(vim.buffers)    # 成员个数
            :py for b in vim.buffers:   # 顺序存取

vim.windows                                             *python-windows*
        一个序列对象，用来提供对 vim 窗口的操作。该对象支持以下操作:
            :py w = vim.windows[i]      # Indexing (read-only)
            :py w in vim.windows        # 成员测试
            :py n = len(vim.windows)    # 成员个数
            :py 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|)
        - 通过 vim.buffers 的索引访问 (|python-buffers|)
        - 通过一个窗口的 "buffer" 属性 (|python-window|)

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

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

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

缓冲对象的方法有:
        b.append(str)   对缓冲附加一行
        b.append(list)  对缓冲附加一系列行
                        备注: append 方法可以带一个字符串序列作为参数，这和
                        Python 中对应的方法是不同的。
        b.mark(name)    返回一个 tuple (行,列) 用来代表该位置上的一个有名的
                        标记 (也可以用于 []"<> 等标记)
        b.range(s,e)    返回一个范围对象 (参见 |python-range|) 用来代表指定
                        缓冲中行 s 与 行 e 之间的部分 (包含 s 和 e
                        |inclusive|).
注意：当增加一行的时候，这一行里一定不要含有换行符 '\n'。行尾的 '\n' 可以，
但会被忽略，所以下面的操作是可以的：
        :py b.append(f.readlines())

例如 (假定 b 是当前缓冲)
        :py print b.name                # 输出缓冲的名字
        :py b[0] = "hello!!!"           # 替换最顶上的一行
        :py b[:] = None                 # 删除整个缓冲
        :py del b[:]                    # 删除整个缓冲
        :py b[0:0] = [ "a line" ]       # 在第一行前添加一行
        :py del b[2]                    # 删除一行 (第三行)
        :py b.append("bottom")          # 在缓冲结尾添加一行
        :py n = len(b)                  # 总行数
        :py (row,col) = b.mark('a')     # 命名标记
        :py 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  属性只有当屏幕被垂直分割时才可写。

6. 动态调入                                             *python-dynamic*
MS-Windows 上，可以动态调入 Python 库。|:version| 输出这时应包括
|+python/dyn|。

这意味着 Vim 只有在必要时才寻找 Python DLL 文件。如果不使用 Python 接口，你就
不需要它。这样，即使没有该 DLL 文件，你也可使用 Vim。

要使用 Python 接口，Python DLL 必须在搜索路径上。控制台窗口里输入 "path" 可以
看到 (搜索路径) 当前使用的目录。

DLL 的名字必须匹配 Vim 编译时所使用的 Python 版本。目前，该名字为
"python24.dll"，也就是 Python 2.4。要确信这一点，编辑 "gvim.exe" 文件并查找
"python\d*.dll\c"。

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

Generated by vim2html on 2006年 06月 24日 星期六 00:27:59 UTC