diff options
author | stomar <stomar@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2018-04-21 20:04:05 +0000 |
---|---|---|
committer | stomar <stomar@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2018-04-21 20:04:05 +0000 |
commit | 300b22dc225ece93394dafab231aae49ba12932f (patch) | |
tree | e4cb5b9cc0c652e4167135e842504ed6ceca6850 /lib | |
parent | c04881f94a1f9f00867f742481e097c4ce8f952a (diff) | |
download | ruby-300b22dc225ece93394dafab231aae49ba12932f.tar.gz |
Improve docs for URI library
* lib/uri/generic.rb: [DOC] fix invalid example code to make it
syntax highlighted; drop unnecessary `puts', `p'; adapt to current
inspect format without Object id; do not display unnecessary return
values in examples; fix or prevent unintended description lists;
fix broken RDoc; fix grammar and typos.
* lib/uri.rb: ditto.
* lib/uri/common.rb: ditto.
* lib/uri/file.rb: ditto.
* lib/uri/ftp.rb: ditto.
* lib/uri/http.rb: ditto.
* lib/uri/ldap.rb: ditto.
* lib/uri/mailto.rb: ditto.
* lib/uri/rfc2396_parser.rb: ditto.
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@63228 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'lib')
-rw-r--r-- | lib/uri.rb | 44 | ||||
-rw-r--r-- | lib/uri/common.rb | 107 | ||||
-rw-r--r-- | lib/uri/file.rb | 4 | ||||
-rw-r--r-- | lib/uri/ftp.rb | 62 | ||||
-rw-r--r-- | lib/uri/generic.rb | 330 | ||||
-rw-r--r-- | lib/uri/http.rb | 20 | ||||
-rw-r--r-- | lib/uri/ldap.rb | 72 | ||||
-rw-r--r-- | lib/uri/mailto.rb | 36 | ||||
-rw-r--r-- | lib/uri/rfc2396_parser.rb | 42 |
9 files changed, 344 insertions, 373 deletions
diff --git a/lib/uri.rb b/lib/uri.rb index b123fa8801..9b6bde91c0 100644 --- a/lib/uri.rb +++ b/lib/uri.rb @@ -1,34 +1,28 @@ # frozen_string_literal: false # URI is a module providing classes to handle Uniform Resource Identifiers -# (RFC2396[http://tools.ietf.org/html/rfc2396]) +# (RFC2396[http://tools.ietf.org/html/rfc2396]). # # == Features # -# * Uniform handling of handling URIs -# * Flexibility to introduce custom URI schemes +# * Uniform way of handling URIs. +# * Flexibility to introduce custom URI schemes. # * Flexibility to have an alternate URI::Parser (or just different patterns -# and regexp's) +# and regexp's). # # == Basic example # # require 'uri' # # uri = URI("http://foo.com/posts?id=30&limit=5#time=1305298413") -# #=> #<URI::HTTP:0x00000000b14880 -# URL:http://foo.com/posts?id=30&limit=5#time=1305298413> -# uri.scheme -# #=> "http" -# uri.host -# #=> "foo.com" -# uri.path -# #=> "/posts" -# uri.query -# #=> "id=30&limit=5" -# uri.fragment -# #=> "time=1305298413" -# -# uri.to_s -# #=> "http://foo.com/posts?id=30&limit=5#time=1305298413" +# #=> #<URI::HTTP http://foo.com/posts?id=30&limit=5#time=1305298413> +# +# uri.scheme #=> "http" +# uri.host #=> "foo.com" +# uri.path #=> "/posts" +# uri.query #=> "id=30&limit=5" +# uri.fragment #=> "time=1305298413" +# +# uri.to_s #=> "http://foo.com/posts?id=30&limit=5#time=1305298413" # # == Adding custom URIs # @@ -41,18 +35,18 @@ # #=> URI::RSYNC # # URI.scheme_list -# #=> {"FILE"=>URI::File, "FTP"=>URI::FTP, "HTTP"=>URI::HTTP, "HTTPS"=>URI::HTTPS, -# "LDAP"=>URI::LDAP, "LDAPS"=>URI::LDAPS, "MAILTO"=>URI::MailTo, -# "RSYNC"=>URI::RSYNC} +# #=> {"FILE"=>URI::File, "FTP"=>URI::FTP, "HTTP"=>URI::HTTP, +# # "HTTPS"=>URI::HTTPS, "LDAP"=>URI::LDAP, "LDAPS"=>URI::LDAPS, +# # "MAILTO"=>URI::MailTo, "RSYNC"=>URI::RSYNC} # # uri = URI("rsync://rsync.foo.com") -# #=> #<URI::RSYNC:0x00000000f648c8 URL:rsync://rsync.foo.com> +# #=> #<URI::RSYNC rsync://rsync.foo.com> # # == RFC References # -# A good place to view an RFC spec is http://www.ietf.org/rfc.html +# A good place to view an RFC spec is http://www.ietf.org/rfc.html. # -# Here is a list of all related RFC's. +# Here is a list of all related RFC's: # - RFC822[http://tools.ietf.org/html/rfc822] # - RFC1738[http://tools.ietf.org/html/rfc1738] # - RFC2255[http://tools.ietf.org/html/rfc2255] diff --git a/lib/uri/common.rb b/lib/uri/common.rb index 292708c152..7200f8b1d7 100644 --- a/lib/uri/common.rb +++ b/lib/uri/common.rb @@ -61,7 +61,7 @@ module URI module_function :make_components_hash end - # module for escaping unsafe characters with codes. + # Module for escaping unsafe characters with codes. module Escape # # == Synopsis @@ -90,13 +90,12 @@ module URI # require 'uri' # # enc_uri = URI.escape("http://example.com/?a=\11\15") - # p enc_uri # # => "http://example.com/?a=%09%0D" # - # p URI.unescape(enc_uri) + # URI.unescape(enc_uri) # # => "http://example.com/?a=\t\r" # - # p URI.escape("@?@!", "!?") + # URI.escape("@?@!", "!?") # # => "@%3F@%21" # def escape(*arg) @@ -112,7 +111,7 @@ module URI # == Args # # +str+:: - # Unescapes the string. + # String to unescape. # # == Description # @@ -125,10 +124,9 @@ module URI # require 'uri' # # enc_uri = URI.escape("http://example.com/?a=\11\15") - # p enc_uri # # => "http://example.com/?a=%09%0D" # - # p URI.unescape(enc_uri) + # URI.unescape(enc_uri) # # => "http://example.com/?a=\t\r" # def unescape(*arg) @@ -142,7 +140,7 @@ module URI include REGEXP @@schemes = {} - # Returns a Hash of the defined schemes + # Returns a Hash of the defined schemes. def self.scheme_list @@schemes end @@ -178,21 +176,21 @@ module URI # # Splits the string on following parts and returns array with result: # - # * Scheme - # * Userinfo - # * Host - # * Port - # * Registry - # * Path - # * Opaque - # * Query - # * Fragment + # * Scheme + # * Userinfo + # * Host + # * Port + # * Registry + # * Path + # * Opaque + # * Query + # * Fragment # # == Usage # # require 'uri' # - # p URI.split("http://www.ruby-lang.org/") + # URI.split("http://www.ruby-lang.org/") # # => ["http", nil, "www.ruby-lang.org", nil, nil, "/", nil, nil, nil] # def self.split(uri) @@ -215,7 +213,7 @@ module URI # # == Raises # - # URI::InvalidURIError + # URI::InvalidURIError:: # Raised if URI given is not a correct one. # # == Usage @@ -223,11 +221,10 @@ module URI # require 'uri' # # uri = URI.parse("http://www.ruby-lang.org/") - # p uri - # # => #<URI::HTTP:0x202281be URL:http://www.ruby-lang.org/> - # p uri.scheme + # # => #<URI::HTTP http://www.ruby-lang.org/> + # uri.scheme # # => "http" - # p uri.host + # uri.host # # => "www.ruby-lang.org" # # It's recommended to first ::escape the provided +uri_str+ if there are any @@ -255,21 +252,20 @@ module URI # # require 'uri' # - # p URI.join("http://example.com/","main.rbx") - # # => #<URI::HTTP:0x2022ac02 URL:http://example.com/main.rbx> + # URI.join("http://example.com/","main.rbx") + # # => #<URI::HTTP http://example.com/main.rbx> # - # p URI.join('http://example.com', 'foo') - # # => #<URI::HTTP:0x01ab80a0 URL:http://example.com/foo> + # URI.join('http://example.com', 'foo') + # # => #<URI::HTTP http://example.com/foo> # - # p URI.join('http://example.com', '/foo', '/bar') - # # => #<URI::HTTP:0x01aaf0b0 URL:http://example.com/bar> + # URI.join('http://example.com', '/foo', '/bar') + # # => #<URI::HTTP http://example.com/bar> # - # p URI.join('http://example.com', '/foo', 'bar') - # # => #<URI::HTTP:0x801a92af0 URL:http://example.com/bar> - # - # p URI.join('http://example.com', '/foo/', 'bar') - # # => #<URI::HTTP:0x80135a3a0 URL:http://example.com/foo/bar> + # URI.join('http://example.com', '/foo', 'bar') + # # => #<URI::HTTP http://example.com/bar> # + # URI.join('http://example.com', '/foo/', 'bar') + # # => #<URI::HTTP http://example.com/foo/bar> # def self.join(*str) RFC3986_PARSER.join(*str) @@ -285,7 +281,7 @@ module URI # +str+:: # String to extract URIs from. # +schemes+:: - # Limit URI matching to a specific schemes. + # Limit URI matching to specific schemes. # # == Description # @@ -316,6 +312,7 @@ module URI # whose scheme is one of the match_schemes. # # == Description + # # Returns a Regexp object which matches to URI-like strings. # The Regexp object returned by this method includes arbitrary # number of capture group (parentheses). Never rely on it's number. @@ -328,7 +325,7 @@ module URI # html_string.slice(URI.regexp) # # # remove ftp URIs - # html_string.sub(URI.regexp(['ftp']) + # html_string.sub(URI.regexp(['ftp']), '') # # # You should not rely on the number of parentheses # html_string.scan(URI.regexp) do |*matches| @@ -360,7 +357,7 @@ module URI HTML5ASCIIINCOMPAT = defined? Encoding::UTF_7 ? [Encoding::UTF_7, Encoding::UTF_16BE, Encoding::UTF_16LE, Encoding::UTF_32BE, Encoding::UTF_32LE] : [] # :nodoc: - # Encode given +str+ to URL-encoded form data. + # Encodes given +str+ to URL-encoded form data. # # This method doesn't convert *, -, ., 0-9, A-Z, _, a-z, but does convert SP # (ASCII space) to + and converts others to %XX. @@ -368,9 +365,9 @@ module URI # If +enc+ is given, convert +str+ to the encoding before percent encoding. # # This is an implementation of - # http://www.w3.org/TR/2013/CR-html5-20130806/forms.html#url-encoded-form-data + # http://www.w3.org/TR/2013/CR-html5-20130806/forms.html#url-encoded-form-data. # - # See URI.decode_www_form_component, URI.encode_www_form + # See URI.decode_www_form_component, URI.encode_www_form. def self.encode_www_form_component(str, enc=nil) str = str.to_s.dup if str.encoding != Encoding::ASCII_8BIT @@ -384,17 +381,17 @@ module URI str.force_encoding(Encoding::US_ASCII) end - # Decode given +str+ of URL-encoded form data. + # Decodes given +str+ of URL-encoded form data. # # This decodes + to SP. # - # See URI.encode_www_form_component, URI.decode_www_form + # See URI.encode_www_form_component, URI.decode_www_form. def self.decode_www_form_component(str, enc=Encoding::UTF_8) raise ArgumentError, "invalid %-encoding (#{str})" if /%(?!\h\h)/ =~ str str.b.gsub(/\+|%\h\h/, TBLDECWWWCOMP_).force_encoding(enc) end - # Generate URL-encoded form data from given +enum+. + # Generates URL-encoded form data from given +enum+. # # This generates application/x-www-form-urlencoded data defined in HTML5 # from given an Enumerable object. @@ -402,7 +399,7 @@ module URI # This internally uses URI.encode_www_form_component(str). # # This method doesn't convert the encoding of given items, so convert them - # before call this method if you want to send data as other than original + # before calling this method if you want to send data as other than original # encoding or mixed encoding data. (Strings which are encoded in an HTML5 # ASCII incompatible encoding are converted to UTF-8.) # @@ -420,7 +417,7 @@ module URI # URI.encode_www_form([["q", "ruby"], ["q", "perl"], ["lang", "en"]]) # #=> "q=ruby&q=perl&lang=en" # - # See URI.encode_www_form_component, URI.decode_www_form + # See URI.encode_www_form_component, URI.decode_www_form. def self.encode_www_form(enum, enc=nil) enum.map do |k,v| if v.nil? @@ -441,22 +438,22 @@ module URI end.join('&') end - # Decode URL-encoded form data from given +str+. + # Decodes URL-encoded form data from given +str+. # # This decodes application/x-www-form-urlencoded data - # and returns array of key-value array. + # and returns an array of key-value arrays. # - # This refers http://url.spec.whatwg.org/#concept-urlencoded-parser , - # so this supports only &-separator, don't support ;-separator. + # This refers http://url.spec.whatwg.org/#concept-urlencoded-parser, + # so this supports only &-separator, and doesn't support ;-separator. # # ary = URI.decode_www_form("a=1&a=2&b=3") - # p ary #=> [['a', '1'], ['a', '2'], ['b', '3']] - # p ary.assoc('a').last #=> '1' - # p ary.assoc('b').last #=> '3' - # p ary.rassoc('a').last #=> '2' - # p Hash[ary] # => {"a"=>"2", "b"=>"3"} + # ary #=> [['a', '1'], ['a', '2'], ['b', '3']] + # ary.assoc('a').last #=> '1' + # ary.assoc('b').last #=> '3' + # ary.rassoc('a').last #=> '2' + # Hash[ary] #=> {"a"=>"2", "b"=>"3"} # - # See URI.decode_www_form_component, URI.encode_www_form + # See URI.decode_www_form_component, URI.encode_www_form. def self.decode_www_form(str, enc=Encoding::UTF_8, separator: '&', use__charset_: false, isindex: false) raise ArgumentError, "the input of #{self.name}.#{__method__} must be ASCII only string" unless str.ascii_only? ary = [] @@ -734,7 +731,7 @@ end # module URI module Kernel # - # Returns +uri+ converted to a URI object. + # Returns +uri+ converted to an URI object. # def URI(uri) if uri.is_a?(URI::Generic) diff --git a/lib/uri/file.rb b/lib/uri/file.rb index ffdd4aaa02..6c959be50d 100644 --- a/lib/uri/file.rb +++ b/lib/uri/file.rb @@ -49,9 +49,9 @@ module URI super(tmp) end - # protected setter for the host component +v+ + # Protected setter for the host component +v+. # - # see also URI::Generic.host= + # See also URI::Generic.host=. # def set_host(v) v = "" if v.nil? || v == "localhost" diff --git a/lib/uri/ftp.rb b/lib/uri/ftp.rb index 90c1403ce6..bc9c9c3c65 100644 --- a/lib/uri/ftp.rb +++ b/lib/uri/ftp.rb @@ -21,11 +21,11 @@ module URI # http://tools.ietf.org/html/draft-hoffman-ftp-uri-04 # class FTP < Generic - # A Default port of 21 for URI::FTP + # A Default port of 21 for URI::FTP. DEFAULT_PORT = 21 # - # An Array of the available components for URI::FTP + # An Array of the available components for URI::FTP. # COMPONENT = [ :scheme, @@ -34,7 +34,7 @@ module URI ].freeze # - # Typecode is "a", "i" or "d". + # Typecode is "a", "i", or "d". # # * "a" indicates a text file (the FTP command was ASCII) # * "i" indicates a binary file (FTP command IMAGE) @@ -42,8 +42,7 @@ module URI # TYPECODE = ['a', 'i', 'd'].freeze - # Typecode prefix - # ';type=' + # Typecode prefix ";type=". TYPECODE_PREFIX = ';type='.freeze def self.new2(user, password, host, port, path, @@ -71,27 +70,29 @@ module URI # # Creates a new URI::FTP object from components, with syntax checking. # - # The components accepted are +userinfo+, +host+, +port+, +path+ and + # The components accepted are +userinfo+, +host+, +port+, +path+, and # +typecode+. # # 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, typecode] + # If an Array is used, the components must be passed in the + # order <code>[userinfo, host, port, path, typecode]</code>. # # If the path supplied is absolute, it will be escaped in order to - # make it absolute in the URI. Examples: + # make it absolute in the URI. + # + # Examples: # # require 'uri' # - # uri = URI::FTP.build(['user:password', 'ftp.example.com', nil, + # uri1 = URI::FTP.build(['user:password', 'ftp.example.com', nil, # '/path/file.zip', 'i']) - # puts uri.to_s -> ftp://user:password@ftp.example.com/%2Fpath/file.zip;type=i + # uri1.to_s # => "ftp://user:password@ftp.example.com/%2Fpath/file.zip;type=i" # # uri2 = URI::FTP.build({:host => 'ftp.example.com', # :path => 'ruby/src'}) - # puts uri2.to_s -> ftp://ftp.example.com/ruby/src + # uri2.to_s # => "ftp://ftp.example.com/ruby/src" # def self.build(args) @@ -128,7 +129,7 @@ module URI # required by RFC1738; instead it is treated as per RFC2396. # # Arguments are +scheme+, +userinfo+, +host+, +port+, +registry+, +path+, - # +opaque+, +query+ and +fragment+, in that order. + # +opaque+, +query+, and +fragment+, in that order. # def initialize(scheme, userinfo, host, port, registry, @@ -155,13 +156,13 @@ module URI end end - # typecode accessor + # typecode accessor. # - # see URI::FTP::COMPONENT + # See URI::FTP::COMPONENT. attr_reader :typecode - # validates typecode +v+, - # returns a +true+ or +false+ boolean + # Validates typecode +v+, + # returns +true+ or +false+. # def check_typecode(v) if TYPECODE.include?(v) @@ -173,9 +174,9 @@ module URI end private :check_typecode - # Private setter for the typecode +v+ + # Private setter for the typecode +v+. # - # see also URI::FTP.typecode= + # See also URI::FTP.typecode=. # def set_typecode(v) @typecode = v @@ -190,21 +191,20 @@ module URI # # == Description # - # public setter for the typecode +v+. - # (with validation) + # Public setter for the typecode +v+ + # (with validation). # - # see also URI::FTP.check_typecode + # See also URI::FTP.check_typecode. # # == Usage # # require 'uri' # # uri = URI.parse("ftp://john@ftp.example.com/my_file.img") - # #=> #<URI::FTP:0x00000000923650 URL:ftp://john@ftp.example.com/my_file.img> + # #=> #<URI::FTP ftp://john@ftp.example.com/my_file.img> # uri.typecode = "i" - # # => "i" # uri - # #=> #<URI::FTP:0x00000000923650 URL:ftp://john@ftp.example.com/my_file.img;type=i> + # #=> #<URI::FTP ftp://john@ftp.example.com/my_file.img;type=i> # def typecode=(typecode) check_typecode(typecode) @@ -226,29 +226,29 @@ module URI # RFC 1738 specifically states that the path for an FTP URI does not # include the / which separates the URI path from the URI host. Example: # - # +ftp://ftp.example.com/pub/ruby+ + # <code>ftp://ftp.example.com/pub/ruby</code> # # The above URI indicates that the client should connect to - # ftp.example.com then cd pub/ruby from the initial login directory. + # ftp.example.com then cd to pub/ruby from the initial login directory. # # If you want to cd to an absolute directory, you must include an # escaped / (%2F) in the path. Example: # - # +ftp://ftp.example.com/%2Fpub/ruby+ + # <code>ftp://ftp.example.com/%2Fpub/ruby</code> # - # This method will then return "/pub/ruby" + # This method will then return "/pub/ruby". # def path return @path.sub(/^\//,'').sub(/^%2F/,'/') end - # Private setter for the path of the URI::FTP + # Private setter for the path of the URI::FTP. def set_path(v) super("/" + v.sub(/^\//, "%2F")) end protected :set_path - # Returns a String representation of the URI::FTP + # Returns a String representation of the URI::FTP. def to_s save_path = nil if @typecode diff --git a/lib/uri/generic.rb b/lib/uri/generic.rb index 7a05438f88..4791151965 100644 --- a/lib/uri/generic.rb +++ b/lib/uri/generic.rb @@ -23,26 +23,26 @@ module URI include URI # - # A Default port of nil for URI::Generic + # A Default port of nil for URI::Generic. # DEFAULT_PORT = nil # - # Returns default port + # Returns default port. # def self.default_port self::DEFAULT_PORT end # - # Returns default port + # Returns default port. # def default_port self.class.default_port end # - # An Array of the available components for URI::Generic + # An Array of the available components for URI::Generic. # COMPONENT = [ :scheme, @@ -68,14 +68,13 @@ module URI # # == Synopsis # - # See #new + # See ::new. # # == Description # # At first, tries to create a new URI::Generic instance using # URI::Generic::build. But, if exception URI::InvalidComponentError is raised, - # then it URI::Escape.escape all URI components and tries again. - # + # then it does URI::Escape.escape all URI components and tries again. # def self.build2(args) begin @@ -106,14 +105,14 @@ module URI # # == Synopsis # - # See #new + # See ::new. # # == Description # # Creates a new URI::Generic instance from components of URI::Generic # with check. Components are: scheme, userinfo, host, port, registry, path, - # opaque, query and fragment. You can provide arguments either by an Array or a Hash. - # See #new for hash keys to use or for order of array items. + # opaque, query, and fragment. You can provide arguments either by an Array or a Hash. + # See ::new for hash keys to use or for order of array items. # def self.build(args) if args.kind_of?(Array) && @@ -137,31 +136,32 @@ module URI tmp << true return self.new(*tmp) end + # # == Args # # +scheme+:: # Protocol scheme, i.e. 'http','ftp','mailto' and so on. # +userinfo+:: - # User name and password, i.e. 'sdmitry:bla' + # User name and password, i.e. 'sdmitry:bla'. # +host+:: - # Server host name + # Server host name. # +port+:: - # Server port + # Server port. # +registry+:: # Registry of naming authorities. # +path+:: - # Path on server + # Path on server. # +opaque+:: - # Opaque part + # Opaque part. # +query+:: - # Query data + # Query data. # +fragment+:: - # A part of URI after '#' sign + # Part of the URI after '#' character. # +parser+:: - # Parser for internal use [URI::DEFAULT_PARSER by default] + # Parser for internal use [URI::DEFAULT_PARSER by default]. # +arg_check+:: - # Check arguments [false by default] + # Check arguments [false by default]. # # == Description # @@ -215,38 +215,37 @@ module URI end # - # returns the scheme component of the URI. + # Returns the scheme component of the URI. # # URI("http://foo/bar/baz").scheme #=> "http" # attr_reader :scheme - # returns the host component of the URI. + # Returns the host component of the URI. # # URI("http://foo/bar/baz").host #=> "foo" # - # It returns nil if no host component. + # It returns nil if no host component exists. # # URI("mailto:foo@example.org").host #=> nil # - # The component doesn't contains the port number. + # The component does not contain the port number. # # URI("http://foo:8080/bar/baz").host #=> "foo" # - # Since IPv6 addresses are wrapped by brackets in URIs, - # this method returns IPv6 addresses wrapped by brackets. - # This form is not appropriate to pass socket methods such as TCPSocket.open. - # If unwrapped host names are required, use "hostname" method. + # Since IPv6 addresses are wrapped with brackets in URIs, + # this method returns IPv6 addresses wrapped with brackets. + # This form is not appropriate to pass to socket methods such as TCPSocket.open. + # If unwrapped host names are required, use the #hostname method. # - # URI("http://[::1]/bar/baz").host #=> "[::1]" + # URI("http://[::1]/bar/baz").host #=> "[::1]" # URI("http://[::1]/bar/baz").hostname #=> "::1" # attr_reader :host - # returns the port component of the URI. - # - # URI("http://foo/bar/baz").port #=> "80" + # Returns the port component of the URI. # + # URI("http://foo/bar/baz").port #=> "80" # URI("http://foo:8080/bar/baz").port #=> "8080" # attr_reader :port @@ -255,13 +254,13 @@ module URI nil end - # returns the path component of the URI. + # Returns the path component of the URI. # # URI("http://foo/bar/baz").path #=> "/bar/baz" # attr_reader :path - # returns the query component of the URI. + # Returns the query component of the URI. # # URI("http://foo/bar/baz?search=FooBar").query #=> "search=FooBar" # @@ -278,15 +277,15 @@ module URI # attr_reader :opaque - # returns the fragment component of the URI. + # Returns the fragment component of the URI. # # URI("http://foo/bar/baz?search=FooBar#ponies").fragment #=> "ponies" # attr_reader :fragment - # returns the parser to be used. + # Returns the parser to be used. # - # Unless a URI::Parser is defined, then DEFAULT_PARSER is used. + # Unless a URI::Parser is defined, DEFAULT_PARSER is used. # def parser if !defined?(@parser) || !@parser @@ -296,7 +295,8 @@ module URI end end - # replace self by other URI object + # Replaces self by other URI object. + # def replace!(oth) if self.class != oth.class raise ArgumentError, "expected #{self.class} object" @@ -316,7 +316,7 @@ module URI end # - # check the scheme +v+ component against the URI::Parser Regexp for :SCHEME + # Checks the scheme +v+ component against the URI::Parser Regexp for :SCHEME. # def check_scheme(v) if v && parser.regexp[:SCHEME] !~ v @@ -328,9 +328,9 @@ module URI end private :check_scheme - # protected setter for the scheme component +v+ + # Protected setter for the scheme component +v+. # - # see also URI::Generic.scheme= + # See also URI::Generic.scheme=. # def set_scheme(v) @scheme = v&.downcase @@ -345,10 +345,10 @@ module URI # # == Description # - # public setter for the scheme component +v+. - # (with validation) + # Public setter for the scheme component +v+ + # (with validation). # - # see also URI::Generic.check_scheme + # See also URI::Generic.check_scheme. # # == Usage # @@ -356,9 +356,7 @@ module URI # # uri = URI.parse("http://my.example.com") # uri.scheme = "https" - # # => "https" - # uri - # #=> #<URI::HTTP:0x000000008e89e8 URL:https://my.example.com> + # uri.to_s #=> "https://my.example.com" # def scheme=(v) check_scheme(v) @@ -367,13 +365,13 @@ module URI end # - # check the +user+ and +password+. + # Checks the +user+ and +password+. # # If +password+ is not provided, then +user+ is # split, using URI::Generic.split_userinfo, to # pull +user+ and +password. # - # see also URI::Generic.check_user, URI::Generic.check_password + # See also URI::Generic.check_user, URI::Generic.check_password. # def check_userinfo(user, password = nil) if !password @@ -387,8 +385,8 @@ module URI private :check_userinfo # - # check the user +v+ component for RFC2396 compliance - # and against the URI::Parser Regexp for :USERINFO + # Checks the user +v+ component for RFC2396 compliance + # and against the URI::Parser Regexp for :USERINFO. # # Can not have a registry or opaque component defined, # with a user component defined. @@ -411,8 +409,8 @@ module URI private :check_user # - # check the password +v+ component for RFC2396 compliance - # and against the URI::Parser Regexp for :USERINFO + # Checks the password +v+ component for RFC2396 compliance + # and against the URI::Parser Regexp for :USERINFO. # # Can not have a registry or opaque component defined, # with a user component defined. @@ -439,7 +437,7 @@ module URI private :check_password # - # Sets userinfo, argument is string like 'name:pass' + # Sets userinfo, argument is string like 'name:pass'. # def userinfo=(userinfo) if userinfo.nil? @@ -458,10 +456,10 @@ module URI # # == Description # - # public setter for the +user+ component. - # (with validation) + # Public setter for the +user+ component + # (with validation). # - # see also URI::Generic.check_user + # See also URI::Generic.check_user. # # == Usage # @@ -469,9 +467,7 @@ module URI # # uri = URI.parse("http://john:S3nsit1ve@my.example.com") # uri.user = "sam" - # # => "sam" - # uri - # #=> #<URI::HTTP:0x00000000881d90 URL:http://sam:V3ry_S3nsit1ve@my.example.com> + # uri.to_s #=> "http://sam:V3ry_S3nsit1ve@my.example.com" # def user=(user) check_user(user) @@ -487,10 +483,10 @@ module URI # # == Description # - # public setter for the +password+ component. - # (with validation) + # Public setter for the +password+ component + # (with validation). # - # see also URI::Generic.check_password + # See also URI::Generic.check_password. # # == Usage # @@ -498,9 +494,7 @@ module URI # # uri = URI.parse("http://john:S3nsit1ve@my.example.com") # uri.password = "V3ry_S3nsit1ve" - # # => "V3ry_S3nsit1ve" - # uri - # #=> #<URI::HTTP:0x00000000881d90 URL:http://john:V3ry_S3nsit1ve@my.example.com> + # uri.to_s #=> "http://john:V3ry_S3nsit1ve@my.example.com" # def password=(password) check_password(password) @@ -508,10 +502,10 @@ module URI # returns password end - # protect setter for the +user+ component, and +password+ if available. - # (with validation) + # Protected setter for the +user+ component, and +password+ if available + # (with validation). # - # see also URI::Generic.userinfo= + # See also URI::Generic.userinfo=. # def set_userinfo(user, password = nil) unless password @@ -524,9 +518,9 @@ module URI end protected :set_userinfo - # protected setter for the user component +v+ + # Protected setter for the user component +v+. # - # see also URI::Generic.user= + # See also URI::Generic.user=. # def set_user(v) set_userinfo(v, @password) @@ -534,9 +528,9 @@ module URI end protected :set_user - # protected setter for the password component +v+ + # Protected setter for the password component +v+. # - # see also URI::Generic.password= + # See also URI::Generic.password=. # def set_password(v) @password = v @@ -544,8 +538,8 @@ module URI end protected :set_password - # returns the userinfo +ui+ as user, password - # if properly formatted as 'user:password' + # Returns the userinfo +ui+ as <code>[user, password]</code> + # if properly formatted as 'user:password'. def split_userinfo(ui) return nil, nil unless ui user, password = ui.split(':', 2) @@ -554,13 +548,13 @@ module URI end private :split_userinfo - # escapes 'user:password' +v+ based on RFC 1738 section 3.1 + # Escapes 'user:password' +v+ based on RFC 1738 section 3.1. def escape_userpass(v) parser.escape(v, /[@:\/]/o) # RFC 1738 section 3.1 #/ end private :escape_userpass - # returns the userinfo, either as 'user' or 'user:password' + # Returns the userinfo, either as 'user' or 'user:password'. def userinfo if @user.nil? nil @@ -571,19 +565,19 @@ module URI end end - # returns the user component + # Returns the user component. def user @user end - # returns the password component + # Returns the password component. def password @password end # - # check the host +v+ component for RFC2396 compliance - # and against the URI::Parser Regexp for :HOST + # Checks the host +v+ component for RFC2396 compliance + # and against the URI::Parser Regexp for :HOST. # # Can not have a registry or opaque component defined, # with a host component defined. @@ -603,9 +597,9 @@ module URI end private :check_host - # protected setter for the host component +v+ + # Protected setter for the host component +v+. # - # see also URI::Generic.host= + # See also URI::Generic.host=. # def set_host(v) @host = v @@ -620,10 +614,10 @@ module URI # # == Description # - # public setter for the host component +v+. - # (with validation) + # Public setter for the host component +v+ + # (with validation). # - # see also URI::Generic.check_host + # See also URI::Generic.check_host. # # == Usage # @@ -631,9 +625,7 @@ module URI # # uri = URI.parse("http://my.example.com") # uri.host = "foo.com" - # # => "foo.com" - # uri - # #=> #<URI::HTTP:0x000000008e89e8 URL:http://foo.com> + # uri.to_s #=> "http://foo.com" # def host=(v) check_host(v) @@ -641,32 +633,31 @@ module URI v end - # extract the host part of the URI and unwrap brackets for IPv6 addresses. + # Extract the host part of the URI and unwrap brackets for IPv6 addresses. # - # This method is same as URI::Generic#host except + # This method is the same as URI::Generic#host except # brackets for IPv6 (and future IP) addresses are removed. # - # u = URI("http://[::1]/bar") - # p u.hostname #=> "::1" - # p u.host #=> "[::1]" + # uri = URI("http://[::1]/bar") + # uri.hostname #=> "::1" + # uri.host #=> "[::1]" # def hostname v = self.host /\A\[(.*)\]\z/ =~ v ? $1 : v end - # set the host part of the URI as the argument with brackets for IPv6 addresses. + # Sets the host part of the URI as the argument with brackets for IPv6 addresses. # - # This method is same as URI::Generic#host= except - # the argument can be bare IPv6 address. + # This method is the same as URI::Generic#host= except + # the argument can be a bare IPv6 address. # - # u = URI("http://foo/bar") - # p u.to_s #=> "http://foo/bar" - # u.hostname = "::1" - # p u.to_s #=> "http://[::1]/bar" + # uri = URI("http://foo/bar") + # uri.hostname = "::1" + # uri.to_s #=> "http://[::1]/bar" # - # If the argument seems IPv6 address, - # it is wrapped by brackets. + # If the argument seems to be an IPv6 address, + # it is wrapped with brackets. # def hostname=(v) v = "[#{v}]" if /\A\[.*\]\z/ !~ v && /:/ =~ v @@ -674,8 +665,8 @@ module URI end # - # check the port +v+ component for RFC2396 compliance - # and against the URI::Parser Regexp for :PORT + # Checks the port +v+ component for RFC2396 compliance + # and against the URI::Parser Regexp for :PORT. # # Can not have a registry or opaque component defined, # with a port component defined. @@ -695,9 +686,9 @@ module URI end private :check_port - # protected setter for the port component +v+ + # Protected setter for the port component +v+. # - # see also URI::Generic.port= + # See also URI::Generic.port=. # def set_port(v) v = v.empty? ? nil : v.to_i unless !v || v.kind_of?(Integer) @@ -713,10 +704,10 @@ module URI # # == Description # - # public setter for the port component +v+. - # (with validation) + # Public setter for the port component +v+ + # (with validation). # - # see also URI::Generic.check_port + # See also URI::Generic.check_port. # # == Usage # @@ -724,9 +715,7 @@ module URI # # uri = URI.parse("http://my.example.com") # uri.port = 8080 - # # => 8080 - # uri - # #=> #<URI::HTTP:0x000000008e89e8 URL:http://my.example.com:8080> + # uri.to_s #=> "http://my.example.com:8080" # def port=(v) check_port(v) @@ -749,9 +738,9 @@ module URI end # - # check the path +v+ component for RFC2396 compliance + # Checks the path +v+ component for RFC2396 compliance # and against the URI::Parser Regexp - # for :ABS_PATH and :REL_PATH + # for :ABS_PATH and :REL_PATH. # # Can not have a opaque component defined, # with a path component defined. @@ -784,9 +773,9 @@ module URI end private :check_path - # protected setter for the path component +v+ + # Protected setter for the path component +v+. # - # see also URI::Generic.path= + # See also URI::Generic.path=. # def set_path(v) @path = v @@ -801,10 +790,10 @@ module URI # # == Description # - # public setter for the path component +v+. - # (with validation) + # Public setter for the path component +v+ + # (with validation). # - # see also URI::Generic.check_path + # See also URI::Generic.check_path. # # == Usage # @@ -812,9 +801,7 @@ module URI # # uri = URI.parse("http://my.example.com/pub/files") # uri.path = "/faq/" - # # => "/faq/" - # uri - # #=> #<URI::HTTP:0x000000008e89e8 URL:http://my.example.com/faq/> + # uri.to_s #=> "http://my.example.com/faq/" # def path=(v) check_path(v) @@ -830,7 +817,7 @@ module URI # # == Description # - # public setter for the query component +v+. + # Public setter for the query component +v+. # # == Usage # @@ -838,9 +825,7 @@ module URI # # uri = URI.parse("http://my.example.com/?id=25") # uri.query = "id=1" - # # => "id=1" - # uri - # #=> #<URI::HTTP:0x000000008e89e8 URL:http://my.example.com/?id=1> + # uri.to_s #=> "http://my.example.com/?id=1" # def query=(v) return @query = nil unless v @@ -857,10 +842,10 @@ module URI end # - # check the opaque +v+ component for RFC2396 compliance and - # against the URI::Parser Regexp for :OPAQUE + # Checks the opaque +v+ component for RFC2396 compliance and + # against the URI::Parser Regexp for :OPAQUE. # - # Can not have a host, port, user or path component defined, + # Can not have a host, port, user, or path component defined, # with an opaque component defined. # def check_opaque(v) @@ -881,9 +866,9 @@ module URI end private :check_opaque - # protected setter for the opaque component +v+ + # Protected setter for the opaque component +v+. # - # see also URI::Generic.opaque= + # See also URI::Generic.opaque=. # def set_opaque(v) @opaque = v @@ -898,10 +883,10 @@ module URI # # == Description # - # public setter for the opaque component +v+. - # (with validation) + # Public setter for the opaque component +v+ + # (with validation). # - # see also URI::Generic.check_opaque + # See also URI::Generic.check_opaque. # def opaque=(v) check_opaque(v) @@ -910,7 +895,7 @@ module URI end # - # check the fragment +v+ component against the URI::Parser Regexp for :FRAGMENT + # Checks the fragment +v+ component against the URI::Parser Regexp for :FRAGMENT. # # # == Args @@ -920,8 +905,8 @@ module URI # # == Description # - # public setter for the fragment component +v+. - # (with validation) + # Public setter for the fragment component +v+ + # (with validation). # # == Usage # @@ -929,9 +914,7 @@ module URI # # uri = URI.parse("http://my.example.com/?id=25#time=1305212049") # uri.fragment = "time=1305212086" - # # => "time=1305212086" - # uri - # #=> #<URI::HTTP:0x000000007a81f8 URL:http://my.example.com/?id=25#time=1305212086> + # uri.to_s #=> "http://my.example.com/?id=25#time=1305212086" # def fragment=(v) return @fragment = nil unless v @@ -947,25 +930,23 @@ module URI end # - # Returns true if URI is hierarchical + # Returns true if URI is hierarchical. # # == Description # - # URI has components listed in order of decreasing signficance from left to right - # see RFC3986 https://tools.ietf.org/html/rfc3986 1.2.3 + # URI has components listed in order of decreasing significance from left to right, + # see RFC3986 https://tools.ietf.org/html/rfc3986 1.2.3. # # == Usage # # require 'uri' # # uri = URI.parse("http://my.example.com/") - # => #<URI::HTTP http://my.example.com/> # uri.hierarchical? - # # => true + # #=> true # uri = URI.parse("mailto:joe@example.com") - # => #<URI::MailTo mailto:joe@example.com> # uri.hierarchical? - # # => false + # #=> false # def hierarchical? if @path @@ -976,7 +957,7 @@ module URI end # - # Returns true if URI has a scheme (e.g. http:// or https://) specified + # Returns true if URI has a scheme (e.g. http:// or https://) specified. # def absolute? if @scheme @@ -988,14 +969,14 @@ module URI alias absolute absolute? # - # Returns true if URI does not have a scheme (e.g. http:// or https://) specified + # Returns true if URI does not have a scheme (e.g. http:// or https://) specified. # def relative? !absolute? end # - # returns an Array of the path split on '/' + # Returns an Array of the path split on '/'. # def split_path(path) path.split("/", -1) @@ -1077,7 +1058,7 @@ module URI # # == Description # - # Destructive form of #merge + # Destructive form of #merge. # # == Usage # @@ -1085,8 +1066,7 @@ module URI # # uri = URI.parse("http://my.example.com") # uri.merge!("/main.rbx?page=1") - # p uri - # # => #<URI::HTTP:0x2021f3b0 URL:http://my.example.com/main.rbx?page=1> + # uri.to_s # => "http://my.example.com/main.rbx?page=1" # def merge!(oth) t = merge(oth) @@ -1106,15 +1086,15 @@ module URI # # == Description # - # Merges two URI's. + # Merges two URIs. # # == Usage # # require 'uri' # # uri = URI.parse("http://my.example.com") - # p uri.merge("/main.rbx?page=1") - # # => #<URI::HTTP:0x2021f3b0 URL:http://my.example.com/main.rbx?page=1> + # uri.merge("/main.rbx?page=1") + # # => "http://my.example.com/main.rbx?page=1" # def merge(oth) rel = parser.send(:convert_to_uri, oth) @@ -1259,15 +1239,15 @@ module URI # # == Description # - # Calculates relative path from oth to self + # Calculates relative path from oth to self. # # == Usage # # require 'uri' # # uri = URI.parse('http://my.example.com/main.rbx?page=1') - # p uri.route_from('http://my.example.com') - # #=> #<URI::Generic:0x20218858 URL:/main.rbx?page=1> + # uri.route_from('http://my.example.com') + # #=> #<URI::Generic /main.rbx?page=1> # def route_from(oth) # you can modify `rel', but can not `oth'. @@ -1299,15 +1279,15 @@ module URI # # == Description # - # Calculates relative path to oth from self + # Calculates relative path to oth from self. # # == Usage # # require 'uri' # # uri = URI.parse('http://my.example.com') - # p uri.route_to('http://my.example.com/main.rbx?page=1') - # #=> #<URI::Generic:0x2020c2f6 URL:/main.rbx?page=1> + # uri.route_to('http://my.example.com/main.rbx?page=1') + # #=> #<URI::Generic /main.rbx?page=1> # def route_to(oth) parser.send(:convert_to_uri, oth).route_from(self) @@ -1333,7 +1313,7 @@ module URI end # - # Destructive version of #normalize + # Destructive version of #normalize. # def normalize! if path&.empty? @@ -1348,7 +1328,7 @@ module URI end # - # Constructs String from URI + # Constructs String from URI. # def to_s str = ''.dup @@ -1388,7 +1368,7 @@ module URI end # - # Compares two URIs + # Compares two URIs. # def ==(oth) if self.class == oth.class @@ -1421,7 +1401,7 @@ module URI =end - # returns an Array of the components defined from the COMPONENT Array + # Returns an Array of the components defined from the COMPONENT Array. def component_ary component.collect do |x| self.send(x) @@ -1432,18 +1412,18 @@ module URI # == Args # # +components+:: - # Multiple Symbol arguments defined in URI::HTTP + # Multiple Symbol arguments defined in URI::HTTP. # # == Description # - # Selects specified components from URI + # Selects specified components from URI. # # == Usage # # require 'uri' # # uri = URI.parse('http://myuser:mypass@my.example.com/test.rbx') - # p uri.select(:userinfo, :host, :path) + # uri.select(:userinfo, :host, :path) # # => ["myuser:mypass", "my.example.com", "/test.rbx"] # def select(*components) @@ -1469,8 +1449,8 @@ module URI # # == Description # - # attempts to parse other URI +oth+, - # returns [parsed_oth, self] + # Attempts to parse other URI +oth+, + # returns [parsed_oth, self]. # # == Usage # @@ -1478,7 +1458,7 @@ module URI # # uri = URI.parse("http://my.example.com") # uri.coerce("http://foo.com") - # #=> [#<URI::HTTP:0x00000000bcb028 URL:http://foo.com/>, #<URI::HTTP:0x00000000d92178 URL:http://my.example.com>] + # #=> [#<URI::HTTP http://foo.com>, #<URI::HTTP http://my.example.com>] # def coerce(oth) case oth @@ -1491,15 +1471,15 @@ module URI return oth, self end - # returns a proxy URI. + # Returns a proxy URI. # The proxy URI is obtained from environment variables such as http_proxy, # ftp_proxy, no_proxy, etc. # If there is no proper proxy, nil is returned. # - # If the optional parameter, +env+, is specified, it is used instead of ENV. + # If the optional parameter +env+ is specified, it is used instead of ENV. # # Note that capitalized variables (HTTP_PROXY, FTP_PROXY, NO_PROXY, etc.) - # are examined too. + # are examined, too. # # But http_proxy and HTTP_PROXY is treated specially under CGI environment. # It's because HTTP_PROXY may be set by Proxy: header. diff --git a/lib/uri/http.rb b/lib/uri/http.rb index 0af1858efe..7d499f08d8 100644 --- a/lib/uri/http.rb +++ b/lib/uri/http.rb @@ -21,10 +21,10 @@ module URI # update. See <URL:http://support.microsoft.com/kb/834489>. # class HTTP < Generic - # A Default port of 80 for URI::HTTP + # A Default port of 80 for URI::HTTP. DEFAULT_PORT = 80 - # An Array of the available components for URI::HTTP + # An Array of the available components for URI::HTTP. COMPONENT = %i[ scheme userinfo host port @@ -36,22 +36,22 @@ module URI # # == Description # - # Create a new URI::HTTP object from components, with syntax checking. + # Creates a new URI::HTTP object from components, with syntax checking. # - # The components accepted are userinfo, host, port, path, query and + # 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. # - # If an Array is used, the components must be passed in the order - # [userinfo, host, port, path, query, fragment]. + # If an Array is used, the components must be passed in the + # order <code>[userinfo, host, port, path, query, fragment]</code>. # # Example: # - # newuri = URI::HTTP.build(host: 'www.example.com', path: '/foo/bar') + # uri = URI::HTTP.build(host: 'www.example.com', path: '/foo/bar') # - # newuri = URI::HTTP.build([nil, "www.example.com", nil, "/path", + # uri = URI::HTTP.build([nil, "www.example.com", nil, "/path", # "query", 'fragment']) # # Currently, if passed userinfo components this method generates @@ -72,8 +72,8 @@ module URI # # Example: # - # newuri = URI::HTTP.build(path: '/foo/bar', query: 'test=true') - # newuri.request_uri # => "/foo/bar?test=true" + # uri = URI::HTTP.build(path: '/foo/bar', query: 'test=true') + # uri.request_uri # => "/foo/bar?test=true" # def request_uri return unless @path diff --git a/lib/uri/ldap.rb b/lib/uri/ldap.rb index f7468a143a..6863fcfbc1 100644 --- a/lib/uri/ldap.rb +++ b/lib/uri/ldap.rb @@ -17,15 +17,16 @@ require 'uri/generic' module URI # - # LDAP URI SCHEMA (described in RFC2255) + # LDAP URI SCHEMA (described in RFC2255). + #-- # ldap://<host>/<dn>[?<attrs>[?<scope>[?<filter>[?<extensions>]]]] - # + #++ class LDAP < Generic - # A Default port of 389 for URI::LDAP + # A Default port of 389 for URI::LDAP. DEFAULT_PORT = 389 - # An Array of the available components for URI::LDAP + # An Array of the available components for URI::LDAP. COMPONENT = [ :scheme, :host, :port, @@ -40,8 +41,8 @@ module URI # # * 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 + # not including any entries under this + # * SCOPE_SUB - subtrees, all entries at all levels # SCOPE = [ SCOPE_ONE = 'one', @@ -52,7 +53,7 @@ module URI # # == Description # - # Create a new URI::LDAP object from components, with syntax checking. + # Creates a new URI::LDAP object from components, with syntax checking. # # The components accepted are host, port, dn, attributes, # scope, filter, and extensions. @@ -60,15 +61,15 @@ module URI # 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]. + # If an Array is used, the components must be passed in the + # order <code>[host, port, dn, attributes, scope, filter, extensions]</code>. # # Example: # - # newuri = URI::LDAP.build({:host => 'ldap.example.com', + # uri = URI::LDAP.build({:host => 'ldap.example.com', # :dn => '/dc=example'}) # - # newuri = URI::LDAP.build(["ldap.example.com", nil, + # uri = URI::LDAP.build(["ldap.example.com", nil, # "/dc=example;dc=com", "query", nil, nil, nil]) # def self.build(args) @@ -92,19 +93,18 @@ module URI # # == Description # - # Create a new URI::LDAP object from generic URI components as per + # Creates 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. + # +opaque+, +query+, and +fragment+, in that order. # # Example: # # uri = URI::LDAP.new("ldap", nil, "ldap.example.com", nil, nil, # "/dc=example;dc=com", nil, "query", nil) # - # - # See also URI::Generic.new + # See also URI::Generic.new. # def initialize(*arg) super(*arg) @@ -117,14 +117,14 @@ module URI parse_query end - # private method to cleanup +dn+ from using the +path+ component attribute + # 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 + # Private method to cleanup +attributes+, +scope+, +filter+, and +extensions+ + # from using the +query+ component attribute. def parse_query @attributes = nil @scope = nil @@ -142,7 +142,7 @@ module URI end private :parse_query - # private method to assemble +query+ from +attributes+, +scope+, +filter+ and +extensions+. + # Private method to assemble +query+ from +attributes+, +scope+, +filter+, and +extensions+. def build_path_query @path = '/' + @dn @@ -155,12 +155,12 @@ module URI end private :build_path_query - # returns dn. + # Returns dn. def dn @dn end - # private setter for dn +val+ + # Private setter for dn +val+. def set_dn(val) @dn = val build_path_query @@ -168,18 +168,18 @@ module URI end protected :set_dn - # setter for dn +val+ + # Setter for dn +val+. def dn=(val) set_dn(val) val end - # returns attributes. + # Returns attributes. def attributes @attributes end - # private setter for attributes +val+ + # Private setter for attributes +val+. def set_attributes(val) @attributes = val build_path_query @@ -187,18 +187,18 @@ module URI end protected :set_attributes - # setter for attributes +val+ + # Setter for attributes +val+. def attributes=(val) set_attributes(val) val end - # returns scope. + # Returns scope. def scope @scope end - # private setter for scope +val+ + # Private setter for scope +val+. def set_scope(val) @scope = val build_path_query @@ -206,18 +206,18 @@ module URI end protected :set_scope - # setter for scope +val+ + # Setter for scope +val+. def scope=(val) set_scope(val) val end - # returns filter. + # Returns filter. def filter @filter end - # private setter for filter +val+ + # Private setter for filter +val+. def set_filter(val) @filter = val build_path_query @@ -225,18 +225,18 @@ module URI end protected :set_filter - # setter for filter +val+ + # Setter for filter +val+. def filter=(val) set_filter(val) val end - # returns extensions. + # Returns extensions. def extensions @extensions end - # private setter for extensions +val+ + # Private setter for extensions +val+. def set_extensions(val) @extensions = val build_path_query @@ -244,14 +244,14 @@ module URI end protected :set_extensions - # setter for extensions +val+ + # 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+ + # Checks if URI has a path. + # For URI::LDAP this will return +false+. def hierarchical? false end diff --git a/lib/uri/mailto.rb b/lib/uri/mailto.rb index 1494c3952b..542bd4e089 100644 --- a/lib/uri/mailto.rb +++ b/lib/uri/mailto.rb @@ -13,15 +13,15 @@ require 'uri/generic' module URI # - # RFC6068, The mailto URL scheme + # RFC6068, the mailto URL scheme. # class MailTo < Generic include REGEXP - # A Default port of nil for URI::MailTo + # A Default port of nil for URI::MailTo. DEFAULT_PORT = nil - # An Array of the available components for URI::MailTo + # An Array of the available components for URI::MailTo. COMPONENT = [ :scheme, :to, :headers ].freeze # :stopdoc: @@ -62,26 +62,26 @@ module URI # Creates a new URI::MailTo object from components, with syntax checking. # # Components can be provided as an Array or Hash. If an Array is used, - # the components must be supplied as [to, headers]. + # the components must be supplied as <code>[to, headers]</code>. # # 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 - # "subject=subscribe&cc=address", or as an Array of Arrays like - # [['subject', 'subscribe'], ['cc', 'address']] + # <code>"subject=subscribe&cc=address"</code>, or as an Array of Arrays + # like <code>[['subject', 'subscribe'], ['cc', 'address']]</code>. # # Examples: # # require 'uri' # # m1 = URI::MailTo.build(['joe@example.com', 'subject=Ruby']) - # puts m1.to_s -> mailto:joe@example.com?subject=Ruby + # 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 + # 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 + # m3.to_s # => "mailto:listman@example.com?subject=subscribe" # def self.build(args) tmp = Util.make_components_hash(self, args) @@ -160,13 +160,13 @@ module URI end end - # The primary e-mail address of the URL, as a String + # The primary e-mail address of the URL, as a String. attr_reader :to - # E-mail headers set by the URL, as an Array of Arrays + # E-mail headers set by the URL, as an Array of Arrays. attr_reader :headers - # check the to +v+ component + # Checks the to +v+ component. def check_to(v) return true unless v return true if v.size == 0 @@ -191,20 +191,20 @@ module URI end private :check_to - # private setter for to +v+ + # Private setter for to +v+. def set_to(v) @to = v end protected :set_to - # setter for to +v+ + # Setter for to +v+. def to=(v) check_to(v) set_to(v) v end - # check the headers +v+ component against either + # Checks the headers +v+ component against either # * HEADER_REGEXP def check_headers(v) return true unless v @@ -218,7 +218,7 @@ module URI end private :check_headers - # private setter for headers +v+ + # Private setter for headers +v+. def set_headers(v) @headers = [] if v @@ -229,14 +229,14 @@ module URI end protected :set_headers - # setter for headers +v+ + # Setter for headers +v+. def headers=(v) check_headers(v) set_headers(v) v end - # Constructs String from URI + # Constructs String from URI. def to_s @scheme + ':' + if @to diff --git a/lib/uri/rfc2396_parser.rb b/lib/uri/rfc2396_parser.rb index 6a2d819152..a143437d8a 100644 --- a/lib/uri/rfc2396_parser.rb +++ b/lib/uri/rfc2396_parser.rb @@ -58,7 +58,7 @@ module URI # :startdoc: end # REGEXP - # class that Parses String's into URI's + # Class that Parses String's into URI's. # # It contains a Hash set of patterns and Regexp's that match and validate. # @@ -88,12 +88,12 @@ module URI # == Examples # # p = URI::Parser.new(:ESCAPED => "(?:%[a-fA-F0-9]{2}|%u[a-fA-F0-9]{4})") - # u = p.parse("http://example.jp/%uABCD") #=> #<URI::HTTP:0xb78cf4f8 URL:http://example.jp/%uABCD> + # u = p.parse("http://example.jp/%uABCD") #=> #<URI::HTTP http://example.jp/%uABCD> # URI.parse(u.to_s) #=> raises URI::InvalidURIError # # s = "http://example.com/ABCD" - # u1 = p.parse(s) #=> #<URI::HTTP:0xb78c3220 URL:http://example.com/ABCD> - # u2 = URI.parse(s) #=> #<URI::HTTP:0xb78b6d54 URL:http://example.com/ABCD> + # u1 = p.parse(s) #=> #<URI::HTTP http://example.com/ABCD> + # u2 = URI.parse(s) #=> #<URI::HTTP http://example.com/ABCD> # u1 == u2 #=> true # u1.eql?(u2) #=> false # @@ -109,15 +109,15 @@ module URI # The Hash of patterns. # - # see also URI::Parser.initialize_pattern + # See also URI::Parser.initialize_pattern. attr_reader :pattern - # The Hash of Regexp + # The Hash of Regexp. # - # see also URI::Parser.initialize_regexp + # See also URI::Parser.initialize_regexp. attr_reader :regexp - # Returns a split URI against regexp[:ABS_URI] + # Returns a split URI against regexp[:ABS_URI]. def split(uri) case uri when '' @@ -198,14 +198,14 @@ module URI # # == Description # - # parses +uri+ and constructs either matching URI scheme object - # (FTP, HTTP, HTTPS, LDAP, LDAPS, or MailTo) or URI::Generic + # Parses +uri+ and constructs either matching URI scheme object + # (file, FTP, HTTP, HTTPS, LDAP, LDAPS, or MailTo) or URI::Generic. # # == Usage # # p = URI::Parser.new # p.parse("ldap://ldap.example.com/dc=example?user=john") - # #=> #<URI::LDAP:0x00000000b9e7e8 URL:ldap://ldap.example.com/dc=example?user=john> + # #=> #<URI::LDAP ldap://ldap.example.com/dc=example?user=john> # def parse(uri) scheme, userinfo, host, port, @@ -231,7 +231,7 @@ module URI # # == Description # - # Attempts to parse and merge a set of URIs + # Attempts to parse and merge a set of URIs. # def join(*uris) uris[0] = convert_to_uri(uris[0]) @@ -253,11 +253,11 @@ module URI # # == Description # - # Attempts to parse and merge a set of URIs - # If no +block+ given , then returns the result, + # Attempts to parse and merge a set of URIs. + # If no +block+ given, then returns the result, # else it calls +block+ for each element in result. # - # see also URI::Parser.make_regexp + # See also URI::Parser.make_regexp. # def extract(str, schemes = nil) if block_given? @@ -270,8 +270,8 @@ module URI end end - # returns Regexp that is default self.regexp[:ABS_URI_REF], - # unless +schemes+ is provided. Then it is a Regexp.union with self.pattern[:X_ABS_URI] + # Returns Regexp that is default self.regexp[:ABS_URI_REF], + # unless +schemes+ is provided. Then it is a Regexp.union with self.pattern[:X_ABS_URI]. def make_regexp(schemes = nil) unless schemes @regexp[:ABS_URI_REF] @@ -294,7 +294,7 @@ module URI # # == Description # - # constructs a safe String from +str+, removing unsafe characters, + # Constructs a safe String from +str+, removing unsafe characters, # replacing them with codes. # def escape(str, unsafe = @regexp[:UNSAFE]) @@ -326,7 +326,7 @@ module URI # # == Description # - # Removes escapes from +str+ + # Removes escapes from +str+. # def unescape(str, escaped = @regexp[:ESCAPED]) enc = str.encoding @@ -341,7 +341,7 @@ module URI private - # Constructs the default Hash of patterns + # Constructs the default Hash of patterns. def initialize_pattern(opts = {}) ret = {} ret[:ESCAPED] = escaped = (opts.delete(:ESCAPED) || PATTERN::ESCAPED) @@ -499,7 +499,7 @@ module URI ret end - # Constructs the default Hash of Regexp's + # Constructs the default Hash of Regexp's. def initialize_regexp(pattern) ret = {} |