/mack-data_mapper/lib/gems/addressable-2.0.1/lib/addressable/uri.rb

Large files files are truncated, but you can click here to view the full file

# coding:utf-8
#--
# Addressable, Copyright (c) 2006-2008 Bob Aman
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#++

$:.unshift(File.expand_path(File.join(File.dirname(__FILE__), '/..')))
$:.uniq!

require "addressable/version"
require "addressable/idna"

module Addressable
  ##
  # This is an implementation of a URI parser based on
  # <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>,
  # <a href="http://www.ietf.org/rfc/rfc3987.txt">RFC 3987</a>.
  class URI
    ##
    # Raised if something other than a uri is supplied.
    class InvalidURIError < StandardError
    end

    ##
    # Raised if an invalid method option is supplied.
    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>.
    module CharacterClasses
      ALPHA = "a-zA-Z"
      DIGIT = "0-9"
      GEN_DELIMS = "\\:\\/\\?\\#\\[\\]\\@"
      SUB_DELIMS = "\\!\\$\\&\\'\\(\\)\\*\\+\\,\\;\\="
      RESERVED = GEN_DELIMS + SUB_DELIMS
      UNRESERVED = ALPHA + DIGIT + "\\-\\.\\_\\~"
      PCHAR = UNRESERVED + SUB_DELIMS + "\\:\\@"
      SCHEME = ALPHA + DIGIT + "\\-\\+\\."
      AUTHORITY = PCHAR
      PATH = PCHAR + "\\/"
      QUERY = PCHAR + "\\/\\?"
      FRAGMENT = PCHAR + "\\/\\?"
    end

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

      # 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
      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(/^([^\[\]]*)@/, "").gsub(/:([^:@\[\]]*?)$/, "")
        port = authority[/:([^:@\[\]]*?)$/, 1]
      end
      if port == ""
        port = nil
      end

      return Addressable::URI.new(
        :scheme => scheme,
        :user => user,
        :password => password,
        :host => host,
        :port => port,
        :path => path,
        :query => query,
        :fragment => fragment
      )
    end

    ##
    # 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.
    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 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 /^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.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
        end
      end
      return parsed
    end

    ##
    # 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 <tt>Addressable::URI.parse</tt>.  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/"
    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:\/?\/?/, "") if path =~ /^file:\/?\/?/
      path = "/" + path if path =~ /^([a-zA-Z])(\||:)/
      uri = self.parse(path)

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

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

      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>.
    #
    # @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
        transformed_value =
          value.respond_to?(:to_ary) ? value.to_ary : value.to_str

        # Handle percent escaping, and unicode normalization
        if transformed_value.kind_of?(Array)
          transformed_value.map! do |value|
            self.encode_component(
              Addressable::IDNA.unicode_normalize_kc(value),
              Addressable::URI::CharacterClasses::UNRESERVED
            )
          end
        else
          transformed_value = self.encode_component(
            Addressable::IDNA.unicode_normalize_kc(transformed_value),
            Addressable::URI::CharacterClasses::UNRESERVED
          )
        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)
          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.
    #
    # @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>
    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

    ##
    # 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"
    def self.encode_component(component, character_class=
        CharacterClasses::RESERVED + CharacterClasses::UNRESERVED)
      return nil if component.nil?
      if !component.respond_to?(:to_str)
        raise TypeError, "Can't convert #{component.class} into String."
      end
      component = component.to_str
      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
      return component.gsub(character_class) do |sequence|
        (sequence.unpack('C*').map { |c| "%#{c.to_s(16).upcase}" }).join("")
      end
    end

    class << self
      alias_method :encode_component, :encode_component
    end

    ##
    # 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 <tt>unencode_component</tt> 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.
    def self.unencode(uri, returning=String)
      return nil if uri.nil?
      if !uri.respond_to?(:to_str)
        raise TypeError, "Can't convert #{uri.class} into String."
      end
      if ![String, ::Addressable::URI].include?(returning)
        raise TypeError,
          "Expected Class (String or Addressable::URI), " +
          "got #{returning.inspect}"
      end
      result = uri.to_str.gsub(/%[0-9a-f]{2}/i) 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

    class << self
      alias_method :unescape, :unencode
      alias_method :unencode_component, :unencode
      alias_method :unescape_component, :unencode
    end

    ##
    # 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.
    def self.encode(uri, returning=String)
      return nil if uri.nil?
      if !uri.respond_to?(:to_str)
        raise TypeError, "Can't convert #{uri.class} into String."
      end
      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.to_str)
      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

    class << self
      alias_method :escape, :encode
    end

    ##
    # 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.
    def self.normalized_encode(uri, returning=String)
      if !uri.respond_to?(:to_str)
        raise TypeError, "Can't convert #{uri.class} into String."
      end
      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.to_str)
      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
          components[key] = Addressable::IDNA.unicode_normalize_kc(value.to_s)
        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

    ##
    # 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.
    #
    # @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.
    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.validation_deferred = true
      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.fragment = options[:fragment] if options[:fragment]
      self.validation_deferred = false
    end

    ##
    # The scheme component for this URI.
    #
    # @return [String] The scheme component.
    def scheme
      return @scheme
    end

    ##
    # The scheme component for this URI, normalized.
    #
    # @return [String] The scheme component, normalized.
    def normalized_scheme
      @normalized_scheme ||= (begin
        if self.scheme != nil
          if self.scheme =~ /^\s*ssh\+svn\s*$/i
            "svn+ssh"
          else
            Addressable::URI.encode_component(
              Addressable::IDNA.unicode_normalize_kc(
                Addressable::URI.unencode_component(
                  self.scheme.strip.downcase)),
              Addressable::URI::CharacterClasses::SCHEME
            )
          end
        else
          nil
        end
      end)
    end

    ##
    # Sets the scheme component for this URI.
    #
    # @param [String, #to_str] new_scheme The new scheme component.
    def scheme=(new_scheme)
      @scheme = new_scheme ? new_scheme.to_str : nil
      @scheme = nil if @scheme.to_s.strip == ""

      # Reset dependant values
      @normalized_scheme = nil
    end

    ##
    # The user component for this URI.
    #
    # @return [String] The user component.
    def user
      return @user
    end

    ##
    # The user component for this URI, normalized.
    #
    # @return [String] The user component, normalized.
    def normalized_user
      @normalized_user ||= (begin
        if self.user
          if normalized_scheme =~ /https?/ && self.user.strip == "" &&
              (!self.password || self.password.strip == "")
            nil
          else
            Addressable::URI.encode_component(
              Addressable::IDNA.unicode_normalize_kc(
                Addressable::URI.unencode_component(self.user.strip)),
              Addressable::URI::CharacterClasses::UNRESERVED
            )
          end
        else
          nil
        end
      end)
    end

    ##
    # Sets the user component for this URI.
    #
    # @param [String, #to_str] new_user The new user component.
    def user=(new_user)
      @user = new_user ? new_user.to_str : nil

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

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

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

    ##
    # The password component for this URI.
    #
    # @return [String] The password component.
    def password
      return @password
    end

    ##
    # The password component for this URI, normalized.
    #
    # @return [String] The password component, normalized.
    def normalized_password
      @normalized_password ||= (begin
        if self.password
          if normalized_scheme =~ /https?/ && self.password.strip == "" &&
              (!self.user || self.user.strip == "")
            nil
          else
            Addressable::URI.encode_component(
              Addressable::IDNA.unicode_normalize_kc(
                Addressable::URI.unencode_component(self.password.strip)),
              Addressable::URI::CharacterClasses::UNRESERVED
            )
          end
        else
          nil
        end
      end)
    end

    ##
    # Sets the password component for this URI.
    #
    # @param [String, #to_str] new_password The new password component.
    def password=(new_password)
      @password = new_password ? new_password.to_str : nil

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

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

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

    ##
    # The userinfo component for this URI.
    # Combines the user and password components.
    #
    # @return [String] The userinfo component.
    def userinfo
      @userinfo ||= (begin
        current_user = self.user
     …