附加库

SingleForwardable

详情请参考[ruby-src:doc/forwardable.rd.ja]

ftools.rb
注意

在1.8以后的版本中,最好不要使用ftools.rb。进行文件操作时, 请使用fileutils.rb。
概要

如果require 'ftools'的话, 就会添加拷贝或删除文件的方法。to是新文件名或目录名。当verbose为真时, 标准错误输出会显示处理的过程。
方法

File.copy(from, to[, verbose = false]) => true or false
File.cp(from, to[, verbose = false]) => true or false

  拷贝文件。严格说来,是先读取from,然后写到to中,并修改模式。文件的更新时间就是拷贝的时间。

  例如, 若想要保持更新时间的话,可以这样

  File.copy(from, to)
  stat = File.stat(from)
  File.utime(stat.atime, stat.mtime, to)

File.move(from, to[, verbose = false]) => true or false
File.mv(from, to[, verbose = false]) => true or false

  移动文件。与File.rename不同的是, 它可以进行跨区移动。
File.compare(from, to[, verbose = false]) => true or false
File.cmp(from, to[, verbose = false]) => true or false

  比较2个文件。若相同返回true,若不同则返回false。
File.safe_unlink(files[, ...][, verbose = false])
File.rm_f(files[, ...][, verbose = false])

  尽可能地删除(多个)文件。返回成功删除的文件数。相当于rm -f(rm(1))。
File.makedirs(dirs[, ...][, verbose = false])
File.mkpath(dirs[, ...][, verbose = false])

  生成(多个)目录。可一次生成多层的路径。若目录早已存在,则不作任何动作。相当于mkdir -p(mkdir(1))。
File.chmod(mode, files[, ...][, verbose = false])

  修改(多个)文件的属性。该方法只是在原来的File.chmod中添加了指定verbose的部分。
File.install(from, to[, mode = nil[, verbose = false]])

  拷贝文件并设定模式。若对象目录中已经存在相同文件时, 就会删除那个文件, 因此指向那个文件的硬连接也会被破坏。相当于install (install(1))命令。

gdbm.so

--> GDBM

访问GDBM文件的类. 您可以像使用Hash类一样来使用它,但是有两点需要注意:索引和数据都必须是字符串;数据是保存在文件中的.
超类:

  * Object

包含的模块:

  * Enumerable

类方法:

new(dbname[, mode[, flags]])
open(dbname[, mode[, flags]])
open(dbname[, mode[, flags]]) {|db| ...}

  以mode模式打开dbname所指数据库. mode的缺省值为0666. 若将mode指定为nil的话,一旦没有数据库时,将不会新建数据库,而是返回nil.

  flags中可以使用 GDBM::FAST, GDBM::SYNC, GDBM::NOLOCK. 默认值为0(即不指定).

  在Ruby 1.8.2 之后的版本中, 将flags指定为GDBM::READER, GDBM::WRITER, GDBM::WRCREAT, GDBM::NEWDB中的某个值时, 就可以指定读写模式. 若不指定任何值时, 将依次试用GDBM::WRCREAT, GDBM::WRITER, GDBM::READER。

  若指定了块时, 将把打开的GDBM对象当做参数来执行块的内容. 执行结束后关闭GDBM对象, open方法返回块的计算结果. 该运作方式等同于

  dbm = GDBM.open(file)
  begin
  yield dbm
  ensure
  dbm.close
  end

方法:

self[key]

  返回索引为key的值
self[key]=value

  将value赋值给索引为key的元素
cachesize = size
clear

  清空DBM文件
close

  关闭DBM文件. 此后的操作将引发异常.
delete(key)
delete(key) {|key| ... }

  删除索引为key的元素

  若不存在指定的索引则返回nil, 此时若指定了块 , 就计算块的内容.
delete_if { |key, value| ... }
reject! { |key, value| ... }

  若块的计算值为真,就删除该元素
each {|key, value| ... }
each_pair {|key, value| ... }

  对所有元素进行迭代操作
each_key {|key| ... }

  对所有key进行迭代操作
each_value {|value| ... }

  对所有value进行迭代操作
empty?

  若数据库为空则返回真
fastmode = bool
syncmode = bool

  修改已打开的GDBM对象的模式. 请参考下列的GDBM::FAST、GDBM::SYNC常数
fetch(key[,ifnone])
fetch(key) {|key| ... }

  与哈希表相同
has_key?(key)
key?(key)
include?(key)
member?(key)

  若数据库中包含key时,就返回真
has_value?(key)
value?(value)

  若数据库中包含值为value的元素时,就返回真
index(val)

  与哈希表相同
