123456789_123456789_123456789_123456789_123456789_

Module: URI

Relationships & Source Files
Namespace Children
Modules:
Escape, RFC2396_REGEXP
Classes:
FTP, Generic, HTTP, HTTPS, LDAP, LDAPS, MailTo, RFC2396_Parser
Exceptions:
BadURIError, Error, InvalidComponentError, InvalidURIError
Extension / Inclusion / Inheritance Descendants
Included In:
FTP, Generic, HTTP, HTTPS, LDAP, LDAPS, MailTo
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, Escape
Instance Chain:
self, RFC2396_REGEXP
Defined in: lib/uri.rb,
lib/uri/common.rb,
lib/uri/ftp.rb,
lib/uri/generic.rb,
lib/uri/http.rb,
lib/uri/https.rb,
lib/uri/ldap.rb,
lib/uri/ldaps.rb,
lib/uri/mailto.rb,
lib/uri/rfc2396_parser.rb,
lib/uri/rfc3986_parser.rb

Overview

URI is a module providing classes to handle Uniform Resource Identifiers (RFC2396)

Features

  • Uniform handling of handling URIs

  • Flexibility to introduce custom URI schemes

  • Flexibility to have an alternate Parser (or just different patterns and regexp's)

Basic example

require 'uri'

uri = URI("http://foo.com/posts?id=30&limit=5#time=1305298413")
#=> #<URI::HTTP:0x00000000b14880
      URL:http://foo.com/posts?id=30&limit=5#time=1305298413>
uri.scheme
#=> "http"
uri.host
#=> "foo.com"
uri.path
#=> "/posts"
uri.query
#=> "id=30&limit=5"
uri.fragment
#=> "time=1305298413"

uri.to_s
#=> "http://foo.com/posts?id=30&limit=5#time=1305298413"

Adding custom URIs

module URI
  class RSYNC < Generic
    DEFAULT_PORT = 873
  end
  @@schemes['RSYNC'] = RSYNC
end
#=> URI::RSYNC

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

uri = URI("rsync://rsync.foo.com")
#=> #<URI::RSYNC:0x00000000f648c8 URL:rsync://rsync.foo.com>

RFC References

A good place to view an RFC spec is www.ietf.org/rfc.html

Here is a list of all related RFC's.

Class tree

  • Generic (in uri/generic.rb)

    • URI::FTP - (in uri/ftp.rb)

    • URI::HTTP - (in uri/http.rb)

      • URI::HTTPS - (in uri/https.rb)

    • URI::LDAP - (in uri/ldap.rb)

      • URI::LDAPS - (in uri/ldaps.rb)

    • URI::MailTo - (in uri/mailto.rb)

  • Parser - (in uri/common.rb)

  • REGEXP - (in uri/common.rb)

    • URI::REGEXP::PATTERN - (in uri/common.rb)

  • Util - (in uri/common.rb)

  • Escape - (in uri/common.rb)

  • Error - (in uri/common.rb)

    • URI::InvalidURIError - (in uri/common.rb)

    • URI::InvalidComponentError - (in uri/common.rb)

    • URI::BadURIError - (in uri/common.rb)

Copyright Info

Author

Akira Yamada <akira@ruby-lang.org>

Documentation

Akira Yamada <akira@ruby-lang.org> Dmitry V. Sabanin <sdmitry@lrn.ru> Vincent Batts <vbatts@hashbangbash.com>

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$

Constant Summary

Class Method Summary

Escape - Extended

decode

Alias for Escape#unescape.
encode

Alias for Escape#escape.
escape

Synopsis.
unescape

Synopsis.

Class Method Details

.decode_www_form(str, enc = Encoding::UTF_8, separator: '&', use__charset_: false, isindex: false)

Decode URL-encoded form data from given str.

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

This refers url.spec.whatwg.org/#concept-urlencoded-parser , so this supports only &-separator, don't support ;-separator.

ary = URI.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[ary]            # => {"a"=>"2", "b"=>"3"}

See .decode_www_form_component, .encode_www_form

Raises:

  • (ArgumentError)
[ GitHub ] 

  


# File 'lib/uri/common.rb', line 450



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


  








  

    .decode_www_form_component(str, enc = Encoding::UTF_8)  
  



  

    

Decode given str of URL-encoded form data.



This decodes + to SP.



See .encode_www_form_component, .decode_www_form


  





  
Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/uri/common.rb', line 382



def self.decode_www_form_component(str, enc=Encoding::UTF_8)
  raise ArgumentError, "invalid %-encoding (#{str})" if /%(?!\h\h)/ =~ str
  str.b.gsub(/\+|%\h\h/, TBLDECWWWCOMP_).force_encoding(enc)
end


  








  

    .encode_www_form(enum, enc = nil)  
  



  

    

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 URI.encode_www_form_component(str).



This method doesn't convert the encoding of given 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 are encoded in an HTML5 ASCII incompatible encoding are converted to UTF-8.)



This method doesn't handle files.  When you send a file, use multipart/form-data.



This refers url.spec.whatwg.org/#concept-urlencoded-serializer



URI.encode_www_form([["q", "ruby"], ["lang", "en"]])
#=> "q=ruby&lang=en"
URI.encode_www_form("q" => "ruby", "lang" => "en")
#=> "q=ruby&lang=en"
URI.encode_www_form("q" => ["ruby", "perl"], "lang" => "en")
#=> "q=ruby&q=perl&lang=en"
URI.encode_www_form([["q", "ruby"], ["q", "perl"], ["lang", "en"]])
#=> "q=ruby&q=perl&lang=en"



See .encode_www_form_component, .decode_www_form


  



  [ GitHub ]


  

  


# File 'lib/uri/common.rb', line 414



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


  








  

    .encode_www_form_component(str, enc = nil)  
  



  

    

Encode given str to URL-encoded form data.



This method doesn't convert *, -, ., 0-9, A-Z, _, a-z, but does convert SP (ASCII space) to + and converts others to %XX.



If enc is given, convert str to the encoding before percent encoding.



This is an implementation of www.w3.org/TR/2013/CR-html5-20130806/forms.html#url-encoded-form-data



See .decode_www_form_component, .encode_www_form


  



  [ GitHub ]


  

  


# File 'lib/uri/common.rb', line 364



def self.encode_www_form_component(str, enc=nil)
  str = str.to_s.dup
  if str.encoding != Encoding::ASCII_8BIT
    if enc && enc != Encoding::ASCII_8BIT
      str.encode!(Encoding::UTF_8, invalid: :replace, undef: :replace)
      str.encode!(enc, fallback: ->(x){"&#{x.ord};"})
    end
    str.force_encoding(Encoding::ASCII_8BIT)
  end
  str.gsub!(/[^*\-.0-9A-Z_a-z]/, TBLENCWWWCOMP_)
  str.force_encoding(Encoding::US_ASCII)
end


  








  

    .extract(str, schemes = nil, &block)  
  



  

    

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"]


  



  [ GitHub ]


  

  


# File 'lib/uri/common.rb', line 292



def self.extract(str, schemes = nil, &block)
  warn "#{caller(1)[0]}: warning: URI.extract is obsolete" if $VERBOSE
  DEFAULT_PARSER.extract(str, schemes, &block)
end


  








  

    .join(*str)  
  



  

    

Synopsis



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



Args


str



String(s) to work with, will be converted to RFC3986 URIs before merging.





Description



Joins URIs.



Usage



require 'uri'

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

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

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

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

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


  



  [ GitHub ]


  

  


# File 'lib/uri/common.rb', line 264



def self.join(*str)
  RFC3986_PARSER.join(*str)
end


  








  

    .parse(uri)  
  



  

    

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"



It's recommended to first .escape the provided uri_str if there are any invalid URI characters.


  



  [ GitHub ]


  

  


# File 'lib/uri/common.rb', line 226



def self.parse(uri)
  RFC3986_PARSER.parse(uri)
end


  








  

    .regexp(schemes = nil)  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/uri/common.rb', line 328



def self.regexp(schemes = nil)
  warn "#{caller(1)[0]}: warning: URI.regexp is obsolete" if $VERBOSE
  DEFAULT_PARSER.make_regexp(schemes)
end


  








  

    .scheme_list  
  



  

    

Returns a Hash of the defined schemes


  



  [ GitHub ]


  

  


# File 'lib/uri/common.rb', line 136



def self.scheme_list
  @@schemes
end


  








  

    .split(uri)  
  



  

    

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]


  



  [ GitHub ]


  

  


# File 'lib/uri/common.rb', line 188



def self.split(uri)
  RFC3986_PARSER.split(uri)
end