Class Addressable::URI
In: lib/addressable/uri.rb
Parent: Object

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>.

Methods

Classes and Modules

Module Addressable::URI::CharacterClasses
Class Addressable::URI::InvalidOptionError
Class Addressable::URI::InvalidTemplateOperatorError
Class Addressable::URI::InvalidTemplateValueError
Class Addressable::URI::InvalidURIError
Class Addressable::URI::TemplateOperatorAbortedError

External Aliases

encode_component -> encode_component
unencode -> unescape
unencode -> unencode_component
unencode -> unescape_component
encode -> escape

Public Class methods

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 <tt>String</tt> 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/"

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
  <tt>String</tt> or <tt>Addressable::URI</tt>.  All other values
  are invalid.  Defaults to <tt>String</tt>.

@return [String, Addressable::URI]

  The encoded URI.  The return type is determined by
  the <tt>returning</tt> parameter.

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 <tt>String</tt>
  is passed, the <tt>String</tt> must be formatted as a regular
  expression character class.  (Do not include the surrounding square
  brackets.)  For example, <tt>"b-zB-Z0-9"</tt> would cause everything
  but the letters 'b' through 'z' and the numbers '0' through '9' to be
  percent encoded.  If a <tt>Regexp</tt> is passed, the value
  <tt>/[^b-zB-Z0-9]/</tt> would have the same effect.
  A set of useful <tt>String</tt> values may be found in the
  <tt>Addressable::URI::CharacterClasses</tt> 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"

Expands a URI template into a full URI.

@param [String, to_str] pattern The URI template pattern. @param [Hash] mapping The mapping that corresponds to the pattern. @param [validate, transform] processor

  An optional processor object may be supplied.  The object should
  respond to either the <tt>validate</tt> or <tt>transform</tt> messages
  or both.  Both the <tt>validate</tt> and <tt>transform</tt> methods
  should take two parameters: <tt>name</tt> and <tt>value</tt>.  The
  <tt>validate</tt> method should return <tt>true</tt> or
  <tt>false</tt>; <tt>true</tt> if the value of the variable is valid,
  <tt>false</tt> otherwise.  An <tt>InvalidTemplateValueError</tt>
  exception will be raised if the value is invalid.  The
  <tt>transform</tt> method should return the transformed variable
  value as a <tt>String</tt>.  If a <tt>transform</tt> method is used,
  the value will not be percent encoded automatically.  Unicode
  normalization will be performed both before and after sending the
  value to the transform method.

@return [Addressable::URI] The expanded URI template.

@example

  class ExampleProcessor
    def self.validate(name, value)
      return !!(value =~ /^[\w ]+$/) if name == "query"
      return true
    end

    def self.transform(name, value)
      return value.gsub(/ /, "+") if name == "query"
      return value
    end
  end

  Addressable::URI.expand_template(
    "http://example.com/search/{query}/",
    {"query" => "an example search query"},
    ExampleProcessor
  ).to_s
  #=> "http://example.com/search/an+example+search+query/"

  Addressable::URI.expand_template(
    "http://example.com/search/{-list|+|query}/",
    {"query" => "an example search query".split(" ")}
  ).to_s
  #=> "http://example.com/search/an+example+search+query/"

  Addressable::URI.expand_template(
    "http://example.com/search/{query}/",
    {"query" => "bogus!"},
    ExampleProcessor
  ).to_s
  #=> Addressable::URI::InvalidTemplateValueError

Extracts uris from an arbitrary body of text.

@param [String, to_str] text

  The body of text to extract URIs from.

@option [String, Addressable::URI, to_str] base

  Causes any relative URIs to be resolved against the base URI.

@option [TrueClass, FalseClass] parse

  If parse is true, all extracted URIs will be parsed.  If parse is
  false, the return value with be an <tt>Array</tt> of <tt>Strings</aa>.
  Defaults to false.

@return [Array] The extracted URIs.

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 <tt>Addressable::URI</tt>.

@param [Hash] hints

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

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

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

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>

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.

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
  <tt>String</tt> or <tt>Addressable::URI</tt>.  All other values
  are invalid.  Defaults to <tt>String</tt>.

@return [String, Addressable::URI]

  The encoded URI.  The return type is determined by
  the <tt>returning</tt> parameter.

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 <tt>Addressable::URI</tt>.

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

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.

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
  <tt>String</tt> or <tt>Addressable::URI</tt>.  All other values
  are invalid.  Defaults to <tt>String</tt>.

@return [String, Addressable::URI]

  The unencoded component or URI.  The return type is determined by
  the <tt>returning</tt> parameter.

Public Instance methods

+(uri)

Alias for join

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]

  <tt>true</tt> if the URIs are equivalent, <tt>false</tt> otherwise.

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]

  <tt>true</tt> if the URIs are equivalent, <tt>false</tt> otherwise.

Determines if the URI is absolute.

@return [TrueClass, FalseClass]

  <tt>true</tt> if the URI is absolute.
  <tt>false</tt> otherwise.

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

