*if_ruby.txt*   For Vim version 8.0.  最近更新: 2017年7月


		  VIM 参考手册    by Shugo Maeda
				译者: Willis, tocer
				http://vimcdoc.sf.net

Vim 的 Ruby 接口					*ruby* *Ruby*


1. 命令				|ruby-commands|
2. Vim 模块			|ruby-vim|
3. Vim::Buffer 对象		|ruby-buffer|
4. Vim::Window 对象		|ruby-window|
5. 全局变量			|ruby-globals|
6. 动态调入			|ruby-dynamic|

{Vi 无此功能}
			*E266* *E267* *E268* *E269* *E270* *E271* *E272* *E273*

只有编译 Vim 时加入 |+ruby| 特性才会有 Ruby 接口功能。

ruby 的主页是 http://www.ruby-lang.org/。你可以在那里找到 Ruby 下载的链接。

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

							*:ruby* *:rub*
:rub[y] {cmd}		执行 Ruby 命令 {cmd}。要试一试: >
				:ruby print "Hello"

:rub[y] << {endpattern}
{script}
{endpattern}
			执行 Ruby 脚本 {script}。
			{endpattern} _不能_有前导空白。如果 {endpattern} 省
			略，缺省为单个句号 '.'，类似于 |:append| 和 |:insert|
			命令。这种形式的 |:ruby| 命令主要用于在 vim 脚本里包含
			ruby 代码。
			注意: 如果编译时没有加入 Ruby 特性，这个命令不会工作。
			为了避免错误，参看 |script-here|。

示例 Vim 脚本: >

	function! RedGem()
	ruby << EOF
	class Garnet
		def initialize(s)
			@buffer = Vim::Buffer.current
			vimputs(s)
		end
		def vimputs(s)
			@buffer.append(@buffer.count,s)
		end
	end
	gem = Garnet.new("pretty")
	EOF
	endfunction
<
要看运行的 Ruby 版本: >
	:ruby print RUBY_VERSION
<

						*:rubydo* *:rubyd* *E265*
:[range]rubyd[o] {cmd}	在 [range] 界定的每行上分别执行 Ruby 命令 {cmd}，执行
			时，$_ 设为相应的行文本，不含结尾的 <EOL>。修改 $_ 就
			会修改相应的行，不过要 注意: 此命令不能用来增加或者删
			除行。
			缺省的 [range] 是整个文件: "1,$"。

							*:rubyfile* *:rubyf*
:rubyf[ile] {file}	执行 Ruby 脚本文件 {file}。这和 `:ruby load 'file'` 相
			当，但可用文件名自动补全功能。


|sandbox| 里不能执行 Ruby 命令。

==============================================================================
2. Vim 模块						*ruby-vim*

Ruby 代码通过 "Vim" 模块调用所有的 vim 功能。

概述: >
	print "Hello"				# 显示消息
	Vim.command(cmd)			# 执行 ex 命令
	num = Vim::Window.count			# 得到窗口行数
	w = Vim::Window[n]			# 得到第 "n" 个窗口
	cw = Vim::Window.current		# 得到当前窗口
	num = Vim::Buffer.count			# 得到缓冲区的个数
	b = Vim::Buffer[n]			# 得到第 "n" 个缓冲区
	cb = Vim::Buffer.current		# 得到当前缓冲区
	w.height = lines			# 设置窗口高度
	w.cursor = [row, col]			# 设置窗口里的光标位置
	pos = w.cursor				# 得到数组 [行, 列]
	name = b.name				# 得到缓冲区的文件名
	line = b[n]				# 得到缓冲区的某一行
	num = b.count				# 得到总的行数
	b[n] = str				# 设置缓冲区的某一行
	b.delete(n)				# 删除某一行
	b.append(n, str)			# 在第 n 行后增加一行
	line = Vim::Buffer.current.line		# 得到当前行
	num = Vim::Buffer.current.line_number	# 得到当前行号
	Vim::Buffer.current.line = "test"	# 设置当前行
<

模块函数:

							*ruby-message*
Vim::message({msg})
	显示消息 {msg}。

							*ruby-set_option*
Vim::set_option({arg})
	设置 vim 选项。{arg} 可以是任何一个 ":set" 命令接受的命令。 注意 这意
	味着参数里不能有空格！参见 |:set|。

							*ruby-command*
Vim::command({cmd})
	执行 Ex 命令 {cmd}。

							*ruby-evaluate*
Vim::evaluate({expr})
	用 vim 内部的表达式分析器执行 {expr} (参看 |expression|)。执行结果返回
	的类型如下:
	- Integer， 如果 Vim 表达式返回数值
	- Float，如果 Vim 表达式返回浮点数
	- String，如果 Vim 表达式返回字符串
	- Array，如果 Vim 表达式返回 Vim 列表
	- Hash，如果 Vim 表达式返回 Vim 字典
	递归扩展字典和列表。

==============================================================================
3. Vim::Buffer 对象					*ruby-buffer*

Vim::Buffer 对象代表 Vim 缓冲区。

类方法:

current		返回当前缓冲区对象。
count		返回缓冲区的总数。
self[{n}]	返回第 {n} 个缓冲区。首个缓冲区的序号是 0。

方法:

name		返回缓冲区的名字。
number		返回缓冲区的序号。
count		返回总行数。
length		返回总行数。
self[{n}]	从缓冲区中返回一行。{n} 是行号。
self[{n}] = {str}
		设置缓冲区的一行。{n} 是行号。
delete({n})	删除缓冲区的一行。{n} 是行号。
append({n}, {str})
		在第 {n} 行后增加一行。
line		如果缓冲区激活，返回缓冲区的当前行。
line = {str}    如果缓冲区激活，设置缓冲区的当前行。
line_number     如果缓冲区激活，返回当前行的行号。

==============================================================================
4. Vim::Window 对象					*ruby-window*

Vim::Window 对象代表 Vim 窗口。

类方法:

current		返回当前窗口对象。
count		返回窗口的总数。
self[{n}]	返回第 {n} 个窗口。首个窗口的序号是 0。

方法:

buffer		返回显示的缓冲区对象。
height		返回窗口的高度。
height = {n}	设置窗口的高度为 {n}。
width		返回窗口的宽度。
width = {n}	设置窗口的宽度为 {n}。
cursor		返回光标位置数组: [行、列]。
cursor = [{row}, {col}]
		设置光标位置为行 {row} 和列 {col}。

==============================================================================
5. 全局变量						*ruby-globals*

有两个全局变量。

$curwin		当前窗口对象。
$curbuf		当前缓冲区对象。

==============================================================================
6. 动态调入						*ruby-dynamic*

MS-Windows 和 Unix 上，可以动态调入 Ruby 库。|:version| 输出这时应包括
|+ruby/dyn|。

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


MS-Windows ~

必须安装正确的 Ruby 版本才能工作。该包可以从这里下载:
http://rubyinstaller.org/downloads/
目前的版本是 rubyinstaller-2.2.5.exe

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

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

如果编译 Vim 时要使用带 MSVC 的 RubyInstaller 1.9 或 2.X，需要一点技巧。详见
src/INSTALLpc.txt。


Unix ~

'rubydll' 选项可用来指定 Ruby 共享库文件，而不用编译时指定的 DYNAMIC_RUBY_DLL
文件。共享库的版本必须和 Vim 编译使用的 Ruby 版本保持一致。

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