addressable 2.0.2 → 2.1.0

data/lib/addressable/uri.rb

@@ -1,4 +1,4 @@
-# coding:utf-8
+# encoding:utf-8
 #--
 # Addressable, Copyright (c) 2006-2008 Bob Aman
 #
@@ -44,21 +44,6 @@ module Addressable
     class InvalidOptionError < StandardError
     end
 
-    ##
-    # Raised if an invalid template value is supplied.
-    class InvalidTemplateValueError < StandardError
-    end
-
-    ##
-    # Raised if an invalid template operator is used in a pattern.
-    class InvalidTemplateOperatorError < StandardError
-    end
-
-    ##
-    # Raised if an invalid template operator is used in a pattern.
-    class TemplateOperatorAbortedError < StandardError
-    end
-
     ##
     # Container for the character classes specified in
     # <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>.
@@ -90,11 +75,6 @@ module Addressable
       return nil unless uri
       # If a URI object is passed, just return itself.
       return uri 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
 
       # If a URI object of the Ruby standard library variety is passed,
       # convert it to a string, then parse the string.
@@ -104,18 +84,22 @@ module Addressable
         uri = uri.to_s
       end
 
+      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
+
       # This Regexp supplied as an example in RFC 3986, and it works great.
       uri_regex =
-        /^(([^:\/?#]+):)?(\/\/([^\/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?/
+        /^(([^:\/?#]+):)?(\/\/([^\/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?$/
       scan = uri.scan(uri_regex)
       fragments = scan[0]
-      return nil if fragments.nil?
       scheme = fragments[1]
       authority = fragments[3]
       path = fragments[4]
       query = fragments[6]
       fragment = fragments[8]
-      userinfo = nil
       user = nil
       password = nil
       host = nil
@@ -186,16 +170,14 @@ module Addressable
       if parsed.scheme =~ /^[^\/?#\.]+\.[^\/?#]+$/
         parsed = self.parse(hints[:scheme] + "://" + uri)
       end
-      if parsed.authority == nil
-        if parsed.path =~ /^[^\/]+\./
-          new_host = parsed.path[/^([^\/]+\.[^\/]*)/, 1]
-          if new_host
-            new_path = parsed.path.gsub(
-              Regexp.new("^" + Regexp.escape(new_host)), "")
-            parsed.host = new_host
-            parsed.path = new_path
-            parsed.scheme = hints[:scheme]
-          end
+      if parsed.path.include?(".")
+        new_host = parsed.path[/^([^\/]+\.[^\/]*)/, 1]
+        if new_host
+          new_path = parsed.path.gsub(
+            Regexp.new("^" + Regexp.escape(new_host)), "")
+          parsed.host = new_host
+          parsed.path = new_path
+          parsed.scheme = hints[:scheme] unless parsed.scheme
         end
       end
       return parsed
@@ -266,643 +248,6 @@ module Addressable
       return uri
     end
 
-    ##
-    # 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
-    def self.expand_template(pattern, mapping, processor=nil)
-
-      # FIXME: MUST REFACTOR!!!
-
-      result = pattern.dup
-
-      reserved = Addressable::URI::CharacterClasses::RESERVED
-      unreserved = Addressable::URI::CharacterClasses::UNRESERVED
-      anything = reserved + unreserved
-      operator_expansion =
-        /\{-([a-zA-Z]+)\|([#{anything}]+)\|([#{anything}]+)\}/
-      variable_expansion = /\{([#{anything}]+?)(=([#{anything}]+))?\}/
-
-      transformed_mapping = mapping.inject({}) do |accu, pair|
-        name, value = pair
-        unless value.respond_to?(:to_ary) || value.respond_to?(:to_str)
-          raise TypeError,
-            "Can't convert #{value.class} into String or Array."
-        end
-
-        value =
-          value.respond_to?(:to_ary) ? value.to_ary : value.to_str
-        # Handle unicode normalization
-        if value.kind_of?(Array)
-          value.map! { |val| Addressable::IDNA.unicode_normalize_kc(val) }
-        else
-          value = Addressable::IDNA.unicode_normalize_kc(value)
-        end
-
-        if processor == nil || !processor.respond_to?(:transform)
-          # Handle percent escaping
-          if value.kind_of?(Array)
-            transformed_value = value.map do |val|
-              self.encode_component(
-                val, Addressable::URI::CharacterClasses::UNRESERVED)
-            end
-          else
-            transformed_value = self.encode_component(
-              value, Addressable::URI::CharacterClasses::UNRESERVED)
-          end
-        end
-
-        # Process, if we've got a processor
-        if processor != nil
-          if processor.respond_to?(:validate)
-            if !processor.validate(name, value)
-              display_value = value.kind_of?(Array) ? value.inspect : value
-              raise InvalidTemplateValueError,
-                "#{name}=#{display_value} is an invalid template value."
-            end
-          end
-          if processor.respond_to?(:transform)
-            transformed_value = processor.transform(name, value)
-            if transformed_value.kind_of?(Array)
-              transformed_value.map! do |val|
-                Addressable::IDNA.unicode_normalize_kc(val)
-              end
-            else
-              transformed_value =
-                Addressable::IDNA.unicode_normalize_kc(transformed_value)
-            end
-          end
-        end
-
-        accu[name] = transformed_value
-        accu
-      end
-      result.gsub!(
-        /#{operator_expansion}|#{variable_expansion}/
-      ) do |capture|
-        if capture =~ operator_expansion
-          operator, argument, variables, default_mapping =
-            parse_template_expansion(capture, transformed_mapping)
-          expand_method = "expand_#{operator}_operator"
-          if ([expand_method, expand_method.to_sym] & private_methods).empty?
-            raise InvalidTemplateOperatorError,
-              "Invalid template operator: #{operator}"
-          else
-            send(expand_method.to_sym, argument, variables, default_mapping)
-          end
-        else
-          varname, _, vardefault = capture.scan(/^\{(.+?)(=(.*))?\}$/)[0]
-          transformed_mapping[varname] || vardefault
-        end
-      end
-      return Addressable::URI.parse(result)
-    end
-
-    ##
-    # Expands a URI Template opt operator.
-    #
-    # @param [String] argument The argument to the operator.
-    # @param [Array] variables The variables the operator is working on.
-    # @param [Hash] mapping The mapping of variables to values.
-    #
-    # @return [String] The expanded result.
-    def self.expand_opt_operator(argument, variables, mapping)
-      if (variables.any? do |variable|
-        mapping[variable] != [] &&
-        mapping[variable]
-      end)
-        argument
-      else
-        ""
-      end
-    end
-    class <<self; private :expand_opt_operator; end
-
-    ##
-    # Expands a URI Template neg operator.
-    #
-    # @param [String] argument The argument to the operator.
-    # @param [Array] variables The variables the operator is working on.
-    # @param [Hash] mapping The mapping of variables to values.
-    #
-    # @return [String] The expanded result.
-    def self.expand_neg_operator(argument, variables, mapping)
-      if (variables.any? do |variable|
-        mapping[variable] != [] &&
-        mapping[variable]
-      end)
-        ""
-      else
-        argument
-      end
-    end
-    class <<self; private :expand_neg_operator; end
-
-    ##
-    # Expands a URI Template prefix operator.
-    #
-    # @param [String] argument The argument to the operator.
-    # @param [Array] variables The variables the operator is working on.
-    # @param [Hash] mapping The mapping of variables to values.
-    #
-    # @return [String] The expanded result.
-    def self.expand_prefix_operator(argument, variables, mapping)
-      if variables.size != 1
-        raise InvalidTemplateOperatorError,
-          "Template operator 'prefix' takes exactly one variable."
-      end
-      value = mapping[variables.first]
-      if value.kind_of?(Array)
-        (value.map { |list_value| argument + list_value }).join("")
-      else
-        argument + value.to_s
-      end
-    end
-    class <<self; private :expand_prefix_operator; end
-
-    ##
-    # Expands a URI Template suffix operator.
-    #
-    # @param [String] argument The argument to the operator.
-    # @param [Array] variables The variables the operator is working on.
-    # @param [Hash] mapping The mapping of variables to values.
-    #
-    # @return [String] The expanded result.
-    def self.expand_suffix_operator(argument, variables, mapping)
-      if variables.size != 1
-        raise InvalidTemplateOperatorError,
-          "Template operator 'suffix' takes exactly one variable."
-      end
-      value = mapping[variables.first]
-      if value.kind_of?(Array)
-        (value.map { |list_value| list_value + argument }).join("")
-      else
-        value.to_s + argument
-      end
-    end
-    class <<self; private :expand_suffix_operator; end
-
-    ##
-    # Expands a URI Template join operator.
-    #
-    # @param [String] argument The argument to the operator.
-    # @param [Array] variables The variables the operator is working on.
-    # @param [Hash] mapping The mapping of variables to values.
-    #
-    # @return [String] The expanded result.
-    def self.expand_join_operator(argument, variables, mapping)
-      variable_values = variables.inject([]) do |accu, variable|
-        if !mapping[variable].kind_of?(Array)
-          if mapping[variable]
-            accu << variable + "=" + (mapping[variable])
-          end
-        else
-          raise InvalidTemplateOperatorError,
-            "Template operator 'join' does not accept Array values."
-        end
-        accu
-      end
-      variable_values.join(argument)
-    end
-    class <<self; private :expand_join_operator; end
-
-    ##
-    # Expands a URI Template list operator.
-    #
-    # @param [String] argument The argument to the operator.
-    # @param [Array] variables The variables the operator is working on.
-    # @param [Hash] mapping The mapping of variables to values.
-    #
-    # @return [String] The expanded result.
-    def self.expand_list_operator(argument, variables, mapping)
-      if variables.size != 1
-        raise InvalidTemplateOperatorError,
-          "Template operator 'list' takes exactly one variable."
-      end
-      mapping[variables.first].join(argument)
-    end
-    class <<self; private :expand_list_operator; end
-
-    ##
-    # Parses a URI template expansion <tt>String</tt>.
-    #
-    # @param [String] expansion The operator <tt>String</tt>.
-    # @param [Hash] mapping The mapping to merge defaults into.
-    #
-    # @return [Array]
-    #   A tuple of the operator, argument, variables, and mapping.
-    def self.parse_template_expansion(capture, mapping)
-      operator, argument, variables = capture[1...-1].split("|")
-      operator.gsub!(/^\-/, "")
-      variables = variables.split(",")
-      mapping = (variables.inject({}) do |accu, var|
-        varname, _, vardefault = var.scan(/^(.+?)(=(.*))?$/)[0]
-        accu[varname] = vardefault
-        accu
-      end).merge(mapping)
-      variables = variables.map { |var| var.gsub(/=.*$/, "") }
-      return operator, argument, variables, mapping
-    end
-    class <<self; private :parse_template_expansion; end
-
-    ##
-    # 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"]}
-    def extract_mapping(pattern, processor=nil)
-      reserved = Addressable::URI::CharacterClasses::RESERVED
-      unreserved = Addressable::URI::CharacterClasses::UNRESERVED
-      anything = reserved + unreserved
-      operator_expansion =
-        /\{-([a-zA-Z]+)\|([#{anything}]+)\|([#{anything}]+)\}/
-      variable_expansion = /\{([#{anything}]+?)(=([#{anything}]+))?\}/
-
-      # First, we need to process the pattern, and extract the values.
-      expansions, expansion_regexp =
-        parse_template_pattern(pattern, processor)
-      unparsed_values = self.to_s.scan(expansion_regexp).flatten
-
-      mapping = {}
-
-      if self.to_s == pattern
-        return mapping
-      elsif expansions.size > 0 && expansions.size == unparsed_values.size
-        expansions.each_with_index do |expansion, index|
-          unparsed_value = unparsed_values[index]
-          if expansion =~ operator_expansion
-            operator, argument, variables =
-              parse_template_expansion(expansion)
-            extract_method = "extract_#{operator}_operator"
-            if ([extract_method, extract_method.to_sym] &
-                private_methods).empty?
-              raise InvalidTemplateOperatorError,
-                "Invalid template operator: #{operator}"
-            else
-              begin
-                send(
-                  extract_method.to_sym, unparsed_value, processor,
-                  argument, variables, mapping
-                )
-              rescue TemplateOperatorAbortedError
-                return nil
-              end
-            end
-          else
-            name = expansion[variable_expansion, 1]
-            value = unparsed_value
-            if processor != nil && processor.respond_to?(:restore)
-              value = processor.restore(name, value)
-            end
-            mapping[name] = value
-          end
-        end
-        return mapping
-      else
-        return nil
-      end
-    end
-
-    ##
-    # Generates the <tt>Regexp</tt> that parses a template pattern.
-    #
-    # @param [String] pattern The URI template pattern.
-    # @param [#match] processor The template processor to use.
-    #
-    # @return [Regexp]
-    #   A regular expression which may be used to parse a template pattern.
-    def parse_template_pattern(pattern, processor)
-      reserved = Addressable::URI::CharacterClasses::RESERVED
-      unreserved = Addressable::URI::CharacterClasses::UNRESERVED
-      anything = reserved + unreserved
-      operator_expansion =
-        /\{-[a-zA-Z]+\|[#{anything}]+\|[#{anything}]+\}/
-      variable_expansion = /\{([#{anything}]+?)(=([#{anything}]+))?\}/
-
-      # Escape the pattern.  The two gsubs restore the escaped curly braces
-      # back to their original form.  Basically, escape everything that isn't
-      # within an expansion.
-      escaped_pattern = Regexp.escape(
-        pattern
-      ).gsub(/\\\{(.*?)\\\}/) do |escaped|
-        escaped.gsub(/\\(.)/, "\\1")
-      end
-
-      expansions = []
-
-      # Create a regular expression that captures the values of the
-      # variables in the URI.
-      regexp_string = escaped_pattern.gsub(
-        /#{operator_expansion}|#{variable_expansion}/
-      ) do |expansion|
-        expansions << expansion
-        if expansion =~ operator_expansion
-          capture_group = "(.*)"
-          if processor != nil && processor.respond_to?(:match)
-            # We can only lookup the match values for single variable
-            # operator expansions.  Besides, ".*" is usually the only
-            # reasonable value for multivariate operators anyways.
-            operator, _, names, _ =
-              parse_template_expansion(expansion)
-            if ["prefix", "suffix", "list"].include?(operator)
-              capture_group = "(#{processor.match(names.first)})"
-            end
-          end
-          capture_group
-        else
-          capture_group = "(.*?)"
-          if processor != nil && processor.respond_to?(:match)
-            name = expansion[/\{([^\}=]+)(=[^\}]+)?\}/, 1]
-            capture_group = "(#{processor.match(name)})"
-          end
-          capture_group
-        end
-      end
-
-      # Ensure that the regular expression matches the whole URI.
-      regexp_string = "^#{regexp_string}$"
-
-      return expansions, Regexp.new(regexp_string)
-    end
-    private :parse_template_pattern
-
-    ##
-    # Parses a URI template expansion <tt>String</tt>.
-    #
-    # @param [String] expansion The operator <tt>String</tt>.
-    #
-    # @return [Array]
-    #   A tuple of the operator, argument, variables.
-    def parse_template_expansion(capture)
-      operator, argument, variables = capture[1...-1].split("|")
-      operator.gsub!(/^\-/, "")
-      variables = variables.split(",").map { |var| var.gsub(/=.*$/, "") }
-      return operator, argument, variables
-    end
-    private :parse_template_expansion
-
-
-    ##
-    # Extracts a URI Template opt operator.
-    #
-    # @param [String] value The unparsed value to extract from.
-    # @param [#restore] processor The processor object.
-    # @param [String] argument The argument to the operator.
-    # @param [Array] variables The variables the operator is working on.
-    # @param [Hash] mapping The mapping of variables to values.
-    #
-    # @return [String] The extracted result.
-    def extract_opt_operator(
-        value, processor, argument, variables, mapping)
-      if value != "" && value != argument
-        raise TemplateOperatorAbortedError,
-          "Value for template operator 'neg' was unexpected."
-      end
-    end
-    private :extract_opt_operator
-
-    ##
-    # Extracts a URI Template neg operator.
-    #
-    # @param [String] value The unparsed value to extract from.
-    # @param [#restore] processor The processor object.
-    # @param [String] argument The argument to the operator.
-    # @param [Array] variables The variables the operator is working on.
-    # @param [Hash] mapping The mapping of variables to values.
-    #
-    # @return [String] The extracted result.
-    def extract_neg_operator(
-        value, processor, argument, variables, mapping)
-      if value != "" && value != argument
-        raise TemplateOperatorAbortedError,
-          "Value for template operator 'neg' was unexpected."
-      end
-    end
-    private :extract_neg_operator
-
-    ##
-    # Extracts a URI Template prefix operator.
-    #
-    # @param [String] value The unparsed value to extract from.
-    # @param [#restore] processor The processor object.
-    # @param [String] argument The argument to the operator.
-    # @param [Array] variables The variables the operator is working on.
-    # @param [Hash] mapping The mapping of variables to values.
-    #
-    # @return [String] The extracted result.
-    def extract_prefix_operator(
-        value, processor, argument, variables, mapping)
-      if variables.size != 1
-        raise InvalidTemplateOperatorError,
-          "Template operator 'suffix' takes exactly one variable."
-      end
-      if value[0...argument.size] != argument
-        raise TemplateOperatorAbortedError,
-          "Value for template operator 'prefix' missing expected prefix."
-      end
-      values = value.split(argument)
-      # Compensate for the crappy result from split.
-      if value[-argument.size..-1] == argument
-        values << ""
-      end
-      if values[0] == ""
-        values.shift
-      end
-      if processor && processor.respond_to?(:restore)
-        values.map! { |value| processor.restore(variables.first, value) }
-      end
-      mapping[variables.first] = values
-    end
-    private :extract_prefix_operator
-
-    ##
-    # Extracts a URI Template suffix operator.
-    #
-    # @param [String] value The unparsed value to extract from.
-    # @param [#restore] processor The processor object.
-    # @param [String] argument The argument to the operator.
-    # @param [Array] variables The variables the operator is working on.
-    # @param [Hash] mapping The mapping of variables to values.
-    #
-    # @return [String] The extracted result.
-    def extract_suffix_operator(
-        value, processor, argument, variables, mapping)
-      if variables.size != 1
-        raise InvalidTemplateOperatorError,
-          "Template operator 'suffix' takes exactly one variable."
-      end
-      if value[-argument.size..-1] != argument
-        raise TemplateOperatorAbortedError,
-          "Value for template operator 'suffix' missing expected suffix."
-      end
-      values = value.split(argument)
-      # Compensate for the crappy result from split.
-      if value[-argument.size..-1] == argument
-        values << ""
-      end
-      if values[-1] == ""
-        values.pop
-      end
-      if processor && processor.respond_to?(:restore)
-        values.map! { |value| processor.restore(variables.first, value) }
-      end
-      mapping[variables.first] = values
-    end
-    private :extract_suffix_operator
-
-    ##
-    # Extracts a URI Template join operator.
-    #
-    # @param [String] value The unparsed value to extract from.
-    # @param [#restore] processor The processor object.
-    # @param [String] argument The argument to the operator.
-    # @param [Array] variables The variables the operator is working on.
-    # @param [Hash] mapping The mapping of variables to values.
-    #
-    # @return [String] The extracted result.
-    def extract_join_operator(value, processor, argument, variables, mapping)
-      unparsed_values = value.split(argument)
-      parsed_variables = []
-      for unparsed_value in unparsed_values
-        name = unparsed_value[/^(.+?)=(.+)$/, 1]
-        parsed_variables << name
-        parsed_value = unparsed_value[/^(.+?)=(.+)$/, 2]
-        if processor && processor.respond_to?(:restore)
-          parsed_value = processor.restore(name, parsed_value)
-        end
-        mapping[name] = parsed_value
-      end
-      if (parsed_variables & variables) != parsed_variables
-        raise TemplateOperatorAbortedError,
-          "Template operator 'join' variable mismatch: " +
-          "#{parsed_variables.inspect}, #{variables.inspect}"
-      end
-    end
-    private :extract_join_operator
-
-    ##
-    # Extracts a URI Template list operator.
-    #
-    # @param [String] value The unparsed value to extract from.
-    # @param [#restore] processor The processor object.
-    # @param [String] argument The argument to the operator.
-    # @param [Array] variables The variables the operator is working on.
-    # @param [Hash] mapping The mapping of variables to values.
-    #
-    # @return [String] The extracted result.
-    def extract_list_operator(value, processor, argument, variables, mapping)
-      if variables.size != 1
-        raise InvalidTemplateOperatorError,
-          "Template operator 'list' takes exactly one variable."
-      end
-      values = value.split(argument)
-      if processor && processor.respond_to?(:restore)
-        values.map! { |value| processor.restore(variables.first, value) }
-      end
-      mapping[variables.first] = values
-    end
-    private :extract_list_operator
-
     ##
     # Joins several URIs together.
     #
@@ -973,6 +318,12 @@ module Addressable
       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
@@ -1111,7 +462,13 @@ module Addressable
       }
       components.each do |key, value|
         if value != nil
-          components[key] = Addressable::IDNA.unicode_normalize_kc(value.to_s)
+          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(
@@ -1137,67 +494,6 @@ module Addressable
       end
     end
 
-    ##
-    # 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.
-    def self.extract(text, options={})
-      defaults = {:base => nil, :parse => false}
-      options = defaults.merge(options)
-      raise InvalidOptionError unless (options.keys - defaults.keys).empty?
-      # This regular expression needs to be less forgiving or else it would
-      # match virtually all text.  Which isn't exactly what we're going for.
-      extract_regex = /((([a-z\+]+):)[^ \n\<\>\"\\]+[\w\/])/
-      extracted_uris =
-        text.scan(extract_regex).collect { |match| match[0] }
-      sgml_extract_regex = /<[^>]+href=\"([^\"]+?)\"[^>]*>/
-      sgml_extracted_uris =
-        text.scan(sgml_extract_regex).collect { |match| match[0] }
-      extracted_uris.concat(sgml_extracted_uris - extracted_uris)
-      textile_extract_regex = /\".+?\":([^ ]+\/[^ ]+)[ \,\.\;\:\?\!\<\>\"]/i
-      textile_extracted_uris =
-        text.scan(textile_extract_regex).collect { |match| match[0] }
-      extracted_uris.concat(textile_extracted_uris - extracted_uris)
-      parsed_uris = []
-      base_uri = nil
-      if options[:base] != nil
-        base_uri = options[:base] if options[:base].kind_of?(self)
-        base_uri = self.parse(options[:base].to_s) if base_uri == nil
-      end
-      for uri_string in extracted_uris
-        begin
-          if base_uri == nil
-            parsed_uris << self.parse(uri_string)
-          else
-            parsed_uris << (base_uri + self.parse(uri_string))
-          end
-        rescue Exception
-          nil
-        end
-      end
-      parsed_uris = parsed_uris.select do |uri|
-        (self.ip_based_schemes | [
-          "file", "git", "svn", "mailto", "tel"
-        ]).include?(uri.normalized_scheme)
-      end
-      if options[:parse]
-        return parsed_uris
-      else
-        return parsed_uris.collect { |uri| uri.to_s }
-      end
-    end
-
     ##
     # Creates a new uri object from component parts.
     #
@@ -1282,11 +578,18 @@ module Addressable
     #
     # @param [String, #to_str] new_scheme The new scheme component.
     def scheme=(new_scheme)
+      # Check for frozenness
+      raise TypeError, "Can't modify frozen URI." if self.frozen?
+
       @scheme = new_scheme ? new_scheme.to_str : nil
       @scheme = nil if @scheme.to_s.strip == ""
 
       # Reset dependant values
       @normalized_scheme = nil
+      @uri_string = nil
+
+      # Ensure we haven't created an invalid URI
+      validate()
     end
 
     ##
@@ -1325,9 +628,13 @@ module Addressable
     #
     # @param [String, #to_str] new_user The new user component.
     def user=(new_user)
+      # Check for frozenness
+      raise TypeError, "Can't modify frozen URI." if self.frozen?
+
       @user = new_user ? new_user.to_str : nil
 
       # You can't have a nil user with a non-nil password
+      @password ||= nil
       if @password != nil
         @user = "" if @user.nil?
       end
@@ -1337,6 +644,7 @@ module Addressable
       @normalized_userinfo = nil
       @authority = nil
       @normalized_user = nil
+      @uri_string = nil
 
       # Ensure we haven't created an invalid URI
       validate()
@@ -1378,9 +686,14 @@ module Addressable
     #
     # @param [String, #to_str] new_password The new password component.
     def password=(new_password)
+      # Check for frozenness
+      raise TypeError, "Can't modify frozen URI." if self.frozen?
+
       @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 = "" if @user.nil?
       end
@@ -1390,6 +703,7 @@ module Addressable
       @normalized_userinfo = nil
       @authority = nil
       @normalized_password = nil
+      @uri_string = nil
 
       # Ensure we haven't created an invalid URI
       validate()
@@ -1437,6 +751,9 @@ module Addressable
     #
     # @param [String, #to_str] new_userinfo The new userinfo component.
     def userinfo=(new_userinfo)
+      # Check for frozenness
+      raise TypeError, "Can't modify frozen URI." if self.frozen?
+
       new_user, new_password = if new_userinfo
         [
           new_userinfo.to_str.strip[/^(.*):/, 1],
@@ -1452,6 +769,7 @@ module Addressable
 
       # Reset dependant values
       @authority = nil
+      @uri_string = nil
 
       # Ensure we haven't created an invalid URI
       validate()
@@ -1495,11 +813,15 @@ module Addressable
     #
     # @param [String, #to_str] new_host The new host component.
     def host=(new_host)
+      # Check for frozenness
+      raise TypeError, "Can't modify frozen URI." if self.frozen?
+
       @host = new_host ? new_host.to_str : nil
 
       # Reset dependant values
       @authority = nil
       @normalized_host = nil
+      @uri_string = nil
 
       # Ensure we haven't created an invalid URI
       validate()
@@ -1555,6 +877,9 @@ module Addressable
     #
     # @param [String, #to_str] new_authority The new authority component.
     def authority=(new_authority)
+      # Check for frozenness
+      raise TypeError, "Can't modify frozen URI." if self.frozen?
+
       if new_authority
         new_authority = new_authority.to_str
         new_userinfo = new_authority[/^([^\[\]]*)@/, 1]
@@ -1578,6 +903,7 @@ module Addressable
       @inferred_port = nil
       @userinfo = nil
       @normalized_userinfo = nil
+      @uri_string = nil
 
       # Ensure we haven't created an invalid URI
       validate()
@@ -1618,7 +944,7 @@ module Addressable
     #
     # @return [Integer] The port component.
     def port
-      return @port
+      return @port ||= nil
     end
 
     ##
@@ -1640,6 +966,9 @@ module Addressable
     #
     # @param [String, Integer, #to_s] new_port The new port component.
     def port=(new_port)
+      # Check for frozenness
+      raise TypeError, "Can't modify frozen URI." if self.frozen?
+
       if new_port != nil && new_port.respond_to?(:to_str)
         new_port = Addressable::URI.unencode_component(new_port.to_str)
       end
@@ -1655,6 +984,7 @@ module Addressable
       @authority = nil
       @inferred_port = nil
       @normalized_port = nil
+      @uri_string = nil
 
       # Ensure we haven't created an invalid URI
       validate()
@@ -1694,11 +1024,19 @@ module Addressable
     # @return [String] The path component, normalized.
     def normalized_path
       @normalized_path ||= (begin
-        result = Addressable::URI.encode_component(
-          Addressable::IDNA.unicode_normalize_kc(
-            Addressable::URI.unencode_component(self.path.strip)),
-          Addressable::URI::CharacterClasses::PATH
-        )
+        begin
+          result = Addressable::URI.encode_component(
+            Addressable::IDNA.unicode_normalize_kc(
+              Addressable::URI.unencode_component(self.path.strip)),
+            Addressable::URI::CharacterClasses::PATH
+          )
+        rescue ArgumentError
+          # Likely a malformed UTF-8 character, skip unicode normalization
+          result = Addressable::URI.encode_component(
+            Addressable::URI.unencode_component(self.path.strip),
+            Addressable::URI::CharacterClasses::PATH
+          )
+        end
         result = self.class.normalize_path(result)
         if result == "" &&
             ["http", "https", "ftp", "tftp"].include?(self.normalized_scheme)
@@ -1713,6 +1051,9 @@ module Addressable
     #
     # @param [String, #to_str] new_path The new path component.
     def path=(new_path)
+      # Check for frozenness
+      raise TypeError, "Can't modify frozen URI." if self.frozen?
+
       @path = (new_path || "").to_str
       if @path != "" && @path[0..0] != "/" && host != nil
         @path = "/#{@path}"
@@ -1720,6 +1061,7 @@ module Addressable
 
       # Reset dependant values
       @normalized_path = nil
+      @uri_string = nil
     end
 
     ##
@@ -1772,10 +1114,14 @@ module Addressable
     #
     # @param [String, #to_str] new_query The new query component.
     def query=(new_query)
+      # Check for frozenness
+      raise TypeError, "Can't modify frozen URI." if self.frozen?
+
       @query = new_query ? new_query.to_str : nil
 
       # Reset dependant values
       @normalized_query = nil
+      @uri_string = nil
     end
 
     ##
@@ -1816,11 +1162,24 @@ module Addressable
         raise ArgumentError,
           "Invalid notation. Must be one of: [:flat, :dot, :subscript]."
       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, (key, value)|
+            accu << value; accu
+          end
+        else
+          hash
+        end
+      end
       return nil if self.query == nil
-      return (self.query.split("&").map do |pair|
+      return ((self.query.split("&").map do |pair|
         pair.split("=")
-      end).inject({}) do |accumulator, pair|
-        key, value = pair
+      end).inject({}) do |accumulator, (key, value)|
         value = true if value.nil?
         key = self.class.unencode_component(key)
         if value != true
@@ -1853,28 +1212,62 @@ module Addressable
           end
         end
         accumulator
+      end).inject({}) do |accumulator, (key, value)|
+        accumulator[key] = value.kind_of?(Hash) ? dehash.call(value) : value
+        accumulator
       end
     end
 
     ##
     # Sets the query component for this URI from a Hash object.
+    # This method produces a query string using the :subscript notation.
     #
     # @param [Hash, #to_hash] new_query_values The new query values.
     def query_values=(new_query_values)
-      @query = (new_query_values.to_hash.inject([]) do |accumulator, pair|
-        key, value = pair
-        key = self.class.encode_component(key, CharacterClasses::UNRESERVED)
-        if value == true
-          accumulator << "#{key}"
+      # Check for frozenness
+      raise TypeError, "Can't modify frozen URI." if self.frozen?
+      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
+
+      # Algorithm shamelessly stolen from Julien Genestoux, slightly modified
+      buffer = ""
+      stack = []
+      e = lambda do |component|
+        component = component.to_s if component.kind_of?(Symbol)
+        self.class.encode_component(component, CharacterClasses::UNRESERVED)
+      end
+      new_query_values.each do |key, value|
+        if value.kind_of?(Hash)
+          stack << [key, value]
+        elsif value.kind_of?(Array)
+          stack << [
+            key,
+            value.inject({}) { |accu, x| accu[accu.size.to_s] = x; accu }
+          ]
+        elsif value == true
+          buffer << "#{e.call(key)}&"
         else
-          value = self.class.encode_component(
-            value, CharacterClasses::UNRESERVED)
-          accumulator << "#{key}=#{value}"
+          buffer << "#{e.call(key)}=#{e.call(value)}&"
+        end
+      end
+      stack.each do |(parent, hash)|
+        (hash.sort_by { |key| key.to_s }).each do |(key, value)|
+          if value.kind_of?(Hash)
+            stack << ["#{parent}[#{key}]", value]
+          elsif value == true
+            buffer << "#{parent}[#{e.call(key)}]&"
+          else
+            buffer << "#{parent}[#{e.call(key)}]=#{e.call(value)}&"
+          end
         end
-      end).join("&")
+      end
+      @query = buffer.chop
 
       # Reset dependant values
       @normalized_query = nil
+      @uri_string = nil
     end
 
     ##
@@ -1908,10 +1301,17 @@ module Addressable
     #
     # @param [String, #to_str] new_fragment The new fragment component.
     def fragment=(new_fragment)
+      # Check for frozenness
+      raise TypeError, "Can't modify frozen URI." if self.frozen?
+
       @fragment = new_fragment ? new_fragment.to_str : nil
 
       # Reset dependant values
       @normalized_fragment = nil
+      @uri_string = nil
+
+      # Ensure we haven't created an invalid URI
+      validate()
     end
 
     ##
@@ -2259,8 +1659,7 @@ module Addressable
     # @return [Addressable::URI] A URI suitable for display purposes.
     def display_uri
       display_uri = self.normalize
-      display_uri.instance_variable_set("@host",
-        ::Addressable::IDNA.to_unicode(display_uri.host))
+      display_uri.host = ::Addressable::IDNA.to_unicode(display_uri.host)
       return display_uri
     end
 
@@ -2318,7 +1717,7 @@ module Addressable
     #
     # @return [Integer] A hash of the URI.
     def hash
-      return (self.normalize.to_s.hash * -1)
+      return @hash ||= (self.to_s.hash * -1)
     end
 
     ##
@@ -2339,6 +1738,28 @@ module Addressable
       return duplicated_uri
     end
 
+    ##
+    # Freezes the URI object.
+    #
+    # @return [Addressable::URI] The frozen URI.
+    def freeze
+      # Unfortunately, because of the memoized implementation of many of the
+      # URI methods, the default freeze method will cause unexpected errors.
+      # As an alternative, we freeze the string representation of the URI
+      # instead.  This should generally produce the desired effect.
+      self.to_s.freeze
+      return self
+    end
+
+    ##
+    # Determines if the URI is frozen.
+    #
+    # @return [TrueClass, FalseClass]
+    #   True if the URI is frozen, false otherwise.
+    def frozen?
+      self.to_s.frozen?
+    end
+
     ##
     # Omits components from a URI.
     #
@@ -2365,6 +1786,7 @@ module Addressable
       components.each do |component|
         duplicated_uri.send((component.to_s + "=").to_sym, nil)
       end
+      duplicated_uri.user = duplicated_uri.normalized_user
       duplicated_uri.validation_deferred = false
       duplicated_uri
     end
@@ -2386,16 +1808,18 @@ module Addressable
     #
     # @return [String] The URI's <tt>String</tt> representation.
     def to_s
-      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
-      return uri_string
+      @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
 
     ##
@@ -2434,7 +1858,7 @@ module Addressable
     #   <tt>true</tt> if validation has been deferred,
     #   <tt>false</tt> otherwise.
     def validation_deferred
-      @validation_deferred ||= false
+      !!@validation_deferred
     end
 
     ##
@@ -2444,6 +1868,9 @@ module Addressable
     #   <tt>true</tt> if validation will be deferred,
     #   <tt>false</tt> otherwise.
     def validation_deferred=(new_validation_deferred)
+      # Check for frozenness
+      raise TypeError, "Can't modify frozen URI." if self.frozen?
+
       @validation_deferred = new_validation_deferred
       validate unless @validation_deferred
     end