class URI

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"

Defined in:

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class Reference

==(other : self)
==(other : JSON::Any)
==(other : YAML::Any)
==(other)
==
, dup dup, hash(hasher) hash, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference)
same?(other : Nil)
same?
, to_s(io : IO) : Nil to_s

Constructor methods inherited from class Reference

new new

Instance methods inherited from class Object

!=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other)
===
, =~(other) =~, class class, dup dup, hash(hasher)
hash
hash
, inspect(io : IO) : Nil
inspect : String
inspect
, itself itself, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, tap(&block) tap, to_json(io : IO)
to_json
to_json
, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, indent : String = " ")
to_pretty_json
, to_s : String
to_s(io : IO) : Nil
to_s
, to_yaml(io : IO)
to_yaml
to_yaml
, try(&block) try, unsafe_as(type : T.class) forall T unsafe_as

Constructor methods inherited from class Object

from_json(string_or_io, root : String) : self
from_json(string_or_io) : self
from_json
, from_yaml(string_or_io : String | IO) : self from_yaml

Constructor Detail

def self.new(scheme = nil, host = nil, port = nil, path = "", query = nil, user = nil, password = nil, fragment = nil) #

def self.parse(raw_url : String) : URI #

Parses the given raw_url into an URI. The raw_url may be relative or absolute.

require "uri"

uri = URI.parse("http://crystal-lang.org") # => #<URI:0x1068a7e40 @scheme="http", @host="crystal-lang.org", ... >
uri.scheme                                 # => "http"
uri.host                                   # => "crystal-lang.org"

Class Method Detail

def self.default_port(scheme : String) : Int32? #

Returns the default port for the given scheme if known, otherwise returns nil.

require "uri"

URI.default_port "http"  # => 80
URI.default_port "ponzi" # => nil

def self.escape(string : String, io : IO, space_to_plus = false) #

URL-encodes the given string and writes the result to io.


def self.escape(string : String, space_to_plus = false) : String #

URL-encodes the given string.

If space_to_plus is true, all space characters (0x20) are replaced by '+' and '+' is encoded to '%2B'. E.g. application/x-www-form-urlencoded wants this replace.

require "uri"

URI.escape("'Stop!' said Fred")                      # => "%27Stop%21%27%20said%20Fred"
URI.escape("'Stop!' said Fred", space_to_plus: true) # => "%27Stop%21%27+said+Fred"

def self.escape(string : String, io : IO, space_to_plus = false, &block) #

URL-encodes the given string and writes the result to io.

This method requires a block.


def self.escape(string : String, space_to_plus = false, &block) : String #

URL-encodes the given string.

This method requires a block, the block is called with each byte whose codepoint is less than 0x80. The bytes that return true in the block are not escaped, other bytes are escaped.

require "uri"

# Escape URI path
URI.escape("/foo/file?(1).txt") do |byte|
  URI.unreserved?(byte) || byte.chr == '/'
end
# => "/foo/file%3F%281%29.txt"

def self.reserved?(byte) : Bool #

Returns whether given byte is reserved character defined in RFC 3986.

Reserved characters are ':', '/', '?', '#', '[', ']', '@', '!', '$', '&', "'", '(', ')', '*', '+', ',', ';' and '='.


def self.set_default_port(scheme : String, port : Int32?) : Nil #

Registers the default port for the given scheme.

If port is nil, the existing default port for the scheme, if any, will be unregistered.

require "uri"

URI.set_default_port "ponzi", 9999

def self.unescape(string : String, io : IO, plus_to_space = false) #

URL-decodes the given string and writes the result to io.


def self.unescape(string : String, plus_to_space = false) : String #

URL-decodes the given string.

If plus_to_space is true, all plus characters (0x2B) will be replaced by ' '. E.g. application/x-www-form-urlencoded wants this replace.

require "uri"

URI.unescape("%27Stop%21%27%20said%20Fred")                  # => "'Stop!' said Fred"
URI.unescape("%27Stop%21%27+said+Fred", plus_to_space: true) # => "'Stop!' said Fred"

def self.unescape(string : String, io : IO, plus_to_space = false, &block) #

URL-decodes the given string and writes the result to io.

This method requires a block.


def self.unescape(string : String, plus_to_space = false, &block) : String #

URL-decodes the given string.

This method requires a block, the block is called with each byte whose codepoint is less than 0x80. The bytes that return true in the block are not unescaped, other bytes are unescaped.


def self.unreserved?(byte) : Bool #

Returns whether given byte is unreserved character defined in RFC 3986.

Unreserved characters are ASCII letters, ASCII digits, '_', '.', '-' and '~'.


Instance Method Detail

def ==(other : self) #

def absolute? : Bool #

Returns true if URI has a scheme specified.


def fragment : String? #

Returns the fragment component of the URI.

require "uri"

URI.parse("http://foo.com/bar#section1").fragment # => "section1"

def fragment=(fragment : String?) #

Sets the fragment component of the URI.


def full_path : String #

Returns the full path of this URI.

require "uri"

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

def hash(hasher) #

def host : String? #

Returns the host component of the URI.

require "uri"

URI.parse("http://foo.com").host # => "foo.com"

def host=(host : String?) #

Sets the host component of the URI.


def hostname #

Returns the host part of the URI and unwrap brackets for IPv6 addresses.

require "uri"

URI.parse("http://[::1]/bar").hostname # => "::1"
URI.parse("http://[::1]/bar").host     # => "[::1]"

def normalize : URI #

Returns a normalized copy of this URI.

See #normalize! for details.


def normalize! : URI #

Normalizes this URI instance.

The following normalizations are applied to the individual components (if available):

  • #scheme is lowercased.
  • #host is lowercased.
  • #port is removed if it is the .default_port? of the scheme.
  • #path is resolved to a minimal, semantical equivalent representation removing dot segments /. and /...
uri = URI.parse("HTTP://example.COM:80/./foo/../bar/")
uri.normalize!
uri # => "http://example.com/bar/"

def opaque? : Bool #

Returns true if this URI is opaque.

A URI is considered opaque if it has a #scheme but no hierachical part, i.e. no #host and the first character of #path is not a slash (/).


def password : String? #

Returns the password component of the URI.

require "uri"

URI.parse("http://admin:password@foo.com").password # => "password"

def password=(password : String?) #

Sets the password component of the URI.


def path : String #

Returns the path component of the URI.

require "uri"

URI.parse("http://foo.com/bar").path # => "/bar"

def path=(path : String) #

Sets the path component of the URI.


def port : Int32? #

Returns the port component of the URI.

require "uri"

URI.parse("http://foo.com:5432").port # => 5432

def port=(port : Int32?) #

Sets the port component of the URI.


def query : String? #

Returns the query component of the URI.

require "uri"

URI.parse("http://foo.com/bar?q=1").query # => "q=1"

def query=(query : String?) #

Sets the query component of the URI.


def relative? : Bool #

Returns true if URI does not have a scheme specified.


def scheme : String? #

Returns the scheme component of the URI.

require "uri"

URI.parse("http://foo.com").scheme           # => "http"
URI.parse("mailto:alice@example.com").scheme # => "mailto"

def scheme=(scheme : String?) #

Sets the scheme component of the URI.


def to_s(io : IO) : Nil #

def user : String? #

Returns the user component of the URI.

require "uri"

URI.parse("http://admin:password@foo.com").user # => "admin"

def user=(user : String?) #

Sets the user component of the URI.


def userinfo #

Returns the user-information component containing the provided username and password.

require "uri"

uri = URI.parse "http://admin:password@foo.com"
uri.userinfo # => "admin:password"