模块 URI

与 URI.decode_www_form_component 相似，但保留了 '+'。

# File lib/uri/common.rb, line 379
def self.decode_uri_component(str, enc=Encoding::UTF_8)
  _decode_uri_component(/%\h\h/, str, enc)
end

从给定的字符串 str 中返回名称/值对，该字符串必须是 ASCII 字符串。

该方法可用于解码 Net::HTTPResponse 对象 res 的主体，其中 res['Content-Type'] 为 'application/x-www-form-urlencoded'。

返回的数据是一个包含 2 个元素子数组的数组；每个子数组都是一个名称/值对（两者都是字符串）。每个返回的字符串都具有编码 enc，并且已通过 String#scrub 删除了无效字符。

一个简单的例子

URI.decode_www_form('foo=0&bar=1&baz')
# => [["foo", "0"], ["bar", "1"], ["baz", ""]]

返回的字符串进行了一些转换，类似于在 URI.decode_www_form_component 中执行的转换

URI.decode_www_form('f%23o=%2F&b-r=%24&b+z=%40')
# => [["f#o", "/"], ["b-r", "$"], ["b z", "@"]]

给定的字符串可能包含连续的分隔符

URI.decode_www_form('foo=0&&bar=1&&baz=2')
# => [["foo", "0"], ["", ""], ["bar", "1"], ["", ""], ["baz", "2"]]

可以指定不同的分隔符

URI.decode_www_form('foo=0--bar=1--baz', separator: '--')
# => [["foo", "0"], ["bar", "1"], ["baz", ""]]

# File lib/uri/common.rb, line 554
def self.decode_www_form(str, enc=Encoding::UTF_8, separator: '&', use__charset_: false, isindex: false)
  raise ArgumentError, "the input of #{self.name}.#{__method__} must be ASCII only string" unless str.ascii_only?
  ary = []
  return ary if str.empty?
  enc = Encoding.find(enc)
  str.b.each_line(separator) do |string|
    string.chomp!(separator)
    key, sep, val = string.partition('=')
    if isindex
      if sep.empty?
        val = key
        key = +''
      end
      isindex = false
    end

    if use__charset_ and key == '_charset_' and e = get_encoding(val)
      enc = e
      use__charset_ = false
    end

    key.gsub!(/\+|%\h\h/, TBLDECWWWCOMP_)
    if val
      val.gsub!(/\+|%\h\h/, TBLDECWWWCOMP_)
    else
      val = +''
    end

    ary << [key, val]
  end
  ary.each do |k, v|
    k.force_encoding(enc)
    k.scrub!
    v.force_encoding(enc)
    v.scrub!
  end
  ary
end

返回从给定的 URL 编码字符串 str 解码的字符串。

给定的字符串首先被编码为 Encoding::ASCII-8BIT（使用 String#b），然后解码（如下），最后强制编码为给定的编码 enc。

返回的字符串

• 保留

  • 字符 '*'、'.'、'-' 和 '_'。

  • 范围 'a'..'z'、'A'..'Z' 和 '0'..'9' 中的字符。

  示例

  URI.decode_www_form_component('*.-_azAZ09')
  # => "*.-_azAZ09"
  

• 转换

  • 字符 '+' 为字符 ' '。

  • 每个“百分比表示法”为一个 ASCII 字符。

  示例

  URI.decode_www_form_component('Here+are+some+punctuation+characters%3A+%2C%3B%3F%3A')
  # => "Here are some punctuation characters: ,;?:"
  

相关：URI.decode_uri_component（保留 '+'）。

# File lib/uri/common.rb, line 368
def self.decode_www_form_component(str, enc=Encoding::UTF_8)
  _decode_uri_component(/\+|%\h\h/, str, enc)
end

与 URI.encode_www_form_component 相似，但 ' '（空格）被编码为 '%20'（而不是 '+'）。

# File lib/uri/common.rb, line 374
def self.encode_uri_component(str, enc=nil)
  _encode_uri_component(/[^*\-.0-9A-Z_a-z]/, TBLENCURICOMP_, str, enc)
end

返回从给定 Enumerable enum 导出的 URL 编码字符串。

结果适合用作 HTTP 请求的表单数据，其 Content-Type 为 'application/x-www-form-urlencoded'。

返回的字符串由 enum 的元素组成，每个元素都转换为一个或多个 URL 编码字符串，并使用字符 '&' 连接。

简单示例

URI.encode_www_form([['foo', 0], ['bar', 1], ['baz', 2]])
# => "foo=0&bar=1&baz=2"
URI.encode_www_form({foo: 0, bar: 1, baz: 2})
# => "foo=0&bar=1&baz=2"

返回的字符串使用方法 URI.encode_www_form_component 形成，该方法会转换某些字符

URI.encode_www_form('f#o': '/', 'b-r': '$', 'b z': '@')
# => "f%23o=%2F&b-r=%24&b+z=%40"

