rbs 2.0.0 → 2.2.2

data/stdlib/cgi/0/core.rbs

@@ -1,3 +1,4 @@
+# <!-- rdoc-file=lib/cgi.rb -->
 # ## Overview
 #
 # The Common Gateway Interface (CGI) is a simple protocol for passing an HTTP
@@ -266,7 +267,17 @@
 #     include CGI::Util
 #     escapeHTML('Usage: foo "bar" <baz>')
 #     h('Usage: foo "bar" <baz>') # alias
+#
 class CGI
+  include CGI::Util
+
+  extend CGI::Util
+
+  # <!--
+  #   rdoc-file=lib/cgi/core.rb
+  #   - CGI.new(tag_maker) { block }
+  #   - CGI.new(options_hash = {}) { block }
+  # -->
   # Create a new CGI instance.
   #
   # `tag_maker`
@@ -343,26 +354,42 @@ class CGI
   def initialize: (?String tag_maker) ?{ (String name, String value) -> void } -> void
                 | (Hash[Symbol, untyped] options_hash) ?{ (String name, String value) -> void } -> void
 
-  attr_reader accept_charset: String
-
+  # <!--
+  #   rdoc-file=lib/cgi/core.rb
+  #   - accept_charset()
+  # -->
   # Return the accept character set for all new CGI instances.
   #
   def self.accept_charset: () -> String
 
+  # <!--
+  #   rdoc-file=lib/cgi/core.rb
+  #   - accept_charset=(accept_charset)
+  # -->
   # Set the accept character set for all new CGI instances.
   #
   def self.accept_charset=: (String accept_charset) -> String
 
+  # <!--
+  #   rdoc-file=lib/cgi/core.rb
+  #   - parse(query)
+  # -->
   # Parse an HTTP query string into a hash of key=>value pairs.
   #
   #     params = CGI.parse("query_string")
   #       # {"name1" => ["value1", "value2", ...],
   #       #  "name2" => ["value1", "value2", ...], ... }
   #
-  def self.parse: (String query) -> Hash[String, String | Array[String]]
+  def self.parse: (String query) -> Hash[String, Array[String]]
 
   public
 
+  # <!-- rdoc-file=lib/cgi/core.rb -->
+  # Return the accept character set for this CGI instance.
+  #
+  attr_reader accept_charset: String
+
+  # <!-- rdoc-file=lib/cgi/core.rb -->
   # This method is an alias for #http_header, when HTML5 tag maker is inactive.
   #
   # NOTE: use #http_header to create HTTP header blocks, this alias is only
@@ -372,6 +399,11 @@ class CGI
   #
   alias header http_header
 
+  # <!--
+  #   rdoc-file=lib/cgi/core.rb
+  #   - http_header(content_type_string="text/html")
+  #   - http_header(headers_hash)
+  # -->
   # Create an HTTP header block as a string.
   #
   # Includes the empty line that ends the header block.
@@ -485,8 +517,13 @@ class CGI
   def http_header: (?String options) -> String
                  | (?Hash[String | Symbol, untyped] header_hash) -> String
 
-  def nph?: () -> boolish
+  def nph?: () -> untyped
 
+  # <!--
+  #   rdoc-file=lib/cgi/core.rb
+  #   - cgi.out(content_type_string='text/html')
+  #   - cgi.out(headers_hash)
+  # -->
   # Print an HTTP header and body to $DEFAULT_OUTPUT ($>)
   #
   # `content_type_string`
@@ -551,6 +588,10 @@ class CGI
   def out: (?String content_type_string) { () -> String } -> void
          | (Hash[String | Symbol, untyped] headers_hash) { () -> String } -> void
 
+  # <!--
+  #   rdoc-file=lib/cgi/core.rb
+  #   - print(*options)
+  # -->
   # Print an argument or list of arguments to the default output stream
   #
   #     cgi = CGI.new
@@ -560,36 +601,623 @@ class CGI
 
   private
 
+  # <!--
+  #   rdoc-file=lib/cgi/core.rb
+  #   - stdinput()
+  # -->
   # Synonym for $stdin.
   #
   def stdinput: () -> ::IO
 
