%a{annotate:rdoc:skip}
module URI
  # <!-- rdoc-file=lib/uri/rfc2396_parser.rb -->
  # Includes URI::REGEXP::PATTERN
  #
  module RFC2396_REGEXP
  end

  # <!-- rdoc-file=lib/uri/rfc2396_parser.rb -->
  # Class that parses String's into URI's.
  #
  # It contains a Hash set of patterns and Regexp's that match and validate.
  #
  class RFC2396_Parser
    include RFC2396_REGEXP

    # <!-- rdoc-file=lib/uri/rfc2396_parser.rb -->
    # The Hash of patterns.
    #
    # See also URI::Parser.initialize_pattern.
    #
    attr_reader pattern: Hash[Symbol, String]

    # <!-- rdoc-file=lib/uri/rfc2396_parser.rb -->
    # The Hash of Regexp.
    #
    # See also URI::Parser.initialize_regexp.
    #
    attr_reader regexp: Hash[Symbol, Regexp]

    # <!--
    #   rdoc-file=lib/uri/rfc2396_parser.rb
    #   - new(opts = {})
    # -->
    # ## Synopsis
    #
    #     URI::Parser.new([opts])
    #
    # ## Args
    #
    # The constructor accepts a hash as options for parser. Keys of options are
    # pattern names of URI components and values of options are pattern strings. The
    # constructor generates set of regexps for parsing URIs.
    #
    # You can use the following keys:
    #
    #     * :ESCAPED (URI::PATTERN::ESCAPED in default)
    #     * :UNRESERVED (URI::PATTERN::UNRESERVED in default)
    #     * :DOMLABEL (URI::PATTERN::DOMLABEL in default)
    #     * :TOPLABEL (URI::PATTERN::TOPLABEL in default)
    #     * :HOSTNAME (URI::PATTERN::HOSTNAME in default)
    #
    # ## 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 http://example.jp/%uABCD>
    #     URI.parse(u.to_s) #=> raises URI::InvalidURIError
    #
    #     s = "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
    #
    def initialize: (?Hash[Symbol, String] opts) -> void

    # <!--
    #   rdoc-file=lib/uri/rfc2396_parser.rb
    #   - escape( str )
    #   - escape( str, unsafe )
    # -->
    # ## Args
    #
    # `str`
    # :   String to make safe
    # `unsafe`
    # :   Regexp to apply. Defaults to `self.regexp[:UNSAFE]`
    #
    #
    # ## Description
    #
    # Constructs a safe String from `str`, removing unsafe characters, replacing
    # them with codes.
    #
    def escape: (String str, ?Regexp unsafe) -> String

    # <!--
    #   rdoc-file=lib/uri/rfc2396_parser.rb
    #   - extract( str )
    #   - extract( str, schemes )
    #   - extract( str, schemes ) {|item| block }
    # -->
    # ## Args
    #
    # `str`
    # :   String to search
    # `schemes`
    # :   Patterns to apply to `str`
    #
    #
    # ## Description
    #
    # 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.
    #
    def extract: (String str, ?Array[String] schemes) -> Array[String]
               | (String str, ?Array[String] schemes) { (String) -> untyped } -> nil

    # <!--
    #   rdoc-file=lib/uri/rfc2396_parser.rb
    #   - join(*uris)
    # -->
    # ## Args
    #
    # `uris`
    # :   an Array of Strings
    #
    #
    # ## Description
    #
    # Attempts to parse and merge a set of URIs.
    #
    def join: (*String uris) -> URI::Generic

    # <!--
    #   rdoc-file=lib/uri/rfc2396_parser.rb
    #   - make_regexp(schemes = nil)
    # -->
    # 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: (?Array[String] schemes) -> Regexp

    # <!--
    #   rdoc-file=lib/uri/rfc2396_parser.rb
    #   - parse(uri)
    # -->
    # ## Args
    #
    # `uri`
    # :   String
    #
    #
    # ## Description
    #
    # 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 ldap://ldap.example.com/dc=example?user=john>
    #
    def parse: (String uri) -> URI::Generic

    # <!--
    #   rdoc-file=lib/uri/rfc2396_parser.rb
    #   - split(uri)
    # -->
    # Returns a split URI against `regexp[:ABS_URI]`.
    #
    def split: (String uri) -> [ String?, String?, String?, String?, String?, String?, String?, String?, String? ]

    # <!--
    #   rdoc-file=lib/uri/rfc2396_parser.rb
    #   - unescape( str )
    #   - unescape( str, escaped )
    # -->
    # ## Args
    #
    # `str`
    # :   String to remove escapes from
    # `escaped`
    # :   Regexp to apply. Defaults to `self.regexp[:ESCAPED]`
    #
    #
    # ## Description
    #
    # Removes escapes from `str`.
    #
    def unescape: (String str, ?Regexp escaped) -> String
  end
end