# URI is a module providing classes to handle Uniform Resource Identifiers
# ([RFC2396](http://tools.ietf.org/html/rfc2396)).
#
# ## Features
#
# *   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).
#
#
# ## Basic example
#
#     require 'uri'
#
#     uri = URI("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
#
#     module URI
#       class RSYNC < Generic
#         DEFAULT_PORT = 873
#       end
#       @@schemes['RSYNC'] = RSYNC
#     end
#     #=> 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}
#
#     uri = URI("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.
#
# 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)
# *   [RFC2368](http://tools.ietf.org/html/rfc2368)
# *   [RFC2373](http://tools.ietf.org/html/rfc2373)
# *   [RFC2396](http://tools.ietf.org/html/rfc2396)
# *   [RFC2732](http://tools.ietf.org/html/rfc2732)
# *   [RFC3986](http://tools.ietf.org/html/rfc3986)
#
#
# ## Class tree
#
# *   URI::Generic (in uri/generic.rb)
#     *   URI::File - (in uri/file.rb)
#     *   URI::FTP - (in uri/ftp.rb)
#     *   URI::HTTP - (in uri/http.rb)
#         *   URI::HTTPS - (in uri/https.rb)
#
#     *   URI::LDAP - (in uri/ldap.rb)
#         *   URI::LDAPS - (in uri/ldaps.rb)
#
#     *   URI::MailTo - (in uri/mailto.rb)
#
# *   URI::Parser - (in uri/common.rb)
# *   URI::REGEXP - (in uri/common.rb)
#     *   URI::REGEXP::PATTERN - (in uri/common.rb)
#
# *   URI::Util - (in uri/common.rb)
# *   URI::Escape - (in uri/common.rb)
# *   URI::Error - (in uri/common.rb)
#     *   URI::InvalidURIError - (in uri/common.rb)
#     *   URI::InvalidComponentError - (in uri/common.rb)
#     *   URI::BadURIError - (in uri/common.rb)
#
#
#
# ## Copyright Info
#
# Author
# :   Akira Yamada <akira@ruby-lang.org>
# Documentation
# :   Akira Yamada <akira@ruby-lang.org> Dmitry V. Sabanin <sdmitry@lrn.ru>
#     Vincent Batts <vbatts@hashbangbash.com>
# License
# :   Copyright (c) 2001 akira yamada <akira@ruby-lang.org> You can redistribute
#     it and/or modify it under the same term as Ruby.
# Revision
# :   $Id$
#
#
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
  # update. See <URL:http://support.microsoft.com/kb/834489>.
  #
  class HTTP < Generic
    # A Default port of 80 for URI::HTTP.
    DEFAULT_PORT: Integer

    # An Array of the available components for URI::HTTP.
    COMPONENT: Array[Symbol]

    #
    # == Description
    #
    # Creates a new URI::HTTP object from components, with syntax checking.
    #
    # 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 <code>[userinfo, host, port, path, query, fragment]</code>.
    #
    # Example:
    #
    #     uri = URI::HTTP.build(host: 'www.example.com', path: '/foo/bar')
    #
    #     uri = URI::HTTP.build([nil, "www.example.com", nil, "/path",
    #       "query", 'fragment'])
    #
    # Currently, if passed userinfo components this method generates
    # invalid HTTP URIs as per RFC 1738.
    #
    def self.build: (Array[String | Integer] args) -> URI::HTTP
                  | ({ userinfo: String, host: String, port: Integer, path: String, query: String, fragment: String }) -> URI::HTTP

    #
    # == Description
    #
    # Returns the full path for an HTTP request, as required by Net::HTTP::Get.
    #
    # If the URI contains a query, the full path is URI#path + '?' + URI#query.
    # Otherwise, the path is simply URI#path.
    #
    # Example:
    #
    #     uri = URI::HTTP.build(path: '/foo/bar', query: 'test=true')
    #     uri.request_uri #  => "/foo/bar?test=true"
    #
    def request_uri: () -> String
  end
end