附加库

将异常类与特定的错误消息格式联系起来。
Usage

1. 若已经在类定义中使用extend语句添加了Exception2MessageMapper的话，就可以使用def_e2message和def_exception方法了。这样就可以将异常类与消息联系起来。

class Foo
 extend Exception2MessageMapper
 def_e2message ExistingExceptionClass, "message..."
 def_exception :NewExceptionClass, "message...", StandardError
 ...
end

foo = Foo.new
foo.Fail ....

2. 若您想多次使用同一个异常类时，可以将它写成模块，然后再include该模块就可以了。

module ErrorMod
 extend Exception2MessageMapper
 def_e2meggage ExistingExceptionClass, "message..."
 def_exception :NewExceptionClass, "message...", StandardError
 ...
end
class Foo
 include ErrorMod
 ...
end

foo = Foo.new
foo.Fail ....

3. 您还可以在异常类的实例之外调用异常。

module ErrorMod
 extend Exception2MessageMapper
 def_e2message ExistingExceptionClass, "message..."
 def_exception :NewExceptionClass, "message...", StandardError
 ...
end
class Foo
 extend Exception2MessageMapper
 include ErrorMod
 ...
end

Foo.Fail NewExceptionClass, arg...
Foo.Fail ExistingExceptionClass, arg...

Methods

def_e2message(exception, message_form)

将已存在的异常类exception与错误消息格式message_form联系起来。message_form的形式与sprintf()中的format字符串的形式相同。

该格式用在Raise(或其别名Fail)中。

def_exception(exception_name, message_form, superclass)

生成名为exception_name的异常类(将符号传给exception_name)。若设置了superclass时，该异常类就是superclass的子类。若没有设置superclass时，该异常类就是StandardError的子类。

然后将该异常类与message_form指定的格式联系起来，就可以在Raise(或其別名Fail)中使用了。

Raise(error, [args [,args2...]])

引发error类的错误。

error后续的args参数群将和错误消息格式一起出现在错误消息中。例如，若给出下面的定义的话

class Foo
 extend Exception2MessageMapper
 def_exception :NewExceptionClass, "message...%d, %d and %d"

 def foo
  Raise NewExceptionClass, 1, 2, 3
 end
end

就可以使用下面的方法

Foo.new().foo()

来引发如下错误。

in `Raise': message...1, 2 and 3 (Foo::NewExceptionClass) 

另外，下面的这个方法

Foo.Raise Foo::NewExceptionClass, 1, 3, 5

也会引发如下错误

in `Raise': message...1, 3 and 5 (Foo::NewExceptionClass) 

Fail(error, [args [,args2...]])

它是Raise的别名。

Exception2MessageMapper

--> e2mmap.rb

enumerator.so

请参考Enumerable::Enumerator。
若使用require语句来包含该模块时，Object类将新增下列方法

Object#to_enum(method = :each, *args)
Object#enum_for(method = :each, *args)

  返回Enumerable::Enumerator.new(self, method, *args)。

  例:
   str = "xyz"

   enum = str.enum_for(:each_byte)
   a = enum.map {|b| '%02x' % b } #=> ["78", "79", "7a"]

   # protects an array from being modified
   a = [1, 2, 3]
   some_method(a.to_enum)

若使用require语句来包含该模块时，Enumerable模块将新增下列方法

Enumerable#each_slice(n) {...}

  依次将n个元素传给块来进行迭代操作。

  例:
   (1..10).each_slice(3) {|a| p a}
   # outputs below
   [1, 2, 3]
   [4, 5, 6]
   [7, 8, 9]
   [10]

Enumerable#enum_slice(n)

  返回Enumerable::Enumerator.new(self, :each_slice, n)。
Enumerable#each_cons(n) {...}

  将由连续的n个元素构成的数组传给块进行迭代操作。

  例:
   (1..10).each_cons(3) {|a| p a}
   # outputs below
   [1, 2, 3]
   [2, 3, 4]
   [3, 4, 5]
   [4, 5, 6]
   [5, 6, 7]
   [6, 7, 8]
   [7, 8, 9]
   [8, 9, 10]

