rubysl-uri 1.0.0 → 2.0.0

data/lib/uri/http.rb

@@ -1,9 +1,10 @@
-#
 # = uri/http.rb
 #
 # Author:: Akira Yamada <akira@ruby-lang.org>
 # License:: You can redistribute it and/or modify it under the same term as Ruby.
-# Revision:: $Id: http.rb 11747 2007-02-15 02:41:45Z knu $
+# Revision:: $Id$
+#
+# See URI for general documentation
 #
 
 require 'uri/generic'
@@ -14,18 +15,20 @@ module URI
   # The syntax of HTTP URIs is defined in RFC1738 section 3.3.
   #
   # Note that the Ruby URI library allows HTTP URLs containing usernames and
-  # passwords. This is not legal as per the RFC, but used to be 
-  # supported in Internet Explorer 5 and 6, before the MS04-004 security 
+  # passwords. This is not legal as per the RFC, but used to be
+  # supported in Internet Explorer 5 and 6, before the MS04-004 security
   # update. See <URL:http://support.microsoft.com/kb/834489>.
   #
   class HTTP < Generic
+    # A Default port of 80 for URI::HTTP
     DEFAULT_PORT = 80
 
+    # An Array of the available components for URI::HTTP
     COMPONENT = [
-      :scheme, 
-      :userinfo, :host, :port, 
-      :path, 
-      :query, 
+      :scheme,
+      :userinfo, :host, :port,
+      :path,
+      :query,
       :fragment
     ].freeze
 
@@ -37,21 +40,21 @@ module URI
     # The components accepted are userinfo, host, port, path, query and
     # fragment.
     #
-    # The components should be provided either as an Array, or as a Hash 
-    # with keys formed by preceding the component names with a colon. 
+    # The components should be provided either as an Array, or as a Hash
+    # with keys formed by preceding the component names with a colon.
     #
     # If an Array is used, the components must be passed in the order
     # [userinfo, host, port, path, query, fragment].
     #
     # Example:
     #
-    #     newuri = URI::HTTP.build({:host => 'www.example.com', 
-    #       :path> => '/foo/bar'})
+    #     newuri = URI::HTTP.build({:host => 'www.example.com',
+    #       :path => '/foo/bar'})
     #
-    #     newuri = URI::HTTP.build([nil, "www.example.com", nil, "/path", 
+    #     newuri = URI::HTTP.build([nil, "www.example.com", nil, "/path",
     #       "query", 'fragment'])
     #
-    # Currently, if passed userinfo components this method generates 
+    # Currently, if passed userinfo components this method generates
     # invalid HTTP URIs as per RFC 1738.
     #
     def self.build(args)
@@ -63,16 +66,19 @@ module URI
     # == Description
     #
     # Create a new URI::HTTP object from generic URI components as per
-    # RFC 2396. No HTTP-specific syntax checking (as per RFC 1738) is 
+    # RFC 2396. No HTTP-specific syntax checking (as per RFC 1738) is
     # performed.
     #
-    # Arguments are +scheme+, +userinfo+, +host+, +port+, +registry+, +path+, 
+    # Arguments are +scheme+, +userinfo+, +host+, +port+, +registry+, +path+,
     # +opaque+, +query+ and +fragment+, in that order.
     #
     # Example:
     #
-    #     uri = URI::HTTP.new(['http', nil, "www.example.com", nil, "/path",
-    #       "query", 'fragment'])
+    #     uri = URI::HTTP.new('http', nil, "www.example.com", nil, "/path",
+    #       "query", 'fragment')
+    #
+    #
+    # See also URI::Generic.new
     #
     def initialize(*arg)
       super(*arg)
@@ -88,7 +94,7 @@ module URI
     #
     def request_uri
       r = path_query
-      if r[0] != ?/
+      if r && r[0] != ?/
         r = '/' + r
       end
 

data/lib/uri/https.rb

@@ -1,9 +1,10 @@
-#
 # = uri/https.rb
 #
 # Author:: Akira Yamada <akira@ruby-lang.org>
 # License:: You can redistribute it and/or modify it under the same term as Ruby.
-# Revision:: $Id: https.rb 11747 2007-02-15 02:41:45Z knu $
+# Revision:: $Id$
+#
+# See URI for general documentation
 #
 
 require 'uri/http'
@@ -14,6 +15,7 @@ module URI
   # than 'http:'. Other than that, HTTPS URIs are identical to HTTP URIs;
   # see URI::HTTP.
   class HTTPS < HTTP
