%a{annotate:rdoc:skip}
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

    # <!--
    #   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
