Merge pull request #175 from nobu/doc-uri_parser

nobu · web-flow · commit 340c965418db · 2025-07-14T14:11:53.000+09:00
Update documents that used `URI::Parser`
diff --git a/.rdoc_options b/.rdoc_options
@@ -2,3 +2,4 @@ main_page: README.md
 op_dir: _site
 warn_missing_rdoc_ref: true
 title: URI Documentation
+visibility: :private
diff --git a/lib/uri/common.rb b/lib/uri/common.rb
@@ -159,9 +159,11 @@ def self.scheme_list
     Schemes.list
   end
 
+  # :stopdoc:
   INITIAL_SCHEMES = scheme_list
   private_constant :INITIAL_SCHEMES
   Ractor.make_shareable(INITIAL_SCHEMES) if defined?(Ractor)
+  # :startdoc:
 
   # Returns a new object constructed from the given +scheme+, +arguments+,
   # and +default+:
@@ -437,6 +439,8 @@ def self.decode_uri_component(str, enc=Encoding::UTF_8)
     _decode_uri_component(/%\h\h/, str, enc)
   end
 
+  # Returns a string derived from the given string +str+ with
+  # URI-encoded characters matching +regexp+ according to +table+.
   def self._encode_uri_component(regexp, table, str, enc)
     str = str.to_s.dup
     if str.encoding != Encoding::ASCII_8BIT
@@ -451,6 +455,8 @@ def self._encode_uri_component(regexp, table, str, enc)
   end
   private_class_method :_encode_uri_component
 
+  # Returns a string decoding characters matching +regexp+ from the
+  # given \URL-encoded string +str+.
   def self._decode_uri_component(regexp, str, enc)
     raise ArgumentError, "invalid %-encoding (#{str})" if /%(?!\h\h)/.match?(str)
     str.b.gsub(regexp, TBLDECWWWCOMP_).force_encoding(enc)
diff --git a/lib/uri/generic.rb b/lib/uri/generic.rb
@@ -284,7 +284,7 @@ def registry # :nodoc:
 
     # Returns the parser to be used.
     #
-    # Unless a URI::Parser is defined, DEFAULT_PARSER is used.
+    # Unless the +parser+ is defined, DEFAULT_PARSER is used.
     #
     def parser
       if !defined?(@parser) || !@parser
@@ -315,7 +315,7 @@ def component
     end
 
     #
-    # Checks the scheme +v+ component against the URI::Parser Regexp for :SCHEME.
+    # Checks the scheme +v+ component against the +parser+ Regexp for :SCHEME.
     #
     def check_scheme(v)
       if v && parser.regexp[:SCHEME] !~ v
@@ -385,7 +385,7 @@ def check_userinfo(user, password = nil)
 
     #
     # Checks the user +v+ component for RFC2396 compliance
-    # and against the URI::Parser Regexp for :USERINFO.
+    # and against the +parser+ Regexp for :USERINFO.
     #
     # Can not have a registry or opaque component defined,
     # with a user component defined.
@@ -409,7 +409,7 @@ def check_user(v)
 
     #
     # Checks the password +v+ component for RFC2396 compliance
-    # and against the URI::Parser Regexp for :USERINFO.
+    # and against the +parser+ Regexp for :USERINFO.
     #
     # Can not have a registry or opaque component defined,
     # with a user component defined.
@@ -586,7 +586,7 @@ def decoded_password
 
     #
     # Checks the host +v+ component for RFC2396 compliance
-    # and against the URI::Parser Regexp for :HOST.
+    # and against the +parser+ Regexp for :HOST.
     #
     # Can not have a registry or opaque component defined,
     # with a host component defined.
@@ -675,7 +675,7 @@ def hostname=(v)
 
     #
     # Checks the port +v+ component for RFC2396 compliance
-    # and against the URI::Parser Regexp for :PORT.
+    # and against the +parser+ Regexp for :PORT.
     #
     # Can not have a registry or opaque component defined,
     # with a port component defined.
@@ -748,7 +748,7 @@ def registry=(v) # :nodoc:
 
     #
     # Checks the path +v+ component for RFC2396 compliance
-    # and against the URI::Parser Regexp
+    # and against the +parser+ Regexp
     # for :ABS_PATH and :REL_PATH.
     #
     # Can not have a opaque component defined,
@@ -853,7 +853,7 @@ def query=(v)
 
     #
     # Checks the opaque +v+ component for RFC2396 compliance and
-    # against the URI::Parser Regexp for :OPAQUE.
+    # against the +parser+ Regexp for :OPAQUE.
     #
     # Can not have a host, port, user, or path component defined,
     # with an opaque component defined.
@@ -905,7 +905,7 @@ def opaque=(v)
     end
 
     #
-    # Checks the fragment +v+ component against the URI::Parser Regexp for :FRAGMENT.
+    # Checks the fragment +v+ component against the +parser+ Regexp for :FRAGMENT.
     #
     #
     # == Args
diff --git a/lib/uri/rfc2396_parser.rb b/lib/uri/rfc2396_parser.rb
@@ -67,7 +67,7 @@ class RFC2396_Parser
     #
     # == Synopsis
     #