+    # A Default port of 443 for URI::HTTPS
     DEFAULT_PORT = 443
   end
   @@schemes['HTTPS'] = HTTPS

data/lib/uri/ldap.rb

@@ -1,13 +1,14 @@
-#
 # = uri/ldap.rb
 #
-# Author:: 
+# Author::
 #  Takaaki Tateishi <ttate@jaist.ac.jp>
 #  Akira Yamada <akira@ruby-lang.org>
-# License:: 
+# License::
 #   URI::LDAP is copyrighted free software by Takaaki Tateishi and Akira Yamada.
 #   You can redistribute it and/or modify it under the same term as Ruby.
-# Revision:: $Id: ldap.rb 11708 2007-02-12 23:01:19Z shyouhei $
+# Revision:: $Id$
+#
+# See URI for general documentation
 #
 
 require 'uri/generic'
@@ -20,8 +21,10 @@ module URI
   #
   class LDAP < Generic
 
+    # A Default port of 389 for URI::LDAP
     DEFAULT_PORT = 389
-    
+
+    # An Array of the available components for URI::LDAP
     COMPONENT = [
       :scheme,
       :host, :port,
@@ -32,12 +35,41 @@ module URI
       :extensions,
     ].freeze
 
+    # Scopes available for the starting point.
+    #
+    # * SCOPE_BASE - the Base DN
+    # * SCOPE_ONE  - one level under the Base DN, not including the base DN and
+    #                not including any entries under this.
+    # * SCOPE_SUB  - subtress, all entries at all levels
+    #
     SCOPE = [
       SCOPE_ONE = 'one',
       SCOPE_SUB = 'sub',
       SCOPE_BASE = 'base',
     ].freeze
 
+    #
+    # == Description
+    #
+    # Create a new URI::LDAP object from components, with syntax checking.
+    #
+    # The components accepted are host, port, dn, attributes,
+    # scope, filter, and extensions.
+    #
+    # The components should be provided either as an Array, or as a Hash
+    # with keys formed by preceding the component names with a colon.
+    #
+    # If an Array is used, the components must be passed in the order
+    # [host, port, dn, attributes, scope, filter, extensions].
+    #
+    # Example:
+    #
+    #     newuri = URI::LDAP.build({:host => 'ldap.example.com',
+    #       :dn> => '/dc=example'})
+    #
+    #     newuri = URI::LDAP.build(["ldap.example.com", nil,
+    #       "/dc=example;dc=com", "query", nil, nil, nil])
+    #
     def self.build(args)
       tmp = Util::make_components_hash(self, args)
 
@@ -56,6 +88,23 @@ module URI
       return super(tmp)
     end
 
+    #
+    # == Description
+    #
+    # Create a new URI::LDAP object from generic URI components as per
+    # RFC 2396. No LDAP-specific syntax checking is performed.
+    #
+    # Arguments are +scheme+, +userinfo+, +host+, +port+, +registry+, +path+,
+    # +opaque+, +query+ and +fragment+, in that order.
+    #
+    # Example:
+    #
+    #     uri = URI::LDAP.new("ldap", nil, "ldap.example.com", nil,
+    #       "/dc=example;dc=com", "query", nil, nil, nil, nil)
+    #
+    #
+    # See also URI::Generic.new
+    #
     def initialize(*arg)
       super(*arg)
 
@@ -67,11 +116,14 @@ module URI
       parse_query
     end
 
+    # private method to cleanup +dn+ from using the +path+ component attribute
     def parse_dn
       @dn = @path[1..-1]
     end
     private :parse_dn
 
+    # private method to cleanup +attributes+, +scope+, +filter+ and +extensions+,
+    # from using the +query+ component attribute
     def parse_query
       @attributes = nil
       @scope      = nil
@@ -89,6 +141,7 @@ module URI
     end
     private :parse_query
 
+    # private method to assemble +query+ from +attributes+, +scope+, +filter+ and +extensions+.
     def build_path_query
       @path = '/' + @dn
 
@@ -101,10 +154,12 @@ module URI
     end
     private :build_path_query
 
+    # returns dn.
     def dn
       @dn
     end
 
+    # private setter for dn +val+
     def set_dn(val)
       @dn = val
       build_path_query
@@ -112,15 +167,18 @@ module URI
     end
     protected :set_dn
 