indexes(key_1, ... ) obsolete
indices(key_1, ... ) obsolete

  返回以各参数值为索引的元素所构成的数组
invert

  返回由值到索引的哈希表
keys

  返回由数据库中全部索引所构成的数组
length
size

  返回数据库中的元素数量(注意:在现条件下,要计算元素数量则必须检索整个数据库)
reject {|key, value| ... }

  与self.to_hash.reject相同, 返回哈希表
reorganize

  在GDBM中, 删除元素后DB文件体积不会减小(由删除所腾出空间将会被留作下次存储). 调用该方法后, 将重新生成DBM文件,这样可以避免浪费存储空间.

  删除大量数据后, 可以使用该方法来节省磁盘空间.
replace(other)

  用other来替换DBM的内容. other必须是带each_pair方法的对象
shift

  从数据库中取出一个元素,并将其删除
store(key, val)

  等同于self[key]=val, 将val赋值给索引为key的元素
sync

  将元素的变更反映到文件中. 只有在FAST模式(将GDBM#open()的第3参数指定为GDBM::FAST)时才有效

  注: 在GNU gdbm version 1.8以后的版本中,FAST模式已成为默认值
to_a

  以数组的形式返回DBM中的各个元素. 返回数组中的元素形式为[key, val].(也就是数组的数组)
to_hash

  返回包含DBM中的各个元素的哈希表
update(other)

  合并DBM和other的内容. 若出现重复的索引时,该元素的值就以other中的元素值为准.

  other必须是带each_pair方法的对象
values

  返回包含数据库中全部值的数组

常数

GDBM::VERSION

  表示libgdbm 版本信息的字符串

下列常数用于open的第3参数

GDBM::FAST

  写入的结果不会马上反映在磁盘上的文件中. 若使用该模式时, 要想显示地将结果写入文件,必须调用 GDBM#sync方法. 在libgdbm version 1.8.0 以后的版本中, 该模式成为默认值.
GDBM::SYNC

  写入的结果马上就会反映在磁盘上的文件中. 它是libgdbm version 1.8.0以前版本中的默认模式.

  该常数在libgdbm version 1.8.0 以后的版本中有效.
GDBM::NOLOCK

  通常情况下,在某进程已经打开某DB时, 若有其他进程试图打开该DB的话,就会引发Errno::EWOULDBLOCK(或Errno::EAGAIN)异常. 若指定了该标识的话,就可以同时打开DB而不会引发异常了.

  该常数在libgdbm version 1.8.0 以后的版本中有效.
GDBM::READER (Ruby 1.8.2 以后)

  以读入模式打开
GDBM::WRITER (Ruby 1.8.2 以后)

  以写入模式打开
GDBM::WRCREAT (Ruby 1.8.2 以后)

  在写入模式下,若并不存在相应的文件时, 就新建一个
GDBM::NEWDB (Ruby 1.8.2 以后)

  在写入模式下, 若已经存在相应的文件时,就将其删除后再新建一个

# getoptlong.rb 命令行选项的解析 请参考<URL:http://www.sra.co.jp/people/m-kasahr/ruby/getoptlong/>

Author: <jammy@shljapan.co.jp>

对选项进行解析，设置$OPT_xxx的值。

典型的用法如下。

require 'getopts'

unless getopts('vh', 'version', 'help')
 abort "usage: #$0 [-vh] [--version] [--help] file"
end

if $OPT_v or $OPT_version
 puts VERSION_STRING
 exit
end

# ARGV中的选项被删除。

while line = ARGF.gets
 # ...
end

格式:

getopts(single_opts, *long_opts)

第一参数:

  指定`-f'或`-x(=-fx)'这样的单字符的选项。若选项包含`-f'和`-x'这两部分时，应写成`"fx"'。若没有选项时，则必须写成`nil'。
第二参数:

  指定长选项或带参数的选项。如`--version'、`--geometry 300x400'、`-d host:0.0'等。若选项中带参数，则必须加上":"。如"version"、"geometry:"、"d:"等。若想指定选项的缺省值时，应该在 ":"的后面给出缺省值。如"geometry:80x25"。

选项解析:

解析结果采用"$OPT_指定的参数名"的形式进行处理。

  *

  若使用单选项或不带参数的选项时，它将被设为`true'。

  `-f'→`$OPT_f = true' `--version'→`$OPT_version = true'
  *

  除此之外，将会使用选项的参数。

  `-d pengo:0.0'→`$OPT_d = pengo:0.0' `--geometry 80x25'→ `$OPT_geometry = 80x25'。
  * 若遇到`-'或`--'时，就不会对其后面的内容进行解析了。

返回值:

返回实际设定的选项数。若指定了错误的选项时，返回`nil'。

gserver.rb

<URL:http://www.ruby-doc.org/stdlib/libdoc/gserver/rdoc/>

iconv.so

进行代码变换的扩展库。

--> Iconv

该库的说明文件已被嵌入源代码中，可用下列方法取得原文。

% ruby -ne 'print if /=begin/.../=end/' ext/iconv/iconv.c

Iconv是UNIX 95的iconv()函数的封装形式，它在各种字符代码体系间进行字符串转换。

详情请参考Open Group的在线文档。

  * iconv.h
  * iconv_open()
  * iconv()
  * iconv_close()

具体使用哪套字符代码体系要看系统而定。
Iconv 类
类方法

Iconv.new(to, from)

  生成并返回从from到to的新的转换器。

  to和from分别指变换后和变换前的字符代码体系。

  该方法中可能出现的异常如下。

  若to或from不是String时，将引发TypeError。

  若找不到to和from所指的变换器时，则引发ArgumentError。

  若iconv_open(3)运行失败，则引发SystemCallError。
Iconv.open(to, from) {|cd| ...}

  若没给块时，它相当于Iconv.new。若给块的话，将计算块的内容，关闭转换器，并返回块的计算值。
Iconv.iconv(to, from, *strs)

  它是下列语句

  Iconv.open(to, from) {|cd| (strs + [nil]).collect {|s| cd.iconv(s)}}

  的省略形式。其中to和from的意义与Iconv.new中的相同。

  strs是被变换的字符串。

  该方法可能会引起Iconv.new, Iconv.open 以及 Iconv#iconv 中的异常。
Iconv.conv(to, from, str)

  它是下列语句

  Iconv.iconv(to, from, str).join

  的省略形式。请参考Iconv.iconv。
Iconv.list {|*aliases| ... } ((<ruby 1.9 特性>))

  Iterates each alias sets. 若未指定块，则返回编码名列表。

实例方法

Iconv#close

  结束转换。

  若调用该方法之后再调用Iconv#iconv的话，就会引发异常。但若只调用close本身的话则没问题。

  它的返回值是可以使输出缓冲区恢复到初始shift状态的字节串。

  i = Iconv.open("ISO-2022-JP", "EUC-JP")
  i.iconv("\264\301")  #=> "\e$B4A"
  i.iconv("\273\372")  #=> ";z"
  i.close      #=> "\e(B"

Iconv#iconv(str, [ start = 0, [ length = -1 ] ])

  开始转换字符串，并返回转换结果。

  若str是字符串，则进行str[start, length]转换，并返回转换结果。

  若str为nil，则将转换器恢复到初始shift状态，并返回可将输出缓冲区恢复为初始shift状态的字节串。

  除此以外将引发异常。

  str是转换后的字符串或nil。

  start是str中的转换起始点。

  length是str中的转换长度。若为nil或-1的话，则指转换start后面的所有字符。

  该方法可能会引发Iconv::IllegalSequence、 Iconv::InvalidCharacter、以及 Iconv::OutOfRange 异常。

Iconv::Failure 模块

为Iconv可能引发的异常而设置的模块。
实例方法

Iconv::Failure#success

  返回发生异常前转换成功的字符串。

  在Iconv.iconv 中发生该异常时的返回值是，由发生异常前转换成功的字符串所构成的数组。数组的最后一个元素就是变换中的字符串。
Iconv::Failure#failed

  它返回传给Iconv的字符串中的异常发生点之后部分。
Iconv::Failure#inspect

  返回形如#<type: "success", "failed">这样的字符串。

Iconv::IllegalSequence 类

它表示，因为输出或输入的字符不在指定的字符集合内，所以停止转换。
超类

ArgumentError
包含的模块

Iconv::Failure
Iconv::InvalidCharacter 类

它表示，因为输入的末尾部分是不完整的字符或shift，所以停止转换。
超类

ArgumentError
包含的类

Iconv::Failure
Iconv::OutOfRange 类

Iconv库的内部错误。通常不会引发该异常。
超类

RuntimeError
包含的模块

Iconv::Failure
例

 1.

  新生成Iconv的实例，并使用Iconv#iconv方法

  cd = Iconv.new(to, from)
  begin
   input.each {|s| output << cd.iconv(s)}
   output << cd.iconv(nil)  # don't forget this
  ensure
   cd.close
  end

 2.

  带块调用Iconv.open

  Iconv.open(to, from) do |cd|
   input.each {|s| output << cd.iconv(s)}
   output << cd.iconv(nil)
  end

 3.

  (2) 的简略形式

  Iconv.iconv(to, from, *input.to_a)