class URI

• URI
• Reference
• Object

Overview

This class represents a URI reference as defined by RFC 3986: Uniform Resource Identifier (URI): Generic Syntax.

This class provides constructors for creating URI instances from their components or by parsing their string forms and methods for accessing the various components of an instance.

NOTE To use URI, you must explicitly import it with require "uri"

Basic example:

require "uri"

uri = URI.parse "http://foo.com/posts?id=30&limit=5#time=1305298413"
# => #<URI:0x1003f1e40 @scheme="http", @host="foo.com", @port=nil, @path="/posts", @query="id=30&limit=5", ... >
uri.scheme # => "http"
uri.host   # => "foo.com"
uri.query  # => "id=30&limit=5"
uri.to_s   # => "http://foo.com/posts?id=30&limit=5#time=1305298413"

Resolution and Relativization

Resolution is the process of resolving one URI against another, base URI. The resulting URI is constructed from components of both URIs in the manner specified by RFC 3986 section 5.2, taking components from the base URI for those not specified in the original. For hierarchical URIs, the path of the original is resolved against the path of the base and then normalized. See #resolve for examples.

Relativization is the inverse of resolution as that it procures an URI that resolves to the original when resolved against the base.

For normalized URIs, the following is true:

a.relativize(a.resolve(b)) # => b
a.resolve(a.relativize(b)) # => b

This operation is often useful when constructing a document containing URIs that must be made relative to the base URI of the document wherever possible.

URL Encoding

This class provides a number of methods for encoding and decoding strings using URL Encoding (also known as Percent Encoding) as defined in RFC 3986 as well as x-www-form-urlencoded.

Each method has two variants, one returns a string, the other writes directly to an IO.

• .decode(string : String, *, plus_to_space : Bool = false) : String: Decodes a URL-encoded string.
• .decode(string : String, io : IO, *, plus_to_space : Bool = false) : Nil: Decodes a URL-encoded string to an IO.
• .encode_path(string : String) : String: URL-encodes a string.
• .encode_path(string : String, io : IO) : Nil: URL-encodes a string to an IO.
• .encode_path_segment(string : String) : String: URL-encodes a string, escaping /.
• .encode_path_segment(string : String, io : IO) : Nil: URL-encodes a string to an IO, escaping /.
• .decode_www_form(string : String, *, plus_to_space : Bool = true) : String: Decodes an x-www-form-urlencoded string component.
• .decode_www_form(string : String, io : IO, *, plus_to_space : Bool = true) : Nil: Decodes an x-www-form-urlencoded string component to an IO.
• .encode_www_form(string : String, *, space_to_plus : Bool = true) : String: Encodes a string as a x-www-form-urlencoded component.
• .encode_www_form(string : String, io : IO, *, space_to_plus : Bool = true) : Nil: Encodes a string as a x-www-form-urlencoded component to an IO.

.encode_www_form encodes white space () as +, while .encode_path and .encode_path_segment encode it as %20. The decode methods differ regarding the handling of + characters, respectively.

NOTE URI::Params provides a higher-level API for handling x-www-form-urlencoded serialized data.

Defined in:

Instance Method Summary

• #absolutize!(base : URI)
• #join(this : String, that : String) : String

  Returns a new clean path a = URI.parse("http://www.mysite.com/l1/l2/index.html") a.join("same.html") # => "http://www.mysite.com/l1/l2/same.html" a.join("./same.html") # => "http://www.mysite.com/l1/l2/same.html" a.join("../higher.html") # => "http://www.mysite.com/l1/higher.html" a.join("../../higher.html") # => "http://www.mysite.com/higher.html" a.join("../../../higher.html") # => "http://www.mysite.com/higher.html" a = URI.parse("http://www.mysite.com/l1/l2/ a.join("child.html") # => "http://www.mysite.com/l1/l2/child.html" a.join("l3/") # => "http://www.mysite.com/l1/l2/l3/" a.join("new_l2/") # => "http://www.mysite.com/l1/new_l2/"

• #ljoin!(other : String)
• #rjoin!(other : String)
• #same_domain?(other : URI)

Instance Method Detail

a = URI.parse("http://www.mysite.com/l1/l2/index.html")
a.join("same.html") # => "http://www.mysite.com/l1/l2/same.html"
a.join("./same.html") # => "http://www.mysite.com/l1/l2/same.html"
a.join("../higher.html") # => "http://www.mysite.com/l1/higher.html"
a.join("../../higher.html") # => "http://www.mysite.com/higher.html"
a.join("../../../higher.html") # => "http://www.mysite.com/higher.html"
a = URI.parse("http://www.mysite.com/l1/l2/
a.join("child.html") # => "http://www.mysite.com/l1/l2/child.html"
a.join("l3/") # => "http://www.mysite.com/l1/l2/l3/"
a.join("new_l2/") # => "http://www.mysite.com/l1/new_l2/"