Extended maintenance of Ruby versions 1.8.7 and 1.9.2 will end on July 31, 2014. Read more

In Files

  • uri.rb
  • uri/common.rb
  • uri/ftp.rb
  • uri/generic.rb
  • uri/http.rb
  • uri/https.rb
  • uri/ldap.rb
  • uri/ldaps.rb
  • uri/mailto.rb

URI

URI support for Ruby

Author

Akira Yamada <akira@ruby-lang.org>

Documentation

Akira Yamada <akira@ruby-lang.org>, Dmitry V. Sabanin <sdmitry@lrn.ru>

License

Copyright © 2001 akira yamada <akira@ruby-lang.org> You can redistribute it and/or modify it under the same term as Ruby.

Revision

$Id: uri.rb 25189 2009-10-02 12:04:37Z akr $

See URI for documentation

uri/common.rb

Author

Akira Yamada <akira@ruby-lang.org>

Revision

$Id: common.rb 34407 2012-01-31 19:11:05Z tenderlove $

License

You can redistribute it and/or modify it under the same term as Ruby.

Constants

DEFAULT_PARSER

Public Class Methods

decode_www_form(str, enc=Encoding::UTF_8) click to toggle source

Decode URL-encoded form data from given str.

This decodes application/x-www-form-urlencoded data and returns array of key-value array. This internally uses ::decode_www_form_component.

charset hack is not supported now because the mapping from given charset to Ruby's encoding is not clear yet. see also www.w3.org/TR/html5/syntax.html#character-encodings-0

This refers www.w3.org/TR/html5/forms.html#url-encoded-form-data

ary = ::decode_www_form(“a=1&a=2&b=3”) p ary #=> [[‘a’, ‘1’], [‘a’, ‘2’], [‘b’, ‘3’]] p ary.assoc(‘a’).last #=> ‘1’ p ary.assoc(‘b’).last #=> ‘3’ p ary.rassoc(‘a’).last #=> ‘2’ p Hash # => {“a”=>“2”, “b”=>“3”}

See ::decode_www_form_component, ::encode_www_form

 
               # File uri/common.rb, line 823
def self.decode_www_form(str, enc=Encoding::UTF_8)
  return [] if str.empty?
  unless /\A#{WFKV_}*=#{WFKV_}*(?:[;&]#{WFKV_}*=#{WFKV_}*)*\z/o =~ str
    raise ArgumentError, "invalid data of application/x-www-form-urlencoded (#{str})"
  end
  ary = []
  $&.scan(/([^=;&]+)=([^;&]*)/) do
    ary << [decode_www_form_component($1, enc), decode_www_form_component($2, enc)]
  end
  ary
end
            
decode_www_form_component(str, enc=Encoding::UTF_8) click to toggle source

Decode given str of URL-encoded form data.

This decods + to SP.

See ::encode_www_form_component, ::decode_www_form

 
               # File uri/common.rb, line 764
def self.decode_www_form_component(str, enc=Encoding::UTF_8)
  raise ArgumentError, "invalid %-encoding (#{str})" unless /\A(?:%\h\h|[^%]+)*\z/ =~ str
  str.gsub(/\+|%\h\h/, TBLDECWWWCOMP_).force_encoding(enc)
end
            
encode_www_form(enum) click to toggle source

Generate URL-encoded form data from given enum.

This generates application/x-www-form-urlencoded data defined in HTML5 from given an Enumerable object.

This internally uses ::encode_www_form_component.

This doesn’t convert encodings of give items, so convert them before call this method if you want to send data as other than original encoding or mixed encoding data. (strings which is encoded in HTML5 ASCII incompatible encoding is converted to UTF-8)

This doesn’t treat files. When you send a file, use multipart/form-data.

This refers www.w3.org/TR/html5/forms.html#url-encoded-form-data

See ::encode_www_form_component, ::decode_www_form

 
               # File uri/common.rb, line 786
def self.encode_www_form(enum)
  str = nil
  enum.each do |k,v|
    if str
      str << '&'
    else
      str = nil.to_s
    end
    str << encode_www_form_component(k)
    str << '='
    str << encode_www_form_component(v)
  end
  str