-    #   URI::Parser.new([opts])
+    #   URI::RFC2396_Parser.new([opts])
     #
     # == Args
     #
@@ -86,7 +86,7 @@ class RFC2396_Parser
     #
     # == Examples
     #
-    #   p = URI::Parser.new(:ESCAPED => "(?:%[a-fA-F0-9]{2}|%u[a-fA-F0-9]{4})")
+    #   p = URI::RFC2396_Parser.new(:ESCAPED => "(?:%[a-fA-F0-9]{2}|%u[a-fA-F0-9]{4})")
     #   u = p.parse("http://example.jp/%uABCD") #=> #<URI::HTTP http://example.jp/%uABCD>
     #   URI.parse(u.to_s) #=> raises URI::InvalidURIError
     #
@@ -108,12 +108,12 @@ def initialize(opts = {})
 
     # The Hash of patterns.
     #
-    # See also URI::Parser.initialize_pattern.
+    # See also #initialize_pattern.
     attr_reader :pattern
 
     # The Hash of Regexp.
     #
-    # See also URI::Parser.initialize_regexp.
+    # See also #initialize_regexp.
     attr_reader :regexp
 
     # Returns a split URI against +regexp[:ABS_URI]+.
@@ -202,8 +202,7 @@ def split(uri)
     #
     # == Usage
     #
-    #   p = URI::Parser.new
-    #   p.parse("ldap://ldap.example.com/dc=example?user=john")
+    #   URI::RFC2396_PARSER.parse("ldap://ldap.example.com/dc=example?user=john")
     #   #=> #<URI::LDAP ldap://ldap.example.com/dc=example?user=john>
     #
     def parse(uri)