Enumerable#enum_cons(n)

  返回Enumerable::Enumerator.new(self, :each_cons, n)。
Enumerable#enum_with_index

  返回Returns Enumerable::Enumerator.new(self, :each_with_index)。

Enumerable::Enumerator

该封装类使得each以外的方法，如each_byte等也能进行enumerate。

另外请参考enumerator.so。
超类:

  * Object

包含的模块:

  * Enumerable

类方法:

Enumerable::Enumerator.new(obj, method = :each, *args)

  为obj对象生成一个使用method方法而非each来进行迭代操作的对象，并返回该对象。若指定了args的话，将会在调用method时把它传递出去。

  例:
   str = "xyz"

   enum = Enumerable::Enumerator.new(str, :each_byte)
   a = enum.map {|b| '%02x' % b } #=> ["78", "79", "7a"]

方法:

each {...}

  按照生成时的参数的规定，进行迭代操作。

erb.rb

--> ERB

ERB

处理eRuby脚本的类。该类通常被称作ERbLight，与eruby不同的是，它在标准输出中显示字符时并不插入字符串。
用法

使用ERB类时，需要添加require 'erb'语句。

require 'erb'

ERB.new($<.read).run

类方法

ERB.new(eruby_script, safe_level=nil, trim_mode=nil, eoutvar='_erbout')

  从eruby_script中生成ERB。可指定eval时的$SAFE、trim_mode(下文详述)和eoutvar(若需要在eRuby脚本中使用ERB时才需要修改。通常不必更改。)。

方法

ERB#run(b=TOPLEVEL_BINDING)

  以b的binding来执行ERB，显示字符。
ERB#result(b=TOPLEVEL_BINDING)

  以b的binding来执行ERB，返回字符串。
ERB#src

  取得变换之后的Ruby脚本。
ERB#def_method(mod, methodname, fname='(ERB)')

  将变换之后的Ruby脚本定义为方法。以mod来指定新方法所在的模块，以methodname来指定方法名。fname是定义脚本时的文件名。一般发生错误时才会用到它。

  erb = ERB.new(script)
  erb.def_method(MyClass, 'foo(bar)', 'foo.erb')

ERB#def_module(methodname='erb')

  返回一个无名模块，该模块将变换后的Ruby脚本定义为方法。
ERB#def_class(suplerklass=Object, methodname='erb')

  返回一个无名类，该类将变换后的Ruby脚本定义为方法。

Module ERB::Util

ERB::Util.html_escape(s)
ERB::Util.h(s)

  把HTML的 &"<> 变为转义字符。 (基本等同于CGI.escapeHTML。)
ERB::Util.url_encode(s)
ERB::Util.u(s)

  对字符串进行URL编码。 (基本等同于CGI.escape。)

Module ERB::DefMethod

ERB::DefMethod.def_erb_method(methodname, erb)

  将erb的脚本定义为self的方法。由methodname指定方法名。若self是字符串的话，就读入该文件并使用ERB完成变换之后再定义为方法。

  class Writer
  extend ERB::DefMethod
  def_erb_method('to_html', 'writer.erb')
  ...
  end
  ...
  puts writer.to_html

trim_mode

不同的trim_mode选项值会影响到对代码的处理方式。它可以指定

  * 换行的处理
  * 以%开头的行的处理(2.0新增内容)

trim_mode选项的可用值如下。

  * 兼容ERb-1.4.x的指定方法
    o nil, 0: 原封不动地进行变换
    o 1: 若行尾是%>则不输出换行
    o 2: 若行首是<%且行尾是%>则不输出换行
  * 2.0新增的指定方法
    o nil, "": 原封不动地进行变换
    o ">": 与1相同
    o "<>": 与2相同
    o "%": 把以%开头的行看作<%..%>形式进行变换。不输出该行的换行
    o "%>", ">%": 同时进行1和"%"的两种规则
    o "%<>", "<>%": 同时进行2和"%"的两种规则

运行范例