+  # <!--
+  #   rdoc-file=lib/cgi/core.rb
+  #   - stdoutput()
+  # -->
   # Synonym for $stdout.
   #
   def stdoutput: () -> ::IO
-end
 
-# String for carriage return
-CGI::CR: String
+  # <!-- rdoc-file=lib/cgi/core.rb -->
+  # String for carriage return
+  #
+  CR: String
+
+  # <!-- rdoc-file=lib/cgi/core.rb -->
+  # Standard internet newline sequence
+  #
+  EOL: String
+
+  # <!-- rdoc-file=lib/cgi/core.rb -->
+  # HTTP status codes.
+  #
+  HTTP_STATUS: Hash[String, String]
+
+  # <!-- rdoc-file=lib/cgi/core.rb -->
+  # String for linefeed
+  #
+  LF: String
+
+  # <!-- rdoc-file=lib/cgi/core.rb -->
+  # Maximum number of request parameters when multipart
+  #
+  MAX_MULTIPART_COUNT: Integer
+
+  # <!-- rdoc-file=lib/cgi/core.rb -->
+  # Whether processing will be required in binary vs text
+  #
+  NEEDS_BINMODE: bool
+
+  # <!-- rdoc-file=lib/cgi/core.rb -->
+  # Path separators in different environments.
+  #
+  PATH_SEPARATOR: Hash[String, String]
+
+  REVISION: String
+
+  VERSION: String
+
+  # <!-- rdoc-file=lib/cgi/cookie.rb -->
+  # Class representing an HTTP cookie.
+  #
+  # In addition to its specific fields and methods, a Cookie instance is a
+  # delegator to the array of its values.
+  #
+  # See RFC 2965.
+  #
+  # ## Examples of use
+  #     cookie1 = CGI::Cookie.new("name", "value1", "value2", ...)
+  #     cookie1 = CGI::Cookie.new("name" => "name", "value" => "value")
+  #     cookie1 = CGI::Cookie.new('name'     => 'name',
+  #                               'value'    => ['value1', 'value2', ...],
+  #                               'path'     => 'path',   # optional
+  #                               'domain'   => 'domain', # optional
+  #                               'expires'  => Time.now, # optional
+  #                               'secure'   => true,     # optional
+  #                               'httponly' => true      # optional
+  #                               )
+  #
+  #     cgi.out("cookie" => [cookie1, cookie2]) { "string" }
+  #
+  #     name     = cookie1.name
+  #     values   = cookie1.value
+  #     path     = cookie1.path
+  #     domain   = cookie1.domain
+  #     expires  = cookie1.expires
+  #     secure   = cookie1.secure
+  #     httponly = cookie1.httponly
+  #
+  #     cookie1.name     = 'name'
+  #     cookie1.value    = ['value1', 'value2', ...]
+  #     cookie1.path     = 'path'
+  #     cookie1.domain   = 'domain'
+  #     cookie1.expires  = Time.now + 30
+  #     cookie1.secure   = true
+  #     cookie1.httponly = true
+  #
+  class Cookie < Array[String]
+    # <!--
+    #   rdoc-file=lib/cgi/cookie.rb
+    #   - parse(raw_cookie)
+    # -->
+    # Parse a raw cookie string into a hash of cookie-name=>Cookie pairs.
+    #
+    #     cookies = CGI::Cookie.parse("raw_cookie_string")
+    #       # { "name1" => cookie1, "name2" => cookie2, ... }
+    #
+    def self.parse: (String raw_cookie) -> Hash[String, instance]
+
+    public
+
+    # <!-- rdoc-file=lib/cgi/cookie.rb -->
+    # Domain for which this cookie applies, as a `String`
+    #
+    def domain: () -> String?
+
+    # <!-- rdoc-file=lib/cgi/cookie.rb -->
+    # Domain for which this cookie applies, as a `String`
+    #
+    def domain=: (String domain) -> String
+
+    # <!-- rdoc-file=lib/cgi/cookie.rb -->
+    # Time at which this cookie expires, as a `Time`
+    #
+    def expires: () -> Time?
+
+    # <!-- rdoc-file=lib/cgi/cookie.rb -->
+    # Time at which this cookie expires, as a `Time`
+    #
+    def expires=: (Time time) -> Time
+
+    # <!-- rdoc-file=lib/cgi/cookie.rb -->
+    # True if this cookie is httponly; false otherwise
+    #
+    def httponly: () -> bool
+
+    # <!--
+    #   rdoc-file=lib/cgi/cookie.rb
+    #   - httponly=(val)
+    # -->
+    # Set whether the Cookie is a httponly cookie or not.
+    #
+    # `val` must be a boolean.
+    #
+    def httponly=: (boolish val) -> bool
+
+    # <!--
+    #   rdoc-file=lib/cgi/cookie.rb
+    #   - inspect()
+    # -->
+    # A summary of cookie string.
+    #
+    def inspect: () -> String
+
+    # <!-- rdoc-file=lib/cgi/cookie.rb -->
+    # Name of this cookie, as a `String`
+    #
+    def name: () -> String
+
+    # <!-- rdoc-file=lib/cgi/cookie.rb -->
+    # Name of this cookie, as a `String`
+    #
+    def name=: (String name) -> String
+
+    # <!-- rdoc-file=lib/cgi/cookie.rb -->
+    # Path for which this cookie applies, as a `String`
+    #
+    def path: () -> String?
+
+    # <!-- rdoc-file=lib/cgi/cookie.rb -->
+    # Path for which this cookie applies, as a `String`
+    #
+    def path=: (String path) -> String
+
+    # <!-- rdoc-file=lib/cgi/cookie.rb -->
+    # True if this cookie is secure; false otherwise
+    #
+    def secure: () -> bool
+
+    # <!--
+    #   rdoc-file=lib/cgi/cookie.rb
+    #   - secure=(val)
+    # -->
+    # Set whether the Cookie is a secure cookie or not.
+    #
+    # `val` must be a boolean.
+    #
+    def secure=: [A] (boolish val) -> A
+
+    # <!--
+    #   rdoc-file=lib/cgi/cookie.rb
+    #   - to_s()
+    # -->
+    # Convert the Cookie to its string representation.
+    #
+    def to_s: () -> String
+
+    # <!--
+    #   rdoc-file=lib/cgi/cookie.rb
+    #   - value()
+    # -->
+    # Returns the value or list of values for this cookie.
+    #
+    def value: () -> Array[String]
+
+    # <!--
+    #   rdoc-file=lib/cgi/cookie.rb
+    #   - value=(val)
+    # -->
+    # Replaces the value of this cookie with a new value or list of values.
+    #
+    def value=: (String val) -> String
+              | (Array[String] val) -> Array[String]
+
+    private
+
+    # <!--
+    #   rdoc-file=lib/cgi/cookie.rb
+    #   - Cookie.new(name_string,*value)
+    #   - Cookie.new(options_hash)
+    # -->
+    # Create a new CGI::Cookie object.
+    #
+    # `name_string`
+    # :   The name of the cookie; in this form, there is no #domain or #expiration.
+    #     The #path is gleaned from the `SCRIPT_NAME` environment variable, and
+    #     #secure is false.
+    # `*value`
+    # :   value or list of values of the cookie
+    # `options_hash`
+    # :   A Hash of options to initialize this Cookie.  Possible options are:
+    #
+    #     name
+    # :       the name of the cookie.  Required.
+    #     value
+    # :       the cookie's value or list of values.
+    #     path
+    # :       the path for which this cookie applies.  Defaults to the value of the
+    #         `SCRIPT_NAME` environment variable.
+    #     domain
+    # :       the domain for which this cookie applies.
+    #     expires
+    # :       the time at which this cookie expires, as a `Time` object.
+    #     secure
+    # :       whether this cookie is a secure cookie or not (default to false).
+    #         Secure cookies are only transmitted to HTTPS servers.
+    #     httponly
+    # :       whether this cookie is a HttpOnly cookie or not (default to
+    #
+    #         false).  HttpOnly cookies are not available to javascript.
+    #
+    #     These keywords correspond to attributes of the cookie object.
+    #
+    def initialize: (String name_string, *String value) -> void
+                  | (Hash[String, untyped] options_hash) -> void
+  end
+
+  module Escape
+    public
+
+    # <!--
+    #   rdoc-file=ext/cgi/escape/escape.c
+    #   - CGI.escape(string) -> string
+    # -->
+    # Returns URL-escaped string.
+    #
+    def escape: (string str) -> String
+
+    # <!--
+    #   rdoc-file=ext/cgi/escape/escape.c
+    #   - CGI.escapeHTML(string) -> string
+    # -->
+    # Returns HTML-escaped string.
+    #
+    def escapeHTML: (string str) -> String
+
+    # <!--
+    #   rdoc-file=ext/cgi/escape/escape.c
+    #   - CGI.unescape(string, encoding=@@accept_charset) -> string
+    # -->
+    # Returns URL-unescaped string.
+    #
+    def unescape: (string str, ?encoding encoding) -> String
+
+    # <!--
+    #   rdoc-file=ext/cgi/escape/escape.c
+    #   - CGI.unescapeHTML(string) -> string
+    # -->
+    # Returns HTML-unescaped string.
+    #
+    def unescapeHTML: (string str) -> String
+  end
+
+  # <!-- rdoc-file=lib/cgi/core.rb -->
+  # Exception raised when there is an invalid encoding detected
+  #
+  class InvalidEncoding < Exception
+  end
+
+  # <!-- rdoc-file=lib/cgi/core.rb -->
+  # Mixin module that provides the following:
+  #
+  # 1.  Access to the CGI environment variables as methods.  See documentation to
+  #     the CGI class for a list of these variables.  The methods are exposed by
+  #     removing the leading `HTTP_` (if it exists) and downcasing the name.  For
+  #     example, `auth_type` will return the environment variable `AUTH_TYPE`, and
+  #     `accept` will return the value for `HTTP_ACCEPT`.
+  #
+  # 2.  Access to cookies, including the cookies attribute.
+  #
+  # 3.  Access to parameters, including the params attribute, and overloading #[]
+  #     to perform parameter value lookup by key.
+  #
+  # 4.  The initialize_query method, for initializing the above mechanisms,
+  #     handling multipart forms, and allowing the class to be used in "offline"
+  #     mode.
+  #
+  module QueryExtension
+    public
+
+    # <!--
+    #   rdoc-file=lib/cgi/core.rb
+    #   - [](key)
+    # -->
+    # Get the value for the parameter with a given key.
+    #
+    # If the parameter has multiple values, only the first will be retrieved; use
+    # #params to get the array of values.
+    #
+    def []: (String key) -> String?
+
+    def accept: () -> String?
+
+    def accept_charset: () -> String?
+
+    def accept_encoding: () -> String?
+
+    def accept_language: () -> String?
+
+    def auth_type: () -> String?
+
+    def cache_control: () -> String?
+
+    def content_length: () -> String?
+
+    def content_type: () -> String?
+
+    # <!-- rdoc-file=lib/cgi/core.rb -->
+    # Get the cookies as a hash of cookie-name=>Cookie pairs.
+    #
+    def cookies: () -> Hash[String, Cookie]
+
+    # <!-- rdoc-file=lib/cgi/core.rb -->
+    # Get the cookies as a hash of cookie-name=>Cookie pairs.
+    #
+    def cookies=: (Hash[String, Cookie] cookies) -> Hash[String, Cookie]
+
+    def create_body: (boolish is_large) -> (Tempfile | StringIO)
+
+    # <!-- rdoc-file=lib/cgi/core.rb -->
+    # Get the uploaded files as a hash of name=>values pairs
+    #
+    def files: () -> Hash[String, Tempfile | StringIO]
+
+    def from: () -> String?
+
+    def gateway_interface: () -> String?
+
+    # <!--
+    #   rdoc-file=lib/cgi/core.rb
+    #   - has_key?(*args)
+    # -->
+    # Returns true if a given query string parameter exists.
+    #
+    def has_key?: (String key) -> bool
+
+    def host: () -> String?
+
+    # <!--
+    #   rdoc-file=lib/cgi/core.rb
+    #   - include?(*args)
+    # -->
+    #
+    alias include? has_key?
+
+    # <!--
+    #   rdoc-file=lib/cgi/core.rb
+    #   - key?(*args)
+    # -->
+    #
+    alias key? has_key?
+
+    # <!--
+    #   rdoc-file=lib/cgi/core.rb
+    #   - keys(*args)
+    # -->
+    # Return all query parameter names as an array of String.
+    #
+    def keys: () -> Array[String]
+
+    # <!--
+    #   rdoc-file=lib/cgi/core.rb
+    #   - multipart?()
+    # -->
+    # Returns whether the form contained multipart/form-data
+    #
+    def multipart?: () -> bool
+
+    def negotiate: () -> String?
+
+    # <!-- rdoc-file=lib/cgi/core.rb -->
+    # Get the parameters as a hash of name=>values pairs, where values is an Array.
+    #
+    def params: () -> Hash[String, Array[String] | Tempfile | StringIO]
+
+    # <!--
+    #   rdoc-file=lib/cgi/core.rb
+    #   - params=(hash)
+    # -->
+    # Set all the parameters.
+    #
+    def params=: (Hash[String, Array[String] | Tempfile | StringIO] hash) -> Hash[String, Array[String] | Tempfile | StringIO]
+
+    def path_info: () -> String?
 
