Module: URI
Relationships & Source Files | |
Namespace Children | |
Modules:
| |
Classes:
| |
Exceptions:
| |
Extension / Inclusion / Inheritance Descendants | |
Included In:
| |
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
-
DEFAULT_PARSER =
URI::Parser.new
Parser.new
-
Parser =
# File 'lib/uri/common.rb', line 18RFC2396_Parser
-
REGEXP =
# File 'lib/uri/common.rb', line 17RFC2396_REGEXP
-
RFC3986_PARSER =
# File 'lib/uri/common.rb', line 19RFC3986_Parser.new
Class Method Summary
-
.decode_www_form(str, enc = Encoding::UTF_8, separator: '&', use__charset_: false, isindex: false)
Decode URL-encoded form data from given
str
. -
.decode_www_form_component(str, enc = Encoding::UTF_8)
Decode given
str
of URL-encoded form data. -
.encode_www_form(enum, enc = nil)
Generate URL-encoded form data from given
enum
. -
.encode_www_form_component(str, enc = nil)
Encode given
str
to URL-encoded form data. -
.extract(str, schemes = nil, &block)
Synopsis.
-
.join(*str)
Synopsis.
-
.parse(uri)
Synopsis.
-
.regexp(schemes = nil)
Synopsis.
-
.scheme_list
Returns a Hash of the defined schemes.
-
.split(uri)
Synopsis.
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"}
# 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.
# 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"
# 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
# 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"]
# 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>
# 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
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.
# 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
# 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
# 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]
# File 'lib/uri/common.rb', line 188
def self.split(uri) RFC3986_PARSER.split(uri) end