当 enum 是类似数组的时，每个元素 ele 都转换为一个字段

• 如果 ele 是一个包含两个或多个元素的数组，则该字段由其前两个元素形成（任何其他元素都会被忽略）

  name = URI.encode_www_form_component(ele[0], enc)
  value = URI.encode_www_form_component(ele[1], enc)
  "#{name}=#{value}"
  

  示例

  URI.encode_www_form([%w[foo bar], %w[baz bat bah]])
  # => "foo=bar&baz=bat"
  URI.encode_www_form([['foo', 0], ['bar', :baz, 'bat']])
  # => "foo=0&bar=baz"
  

• 如果 ele 是一个包含一个元素的数组，则该字段由 ele[0] 形成

  URI.encode_www_form_component(ele[0])
  

  示例

  URI.encode_www_form([['foo'], [:bar], [0]])
  # => "foo&bar&0"
  

• 否则，该字段由 ele 形成

  URI.encode_www_form_component(ele)
  

  示例

  URI.encode_www_form(['foo', :bar, 0])
  # => "foo&bar&0"
  

类似数组的 enum 的元素可以是混合的

URI.encode_www_form([['foo', 0], ['bar', 1, 2], ['baz'], :bat])
# => "foo=0&bar=1&baz&bat"

当 enum 是类似哈希的时，每个 key/value 对都转换为一个或多个字段

• 如果 value 是 可转换为数组的，则 value 中的每个元素 ele 都与 key 配对形成一个字段

  name = URI.encode_www_form_component(key, enc)
  value = URI.encode_www_form_component(ele, enc)
  "#{name}=#{value}"
  

  示例

  URI.encode_www_form({foo: [:bar, 1], baz: [:bat, :bam, 2]})
  # => "foo=bar&foo=1&baz=bat&baz=bam&baz=2"
  

• 否则，key 和 value 配对形成一个字段

  name = URI.encode_www_form_component(key, enc)
  value = URI.encode_www_form_component(value, enc)
  "#{name}=#{value}"
  

  示例

  URI.encode_www_form({foo: 0, bar: 1, baz: 2})
  # => "foo=0&bar=1&baz=2"
  

类似哈希的 enum 的元素可以是混合的

URI.encode_www_form({foo: [0, 1], bar: 2})
# => "foo=0&foo=1&bar=2"

# File lib/uri/common.rb, line 501
def self.encode_www_form(enum, enc=nil)
  enum.map do |k,v|
    if v.nil?
      encode_www_form_component(k, enc)
    elsif v.respond_to?(:to_ary)
      v.to_ary.map do |w|
        str = encode_www_form_component(k, enc)
        unless w.nil?
          str << '='
          str << encode_www_form_component(w, enc)
        end
      end.join('&')
    else
      str = encode_www_form_component(k, enc)
      str << '='
      str << encode_www_form_component(v, enc)
    end
  end.join('&')
end

返回从给定字符串 str 导出的 URL 编码字符串。

返回的字符串

• 保留

  • 字符 '*'、'.'、'-' 和 '_'。

  • 范围 'a'..'z'、'A'..'Z' 和 '0'..'9' 中的字符。

  示例

  URI.encode_www_form_component('*.-_azAZ09')
  # => "*.-_azAZ09"
  

• 转换

  • 字符 ' ' 转换为字符 '+'。

  • 任何其他字符都转换为“百分比表示法”；字符 c 的百分比表示法为 '%%%X' % c.ord。

  示例

  URI.encode_www_form_component('Here are some punctuation characters: ,;?:')
  # => "Here+are+some+punctuation+characters%3A+%2C%3B%3F%3A"
  

编码

• 如果 str 的编码为 Encoding::ASCII_8BIT，则参数 enc 将被忽略。

• 否则，str 首先转换为 Encoding::UTF_8（使用适当的字符替换），然后转换为编码 enc。

在这两种情况下，返回的字符串都强制使用编码 Encoding::US_ASCII。

相关：URI.encode_uri_component（将 ' ' 编码为 '%20'）。

# File lib/uri/common.rb, line 335
def self.encode_www_form_component(str, enc=nil)
  _encode_uri_component(/[^*\-.0-9A-Z_a-z]/, TBLENCWWWCOMP_, str, enc)
end

返回一个使用给定的 scheme、arguments 和 default 构造的新对象。

• 新对象是 URI.scheme_list[scheme.upcase] 的实例。

• 该对象通过使用 scheme 和 arguments 调用类初始化器进行初始化。参见 URI::Generic.new。

示例

values = ['john.doe', 'www.example.com', '123', nil, '/forum/questions/', nil, 'tag=networking&order=newest', 'top']
URI.for('https', *values)
# => #<URI::HTTPS https://[email protected]:123/forum/questions/?tag=networking&order=newest#top>
URI.for('foo', *values, default: URI::HTTP)
# => #<URI::HTTP foo://[email protected]:123/forum/questions/?tag=networking&order=newest#top>

