Addressable C0 Coverage Information - RCov

lib/addressable/uri.rb

Name Total Lines Lines of Code Total Coverage Code Coverage
lib/addressable/uri.rb 2273 1372
99.87%
99.78%

Key

Code reported as executed by Ruby looks like this...and this: this line is also marked as covered.Lines considered as run by rcov, but not reported by Ruby, look like this,and this: these lines were inferred by rcov (using simple heuristics).Finally, here's a line marked as not executed.

Coverage Details

1 # encoding:utf-8
2 #--
3 # Copyright (C) 2006-2011 Bob Aman
4 #
5 #    Licensed under the Apache License, Version 2.0 (the "License");
6 #    you may not use this file except in compliance with the License.
7 #    You may obtain a copy of the License at
8 #
9 #        http://www.apache.org/licenses/LICENSE-2.0
10 #
11 #    Unless required by applicable law or agreed to in writing, software
12 #    distributed under the License is distributed on an "AS IS" BASIS,
13 #    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 #    See the License for the specific language governing permissions and
15 #    limitations under the License.
16 #++
17 
18 
19 require "addressable/version"
20 require "addressable/idna"
21 
22 ##
23 # Addressable is a library for processing links and URIs.
24 module Addressable
25   ##
26   # This is an implementation of a URI parser based on
27   # <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>,
28   # <a href="http://www.ietf.org/rfc/rfc3987.txt">RFC 3987</a>.
29   class URI
30     ##
31     # Raised if something other than a uri is supplied.
32     class InvalidURIError < StandardError
33     end
34 
35     ##
36     # Container for the character classes specified in
37     # <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>.
38     module CharacterClasses
39       ALPHA = "a-zA-Z"
40       DIGIT = "0-9"
41       GEN_DELIMS = "\\:\\/\\?\\#\\[\\]\\@"
42       SUB_DELIMS = "\\!\\$\\&\\'\\(\\)\\*\\+\\,\\;\\="
43       RESERVED = GEN_DELIMS + SUB_DELIMS
44       UNRESERVED = ALPHA + DIGIT + "\\-\\.\\_\\~"
45       PCHAR = UNRESERVED + SUB_DELIMS + "\\:\\@"
46       SCHEME = ALPHA + DIGIT + "\\-\\+\\."
47       AUTHORITY = PCHAR
48       PATH = PCHAR + "\\/"
49       QUERY = PCHAR + "\\/\\?"
50       FRAGMENT = PCHAR + "\\/\\?"
51     end
52 
53     SLASH = '/'
54     EMPTYSTR = ''
55 
56     URIREGEX = /^(([^:\/?#]+):)?(\/\/([^\/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?$/
57 
58     PORT_MAPPING = {
59       "http" => 80,
60       "https" => 443,
61       "ftp" => 21,
62       "tftp" => 69,
63       "sftp" => 22,
64       "ssh" => 22,
65       "svn+ssh" => 22,
66       "telnet" => 23,
67       "nntp" => 119,
68       "gopher" => 70,
69       "wais" => 210,
70       "ldap" => 389,
71       "prospero" => 1525
72     }
73 
74     ##
75     # Returns a URI object based on the parsed string.
76     #
77     # @param [String, Addressable::URI, #to_str] uri
78     #   The URI string to parse.
79     #   No parsing is performed if the object is already an
80     #   <code>Addressable::URI</code>.
81     #
82     # @return [Addressable::URI] The parsed URI.
83     def self.parse(uri)
84       # If we were given nil, return nil.
85       return nil unless uri
86       # If a URI object is passed, just return itself.
87       return uri.dup if uri.kind_of?(self)
88 
89       # If a URI object of the Ruby standard library variety is passed,
90       # convert it to a string, then parse the string.
91       # We do the check this way because we don't want to accidentally
92       # cause a missing constant exception to be thrown.
93       if uri.class.name =~ /^URI\b/
94         uri = uri.to_s
95       end
96 
97       # Otherwise, convert to a String
98       begin
99         uri = uri.to_str
100       rescue TypeError, NoMethodError
101         raise TypeError, "Can't convert #{uri.class} into String."
102       end if not uri.is_a? String
103 
104       # This Regexp supplied as an example in RFC 3986, and it works great.
105       scan = uri.scan(URIREGEX)
106       fragments = scan[0]
107       scheme = fragments[1]
108       authority = fragments[3]
109       path = fragments[4]
110       query = fragments[6]
111       fragment = fragments[8]
112       user = nil
113       password = nil
114       host = nil
115       port = nil
116       if authority != nil
117         # The Regexp above doesn't split apart the authority.
118         userinfo = authority[/^([^\[\]]*)@/, 1]
119         if userinfo != nil
120           user = userinfo.strip[/^([^:]*):?/, 1]
121           password = userinfo.strip[/:(.*)$/, 1]
122         end
123         host = authority.gsub(/^([^\[\]]*)@/, EMPTYSTR).gsub(/:([^:@\[\]]*?)$/, EMPTYSTR)
124         port = authority[/:([^:@\[\]]*?)$/, 1]
125       end
126       if port == EMPTYSTR
127         port = nil
128       end
129 
130       return new(
131         :scheme => scheme,
132         :user => user,
133         :password => password,
134         :host => host,
135         :port => port,
136         :path => path,
137         :query => query,
138         :fragment => fragment
139       )
140     end
141 
142     ##
143     # Converts an input to a URI. The input does not have to be a valid
144     # URI — the method will use heuristics to guess what URI was intended.
145     # This is not standards-compliant, merely user-friendly.
146     #
147     # @param [String, Addressable::URI, #to_str] uri
148     #   The URI string to parse.
149     #   No parsing is performed if the object is already an
150     #   <code>Addressable::URI</code>.
151     # @param [Hash] hints
152     #   A <code>Hash</code> of hints to the heuristic parser.
153     #   Defaults to <code>{:scheme => "http"}</code>.
154     #
155     # @return [Addressable::URI] The parsed URI.
156     def self.heuristic_parse(uri, hints={})
157       # If we were given nil, return nil.
158       return nil unless uri
159       # If a URI object is passed, just return itself.
160       return uri.dup if uri.kind_of?(self)
161       if !uri.respond_to?(:to_str)
162         raise TypeError, "Can't convert #{uri.class} into String."
163       end
164       # Otherwise, convert to a String
165       uri = uri.to_str.dup
166       hints = {
167         :scheme => "http"
168       }.merge(hints)
169       case uri
170       when /^http:\/+/
171         uri.gsub!(/^http:\/+/, "http://")
172       when /^https:\/+/
173         uri.gsub!(/^https:\/+/, "https://")
174       when /^feed:\/+http:\/+/
175         uri.gsub!(/^feed:\/+http:\/+/, "feed:http://")
176       when /^feed:\/+/
177         uri.gsub!(/^feed:\/+/, "feed://")
178       when /^file:\/+/
179         uri.gsub!(/^file:\/+/, "file:///")
180       end
181       parsed = self.parse(uri)
182       if parsed.scheme =~ /^[^\/?#\.]+\.[^\/?#]+$/
183         parsed = self.parse(hints[:scheme] + "://" + uri)
184       end
185       if parsed.path.include?(".")
186         new_host = parsed.path[/^([^\/]+\.[^\/]*)/, 1]
187         if new_host
188           parsed.defer_validation do
189             new_path = parsed.path.gsub(
190               Regexp.new("^" + Regexp.escape(new_host)), EMPTYSTR)
191             parsed.host = new_host
192             parsed.path = new_path
193             parsed.scheme = hints[:scheme] unless parsed.scheme
194           end
195         end
196       end
197       return parsed
198     end
199 
200     ##
201     # Converts a path to a file scheme URI. If the path supplied is
202     # relative, it will be returned as a relative URI. If the path supplied
203     # is actually a non-file URI, it will parse the URI as if it had been
204     # parsed with <code>Addressable::URI.parse</code>. Handles all of the
205     # various Microsoft-specific formats for specifying paths.
206     #
207     # @param [String, Addressable::URI, #to_str] path
208     #   Typically a <code>String</code> path to a file or directory, but
209     #   will return a sensible return value if an absolute URI is supplied
210     #   instead.
211     #
212     # @return [Addressable::URI]
213     #   The parsed file scheme URI or the original URI if some other URI
214     #   scheme was provided.
215     #
216     # @example
217     #   base = Addressable::URI.convert_path("/absolute/path/")
218     #   uri = Addressable::URI.convert_path("relative/path")
219     #   (base + uri).to_s
220     #   #=> "file:///absolute/path/relative/path"
221     #
222     #   Addressable::URI.convert_path(
223     #     "c:\\windows\\My Documents 100%20\\foo.txt"
224     #   ).to_s
225     #   #=> "file:///c:/windows/My%20Documents%20100%20/foo.txt"
226     #
227     #   Addressable::URI.convert_path("http://example.com/").to_s
228     #   #=> "http://example.com/"
229     def self.convert_path(path)
230       # If we were given nil, return nil.
231       return nil unless path
232       # If a URI object is passed, just return itself.
233       return path if path.kind_of?(self)
234       if !path.respond_to?(:to_str)
235         raise TypeError, "Can't convert #{path.class} into String."
236       end
237       # Otherwise, convert to a String
238       path = path.to_str.strip
239 
240       path.gsub!(/^file:\/?\/?/, EMPTYSTR) if path =~ /^file:\/?\/?/
241       path = SLASH + path if path =~ /^([a-zA-Z])[\|:]/
242       uri = self.parse(path)
243 
244       if uri.scheme == nil
245         # Adjust windows-style uris
246         uri.path.gsub!(/^\/?([a-zA-Z])[\|:][\\\/]/) do
247           "/#{$1.downcase}:/"
248         end
249         uri.path.gsub!(/\\/, SLASH)
250         if File.exists?(uri.path) &&
251             File.stat(uri.path).directory?
252           uri.path.gsub!(/\/$/, EMPTYSTR)
253           uri.path = uri.path + '/'
254         end
255 
256         # If the path is absolute, set the scheme and host.
257         if uri.path =~ /^\//
258           uri.scheme = "file"
259           uri.host = EMPTYSTR
260         end
261         uri.normalize!
262       end
263 
264       return uri
265     end
266 
267     ##
268     # Joins several URIs together.
269     #
270     # @param [String, Addressable::URI, #to_str] *uris
271     #   The URIs to join.
272     #
273     # @return [Addressable::URI] The joined URI.
274     #
275     # @example
276     #   base = "http://example.com/"
277     #   uri = Addressable::URI.parse("relative/path")
278     #   Addressable::URI.join(base, uri)
279     #   #=> #<Addressable::URI:0xcab390 URI:http://example.com/relative/path>
280     def self.join(*uris)
281       uri_objects = uris.collect do |uri|
282         if !uri.respond_to?(:to_str)
283           raise TypeError, "Can't convert #{uri.class} into String."
284         end
285         uri.kind_of?(self) ? uri : self.parse(uri.to_str)
286       end
287       result = uri_objects.shift.dup
288       for uri in uri_objects
289         result.join!(uri)
290       end
291       return result
292     end
293 
294     ##
295     # Percent encodes a URI component.
296     #
297     # @param [String, #to_str] component The URI component to encode.
298     #
299     # @param [String, Regexp] character_class
300     #   The characters which are not percent encoded. If a <code>String</code>
301     #   is passed, the <code>String</code> must be formatted as a regular
302     #   expression character class. (Do not include the surrounding square
303     #   brackets.)  For example, <code>"b-zB-Z0-9"</code> would cause
304     #   everything but the letters 'b' through 'z' and the numbers '0' through
305     #  '9' to be percent encoded. If a <code>Regexp</code> is passed, the
306     #   value <code>/[^b-zB-Z0-9]/</code> would have the same effect. A set of
307     #   useful <code>String</code> values may be found in the
308     #   <code>Addressable::URI::CharacterClasses</code> module. The default
309     #   value is the reserved plus unreserved character classes specified in
310     #   <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>.
311     #
312     # @return [String] The encoded component.
313     #
314     # @example
315     #   Addressable::URI.encode_component("simple/example", "b-zB-Z0-9")
316     #   => "simple%2Fex%61mple"
317     #   Addressable::URI.encode_component("simple/example", /[^b-zB-Z0-9]/)
318     #   => "simple%2Fex%61mple"
319     #   Addressable::URI.encode_component(
320     #     "simple/example", Addressable::URI::CharacterClasses::UNRESERVED
321     #   )
322     #   => "simple%2Fexample"
323     def self.encode_component(component, character_class=
324         CharacterClasses::RESERVED + CharacterClasses::UNRESERVED)
325       return nil if component.nil?
326 
327       begin
328         if component.kind_of?(Symbol) || component.kind_of?(Numeric)
329           component = component.to_s
330         else
331           component = component.to_str
332         end
333       rescue TypeError, NoMethodError
334         raise TypeError, "Can't convert #{component.class} into String."
335       end if !component.is_a? String
336 
337       if ![String, Regexp].include?(character_class.class)
338         raise TypeError,
339           "Expected String or Regexp, got #{character_class.inspect}"
340       end
341       if character_class.kind_of?(String)
342         character_class = /[^#{character_class}]/
343       end
344       if component.respond_to?(:force_encoding)
345         # We can't perform regexps on invalid UTF sequences, but
346         # here we need to, so switch to ASCII.
347         component = component.dup
348         component.force_encoding(Encoding::ASCII_8BIT)
349       end
350       return component.gsub(character_class) do |sequence|
351         (sequence.unpack('C*').map { |c| "%" + ("%02x" % c).upcase }).join
352       end
353     end
354 
355     class << self
356       alias_method :encode_component, :encode_component
357     end
358 
359     ##
360     # Unencodes any percent encoded characters within a URI component.
361     # This method may be used for unencoding either components or full URIs,
362     # however, it is recommended to use the <code>unencode_component</code>
363     # alias when unencoding components.
364     #
365     # @param [String, Addressable::URI, #to_str] uri
366     #   The URI or component to unencode.
367     #
368     # @param [Class] returning
369     #   The type of object to return.
370     #   This value may only be set to <code>String</code> or
371     #   <code>Addressable::URI</code>. All other values are invalid. Defaults
372     #   to <code>String</code>.
373     #
374     # @return [String, Addressable::URI]
375     #   The unencoded component or URI.
376     #   The return type is determined by the <code>returning</code> parameter.
377     def self.unencode(uri, returning=String)
378       return nil if uri.nil?
379 
380       begin
381         uri = uri.to_str
382       rescue NoMethodError, TypeError
383         raise TypeError, "Can't convert #{uri.class} into String."
384       end if !uri.is_a? String
385       if ![String, ::Addressable::URI].include?(returning)
386         raise TypeError,
387           "Expected Class (String or Addressable::URI), " +
388           "got #{returning.inspect}"
389       end
390       result = uri.gsub(/%[0-9a-f]{2}/i) do |sequence|
391         sequence[1..3].to_i(16).chr
392       end
393       result.force_encoding("utf-8") if result.respond_to?(:force_encoding)
394       if returning == String
395         return result
396       elsif returning == ::Addressable::URI
397         return ::Addressable::URI.parse(result)
398       end
399     end
400 
401     class << self
402       alias_method :unescape, :unencode
403       alias_method :unencode_component, :unencode
404       alias_method :unescape_component, :unencode
405     end
406 
407 
408     ##
409     # Normalizes the encoding of a URI component.
410     #
411     # @param [String, #to_str] component The URI component to encode.
412     #
413     # @param [String, Regexp] character_class
414     #   The characters which are not percent encoded. If a <code>String</code>
415     #   is passed, the <code>String</code> must be formatted as a regular
416     #   expression character class. (Do not include the surrounding square
417     #   brackets.)  For example, <code>"b-zB-Z0-9"</code> would cause
418     #   everything but the letters 'b' through 'z' and the numbers '0'
419     #   through '9' to be percent encoded. If a <code>Regexp</code> is passed,
420     #   the value <code>/[^b-zB-Z0-9]/</code> would have the same effect. A
421     #   set of useful <code>String</code> values may be found in the
422     #   <code>Addressable::URI::CharacterClasses</code> module. The default
423     #   value is the reserved plus unreserved character classes specified in
424     #   <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>.
425     #
426     # @return [String] The normalized component.
427     #
428     # @example
429     #   Addressable::URI.normalize_component("simpl%65/%65xampl%65", "b-zB-Z")
430     #   => "simple%2Fex%61mple"
431     #   Addressable::URI.normalize_component(
432     #     "simpl%65/%65xampl%65", /[^b-zB-Z]/
433     #   )
434     #   => "simple%2Fex%61mple"
435     #   Addressable::URI.normalize_component(
436     #     "simpl%65/%65xampl%65",
437     #     Addressable::URI::CharacterClasses::UNRESERVED
438     #   )
439     #   => "simple%2Fexample"
440     def self.normalize_component(component, character_class=
441         CharacterClasses::RESERVED + CharacterClasses::UNRESERVED)
442       return nil if component.nil?
443 
444       begin
445         component = component.to_str
446       rescue NoMethodError, TypeError
447         raise TypeError, "Can't convert #{component.class} into String."
448       end if !component.is_a? String
449 
450       if ![String, Regexp].include?(character_class.class)
451         raise TypeError,
452           "Expected String or Regexp, got #{character_class.inspect}"
453       end
454       if character_class.kind_of?(String)
455         character_class = /[^#{character_class}]/
456       end
457       if component.respond_to?(:force_encoding)
458         # We can't perform regexps on invalid UTF sequences, but
459         # here we need to, so switch to ASCII.
460         component = component.dup
461         component.force_encoding(Encoding::ASCII_8BIT)
462       end
463       unencoded = self.unencode_component(component)
464       begin
465         encoded = self.encode_component(
466           Addressable::IDNA.unicode_normalize_kc(unencoded),
467           character_class
468         )
469       rescue ArgumentError
470         encoded = self.encode_component(unencoded)
471       end
472       return encoded
473     end
474 
475     ##
476     # Percent encodes any special characters in the URI.
477     #
478     # @param [String, Addressable::URI, #to_str] uri
479     #   The URI to encode.
480     #
481     # @param [Class] returning
482     #   The type of object to return.
483     #   This value may only be set to <code>String</code> or
484     #   <code>Addressable::URI</code>. All other values are invalid. Defaults
485     #   to <code>String</code>.
486     #
487     # @return [String, Addressable::URI]
488     #   The encoded URI.
489     #   The return type is determined by the <code>returning</code> parameter.
490     def self.encode(uri, returning=String)
491       return nil if uri.nil?
492 
493       begin
494         uri = uri.to_str
495       rescue NoMethodError, TypeError
496         raise TypeError, "Can't convert #{uri.class} into String."
497       end if !uri.is_a? String
498 
499       if ![String, ::Addressable::URI].include?(returning)
500         raise TypeError,
501           "Expected Class (String or Addressable::URI), " +
502           "got #{returning.inspect}"
503       end
504       uri_object = uri.kind_of?(self) ? uri : self.parse(uri)
505       encoded_uri = Addressable::URI.new(
506         :scheme => self.encode_component(uri_object.scheme,
507           Addressable::URI::CharacterClasses::SCHEME),
508         :authority => self.encode_component(uri_object.authority,
509           Addressable::URI::CharacterClasses::AUTHORITY),
510         :path => self.encode_component(uri_object.path,
511           Addressable::URI::CharacterClasses::PATH),
512         :query => self.encode_component(uri_object.query,
513           Addressable::URI::CharacterClasses::QUERY),
514         :fragment => self.encode_component(uri_object.fragment,
515           Addressable::URI::CharacterClasses::FRAGMENT)
516       )
517       if returning == String
518         return encoded_uri.to_s
519       elsif returning == ::Addressable::URI
520         return encoded_uri
521       end
522     end
523 
524     class << self
525       alias_method :escape, :encode
526     end
527 
528     ##
529     # Normalizes the encoding of a URI. Characters within a hostname are
530     # not percent encoded to allow for internationalized domain names.
531     #
532     # @param [String, Addressable::URI, #to_str] uri
533     #   The URI to encode.
534     #
535     # @param [Class] returning
536     #   The type of object to return.
537     #   This value may only be set to <code>String</code> or
538     #   <code>Addressable::URI</code>. All other values are invalid. Defaults
539     #   to <code>String</code>.
540     #
541     # @return [String, Addressable::URI]
542     #   The encoded URI.
543     #   The return type is determined by the <code>returning</code> parameter.
544     def self.normalized_encode(uri, returning=String)
545       begin
546         uri = uri.to_str
547       rescue NoMethodError, TypeError
548         raise TypeError, "Can't convert #{uri.class} into String."
549       end if !uri.is_a? String
550 
551       if ![String, ::Addressable::URI].include?(returning)
552         raise TypeError,
553           "Expected Class (String or Addressable::URI), " +
554           "got #{returning.inspect}"
555       end
556       uri_object = uri.kind_of?(self) ? uri : self.parse(uri)
557       components = {
558         :scheme => self.unencode_component(uri_object.scheme),
559         :user => self.unencode_component(uri_object.user),
560         :password => self.unencode_component(uri_object.password),
561         :host => self.unencode_component(uri_object.host),
562         :port => uri_object.port,
563         :path => self.unencode_component(uri_object.path),
564         :query => self.unencode_component(uri_object.query),
565         :fragment => self.unencode_component(uri_object.fragment)
566       }
567       components.each do |key, value|
568         if value != nil
569           begin
570             components[key] =
571               Addressable::IDNA.unicode_normalize_kc(value.to_str)
572           rescue ArgumentError
573             # Likely a malformed UTF-8 character, skip unicode normalization
574             components[key] = value.to_str
575           end
576         end
577       end
578       encoded_uri = Addressable::URI.new(
579         :scheme => self.encode_component(components[:scheme],
580           Addressable::URI::CharacterClasses::SCHEME),
581         :user => self.encode_component(components[:user],
582           Addressable::URI::CharacterClasses::UNRESERVED),
583         :password => self.encode_component(components[:password],
584           Addressable::URI::CharacterClasses::UNRESERVED),
585         :host => components[:host],
586         :port => components[:port],
587         :path => self.encode_component(components[:path],
588           Addressable::URI::CharacterClasses::PATH),
589         :query => self.encode_component(components[:query],
590           Addressable::URI::CharacterClasses::QUERY),
591         :fragment => self.encode_component(components[:fragment],
592           Addressable::URI::CharacterClasses::FRAGMENT)
593       )
594       if returning == String
595         return encoded_uri.to_s
596       elsif returning == ::Addressable::URI
597         return encoded_uri
598       end
599     end
600 
601     ##
602     # Encodes a set of key/value pairs according to the rules for the
603     # <code>application/x-www-form-urlencoded</code> MIME type.
604     #
605     # @param [#to_hash, #to_ary] form_values
606     #   The form values to encode.
607     #
608     # @param [TrueClass, FalseClass] sort
609     #   Sort the key/value pairs prior to encoding.
610     #   Defaults to <code>false</code>.
611     #
612     # @return [String]
613     #   The encoded value.
614     def self.form_encode(form_values, sort=false)
615       if form_values.respond_to?(:to_hash)
616         form_values = form_values.to_hash.to_a
617       elsif form_values.respond_to?(:to_ary)
618         form_values = form_values.to_ary
619       else
620         raise TypeError, "Can't convert #{form_values.class} into Array."
621       end
622       form_values = form_values.map do |(key, value)|
623         [key.to_s, value.to_s]
624       end
625       if sort
626         # Useful for OAuth and optimizing caching systems
627         form_values = form_values.sort
628       end
629       escaped_form_values = form_values.map do |(key, value)|
630         # Line breaks are CRLF pairs
631         [
632           self.encode_component(
633             key.gsub(/(\r\n|\n|\r)/, "\r\n"),
634             CharacterClasses::UNRESERVED
635           ).gsub("%20", "+"),
636           self.encode_component(
637             value.gsub(/(\r\n|\n|\r)/, "\r\n"),
638             CharacterClasses::UNRESERVED
639           ).gsub("%20", "+")
640         ]
641       end
642       return (escaped_form_values.map do |(key, value)|
643         "#{key}=#{value}"
644       end).join("&")
645     end
646 
647     ##
648     # Decodes a <code>String</code> according to the rules for the
649     # <code>application/x-www-form-urlencoded</code> MIME type.
650     #
651     # @param [String, #to_str] encoded_value
652     #   The form values to decode.
653     #
654     # @return [Array]
655     #   The decoded values.
656     #   This is not a <code>Hash</code> because of the possibility for
657     #   duplicate keys.
658     def self.form_unencode(encoded_value)
659       if !encoded_value.respond_to?(:to_str)
660         raise TypeError, "Can't convert #{encoded_value.class} into String."
661       end
662       encoded_value = encoded_value.to_str
663       split_values = encoded_value.split("&").map do |pair|
664         pair.split("=", 2)
665       end
666       return split_values.map do |(key, value)|
667         [
668           key ? self.unencode_component(
669             key.gsub("+", "%20")).gsub(/(\r\n|\n|\r)/, "\n") : nil,
670           value ? (self.unencode_component(
671             value.gsub("+", "%20")).gsub(/(\r\n|\n|\r)/, "\n")) : nil
672         ]
673       end
674     end
675 
676     ##
677     # Creates a new uri object from component parts.
678     #
679     # @option [String, #to_str] scheme The scheme component.
680     # @option [String, #to_str] user The user component.
681     # @option [String, #to_str] password The password component.
682     # @option [String, #to_str] userinfo
683     #   The userinfo component. If this is supplied, the user and password
684     #   components must be omitted.
685     # @option [String, #to_str] host The host component.
686     # @option [String, #to_str] port The port component.
687     # @option [String, #to_str] authority
688     #   The authority component. If this is supplied, the user, password,
689     #   userinfo, host, and port components must be omitted.
690     # @option [String, #to_str] path The path component.
691     # @option [String, #to_str] query The query component.
692     # @option [String, #to_str] fragment The fragment component.
693     #
694     # @return [Addressable::URI] The constructed URI object.
695     def initialize(options={})
696       if options.has_key?(:authority)
697         if (options.keys & [:userinfo, :user, :password, :host, :port]).any?
698           raise ArgumentError,
699             "Cannot specify both an authority and any of the components " +
700             "within the authority."
701         end
702       end
703       if options.has_key?(:userinfo)
704         if (options.keys & [:user, :password]).any?
705           raise ArgumentError,
706             "Cannot specify both a userinfo and either the user or password."
707         end
708       end
709 
710       self.defer_validation do
711         # Bunch of crazy logic required because of the composite components
712         # like userinfo and authority.
713         self.scheme = options[:scheme] if options[:scheme]
714         self.user = options[:user] if options[:user]
715         self.password = options[:password] if options[:password]
716         self.userinfo = options[:userinfo] if options[:userinfo]
717         self.host = options[:host] if options[:host]
718         self.port = options[:port] if options[:port]
719         self.authority = options[:authority] if options[:authority]
720         self.path = options[:path] if options[:path]
721         self.query = options[:query] if options[:query]
722         self.query_values = options[:query_values] if options[:query_values]
723         self.fragment = options[:fragment] if options[:fragment]
724       end
725     end
726 
727     ##
728     # Freeze URI, initializing instance variables.
729     #
730     # @return [Addressable::URI] The frozen URI object.
731     def freeze
732       self.normalized_scheme
733       self.normalized_user
734       self.normalized_password
735       self.normalized_userinfo
736       self.normalized_host
737       self.normalized_port
738       self.normalized_authority
739       self.normalized_site
740       self.normalized_path
741       self.normalized_query
742       self.normalized_fragment
743       self.hash
744       super
745     end
746 
747     ##
748     # The scheme component for this URI.
749     #
750     # @return [String] The scheme component.
751     def scheme
752       return instance_variable_defined?(:@scheme) ? @scheme : nil
753     end
754 
755     ##
756     # The scheme component for this URI, normalized.
757     #
758     # @return [String] The scheme component, normalized.
759     def normalized_scheme
760       self.scheme && @normalized_scheme ||= (begin
761         if self.scheme =~ /^\s*ssh\+svn\s*$/i
762           "svn+ssh"
763         else
764           Addressable::URI.normalize_component(
765             self.scheme.strip.downcase,
766             Addressable::URI::CharacterClasses::SCHEME
767           )
768         end
769       end)
770     end
771 
772     ##
773     # Sets the scheme component for this URI.
774     #
775     # @param [String, #to_str] new_scheme The new scheme component.
776     def scheme=(new_scheme)
777       if new_scheme && !new_scheme.respond_to?(:to_str)
778         raise TypeError, "Can't convert #{new_scheme.class} into String."
779       elsif new_scheme
780         new_scheme = new_scheme.to_str
781       end
782       if new_scheme && new_scheme !~ /[a-z][a-z0-9\.\+\-]*/i
783         raise InvalidURIError, "Invalid scheme format."
784       end
785       @scheme = new_scheme
786       @scheme = nil if @scheme.to_s.strip.empty?
787 
788       # Reset dependant values
789       @normalized_scheme = nil
790       @uri_string = nil
791       @hash = nil
792 
793       # Ensure we haven't created an invalid URI
794       validate()
795     end
796 
797     ##
798     # The user component for this URI.
799     #
800     # @return [String] The user component.
801     def user
802       return instance_variable_defined?(:@user) ? @user : nil
803     end
804 
805     ##
806     # The user component for this URI, normalized.
807     #
808     # @return [String] The user component, normalized.
809     def normalized_user
810       self.user && @normalized_user ||= (begin
811         if normalized_scheme =~ /https?/ && self.user.strip.empty? &&
812             (!self.password || self.password.strip.empty?)
813           nil
814         else
815           Addressable::URI.normalize_component(
816             self.user.strip,
817             Addressable::URI::CharacterClasses::UNRESERVED
818           )
819         end
820       end)
821     end
822 
823     ##
824     # Sets the user component for this URI.
825     #
826     # @param [String, #to_str] new_user The new user component.
827     def user=(new_user)
828       if new_user && !new_user.respond_to?(:to_str)
829         raise TypeError, "Can't convert #{new_user.class} into String."
830       end
831       @user = new_user ? new_user.to_str : nil
832 
833       # You can't have a nil user with a non-nil password
834       if password != nil
835         @user = EMPTYSTR if @user.nil?
836       end
837 
838       # Reset dependant values
839       @userinfo = nil
840       @normalized_userinfo = nil
841       @authority = nil
842       @normalized_user = nil
843       @uri_string = nil
844       @hash = nil
845 
846       # Ensure we haven't created an invalid URI
847       validate()
848     end
849 
850     ##
851     # The password component for this URI.
852     #
853     # @return [String] The password component.
854     def password
855       return instance_variable_defined?(:@password) ? @password : nil
856     end
857 
858     ##
859     # The password component for this URI, normalized.
860     #
861     # @return [String] The password component, normalized.
862     def normalized_password
863       self.password && @normalized_password ||= (begin
864         if self.normalized_scheme =~ /https?/ && self.password.strip.empty? &&
865             (!self.user || self.user.strip.empty?)
866           nil
867         else
868           Addressable::URI.normalize_component(
869             self.password.strip,
870             Addressable::URI::CharacterClasses::UNRESERVED
871           )
872         end
873       end)
874     end
875 
876     ##
877     # Sets the password component for this URI.
878     #
879     # @param [String, #to_str] new_password The new password component.
880     def password=(new_password)
881       if new_password && !new_password.respond_to?(:to_str)
882         raise TypeError, "Can't convert #{new_password.class} into String."
883       end
884       @password = new_password ? new_password.to_str : nil
885 
886       # You can't have a nil user with a non-nil password
887       @password ||= nil
888       @user ||= nil
889       if @password != nil
890         @user = EMPTYSTR if @user.nil?
891       end
892 
893       # Reset dependant values
894       @userinfo = nil
895       @normalized_userinfo = nil
896       @authority = nil
897       @normalized_password = nil
898       @uri_string = nil
899       @hash = nil
900 
901       # Ensure we haven't created an invalid URI
902       validate()
903     end
904 
905     ##
906     # The userinfo component for this URI.
907     # Combines the user and password components.
908     #
909     # @return [String] The userinfo component.
910     def userinfo
911       current_user = self.user
912       current_password = self.password
913       (current_user || current_password) && @userinfo ||= (begin
914         if current_user && current_password
915           "#{current_user}:#{current_password}"
916         elsif current_user && !current_password
917           "#{current_user}"
918         end
919       end)
920     end
921 
922     ##
923     # The userinfo component for this URI, normalized.
924     #
925     # @return [String] The userinfo component, normalized.
926     def normalized_userinfo
927       self.userinfo && @normalized_userinfo ||= (begin
928         current_user = self.normalized_user
929         current_password = self.normalized_password
930         if !current_user && !current_password
931           nil
932         elsif current_user && current_password
933           "#{current_user}:#{current_password}"
934         elsif current_user && !current_password
935           "#{current_user}"
936         end
937       end)
938     end
939 
940     ##
941     # Sets the userinfo component for this URI.
942     #
943     # @param [String, #to_str] new_userinfo The new userinfo component.
944     def userinfo=(new_userinfo)
945       if new_userinfo && !new_userinfo.respond_to?(:to_str)
946         raise TypeError, "Can't convert #{new_userinfo.class} into String."
947       end
948       new_user, new_password = if new_userinfo
949         [
950           new_userinfo.to_str.strip[/^(.*):/, 1],
951           new_userinfo.to_str.strip[/:(.*)$/, 1]
952         ]
953       else
954         [nil, nil]
955       end
956 
957       # Password assigned first to ensure validity in case of nil
958       self.password = new_password
959       self.user = new_user
960 
961       # Reset dependant values
962       @authority = nil
963       @uri_string = nil
964       @hash = nil
965 
966       # Ensure we haven't created an invalid URI
967       validate()
968     end
969 
970     ##
971     # The host component for this URI.
972     #
973     # @return [String] The host component.
974     def host
975       return instance_variable_defined?(:@host) ? @host : nil
976     end
977 
978     ##
979     # The host component for this URI, normalized.
980     #
981     # @return [String] The host component, normalized.
982     def normalized_host
983       self.host && @normalized_host ||= (begin
984         if self.host != nil
985           if !self.host.strip.empty?
986             result = ::Addressable::IDNA.to_ascii(
987               URI.unencode_component(self.host.strip.downcase)
988             )
989             if result[-1..-1] == "."
990               # Trailing dots are unnecessary
991               result = result[0...-1]
992             end
993             result
994           else
995             EMPTYSTR
996           end
997         else
998           nil
999         end
1000       end)
1001     end
1002 
1003     ##
1004     # Sets the host component for this URI.
1005     #
1006     # @param [String, #to_str] new_host The new host component.
1007     def host=(new_host)
1008       if new_host && !new_host.respond_to?(:to_str)
1009         raise TypeError, "Can't convert #{new_host.class} into String."
1010       end
1011       @host = new_host ? new_host.to_str : nil
1012 
1013       # Reset dependant values
1014       @authority = nil
1015       @normalized_host = nil
1016       @uri_string = nil
1017       @hash = nil
1018 
1019       # Ensure we haven't created an invalid URI
1020       validate()
1021     end
1022 
1023     ##
1024     # @see Addressable::URI#host
1025     alias_method :hostname, :host
1026 
1027     ##
1028     # @see Addressable::URI#host=
1029     alias_method :hostname=, :host=
1030 
1031     ##
1032     # The authority component for this URI.
1033     # Combines the user, password, host, and port components.
1034     #
1035     # @return [String] The authority component.
1036     def authority
1037       self.host && @authority ||= (begin
1038         authority = ""
1039         if self.userinfo != nil
1040           authority << "#{self.userinfo}@"
1041         end
1042         authority << self.host
1043         if self.port != nil
1044           authority << ":#{self.port}"
1045         end
1046         authority
1047       end)
1048     end
1049 
1050     ##
1051     # The authority component for this URI, normalized.
1052     #
1053     # @return [String] The authority component, normalized.
1054     def normalized_authority
1055       self.authority && @normalized_authority ||= (begin
1056         authority = ""
1057         if self.normalized_userinfo != nil
1058           authority << "#{self.normalized_userinfo}@"
1059         end
1060         authority << self.normalized_host
1061         if self.normalized_port != nil
1062           authority << ":#{self.normalized_port}"
1063         end
1064         authority
1065       end)
1066     end
1067 
1068     ##
1069     # Sets the authority component for this URI.
1070     #
1071     # @param [String, #to_str] new_authority The new authority component.
1072     def authority=(new_authority)
1073       if new_authority
1074         if !new_authority.respond_to?(:to_str)
1075           raise TypeError, "Can't convert #{new_authority.class} into String."
1076         end
1077         new_authority = new_authority.to_str
1078         new_userinfo = new_authority[/^([^\[\]]*)@/, 1]
1079         if new_userinfo
1080           new_user = new_userinfo.strip[/^([^:]*):?/, 1]
1081           new_password = new_userinfo.strip[/:(.*)$/, 1]
1082         end
1083         new_host =
1084           new_authority.gsub(/^([^\[\]]*)@/, EMPTYSTR).gsub(/:([^:@\[\]]*?)$/, EMPTYSTR)
1085         new_port =
1086           new_authority[/:([^:@\[\]]*?)$/, 1]
1087       end
1088 
1089       # Password assigned first to ensure validity in case of nil
1090       self.password = defined?(new_password) ? new_password : nil
1091       self.user = defined?(new_user) ? new_user : nil
1092       self.host = defined?(new_host) ? new_host : nil
1093       self.port = defined?(new_port) ? new_port : nil
1094 
1095       # Reset dependant values
1096       @userinfo = nil
1097       @normalized_userinfo = nil
1098       @uri_string = nil
1099       @hash = nil
1100 
1101       # Ensure we haven't created an invalid URI
1102       validate()
1103     end
1104 
1105     ##
1106     # The origin for this URI, serialized to ASCII, as per
1107     # draft-ietf-websec-origin-00, section 5.2.
1108     #
1109     # @return [String] The serialized origin.
1110     def origin
1111       return (if self.scheme && self.authority
1112         if self.normalized_port
1113           (
1114             "#{self.normalized_scheme}://#{self.normalized_host}" +
1115             ":#{self.normalized_port}"
1116           )
1117         else
1118           "#{self.normalized_scheme}://#{self.normalized_host}"
1119         end
1120       else
1121         "null"
1122       end)
1123     end
1124 
1125     # Returns an array of known ip-based schemes. These schemes typically
1126     # use a similar URI form:
1127     # <code>//<user>:<password>@<host>:<port>/<url-path></code>
1128     def self.ip_based_schemes
1129       return self.port_mapping.keys
1130     end
1131 
1132     # Returns a hash of common IP-based schemes and their default port
1133     # numbers. Adding new schemes to this hash, as necessary, will allow
1134     # for better URI normalization.
1135     def self.port_mapping
1136       PORT_MAPPING
1137     end
1138 
1139     ##
1140     # The port component for this URI.
1141     # This is the port number actually given in the URI. This does not
1142     # infer port numbers from default values.
1143     #
1144     # @return [Integer] The port component.
1145     def port
1146       return instance_variable_defined?(:@port) ? @port : nil
1147     end
1148 
1149     ##
1150     # The port component for this URI, normalized.
1151     #
1152     # @return [Integer] The port component, normalized.
1153     def normalized_port
1154       if URI.port_mapping[self.normalized_scheme] == self.port
1155         nil
1156       else
1157         self.port
1158       end
1159     end
1160 
1161     ##
1162     # Sets the port component for this URI.
1163     #
1164     # @param [String, Integer, #to_s] new_port The new port component.
1165     def port=(new_port)
1166       if new_port != nil && new_port.respond_to?(:to_str)
1167         new_port = Addressable::URI.unencode_component(new_port.to_str)
1168       end
1169       if new_port != nil && !(new_port.to_s =~ /^\d+$/)
1170         raise InvalidURIError,
1171           "Invalid port number: #{new_port.inspect}"
1172       end
1173 
1174       @port = new_port.to_s.to_i
1175       @port = nil if @port == 0
1176 
1177       # Reset dependant values
1178       @authority = nil
1179       @normalized_port = nil
1180       @uri_string = nil
1181       @hash = nil
1182 
1183       # Ensure we haven't created an invalid URI
1184       validate()
1185     end
1186 
1187     ##
1188     # The inferred port component for this URI.
1189     # This method will normalize to the default port for the URI's scheme if
1190     # the port isn't explicitly specified in the URI.
1191     #
1192     # @return [Integer] The inferred port component.
1193     def inferred_port
1194       if self.port.to_i == 0
1195         if self.scheme
1196           URI.port_mapping[self.scheme.strip.downcase]
1197         else
1198           nil
1199         end
1200       else
1201         self.port.to_i
1202       end
1203     end
1204 
1205     ##
1206     # The combination of components that represent a site.
1207     # Combines the scheme, user, password, host, and port components.
1208     # Primarily useful for HTTP and HTTPS.
1209     #
1210     # For example, <code>"http://example.com/path?query"</code> would have a
1211     # <code>site</code> value of <code>"http://example.com"</code>.
1212     #
1213     # @return [String] The components that identify a site.
1214     def site
1215       (self.scheme || self.authority) && @site ||= (begin
1216         site_string = ""
1217         site_string << "#{self.scheme}:" if self.scheme != nil
1218         site_string << "//#{self.authority}" if self.authority != nil
1219         site_string
1220       end)
1221     end
1222 
1223     ##
1224     # The normalized combination of components that represent a site.
1225     # Combines the scheme, user, password, host, and port components.
1226     # Primarily useful for HTTP and HTTPS.
1227     #
1228     # For example, <code>"http://example.com/path?query"</code> would have a
1229     # <code>site</code> value of <code>"http://example.com"</code>.
1230     #
1231     # @return [String] The normalized components that identify a site.
1232     def normalized_site
1233       self.site && @normalized_site ||= (begin
1234         site_string = ""
1235         if self.normalized_scheme != nil
1236           site_string << "#{self.normalized_scheme}:"
1237         end
1238         if self.normalized_authority != nil
1239           site_string << "//#{self.normalized_authority}"
1240         end
1241         site_string
1242       end)
1243     end
1244 
1245     ##
1246     # Sets the site value for this URI.
1247     #
1248     # @param [String, #to_str] new_site The new site value.
1249     def site=(new_site)
1250       if new_site
1251         if !new_site.respond_to?(:to_str)
1252           raise TypeError, "Can't convert #{new_site.class} into String."
1253         end
1254         new_site = new_site.to_str
1255         # These two regular expressions derived from the primary parsing
1256         # expression
1257         self.scheme = new_site[/^(?:([^:\/?#]+):)?(?:\/\/(?:[^\/?#]*))?$/, 1]
1258         self.authority = new_site[
1259           /^(?:(?:[^:\/?#]+):)?(?:\/\/([^\/?#]*))?$/, 1
1260         ]
1261       else
1262         self.scheme = nil
1263         self.authority = nil
1264       end
1265     end
1266 
1267     ##
1268     # The path component for this URI.
1269     #
1270     # @return [String] The path component.
1271     def path
1272       return instance_variable_defined?(:@path) ? @path : EMPTYSTR
1273     end
1274 
1275     NORMPATH = /^(?!\/)[^\/:]*:.*$/
1276     ##
1277     # The path component for this URI, normalized.
1278     #
1279     # @return [String] The path component, normalized.
1280     def normalized_path
1281       @normalized_path ||= (begin
1282         path = self.path.to_s
1283         if self.scheme == nil && path =~ NORMPATH
1284           # Relative paths with colons in the first segment are ambiguous.
1285           path = path.sub(":", "%2F")
1286         end
1287         # String#split(delimeter, -1) uses the more strict splitting behavior
1288         # found by default in Python.
1289         result = (path.strip.split(SLASH, -1).map do |segment|
1290           Addressable::URI.normalize_component(
1291             segment,
1292             Addressable::URI::CharacterClasses::PCHAR
1293           )
1294         end).join(SLASH)
1295 
1296         result = URI.normalize_path(result)
1297         if result.empty? &&
1298             ["http", "https", "ftp", "tftp"].include?(self.normalized_scheme)
1299           result = SLASH
1300         end
1301         result
1302       end)
1303     end
1304 
1305     ##
1306     # Sets the path component for this URI.
1307     #
1308     # @param [String, #to_str] new_path The new path component.
1309     def path=(new_path)
1310       if new_path && !new_path.respond_to?(:to_str)
1311         raise TypeError, "Can't convert #{new_path.class} into String."
1312       end
1313       @path = (new_path || EMPTYSTR).to_str
1314       if !@path.empty? && @path[0..0] != SLASH && host != nil
1315         @path = "/#{@path}"
1316       end
1317 
1318       # Reset dependant values
1319       @normalized_path = nil
1320       @uri_string = nil
1321       @hash = nil
1322     end
1323 
1324     ##
1325     # The basename, if any, of the file in the path component.
1326     #
1327     # @return [String] The path's basename.
1328     def basename
1329       # Path cannot be nil
1330       return File.basename(self.path).gsub(/;[^\/]*$/, EMPTYSTR)
1331     end
1332 
1333     ##
1334     # The extname, if any, of the file in the path component.
1335     # Empty string if there is no extension.
1336     #
1337     # @return [String] The path's extname.
1338     def extname
1339       return nil unless self.path
1340       return File.extname(self.basename)
1341     end
1342 
1343     ##
1344     # The query component for this URI.
1345     #
1346     # @return [String] The query component.
1347     def query
1348       return instance_variable_defined?(:@query) ? @query : nil
1349     end
1350 
1351     ##
1352     # The query component for this URI, normalized.
1353     #
1354     # @return [String] The query component, normalized.
1355     def normalized_query
1356       self.query && @normalized_query ||= (begin
1357         (self.query.split("&", -1).map do |pair|
1358           Addressable::URI.normalize_component(
1359             pair,
1360             Addressable::URI::CharacterClasses::QUERY.sub("\\&", "")
1361           )
1362         end).join("&")
1363       end)
1364     end
1365 
1366     ##
1367     # Sets the query component for this URI.
1368     #
1369     # @param [String, #to_str] new_query The new query component.
1370     def query=(new_query)
1371       if new_query && !new_query.respond_to?(:to_str)
1372         raise TypeError, "Can't convert #{new_query.class} into String."
1373       end
1374       @query = new_query ? new_query.to_str : nil
1375 
1376       # Reset dependant values
1377       @normalized_query = nil
1378       @uri_string = nil
1379       @hash = nil
1380     end
1381 
1382     ##
1383     # Converts the query component to a Hash value.
1384     #
1385     # @option [Symbol] notation
1386     #   May be one of <code>:flat</code>, <code>:dot</code>, or
1387     #   <code>:subscript</code>. The <code>:dot</code> notation is not
1388     #   supported for assignment. Default value is <code>:subscript</code>.
1389     #
1390     # @return [Hash, Array] The query string parsed as a Hash or Array object.
1391     #
1392     # @example
1393     #   Addressable::URI.parse("?one=1&two=2&three=3").query_values
1394     #   #=> {"one" => "1", "two" => "2", "three" => "3"}
1395     #   Addressable::URI.parse("?one[two][three]=four").query_values
1396     #   #=> {"one" => {"two" => {"three" => "four"}}}
1397     #   Addressable::URI.parse("?one.two.three=four").query_values(
1398     #     :notation => :dot
1399     #   )
1400     #   #=> {"one" => {"two" => {"three" => "four"}}}
1401     #   Addressable::URI.parse("?one[two][three]=four").query_values(
1402     #     :notation => :flat
1403     #   )
1404     #   #=> {"one[two][three]" => "four"}
1405     #   Addressable::URI.parse("?one.two.three=four").query_values(
1406     #     :notation => :flat
1407     #   )
1408     #   #=> {"one.two.three" => "four"}
1409     #   Addressable::URI.parse(
1410     #     "?one[two][three][]=four&one[two][three][]=five"
1411     #   ).query_values
1412     #   #=> {"one" => {"two" => {"three" => ["four", "five"]}}}
1413     #   Addressable::URI.parse(
1414     #     "?one=two&one=three").query_values(:notation => :flat_array)
1415     #   #=> [['one', 'two'], ['one', 'three']]
1416     def query_values(options={})
1417       defaults = {:notation => :subscript}
1418       options = defaults.merge(options)
1419       if ![:flat, :dot, :subscript, :flat_array].include?(options[:notation])
1420         raise ArgumentError,
1421           "Invalid notation. Must be one of: " +
1422           "[:flat, :dot, :subscript, :flat_array]."
1423       end
1424       dehash = lambda do |hash|
1425         hash.each do |(key, value)|
1426           if value.kind_of?(Hash)
1427             hash[key] = dehash.call(value)
1428           end
1429         end
1430         if hash != {} && hash.keys.all? { |key| key =~ /^\d+$/ }
1431           hash.sort.inject([]) do |accu, (_, value)|
1432             accu << value; accu
1433           end
1434         else
1435           hash
1436         end
1437       end
1438       return nil if self.query == nil
1439       empty_accumulator = :flat_array == options[:notation] ? [] : {}
1440       return ((self.query.split("&").map do |pair|
1441         pair.split("=", 2) if pair && !pair.empty?
1442       end).compact.inject(empty_accumulator.dup) do |accumulator, (key, value)|
1443         value = true if value.nil?
1444         key = URI.unencode_component(key)
1445         if value != true
1446           value = URI.unencode_component(value.gsub(/\+/, " "))
1447         end
1448         if options[:notation] == :flat
1449           if accumulator[key]
1450             raise ArgumentError, "Key was repeated: #{key.inspect}"
1451           end
1452           accumulator[key] = value
1453         elsif options[:notation] == :flat_array
1454           accumulator << [key, value]
1455         else
1456           if options[:notation] == :dot
1457             array_value = false
1458             subkeys = key.split(".")
1459           elsif options[:notation] == :subscript
1460             array_value = !!(key =~ /\[\]$/)
1461             subkeys = key.split(/[\[\]]+/)
1462           end
1463           current_hash = accumulator
1464           for i in 0...(subkeys.size - 1)
1465             subkey = subkeys[i]
1466             current_hash[subkey] = {} unless current_hash[subkey]
1467             current_hash = current_hash[subkey]
1468           end
1469           if array_value
1470             current_hash[subkeys.last] = [] unless current_hash[subkeys.last]
1471             current_hash[subkeys.last] << value
1472           else
1473             current_hash[subkeys.last] = value
1474           end
1475         end
1476         accumulator
1477       end).inject(empty_accumulator.dup) do |accumulator, (key, value)|
1478         if options[:notation] == :flat_array
1479           accumulator << [key, value]
1480         else
1481           accumulator[key] = value.kind_of?(Hash) ? dehash.call(value) : value
1482         end
1483         accumulator
1484       end
1485     end
1486 
1487     ##
1488     # Sets the query component for this URI from a Hash object.
1489     # This method produces a query string using the :subscript notation.
1490     # An empty Hash will result in a nil query.
1491     #
1492     # @param [Hash, #to_hash, Array] new_query_values The new query values.
1493     def query_values=(new_query_values)
1494       if new_query_values == nil
1495         self.query = nil
1496         return nil
1497       end
1498 
1499       if !new_query_values.is_a?(Array)
1500         if !new_query_values.respond_to?(:to_hash)
1501           raise TypeError,
1502             "Can't convert #{new_query_values.class} into Hash."
1503         end
1504         new_query_values = new_query_values.to_hash
1505         new_query_values = new_query_values.map do |key, value|
1506           key = key.to_s if key.kind_of?(Symbol)
1507           [key, value]
1508         end
1509         # Useful default for OAuth and caching.
1510         # Only to be used for non-Array inputs. Arrays should preserve order.
1511         new_query_values.sort!
1512       end
1513 
1514       ##
1515       # Joins and converts parent and value into a properly encoded and
1516       # ordered URL query.
1517       #
1518       # @private
1519       # @param [String] parent an URI encoded component.
1520       # @param [Array, Hash, Symbol, #to_str] value
1521       #
1522       # @return [String] a properly escaped and ordered URL query.
1523       to_query = lambda do |parent, value|
1524         if value.is_a?(Hash)
1525           value = value.map do |key, val|
1526             [
1527               URI.encode_component(key, CharacterClasses::UNRESERVED),
1528               val
1529             ]
1530           end
1531           value.sort!
1532           buffer = ""
1533           value.each do |key, val|
1534             new_parent = "#{parent}[#{key}]"
1535             buffer << "#{to_query.call(new_parent, val)}&"
1536           end
1537           return buffer.chop
1538         elsif value.is_a?(Array)
1539           buffer = ""
1540           value.each_with_index do |val, i|
1541             new_parent = "#{parent}[#{i}]"
1542             buffer << "#{to_query.call(new_parent, val)}&"
1543           end
1544           return buffer.chop
1545         elsif value == true
1546           return parent
1547         else
1548           encoded_value = URI.encode_component(
1549             value, CharacterClasses::UNRESERVED
1550           )
1551           return "#{parent}=#{encoded_value}"
1552         end
1553       end
1554 
1555       # new_query_values have form [['key1', 'value1'], ['key2', 'value2']]
1556       buffer = ""
1557       new_query_values.each do |parent, value|
1558         encoded_parent = URI.encode_component(
1559           parent, CharacterClasses::UNRESERVED
1560         )
1561         buffer << "#{to_query.call(encoded_parent, value)}&"
1562       end
1563       self.query = buffer.chop
1564     end
1565 
1566     ##
1567     # The HTTP request URI for this URI.  This is the path and the
1568     # query string.
1569     #
1570     # @return [String] The request URI required for an HTTP request.
1571     def request_uri
1572       return nil if self.absolute? && self.scheme !~ /^https?$/
1573       return (
1574         (!self.path.empty? ? self.path : SLASH) +
1575         (self.query ? "?#{self.query}" : EMPTYSTR)
1576       )
1577     end
1578 
1579     ##
1580     # Sets the HTTP request URI for this URI.
1581     #
1582     # @param [String, #to_str] new_request_uri The new HTTP request URI.
1583     def request_uri=(new_request_uri)
1584       if !new_request_uri.respond_to?(:to_str)
1585         raise TypeError, "Can't convert #{new_request_uri.class} into String."
1586       end
1587       if self.absolute? && self.scheme !~ /^https?$/
1588         raise InvalidURIError,
1589           "Cannot set an HTTP request URI for a non-HTTP URI."
1590       end
1591       new_request_uri = new_request_uri.to_str
1592       path_component = new_request_uri[/^([^\?]*)\?(?:.*)$/, 1]
1593       query_component = new_request_uri[/^(?:[^\?]*)\?(.*)$/, 1]
1594       path_component = path_component.to_s
1595       path_component = (!path_component.empty? ? path_component : SLASH)
1596       self.path = path_component
1597       self.query = query_component
1598 
1599       # Reset dependant values
1600       @uri_string = nil
1601       @hash = nil
1602     end
1603 
1604     ##
1605     # The fragment component for this URI.
1606     #
1607     # @return [String] The fragment component.
1608     def fragment
1609       return instance_variable_defined?(:@fragment) ? @fragment : nil
1610     end
1611 
1612     ##
1613     # The fragment component for this URI, normalized.
1614     #
1615     # @return [String] The fragment component, normalized.
1616     def normalized_fragment
1617       self.fragment && @normalized_fragment ||= (begin
1618         Addressable::URI.normalize_component(
1619           self.fragment.strip,
1620           Addressable::URI::CharacterClasses::FRAGMENT
1621         )
1622       end)
1623     end
1624 
1625     ##
1626     # Sets the fragment component for this URI.
1627     #
1628     # @param [String, #to_str] new_fragment The new fragment component.
1629     def fragment=(new_fragment)
1630       if new_fragment && !new_fragment.respond_to?(:to_str)
1631         raise TypeError, "Can't convert #{new_fragment.class} into String."
1632       end
1633       @fragment = new_fragment ? new_fragment.to_str : nil
1634 
1635       # Reset dependant values
1636       @normalized_fragment = nil
1637       @uri_string = nil
1638       @hash = nil
1639 
1640       # Ensure we haven't created an invalid URI
1641       validate()
1642     end
1643 
1644     ##
1645     # Determines if the scheme indicates an IP-based protocol.
1646     #
1647     # @return [TrueClass, FalseClass]
1648     #   <code>true</code> if the scheme indicates an IP-based protocol.
1649     #   <code>false</code> otherwise.
1650     def ip_based?
1651       if self.scheme
1652         return URI.ip_based_schemes.include?(
1653           self.scheme.strip.downcase)
1654       end
1655       return false
1656     end
1657 
1658     ##
1659     # Determines if the URI is relative.
1660     #
1661     # @return [TrueClass, FalseClass]
1662     #   <code>true</code> if the URI is relative. <code>false</code>
1663     #   otherwise.
1664     def relative?
1665       return self.scheme.nil?
1666     end
1667 
1668     ##
1669     # Determines if the URI is absolute.
1670     #
1671     # @return [TrueClass, FalseClass]
1672     #   <code>true</code> if the URI is absolute. <code>false</code>
1673     #   otherwise.
1674     def absolute?
1675       return !relative?
1676     end
1677 
1678     ##
1679     # Joins two URIs together.
1680     #
1681     # @param [String, Addressable::URI, #to_str] The URI to join with.
1682     #
1683     # @return [Addressable::URI] The joined URI.
1684     def join(uri)
1685       if !uri.respond_to?(:to_str)
1686         raise TypeError, "Can't convert #{uri.class} into String."
1687       end
1688       if !uri.kind_of?(URI)
1689         # Otherwise, convert to a String, then parse.
1690         uri = URI.parse(uri.to_str)
1691       end
1692       if uri.to_s.empty?
1693         return self.dup
1694       end
1695 
1696       joined_scheme = nil
1697       joined_user = nil
1698       joined_password = nil
1699       joined_host = nil
1700       joined_port = nil
1701       joined_path = nil
1702       joined_query = nil
1703       joined_fragment = nil
1704 
1705       # Section 5.2.2 of RFC 3986
1706       if uri.scheme != nil
1707         joined_scheme = uri.scheme
1708         joined_user = uri.user
1709         joined_password = uri.password
1710         joined_host = uri.host
1711         joined_port = uri.port
1712         joined_path = URI.normalize_path(uri.path)
1713         joined_query = uri.query
1714       else
1715         if uri.authority != nil
1716           joined_user = uri.user
1717           joined_password = uri.password
1718           joined_host = uri.host
1719           joined_port = uri.port
1720           joined_path = URI.normalize_path(uri.path)
1721           joined_query = uri.query
1722         else
1723           if uri.path == nil || uri.path.empty?
1724             joined_path = self.path
1725             if uri.query != nil
1726               joined_query = uri.query
1727             else
1728               joined_query = self.query
1729             end
1730           else
1731             if uri.path[0..0] == SLASH
1732               joined_path = URI.normalize_path(uri.path)
1733             else
1734               base_path = self.path.dup
1735               base_path = EMPTYSTR if base_path == nil
1736               base_path = URI.normalize_path(base_path)
1737 
1738               # Section 5.2.3 of RFC 3986
1739               #
1740               # Removes the right-most path segment from the base path.
1741               if base_path =~ /\//
1742                 base_path.gsub!(/\/[^\/]+$/, SLASH)
1743               else
1744                 base_path = EMPTYSTR
1745               end
1746 
1747               # If the base path is empty and an authority segment has been
1748               # defined, use a base path of SLASH
1749               if base_path.empty? && self.authority != nil
1750                 base_path = SLASH
1751               end
1752 
1753               joined_path = URI.normalize_path(base_path + uri.path)
1754             end
1755             joined_query = uri.query
1756           end
1757           joined_user = self.user
1758           joined_password = self.password
1759           joined_host = self.host
1760           joined_port = self.port
1761         end
1762         joined_scheme = self.scheme
1763       end
1764       joined_fragment = uri.fragment
1765 
1766       return Addressable::URI.new(
1767         :scheme => joined_scheme,
1768         :user => joined_user,
1769         :password => joined_password,
1770         :host => joined_host,
1771         :port => joined_port,
1772         :path => joined_path,
1773         :query => joined_query,
1774         :fragment => joined_fragment
1775       )
1776     end
1777     alias_method :+, :join
1778 
1779     ##
1780     # Destructive form of <code>join</code>.
1781     #
1782     # @param [String, Addressable::URI, #to_str] The URI to join with.
1783     #
1784     # @return [Addressable::URI] The joined URI.
1785     #
1786     # @see Addressable::URI#join
1787     def join!(uri)
1788       replace_self(self.join(uri))
1789     end
1790 
1791     ##
1792     # Merges a URI with a <code>Hash</code> of components.
1793     # This method has different behavior from <code>join</code>. Any
1794     # components present in the <code>hash</code> parameter will override the
1795     # original components. The path component is not treated specially.
1796     #
1797     # @param [Hash, Addressable::URI, #to_hash] The components to merge with.
1798     #
1799     # @return [Addressable::URI] The merged URI.
1800     #
1801     # @see Hash#merge
1802     def merge(hash)
1803       if !hash.respond_to?(:to_hash)
1804         raise TypeError, "Can't convert #{hash.class} into Hash."
1805       end
1806       hash = hash.to_hash
1807 
1808       if hash.has_key?(:authority)
1809         if (hash.keys & [:userinfo, :user, :password, :host, :port]).any?
1810           raise ArgumentError,
1811             "Cannot specify both an authority and any of the components " +
1812             "within the authority."
1813         end
1814       end
1815       if hash.has_key?(:userinfo)
1816         if (hash.keys & [:user, :password]).any?
1817           raise ArgumentError,
1818             "Cannot specify both a userinfo and either the user or password."
1819         end
1820       end
1821 
1822       uri = Addressable::URI.new
1823       uri.defer_validation do
1824         # Bunch of crazy logic required because of the composite components
1825         # like userinfo and authority.
1826         uri.scheme =
1827           hash.has_key?(:scheme) ? hash[:scheme] : self.scheme
1828         if hash.has_key?(:authority)
1829           uri.authority =
1830             hash.has_key?(:authority) ? hash[:authority] : self.authority
1831         end
1832         if hash.has_key?(:userinfo)
1833           uri.userinfo =
1834             hash.has_key?(:userinfo) ? hash[:userinfo] : self.userinfo
1835         end
1836         if !hash.has_key?(:userinfo) && !hash.has_key?(:authority)
1837           uri.user =
1838             hash.has_key?(:user) ? hash[:user] : self.user
1839           uri.password =
1840             hash.has_key?(:password) ? hash[:password] : self.password
1841         end
1842         if !hash.has_key?(:authority)
1843           uri.host =
1844             hash.has_key?(:host) ? hash[:host] : self.host
1845           uri.port =
1846             hash.has_key?(:port) ? hash[:port] : self.port
1847         end
1848         uri.path =
1849           hash.has_key?(:path) ? hash[:path] : self.path
1850         uri.query =
1851           hash.has_key?(:query) ? hash[:query] : self.query
1852         uri.fragment =
1853           hash.has_key?(:fragment) ? hash[:fragment] : self.fragment
1854       end
1855 
1856       return uri
1857     end
1858 
1859     ##
1860     # Destructive form of <code>merge</code>.
1861     #
1862     # @param [Hash, Addressable::URI, #to_hash] The components to merge with.
1863     #
1864     # @return [Addressable::URI] The merged URI.
1865     #
1866     # @see Addressable::URI#merge
1867     def merge!(uri)
1868       replace_self(self.merge(uri))
1869     end
1870 
1871     ##
1872     # Returns the shortest normalized relative form of this URI that uses the
1873     # supplied URI as a base for resolution. Returns an absolute URI if
1874     # necessary. This is effectively the opposite of <code>route_to</code>.
1875     #
1876     # @param [String, Addressable::URI, #to_str] uri The URI to route from.
1877     #
1878     # @return [Addressable::URI]
1879     #   The normalized relative URI that is equivalent to the original URI.
1880     def route_from(uri)
1881       uri = URI.parse(uri).normalize
1882       normalized_self = self.normalize
1883       if normalized_self.relative?
1884         raise ArgumentError, "Expected absolute URI, got: #{self.to_s}"
1885       end
1886       if uri.relative?
1887         raise ArgumentError, "Expected absolute URI, got: #{uri.to_s}"
1888       end
1889       if normalized_self == uri
1890         return Addressable::URI.parse("##{normalized_self.fragment}")
1891       end
1892       components = normalized_self.to_hash
1893       if normalized_self.scheme == uri.scheme
1894         components[:scheme] = nil
1895         if normalized_self.authority == uri.authority
1896           components[:user] = nil
1897           components[:password] = nil
1898           components[:host] = nil
1899           components[:port] = nil
1900           if normalized_self.path == uri.path
1901             components[:path] = nil
1902             if normalized_self.query == uri.query
1903               components[:query] = nil
1904             end
1905           else
1906             if uri.path != SLASH
1907               components[:path].gsub!(
1908                 Regexp.new("^" + Regexp.escape(uri.path)), EMPTYSTR)
1909             end
1910           end
1911         end
1912       end
1913       # Avoid network-path references.
1914       if components[:host] != nil
1915         components[:scheme] = normalized_self.scheme
1916       end
1917       return Addressable::URI.new(
1918         :scheme => components[:scheme],
1919         :user => components[:user],
1920         :password => components[:password],
1921         :host => components[:host],
1922         :port => components[:port],
1923         :path => components[:path],
1924         :query => components[:query],
1925         :fragment => components[:fragment]
1926       )
1927     end
1928 
1929     ##
1930     # Returns the shortest normalized relative form of the supplied URI that
1931     # uses this URI as a base for resolution. Returns an absolute URI if
1932     # necessary. This is effectively the opposite of <code>route_from</code>.
1933     #
1934     # @param [String, Addressable::URI, #to_str] uri The URI to route to.
1935     #
1936     # @return [Addressable::URI]
1937     #   The normalized relative URI that is equivalent to the supplied URI.
1938     def route_to(uri)
1939       return URI.parse(uri).route_from(self)
1940     end
1941 
1942     ##
1943     # Returns a normalized URI object.
1944     #
1945     # NOTE: This method does not attempt to fully conform to specifications.
1946     # It exists largely to correct other people's failures to read the
1947     # specifications, and also to deal with caching issues since several
1948     # different URIs may represent the same resource and should not be
1949     # cached multiple times.
1950     #
1951     # @return [Addressable::URI] The normalized URI.
1952     def normalize
1953       # This is a special exception for the frequently misused feed
1954       # URI scheme.
1955       if normalized_scheme == "feed"
1956         if self.to_s =~ /^feed:\/*http:\/*/
1957           return URI.parse(
1958             self.to_s[/^feed:\/*(http:\/*.*)/, 1]
1959           ).normalize
1960         end
1961       end
1962 
1963       return Addressable::URI.new(
1964         :scheme => normalized_scheme,
1965         :authority => normalized_authority,
1966         :path => normalized_path,
1967         :query => normalized_query,
1968         :fragment => normalized_fragment
1969       )
1970     end
1971 
1972     ##
1973     # Destructively normalizes this URI object.
1974     #
1975     # @return [Addressable::URI] The normalized URI.
1976     #
1977     # @see Addressable::URI#normalize
1978     def normalize!
1979       replace_self(self.normalize)
1980     end
1981 
1982     ##
1983     # Creates a URI suitable for display to users. If semantic attacks are
1984     # likely, the application should try to detect these and warn the user.
1985     # See <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>,
1986     # section 7.6 for more information.
1987     #
1988     # @return [Addressable::URI] A URI suitable for display purposes.
1989     def display_uri
1990       display_uri = self.normalize
1991       display_uri.host = ::Addressable::IDNA.to_unicode(display_uri.host)
1992       return display_uri
1993     end
1994 
1995     ##
1996     # Returns <code>true</code> if the URI objects are equal. This method
1997     # normalizes both URIs before doing the comparison, and allows comparison
1998     # against <code>Strings</code>.
1999     #
2000     # @param [Object] uri The URI to compare.
2001     #
2002     # @return [TrueClass, FalseClass]
2003     #   <code>true</code> if the URIs are equivalent, <code>false</code>
2004     #   otherwise.
2005     def ===(uri)
2006       if uri.respond_to?(:normalize)
2007         uri_string = uri.normalize.to_s
2008       else
2009         begin
2010           uri_string = ::Addressable::URI.parse(uri).normalize.to_s
2011         rescue InvalidURIError, TypeError
2012           return false
2013         end
2014       end
2015       return self.normalize.to_s == uri_string
2016     end
2017 
2018     ##
2019     # Returns <code>true</code> if the URI objects are equal. This method
2020     # normalizes both URIs before doing the comparison.
2021     #
2022     # @param [Object] uri The URI to compare.
2023     #
2024     # @return [TrueClass, FalseClass]
2025     #   <code>true</code> if the URIs are equivalent, <code>false</code>
2026     #   otherwise.
2027     def ==(uri)
2028       return false unless uri.kind_of?(URI)
2029       return self.normalize.to_s == uri.normalize.to_s
2030     end
2031 
2032     ##
2033     # Returns <code>true</code> if the URI objects are equal. This method
2034     # does NOT normalize either URI before doing the comparison.
2035     #
2036     # @param [Object] uri The URI to compare.
2037     #
2038     # @return [TrueClass, FalseClass]
2039     #   <code>true</code> if the URIs are equivalent, <code>false</code>
2040     #   otherwise.
2041     def eql?(uri)
2042       return false unless uri.kind_of?(URI)
2043       return self.to_s == uri.to_s
2044     end
2045 
2046     ##
2047     # A hash value that will make a URI equivalent to its normalized
2048     # form.
2049     #
2050     # @return [Integer] A hash of the URI.
2051     def hash
2052       return @hash ||= (self.to_s.hash * -1)
2053     end
2054 
2055     ##
2056     # Clones the URI object.
2057     #
2058     # @return [Addressable::URI] The cloned URI.
2059     def dup
2060       duplicated_uri = Addressable::URI.new(
2061         :scheme => self.scheme ? self.scheme.dup : nil,
2062         :user => self.user ? self.user.dup : nil,
2063         :password => self.password ? self.password.dup : nil,
2064         :host => self.host ? self.host.dup : nil,
2065         :port => self.port,
2066         :path => self.path ? self.path.dup : nil,
2067         :query => self.query ? self.query.dup : nil,
2068         :fragment => self.fragment ? self.fragment.dup : nil
2069       )
2070       return duplicated_uri
2071     end
2072 
2073     ##
2074     # Omits components from a URI.
2075     #
2076     # @param [Symbol] *components The components to be omitted.
2077     #
2078     # @return [Addressable::URI] The URI with components omitted.
2079     #
2080     # @example
2081     #   uri = Addressable::URI.parse("http://example.com/path?query")
2082     #   #=> #<Addressable::URI:0xcc5e7a URI:http://example.com/path?query>
2083     #   uri.omit(:scheme, :authority)
2084     #   #=> #<Addressable::URI:0xcc4d86 URI:/path?query>
2085     def omit(*components)
2086       invalid_components = components - [
2087         :scheme, :user, :password, :userinfo, :host, :port, :authority,
2088         :path, :query, :fragment
2089       ]
2090       unless invalid_components.empty?
2091         raise ArgumentError,
2092           "Invalid component names: #{invalid_components.inspect}."
2093       end
2094       duplicated_uri = self.dup
2095       duplicated_uri.defer_validation do
2096         components.each do |component|
2097           duplicated_uri.send((component.to_s + "=").to_sym, nil)
2098         end
2099         duplicated_uri.user = duplicated_uri.normalized_user
2100       end
2101       duplicated_uri
2102     end
2103 
2104     ##
2105     # Destructive form of omit.
2106     #
2107     # @param [Symbol] *components The components to be omitted.
2108     #
2109     # @return [Addressable::URI] The URI with components omitted.
2110     #
2111     # @see Addressable::URI#omit
2112     def omit!(*components)
2113       replace_self(self.omit(*components))
2114     end
2115 
2116     ##
2117     # Converts the URI to a <code>String</code>.
2118     #
2119     # @return [String] The URI's <code>String</code> representation.
2120     def to_s
2121       if self.scheme == nil && self.path != nil && !self.path.empty? &&
2122           self.path =~ NORMPATH
2123         raise InvalidURIError,
2124           "Cannot assemble URI string with ambiguous path: '#{self.path}'"
2125       end
2126       @uri_string ||= (begin
2127         uri_string = ""
2128         uri_string << "#{self.scheme}:" if self.scheme != nil
2129         uri_string << "//#{self.authority}" if self.authority != nil
2130         uri_string << self.path.to_s
2131         uri_string << "?#{self.query}" if self.query != nil
2132         uri_string << "##{self.fragment}" if self.fragment != nil
2133         if uri_string.respond_to?(:force_encoding)
2134           uri_string.force_encoding(Encoding::UTF_8)
2135         end
2136         uri_string
2137       end)
2138     end
2139 
2140     ##
2141     # URI's are glorified <code>Strings</code>. Allow implicit conversion.
2142     alias_method :to_str, :to_s
2143 
2144     ##
2145     # Returns a Hash of the URI components.
2146     #
2147     # @return [Hash] The URI as a <code>Hash</code> of components.
2148     def to_hash
2149       return {
2150         :scheme => self.scheme,
2151         :user => self.user,
2152         :password => self.password,
2153         :host => self.host,
2154         :port => self.port,
2155         :path => self.path,
2156         :query => self.query,
2157         :fragment => self.fragment
2158       }
2159     end
2160 
2161     ##
2162     # Returns a <code>String</code> representation of the URI object's state.
2163     #
2164     # @return [String] The URI object's state, as a <code>String</code>.
2165     def inspect
2166       sprintf("#<%s:%#0x URI:%s>", URI.to_s, self.object_id, self.to_s)
2167     end
2168 
2169     ##
2170     # This method allows you to make several changes to a URI simultaneously,
2171     # which separately would cause validation errors, but in conjunction,
2172     # are valid.  The URI will be revalidated as soon as the entire block has
2173     # been executed.
2174     #
2175     # @param [Proc] block
2176     #   A set of operations to perform on a given URI.
2177     def defer_validation(&block)
2178       raise LocalJumpError, "No block given." unless block
2179       @validation_deferred = true
2180       block.call()
2181       @validation_deferred = false
2182       validate
2183       return nil
2184     end
2185 
2186   private
2187     ##
2188     # Resolves paths to their simplest form.
2189     #
2190     # @param [String] path The path to normalize.
2191     #
2192     # @return [String] The normalized path.
2193 
2194     PARENT1 = '.'
2195     PARENT2 = '..'
2196 
2197     NPATH1 = /\/\.\/|\/\.$/
2198     NPATH2 = /\/([^\/]+)\/\.\.\/|\/([^\/]+)\/\.\.$/
2199     NPATH3 = /^\.\.?\/?/
2200     NPATH4 = /^\/\.\.?\/|^(\/\.\.?)+\/?$/
2201 
2202     def self.normalize_path(path)
2203       # Section 5.2.4 of RFC 3986
2204 
2205       return nil if path.nil?
2206       normalized_path = path.dup
2207       begin
2208         mod = nil
2209         mod ||= normalized_path.gsub!(NPATH1, SLASH)
2210 
2211         parent = normalized_path.match(NPATH2)
2212         if parent && ((parent[1] != PARENT1 && parent[1] != PARENT2) \
2213                       || (parent[2] != PARENT1 && parent[2] != PARENT2))
2214           mod ||= normalized_path.gsub!(/\/#{Regexp.escape(parent[1].to_s)}\/\.\.\/|(\/#{Regexp.escape(parent[2].to_s)}\/\.\.$)/, SLASH)
2215         end
2216 
2217         mod ||= normalized_path.gsub!(NPATH3, EMPTYSTR)
2218         mod ||= normalized_path.gsub!(NPATH4, SLASH)
2219       end until mod.nil?
2220 
2221       return normalized_path
2222     end
2223 
2224     ##
2225     # Ensures that the URI is valid.
2226     def validate
2227       return if !!@validation_deferred
2228       if self.scheme != nil &&
2229           (self.host == nil || self.host.empty?) &&
2230           (self.path == nil || self.path.empty?)
2231         raise InvalidURIError,
2232           "Absolute URI missing hierarchical segment: '#{self.to_s}'"
2233       end
2234       if self.host == nil
2235         if self.port != nil ||
2236             self.user != nil ||
2237             self.password != nil
2238           raise InvalidURIError, "Hostname not supplied: '#{self.to_s}'"
2239         end
2240       end
2241       if self.path != nil && !self.path.empty? && self.path[0..0] != SLASH &&
2242           self.authority != nil
2243         raise InvalidURIError,
2244           "Cannot have a relative path with an authority set: '#{self.to_s}'"
2245       end
2246       return nil
2247     end
2248 
2249     ##
2250     # Replaces the internal state of self with the specified URI's state.
2251     # Used in destructive operations to avoid massive code repetition.
2252     #
2253     # @param [Addressable::URI] uri The URI to replace <code>self</code> with.
2254     #
2255     # @return [Addressable::URI] <code>self</code>.
2256     def replace_self(uri)
2257       # Reset dependant values
2258       instance_variables.each do |var|
2259         instance_variable_set(var, nil)
2260       end
2261 
2262       @scheme = uri.scheme
2263       @user = uri.user
2264       @password = uri.password
2265       @host = uri.host
2266       @port = uri.port
2267       @path = uri.path
2268       @query = uri.query
2269       @fragment = uri.fragment
2270       return self
2271     end
2272   end
2273 end

Generated on Thu Feb 16 15:34:49 +0300 2012 with rcov 0.9.8