rbs 3.1.3 → 3.2.0.pre.1

data/stdlib/zlib/0/gzip_reader.rbs

@@ -0,0 +1,362 @@
+# <!-- rdoc-file=ext/zlib/zlib.c -->
+# This module provides access to the [zlib library](http://zlib.net). Zlib is
+# designed to be a portable, free, general-purpose, legally unencumbered -- that
+# is, not covered by any patents -- lossless data-compression library for use on
+# virtually any computer hardware and operating system.
+#
+# The zlib compression library provides in-memory compression and decompression
+# functions, including integrity checks of the uncompressed data.
+#
+# The zlib compressed data format is described in RFC 1950, which is a wrapper
+# around a deflate stream which is described in RFC 1951.
+#
+# The library also supports reading and writing files in gzip (.gz) format with
+# an interface similar to that of IO. The gzip format is described in RFC 1952
+# which is also a wrapper around a deflate stream.
+#
+# The zlib format was designed to be compact and fast for use in memory and on
+# communications channels. The gzip format was designed for single-file
+# compression on file systems, has a larger header than zlib to maintain
+# directory information, and uses a different, slower check method than zlib.
+#
+# See your system's zlib.h for further information about zlib
+#
+# ## Sample usage
+#
+# Using the wrapper to compress strings with default parameters is quite simple:
+#
+#     require "zlib"
+#
+#     data_to_compress = File.read("don_quixote.txt")
+#
+#     puts "Input size: #{data_to_compress.size}"
+#     #=> Input size: 2347740
+#
+#     data_compressed = Zlib::Deflate.deflate(data_to_compress)
+#
+#     puts "Compressed size: #{data_compressed.size}"
+#     #=> Compressed size: 887238
+#
+#     uncompressed_data = Zlib::Inflate.inflate(data_compressed)
+#
+#     puts "Uncompressed data is: #{uncompressed_data}"
+#     #=> Uncompressed data is: The Project Gutenberg EBook of Don Quixote...
+#
+# ## Class tree
+#
+# *   Zlib::Deflate
+# *   Zlib::Inflate
+# *   Zlib::ZStream
+# *   Zlib::Error
+#     *   Zlib::StreamEnd
+#     *   Zlib::NeedDict
+#     *   Zlib::DataError
+#     *   Zlib::StreamError
+#     *   Zlib::MemError
+#     *   Zlib::BufError
+#     *   Zlib::VersionError
+#     *   Zlib::InProgressError
+#
+#
+#
+# (if you have GZIP_SUPPORT)
+# *   Zlib::GzipReader
+# *   Zlib::GzipWriter
+# *   Zlib::GzipFile
+# *   Zlib::GzipFile::Error
+#     *   Zlib::GzipFile::LengthError
+#     *   Zlib::GzipFile::CRCError
+#     *   Zlib::GzipFile::NoFooter
+#
+module Zlib
+  # <!-- rdoc-file=ext/zlib/zlib.c -->
+  # Zlib::GzipReader is the class for reading a gzipped file.  GzipReader should
+  # be used as an IO, or -IO-like, object.
+  #
+  #     Zlib::GzipReader.open('hoge.gz') {|gz|
+  #       print gz.read
+  #     }
+  #
+  #     File.open('hoge.gz') do |f|
+  #       gz = Zlib::GzipReader.new(f)
+  #       print gz.read
+  #       gz.close
+  #     end
+  #
+  # ## Method Catalogue
+  #
+  # The following methods in Zlib::GzipReader are just like their counterparts in
+  # IO, but they raise Zlib::Error or Zlib::GzipFile::Error exception if an error
+  # was found in the gzip file.
+  # *   #each
+  # *   #each_line
+  # *   #each_byte
+  # *   #gets
+  # *   #getc
+  # *   #lineno
+  # *   #lineno=
+  # *   #read
+  # *   #readchar
+  # *   #readline
+  # *   #readlines
+  # *   #ungetc
+  #
+  #
+  # Be careful of the footer of the gzip file. A gzip file has the checksum of
+  # pre-compressed data in its footer. GzipReader checks all uncompressed data
+  # against that checksum at the following cases, and if it fails, raises
+  # `Zlib::GzipFile::NoFooter`, `Zlib::GzipFile::CRCError`, or
+  # `Zlib::GzipFile::LengthError` exception.
+  #
+  # *   When an reading request is received beyond the end of file (the end of
+  #     compressed data). That is, when Zlib::GzipReader#read,
+  #     Zlib::GzipReader#gets, or some other methods for reading returns nil.
+  # *   When Zlib::GzipFile#close method is called after the object reaches the
+  #     end of file.
+  # *   When Zlib::GzipReader#unused method is called after the object reaches the
+  #     end of file.
+  #
+  #
+  # The rest of the methods are adequately described in their own documentation.
+  #
+  class GzipReader < Zlib::GzipFile
+    include Enumerable[String]
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - Zlib::GzipReader.open(filename) {|gz| ... }
+    # -->
+    # Opens a file specified by `filename` as a gzipped file, and returns a
+    # GzipReader object associated with that file.  Further details of this method
+    # are in Zlib::GzipReader.new and ZLib::GzipFile.wrap.
+    #
+    def self.open: (String filename) { (instance gz) -> void } -> instance
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - Zlib::GzipReader.zcat(io, options = {}, &block) => nil
+    #   - Zlib::GzipReader.zcat(io, options = {}) => string
+    # -->
+    # Decompresses all gzip data in the `io`, handling multiple gzip streams until
+    # the end of the `io`.  There should not be any non-gzip data after the gzip
+    # streams.
+    #
+    # If a block is given, it is yielded strings of uncompressed data, and the
+    # method returns `nil`. If a block is not given, the method returns the
+    # concatenation of all uncompressed data in all gzip streams.
+    #
+    def self.zcat: (IO io, **untyped) -> String
+                 | (IO io, **untyped) { (String chunk) -> void } -> nil
+
+    public
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - each(*args)
+    # -->
+    # See Zlib::GzipReader documentation for a description.
+    #
+    def each: (*untyped) { (String) -> void } -> void
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - each_byte()
+    # -->
+    # See Zlib::GzipReader documentation for a description.
+    #
+    def each_byte: () { (String) -> void } -> void
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - each_char()
+    # -->
+    # See Zlib::GzipReader documentation for a description.
+    #
+    def each_char: () { (String) -> void } -> void
+
+    # <!-- rdoc-file=ext/zlib/zlib.c -->
+    # See Zlib::GzipReader documentation for a description.
+    #
+    def each_line: (*untyped) { (String) -> void } -> void
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - eof()
+    # -->
+    # Returns `true` or `false` whether the stream has reached the end.
+    #
+    def eof: () -> bool
+
+    # <!-- rdoc-file=ext/zlib/zlib.c -->
+    # Returns `true` or `false` whether the stream has reached the end.
+    #
+    def eof?: () -> bool
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - external_encoding()
+    # -->
+    # See Zlib::GzipReader documentation for a description.
+    #
+    def external_encoding: () -> Encoding
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - getbyte()
+    # -->
+    # See Zlib::GzipReader documentation for a description.
+    #
+    def getbyte: () -> Integer?
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - getc()
+    # -->
+    # See Zlib::GzipReader documentation for a description.
+    #
+    def getc: () -> String?
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - gets(*args)
+    # -->
+    # See Zlib::GzipReader documentation for a description. However, note that this
+    # method can return `nil` even if #eof? returns false, unlike the behavior of
+    # File#gets.
+    #
+    def gets: (?String sep, ?Integer limit) -> String?
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - lineno()
+    # -->
+    # The line number of the last row read from this file.
+    #
+    def lineno: () -> Integer
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - lineno=(p1)
+    # -->
+    # Specify line number of the last row read from this file.
+    #
+    def lineno=: (Integer arg0) -> Integer
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - pos()
+    # -->
+    # Total number of output bytes output so far.
+    #
+    def pos: () -> Integer
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - read(p1 = v1)
+    # -->
+    # See Zlib::GzipReader documentation for a description.
+    #
+    def read: (?int? length, ?string outbuf) -> String?
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - readbyte()
+    # -->
+    # See Zlib::GzipReader documentation for a description.
+    #
+    def readbyte: () -> Integer
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - readchar()
+    # -->
+    # See Zlib::GzipReader documentation for a description.
+    #
+    def readchar: () -> String
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - readline(*args)
+    # -->
+    # See Zlib::GzipReader documentation for a description.
+    #
+    def readline: (?String sep, ?Integer limit) -> String
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - readlines(*args)
+    # -->
+    # See Zlib::GzipReader documentation for a description.
+    #
+    def readlines: (?String sep, ?Integer limit) -> ::Array[String]
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - gzipreader.readpartial(maxlen [, outbuf]) => string, outbuf
+    # -->
+    # Reads at most *maxlen* bytes from the gziped stream but it blocks only if
+    # *gzipreader* has no data immediately available. If the optional *outbuf*
+    # argument is present, it must reference a String, which will receive the data.
+    # It raises `EOFError` on end of file.
+    #
+    def readpartial: (int maxlen, ?string outbuf) -> String
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - rewind()
+    # -->
+    # Resets the position of the file pointer to the point created the GzipReader
+    # object.  The associated IO object needs to respond to the `seek` method.
+    #
+    def rewind: () -> Integer
+
+    # <!-- rdoc-file=ext/zlib/zlib.c -->
+    # Total number of output bytes output so far.
+    #
+    def tell: () -> Integer
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - ungetbyte(p1)
+    # -->
+    # See Zlib::GzipReader documentation for a description.
+    #
+    def ungetbyte: (String | Integer arg0) -> NilClass
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - ungetc(p1)
+    # -->
+    # See Zlib::GzipReader documentation for a description.
+    #
+    def ungetc: (String arg0) -> NilClass
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - unused()
+    # -->
+    # Returns the rest of the data which had read for parsing gzip format, or `nil`
+    # if the whole gzip file is not parsed yet.
+    #
+    def unused: () -> String?
+
+    private
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - Zlib::GzipReader.new(io, options = {})
+    # -->
+    # Creates a GzipReader object associated with `io`. The GzipReader object reads
+    # gzipped data from `io`, and parses/decompresses it.  The `io` must have a
+    # `read` method that behaves same as the IO#read.
+    #
+    # The `options` hash may be used to set the encoding of the data.
+    # `:external_encoding`, `:internal_encoding` and `:encoding` may be set as in
+    # IO::new.
+    #
+    # If the gzip file header is incorrect, raises an Zlib::GzipFile::Error
+    # exception.
+    #
+    def initialize: (_Reader io, **untyped opts) -> void
+  end
+end