end
            
encode_www_form_component(str) click to toggle source

Encode given str to URL-encoded form data.

This doesn’t convert *, -, ., 0-9, A-Z, _, a-z, does convert SP to +, and convert others to %XX.

This refers www.w3.org/TR/html5/forms.html#url-encoded-form-data

See ::decode_www_form_component, ::encode_www_form

 
               # File uri/common.rb, line 747
def self.encode_www_form_component(str)
  str = str.to_s
  if HTML5ASCIIINCOMPAT.include?(str.encoding)
    str = str.encode(Encoding::UTF_8)
  else
    str = str.dup
  end
  str.force_encoding(Encoding::ASCII_8BIT)
  str.gsub!(/[^*\-.0-9A-Z_a-z]/, TBLENCWWWCOMP_)
  str.force_encoding(Encoding::US_ASCII)
end
            
extract(str, schemes = nil, &block) click to toggle source

Synopsis

URI::extract(str[, schemes][,&blk])

Args

str

String to extract URIs from.

schemes

Limit URI matching to a specific schemes.

Description

Extracts URIs from a string. If block given, iterates through all matched URIs. Returns nil if block given or array with matches.

Usage

require "uri"

URI.extract("text here http://foo.example.org/bla and here mailto:test@example.com and here also.")
# => ["http://foo.example.com/bla", "mailto:test@example.com"]
 
               # File uri/common.rb, line 680
def self.extract(str, schemes = nil, &block)
  DEFAULT_PARSER.extract(str, schemes, &block)
end
            
join(*str) click to toggle source

Synopsis

URI::join(str[, str, ...])

Args

str

String(s) to work with

Description

Joins URIs.

Usage

require 'uri'

p URI.join("http://localhost/","main.rbx")
# => #<URI::HTTP:0x2022ac02 URL:http://localhost/main.rbx>
 
               # File uri/common.rb, line 652
def self.join(*str)
  DEFAULT_PARSER.join(*str)
end
            
parse(uri) click to toggle source

Synopsis

URI::parse(uri_str)

Args

uri_str

String with URI.

Description

Creates one of the URI’s subclasses instance from the string.

Raises

URI::InvalidURIError

Raised if URI given is not a correct one.

Usage

require 'uri'

uri = URI.parse("http://www.ruby-lang.org/")
p uri
# => #<URI::HTTP:0x202281be URL:http://www.ruby-lang.org/>
p uri.scheme
# => "http"
p uri.host
# => "www.ruby-lang.org"
 
               # File uri/common.rb, line 627
def self.parse(uri)
  DEFAULT_PARSER.parse(uri)
end
            
regexp(schemes = nil) click to toggle source

Synopsis

URI::regexp([match_schemes])

Args

match_schemes

Array of schemes. If given, resulting regexp matches to URIs whose scheme is one of the match_schemes.

Description

Returns a Regexp object which matches to URI-like strings. The Regexp object returned by this method includes arbitrary number of capture group (parentheses). Never rely on it’s number.

Usage

require 'uri'

# extract first URI from html_string
html_string.slice(URI.regexp)

# remove ftp URIs
html_string.sub(URI.regexp(['ftp'])

# You should not rely on the number of parentheses
html_string.scan(URI.regexp) do |*matches|
  p $&
end
 
               # File uri/common.rb, line 715
def self.regexp(schemes = nil)
  DEFAULT_PARSER.make_regexp(schemes)
end
            
scheme_list() click to toggle source
 
               # File uri/common.rb, line 540
def self.scheme_list
  @@schemes
end
            
split(uri) click to toggle source

Synopsis

URI::split(uri)

Args

uri

String with URI.

Description

Splits the string on following parts and returns array with result:

* Scheme
* Userinfo
* Host
* Port
* Registry
* Path
* Opaque
* Query
* Fragment

Usage

require 'uri'

p URI.split("http://www.ruby-lang.org/")
# => ["http", nil, "www.ruby-lang.org", nil, nil, "/", nil, nil, nil]
 
               # File uri/common.rb, line 592
def self.split(uri)
  DEFAULT_PARSER.split(uri)
end
            

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

blog comments powered by Disqus