module RBS
  module Unnamed
    # <!-- rdoc-file=io.c -->
    # ## ARGF and `ARGV`
    #
    # The ARGF object works with the array at global variable `ARGV` to make
    # `$stdin` and file streams available in the Ruby program:
    #
    # *   **ARGV** may be thought of as the **argument vector** array.
    #
    #     Initially, it contains the command-line arguments and options that are
    #     passed to the Ruby program; the program can modify that array as it likes.
    #
    # *   **ARGF** may be thought of as the **argument files** object.
    #
    #     It can access file streams and/or the `$stdin` stream, based on what it
    #     finds in `ARGV`. This provides a convenient way for the command line to
    #     specify streams for a Ruby program to read.
    #
    # ## Reading
    #
    # ARGF may read from *source* streams, which at any particular time are
    # determined by the content of `ARGV`.
    #
    # ### Simplest Case
    #
    # When the *very first* ARGF read occurs with an empty `ARGV` (`[]`), the source
    # is `$stdin`:
    #
    # *   File `t.rb`:
    #
    #         p ['ARGV', ARGV]
    #         p ['ARGF.read', ARGF.read]
    #
    # *   Commands and outputs (see below for the content of files `foo.txt` and
    #     `bar.txt`):
    #
    #         $ echo "Open the pod bay doors, Hal." | ruby t.rb
    #         ["ARGV", []]
    #         ["ARGF.read", "Open the pod bay doors, Hal.\n"]
    #
    #         $ cat foo.txt bar.txt | ruby t.rb
    #         ["ARGV", []]
    #         ["ARGF.read", "Foo 0\nFoo 1\nBar 0\nBar 1\nBar 2\nBar 3\n"]
    #
    # ### About the Examples
    #
    # Many examples here assume the existence of files `foo.txt` and `bar.txt`:
    #
    #     $ cat foo.txt
    #     Foo 0
    #     Foo 1
    #     $ cat bar.txt
    #     Bar 0
    #     Bar 1
    #     Bar 2
    #     Bar 3
    #
    # ### Sources in `ARGV`
    #
    # For any ARGF read *except* the [simplest case](rdoc-ref:ARGF@Simplest+Case)
    # (that is, *except* for the *very first* ARGF read with an empty `ARGV`), the
    # sources are found in `ARGV`.
    #
    # ARGF assumes that each element in array `ARGV` is a potential source, and is
    # one of:
    #
    # *   The string path to a file that may be opened as a stream.
    # *   The character `'-'`, meaning stream `$stdin`.
    #
    # Each element that is *not* one of these should be removed from `ARGV` before
    # ARGF accesses that source.
    #
    # In the following example:
    #
    # *   Filepaths `foo.txt` and `bar.txt` may be retained as potential sources.
    # *   Options `--xyzzy` and `--mojo` should be removed.
    #
    # Example:
    #
    # *   File `t.rb`:
    #
    #         # Print arguments (and options, if any) found on command line.
    #         p ['ARGV', ARGV]
    #
    # *   Command and output:
    #
    #         $ ruby t.rb --xyzzy --mojo foo.txt bar.txt
    #         ["ARGV", ["--xyzzy", "--mojo", "foo.txt", "bar.txt"]]
    #
    # ARGF's stream access considers the elements of `ARGV`, left to right:
    #
    # *   File `t.rb`:
    #
    #         p "ARGV: #{ARGV}"
    #         p "Line: #{ARGF.read}" # Read everything from all specified streams.
    #
    # *   Command and output:
    #
    #         $ ruby t.rb foo.txt bar.txt
    #         "ARGV: [\"foo.txt\", \"bar.txt\"]"
    #         "Read: Foo 0\nFoo 1\nBar 0\nBar 1\nBar 2\nBar 3\n"
    #
    # Because the value at `ARGV` is an ordinary array, you can manipulate it to
    # control which sources ARGF considers:
    #
    # *   If you remove an element from `ARGV`, ARGF will not consider the
    #     corresponding source.
    # *   If you add an element to `ARGV`, ARGF will consider the corresponding
    #     source.
    #
    # Each element in `ARGV` is removed when its corresponding source is accessed;
    # when all sources have been accessed, the array is empty:
    #
    # *   File `t.rb`:
    #
    #         until ARGV.empty? && ARGF.eof?
    #           p "ARGV: #{ARGV}"
    #           p "Line: #{ARGF.readline}" # Read each line from each specified stream.
    #         end
    #
    # *   Command and output:
    #
    #         $ ruby t.rb foo.txt bar.txt
    #         "ARGV: [\"foo.txt\", \"bar.txt\"]"
    #         "Line: Foo 0\n"
    #         "ARGV: [\"bar.txt\"]"
    #         "Line: Foo 1\n"
    #         "ARGV: [\"bar.txt\"]"
    #         "Line: Bar 0\n"
    #         "ARGV: []"
    #         "Line: Bar 1\n"
    #         "ARGV: []"
    #         "Line: Bar 2\n"
    #         "ARGV: []"
    #         "Line: Bar 3\n"
    #
    # #### Filepaths in `ARGV`
    #
    # The `ARGV` array may contain filepaths the specify sources for ARGF reading.
    #
    # This program prints what it reads from files at the paths specified on the
    # command line:
    #
    # *   File `t.rb`:
    #
    #         p ['ARGV', ARGV]
    #         # Read and print all content from the specified sources.
    #         p ['ARGF.read', ARGF.read]
    #
    # *   Command and output:
    #
    #         $ ruby t.rb foo.txt bar.txt
    #         ["ARGV", [foo.txt, bar.txt]
    #         ["ARGF.read", "Foo 0\nFoo 1\nBar 0\nBar 1\nBar 2\nBar 3\n"]
    #
    # #### Specifying `$stdin` in `ARGV`
    #
    # To specify stream `$stdin` in `ARGV`, us the character `'-'`:
    #
    # *   File `t.rb`:
    #
    #         p ['ARGV', ARGV]
    #         p ['ARGF.read', ARGF.read]
    #
    # *   Command and output:
    #
    #         $ echo "Open the pod bay doors, Hal." | ruby t.rb -
    #         ["ARGV", ["-"]]
    #         ["ARGF.read", "Open the pod bay doors, Hal.\n"]
    #
    # When no character `'-'` is given, stream `$stdin` is ignored (exception: see
    # [Specifying $stdin in ARGV](rdoc-ref:ARGF@Specifying+-24stdin+in+ARGV)):
    #
    # *   Command and output:
    #
    #         $ echo "Open the pod bay doors, Hal." | ruby t.rb foo.txt bar.txt
    #         "ARGV: [\"foo.txt\", \"bar.txt\"]"
    #         "Read: Foo 0\nFoo 1\nBar 0\nBar 1\nBar 2\nBar 3\n"
    #
    # #### Mixtures and Repetitions in `ARGV`
    #
    # For an ARGF reader, `ARGV` may contain any mixture of filepaths and character
    # `'-'`, including repetitions.
    #
    # #### Modifications to `ARGV`
    #
    # The running Ruby program may make any modifications to the `ARGV` array; the
    # current value of `ARGV` affects ARGF reading.
    #
    # #### Empty `ARGV`
    #
    # For an empty `ARGV`, an ARGF read method either returns `nil` or raises an
    # exception, depending on the specific method.
    #
    # ### More Read Methods
    #
    # As seen above, method ARGF#read reads the content of all sources into a single
    # string. Other ARGF methods provide other ways to access that content; these
    # include:
    #
    # *   Byte access: #each_byte, #getbyte, #readbyte.
    # *   Character access: #each_char, #getc, #readchar.
    # *   Codepoint access: #each_codepoint.
    # *   Line access: #each_line, #gets, #readline, #readlines.
    # *   Source access: #read, #read_nonblock, #readpartial.
    #
    # ### About Enumerable
    #
    # ARGF includes module Enumerable. Virtually all methods in Enumerable call
    # method `#each` in the including class.
    #
    # **Note well**: In ARGF, method #each returns data from the *sources*, *not*
    # from `ARGV`; therefore, for example, `ARGF#entries` returns an array of lines
    # from the sources, not an array of the strings from `ARGV`:
    #
    # *   File `t.rb`:
    #
    #         p ['ARGV', ARGV]
    #         p ['ARGF.entries', ARGF.entries]
    #
    # *   Command and output:
    #
    #         $ ruby t.rb foo.txt bar.txt
    #         ["ARGV", ["foo.txt", "bar.txt"]]
    #         ["ARGF.entries", ["Foo 0\n", "Foo 1\n", "Bar 0\n", "Bar 1\n", "Bar 2\n", "Bar 3\n"]]
    #
    # ## Writing
    #
    # If *inplace mode* is in effect, ARGF may write to target streams, which at any
    # particular time are determined by the content of ARGV.
    #
    # Methods about inplace mode:
    #
    # *   #inplace_mode
    # *   #inplace_mode=
    # *   #to_write_io
    #
    # Methods for writing:
    #
    # *   #print
    # *   #printf
    # *   #putc
    # *   #puts
    # *   #write
    #
    %a{annotate:rdoc:copy:ARGF}
    class ARGFClass
      include Enumerable[String]

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.argv  -> ARGV
      # -->
      # Returns the `ARGV` array, which contains the arguments passed to your script,
      # one per element.
      #
      # For example:
      #
      #     $ ruby argf.rb -v glark.txt
      #
      #     ARGF.argv   #=> ["-v", "glark.txt"]
      #
      %a{annotate:rdoc:copy:ARGF#argv}
      def argv: () -> ::Array[String]

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.binmode  -> ARGF
      # -->
      # Puts ARGF into binary mode. Once a stream is in binary mode, it cannot be
      # reset to non-binary mode. This option has the following effects:
      #
      # *   Newline conversion is disabled.
      # *   Encoding conversion is disabled.
      # *   Content is treated as ASCII-8BIT.
      #
      %a{annotate:rdoc:copy:ARGF#binmode}
      def binmode: () -> self

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.binmode?  -> true or false
      # -->
      # Returns true if ARGF is being read in binary mode; false otherwise. To enable
      # binary mode use ARGF.binmode.
      #
      # For example:
      #
      #     ARGF.binmode?  #=> false
      #     ARGF.binmode
      #     ARGF.binmode?  #=> true
      #
      %a{annotate:rdoc:copy:ARGF#binmode?}
      def binmode?: () -> bool

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.close  -> ARGF
      # -->
      # Closes the current file and skips to the next file in ARGV. If there are no
      # more files to open, just closes the current file. STDIN will not be closed.
      #
      # For example:
      #
      #     $ ruby argf.rb foo bar
      #
      #     ARGF.filename  #=> "foo"
      #     ARGF.close
      #     ARGF.filename  #=> "bar"
      #     ARGF.close
      #
      %a{annotate:rdoc:copy:ARGF#close}
      def close: () -> self

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.closed?  -> true or false
      # -->
      # Returns *true* if the current file has been closed; *false* otherwise. Use
      # ARGF.close to actually close the current file.
      #
      %a{annotate:rdoc:copy:ARGF#closed?}
      def closed?: () -> bool

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.each(sep=$/)             {|line| block }  -> ARGF
      #   - ARGF.each(sep=$/, limit)      {|line| block }  -> ARGF
      #   - ARGF.each(...)                                 -> an_enumerator
      #   - ARGF.each_line(sep=$/)        {|line| block }  -> ARGF
      #   - ARGF.each_line(sep=$/, limit) {|line| block }  -> ARGF
      #   - ARGF.each_line(...)                            -> an_enumerator
      # -->
      # Returns an enumerator which iterates over each line (separated by *sep*, which
      # defaults to your platform's newline character) of each file in `ARGV`. If a
      # block is supplied, each line in turn will be yielded to the block, otherwise
      # an enumerator is returned. The optional *limit* argument is an Integer
      # specifying the maximum length of each line; longer lines will be split
      # according to this limit.
      #
      # This method allows you to treat the files supplied on the command line as a
      # single file consisting of the concatenation of each named file. After the last
      # line of the first file has been returned, the first line of the second file is
      # returned. The ARGF.filename and ARGF.lineno methods can be used to determine
      # the filename of the current line and line number of the whole input,
      # respectively.
      #
      # For example, the following code prints out each line of each named file
      # prefixed with its line number, displaying the filename once per file:
      #
      #     ARGF.each_line do |line|
      #       puts ARGF.filename if ARGF.file.lineno == 1
      #       puts "#{ARGF.file.lineno}: #{line}"
      #     end
      #
      # While the following code prints only the first file's name at first, and the
      # contents with line number counted through all named files.
      #
      #     ARGF.each_line do |line|
      #       puts ARGF.filename if ARGF.lineno == 1
      #       puts "#{ARGF.lineno}: #{line}"
      #     end
      #
      %a{annotate:rdoc:copy:ARGF#each}
      def each: (?String sep, ?Integer limit) { (String line) -> untyped } -> self
              | (?String sep, ?Integer limit) -> ::Enumerator[String, self]

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.each_byte {|byte| block }  -> ARGF
      #   - ARGF.each_byte                  -> an_enumerator
      # -->
      # Iterates over each byte of each file in `ARGV`. A byte is returned as an
      # Integer in the range 0..255.
      #
      # This method allows you to treat the files supplied on the command line as a
      # single file consisting of the concatenation of each named file. After the last
      # byte of the first file has been returned, the first byte of the second file is
      # returned. The ARGF.filename method can be used to determine the filename of
      # the current byte.
      #
      # If no block is given, an enumerator is returned instead.
      #
      # For example:
      #
      #     ARGF.bytes.to_a  #=> [35, 32, ... 95, 10]
      #
      %a{annotate:rdoc:copy:ARGF#each_byte}
      def each_byte: () { (Integer byte) -> untyped } -> self
                   | () -> ::Enumerator[Integer, self]

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.each_char {|char| block }  -> ARGF
      #   - ARGF.each_char                  -> an_enumerator
      # -->
      # Iterates over each character of each file in ARGF.
      #
      # This method allows you to treat the files supplied on the command line as a
      # single file consisting of the concatenation of each named file. After the last
      # character of the first file has been returned, the first character of the
      # second file is returned. The ARGF.filename method can be used to determine the
      # name of the file in which the current character appears.
      #
      # If no block is given, an enumerator is returned instead.
      #
      %a{annotate:rdoc:copy:ARGF#each_char}
      def each_char: () { (String char) -> untyped } -> self
                   | () -> ::Enumerator[String, self]

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.each_codepoint {|codepoint| block }  -> ARGF
      #   - ARGF.each_codepoint                       -> an_enumerator
      # -->
      # Iterates over each codepoint of each file in ARGF.
      #
      # This method allows you to treat the files supplied on the command line as a
      # single file consisting of the concatenation of each named file. After the last
      # codepoint of the first file has been returned, the first codepoint of the
      # second file is returned. The ARGF.filename method can be used to determine the
      # name of the file in which the current codepoint appears.
      #
      # If no block is given, an enumerator is returned instead.
      #
      %a{annotate:rdoc:copy:ARGF#each_codepoint}
      def each_codepoint: () { (Integer codepoint) -> untyped } -> self
                        | () -> ::Enumerator[Integer, self]

      # <!-- rdoc-file=io.c -->
      # Returns an enumerator which iterates over each line (separated by *sep*, which
      # defaults to your platform's newline character) of each file in `ARGV`. If a
      # block is supplied, each line in turn will be yielded to the block, otherwise
      # an enumerator is returned. The optional *limit* argument is an Integer
      # specifying the maximum length of each line; longer lines will be split
      # according to this limit.
      #
      # This method allows you to treat the files supplied on the command line as a
      # single file consisting of the concatenation of each named file. After the last
      # line of the first file has been returned, the first line of the second file is
      # returned. The ARGF.filename and ARGF.lineno methods can be used to determine
      # the filename of the current line and line number of the whole input,
      # respectively.
      #
      # For example, the following code prints out each line of each named file
      # prefixed with its line number, displaying the filename once per file:
      #
      #     ARGF.each_line do |line|
      #       puts ARGF.filename if ARGF.file.lineno == 1
      #       puts "#{ARGF.file.lineno}: #{line}"
      #     end
      #
      # While the following code prints only the first file's name at first, and the
      # contents with line number counted through all named files.
      #
      #     ARGF.each_line do |line|
      #       puts ARGF.filename if ARGF.lineno == 1
      #       puts "#{ARGF.lineno}: #{line}"
      #     end
      #
      %a{annotate:rdoc:copy:ARGF#each_line}
      def each_line: (?String sep, ?Integer limit) { (String line) -> untyped } -> self
                   | (?String sep, ?Integer limit) -> ::Enumerator[String, self]

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.eof?  -> true or false
      #   - ARGF.eof   -> true or false
      # -->
      # Returns true if the current file in ARGF is at end of file, i.e. it has no
      # data to read. The stream must be opened for reading or an IOError will be
      # raised.
      #
      #     $ echo "eof" | ruby argf.rb
      #
      #     ARGF.eof?                 #=> false
      #     3.times { ARGF.readchar }
      #     ARGF.eof?                 #=> false
      #     ARGF.readchar             #=> "\n"
      #     ARGF.eof?                 #=> true
      #
      %a{annotate:rdoc:copy:ARGF#eof}
      def eof: () -> bool

      # <!-- rdoc-file=io.c -->
      # Returns true if the current file in ARGF is at end of file, i.e. it has no
      # data to read. The stream must be opened for reading or an IOError will be
      # raised.
      #
      #     $ echo "eof" | ruby argf.rb
      #
      #     ARGF.eof?                 #=> false
      #     3.times { ARGF.readchar }
      #     ARGF.eof?                 #=> false
      #     ARGF.readchar             #=> "\n"
      #     ARGF.eof?                 #=> true
      #
      %a{annotate:rdoc:copy:ARGF#eof?}
      def eof?: () -> bool

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.external_encoding   -> encoding
      # -->
      # Returns the external encoding for files read from ARGF as an Encoding object.
      # The external encoding is the encoding of the text as stored in a file.
      # Contrast with ARGF.internal_encoding, which is the encoding used to represent
      # this text within Ruby.
      #
      # To set the external encoding use ARGF.set_encoding.
      #
      # For example:
      #
      #     ARGF.external_encoding  #=>  #<Encoding:UTF-8>
      #
      %a{annotate:rdoc:copy:ARGF#external_encoding}
      def external_encoding: () -> Encoding

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.file  -> IO or File object
      # -->
      # Returns the current file as an IO or File object. `$stdin` is returned when
      # the current file is STDIN.
      #
      # For example:
      #
      #     $ echo "foo" > foo
      #     $ echo "bar" > bar
      #
      #     $ ruby argf.rb foo bar
      #
      #     ARGF.file      #=> #<File:foo>
      #     ARGF.read(5)   #=> "foo\nb"
      #     ARGF.file      #=> #<File:bar>
      #
      %a{annotate:rdoc:copy:ARGF#file}
      def file: () -> (IO | File)

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.filename  -> String
      #   - ARGF.path      -> String
      # -->
      # Returns the current filename. "-" is returned when the current file is STDIN.
      #
      # For example:
      #
      #     $ echo "foo" > foo
      #     $ echo "bar" > bar
      #     $ echo "glark" > glark
      #
      #     $ ruby argf.rb foo bar glark
      #
      #     ARGF.filename  #=> "foo"
      #     ARGF.read(5)   #=> "foo\nb"
      #     ARGF.filename  #=> "bar"
      #     ARGF.skip
      #     ARGF.filename  #=> "glark"
      #
      %a{annotate:rdoc:copy:ARGF#filename}
      def filename: () -> String

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.fileno    -> integer
      #   - ARGF.to_i      -> integer
      # -->
      # Returns an integer representing the numeric file descriptor for the current
      # file. Raises an ArgumentError if there isn't a current file.
      #
      #     ARGF.fileno    #=> 3
      #
      %a{annotate:rdoc:copy:ARGF#fileno}
      def fileno: () -> Integer

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.getbyte  -> Integer or nil
      # -->
      # Gets the next 8-bit byte (0..255) from ARGF. Returns `nil` if called at the
      # end of the stream.
      #
      # For example:
      #
      #     $ echo "foo" > file
      #     $ ruby argf.rb file
      #
      #     ARGF.getbyte #=> 102
      #     ARGF.getbyte #=> 111
      #     ARGF.getbyte #=> 111
      #     ARGF.getbyte #=> 10
      #     ARGF.getbyte #=> nil
      #
      %a{annotate:rdoc:copy:ARGF#getbyte}
      def getbyte: () -> Integer?

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.getc  -> String or nil
      # -->
      # Reads the next character from ARGF and returns it as a String. Returns `nil`
      # at the end of the stream.
      #
      # ARGF treats the files named on the command line as a single file created by
      # concatenating their contents. After returning the last character of the first
      # file, it returns the first character of the second file, and so on.
      #
      # For example:
      #
      #     $ echo "foo" > file
      #     $ ruby argf.rb file
      #
      #     ARGF.getc  #=> "f"
      #     ARGF.getc  #=> "o"
      #     ARGF.getc  #=> "o"
      #     ARGF.getc  #=> "\n"
      #     ARGF.getc  #=> nil
      #     ARGF.getc  #=> nil
      #
      %a{annotate:rdoc:copy:ARGF#getc}
      def getc: () -> String?

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.gets(sep=$/ [, getline_args])     -> string or nil
      #   - ARGF.gets(limit [, getline_args])      -> string or nil
      #   - ARGF.gets(sep, limit [, getline_args]) -> string or nil
      # -->
      # Returns the next line from the current file in ARGF.
      #
      # By default lines are assumed to be separated by `$/`; to use a different
      # character as a separator, supply it as a String for the *sep* argument.
      #
      # The optional *limit* argument specifies how many characters of each line to
      # return. By default all characters are returned.
      #
      # See IO.readlines for details about getline_args.
      #
      %a{annotate:rdoc:copy:ARGF#gets}
      def gets: (?String sep, ?Integer limit) -> String?

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.inplace_mode  -> String
      # -->
      # Returns the file extension appended to the names of backup copies of modified
      # files under in-place edit mode. This value can be set using ARGF.inplace_mode=
      # or passing the `-i` switch to the Ruby binary.
      #
      %a{annotate:rdoc:copy:ARGF#inplace_mode}
      def inplace_mode: () -> String?

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.inplace_mode = ext  -> ARGF
      # -->
      # Sets the filename extension for in-place editing mode to the given String. The
      # backup copy of each file being edited has this value appended to its filename.
      #
      # For example:
      #
      #     $ ruby argf.rb file.txt
      #
      #     ARGF.inplace_mode = '.bak'
      #     ARGF.each_line do |line|
      #       print line.sub("foo","bar")
      #     end
      #
      # First, *file.txt.bak* is created as a backup copy of *file.txt*. Then, each
      # line of *file.txt* has the first occurrence of "foo" replaced with "bar".
      #
      %a{annotate:rdoc:copy:ARGF#inplace_mode=}
      def inplace_mode=: (String) -> self

      alias inspect to_s

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.internal_encoding   -> encoding
      # -->
      # Returns the internal encoding for strings read from ARGF as an Encoding
      # object.
      #
      # If ARGF.set_encoding has been called with two encoding names, the second is
      # returned. Otherwise, if `Encoding.default_external` has been set, that value
      # is returned. Failing that, if a default external encoding was specified on the
      # command-line, that value is used. If the encoding is unknown, `nil` is
      # returned.
      #
      %a{annotate:rdoc:copy:ARGF#internal_encoding}
      def internal_encoding: () -> Encoding

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.lineno  -> integer
      # -->
      # Returns the current line number of ARGF as a whole. This value can be set
      # manually with ARGF.lineno=.
      #
      # For example:
      #
      #     ARGF.lineno   #=> 0
      #     ARGF.readline #=> "This is line 1\n"
      #     ARGF.lineno   #=> 1
      #
      %a{annotate:rdoc:copy:ARGF#lineno}
      def lineno: () -> Integer

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.lineno = integer  -> integer
      # -->
      # Sets the line number of ARGF as a whole to the given Integer.
      #
      # ARGF sets the line number automatically as you read data, so normally you will
      # not need to set it explicitly. To access the current line number use
      # ARGF.lineno.
      #
      # For example:
      #
      #     ARGF.lineno      #=> 0
      #     ARGF.readline    #=> "This is line 1\n"
      #     ARGF.lineno      #=> 1
      #     ARGF.lineno = 0  #=> 0
      #     ARGF.lineno      #=> 0
      #
      %a{annotate:rdoc:copy:ARGF#lineno=}
      def lineno=: (Integer) -> untyped

      # <!-- rdoc-file=io.c -->
      # Returns the current filename. "-" is returned when the current file is STDIN.
      #
      # For example:
      #
      #     $ echo "foo" > foo
      #     $ echo "bar" > bar
      #     $ echo "glark" > glark
      #
      #     $ ruby argf.rb foo bar glark
      #
      #     ARGF.filename  #=> "foo"
      #     ARGF.read(5)   #=> "foo\nb"
      #     ARGF.filename  #=> "bar"
      #     ARGF.skip
      #     ARGF.filename  #=> "glark"
      #
      %a{annotate:rdoc:copy:ARGF#path}
      def path: () -> String

      # <!-- rdoc-file=io.c -->
      # Returns the current offset (in bytes) of the current file in ARGF.
      #
      #     ARGF.pos    #=> 0
      #     ARGF.gets   #=> "This is line one\n"
      #     ARGF.pos    #=> 17
      #
      %a{annotate:rdoc:copy:ARGF#pos}
      def pos: () -> Integer

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.pos = position  -> Integer
      # -->
      # Seeks to the position given by *position* (in bytes) in ARGF.
      #
      # For example:
      #
      #     ARGF.pos = 17
      #     ARGF.gets   #=> "This is line two\n"
      #
      %a{annotate:rdoc:copy:ARGF#pos=}
      def pos=: (Integer) -> Integer

      # <!--
      #   rdoc-file=io.c
      #   - print(*objects) -> nil
      # -->
      # Writes the given objects to the stream; returns `nil`. Appends the output
      # record separator `$OUTPUT_RECORD_SEPARATOR` (`$\`), if it is not `nil`. See
      # [Line IO](rdoc-ref:IO@Line+IO).
      #
      # With argument `objects` given, for each object:
      #
      # *   Converts via its method `to_s` if not a string.
      # *   Writes to the stream.
      # *   If not the last object, writes the output field separator
      #     `$OUTPUT_FIELD_SEPARATOR` (`$,`) if it is not `nil`.
      #
      # With default separators:
      #
      #     f = File.open('t.tmp', 'w+')
      #     objects = [0, 0.0, Rational(0, 1), Complex(0, 0), :zero, 'zero']
      #     p $OUTPUT_RECORD_SEPARATOR
      #     p $OUTPUT_FIELD_SEPARATOR
      #     f.print(*objects)
      #     f.rewind
      #     p f.read
      #     f.close
      #
      # Output:
      #
      #     nil
      #     nil
      #     "00.00/10+0izerozero"
      #
      # With specified separators:
      #
      #     $\ = "\n"
      #     $, = ','
      #     f.rewind
      #     f.print(*objects)
      #     f.rewind
      #     p f.read
      #
      # Output:
      #
      #     "0,0.0,0/1,0+0i,zero,zero\n"
      #
      # With no argument given, writes the content of `$_` (which is usually the most
      # recent user input):
      #
      #     f = File.open('t.tmp', 'w+')
      #     gets # Sets $_ to the most recent user input.
      #     f.print
      #     f.close
      #
      %a{annotate:rdoc:copy:ARGF#print}
      def print: (*untyped args) -> nil

      # <!--
      #   rdoc-file=io.c
      #   - printf(format_string, *objects) -> nil
      # -->
      # Formats and writes `objects` to the stream.
      #
      # For details on `format_string`, see [Format
      # Specifications](rdoc-ref:format_specifications.rdoc).
      #
      %a{annotate:rdoc:copy:ARGF#printf}
      def printf: (String format_string, *untyped args) -> nil

      # <!--
      #   rdoc-file=io.c
      #   - putc(object) -> object
      # -->
      # Writes a character to the stream. See [Character
      # IO](rdoc-ref:IO@Character+IO).
      #
      # If `object` is numeric, converts to integer if necessary, then writes the
      # character whose code is the least significant byte; if `object` is a string,
      # writes the first character:
      #
      #     $stdout.putc "A"
      #     $stdout.putc 65
      #
      # Output:
      #
      #     AA
      #
      %a{annotate:rdoc:copy:ARGF#putc}
      def putc: (Numeric | String obj) -> untyped

      # <!--
      #   rdoc-file=io.c
      #   - puts(*objects) -> nil
      # -->
      # Writes the given `objects` to the stream, which must be open for writing;
      # returns `nil`.\ Writes a newline after each that does not already end with a
      # newline sequence. If called without arguments, writes a newline. See [Line
      # IO](rdoc-ref:IO@Line+IO).
      #
      # Note that each added newline is the character `"\n"<//tt>, not the output
      # record separator (<tt>$\`).
      #
      # Treatment for each object:
      #
      # *   String: writes the string.
      # *   Neither string nor array: writes `object.to_s`.
      # *   Array: writes each element of the array; arrays may be nested.
      #
      # To keep these examples brief, we define this helper method:
      #
      #     def show(*objects)
      #       # Puts objects to file.
      #       f = File.new('t.tmp', 'w+')
      #       f.puts(objects)
      #       # Return file content.
      #       f.rewind
      #       p f.read
      #       f.close
      #     end
      #
      #     # Strings without newlines.
      #     show('foo', 'bar', 'baz')     # => "foo\nbar\nbaz\n"
      #     # Strings, some with newlines.
      #     show("foo\n", 'bar', "baz\n") # => "foo\nbar\nbaz\n"
      #
      #     # Neither strings nor arrays:
      #     show(0, 0.0, Rational(0, 1), Complex(9, 0), :zero)
      #     # => "0\n0.0\n0/1\n9+0i\nzero\n"
      #
      #     # Array of strings.
      #     show(['foo', "bar\n", 'baz']) # => "foo\nbar\nbaz\n"
      #     # Nested arrays.
      #     show([[[0, 1], 2, 3], 4, 5])  # => "0\n1\n2\n3\n4\n5\n"
      #
      %a{annotate:rdoc:copy:ARGF#puts}
      def puts: (*untyped obj) -> nil

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.read([length [, outbuf]])    -> string, outbuf, or nil
      # -->
      # Reads *length* bytes from ARGF. The files named on the command line are
      # concatenated and treated as a single file by this method, so when called
      # without arguments the contents of this pseudo file are returned in their
      # entirety.
      #
      # *length* must be a non-negative integer or `nil`.
      #
      # If *length* is a positive integer, `read` tries to read *length* bytes without
      # any conversion (binary mode). It returns `nil` if an EOF is encountered before
      # anything can be read. Fewer than *length* bytes are returned if an EOF is
      # encountered during the read. In the case of an integer *length*, the resulting
      # string is always in ASCII-8BIT encoding.
      #
      # If *length* is omitted or is `nil`, it reads until EOF and the encoding
      # conversion is applied, if applicable. A string is returned even if EOF is
      # encountered before any data is read.
      #
      # If *length* is zero, it returns an empty string (`""`).
      #
      # If the optional *outbuf* argument is present, it must reference a String,
      # which will receive the data. The *outbuf* will contain only the received data
      # after the method call even if it is not empty at the beginning.
      #
      # For example:
      #
      #     $ echo "small" > small.txt
      #     $ echo "large" > large.txt
      #     $ ./glark.rb small.txt large.txt
      #
      #     ARGF.read      #=> "small\nlarge"
      #     ARGF.read(200) #=> "small\nlarge"
      #     ARGF.read(2)   #=> "sm"
      #     ARGF.read(0)   #=> ""
      #
      # Note that this method behaves like the fread() function in C. This means it
      # retries to invoke read(2) system calls to read data with the specified length.
      # If you need the behavior like a single read(2) system call, consider
      # ARGF#readpartial or ARGF#read_nonblock.
      #
      %a{annotate:rdoc:copy:ARGF#read}
      def read: (?int? length, ?string outbuf) -> String?

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.read_nonblock(maxlen[, options])              -> string
      #   - ARGF.read_nonblock(maxlen, outbuf[, options])      -> outbuf
      # -->
      # Reads at most *maxlen* bytes from the ARGF stream in non-blocking mode.
      #
      %a{annotate:rdoc:copy:ARGF#read_nonblock}
      def read_nonblock: (int maxlen, ?string buf, **untyped options) -> String

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.readbyte  -> Integer
      # -->
      # Reads the next 8-bit byte from ARGF and returns it as an Integer. Raises an
      # EOFError after the last byte of the last file has been read.
      #
      # For example:
      #
      #     $ echo "foo" > file
      #     $ ruby argf.rb file
      #
      #     ARGF.readbyte  #=> 102
      #     ARGF.readbyte  #=> 111
      #     ARGF.readbyte  #=> 111
      #     ARGF.readbyte  #=> 10
      #     ARGF.readbyte  #=> end of file reached (EOFError)
      #
      %a{annotate:rdoc:copy:ARGF#readbyte}
      def readbyte: () -> Integer

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.readchar  -> String or nil
      # -->
      # Reads the next character from ARGF and returns it as a String. Raises an
      # EOFError after the last character of the last file has been read.
      #
      # For example:
      #
      #     $ echo "foo" > file
      #     $ ruby argf.rb file
      #
      #     ARGF.readchar  #=> "f"
      #     ARGF.readchar  #=> "o"
      #     ARGF.readchar  #=> "o"
      #     ARGF.readchar  #=> "\n"
      #     ARGF.readchar  #=> end of file reached (EOFError)
      #
      %a{annotate:rdoc:copy:ARGF#readchar}
      def readchar: () -> String

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.readline(sep=$/)     -> string
      #   - ARGF.readline(limit)      -> string
      #   - ARGF.readline(sep, limit) -> string
      # -->
      # Returns the next line from the current file in ARGF.
      #
      # By default lines are assumed to be separated by `$/`; to use a different
      # character as a separator, supply it as a String for the *sep* argument.
      #
      # The optional *limit* argument specifies how many characters of each line to
      # return. By default all characters are returned.
      #
      # An EOFError is raised at the end of the file.
      #
      %a{annotate:rdoc:copy:ARGF#readline}
      def readline: (?String sep, ?Integer limit) -> String

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.readlines(sep = $/, chomp: false)   -> array
      #   - ARGF.readlines(limit, chomp: false)      -> array
      #   - ARGF.readlines(sep, limit, chomp: false) -> array
      #   - ARGF.to_a(sep = $/, chomp: false)   -> array
      #   - ARGF.to_a(limit, chomp: false)      -> array
      #   - ARGF.to_a(sep, limit, chomp: false) -> array
      # -->
      # Reads each file in ARGF in its entirety, returning an Array containing lines
      # from the files. Lines are assumed to be separated by *sep*.
      #
      #     lines = ARGF.readlines
      #     lines[0]                #=> "This is line one\n"
      #
      # See `IO.readlines` for a full description of all options.
      #
      %a{annotate:rdoc:copy:ARGF#readlines}
      def readlines: (?String sep, ?Integer limit) -> ::Array[String]

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.readpartial(maxlen)              -> string
      #   - ARGF.readpartial(maxlen, outbuf)      -> outbuf
      # -->
      # Reads at most *maxlen* bytes from the ARGF stream.
      #
      # If the optional *outbuf* argument is present, it must reference a String,
      # which will receive the data. The *outbuf* will contain only the received data
      # after the method call even if it is not empty at the beginning.
      #
      # It raises EOFError on end of ARGF stream. Since ARGF stream is a concatenation
      # of multiple files, internally EOF is occur for each file. ARGF.readpartial
      # returns empty strings for EOFs except the last one and raises EOFError for the
      # last one.
      #
      %a{annotate:rdoc:copy:ARGF#readpartial}
      def readpartial: (int maxlen, ?string outbuf) -> String

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.rewind   -> 0
      # -->
      # Positions the current file to the beginning of input, resetting ARGF.lineno to
      # zero.
      #
      #     ARGF.readline   #=> "This is line one\n"
      #     ARGF.rewind     #=> 0
      #     ARGF.lineno     #=> 0
      #     ARGF.readline   #=> "This is line one\n"
      #
      %a{annotate:rdoc:copy:ARGF#rewind}
      def rewind: () -> Integer

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.seek(amount, whence=IO::SEEK_SET)  -> 0
      # -->
      # Seeks to offset *amount* (an Integer) in the ARGF stream according to the
      # value of *whence*. See IO#seek for further details.
      #
      %a{annotate:rdoc:copy:ARGF#seek}
      def seek: (Integer amount, ?Integer whence) -> Integer

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.set_encoding(ext_enc)                -> ARGF
      #   - ARGF.set_encoding("ext_enc:int_enc")      -> ARGF
      #   - ARGF.set_encoding(ext_enc, int_enc)       -> ARGF
      #   - ARGF.set_encoding("ext_enc:int_enc", opt) -> ARGF
      #   - ARGF.set_encoding(ext_enc, int_enc, opt)  -> ARGF
      # -->
      # If single argument is specified, strings read from ARGF are tagged with the
      # encoding specified.
      #
      # If two encoding names separated by a colon are given, e.g. "ascii:utf-8", the
      # read string is converted from the first encoding (external encoding) to the
      # second encoding (internal encoding), then tagged with the second encoding.
      #
      # If two arguments are specified, they must be encoding objects or encoding
      # names. Again, the first specifies the external encoding; the second specifies
      # the internal encoding.
      #
      # If the external encoding and the internal encoding are specified, the optional
      # Hash argument can be used to adjust the conversion process. The structure of
      # this hash is explained in the String#encode documentation.
      #
      # For example:
      #
      #     ARGF.set_encoding('ascii')         # Tag the input as US-ASCII text
      #     ARGF.set_encoding(Encoding::UTF_8) # Tag the input as UTF-8 text
      #     ARGF.set_encoding('utf-8','ascii') # Transcode the input from US-ASCII
      #                                        # to UTF-8.
      #
      %a{annotate:rdoc:copy:ARGF#set_encoding}
      def set_encoding: (String | Encoding ext_or_ext_int_enc, ?String | Encoding int_enc) -> self

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.skip  -> ARGF
      # -->
      # Sets the current file to the next file in ARGV. If there aren't any more files
      # it has no effect.
      #
      # For example:
      #
      #     $ ruby argf.rb foo bar
      #     ARGF.filename  #=> "foo"
      #     ARGF.skip
      #     ARGF.filename  #=> "bar"
      #
      %a{annotate:rdoc:copy:ARGF#skip}
      def skip: () -> self

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.tell  -> Integer
      #   - ARGF.pos   -> Integer
      # -->
      # Returns the current offset (in bytes) of the current file in ARGF.
      #
      #     ARGF.pos    #=> 0
      #     ARGF.gets   #=> "This is line one\n"
      #     ARGF.pos    #=> 17
      #
      %a{annotate:rdoc:copy:ARGF#tell}
      def tell: () -> Integer

      # <!-- rdoc-file=io.c -->
      # Reads each file in ARGF in its entirety, returning an Array containing lines
      # from the files. Lines are assumed to be separated by *sep*.
      #
      #     lines = ARGF.readlines
      #     lines[0]                #=> "This is line one\n"
      #
      # See `IO.readlines` for a full description of all options.
      #
      %a{annotate:rdoc:copy:ARGF#to_a}
      def to_a: (?String sep, ?Integer limit) -> ::Array[String]

      # <!-- rdoc-file=io.c -->
      # Returns an integer representing the numeric file descriptor for the current
      # file. Raises an ArgumentError if there isn't a current file.
      #
      #     ARGF.fileno    #=> 3
      #
      %a{annotate:rdoc:copy:ARGF#to_i}
      def to_i: () -> Integer

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.to_io     -> IO
      # -->
      # Returns an IO object representing the current file. This will be a File object
      # unless the current file is a stream such as STDIN.
      #
      # For example:
      #
      #     ARGF.to_io    #=> #<File:glark.txt>
      #     ARGF.to_io    #=> #<IO:<STDIN>>
      #
      %a{annotate:rdoc:copy:ARGF#to_io}
      def to_io: () -> IO

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.to_s  -> String
      # -->
      # Returns "ARGF".
      #
      %a{annotate:rdoc:copy:ARGF#to_s}
      def to_s: () -> String

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.to_write_io  -> io
      # -->
      # Returns IO instance tied to *ARGF* for writing if inplace mode is enabled.
      #
      %a{annotate:rdoc:copy:ARGF#to_write_io}
      def to_write_io: () -> IO

      # <!--
      #   rdoc-file=io.c
      #   - ARGF.write(*objects)  -> integer
      # -->
      # Writes each of the given `objects` if inplace mode.
      #
      %a{annotate:rdoc:copy:ARGF#write}
      def write: (_ToS string) -> Integer

      private

      %a{annotate:rdoc:copy:ARGF#initialize}
      def initialize: (*String argv) -> void

      %a{annotate:rdoc:copy:ARGF#initialize_copy}
      def initialize_copy: (self orig) -> self
    end
  end
end