data/stdlib/zlib/0/gzip_writer.rbs

@@ -0,0 +1,237 @@
+# <!-- rdoc-file=ext/zlib/zlib.c -->
+# This module provides access to the [zlib library](http://zlib.net). Zlib is
+# designed to be a portable, free, general-purpose, legally unencumbered -- that
+# is, not covered by any patents -- lossless data-compression library for use on
+# virtually any computer hardware and operating system.
+#
+# The zlib compression library provides in-memory compression and decompression
+# functions, including integrity checks of the uncompressed data.
+#
+# The zlib compressed data format is described in RFC 1950, which is a wrapper
+# around a deflate stream which is described in RFC 1951.
+#
+# The library also supports reading and writing files in gzip (.gz) format with
+# an interface similar to that of IO. The gzip format is described in RFC 1952
+# which is also a wrapper around a deflate stream.
+#
+# The zlib format was designed to be compact and fast for use in memory and on
+# communications channels. The gzip format was designed for single-file
+# compression on file systems, has a larger header than zlib to maintain
+# directory information, and uses a different, slower check method than zlib.
+#
+# See your system's zlib.h for further information about zlib
+#
+# ## Sample usage
+#
+# Using the wrapper to compress strings with default parameters is quite simple:
+#
+#     require "zlib"
+#
+#     data_to_compress = File.read("don_quixote.txt")
+#
+#     puts "Input size: #{data_to_compress.size}"
+#     #=> Input size: 2347740
+#
+#     data_compressed = Zlib::Deflate.deflate(data_to_compress)
+#
+#     puts "Compressed size: #{data_compressed.size}"
+#     #=> Compressed size: 887238
+#
+#     uncompressed_data = Zlib::Inflate.inflate(data_compressed)
+#
+#     puts "Uncompressed data is: #{uncompressed_data}"
+#     #=> Uncompressed data is: The Project Gutenberg EBook of Don Quixote...
+#
+# ## Class tree
+#
+# *   Zlib::Deflate
+# *   Zlib::Inflate
+# *   Zlib::ZStream
+# *   Zlib::Error
+#     *   Zlib::StreamEnd
+#     *   Zlib::NeedDict
+#     *   Zlib::DataError
+#     *   Zlib::StreamError
+#     *   Zlib::MemError
+#     *   Zlib::BufError
+#     *   Zlib::VersionError
+#     *   Zlib::InProgressError
+#
+#
+#
+# (if you have GZIP_SUPPORT)
+# *   Zlib::GzipReader
+# *   Zlib::GzipWriter
+# *   Zlib::GzipFile
+# *   Zlib::GzipFile::Error
+#     *   Zlib::GzipFile::LengthError
+#     *   Zlib::GzipFile::CRCError
+#     *   Zlib::GzipFile::NoFooter
+#
+module Zlib
+  # <!-- rdoc-file=ext/zlib/zlib.c -->
+  # Zlib::GzipWriter is a class for writing gzipped files.  GzipWriter should be
+  # used with an instance of IO, or IO-like, object.
+  #
+  # Following two example generate the same result.
+  #
+  #     Zlib::GzipWriter.open('hoge.gz') do |gz|
+  #       gz.write 'jugemu jugemu gokou no surikire...'
+  #     end
+  #
+  #     File.open('hoge.gz', 'w') do |f|
+  #       gz = Zlib::GzipWriter.new(f)
+  #       gz.write 'jugemu jugemu gokou no surikire...'
+  #       gz.close
+  #     end
+  #
+  # To make like gzip(1) does, run following:
+  #
+  #     orig = 'hoge.txt'
+  #     Zlib::GzipWriter.open('hoge.gz') do |gz|
+  #       gz.mtime = File.mtime(orig)
+  #       gz.orig_name = orig
+  #       gz.write IO.binread(orig)
+  #     end
+  #
+  # NOTE: Due to the limitation of Ruby's finalizer, you must explicitly close
+  # GzipWriter objects by Zlib::GzipWriter#close etc.  Otherwise, GzipWriter will
+  # be not able to write the gzip footer and will generate a broken gzip file.
+  #
+  class GzipWriter < Zlib::GzipFile
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - Zlib::GzipWriter.open(filename, level=nil, strategy=nil) { |gz| ... }
+    # -->
+    # Opens a file specified by `filename` for writing gzip compressed data, and
+    # returns a GzipWriter object associated with that file.  Further details of
+    # this method are found in Zlib::GzipWriter.new and Zlib::GzipFile.wrap.
+    #
+    def self.open: (String filename) { (instance gz) -> void } -> instance
+
+    public
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - <<(p1)
+    # -->
+    # Same as IO.
+    #
+    def <<: (_ToS obj) -> self
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - comment=(p1)
+    # -->
+    # Specify the comment (`str`) in the gzip header.
+    #
+    def comment=: (String arg0) -> void
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - flush(flush=nil)
+    # -->
+    # Flushes all the internal buffers of the GzipWriter object.  The meaning of
+    # `flush` is same as in Zlib::Deflate#deflate.  `Zlib::SYNC_FLUSH` is used if
+    # `flush` is omitted.  It is no use giving flush `Zlib::NO_FLUSH`.
+    #
+    def flush: (?Integer flush) -> String
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - mtime=(p1)
+    # -->
+    # Specify the modification time (`mtime`) in the gzip header. Using an Integer.
+    #
+    # Setting the mtime in the gzip header does not effect the mtime of the file
+    # generated. Different utilities that expand the gzipped files may use the mtime
+    # header. For example the gunzip utility can use the `-N` flag which will set
+    # the resultant file's mtime to the value in the header. By default many tools
+    # will set the mtime of the expanded file to the mtime of the gzipped file, not
+    # the mtime in the header.
+    #
+    # If you do not set an mtime, the default value will be the time when
+    # compression started. Setting a value of 0 indicates no time stamp is
+    # available.
+    #
+    def mtime=: (string | _ToPath | IO file_name) -> Time
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - orig_name=(p1)
+    # -->
+    # Specify the original name (`str`) in the gzip header.
+    #
+    def orig_name=: (String arg0) -> void
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - pos()
+    # -->
+    # Total number of input bytes read so far.
+    #
+    def pos: () -> Integer
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - print(*args)
+    # -->
+    # Same as IO.
+    #
+    def print: (*untyped arg0) -> NilClass
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - printf(*args)
+    # -->
+    # Same as IO.
+    #
+    def printf: (String format_string, *untyped arg0) -> NilClass
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - putc(p1)
+    # -->
+    # Same as IO.
+    #
+    def putc: (Numeric | String arg0) -> untyped
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - puts(*args)
+    # -->
+    # Same as IO.
+    #
+    def puts: (*untyped arg0) -> NilClass
+
+    # <!-- rdoc-file=ext/zlib/zlib.c -->
+    # Total number of input bytes read so far.
+    #
+    def tell: () -> Integer
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - write(*args)
+    # -->
+    # Same as IO.
+    #
+    def write: (*_ToS string) -> Integer
+
+    private
+
+    # <!--
+    #   rdoc-file=ext/zlib/zlib.c
+    #   - Zlib::GzipWriter.new(io, level = nil, strategy = nil, options = {})
+    # -->
+    # Creates a GzipWriter object associated with `io`. `level` and `strategy`
+    # should be the same as the arguments of Zlib::Deflate.new.  The GzipWriter
+    # object writes gzipped data to `io`.  `io` must respond to the `write` method
+    # that behaves the same as IO#write.
+    #
+    # The `options` hash may be used to set the encoding of the data.
+    # `:external_encoding`, `:internal_encoding` and `:encoding` may be set as in
+    # IO::new.
+    #
+    def initialize: (_Writer io, Integer level, Integer strategy, **untyped opts) -> void
+  end
+end