Parent

Addressable::URI

This is an implementation of a URI parser based on <a href="RFC">www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>, <a href="RFC">www.ietf.org/rfc/rfc3987.txt">RFC 3987</a>.

Public Class Methods

convert_path(path) click to toggle source

Converts a path to a file scheme URI. If the path supplied is relative, it will be returned as a relative URI. If the path supplied is actually a non-file URI, it will parse the URI as if it had been parsed with Addressable::URI.parse. Handles all of the various Microsoft-specific formats for specifying paths.

@param [String, Addressable::URI, to_str] path

Typically a <code>String</code> path to a file or directory, but
will return a sensible return value if an absolute URI is supplied
instead.

@return [Addressable::URI]

The parsed file scheme URI or the original URI if some other URI
scheme was provided.

@example

base = Addressable::URI.convert_path("/absolute/path/")
uri = Addressable::URI.convert_path("relative/path")
(base + uri).to_s
#=> "file:///absolute/path/relative/path"

Addressable::URI.convert_path(
  "c:\\windows\\My Documents 100%20\\foo.txt"
).to_s
#=> "file:///c:/windows/My%20Documents%20100%20/foo.txt"

Addressable::URI.convert_path("http://example.com/").to_s
#=> "http://example.com/"
# File lib/addressable/uri.rb, line 228
def self.convert_path(path)
  # If we were given nil, return nil.
  return nil unless path
  # If a URI object is passed, just return itself.
  return path if path.kind_of?(self)
  if !path.respond_to?(:to_str)
    raise TypeError, "Can't convert #{path.class} into String."
  end
  # Otherwise, convert to a String
  path = path.to_str.strip

  path.gsub!(/^file:\/?\/?/, EMPTY_STR) if path =~ /^file:\/?\/?/
  path = SLASH + path if path =~ /^([a-zA-Z])[\|:]/
  uri = self.parse(path)

  if uri.scheme == nil
    # Adjust windows-style uris
    uri.path.gsub!(/^\/?([a-zA-Z])[\|:][\\\/]/) do
      "/#{$1.downcase}:/"
    end
    uri.path.gsub!(/\\/, SLASH)
    if File.exists?(uri.path) &&
        File.stat(uri.path).directory?
      uri.path.gsub!(/\/$/, EMPTY_STR)
      uri.path = uri.path + '/'
    end

    # If the path is absolute, set the scheme and host.
    if uri.path =~ /^\//
      uri.scheme = "file"
      uri.host = EMPTY_STR
    end
    uri.normalize!
  end

  return uri
end
encode(uri, returning=String) click to toggle source

Percent encodes any special characters in the URI.

@param [String, Addressable::URI, to_str] uri

The URI to encode.

@param [Class] returning

The type of object to return.
This value may only be set to <code>String</code> or
<code>Addressable::URI</code>. All other values are invalid. Defaults
to <code>String</code>.

@return [String, Addressable::URI]

The encoded URI.
The return type is determined by the <code>returning</code> parameter.
# File lib/addressable/uri.rb, line 489
def self.encode(uri, returning=String)
  return nil if uri.nil?

  begin
    uri = uri.to_str
  rescue NoMethodError, TypeError
    raise TypeError, "Can't convert #{uri.class} into String."
  end if !uri.is_a? String

  if ![String, ::Addressable::URI].include?(returning)
    raise TypeError,
      "Expected Class (String or Addressable::URI), " +
      "got #{returning.inspect}"
  end
  uri_object = uri.kind_of?(self) ? uri : self.parse(uri)
  encoded_uri = Addressable::URI.new(
    :scheme => self.encode_component(uri_object.scheme,
      Addressable::URI::CharacterClasses::SCHEME),
    :authority => self.encode_component(uri_object.authority,
      Addressable::URI::CharacterClasses::AUTHORITY),
    :path => self.encode_component(uri_object.path,
      Addressable::URI::CharacterClasses::PATH),
    :query => self.encode_component(uri_object.query,
      Addressable::URI::CharacterClasses::QUERY),
    :fragment => self.encode_component(uri_object.fragment,
      Addressable::URI::CharacterClasses::FRAGMENT)
  )
  if returning == String
    return encoded_uri.to_s
  elsif returning == ::Addressable::URI
    return encoded_uri
  end
end
Also aliased as: escape
encode_component(component, character_class= CharacterClasses::RESERVED + CharacterClasses::UNRESERVED) click to toggle source

Percent encodes a URI component.

@param [String, to_str] component The URI component to encode.

@param [String, Regexp] character_class

 The characters which are not percent encoded. If a <code>String</code>
 is passed, the <code>String</code> must be formatted as a regular
 expression character class. (Do not include the surrounding square
 brackets.)  For example, <code>"b-zB-Z0-9"</code> would cause
 everything but the letters 'b' through 'z' and the numbers '0' through
'9' to be percent encoded. If a <code>Regexp</code> is passed, the
 value <code>/[^b-zB-Z0-9]/</code> would have the same effect. A set of
 useful <code>String</code> values may be found in the
 <code>Addressable::URI::CharacterClasses</code> module. The default
 value is the reserved plus unreserved character classes specified in
 <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>.

@return [String] The encoded component.

@example