# File lib/uri/common.rb, line 123
def self.for(scheme, *arguments, default: Generic)
  const_name = scheme.to_s.upcase

  uri_class = INITIAL_SCHEMES[const_name]
  uri_class ||= if /\A[A-Z]\w*\z/.match?(const_name) && Schemes.const_defined?(const_name, false)
    Schemes.const_get(const_name, false)
  end
  uri_class ||= default

  return uri_class.new(scheme, *arguments)
end

根据 RFC 2396 合并给定的 URI 字符串 str。

str 中的每个字符串在合并之前都会被转换为 RFC3986 URI。

示例

URI.join("http://example.com/","main.rbx")
# => #<URI::HTTP http://example.com/main.rbx>

URI.join('http://example.com', 'foo')
# => #<URI::HTTP http://example.com/foo>

URI.join('http://example.com', '/foo', '/bar')
# => #<URI::HTTP http://example.com/bar>

URI.join('http://example.com', '/foo', 'bar')
# => #<URI::HTTP http://example.com/bar>

URI.join('http://example.com', '/foo/', 'bar')
# => #<URI::HTTP http://example.com/foo/bar>

# File lib/uri/common.rb, line 211
def self.join(*str)
  RFC3986_PARSER.join(*str)
end

允许打开各种资源，包括 URI。

如果第一个参数响应 ‘open’ 方法，则使用其余参数调用其 ‘open’ 方法。

如果第一个参数是字符串，并且以 (protocol):// 开头，则由 URI.parse 解析。如果解析后的对象响应 ‘open’ 方法，则使用其余参数调用其 ‘open’ 方法。

否则，调用 Kernel#open。

OpenURI::OpenRead#open 提供 URI::HTTP#open、URI::HTTPS#open 和 URI::FTP#open、Kernel#open。

我们可以接受以 http://、https:// 和 ftp:// 开头的 URI 和字符串。在这些情况下，打开的文件对象将由 OpenURI::Meta 扩展。

# File lib/open-uri.rb, line 23
def self.open(name, *rest, &block)
  if name.respond_to?(:open)
    name.open(*rest, &block)
  elsif name.respond_to?(:to_str) &&
        %r{\A[A-Za-z][A-Za-z0-9+\-\.]*://} =~ name &&
        (uri = URI.parse(name)).respond_to?(:open)
    uri.open(*rest, &block)
  else
    super
  end
end

返回一个使用给定字符串 uri 构造的新 URI 对象。

URI.parse('https://[email protected]:123/forum/questions/?tag=networking&order=newest#top')
# => #<URI::HTTPS https://[email protected]:123/forum/questions/?tag=networking&order=newest#top>
URI.parse('http://[email protected]:123/forum/questions/?tag=networking&order=newest#top')
# => #<URI::HTTP http://[email protected]:123/forum/questions/?tag=networking&order=newest#top>

建议如果字符串 uri 可能包含无效的 URI 字符，则先对其进行 ::escape。

# File lib/uri/common.rb, line 184
def self.parse(uri)
  RFC3986_PARSER.parse(uri)
end

注册给定的 klass 作为解析具有给定 scheme 的 URI 时要实例化的类。

URI.register_scheme('MS_SEARCH', URI::Generic) # => URI::Generic
URI.scheme_list['MS_SEARCH']                   # => URI::Generic

请注意，在对 scheme 调用 String#upcase 之后，它必须是有效的常量名称。

# File lib/uri/common.rb, line 79
def self.register_scheme(scheme, klass)
  Schemes.const_set(scheme.to_s.upcase, klass)
end

返回已定义方案的哈希表。

URI.scheme_list
# =>
{"MAILTO"=>URI::MailTo,
 "LDAPS"=>URI::LDAPS,
 "WS"=>URI::WS,
 "HTTP"=>URI::HTTP,
 "HTTPS"=>URI::HTTPS,
 "LDAP"=>URI::LDAP,
 "FILE"=>URI::File,
 "FTP"=>URI::FTP}

相关：URI.register_scheme。

# File lib/uri/common.rb, line 97
def self.scheme_list
  Schemes.constants.map { |name|
    [name.to_s.upcase, Schemes.const_get(name)]
  }.to_h
end

返回一个包含 9 个元素的数组，表示从字符串 uri 形成的 URI 的各个部分；每个数组元素都是字符串或 nil。

names = %w[scheme userinfo host port registry path opaque query fragment]
values = URI.split('https://[email protected]:123/forum/questions/?tag=networking&order=newest#top')
names.zip(values)
# =>
[["scheme", "https"],
 ["userinfo", "john.doe"],
 ["host", "www.example.com"],
 ["port", "123"],
 ["registry", nil],
 ["path", "/forum/questions/"],
 ["opaque", nil],
 ["query", "tag=networking&order=newest"],
 ["fragment", "top"]]

# File lib/uri/common.rb, line 170
def self.split(uri)
  RFC3986_PARSER.split(uri)
end