@@ -244,7 +243,7 @@ def join(*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 #make_regexp.
     #
     def extract(str, schemes = nil)
       if block_given?
@@ -524,6 +523,8 @@ def initialize_regexp(pattern)
       ret
     end
 
+    # Returns +uri+ as-is if it is URI, or convert it to URI if it is
+    # a String.
     def convert_to_uri(uri)
       if uri.is_a?(URI::Generic)
         uri

Original file line number	Diff line number	Diff line change
`@@ -284,7 +284,7 @@ def registry # :nodoc:`
`284`	`284`
`285`	`285`	`# Returns the parser to be used.`
`286`	`286`	`#`
`287`		`- # Unless a URI::Parser is defined, DEFAULT_PARSER is used.`
	`287`	`+ # Unless the +parser+ is defined, DEFAULT_PARSER is used.`
`288`	`288`	`#`
`289`	`289`	`def parser`
`290`	`290`	`if !defined?(@parser) \|\| !@parser`
`@@ -315,7 +315,7 @@ def component`
`315`	`315`	`end`
`316`	`316`
`317`	`317`	`#`
`318`		`- # Checks the scheme +v+ component against the URI::Parser Regexp for :SCHEME.`
	`318`	`+ # Checks the scheme +v+ component against the +parser+ Regexp for :SCHEME.`
`319`	`319`	`#`
`320`	`320`	`def check_scheme(v)`
`321`	`321`	`if v && parser.regexp[:SCHEME] !~ v`
`@@ -385,7 +385,7 @@ def check_userinfo(user, password = nil)`
`385`	`385`
`386`	`386`	`#`
`387`	`387`	`# Checks the user +v+ component for RFC2396 compliance`
`388`		`- # and against the URI::Parser Regexp for :USERINFO.`
	`388`	`+ # and against the +parser+ Regexp for :USERINFO.`
`389`	`389`	`#`
`390`	`390`	`# Can not have a registry or opaque component defined,`
`391`	`391`	`# with a user component defined.`
`@@ -409,7 +409,7 @@ def check_user(v)`
`409`	`409`
`410`	`410`	`#`
`411`	`411`	`# Checks the password +v+ component for RFC2396 compliance`
`412`		`- # and against the URI::Parser Regexp for :USERINFO.`
	`412`	`+ # and against the +parser+ Regexp for :USERINFO.`
`413`	`413`	`#`
`414`	`414`	`# Can not have a registry or opaque component defined,`
`415`	`415`	`# with a user component defined.`
`@@ -586,7 +586,7 @@ def decoded_password`
`586`	`586`
`587`	`587`	`#`
`588`	`588`	`# Checks the host +v+ component for RFC2396 compliance`
`589`		`- # and against the URI::Parser Regexp for :HOST.`
	`589`	`+ # and against the +parser+ Regexp for :HOST.`
`590`	`590`	`#`
`591`	`591`	`# Can not have a registry or opaque component defined,`
`592`	`592`	`# with a host component defined.`
`@@ -675,7 +675,7 @@ def hostname=(v)`
`675`	`675`
`676`	`676`	`#`
`677`	`677`	`# Checks the port +v+ component for RFC2396 compliance`
`678`		`- # and against the URI::Parser Regexp for :PORT.`
	`678`	`+ # and against the +parser+ Regexp for :PORT.`
`679`	`679`	`#`
`680`	`680`	`# Can not have a registry or opaque component defined,`
`681`	`681`	`# with a port component defined.`
`@@ -748,7 +748,7 @@ def registry=(v) # :nodoc:`
`748`	`748`
`749`	`749`	`#`
`750`	`750`	`# Checks the path +v+ component for RFC2396 compliance`
`751`		`- # and against the URI::Parser Regexp`
	`751`	`+ # and against the +parser+ Regexp`
`752`	`752`	`# for :ABS_PATH and :REL_PATH.`
`753`	`753`	`#`
`754`	`754`	`# Can not have a opaque component defined,`
`@@ -853,7 +853,7 @@ def query=(v)`
`853`	`853`
`854`	`854`	`#`
`855`	`855`	`# Checks the opaque +v+ component for RFC2396 compliance and`
`856`		`- # against the URI::Parser Regexp for :OPAQUE.`
	`856`	`+ # against the +parser+ Regexp for :OPAQUE.`
`857`	`857`	`#`
`858`	`858`	`# Can not have a host, port, user, or path component defined,`
`859`	`859`	`# with an opaque component defined.`
`@@ -905,7 +905,7 @@ def opaque=(v)`
`905`	`905`	`end`
`906`	`906`
`907`	`907`	`#`
`908`		`- # Checks the fragment +v+ component against the URI::Parser Regexp for :FRAGMENT.`
	`908`	`+ # Checks the fragment +v+ component against the +parser+ Regexp for :FRAGMENT.`
`909`	`909`	`#`
`910`	`910`	`#`
`911`	`911`	`# == Args`
Original file line number	Diff line number	Diff line change
`@@ -67,7 +67,7 @@ class RFC2396_Parser`
`67`	`67`	`#`
`68`	`68`	`# == Synopsis`
`69`	`69`	`#`
`70`		`- # URI::Parser.new([opts])`
	`70`	`+ # URI::RFC2396_Parser.new([opts])`
`71`	`71`	`#`
`72`	`72`	`# == Args`
`73`	`73`	`#`
`@@ -86,7 +86,7 @@ class RFC2396_Parser`
`86`	`86`	`#`
`87`	`87`	`# == Examples`
`88`	`88`	`#`
`89`		`- # p = URI::Parser.new(:ESCAPED => "(?:%[a-fA-F0-9]{2}\|%u[a-fA-F0-9]{4})")`
	`89`	`+ # p = URI::RFC2396_Parser.new(:ESCAPED => "(?:%[a-fA-F0-9]{2}\|%u[a-fA-F0-9]{4})")`
`90`	`90`	`# u = p.parse("http://example.jp/%uABCD") #=> #<URI::HTTP http://example.jp/%uABCD>`
`91`	`91`	`# URI.parse(u.to_s) #=> raises URI::InvalidURIError`
`92`	`92`	`#`
`@@ -108,12 +108,12 @@ def initialize(opts = {})`
`108`	`108`
`109`	`109`	`# The Hash of patterns.`
`110`	`110`	`#`
`111`		`- # See also URI::Parser.initialize_pattern.`
	`111`	`+ # See also #initialize_pattern.`
`112`	`112`	`attr_reader :pattern`
`113`	`113`
`114`	`114`	`# The Hash of Regexp.`
`115`	`115`	`#`
`116`		`- # See also URI::Parser.initialize_regexp.`
	`116`	`+ # See also #initialize_regexp.`
`117`	`117`	`attr_reader :regexp`
`118`	`118`
`119`	`119`	`# Returns a split URI against +regexp[:ABS_URI]+.`
`@@ -202,8 +202,7 @@ def split(uri)`
`202`	`202`	`#`
`203`	`203`	`# == Usage`
`204`	`204`	`#`
`205`		`- # p = URI::Parser.new`
`206`		`- # p.parse("ldap://ldap.example.com/dc=example?user=john")`
	`205`	`+ # URI::RFC2396_PARSER.parse("ldap://ldap.example.com/dc=example?user=john")`
`207`	`206`	`# #=> #<URI::LDAP ldap://ldap.example.com/dc=example?user=john>`
`208`	`207`	`#`
`209`	`208`	`def parse(uri)`
`@@ -244,7 +243,7 @@ def join(*uris)`
`244`	`243`	`# If no +block+ given, then returns the result,`
`245`	`244`	`# else it calls +block+ for each element in result.`
`246`	`245`	`#`
`247`		`- # See also URI::Parser.make_regexp.`
	`246`	`+ # See also #make_regexp.`
`248`	`247`	`#`
`249`	`248`	`def extract(str, schemes = nil)`
`250`	`249`	`if block_given?`
`@@ -524,6 +523,8 @@ def initialize_regexp(pattern)`
`524`	`523`	`ret`
`525`	`524`	`end`
`526`	`525`
	`526`	`+ # Returns +uri+ as-is if it is URI, or convert it to URI if it is`
	`527`	`+ # a String.`
`527`	`528`	`def convert_to_uri(uri)`
`528`	`529`	`if uri.is_a?(URI::Generic)`
`529`	`530`	`uri`