+    # setter for dn +val+
     def dn=(val)
       set_dn(val)
       val
     end
 
+    # returns attributes.
     def attributes
       @attributes
     end
 
+    # private setter for attributes +val+
     def set_attributes(val)
       @attributes = val
       build_path_query
@@ -128,15 +186,18 @@ module URI
     end
     protected :set_attributes
 
+    # setter for attributes +val+
     def attributes=(val)
       set_attributes(val)
       val
     end
 
+    # returns scope.
     def scope
       @scope
     end
 
+    # private setter for scope +val+
     def set_scope(val)
       @scope = val
       build_path_query
@@ -144,15 +205,18 @@ module URI
     end
     protected :set_scope
 
+    # setter for scope +val+
     def scope=(val)
       set_scope(val)
       val
     end
 
+    # returns filter.
     def filter
       @filter
     end
 
+    # private setter for filter +val+
     def set_filter(val)
       @filter = val
       build_path_query
@@ -160,15 +224,18 @@ module URI
     end
     protected :set_filter
 
+    # setter for filter +val+
     def filter=(val)
       set_filter(val)
       val
     end
 
+    # returns extensions.
     def extensions
       @extensions
     end
 
+    # private setter for extensions +val+
     def set_extensions(val)
       @extensions = val
       build_path_query
@@ -176,11 +243,14 @@ module URI
     end
     protected :set_extensions
 
+    # setter for extensions +val+
     def extensions=(val)
       set_extensions(val)
       val
     end
 
+    # Checks if URI has a path
+    # For URI::LDAP this will return +false+
     def hierarchical?
       false
     end

data/lib/uri/ldaps.rb

@@ -1,3 +1,10 @@
+# = uri/ldap.rb
+#
+# License:: You can redistribute it and/or modify it under the same term as Ruby.
+#
+# See URI for general documentation
+#
+
 require 'uri/ldap'
 
 module URI
@@ -6,6 +13,7 @@ module URI
   # than 'ldap:'. Other than that, LDAPS URIs are identical to LDAP URIs;
   # see URI::LDAP.
   class LDAPS < LDAP
+    # A Default port of 636 for URI::LDAPS
     DEFAULT_PORT = 636
   end
   @@schemes['LDAPS'] = LDAPS

data/lib/uri/mailto.rb

@@ -1,9 +1,10 @@
-#
 # = uri/mailto.rb
 #
 # Author:: Akira Yamada <akira@ruby-lang.org>
 # License:: You can redistribute it and/or modify it under the same term as Ruby.
-# Revision:: $Id: mailto.rb 11747 2007-02-15 02:41:45Z knu $
+# Revision:: $Id$
+#
+# See URI for general documentation
 #
 
 require 'uri/generic'
@@ -16,8 +17,10 @@ module URI
   class MailTo < Generic
     include REGEXP
 
+    # A Default port of nil for URI::MailTo
     DEFAULT_PORT = nil
 
+    # An Array of the available components for URI::MailTo
     COMPONENT = [ :scheme, :to, :headers ].freeze
 
     # :stopdoc:
@@ -38,7 +41,7 @@ module URI
     # hvalue     =  *urlc
     # header     =  hname "=" hvalue
     HEADER_PATTERN = "(?:[^?=&]*=[^?=&]*)".freeze
-    HEADER_REGEXP  = Regexp.new(HEADER_PATTERN, 'N').freeze
+    HEADER_REGEXP  = Regexp.new(HEADER_PATTERN).freeze
     # headers    =  "?" header *( "&" header )
     # to         =  #mailbox
     # mailtoURL  =  "mailto:" [ to ] [ headers ]
@@ -55,7 +58,7 @@ module URI
         (#{PATTERN::FRAGMENT})                        (?# 3: fragment)
       )?
       \\z
-    ", Regexp::EXTENDED, 'N').freeze
+    ", Regexp::EXTENDED).freeze
     # :startdoc:
 
     #
@@ -68,20 +71,20 @@ module URI
     #
     # If a Hash is used, the keys are the component names preceded by colons.
     #
-    # The headers can be supplied as a pre-encoded string, such as 
+    # The headers can be supplied as a pre-encoded string, such as
     # "subject=subscribe&cc=address", or as an Array of Arrays like
     # [['subject', 'subscribe'], ['cc', 'address']]
     #
     # Examples:
-    # 
+    #
     #    require 'uri'