Addressable::URI.encode_component("simple/example", "b-zB-Z0-9")
=> "simple%2Fex%61mple"
Addressable::URI.encode_component("simple/example", /[^b-zB-Z0-9]/)
=> "simple%2Fex%61mple"
Addressable::URI.encode_component(
  "simple/example", Addressable::URI::CharacterClasses::UNRESERVED
)
=> "simple%2Fexample"
# File lib/addressable/uri.rb, line 322
def self.encode_component(component, character_class=
    CharacterClasses::RESERVED + CharacterClasses::UNRESERVED)
  return nil if component.nil?

  begin
    if component.kind_of?(Symbol) || component.kind_of?(Numeric)
      component = component.to_s
    else
      component = component.to_str
    end
  rescue TypeError, NoMethodError
    raise TypeError, "Can't convert #{component.class} into String."
  end if !component.is_a? String

  if ![String, Regexp].include?(character_class.class)
    raise TypeError,
      "Expected String or Regexp, got #{character_class.inspect}"
  end
  if character_class.kind_of?(String)
    character_class = /[^#{character_class}]/
  end
  if component.respond_to?(:force_encoding)
    # We can't perform regexps on invalid UTF sequences, but
    # here we need to, so switch to ASCII.
    component = component.dup
    component.force_encoding(Encoding::ASCII_8BIT)
  end
  return component.gsub(character_class) do |sequence|
    (sequence.unpack('C*').map { |c| "%" + ("%02x" % c).upcase }).join
  end
end
Also aliased as: encode_component
escape(uri, returning=String) click to toggle source
Alias for: encode
form_encode(form_values, sort=false) click to toggle source

Encodes a set of key/value pairs according to the rules for the application/x-www-form-urlencoded MIME type.

@param [to_hash, to_ary] form_values

The form values to encode.

@param [TrueClass, FalseClass] sort

Sort the key/value pairs prior to encoding.
Defaults to <code>false</code>.

@return [String]

The encoded value.
# File lib/addressable/uri.rb, line 613
def self.form_encode(form_values, sort=false)
  if form_values.respond_to?(:to_hash)
    form_values = form_values.to_hash.to_a
  elsif form_values.respond_to?(:to_ary)
    form_values = form_values.to_ary
  else
    raise TypeError, "Can't convert #{form_values.class} into Array."
  end

  form_values = form_values.inject([]) do |accu, (key, value)|
    if value.kind_of?(Array)
      value.each do |v|
        accu << [key.to_s, v.to_s]
      end
    else
      accu << [key.to_s, value.to_s]
    end
    accu
  end

  if sort
    # Useful for OAuth and optimizing caching systems
    form_values = form_values.sort
  end
  escaped_form_values = form_values.map do |(key, value)|
    # Line breaks are CRLF pairs
    [
      self.encode_component(
        key.gsub(/(\r\n|\n|\r)/, "\r\n"),
        CharacterClasses::UNRESERVED
      ).gsub("%20", "+"),
      self.encode_component(
        value.gsub(/(\r\n|\n|\r)/, "\r\n"),
        CharacterClasses::UNRESERVED
      ).gsub("%20", "+")
    ]
  end
  return (escaped_form_values.map do |(key, value)|
    "#{key}=#{value}"
  end).join("&")
end
form_unencode(encoded_value) click to toggle source

Decodes a String according to the rules for the application/x-www-form-urlencoded MIME type.

@param [String, to_str] encoded_value

The form values to decode.

@return [Array]

The decoded values.
This is not a <code>Hash</code> because of the possibility for
duplicate keys.
# File lib/addressable/uri.rb, line 666
def self.form_unencode(encoded_value)
  if !encoded_value.respond_to?(:to_str)
    raise TypeError, "Can't convert #{encoded_value.class} into String."
  end
  encoded_value = encoded_value.to_str
  split_values = encoded_value.split("&").map do |pair|
    pair.split("=", 2)
  end
  return split_values.map do |(key, value)|
    [
      key ? self.unencode_component(
        key.gsub("+", "%20")).gsub(/(\r\n|\n|\r)/, "\n") : nil,
      value ? (self.unencode_component(
        value.gsub("+", "%20")).gsub(/(\r\n|\n|\r)/, "\n")) : nil
    ]
  end
end
heuristic_parse(uri, hints={}) click to toggle source

Converts an input to a URI. The input does not have to be a valid URI — the method will use heuristics to guess what URI was intended. This is not standards-compliant, merely user-friendly.

@param [String, Addressable::URI, to_str] uri

The URI string to parse.
No parsing is performed if the object is already an
<code>Addressable::URI</code>.

@param [Hash] hints

A <code>Hash</code> of hints to the heuristic parser.
Defaults to <code>{:scheme => "http"}</code>.

@return [Addressable::URI] The parsed URI.

# File lib/addressable/uri.rb, line 155
def self.heuristic_parse(uri, hints={})
  # If we were given nil, return nil.
  return nil unless uri
  # If a URI object is passed, just return itself.
  return uri.dup if uri.kind_of?(self)
  if !uri.respond_to?(:to_str)
    raise TypeError, "Can't convert #{uri.class} into String."
  end
  # Otherwise, convert to a String
  uri = uri.to_str.dup
  hints = {
    :scheme => "http"
  }.merge(hints)
  case uri
  when /^http:\/+/
    uri.gsub!(/^http:\/+/, "http://")
  when /^https:\/+/
    uri.gsub!(/^https:\/+/, "https://")
  when /^feed:\/+http:\/+/
    uri.gsub!(/^feed:\/+http:\/+/, "feed:http://")
  when /^feed:\/+/
    uri.gsub!(/^feed:\/+/, "feed://")
  when /^file:\/+/
    uri.gsub!(/^file:\/+/, "file:///")
  end
  parsed = self.parse(uri)
  if parsed.scheme =~ /^[^\/?#\.]+\.[^\/?#]+$/
    parsed = self.parse(hints[:scheme] + "://" + uri)
  end
  if parsed.path.include?(".")
    new_host = parsed.path[/^([^\/]+\.[^\/]*)/, 1]
    if new_host
      parsed.defer_validation do
        new_path = parsed.path.gsub(
          Regexp.new("^" + Regexp.escape(new_host)), EMPTY_STR)
        parsed.host = new_host
        parsed.path = new_path
        parsed.scheme = hints[:scheme] unless parsed.scheme
      end
    end
  end
  return parsed
end
ip_based_schemes() click to toggle source

Returns an array of known ip-based schemes. These schemes typically use a similar URI form: //<user>:<password>@<host>:<port>/<url-path>

# File lib/addressable/uri.rb, line 1136
def self.ip_based_schemes
  return self.port_mapping.keys
end
join(*uris) click to toggle source

Joins several URIs together.

@param [String, Addressable::URI, to_str] *uris

The URIs to join.

@return [Addressable::URI] The joined URI.

@example

base = "http://example.com/"
uri = Addressable::URI.parse("relative/path")
Addressable::URI.join(base, uri)
#=> #<Addressable::URI:0xcab390 URI:http://example.com/relative/path>
# File lib/addressable/uri.rb, line 279
def self.join(*uris)
  uri_objects = uris.collect do |uri|
    if !uri.respond_to?(:to_str)
      raise TypeError, "Can't convert #{uri.class} into String."
    end
    uri.kind_of?(self) ? uri : self.parse(uri.to_str)
  end
  result = uri_objects.shift.dup
  for uri in uri_objects
    result.join!(uri)
  end
  return result
end
new(options={}) click to toggle source

Creates a new uri object from component parts.

@option [String, to_str] scheme The scheme component. @option [String, to_str] user The user component. @option [String, to_str] password The password component. @option [String, to_str] userinfo

The userinfo component. If this is supplied, the user and password
components must be omitted.

@option [String, to_str] host The host component. @option [String, to_str] port The port component. @option [String, to_str] authority

The authority component. If this is supplied, the user, password,
userinfo, host, and port components must be omitted.

@option [String, to_str] path The path component. @option [String, to_str] query The query component. @option [String, to_str] fragment The fragment component.

@return [Addressable::URI] The constructed URI object.

# File lib/addressable/uri.rb, line 703
def initialize(options={})
  if options.has_key?(:authority)
    if (options.keys & [:userinfo, :user, :password, :host, :port]).any?
      raise ArgumentError,
        "Cannot specify both an authority and any of the components " +
        "within the authority."
    end
  end
  if options.has_key?(:userinfo)
    if (options.keys & [:user, :password]).any?
      raise ArgumentError,
        "Cannot specify both a userinfo and either the user or password."
    end
  end

  self.defer_validation do
    # Bunch of crazy logic required because of the composite components
    # like userinfo and authority.
    self.scheme = options[:scheme] if options[:scheme]
    self.user = options[:user] if options[:user]
    self.password = options[:password] if options[:password]
    self.userinfo = options[:userinfo] if options[:userinfo]
    self.host = options[:host] if options[:host]
    self.port = options[:port] if options[:port]
    self.authority = options[:authority] if options[:authority]
    self.path = options[:path] if options[:path]
    self.query = options[:query] if options[:query]
    self.query_values = options[:query_values] if options[:query_values]
    self.fragment = options[:fragment] if options[:fragment]
  end
end
normalize_component(component, character_class= CharacterClasses::RESERVED + CharacterClasses::UNRESERVED) click to toggle source

Normalizes the encoding of a URI component.

@param [String, to_str] component The URI component to encode.

@param [String, Regexp] character_class

The characters which are not percent encoded. If a <code>String</code>
is passed, the <code>String</code> must be formatted as a regular
expression character class. (Do not include the surrounding square
brackets.)  For example, <code>"b-zB-Z0-9"</code> would cause
everything but the letters 'b' through 'z' and the numbers '0'
through '9' to be percent encoded. If a <code>Regexp</code> is passed,
the value <code>/[^b-zB-Z0-9]/</code> would have the same effect. A
set of useful <code>String</code> values may be found in the
<code>Addressable::URI::CharacterClasses</code> module. The default
value is the reserved plus unreserved character classes specified in
<a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>.

@return [String] The normalized component.

@example

Addressable::URI.normalize_component("simpl%65/%65xampl%65", "b-zB-Z")
=> "simple%2Fex%61mple"
Addressable::URI.normalize_component(
  "simpl%65/%65xampl%65", /[^b-zB-Z]/
)
=> "simple%2Fex%61mple"
Addressable::URI.normalize_component(
  "simpl%65/%65xampl%65",
  Addressable::URI::CharacterClasses::UNRESERVED
)
=> "simple%2Fexample"
# File lib/addressable/uri.rb, line 439
def self.normalize_component(component, character_class=
    CharacterClasses::RESERVED + CharacterClasses::UNRESERVED)
  return nil if component.nil?

  begin
    component = component.to_str
  rescue NoMethodError, TypeError
    raise TypeError, "Can't convert #{component.class} into String."
  end if !component.is_a? String

  if ![String, Regexp].include?(character_class.class)
    raise TypeError,
      "Expected String or Regexp, got #{character_class.inspect}"
  end
  if character_class.kind_of?(String)
    character_class = /[^#{character_class}]/
  end
  if component.respond_to?(:force_encoding)
    # We can't perform regexps on invalid UTF sequences, but
    # here we need to, so switch to ASCII.
    component = component.dup
    component.force_encoding(Encoding::ASCII_8BIT)
  end
  unencoded = self.unencode_component(component)
  begin
    encoded = self.encode_component(
      Addressable::IDNA.unicode_normalize_kc(unencoded),
      character_class
    )
  rescue ArgumentError
    encoded = self.encode_component(unencoded)
  end
  return encoded
end
normalized_encode(uri, returning=String) click to toggle source

Normalizes the encoding of a URI. Characters within a hostname are not percent encoded to allow for internationalized domain names.

@param [String, Addressable::URI, to_str] uri

The URI to encode.

@param [Class] returning

The type of object to return.
This value may only be set to <code>String</code> or
<code>Addressable::URI</code>. All other values are invalid. Defaults
to <code>String</code>.

@return [String, Addressable::URI]

The encoded URI.
The return type is determined by the <code>returning</code> parameter.
# File lib/addressable/uri.rb, line 543
def self.normalized_encode(uri, returning=String)
  begin
    uri = uri.to_str
  rescue NoMethodError, TypeError
    raise TypeError, "Can't convert #{uri.class} into String."
  end if !uri.is_a? String

  if ![String, ::Addressable::URI].include?(returning)
    raise TypeError,
      "Expected Class (String or Addressable::URI), " +
      "got #{returning.inspect}"
  end
  uri_object = uri.kind_of?(self) ? uri : self.parse(uri)
  components = {
    :scheme => self.unencode_component(uri_object.scheme),
    :user => self.unencode_component(uri_object.user),
    :password => self.unencode_component(uri_object.password),
    :host => self.unencode_component(uri_object.host),
    :port => uri_object.port,
    :path => self.unencode_component(uri_object.path),
    :query => self.unencode_component(uri_object.query),
    :fragment => self.unencode_component(uri_object.fragment)
  }
  components.each do |key, value|
    if value != nil
      begin
        components[key] =
          Addressable::IDNA.unicode_normalize_kc(value.to_str)
      rescue ArgumentError
        # Likely a malformed UTF-8 character, skip unicode normalization
        components[key] = value.to_str
      end
    end
  end
  encoded_uri = Addressable::URI.new(
    :scheme => self.encode_component(components[:scheme],
      Addressable::URI::CharacterClasses::SCHEME),
    :user => self.encode_component(components[:user],
      Addressable::URI::CharacterClasses::UNRESERVED),
    :password => self.encode_component(components[:password],
      Addressable::URI::CharacterClasses::UNRESERVED),
    :host => components[:host],
    :port => components[:port],
    :path => self.encode_component(components[:path],
      Addressable::URI::CharacterClasses::PATH),
    :query => self.encode_component(components[:query],
      Addressable::URI::CharacterClasses::QUERY),
    :fragment => self.encode_component(components[:fragment],
      Addressable::URI::CharacterClasses::FRAGMENT)
  )
  if returning == String
    return encoded_uri.to_s
  elsif returning == ::Addressable::URI
    return encoded_uri
  end
end
parse(uri) click to toggle source

Returns a URI object based on the parsed string.

@param [String, Addressable::URI, to_str] uri

The URI string to parse.
No parsing is performed if the object is already an
<code>Addressable::URI</code>.

@return [Addressable::URI] The parsed URI.

# File lib/addressable/uri.rb, line 82
def self.parse(uri)
  # If we were given nil, return nil.
  return nil unless uri
  # If a URI object is passed, just return itself.
  return uri.dup if uri.kind_of?(self)

  # If a URI object of the Ruby standard library variety is passed,
  # convert it to a string, then parse the string.
  # We do the check this way because we don't want to accidentally
  # cause a missing constant exception to be thrown.
  if uri.class.name =~ /^URI\b/
    uri = uri.to_s
  end

  # Otherwise, convert to a String
  begin
    uri = uri.to_str
  rescue TypeError, NoMethodError
    raise TypeError, "Can't convert #{uri.class} into String."
  end if not uri.is_a? String

  # This Regexp supplied as an example in RFC 3986, and it works great.
  scan = uri.scan(URIREGEX)
  fragments = scan[0]
  scheme = fragments[1]
  authority = fragments[3]
  path = fragments[4]
  query = fragments[6]
  fragment = fragments[8]
  user = nil
  password = nil
  host = nil
  port = nil
  if authority != nil
    # The Regexp above doesn't split apart the authority.
    userinfo = authority[/^([^\[\]]*)@/, 1]
    if userinfo != nil
      user = userinfo.strip[/^([^:]*):?/, 1]
      password = userinfo.strip[/:(.*)$/, 1]
    end
    host = authority.gsub(/^([^\[\]]*)@/, EMPTY_STR).gsub(/:([^:@\[\]]*?)$/, EMPTY_STR)
    port = authority[/:([^:@\[\]]*?)$/, 1]
  end
  if port == EMPTY_STR
    port = nil
  end

  return new(
    :scheme => scheme,
    :user => user,
    :password => password,
    :host => host,
    :port => port,
    :path => path,
    :query => query,
    :fragment => fragment
  )
end
port_mapping() click to toggle source

Returns a hash of common IP-based schemes and their default port numbers. Adding new schemes to this hash, as necessary, will allow for better URI normalization.

# File lib/addressable/uri.rb, line 1143
def self.port_mapping
  PORT_MAPPING
end
unencode(uri, returning=String) click to toggle source

Unencodes any percent encoded characters within a URI component. This method may be used for unencoding either components or full URIs, however, it is recommended to use the unencode_component alias when unencoding components.

@param [String, Addressable::URI, to_str] uri

The URI or component to unencode.

@param [Class] returning

The type of object to return.
This value may only be set to <code>String</code> or
<code>Addressable::URI</code>. All other values are invalid. Defaults
to <code>String</code>.

@return [String, Addressable::URI]

The unencoded component or URI.
The return type is determined by the <code>returning</code> parameter.
# File lib/addressable/uri.rb, line 376
def self.unencode(uri, returning=String)
  return nil if uri.nil?

  begin
    uri = uri.to_str
  rescue NoMethodError, TypeError
    raise TypeError, "Can't convert #{uri.class} into String."
  end if !uri.is_a? String
  if ![String, ::Addressable::URI].include?(returning)
    raise TypeError,
      "Expected Class (String or Addressable::URI), " +
      "got #{returning.inspect}"
  end
  result = uri.gsub(/%[0-9a-f]{2}/) do |sequence|
    sequence[1..3].to_i(16).chr
  end
  result.force_encoding("utf-8") if result.respond_to?(:force_encoding)
  if returning == String
    return result
  elsif returning == ::Addressable::URI
    return ::Addressable::URI.parse(result)
  end
end
unencode_component(uri, returning=String) click to toggle source
Alias for: unencode
unescape(uri, returning=String) click to toggle source
Alias for: unencode
unescape_component(uri, returning=String) click to toggle source
Alias for: unencode

Public Instance Methods

+(uri) click to toggle source
Alias for: join
==(uri) click to toggle source

Returns true if the URI objects are equal. This method normalizes both URIs before doing the comparison.

@param [Object] uri The URI to compare.

@return [TrueClass, FalseClass]

<code>true</code> if the URIs are equivalent, <code>false</code>
otherwise.
# File lib/addressable/uri.rb, line 2035
def ==(uri)
  return false unless uri.kind_of?(URI)
  return self.normalize.to_s == uri.normalize.to_s
end
===(uri) click to toggle source

Returns true if the URI objects are equal. This method normalizes both URIs before doing the comparison, and allows comparison against Strings.

@param [Object] uri The URI to compare.

@return [TrueClass, FalseClass]

<code>true</code> if the URIs are equivalent, <code>false</code>
otherwise.
# File lib/addressable/uri.rb, line 2013
def ===(uri)
  if uri.respond_to?(:normalize)
    uri_string = uri.normalize.to_s
  else
    begin
      uri_string = ::Addressable::URI.parse(uri).normalize.to_s
    rescue InvalidURIError, TypeError
      return false
    end
  end
  return self.normalize.to_s == uri_string
end
absolute?() click to toggle source

Determines if the URI is absolute.

@return [TrueClass, FalseClass]

<code>true</code> if the URI is absolute. <code>false</code>
otherwise.
# File lib/addressable/uri.rb, line 1682
def absolute?
  return !relative?
end
authority() click to toggle source

The authority component for this URI. Combines the user, password, host, and port components.

@return [String] The authority component.

# File lib/addressable/uri.rb, line 1044
def authority
  self.host && @authority ||= (begin
    authority = ""
    if self.userinfo != nil
      authority << "#{self.userinfo}@"
    end
    authority << self.host
    if self.port != nil
      authority << ":#{self.port}"
    end
    authority
  end)
end
authority=(new_authority) click to toggle source

Sets the authority component for this URI.

@param [String, to_str] new_authority The new authority component.

# File lib/addressable/uri.rb, line 1080
def authority=(new_authority)
  if new_authority
    if !new_authority.respond_to?(:to_str)
      raise TypeError, "Can't convert #{new_authority.class} into String."
    end
    new_authority = new_authority.to_str
    new_userinfo = new_authority[/^([^\[\]]*)@/, 1]
    if new_userinfo
      new_user = new_userinfo.strip[/^([^:]*):?/, 1]
      new_password = new_userinfo.strip[/:(.*)$/, 1]
    end
    new_host =
      new_authority.gsub(/^([^\[\]]*)@/, EMPTY_STR).gsub(/:([^:@\[\]]*?)$/, EMPTY_STR)
    new_port =
      new_authority[/:([^:@\[\]]*?)$/, 1]
  end

  # Password assigned first to ensure validity in case of nil
  self.password = defined?(new_password) ? new_password : nil
  self.user = defined?(new_user) ? new_user : nil
  self.host = defined?(new_host) ? new_host : nil
  self.port = defined?(new_port) ? new_port : nil

  # Reset dependant values
  @userinfo = nil
  @normalized_userinfo = nil
  @uri_string = nil
  @hash = nil

  # Ensure we haven't created an invalid URI
  validate()
end
basename() click to toggle source

The basename, if any, of the file in the path component.

@return [String] The path's basename.

# File lib/addressable/uri.rb, line 1336
def basename
  # Path cannot be nil
  return File.basename(self.path).gsub(/;[^\/]*$/, EMPTY_STR)
end
defer_validation(&block) click to toggle source

This method allows you to make several changes to a URI simultaneously, which separately would cause validation errors, but in conjunction, are valid. The URI will be revalidated as soon as the entire block has been executed.

@param [Proc] block

A set of operations to perform on a given URI.
# File lib/addressable/uri.rb, line 2185
def defer_validation(&block)
  raise LocalJumpError, "No block given." unless block
  @validation_deferred = true
  block.call()
  @validation_deferred = false
  validate
  return nil
end
display_uri() click to toggle source

Creates a URI suitable for display to users. If semantic attacks are likely, the application should try to detect these and warn the user. See <a href="RFC">www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>, section 7.6 for more information.

@return [Addressable::URI] A URI suitable for display purposes.

# File lib/addressable/uri.rb, line 1997
def display_uri
  display_uri = self.normalize
  display_uri.host = ::Addressable::IDNA.to_unicode(display_uri.host)
  return display_uri
end
dup() click to toggle source

Clones the URI object.

@return [Addressable::URI] The cloned URI.

# File lib/addressable/uri.rb, line 2067
def dup
  duplicated_uri = Addressable::URI.new(
    :scheme => self.scheme ? self.scheme.dup : nil,
    :user => self.user ? self.user.dup : nil,
    :password => self.password ? self.password.dup : nil,
    :host => self.host ? self.host.dup : nil,
    :port => self.port,
    :path => self.path ? self.path.dup : nil,
    :query => self.query ? self.query.dup : nil,
    :fragment => self.fragment ? self.fragment.dup : nil
  )
  return duplicated_uri
end
eql?(uri) click to toggle source

Returns true if the URI objects are equal. This method does NOT normalize either URI before doing the comparison.

@param [Object] uri The URI to compare.

@return [TrueClass, FalseClass]

<code>true</code> if the URIs are equivalent, <code>false</code>
otherwise.
# File lib/addressable/uri.rb, line 2049
def eql?(uri)
  return false unless uri.kind_of?(URI)
  return self.to_s == uri.to_s
end
extname() click to toggle source

The extname, if any, of the file in the path component. Empty string if there is no extension.

@return [String] The path's extname.

# File lib/addressable/uri.rb, line 1346
def extname
  return nil unless self.path
  return File.extname(self.basename)
end
fragment() click to toggle source

The fragment component for this URI.

@return [String] The fragment component.

# File lib/addressable/uri.rb, line 1616
def fragment
  return instance_variable_defined?(:@fragment) ? @fragment : nil
end
fragment=(new_fragment) click to toggle source

Sets the fragment component for this URI.

@param [String, to_str] new_fragment The new fragment component.

# File lib/addressable/uri.rb, line 1637
def fragment=(new_fragment)
  if new_fragment && !new_fragment.respond_to?(:to_str)
    raise TypeError, "Can't convert #{new_fragment.class} into String."
  end
  @fragment = new_fragment ? new_fragment.to_str : nil

  # Reset dependant values
  @normalized_fragment = nil
  @uri_string = nil
  @hash = nil

  # Ensure we haven't created an invalid URI
  validate()
end
freeze() click to toggle source

Freeze URI, initializing instance variables.

@return [Addressable::URI] The frozen URI object.

# File lib/addressable/uri.rb, line 739
def freeze
  self.normalized_scheme
  self.normalized_user
  self.normalized_password
  self.normalized_userinfo
  self.normalized_host
  self.normalized_port
  self.normalized_authority
  self.normalized_site
  self.normalized_path
  self.normalized_query
  self.normalized_fragment
  self.hash
  super
end
hash() click to toggle source

A hash value that will make a URI equivalent to its normalized form.

@return [Integer] A hash of the URI.

# File lib/addressable/uri.rb, line 2059
def hash
  return @hash ||= (self.to_s.hash * -1)
end
host() click to toggle source

The host component for this URI.

@return [String] The host component.

# File lib/addressable/uri.rb, line 982
def host
  return instance_variable_defined?(:@host) ? @host : nil
end
Also aliased as: hostname
host=(new_host) click to toggle source

Sets the host component for this URI.

@param [String, to_str] new_host The new host component.

# File lib/addressable/uri.rb, line 1015
def host=(new_host)
  if new_host && !new_host.respond_to?(:to_str)
    raise TypeError, "Can't convert #{new_host.class} into String."
  end
  @host = new_host ? new_host.to_str : nil

  # Reset dependant values
  @authority = nil
  @normalized_host = nil
  @uri_string = nil
  @hash = nil

  # Ensure we haven't created an invalid URI
  validate()
end
Also aliased as: hostname=
hostname() click to toggle source
Alias for: host
hostname=(new_host) click to toggle source
Alias for: host=
inferred_port() click to toggle source

The inferred port component for this URI. This method will normalize to the default port for the URI's scheme if the port isn't explicitly specified in the URI.

@return [Integer] The inferred port component.

# File lib/addressable/uri.rb, line 1201
def inferred_port
  if self.port.to_i == 0
    if self.scheme
      URI.port_mapping[self.scheme.strip.downcase]
    else
      nil
    end
  else
    self.port.to_i
  end
end
inspect() click to toggle source

Returns a String representation of the URI object's state.

@return [String] The URI object's state, as a String.

# File lib/addressable/uri.rb, line 2173
def inspect
  sprintf("#<%s:%#0x URI:%s>", URI.to_s, self.object_id, self.to_s)
end
ip_based?() click to toggle source

Determines if the scheme indicates an IP-based protocol.

@return [TrueClass, FalseClass]

<code>true</code> if the scheme indicates an IP-based protocol.
<code>false</code> otherwise.
# File lib/addressable/uri.rb, line 1658
def ip_based?
  if self.scheme
    return URI.ip_based_schemes.include?(
      self.scheme.strip.downcase)
  end
  return false
end
join(uri) click to toggle source

Joins two URIs together.

@param [String, Addressable::URI, to_str] The URI to join with.

@return [Addressable::URI] The joined URI.

# File lib/addressable/uri.rb, line 1692
def join(uri)
  if !uri.respond_to?(:to_str)
    raise TypeError, "Can't convert #{uri.class} into String."
  end
  if !uri.kind_of?(URI)
    # Otherwise, convert to a String, then parse.
    uri = URI.parse(uri.to_str)
  end
  if uri.to_s.empty?
    return self.dup
  end

  joined_scheme = nil
  joined_user = nil
  joined_password = nil
  joined_host = nil
  joined_port = nil
  joined_path = nil
  joined_query = nil
  joined_fragment = nil

  # Section 5.2.2 of RFC 3986
  if uri.scheme != nil
    joined_scheme = uri.scheme
    joined_user = uri.user
    joined_password = uri.password
    joined_host = uri.host
    joined_port = uri.port
    joined_path = URI.normalize_path(uri.path)
    joined_query = uri.query
  else
    if uri.authority != nil
      joined_user = uri.user
      joined_password = uri.password
      joined_host = uri.host
      joined_port = uri.port
      joined_path = URI.normalize_path(uri.path)
      joined_query = uri.query
    else
      if uri.path == nil || uri.path.empty?
        joined_path = self.path
        if uri.query != nil
          joined_query = uri.query
        else
          joined_query = self.query
        end
      else
        if uri.path[0..0] == SLASH
          joined_path = URI.normalize_path(uri.path)
        else
          base_path = self.path.dup
          base_path = EMPTY_STR if base_path == nil
          base_path = URI.normalize_path(base_path)

          # Section 5.2.3 of RFC 3986
          #
          # Removes the right-most path segment from the base path.
          if base_path =~ /\//
            base_path.gsub!(/\/[^\/]+$/, SLASH)
          else
            base_path = EMPTY_STR
          end

          # If the base path is empty and an authority segment has been
          # defined, use a base path of SLASH
          if base_path.empty? && self.authority != nil
            base_path = SLASH
          end

          joined_path = URI.normalize_path(base_path + uri.path)
        end
        joined_query = uri.query
      end
      joined_user = self.user
      joined_password = self.password
      joined_host = self.host
      joined_port = self.port
    end
    joined_scheme = self.scheme
  end
  joined_fragment = uri.fragment

  return Addressable::URI.new(
    :scheme => joined_scheme,
    :user => joined_user,
    :password => joined_password,
    :host => joined_host,
    :port => joined_port,
    :path => joined_path,
    :query => joined_query,
    :fragment => joined_fragment
  )
end
Also aliased as: +
join!(uri) click to toggle source

Destructive form of join.

@param [String, Addressable::URI, to_str] The URI to join with.

@return [Addressable::URI] The joined URI.

@see Addressable::URI#join

# File lib/addressable/uri.rb, line 1795
def join!(uri)
  replace_self(self.join(uri))
end
merge(hash) click to toggle source

Merges a URI with a Hash of components. This method has different behavior from join. Any components present in the hash parameter will override the original components. The path component is not treated specially.

@param [Hash, Addressable::URI, to_hash] The components to merge with.

@return [Addressable::URI] The merged URI.

@see Hash#merge

# File lib/addressable/uri.rb, line 1810
def merge(hash)
  if !hash.respond_to?(:to_hash)
    raise TypeError, "Can't convert #{hash.class} into Hash."
  end
  hash = hash.to_hash

  if hash.has_key?(:authority)
    if (hash.keys & [:userinfo, :user, :password, :host, :port]).any?
      raise ArgumentError,
        "Cannot specify both an authority and any of the components " +
        "within the authority."
    end
  end
  if hash.has_key?(:userinfo)
    if (hash.keys & [:user, :password]).any?
      raise ArgumentError,
        "Cannot specify both a userinfo and either the user or password."
    end
  end

  uri = Addressable::URI.new
  uri.defer_validation do
    # Bunch of crazy logic required because of the composite components
    # like userinfo and authority.
    uri.scheme =
      hash.has_key?(:scheme) ? hash[:scheme] : self.scheme
    if hash.has_key?(:authority)
      uri.authority =
        hash.has_key?(:authority) ? hash[:authority] : self.authority
    end
    if hash.has_key?(:userinfo)
      uri.userinfo =
        hash.has_key?(:userinfo) ? hash[:userinfo] : self.userinfo
    end
    if !hash.has_key?(:userinfo) && !hash.has_key?(:authority)
      uri.user =
        hash.has_key?(:user) ? hash[:user] : self.user
      uri.password =
        hash.has_key?(:password) ? hash[:password] : self.password
    end
    if !hash.has_key?(:authority)
      uri.host =
        hash.has_key?(:host) ? hash[:host] : self.host
      uri.port =
        hash.has_key?(:port) ? hash[:port] : self.port
    end
    uri.path =
      hash.has_key?(:path) ? hash[:path] : self.path
    uri.query =
      hash.has_key?(:query) ? hash[:query] : self.query
    uri.fragment =
      hash.has_key?(:fragment) ? hash[:fragment] : self.fragment
  end

  return uri
end
merge!(uri) click to toggle source

Destructive form of merge.

@param [Hash, Addressable::URI, to_hash] The components to merge with.

@return [Addressable::URI] The merged URI.

@see Addressable::URI#merge

# File lib/addressable/uri.rb, line 1875
def merge!(uri)
  replace_self(self.merge(uri))
end
normalize() click to toggle source

Returns a normalized URI object.

NOTE: This method does not attempt to fully conform to specifications. It exists largely to correct other people's failures to read the specifications, and also to deal with caching issues since several different URIs may represent the same resource and should not be cached multiple times.

@return [Addressable::URI] The normalized URI.

# File lib/addressable/uri.rb, line 1960
def normalize
  # This is a special exception for the frequently misused feed
  # URI scheme.
  if normalized_scheme == "feed"
    if self.to_s =~ /^feed:\/*http:\/*/
      return URI.parse(
        self.to_s[/^feed:\/*(http:\/*.*)/, 1]
      ).normalize
    end
  end

  return Addressable::URI.new(
    :scheme => normalized_scheme,
    :authority => normalized_authority,
    :path => normalized_path,
    :query => normalized_query,
    :fragment => normalized_fragment
  )
end
normalize!() click to toggle source

Destructively normalizes this URI object.

@return [Addressable::URI] The normalized URI.

@see Addressable::URI#normalize

# File lib/addressable/uri.rb, line 1986
def normalize!
  replace_self(self.normalize)
end
normalized_authority() click to toggle source

The authority component for this URI, normalized.

@return [String] The authority component, normalized.

# File lib/addressable/uri.rb, line 1062
def normalized_authority
  self.authority && @normalized_authority ||= (begin
    authority = ""
    if self.normalized_userinfo != nil
      authority << "#{self.normalized_userinfo}@"
    end
    authority << self.normalized_host
    if self.normalized_port != nil
      authority << ":#{self.normalized_port}"
    end
    authority
  end)
end
normalized_fragment() click to toggle source

The fragment component for this URI, normalized.

@return [String] The fragment component, normalized.

# File lib/addressable/uri.rb, line 1624
def normalized_fragment
  self.fragment && @normalized_fragment ||= (begin
    Addressable::URI.normalize_component(
      self.fragment.strip,
      Addressable::URI::CharacterClasses::FRAGMENT
    )
  end)
end
normalized_host() click to toggle source

The host component for this URI, normalized.

@return [String] The host component, normalized.

# File lib/addressable/uri.rb, line 990
def normalized_host
  self.host && @normalized_host ||= (begin
    if self.host != nil
      if !self.host.strip.empty?
        result = ::Addressable::IDNA.to_ascii(
          URI.unencode_component(self.host.strip.downcase)
        )
        if result[-1..-1] == "."
          # Trailing dots are unnecessary
          result = result[0...-1]
        end
        result
      else
        EMPTY_STR
      end
    else
      nil
    end
  end)
end
normalized_password() click to toggle source

The password component for this URI, normalized.

@return [String] The password component, normalized.

# File lib/addressable/uri.rb, line 870
def normalized_password
  self.password && @normalized_password ||= (begin
    if self.normalized_scheme =~ /https?/ && self.password.strip.empty? &&
        (!self.user || self.user.strip.empty?)
      nil
    else
      Addressable::URI.normalize_component(
        self.password.strip,
        Addressable::URI::CharacterClasses::UNRESERVED
      )
    end
  end)
end
normalized_path() click to toggle source

The path component for this URI, normalized.

@return [String] The path component, normalized.

# File lib/addressable/uri.rb, line 1288
def normalized_path
  @normalized_path ||= (begin
    path = self.path.to_s
    if self.scheme == nil && path =~ NORMPATH
      # Relative paths with colons in the first segment are ambiguous.
      path = path.sub(":", "%2F")
    end
    # String#split(delimeter, -1) uses the more strict splitting behavior
    # found by default in Python.
    result = (path.strip.split(SLASH, -1).map do |segment|
      Addressable::URI.normalize_component(
        segment,
        Addressable::URI::CharacterClasses::PCHAR
      )
    end).join(SLASH)

    result = URI.normalize_path(result)
    if result.empty? &&
        ["http", "https", "ftp", "tftp"].include?(self.normalized_scheme)
      result = SLASH
    end
    result
  end)
end
normalized_port() click to toggle source

The port component for this URI, normalized.

@return [Integer] The port component, normalized.

# File lib/addressable/uri.rb, line 1161
def normalized_port
  if URI.port_mapping[self.normalized_scheme] == self.port
    nil
  else
    self.port
  end
end
normalized_query() click to toggle source

The query component for this URI, normalized.

@return [String] The query component, normalized.

# File lib/addressable/uri.rb, line 1363
def normalized_query
  self.query && @normalized_query ||= (begin
    (self.query.split("&", -1).map do |pair|
      Addressable::URI.normalize_component(
        pair,
        Addressable::URI::CharacterClasses::QUERY.sub("\\&", "")
      )
    end).join("&")
  end)
end
normalized_scheme() click to toggle source

The scheme component for this URI, normalized.

@return [String] The scheme component, normalized.

# File lib/addressable/uri.rb, line 767
def normalized_scheme
  self.scheme && @normalized_scheme ||= (begin
    if self.scheme =~ /^\s*ssh\+svn\s*$/
      "svn+ssh"
    else
      Addressable::URI.normalize_component(
        self.scheme.strip.downcase,
        Addressable::URI::CharacterClasses::SCHEME
      )
    end
  end)
end
normalized_site() click to toggle source

The normalized combination of components that represent a site. Combines the scheme, user, password, host, and port components. Primarily useful for HTTP and HTTPS.

For example, "http://example.com/path?query" would have a site value of "http://example.com".

@return [String] The normalized components that identify a site.

# File lib/addressable/uri.rb, line 1240
def normalized_site
  self.site && @normalized_site ||= (begin
    site_string = ""
    if self.normalized_scheme != nil
      site_string << "#{self.normalized_scheme}:"
    end
    if self.normalized_authority != nil
      site_string << "//#{self.normalized_authority}"
    end
    site_string
  end)
end
normalized_user() click to toggle source

The user component for this URI, normalized.

@return [String] The user component, normalized.

# File lib/addressable/uri.rb, line 817
def normalized_user
  self.user && @normalized_user ||= (begin
    if normalized_scheme =~ /https?/ && self.user.strip.empty? &&
        (!self.password || self.password.strip.empty?)
      nil
    else
      Addressable::URI.normalize_component(
        self.user.strip,
        Addressable::URI::CharacterClasses::UNRESERVED
      )
    end
  end)
end
normalized_userinfo() click to toggle source

The userinfo component for this URI, normalized.

@return [String] The userinfo component, normalized.

# File lib/addressable/uri.rb, line 934
def normalized_userinfo
  self.userinfo && @normalized_userinfo ||= (begin
    current_user = self.normalized_user
    current_password = self.normalized_password
    if !current_user && !current_password
      nil
    elsif current_user && current_password
      "#{current_user}:#{current_password}"
    elsif current_user && !current_password
      "#{current_user}"
    end
  end)
end
omit(*components) click to toggle source

Omits components from a URI.

@param [Symbol] *components The components to be omitted.

@return [Addressable::URI] The URI with components omitted.

@example

uri = Addressable::URI.parse("http://example.com/path?query")
#=> #<Addressable::URI:0xcc5e7a URI:http://example.com/path?query>
uri.omit(:scheme, :authority)
#=> #<Addressable::URI:0xcc4d86 URI:/path?query>
# File lib/addressable/uri.rb, line 2093
def omit(*components)
  invalid_components = components - [
    :scheme, :user, :password, :userinfo, :host, :port, :authority,
    :path, :query, :fragment
  ]
  unless invalid_components.empty?
    raise ArgumentError,
      "Invalid component names: #{invalid_components.inspect}."
  end
  duplicated_uri = self.dup
  duplicated_uri.defer_validation do
    components.each do |component|
      duplicated_uri.send((component.to_s + "=").to_sym, nil)
    end
    duplicated_uri.user = duplicated_uri.normalized_user
  end
  duplicated_uri
end
omit!(*components) click to toggle source

Destructive form of omit.

@param [Symbol] *components The components to be omitted.

@return [Addressable::URI] The URI with components omitted.

@see Addressable::URI#omit

# File lib/addressable/uri.rb, line 2120
def omit!(*components)
  replace_self(self.omit(*components))
end
origin() click to toggle source

The origin for this URI, serialized to ASCII, as per draft-ietf-websec-origin-00, section 5.2.

@return [String] The serialized origin.

# File lib/addressable/uri.rb, line 1118
def origin
  return (if self.scheme && self.authority
    if self.normalized_port
      (
        "#{self.normalized_scheme}://#{self.normalized_host}" +
        ":#{self.normalized_port}"
      )
    else
      "#{self.normalized_scheme}://#{self.normalized_host}"
    end
  else
    "null"
  end)
end
password() click to toggle source

The password component for this URI.

@return [String] The password component.

# File lib/addressable/uri.rb, line 862
def password
  return instance_variable_defined?(:@password) ? @password : nil
end
password=(new_password) click to toggle source

Sets the password component for this URI.

@param [String, to_str] new_password The new password component.

# File lib/addressable/uri.rb, line 888
def password=(new_password)
  if new_password && !new_password.respond_to?(:to_str)
    raise TypeError, "Can't convert #{new_password.class} into String."
  end
  @password = new_password ? new_password.to_str : nil

  # You can't have a nil user with a non-nil password
  @password ||= nil
  @user ||= nil
  if @password != nil
    @user = EMPTY_STR if @user.nil?
  end

  # Reset dependant values
  @userinfo = nil
  @normalized_userinfo = nil
  @authority = nil
  @normalized_password = nil
  @uri_string = nil
  @hash = nil

  # Ensure we haven't created an invalid URI
  validate()
end
path() click to toggle source

The path component for this URI.

@return [String] The path component.

# File lib/addressable/uri.rb, line 1279
def path
  return instance_variable_defined?(:@path) ? @path : EMPTY_STR
end
path=(new_path) click to toggle source

Sets the path component for this URI.

@param [String, to_str] new_path The new path component.

# File lib/addressable/uri.rb, line 1317
def path=(new_path)
  if new_path && !new_path.respond_to?(:to_str)
    raise TypeError, "Can't convert #{new_path.class} into String."
  end
  @path = (new_path || EMPTY_STR).to_str
  if !@path.empty? && @path[0..0] != SLASH && host != nil
    @path = "/#{@path}"
  end

  # Reset dependant values
  @normalized_path = nil
  @uri_string = nil
  @hash = nil
end
port() click to toggle source

The port component for this URI. This is the port number actually given in the URI. This does not infer port numbers from default values.

@return [Integer] The port component.

# File lib/addressable/uri.rb, line 1153
def port
  return instance_variable_defined?(:@port) ? @port : nil
end
port=(new_port) click to toggle source

Sets the port component for this URI.

@param [String, Integer, to_s] new_port The new port component.

# File lib/addressable/uri.rb, line 1173
def port=(new_port)
  if new_port != nil && new_port.respond_to?(:to_str)
    new_port = Addressable::URI.unencode_component(new_port.to_str)
  end
  if new_port != nil && !(new_port.to_s =~ /^\d+$/)
    raise InvalidURIError,
      "Invalid port number: #{new_port.inspect}"
  end

  @port = new_port.to_s.to_i
  @port = nil if @port == 0

  # Reset dependant values
  @authority = nil
  @normalized_port = nil
  @uri_string = nil
  @hash = nil

  # Ensure we haven't created an invalid URI
  validate()
end
query() click to toggle source

The query component for this URI.

@return [String] The query component.

# File lib/addressable/uri.rb, line 1355
def query
  return instance_variable_defined?(:@query) ? @query : nil
end
query=(new_query) click to toggle source

Sets the query component for this URI.

@param [String, to_str] new_query The new query component.

# File lib/addressable/uri.rb, line 1378
def query=(new_query)
  if new_query && !new_query.respond_to?(:to_str)
    raise TypeError, "Can't convert #{new_query.class} into String."
  end
  @query = new_query ? new_query.to_str : nil

  # Reset dependant values
  @normalized_query = nil
  @uri_string = nil
  @hash = nil
end
query_values(options={}) click to toggle source

Converts the query component to a Hash value.

@option [Symbol] notation

May be one of <code>:flat</code>, <code>:dot</code>, or
<code>:subscript</code>. The <code>:dot</code> notation is not
supported for assignment. Default value is <code>:subscript</code>.

@return [Hash, Array] The query string parsed as a Hash or Array object.

@example

Addressable::URI.parse("?one=1&two=2&three=3").query_values
#=> {"one" => "1", "two" => "2", "three" => "3"}
Addressable::URI.parse("?one[two][three]=four").query_values
#=> {"one" => {"two" => {"three" => "four"}}}
Addressable::URI.parse("?one.two.three=four").query_values(
  :notation => :dot
)
#=> {"one" => {"two" => {"three" => "four"}}}
Addressable::URI.parse("?one[two][three]=four").query_values(
  :notation => :flat
)
#=> {"one[two][three]" => "four"}
Addressable::URI.parse("?one.two.three=four").query_values(
  :notation => :flat
)
#=> {"one.two.three" => "four"}
Addressable::URI.parse(
  "?one[two][three][]=four&one[two][three][]=five"
).query_values
#=> {"one" => {"two" => {"three" => ["four", "five"]}}}
Addressable::URI.parse(
  "?one=two&one=three").query_values(:notation => :flat_array)
#=> [['one', 'two'], ['one', 'three']]
# File lib/addressable/uri.rb, line 1424
def query_values(options={})
  defaults = {:notation => :subscript}
  options = defaults.merge(options)
  if ![:flat, :dot, :subscript, :flat_array].include?(options[:notation])
    raise ArgumentError,
      "Invalid notation. Must be one of: " +
      "[:flat, :dot, :subscript, :flat_array]."
  end
  dehash = lambda do |hash|
    hash.each do |(key, value)|
      if value.kind_of?(Hash)
        hash[key] = dehash.call(value)
      end
    end
    if hash != {} && hash.keys.all? { |key| key =~ /^\d+$/ }
      hash.sort.inject([]) do |accu, (_, value)|
        accu << value; accu
      end
    else
      hash
    end
  end
  return nil if self.query == nil
  empty_accumulator = :flat_array == options[:notation] ? [] : {}
  return ((self.query.split("&").map do |pair|
    pair.split("=", 2) if pair && !pair.empty?
  end).compact.inject(empty_accumulator.dup) do |accumulator, (key, value)|
    value = true if value.nil?
    key = URI.unencode_component(key)
    if value != true
      value = URI.unencode_component(value.gsub(/\+/, " "))
    end
    if options[:notation] == :flat
      if accumulator[key]
        raise ArgumentError, "Key was repeated: #{key.inspect}"
      end
      accumulator[key] = value
    elsif options[:notation] == :flat_array
      accumulator << [key, value]
    else
      if options[:notation] == :dot
        array_value = false
        subkeys = key.split(".")
      elsif options[:notation] == :subscript
        array_value = !!(key =~ /\[\]$/)
        subkeys = key.split(/[\[\]]+/)
      end
      current_hash = accumulator
      for i in 0...(subkeys.size - 1)
        subkey = subkeys[i]
        current_hash[subkey] = {} unless current_hash[subkey]
        current_hash = current_hash[subkey]
      end
      if array_value
        current_hash[subkeys.last] = [] unless current_hash[subkeys.last]
        current_hash[subkeys.last] << value
      else
        current_hash[subkeys.last] = value
      end
    end
    accumulator
  end).inject(empty_accumulator.dup) do |accumulator, (key, value)|
    if options[:notation] == :flat_array
      accumulator << [key, value]
    else
      accumulator[key] = value.kind_of?(Hash) ? dehash.call(value) : value
    end
    accumulator
  end
end
query_values=(new_query_values) click to toggle source

Sets the query component for this URI from a Hash object. This method produces a query string using the :subscript notation. An empty Hash will result in a nil query.

@param [Hash, to_hash, Array] new_query_values The new query values.

# File lib/addressable/uri.rb, line 1501
def query_values=(new_query_values)
  if new_query_values == nil
    self.query = nil
    return nil
  end

  if !new_query_values.is_a?(Array)
    if !new_query_values.respond_to?(:to_hash)
      raise TypeError,
        "Can't convert #{new_query_values.class} into Hash."
    end
    new_query_values = new_query_values.to_hash
    new_query_values = new_query_values.map do |key, value|
      key = key.to_s if key.kind_of?(Symbol)
      [key, value]
    end
    # Useful default for OAuth and caching.
    # Only to be used for non-Array inputs. Arrays should preserve order.
    new_query_values.sort!
  end

  ##
  # Joins and converts parent and value into a properly encoded and
  # ordered URL query.
  #
  # @private
  # @param [String] parent an URI encoded component.
  # @param [Array, Hash, Symbol, #to_str] value
  #
  # @return [String] a properly escaped and ordered URL query.
  to_query = lambda do |parent, value|
    if value.is_a?(Hash)
      value = value.map do |key, val|
        [
          URI.encode_component(key, CharacterClasses::UNRESERVED),
          val
        ]
      end
      value.sort!
      buffer = ""
      value.each do |key, val|
        new_parent = "#{parent}[#{key}]"
        buffer << "#{to_query.call(new_parent, val)}&"
      end
      return buffer.chop
    elsif value.is_a?(Array)
      buffer = ""
      value.each_with_index do |val, i|
        new_parent = "#{parent}[#{i}]"
        buffer << "#{to_query.call(new_parent, val)}&"
      end
      return buffer.chop
    elsif value == true
      return parent
    else
      encoded_value = URI.encode_component(
        value, CharacterClasses::UNRESERVED
      )
      return "#{parent}=#{encoded_value}"
    end
  end

  # new_query_values have form [['key1', 'value1'], ['key2', 'value2']]
  buffer = ""
  new_query_values.each do |parent, value|
    encoded_parent = URI.encode_component(
      parent, CharacterClasses::UNRESERVED
    )
    buffer << "#{to_query.call(encoded_parent, value)}&"
  end
  self.query = buffer.chop
end
relative?() click to toggle source

Determines if the URI is relative.

@return [TrueClass, FalseClass]

<code>true</code> if the URI is relative. <code>false</code>
otherwise.
# File lib/addressable/uri.rb, line 1672
def relative?
  return self.scheme.nil?
end
request_uri() click to toggle source

The HTTP request URI for this URI. This is the path and the query string.

@return [String] The request URI required for an HTTP request.

# File lib/addressable/uri.rb, line 1579
def request_uri
  return nil if self.absolute? && self.scheme !~ /^https?$/
  return (
    (!self.path.empty? ? self.path : SLASH) +
    (self.query ? "?#{self.query}" : EMPTY_STR)
  )
end
request_uri=(new_request_uri) click to toggle source

Sets the HTTP request URI for this URI.

@param [String, to_str] new_request_uri The new HTTP request URI.

# File lib/addressable/uri.rb, line 1591
def request_uri=(new_request_uri)
  if !new_request_uri.respond_to?(:to_str)
    raise TypeError, "Can't convert #{new_request_uri.class} into String."
  end
  if self.absolute? && self.scheme !~ /^https?$/
    raise InvalidURIError,
      "Cannot set an HTTP request URI for a non-HTTP URI."
  end
  new_request_uri = new_request_uri.to_str
  path_component = new_request_uri[/^([^\?]*)\?(?:.*)$/, 1]
  query_component = new_request_uri[/^(?:[^\?]*)\?(.*)$/, 1]
  path_component = path_component.to_s
  path_component = (!path_component.empty? ? path_component : SLASH)
  self.path = path_component
  self.query = query_component

  # Reset dependant values
  @uri_string = nil
  @hash = nil
end
route_from(uri) click to toggle source

Returns the shortest normalized relative form of this URI that uses the supplied URI as a base for resolution. Returns an absolute URI if necessary. This is effectively the opposite of route_to.

@param [String, Addressable::URI, to_str] uri The URI to route from.

@return [Addressable::URI]

The normalized relative URI that is equivalent to the original URI.
# File lib/addressable/uri.rb, line 1888
def route_from(uri)
  uri = URI.parse(uri).normalize
  normalized_self = self.normalize
  if normalized_self.relative?
    raise ArgumentError, "Expected absolute URI, got: #{self.to_s}"
  end
  if uri.relative?
    raise ArgumentError, "Expected absolute URI, got: #{uri.to_s}"
  end
  if normalized_self == uri
    return Addressable::URI.parse("##{normalized_self.fragment}")
  end
  components = normalized_self.to_hash
  if normalized_self.scheme == uri.scheme
    components[:scheme] = nil
    if normalized_self.authority == uri.authority
      components[:user] = nil
      components[:password] = nil
      components[:host] = nil
      components[:port] = nil
      if normalized_self.path == uri.path
        components[:path] = nil
        if normalized_self.query == uri.query
          components[:query] = nil
        end
      else
        if uri.path != SLASH
          components[:path].gsub!(
            Regexp.new("^" + Regexp.escape(uri.path)), EMPTY_STR)
        end
      end
    end
  end
  # Avoid network-path references.
  if components[:host] != nil
    components[:scheme] = normalized_self.scheme
  end
  return Addressable::URI.new(
    :scheme => components[:scheme],
    :user => components[:user],
    :password => components[:password],
    :host => components[:host],
    :port => components[:port],
    :path => components[:path],
    :query => components[:query],
    :fragment => components[:fragment]
  )
end
route_to(uri) click to toggle source

Returns the shortest normalized relative form of the supplied URI that uses this URI as a base for resolution. Returns an absolute URI if necessary. This is effectively the opposite of route_from.

@param [String, Addressable::URI, to_str] uri The URI to route to.

@return [Addressable::URI]

The normalized relative URI that is equivalent to the supplied URI.
# File lib/addressable/uri.rb, line 1946
def route_to(uri)
  return URI.parse(uri).route_from(self)
end
scheme() click to toggle source

The scheme component for this URI.

@return [String] The scheme component.

# File lib/addressable/uri.rb, line 759
def scheme
  return instance_variable_defined?(:@scheme) ? @scheme : nil
end
scheme=(new_scheme) click to toggle source

Sets the scheme component for this URI.

@param [String, to_str] new_scheme The new scheme component.

# File lib/addressable/uri.rb, line 784
def scheme=(new_scheme)
  if new_scheme && !new_scheme.respond_to?(:to_str)
    raise TypeError, "Can't convert #{new_scheme.class} into String."
  elsif new_scheme
    new_scheme = new_scheme.to_str
  end
  if new_scheme && new_scheme !~ /[a-z][a-z0-9\.\+\-]*/
    raise InvalidURIError, "Invalid scheme format."
  end
  @scheme = new_scheme
  @scheme = nil if @scheme.to_s.strip.empty?

  # Reset dependant values
  @normalized_scheme = nil
  @uri_string = nil
  @hash = nil

  # Ensure we haven't created an invalid URI
  validate()
end
site() click to toggle source

The combination of components that represent a site. Combines the scheme, user, password, host, and port components. Primarily useful for HTTP and HTTPS.

For example, "http://example.com/path?query" would have a site value of "http://example.com".

@return [String] The components that identify a site.

# File lib/addressable/uri.rb, line 1222
def site
  (self.scheme || self.authority) && @site ||= (begin
    site_string = ""
    site_string << "#{self.scheme}:" if self.scheme != nil
    site_string << "//#{self.authority}" if self.authority != nil
    site_string
  end)
end
site=(new_site) click to toggle source

Sets the site value for this URI.

@param [String, to_str] new_site The new site value.

# File lib/addressable/uri.rb, line 1257
def site=(new_site)
  if new_site
    if !new_site.respond_to?(:to_str)
      raise TypeError, "Can't convert #{new_site.class} into String."
    end
    new_site = new_site.to_str
    # These two regular expressions derived from the primary parsing
    # expression
    self.scheme = new_site[/^(?:([^:\/?#]+):)?(?:\/\/(?:[^\/?#]*))?$/, 1]
    self.authority = new_site[
      /^(?:(?:[^:\/?#]+):)?(?:\/\/([^\/?#]*))?$/, 1
    ]
  else
    self.scheme = nil
    self.authority = nil
  end
end
to_hash() click to toggle source

Returns a Hash of the URI components.

@return [Hash] The URI as a Hash of components.

# File lib/addressable/uri.rb, line 2156
def to_hash
  return {
    :scheme => self.scheme,
    :user => self.user,
    :password => self.password,
    :host => self.host,
    :port => self.port,
    :path => self.path,
    :query => self.query,
    :fragment => self.fragment
  }
end
to_s() click to toggle source

Converts the URI to a String.

@return [String] The URI's String representation.

# File lib/addressable/uri.rb, line 2128
def to_s
  if self.scheme == nil && self.path != nil && !self.path.empty? &&
      self.path =~ NORMPATH
    raise InvalidURIError,
      "Cannot assemble URI string with ambiguous path: '#{self.path}'"
  end
  @uri_string ||= (begin
    uri_string = ""
    uri_string << "#{self.scheme}:" if self.scheme != nil
    uri_string << "//#{self.authority}" if self.authority != nil
    uri_string << self.path.to_s
    uri_string << "?#{self.query}" if self.query != nil
    uri_string << "##{self.fragment}" if self.fragment != nil
    if uri_string.respond_to?(:force_encoding)
      uri_string.force_encoding(Encoding::UTF_8)
    end
    uri_string
  end)
end
Also aliased as: to_str
to_str() click to toggle source

URI's are glorified Strings. Allow implicit conversion.

Alias for: to_s
user() click to toggle source

The user component for this URI.

@return [String] The user component.

# File lib/addressable/uri.rb, line 809
def user
  return instance_variable_defined?(:@user) ? @user : nil
end
user=(new_user) click to toggle source

Sets the user component for this URI.

@param [String, to_str] new_user The new user component.

# File lib/addressable/uri.rb, line 835
def user=(new_user)
  if new_user && !new_user.respond_to?(:to_str)
    raise TypeError, "Can't convert #{new_user.class} into String."
  end
  @user = new_user ? new_user.to_str : nil

  # You can't have a nil user with a non-nil password
  if password != nil
    @user = EMPTY_STR if @user.nil?
  end

  # Reset dependant values
  @userinfo = nil
  @normalized_userinfo = nil
  @authority = nil
  @normalized_user = nil
  @uri_string = nil
  @hash = nil

  # Ensure we haven't created an invalid URI
  validate()
end
userinfo() click to toggle source

The userinfo component for this URI. Combines the user and password components.

@return [String] The userinfo component.

# File lib/addressable/uri.rb, line 918
def userinfo
  current_user = self.user
  current_password = self.password
  (current_user || current_password) && @userinfo ||= (begin
    if current_user && current_password
      "#{current_user}:#{current_password}"
    elsif current_user && !current_password
      "#{current_user}"
    end
  end)
end
userinfo=(new_userinfo) click to toggle source

Sets the userinfo component for this URI.

@param [String, to_str] new_userinfo The new userinfo component.

# File lib/addressable/uri.rb, line 952
def userinfo=(new_userinfo)
  if new_userinfo && !new_userinfo.respond_to?(:to_str)
    raise TypeError, "Can't convert #{new_userinfo.class} into String."
  end
  new_user, new_password = if new_userinfo
    [
      new_userinfo.to_str.strip[/^(.*):/, 1],
      new_userinfo.to_str.strip[/:(.*)$/, 1]
    ]
  else
    [nil, nil]
  end

  # Password assigned first to ensure validity in case of nil
  self.password = new_password
  self.user = new_user

  # Reset dependant values
  @authority = nil
  @uri_string = nil
  @hash = nil

  # Ensure we haven't created an invalid URI
  validate()
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.