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:
uri/punycode.cruri/uri_parser.cr
uri.cr
Constructors
- .new(scheme = nil, host = nil, port = nil, path = "", query = nil, user = nil, password = nil, fragment = nil)
-
.parse(raw_url : String) : URI
Parses the given raw_url into an URI.
Class Method Summary
-
.default_port(scheme : String) : Int32?
Returns the default port for the given scheme if known, otherwise returns
nil
. -
.escape(string : String, io : IO, space_to_plus = false)
URL-encodes the given string and writes the result to io.
-
.escape(string : String, space_to_plus = false) : String
URL-encodes the given string.
-
.escape(string : String, io : IO, space_to_plus = false, &block)
URL-encodes the given string and writes the result to io.
-
.escape(string : String, space_to_plus = false, &block) : String
URL-encodes the given string.
-
.reserved?(byte) : Bool
Returns whether given byte is reserved character defined in RFC 3986.
-
.set_default_port(scheme : String, port : Int32?) : Nil
Registers the default port for the given scheme.
-
.unescape(string : String, io : IO, plus_to_space = false)
URL-decodes the given string and writes the result to io.
-
.unescape(string : String, plus_to_space = false) : String
URL-decodes the given string.
-
.unescape(string : String, io : IO, plus_to_space = false, &block)
URL-decodes the given string and writes the result to io.
-
.unescape(string : String, plus_to_space = false, &block) : String
URL-decodes the given string.
-
.unreserved?(byte) : Bool
Returns whether given byte is unreserved character defined in RFC 3986.
Instance Method Summary
- #==(other : self)
-
#absolute? : Bool
Returns
true
if URI has a scheme specified. -
#fragment : String?
Returns the fragment component of the URI.
-
#fragment=(fragment : String?)
Sets the fragment component of the URI.
-
#full_path : String
Returns the full path of this URI.
- #hash(hasher)
-
#host : String?
Returns the host component of the URI.
-
#host=(host : String?)
Sets the host component of the URI.
-
#hostname
Returns the host part of the URI and unwrap brackets for IPv6 addresses.
-
#normalize : URI
Returns a normalized copy of this URI.
-
#normalize! : URI
Normalizes this URI instance.
-
#opaque? : Bool
Returns
true
if this URI is opaque. -
#password : String?
Returns the password component of the URI.
-
#password=(password : String?)
Sets the password component of the URI.
-
#path : String
Returns the path component of the URI.
-
#path=(path : String)
Sets the path component of the URI.
-
#port : Int32?
Returns the port component of the URI.
-
#port=(port : Int32?)
Sets the port component of the URI.
-
#query : String?
Returns the query component of the URI.
-
#query=(query : String?)
Sets the query component of the URI.
-
#relative? : Bool
Returns
true
if URI does not have a scheme specified. -
#scheme : String?
Returns the scheme component of the URI.
-
#scheme=(scheme : String?)
Sets the scheme component of the URI.
- #to_s(io : IO) : Nil
-
#user : String?
Returns the user component of the URI.
-
#user=(user : String?)
Sets the user component of the URI.
-
#userinfo
Returns the user-information component containing the provided username and password.
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) : selffrom_json(string_or_io) : self from_json, from_yaml(string_or_io : String | IO) : self from_yaml
Constructor Detail
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
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
URL-encodes the given string and writes the result to io.
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"
URL-encodes the given string and writes the result to io.
This method requires a block.
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"
Returns whether given byte is reserved character defined in RFC 3986.
Reserved characters are ':', '/', '?', '#', '[', ']', '@', '!', '$', '&', "'", '(', ')', '*', '+', ',', ';' and '='.
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
URL-decodes the given string and writes the result to io.
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"
URL-decodes the given string and writes the result to io.
This method requires a block.
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.
Returns whether given byte is unreserved character defined in RFC 3986.
Unreserved characters are ASCII letters, ASCII digits, '_', '.', '-' and '~'.
Instance Method Detail
Returns the fragment component of the URI.
require "uri"
URI.parse("http://foo.com/bar#section1").fragment # => "section1"
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"
Returns the host component of the URI.
require "uri"
URI.parse("http://foo.com").host # => "foo.com"
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]"
Returns a normalized copy of this URI.
See #normalize!
for details.
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/"
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 (/
).
Returns the password component of the URI.
require "uri"
URI.parse("http://admin:password@foo.com").password # => "password"
Returns the path component of the URI.
require "uri"
URI.parse("http://foo.com/bar").path # => "/bar"
Returns the port component of the URI.
require "uri"
URI.parse("http://foo.com:5432").port # => 5432
Returns the query component of the URI.
require "uri"
URI.parse("http://foo.com/bar?q=1").query # => "q=1"
Returns the scheme component of the URI.
require "uri"
URI.parse("http://foo.com").scheme # => "http"
URI.parse("mailto:alice@example.com").scheme # => "mailto"
Returns the user component of the URI.
require "uri"
URI.parse("http://admin:password@foo.com").user # => "admin"
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"