# 脚本
<% 3.times do |n| %>
% n = 0
* <%= n%>
<% end %>

# trim_mode = nil, '', 0

% n = 0
* 0

% n = 0
* 1

% n = 0
* 2

# trim_mode = 1, '>'
% n = 0
* 0% n = 0
* 1% n = 0
* 2

# trim_mode = 2, '<>'
% n = 0
* 0
% n = 0
* 1
% n = 0
* 2

# trim_mode = '%'

* 0

* 0

* 0

# trim_mode = '%>', '>%'
* 0* 0* 0

# trim_mode = '%<>', '<>%'
* 0
* 0
* 0

eregex.rb
目的·概要

提供了由2个正则表达式构成AND/OR的功能。

在Regexp类中定义&和|方法. 若与两个正则表达式都匹配的话, 前者(RegAnd)返回真;若只能匹配其中一个时,则后者(RegOr)为真. RegAnd、RegOr都只能支持=~。
范例代码

require 'eregex'
p "abc" =~ /b/|/c/
p "abc" =~ /b/&/c/

class Regexp

在扩展了内部类Regexp之后,定义了下列方法。
实例方法

Regexp#&(other)

  返回RegAnd(self,other)
Regexp#|(other)

  返回RegOr(self,other)

class RegAnd
实例方法

RegAnd#initialize(reg1,reg2)

  构造函数
RegAnd#=~(str)

  若str同时匹配reg1和reg2, 则返回真

class RegOr
实例方法

RegOr#initialize(reg1,reg2)

  构造函数
RegOr#=~(str)

  若str只匹配reg1或reg2中的一个时,就返回真

etc.so

--> Etc

Etc

用来在/etc中的数据库中获取信息的模块. 也可以在类中include该模块后加以利用.
用法:

require 'etc'
p Etc.getlogin

模块函数:

Etc.endgrent ((<ruby 1.8 特性>))
Etc.endpwent ((<ruby 1.8 特性>))
Etc.getgrent ((<ruby 1.8 特性>))
Etc.getpwent ((<ruby 1.8 特性>))
Etc.setgrent ((<ruby 1.8 特性>))
Etc.setpwent ((<ruby 1.8 特性>))

  ruby 1.8 特性
Etc.getlogin

  返回自己的login名。若获取login名失败,则返回nil。

  该方法失败时,可退回到Etc.getpwuid。
Etc.getpwnam(name)

  搜索passwd数据库, 返回姓名为name的passwd条目。返回值是passwd结构体, 其成员如下。

  struct passwd
  name   # 用户名(字符串)
  passwd  # 密码(字符串)
  uid   # 用户ID(整数)
  gid   # 组ID(整数)
  gecos   # gecoszi字段(字符串)
  dir   # 主目录(字符串)
  shell   # login shell(字符串)
  # 有些系统不支持下列成员
  change  # 修改密码的时间(整数)
  quota   # 定额(整数)
  age   # age(整数)
  class   # 用户访问类(字符串)
  comment  # comment(字符串)
  expire  # 帐户有效期限(整数)   
  end

  详情请参考getpwnam(3) 。
Etc.getpwuid([uid])

  搜索passwd数据库, 返回用户ID为uid的passwd条目。返回值与Etc.getpwnam相同。省略参数时,将使用getuid(2)的值。

  详情请参考getpwuid(3)。
Etc.getgrgid(gid)

  搜索group数据库, 返回组ID为gid的组条目。返回值是group结构体, 其成员如下。

  struct group
  name   # 组名(字符串)
  passwd  # 组的密码(字符串)
  gid   # 组ID(整数)
  mem   # 组成员名的数组
  end

  详情请参考getgrgid(3)
Etc.getgrnam(name)

  返回名为name的组条目。返回值与Etc.getgrgid 相同。

  详情请参考getgrnam(3) 。
Etc.group

  可依次访问所有组条目的迭代器。
Etc.passwd

  可依次访问所有passwd条目的迭代器。

expect.rb

IO#expect(pat, [timeout])

--> [ruby-src:ext/pty/README.expect.ja]