模块 OpenURI::OpenRead

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

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’ 从网络获取内容片段时，都会使用一个参数调用该过程。参数 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 之间进行重定向。

:max_redirects

概要

:max_redirects=>int

在引发 OpenURI::TooManyRedirects 之前允许的 HTTP 重定向次数。默认值为 64。

:request_specific_fields

概要

:request_specific_fields => {}
:request_specific_fields => lambda {|url| ...}

:request_specific_fields 选项允许指定随 HTTP 请求发送的自定义标头字段。它可以作为 Hash 或 Proc 传递，该 Proc 在每个请求上进行评估并返回标头字段的 Hash。

如果提供了 Hash，它仅为初始请求指定标头，并且这些标头不会在重定向时发送。

如果提供了 Proc，它将为包括重定向在内的每个请求执行，从而允许基于请求 URL 进行动态标头自定义。重要的是 Proc 返回一个 Hash。并且此 Hash 指定要随请求发送的标头。

例如，使用 Hash

URI.open("http://...",
         request_specific_fields: {"Authorization" => "token dummy"}) {|f| ... }

例如，使用 Proc

URI.open("http://...",
         request_specific_fields: lambda { |uri|
           if uri.host == "example.com"
             {"Authorization" => "token dummy"}
           else
             {}
           end
         }) {|f| ... }

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

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