-# Standard internet newline sequence
-CGI::EOL: String
+    def path_translated: () -> String?
 
-# HTTP status codes.
-CGI::HTTP_STATUS: Hash[String, String]
+    def pragma: () -> String?
 
-# String for linefeed
-CGI::LF: String
+    def query_string: () -> String?
 
-# Maximum number of request parameters when multipart
-CGI::MAX_MULTIPART_COUNT: Integer
+    # <!--
+    #   rdoc-file=lib/cgi/core.rb
+    #   - raw_cookie()
+    # -->
+    # Get the raw cookies as a string.
+    #
+    def raw_cookie: () -> String?
 
-# Whether processing will be required in binary vs text
-CGI::NEEDS_BINMODE: bool
+    # <!--
+    #   rdoc-file=lib/cgi/core.rb
+    #   - raw_cookie2()
+    # -->
+    # Get the raw RFC2965 cookies as a string.
+    #
+    def raw_cookie2: () -> String?
 
-# Path separators in different environments.
-CGI::PATH_SEPARATOR: Hash[String, String]
+    def referer: () -> String?
 
-CGI::REVISION: String
+    def remote_addr: () -> String?
 
-CGI::VERSION: String
+    def remote_host: () -> String?
+
+    def remote_ident: () -> String?
+
+    def remote_user: () -> String?
+
+    def request_method: () -> String?
+
+    def script_name: () -> String?
+
+    def server_name: () -> String?
+
+    def server_port: () -> String?
+
+    def server_protocol: () -> String?
+
+    def server_software: () -> String?
+
+    def unescape_filename?: () -> bool
+
+    def user_agent: () -> String?
+
+    private
+
+    # <!--
+    #   rdoc-file=lib/cgi/core.rb
+    #   - initialize_query()
+    # -->
+    # A wrapper class to use a StringIO object as the body and switch to a TempFile
+    # when the passed threshold is passed. Initialize the data from the query.
+    #
+    # Handles multipart forms (in particular, forms that involve file uploads).
+    # Reads query parameters in the @params field, and cookies into @cookies.
+    #
+    def initialize_query: () -> void
+
+    # <!--
+    #   rdoc-file=lib/cgi/core.rb
+    #   - read_from_cmdline()
+    # -->
+    # offline mode. read name=value pairs on standard input.
+    #
+    def read_from_cmdline: () -> String
+
+    # <!--
+    #   rdoc-file=lib/cgi/core.rb
+    #   - read_multipart(boundary, content_length)
+    # -->
+    # Parses multipart form elements according to
+    #     http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2
+    #
+    # Returns a hash of multipart form parameters with bodies of type StringIO or
+    # Tempfile depending on whether the multipart form element exceeds 10 KB
+    #
+    #     params[name => body]
+    #
+    def read_multipart: (String boundary, Integer content_length) -> (Tempfile | StringIO)
+  end
+
+  module Util
+    include CGI::Escape
+
+    public
+
+    # <!--
+    #   rdoc-file=lib/cgi/util.rb
+    #   - escapeElement(string, *elements)
+    # -->
+    # Escape only the tags of certain HTML elements in `string`.
+    #
+    # Takes an element or elements or array of elements.  Each element is specified
+    # by the name of the element, without angle brackets. This matches both the
+    # start and the end tag of that element. The attribute list of the open tag will
+    # also be escaped (for instance, the double-quotes surrounding attribute
+    # values).
+    #
+    #     print CGI.escapeElement('<BR><A HREF="url"></A>', "A", "IMG")
+    #       # "<BR>&lt;A HREF=&quot;url&quot;&gt;&lt;/A&gt"
+    #
+    #     print CGI.escapeElement('<BR><A HREF="url"></A>', ["A", "IMG"])
+    #       # "<BR>&lt;A HREF=&quot;url&quot;&gt;&lt;/A&gt"
+    #
+    def escapeElement: (string string, *String | Array[String] elements) -> String
+
+    # <!-- rdoc-file=lib/cgi/util.rb -->
+    # Synonym for CGI.escapeElement(str)
+    #
+    alias escape_element escapeElement
+
+    # <!-- rdoc-file=lib/cgi/util.rb -->
+    # Synonym for CGI.escapeHTML(str)
+    #
+    alias escape_html escapeHTML
+
+    # <!--
+    #   rdoc-file=lib/cgi/util.rb
+    #   - h(string)
+    # -->
+    #
+    alias h escapeHTML
+
+    # <!--
+    #   rdoc-file=lib/cgi/util.rb
+    #   - pretty(string, shift = " ")
+    # -->
+    # Prettify (indent) an HTML string.
+    #
+    # `string` is the HTML string to indent.  `shift` is the indentation unit to
+    # use; it defaults to two spaces.
+    #
+    #     print CGI.pretty("<HTML><BODY></BODY></HTML>")
+    #       # <HTML>
+    #       #   <BODY>
+    #       #   </BODY>
+    #       # </HTML>
+    #
+    #     print CGI.pretty("<HTML><BODY></BODY></HTML>", "\t")
+    #       # <HTML>
+    #       #         <BODY>
+    #       #         </BODY>
+    #       # </HTML>
+    #
+    def pretty: (string string, ?String shift) -> String
+
+    # <!--
+    #   rdoc-file=lib/cgi/util.rb
+    #   - rfc1123_date(time)
+    # -->
+    # Format a `Time` object as a String using the format specified by RFC 1123.
+    #
+    #     CGI.rfc1123_date(Time.now)
+    #       # Sat, 01 Jan 2000 00:00:00 GMT
+    #
+    def rfc1123_date: (Time time) -> String
+
+    # <!--
+    #   rdoc-file=lib/cgi/util.rb
+    #   - unescapeElement(string, *elements)
+    # -->
+    # Undo escaping such as that done by CGI.escapeElement()
+    #
+    #     print CGI.unescapeElement(
+    #             CGI.escapeHTML('<BR><A HREF="url"></A>'), "A", "IMG")
+    #       # "&lt;BR&gt;<A HREF="url"></A>"
+    #
+    #     print CGI.unescapeElement(
+    #             CGI.escapeHTML('<BR><A HREF="url"></A>'), ["A", "IMG"])
+    #       # "&lt;BR&gt;<A HREF="url"></A>"
+    #
+    def unescapeElement: (string string, *String | Array[String] elements) -> String
+
+    # <!-- rdoc-file=lib/cgi/util.rb -->
+    # Synonym for CGI.unescapeElement(str)
+    #
+    alias unescape_element unescapeElement
+
+    # <!-- rdoc-file=lib/cgi/util.rb -->
+    # Synonym for CGI.unescapeHTML(str)
+    #
+    alias unescape_html unescapeHTML
+
+    # Abbreviated day-of-week names specified by RFC 822
+    RFC822_DAYS: Array[String]
+
+    # Abbreviated month names specified by RFC 822
+    RFC822_MONTHS: Array[String]
+
+    # <!-- rdoc-file=lib/cgi/util.rb -->
+    # The set of special characters and their escaped values
+    #
+    TABLE_FOR_ESCAPE_HTML__: Hash[String, String]
+  end
+end