-    #    
+    #
     #    m1 = URI::MailTo.build(['joe@example.com', 'subject=Ruby'])
     #    puts m1.to_s  ->  mailto:joe@example.com?subject=Ruby
-    #    
+    #
     #    m2 = URI::MailTo.build(['john@example.com', [['Subject', 'Ruby'], ['Cc', 'jack@example.com']]])
     #    puts m2.to_s  ->  mailto:john@example.com?Subject=Ruby&Cc=jack@example.com
-    #    
+    #
     #    m3 = URI::MailTo.build({:to => 'listman@example.com', :headers => [['subject', 'subscribe']]})
     #    puts m3.to_s  ->  mailto:listman@example.com?subject=subscribe
     #
@@ -100,7 +103,7 @@ module URI
         if tmp[:headers].kind_of?(Array)
           tmp[:opaque] << tmp[:headers].collect { |x|
             if x.kind_of?(Array)
-              x[0] + '=' + x[1..-1].to_s
+              x[0] + '=' + x[1..-1].join
             else
               x.to_s
             end
@@ -135,7 +138,7 @@ module URI
       @headers = []
 
       if MAILTO_REGEXP =~ @opaque
-         if arg[-1]
+        if arg[-1]
           self.to = $1
           self.headers = $2
         else
@@ -155,11 +158,14 @@ module URI
     # E-mail headers set by the URL, as an Array of Arrays
     attr_reader :headers
 
+    # check the to +v+ component against either
+    # * URI::Parser Regexp for :OPAQUE
+    # * MAILBOX_PATTERN
     def check_to(v)
       return true unless v
       return true if v.size == 0
 
-      if OPAQUE !~ v || /\A#{MAILBOX_PATTERN}*\z/o !~ v
+      if parser.regexp[:OPAQUE] !~ v || /\A#{MAILBOX_PATTERN}*\z/o !~ v
         raise InvalidComponentError,
           "bad component(expected opaque component): #{v}"
       end
@@ -168,22 +174,27 @@ module URI
     end
     private :check_to
 
+    # private setter for to +v+
     def set_to(v)
       @to = v
     end
     protected :set_to
 
+    # setter for to +v+
     def to=(v)
       check_to(v)
       set_to(v)
       v
     end
 
+    # check the headers +v+ component against either
+    # * URI::Parser Regexp for :OPAQUE
+    # * HEADER_PATTERN
     def check_headers(v)
       return true unless v
       return true if v.size == 0
 
-      if OPAQUE !~ v || 
+      if parser.regexp[:OPAQUE] !~ v ||
           /\A(#{HEADER_PATTERN}(?:\&#{HEADER_PATTERN})*)\z/o !~ v
         raise InvalidComponentError,
           "bad component(expected opaque component): #{v}"
@@ -193,6 +204,7 @@ module URI
     end
     private :check_headers
 
+    # private setter for headers +v+
     def set_headers(v)
       @headers = []
       if v
@@ -203,19 +215,21 @@ module URI
     end
     protected :set_headers
 
+    # setter for headers +v+
     def headers=(v)
       check_headers(v)
       set_headers(v)
       v
     end
 
+    # Constructs String from URI
     def to_s
-      @scheme + ':' + 
-        if @to 
+      @scheme + ':' +
+        if @to
           @to
         else
           ''
-        end + 
+        end +
         if @headers.size > 0
           '?' + @headers.collect{|x| x.join('=')}.join('&')
         else
@@ -227,7 +241,7 @@ module URI
           ''
         end
     end
-    
+
     # Returns the RFC822 e-mail text equivalent of the URL, as a String.
     #
     # Example:
@@ -239,18 +253,18 @@ module URI
     #   # => "To: ruby-list@ruby-lang.org\nSubject: subscribe\nCc: myaddr\n\n\n"
     #
     def to_mailtext
-      to = URI::unescape(@to)
+      to = parser.unescape(@to)
       head = ''
       body = ''
       @headers.each do |x|
         case x[0]
         when 'body'
-          body = URI::unescape(x[1])
+          body = parser.unescape(x[1])
         when 'to'
-          to << ', ' + URI::unescape(x[1])
+          to << ', ' + parser.unescape(x[1])
         else
-          head << URI::unescape(x[0]).capitalize + ': ' +
-            URI::unescape(x[1])  + "\n"
+          head << parser.unescape(x[0]).capitalize + ': ' +
+            parser.unescape(x[1])  + "\n"
         end
       end