@return [String] The authority component.

Sets the authority component for this URI.

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

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

@return [String] The path‘s basename.

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.

Clones the URI object.

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

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]

  <tt>true</tt> if the URIs are equivalent, <tt>false</tt> otherwise.

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

@return [String] The path‘s extname.

Extracts a mapping from the URI using a URI Template pattern.

@param [String] pattern

  A URI template pattern.

@param [restore, match] processor

  A template processor object may optionally be supplied.
  The object should respond to either the <tt>restore</tt> or
  <tt>match</tt> messages or both.  The <tt>restore</tt> method should
  take two parameters: [String] name and [String] value.  The
  <tt>restore</tt> method should reverse any transformations that have
  been performed on the value to ensure a valid URI.  The
  <tt>match</tt> method should take a single parameter: [String] name.
  The <tt>match</tt> method should return a <tt>String</tt> containing
  a regular expression capture group for matching on that particular
  variable.  The default value is ".*?".  The <tt>match</tt> method has
  no effect on multivariate operator expansions.

@return [Hash, NilClass]

  The <tt>Hash</tt> mapping that was extracted from the URI, or
  <tt>nil</tt> if the URI didn't match the template.

@example

  class ExampleProcessor
    def self.restore(name, value)
      return value.gsub(/\+/, " ") if name == "query"
      return value
    end

    def self.match(name)
      return ".*?" if name == "first"
      return ".*"
    end
  end

  uri = Addressable::URI.parse(
    "http://example.com/search/an+example+search+query/"
  )
  uri.extract_mapping(
    "http://example.com/search/{query}/",
    ExampleProcessor
  )
  #=> {"query" => "an example search query"}

  uri = Addressable::URI.parse("http://example.com/a/b/c/")
  uri.extract_mapping(
    "http://example.com/{first}/{second}/",
    ExampleProcessor
  )
  #=> {"first" => "a", "second" => "b/c"}

  uri = Addressable::URI.parse("http://example.com/a/b/c/")
  uri.extract_mapping(
    "http://example.com/{first}/{-list|/|second}/"
  )
  #=> {"first" => "a", "second" => ["b", "c"]}

The fragment component for this URI.

@return [String] The fragment component.

Sets the fragment component for this URI.

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

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

@return [Integer] A hash of the URI.

The host component for this URI.

@return [String] The host component.

Sets the host component for this URI.

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

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.

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

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

Determines if the scheme indicates an IP-based protocol.

@return [TrueClass, FalseClass]

  <tt>true</tt> if the scheme indicates an IP-based protocol.
  <tt>false</tt> otherwise.

Joins two URIs together.

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

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

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

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

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

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.

Destructively normalizes this URI object.

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

@see Addressable::URI#normalize

The authority component for this URI, normalized.

@return [String] The authority component, normalized.

The fragment component for this URI, normalized.

@return [String] The fragment component, normalized.

The host component for this URI, normalized.

@return [String] The host component, normalized.

The password component for this URI, normalized.

@return [String] The password component, normalized.

The path component for this URI, normalized.

@return [String] The path component, normalized.

The port component for this URI, normalized.

@return [Integer] The port component, normalized.

The query component for this URI, normalized.

@return [String] The query component, normalized.

The scheme component for this URI, normalized.

@return [String] The scheme component, normalized.

The user component for this URI, normalized.

@return [String] The user component, normalized.

The userinfo component for this URI, normalized.

@return [String] The userinfo component, normalized.

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>

Destructive form of omit.

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

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

@see Addressable::URI#omit

The password component for this URI.

@return [String] The password component.

Sets the password component for this URI.

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

The path component for this URI.

@return [String] The path component.

Sets the path component for this URI.

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

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.

Sets the port component for this URI.

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

The query component for this URI.

@return [String] The query component.

Sets the query component for this URI.

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

Converts the query component to a Hash value.

@option [Symbol] notation

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

@return [Hash] The query string parsed as a Hash 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"]}}}

Sets the query component for this URI from a Hash object.

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

Determines if the URI is relative.

@return [TrueClass, FalseClass]

  <tt>true</tt> if the URI is relative.
  <tt>false</tt> otherwise.

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.

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.

The scheme component for this URI.

@return [String] The scheme component.

Sets the scheme component for this URI.

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

Returns a Hash of the URI components.

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

Converts the URI to a String.

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

to_str()

Alias for to_s

The user component for this URI.

@return [String] The user component.

Sets the user component for this URI.

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

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

@return [String] The userinfo component.

Sets the userinfo component for this URI.

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

If URI validation needs to be disabled, this can be set to true.

@return [TrueClass, FalseClass]

  <tt>true</tt> if validation has been deferred,
  <tt>false</tt> otherwise.

If URI validation needs to be disabled, this can be set to true.

@param [TrueClass, FalseClass] new_validation_deferred

  <tt>true</tt> if validation will be deferred,
  <tt>false</tt> otherwise.

[Validate]