模块 OpenURI::OpenRead

OpenURI::OpenRead#open 为 URI::HTTP 和 URI::FTP 提供 “open”。

OpenURI::OpenRead#open 接受可选的 3 个参数作为

OpenURI::OpenRead#open([mode [, perm]] [, options]) [{|io| ... }]

OpenURI::OpenRead#open 如果没有给出块，则返回一个类似 IO 的对象。否则，它会生成 IO 对象并返回块的值。该 IO 对象扩展了 OpenURI::Meta。

mode 和 perm 与 Kernel#open 相同。

但是，mode 必须是读取模式，因为 OpenURI::OpenRead#open 不支持写入模式（尚未）。此外，perm 被忽略，因为它仅对文件创建有意义。

options 必须是一个哈希。

每个具有字符串键的选项都指定了 HTTP 的额外标头字段。即，对于没有 HTTP 代理的 FTP，它被忽略。

该哈希可能包含其他选项，其中键是符号

:proxy

概要

:proxy => "http://proxy.foo.com:8000/"
:proxy => URI.parse("http://proxy.foo.com:8000/")
:proxy => true
:proxy => false
:proxy => nil

如果指定了 :proxy 选项，则该值应为 String、URI、布尔值或 nil。

当给出 String 或 URI 时，它被视为代理 URI。

当给出 true 或未指定选项本身时，将检查环境变量 “scheme_proxy”。“scheme” 被替换为 “http”、“https” 或 “ftp”。

当给出 false 或 nil 时，将忽略环境变量，并将直接连接到服务器。

:proxy_http_basic_authentication

概要

:proxy_http_basic_authentication =>
  ["http://proxy.foo.com:8000/", "proxy-user", "proxy-password"]
:proxy_http_basic_authentication =>
  [URI.parse("http://proxy.foo.com:8000/"),
   "proxy-user", "proxy-password"]

如果指定了 :proxy 选项，则该值应为一个包含 3 个元素的 Array。它应该包含一个代理 URI、一个代理用户名和一个代理密码。代理 URI 应该是一个 String、一个 URI 或 nil。代理用户名和密码应该是一个 String。

如果为代理 URI 给出 nil，则此选项将被忽略。

如果指定了 :proxy 和 :proxy_http_basic_authentication，则会引发 ArgumentError。

:http_basic_authentication

概要

:http_basic_authentication=>[user, password]

如果指定了 :http_basic_authentication，则该值应为一个包含 2 个字符串的数组：用户名和密码。它用于 RFC 2617 定义的 HTTP 基本身份验证。

:content_length_proc

概要

:content_length_proc => lambda {|content_length| ... }

如果指定了 :content_length_proc 选项，则在实际传输开始之前会调用该选项值过程。它接受一个参数，该参数是预期的字节数内容长度。

如果通过 HTTP 重定向执行两个或多个传输，则该过程仅对最后一个传输调用一次。

当预期内容长度未知时，该过程将使用 nil 调用。当 HTTP 响应没有 Content-Length 标头时，就会发生这种情况。

:progress_proc

概要

:progress_proc => lambda {|size| ...}

如果指定了 :progress_proc 选项，则每次“open”从网络获取内容片段时，都会使用一个参数调用该 proc。参数 size 是累积的已传输字节数。

如果通过 HTTP 重定向完成两个或多个传输，则该过程仅对最后一个传输调用一次。

:progress_proc 和 :content_length_proc 旨在用于进度条。例如，可以使用 Ruby/ProgressBar 如下实现。

pbar = nil
open("http://...",
  :content_length_proc => lambda {|t|
    if t && 0 < t
      pbar = ProgressBar.new("...", t)
      pbar.file_transfer_mode
    end
  },
  :progress_proc => lambda {|s|
    pbar.set s if pbar
  }) {|f| ... }

:read_timeout

概要

:read_timeout=>nil     (no timeout)
:read_timeout=>10      (10 second)

:read_timeout 选项指定 http 连接读取的超时时间。

:open_timeout

概要

:open_timeout=>nil     (no timeout)
:open_timeout=>10      (10 second)

:open_timeout 选项指定 http 连接打开的超时时间。

:ssl_ca_cert

概要

:ssl_ca_cert=>filename or an Array of filenames

:ssl_ca_cert 用于指定 SSL 的 CA 证书。如果给出，则不使用默认证书。

:ssl_verify_mode

概要

:ssl_verify_mode=>mode

:ssl_verify_mode 用于指定 openssl 验证模式。

:ssl_min_version

概要

:ssl_min_version=>:TLS1_2

:ssl_min_version 选项指定允许的最小 SSL/TLS 协议版本。另请参见 OpenSSL::SSL::SSLContext#min_version=.

:ssl_max_version

概要

:ssl_max_version=>:TLS1_2

:ssl_max_version 选项指定允许的最大 SSL/TLS 协议版本。另请参见 OpenSSL::SSL::SSLContext#max_version=.

:ftp_active_mode

概要

:ftp_active_mode=>bool

:ftp_active_mode => true 用于使 ftp 处于活动模式。Ruby 1.9 默认使用被动模式。请注意，活动模式是 Ruby 1.8 或更早版本中的默认模式。

:redirect

概要

:redirect=>bool

:redirect 默认情况下为 true。:redirect => false 用于禁用所有 HTTP 重定向。

OpenURI::HTTPRedirect 异常在重定向时引发。使用 true 还意味着允许 http 和 ftp 之间的重定向。

# File lib/open-uri.rb, line 749
def open(*rest, &block)
  OpenURI.open_uri(self, *rest, &block)
end

OpenURI::OpenRead#read([ options ]) 读取 self 引用的内容并以字符串形式返回内容。该字符串使用 OpenURI::Meta 扩展。参数 options 与 OpenURI::OpenRead#open 相同。

# File lib/open-uri.rb, line 757
def read(options={})
  self.open(options) {|f|
    str = f.read
    Meta.init str, f
    str
  }
end