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.

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(string : String, *, space_to_plus : Bool = false) : String: URL-encodes a string.
• .encode(string : String, io : IO, *, space_to_plus : Bool = false) : Nil: URL-encodes a string to an IO.
• .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.

The main difference is that .encode_www_form encodes reserved characters (see .reserved?), while .encode does not. The decode methods are identical except for the handling of + characters.

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

Defined in:

http-params-serializable/ext/uri.cr

Class Method Summary

• .from_http_param(value : String)

  Parse URI from an HTTP param.

Instance Method Summary

• #to_http_param(builder : HTTP::Params::Builder, key : String)

  Put self as an HTTP param into the builder at key.

• #to_http_param

  Return self as an HTTP param string.

Class Method Detail

Instance Method Detail