io-like 0.3.1 → 0.4.0.pre1

data/lib/io/like.rb

@@ -1,1455 +1,2057 @@
-class IO # :nodoc:
-  # IO::Like is a module which provides most of the basic input and output
-  # functions of IO objects using methods named _unbuffered_read_,
-  # _unbuffered_write_, and _unbuffered_seek_.
-  #
-  # == Readers
-  #
-  # In order to use this module to provide input methods, a class which
-  # includes it must provide the _unbuffered_read_ method which takes one
-  # argument, a length, as follows:
-  #
-  #   def unbuffered_read(length)
-  #     ...
-  #   end
-  #
-  # This method must return at most _length_ bytes as a String, raise EOFError
-  # if reading begins at the end of data, and raise SystemCallError on error.
-  # Errno::EAGAIN should be raised if there is no data to return immediately and
-  # the read operation should not block.  Errno::EINTR should be raised if the
-  # read operation is interrupted before any data is read.
-  #
-  # == Writers
-  #
-  # In order to use this module to provide output methods, a class which
-  # includes it must provide the _unbuffered_write_ method which takes a single
-  # string argument as follows:
-  #
-  #   def unbuffered_write(string)
-  #     ...
-  #   end
-  #
-  # This method must either return the number of bytes written to the stream,
-  # which may be less than the length of _string_ in bytes, OR must raise an
-  # instance of SystemCallError.  Errno::EAGAIN should be raised if no data can
-  # be written immediately and the write operation should not block.
-  # Errno::EINTR should be raised if the write operation is interrupted before
-  # any data is written.
-  #
-  # == Seekers
-  #
-  # In order to use this module to provide seeking methods, a class which
-  # includes it must provide the _unbuffered_seek_ method which takes two
-  # required arguments, an offset and a start position, as follows:
-  #
-  #   def unbuffered_seek(offset, whence)
-  #     ...
-  #   end
-  #
-  # This method must return the new position within the data stream relative to
-  # the beginning of the stream and should raise SystemCallError on error.
-  # _offset_ can be any integer and _whence_ can be any of IO::SEEK_SET,
-  # IO::SEEK_CUR, or IO::SEEK_END.  They are interpreted together as follows:
-  #
-  #         whence | resulting position
-  #   -------------+------------------------------------------------------------
-  #   IO::SEEK_SET | Add offset to the position of the beginning of the stream.
-  #   -------------+------------------------------------------------------------
-  #   IO::SEEK_CUR | Add offset to the current position of the stream.
-  #   -------------+------------------------------------------------------------
-  #   IO::SEEK_END | Add offset to the position of the end of the stream.
-  #
-  # == Duplexed Streams
-  #
-  # In order to create a duplexed stream where writing and reading happen
-  # independently of each other, override the #duplexed? method to return
-  # +true+ and then provide the _unbuffered_read_ and _unbuffered_write_
-  # methods.  Do *NOT* provide an _unbuffered_seek_ method or the contents of
-  # the internal read and write buffers may be lost unexpectedly.
-  # ---
-  # <b>NOTE:</b> Due to limitations of Ruby's finalizer, IO::Like#close is not
-  # automatically called when the object is garbage collected, so it must be
-  # explicitly called when the object is no longer needed or risk losing
-  # whatever data remains in the internal write buffer.
-  module Like
-    include Enumerable
-
-    # call-seq:
-    #   ios << obj           -> ios
-    #
-    # Writes _obj_ to the stream using #write and returns _ios_.  _obj_ is
-    # converted to a String using _to_s_.
-    def <<(obj)
-      write(obj)
-      self
-    end
-
-    # call-seq:
-    #   ios.binmode          -> ios
-    #
-    # Returns +self+.  Just for compatibility with IO.
-    def binmode
-      self
+# frozen_string_literal: true
+
+require 'io/like_helpers/duplexed_io'
+require 'io/like_helpers/io'
+require 'io/like_helpers/io_wrapper'
+require 'io/like_helpers/pipeline'
+require 'io/like_helpers/ruby_facts'
+
+##
+# All the goodies for this library go in this namespace.  It's probably a bad
+# idea.
+class IO
+
+##
+# This is a wrapper class that provides the same instance methods as the IO
+# class for simpler delegates given to it.
+class Like < LikeHelpers::DuplexedIO
+  include LikeHelpers::RubyFacts
+  include Enumerable
+
+  ##
+  # This is used by #puts as the separator between all arguments.
+  ORS = "\n"
+
+  ##
+  # Creates a new instance of this class.
+  #
+  # @param delegate_r [LikeHelpers::AbstractIO] delegate for read operations
+  # @param delegate_w [LikeHelpers::AbstractIO] delegate for write operations
+  # @param autoclose [Boolean] when `true` close the delegate(s) when this
+  #   stream is closed
+  # @param binmode [Boolean] when `true` suppresses EOL <-> CRLF conversion on
+  #   Windows and sets external encoding to ASCII-8BIT unless explicitly
+  #   specified
+  # @param encoding [Encoding, String] the external encoding or both the
+  #   external and internal encoding if specified as `"ext_enc:int_enc"`
+  # @param encoding_opts [Hash] options to be passed to String#encode
+  # @param external_encoding [Encoding, String] the external encoding
+  # @param internal_encoding [Encoding, String] the internal encoding
+  # @param sync [Boolean] when `true` causes write operations to bypass internal
+  #   buffering
+  # @param pid [Integer] the return value for {#pid}
+  def initialize(
+    delegate_r,
+    delegate_w = delegate_r,
+    autoclose: true,
+    binmode: false,
+    encoding: nil,
+    encoding_opts: {},
+    external_encoding: nil,
+    internal_encoding: nil,
+    sync: false,
+    pid: nil,
+    pipeline_class: LikeHelpers::Pipeline
+  )
+    if encoding
+      if external_encoding
+        warn("Ignoring encoding parameter '#{encoding}': external_encoding is used")
+        encoding = nil
+      elsif internal_encoding
+        warn("Ignoring encoding parameter '#{encoding}': internal_encoding is used")
+        encoding = nil
+      end
     end
 
-    # call-seq:
-    #   ios.close            -> nil
-    #
-    # Arranges for #closed? to return +true+.  Raises IOError if #closed?
-    # already returns +true+.  For duplexed objects, calls #close_read and
-    # #close_write.  For non-duplexed objects, calls #flush if #writable?
-    # returns +true+ and then sets a flag so that #closed? will return +true+.
-    def close
-      raise IOError, 'closed stream' if closed?
-      __io_like__close_read
-      flush if writable?
-      __io_like__close_write
-      nil
+    if external_encoding
+      external_encoding = Encoding.find(external_encoding)
+    elsif internal_encoding
+      external_encoding = Encoding.default_external
     end
 
-    # call-seq:
-    #   ios.close_read       -> nil
-    #
-    # Closes the read end of a duplexed object or the whole object if the object
-    # is read-only.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError for duplexed
-    # objects if called more than once.  Raises IOError for non-duplexed objects
-    # if #writable? returns +true+.
-    def close_read
-      raise IOError, 'closed stream' if closed?
-      if __io_like__closed_read? || ! duplexed? && writable? then
-        raise IOError, 'closing non-duplex IO for reading'
-      end
-      if duplexed? then
-        __io_like__close_read
+    @pipeline_class = pipeline_class
+    pipeline_r = @pipeline_class.new(delegate_r, autoclose: autoclose)
+    pipeline_w = delegate_r == delegate_w ?
+      pipeline_r :
+      @pipeline_class.new(delegate_w, autoclose: autoclose)
+
+    super(pipeline_r, pipeline_w)
+
+    # NOTE:
+    # Binary mode must be set before the encoding in order to allow any
+    # explicitly set external encoding to override the implicit ASCII-8BIT
+    # encoding when binmode is set.
+    @binmode = false
+    self.binmode if binmode
+    if ! binmode || encoding || external_encoding || internal_encoding
+      if encoding && ! (Encoding === encoding) && encoding =~ /^bom\|/i
+        if ! set_encoding_by_bom
+          set_encoding(encoding.to_s[4..-1], **encoding_opts)
+        end
       else
-        close
+        set_encoding(
+          encoding || external_encoding, internal_encoding, **encoding_opts
+        )
       end
-      nil
     end
 
-    # call-seq:
-    #   ios.close_write      -> nil
-    #
-    # Closes the write end of a duplexed object or the whole object if the
-    # object is write-only.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError for duplexed
-    # objects if called more than once.  Raises IOError for non-duplexed objects
-    # if #readable? returns +true+.
-    def close_write
-      raise IOError, 'closed stream' if closed?
-      if __io_like__closed_write? || ! duplexed? && readable? then
-        raise IOError, 'closing non-duplex IO for reading'
-      end
-      if duplexed? then
-        flush
-        __io_like__close_write
-      else
-        close
-      end
-      nil
-    end
+    @pid = nil == pid ? pid : ensure_integer(pid)
 
-    # call-seq:
-    #   ios.closed?          -> true or false
-    #
-    # Returns +true+ if this object is closed or otherwise unusable for read and
-    # write operations.
-    def closed?
-      (__io_like__closed_read? || ! readable?) &&
-      (__io_like__closed_write? || ! writable?)
-    end
+    self.sync = sync
 
-    # call-seq:
-    #   ios.duplexed?        -> true or false
-    #
-    # Returns +false+.  Override this to return +true+ when creating duplexed
-    # IO objects.
-    def duplexed?
-      false
-    end
+    @skip_duplexed_check = false
+    @readable = @writable = nil
+  end
 
-    # call-seq:
-    #   ios.each_byte { |byte| block } -> ios
-    #
-    # Reads each byte (0..255) from the stream using #getc and calls the given
-    # block once for each byte, passing the byte as an argument.
-    #
-    # <b>NOTE:</b> This method ignores Errno::EAGAIN and Errno::EINTR raised by
-    # #unbuffered_read.  Therefore, this method always blocks.  Aside from that
-    # exception and the conversion of EOFError results into +nil+ results, this
-    # method will also raise the same errors and block at the same times as
-    # #unbuffered_read.
-    def each_byte
-      while (byte = getc) do
-        yield(byte)
-      end
-      self
+  ##
+  # Writes `obj` to the stream using {#write}.
+  #
+  # @param obj converted to a String using its #to_s method
+  #
+  # @return [self]
+  def <<(obj)
+    write(obj)
+    self
+  end
+
+  ##
+  # Puts the stream into binary mode.
+  #
+  # Once a stream is in binary mode, it cannot be reset to nonbinary mode.
+  # * Newline conversion disabled
+  # * Encoding conversion disabled
+  # * Content is treated as ASCII-8BIT
+  #
+  # @return [self]
+  #
+  # @raise [IOError] if the stream is closed
+  def binmode
+    assert_open
+    @binmode = true
+    set_encoding(Encoding::BINARY)
+    self
+  end
+
+  ##
+  # Returns `true` if the stream is in binary mode and `false` otherwise.
+  #
+  # @return [Boolean]
+  #
+  # @raise [IOError] if the stream is closed
+  def binmode?
+    assert_open
+    @binmode
+  end
+
+  if RBVER_LT_3_0
+  ##
+  # @deprecated Use {#each_byte} instead.
+  #
+  # @version < Ruby 3.0
+  def bytes(&block)
+    warn('warning: IO#bytes is deprecated; use #each_byte instead')
+    each_byte(&block)
+  end
+
+  ##
+  # @deprecated Use {#each_char} instead.
+  #
+  # @version < Ruby 3.0
+  def chars(&block)
+    warn('warning: IO#chars is deprecated; use #each_char instead')
+    each_char(&block)
+  end
+  end
+
+  ##
+  # Closes the stream, flushing any buffered data first.
+  #
+  # This always blocks when buffered data needs to be written, even when the
+  # stream is in nonblocking mode.
+  #
+  # @return [nil]
+  def close
+    @skip_duplexed_check = true
+    super
+
+    nil
+  ensure
+    @skip_duplexed_check = false
+  end
+
+  ##
+  # Closes the read side of duplexed streams and closes the entire stream for
+  # read-only, non-duplexed streams.
+  #
+  # @return [nil]
+  #
+  # @raise [IOError] if the stream is non-duplexed and writable
+  def close_read
+    return if closed_read?
+
+    if ! @skip_duplexed_check && ! duplexed? && writable?
+      raise IOError, 'closing non-duplex IO for reading'
     end
 
-    # call-seq:
-    #   ios.each_line(sep_string = $/) { |line| block } -> ios
-    #   ios.each(sep_string = $/) { |line| block } -> ios
-    #
-    # Reads each line from the stream using #gets and calls the given block once
-    # for each line, passing the line as an argument.
-    #
-    # <b>NOTE:</b> When _sep_string_ is not +nil+, this method ignores
-    # Errno::EAGAIN and Errno::EINTR raised by #unbuffered_read.  Therefore,
-    # this method always blocks.  Aside from that exception and the conversion
-    # of EOFError results into +nil+ results, this method will also raise the
-    # same errors and block at the same times as #unbuffered_read.
-    def each_line(sep_string = $/)
-      while (line = gets(sep_string)) do
-        yield(line)
-      end
-      self
+    super
+
+    nil
+  end
+
+  ##
+  # Closes the write side of duplexed streams and closes the entire stream for
+  # write-only, non-duplexed streams.
+  #
+  # @return [nil]
+  #
+  # @raise [IOError] if the stream is non-duplexed and readable
+  def close_write
+    return if closed_write?
+
+    if ! @skip_duplexed_check && ! duplexed? && readable?
+      raise IOError, 'closing non-duplex IO for writing'
     end
-    alias :each :each_line
-
-    # call-seq:
-    #   ios.eof?             -> true or false
-    #   ios.eof              -> true or false
-    #
-    # Returns +true+ if there is no more data to read.
-    #
-    # This works by using #getc to fetch the next character and using #ungetc to
-    # put the character back if one was fetched.  It may be a good idea to
-    # replace this implementation in derivative classes.
-    #
-    # <b>NOTE:</b> This method ignores Errno::EAGAIN and Errno::EINTR raised by
-    # #unbuffered_read.  Therefore, this method always blocks.  Aside from that
-    # exception and the conversion of EOFError results into +nil+ results, this
-    # method will also raise the same errors and block at the same times as
-    # #unbuffered_read.
-    def eof?
-      if (char = getc) then
-        ungetc(char)
-        return false
-      end
-      true
+
+    flush if writable?
+    super
+
+    nil
+  end
+
+  if RBVER_LT_3_0
+  ##
+  # @deprecated Use {#each_codepoint} instead.
+  #
+  # @version < Ruby 3.0
+  def codepoints(&block)
+    warn('warning: IO#codepoints is deprecated; use #each_codepoint instead')
+    each_codepoint(&block)
+  end
+  end
+
+  ##
+  # @overload each_byte
+  #   @return [Enumerator] an enumerator that iterates over each byte in the
+  #     stream
+  #
+  # @overload each_byte
+  #   Iterates over each byte in the stream, yielding each byte to the given
+  #   block.
+  #
+  #   @yieldparam byte [Integer] the next byte from the stream
+  #
+  #   @return [self]
+  #
+  # @raise [IOError] if the stream is not open for reading
+  def each_byte
+    return to_enum(:each_byte) unless block_given?
+
+    while (byte = getbyte) do
+      yield(byte)
     end
-    alias :eof :eof?
-
-    # call-seq:
-    #   ios.fcntl
-    #
-    # Raises NotImplementedError.
-    def fcntl(*args)
-      raise NotImplementedError, 'not implemented'
+    self
+  end
+
+  ##
+  # @overload each_char
+  #   @return [Enumerator] an enumerator that iterates over each character in
+  #     the stream
+  #
+  # @overload each_char
+  #   Iterates over each character in the stream, yielding each character to the
+  #   given block.
+  #
+  #   @yieldparam char [String] the next character from the stream
+  #
+  #   @return [self]
+  #
+  # @raise [IOError] if the stream is not open for reading
+  def each_char
+    return to_enum(:each_char) unless block_given?
+
+    while char = getc do
+      yield(char)
     end
+    self
+  end
+
+  ##
+  # @overload each_codepoint
+  #   @return [Enumerator] an enumerator that iterates over each Integer ordinal
+  #     of each character in the stream
+  #
+  # @overload each_codepoint
+  #   Iterates over each Integer ordinal of each character in the stream,
+  #   yielding each ordinal to the given block.
+  #
+  #   @yieldparam codepoint [Integer] the Integer ordinal of the next character
+  #     from the stream
+  #
+  #   @return [self]
+  #
+  # @raise [IOError] if the stream is not open for reading
+  def each_codepoint
+    return to_enum(:each_codepoint) unless block_given?
+
+    each_char { |c| yield(c.codepoints[0]) }
+    self
+  end
 
-    # call-seq:
-    #   ios.fileno           -> nil
-    #
-    # Returns +nil+.  Just for compatibility with IO.
-    def fileno
-      nil
+  ##
+  # @overload each_line(separator = $/, limit = nil, chomp: false)
+  #   @param separator [String, nil] a non-empty String that separates each
+  #     line, an empty String that equates to 2 or more successive newlines as
+  #     the separator, or `nil` to indicate reading all remaining data
+  #   @param limit [Integer, nil] an Integer limiting the number of bytes
+  #     returned in each line or `nil` to indicate no limit
+  #   @param chomp [Boolean] when `true` trailing newlines and carriage returns
+  #     will be removed from each line
+  #
+  #   @return [Enumerator] an enumerator that iterates over each line in the
+  #     stream
+  #
+  # @overload each_line(limit, chomp: false)
+  #   @param limit [Integer] an Integer limiting the number of bytes returned in
+  #     each line or `nil` to indicate no limit
+  #   @param chomp [Boolean] when `true` trailing newlines and carriage returns
+  #     will be removed from each line
+  #
+  #   @return [Enumerator] an enumerator that iterates over each line in the
+  #     stream where each line is separated by `$/`
+  #
+  # @overload each_line(separator = $/, limit = nil, chomp: false)
+  #   Iterates over each line in the stream, yielding each line to the given
+  #   block.
+  #
+  #   @param separator [String, nil] a non-empty String that separates each
+  #     line, an empty String that equates to 2 or more successive newlines as
+  #     the separator, or `nil` to indicate reading all remaining data
+  #   @param limit [Integer, nil] an Integer limiting the number of bytes
+  #     returned in each line or `nil` to indicate no limit
+  #   @param chomp [Boolean] when `true` trailing newlines and carriage returns
+  #     will be removed from each line
+  #
+  #   @yieldparam line [String] a line from the stream
+  #
+  #   @return [self]
+  #
+  # @overload each_line(limit, chomp: false)
+  #   Iterates over each line in the stream, where each line is separated by
+  #   `$/`, yielding each line to the given block.
+  #
+  #   @param limit [Integer] an Integer limiting the number of bytes returned in
+  #     each line or `nil` to indicate no limit
+  #   @param chomp [Boolean] when `true` trailing newlines and carriage returns
+  #     will be removed from each line
+  #
+  #   @yieldparam line [String] a line from the stream
+  #
+  #   @return [self]
+  #
+  # @raise [IOError] if the stream is not open for reading
+  def each_line(*args, **opts)
+    unless block_given?
+      return to_enum(:each_line, *args, **opts)
     end
 
-    # call-seq:
-    #   ios.fill_size        -> integer
-    #
-    # Returns the number of bytes to read as a block whenever the internal
-    # buffer needs to be refilled.  Unless set explicitly via #fill_size=, this
-    # defaults to 4096.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError if the
-    # stream is not opened for reading.
-    def fill_size
-      raise IOError, 'closed stream' if closed?
-      raise IOError, 'not opened for reading' unless readable?
-
-      @__io_like__fill_size ||= 4096
+    sep_string, limit = parse_readline_args(*args)
+    raise ArgumentError, 'invalid limit: 0 for each_line' if limit == 0
+
+    while (line = gets(sep_string, limit, **opts)) do
+      yield(line)
     end
+    self
+  end
+  alias_method :each, :each_line
 
-    # call-seq:
-    #   ios.fill_size = integer -> integer
-    #
-    # Sets the number of bytes to read as a block whenever the internal read
-    # buffer needs to be refilled.  The new value must be a number greater than
-    # or equal to 0.  Setting this to 0 effectively disables buffering.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError if the
-    # stream is not opened for reading.
-    def fill_size=(fill_size)
-      raise IOError, 'closed stream' if closed?
-      raise IOError, 'not opened for reading' unless readable?
-
-      unless fill_size >= 0 then
-        raise ArgumentError, "non-positive fill_size #{fill_size} given"
-      end
-      @__io_like__fill_size = fill_size
+  ##
+  # Returns `true` if the end of the stream has been reached and `false`
+  # otherwise.
+  #
+  # @note This method will block if reading the stream blocks.
+  # @note This method relies on buffered operations, so using it in conjuction
+  #   with {#sysread} will be complicated at best.
+  #
+  # @return [Boolean]
+  #
+  # @raise [IOError] if the stream is not open for reading
+  def eof?
+    if byte = getbyte
+      ungetbyte(byte)
+      return false
     end
+    true
+  end
+  alias_method :eof, :eof?
 
-    # call-seq:
-    #   ios.flush            -> ios
-    #
-    # Flushes the internal write buffer to the underlying data stream.
-    #
-    # Regardless of the blocking status of the data stream or interruptions
-    # during writing, this method will block until either all the data is
-    # flushed or until an error is raised.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError unless
-    # #writable? returns +true+.
-    #
-    # <b>NOTE:</b> This method ignores Errno::EAGAIN and Errno::EINTR raised by
-    # #unbuffered_write.  Therefore, this method always blocks if unable to
-    # flush the internal write buffer.  Aside from that exception, this
-    # method will also raise the same errors and block at the same times as
-    # #unbuffered_write.
-    def flush
-      begin
-        __io_like__buffered_flush
-      rescue Errno::EAGAIN, Errno::EINTR
-        retry if write_ready?
-      end
-      self
+  ##
+  # Returns the external encoding of the stream, if any.
+  #
+  # @return [Encoding] the Encoding object that represents the encoding of the
+  #   stream
+  # @return [nil] if the stream is writable and no encoding is specified
+  #
+  # @raise [IOError] if the stream is closed and Ruby version is less than 3.1
+  def external_encoding
+    assert_open if RBVER_LT_3_1
+
+    encoding = delegate.character_io.external_encoding
+    return encoding if encoding || writable?
+
+    Encoding::default_external
+  end
+
+  ##
+  # Flushes the internal write buffer to the underlying stream.
+  #
+  # Regardless of the blocking status of the stream or interruptions during
+  # writing, this method will block until either all the data is flushed or
+  # until an error is raised.
+  #
+  # @return [self]
+  #
+  # @raise [IOError] if the stream is not open for writing
+  def flush
+    assert_open
+
+    delegate_w.buffered_io.flush
+
+    self
+  end
+
+  ##
+  # Returns the next byte from the stream.
+  #
+  # @return [Integer] the next byte from the stream
+  # @return [nil] if the end of the stream has been reached
+  #
+  # @raise [IOError] if the stream is not open for reading
+  def getbyte
+    readbyte
+  rescue EOFError
+    return nil
+  end
+
+  ##
+  # Returns the next character from the stream.
+  #
+  # @return [String] the next character from the stream
+  # @return [nil] if the end of the stream has been reached
+  #
+  # @raise [IOError] if the stream is not open for reading
+  def getc
+    readchar
+  rescue EOFError
+    nil
+  end
+
+  ##
+  # Returns the next line from the stream.
+  #
+  # @overload gets(separator = $/, limit = nil, chomp: false)
+  #
+  #   @param separator [String, nil] a non-empty String that separates each
+  #     line, an empty String that equates to 2 or more successive newlines as
+  #     the separator, or `nil` to indicate reading all remaining data
+  #   @param limit [Integer, nil] an Integer limiting the number of bytes
+  #     returned in each line or `nil` to indicate no limit
+  #   @param chomp [Boolean] when `true` trailing newlines and carriage returns
+  #     will be removed from each line
+  #
+  #   @return [String] the next line in the stream
+  #   @return [nil] if the end of the stream has been reached
+  #
+  # @overload gets(limit, chomp: false)
+  #
+  #   @param limit [Integer] an Integer limiting the number of bytes returned in
+  #     each line or `nil` to indicate no limit
+  #   @param chomp [Boolean] when `true` trailing newlines and carriage returns
+  #     will be removed from each line
+  #
+  #   @return [String] the next line in the stream where the separator is `$/`
+  #   @return [nil] if the end of the stream has been reached
+  #
+  # @raise [IOError] if the stream is not open for reading
+  def gets(*args, **opts)
+    readline(*args, **opts)
+  rescue EOFError
+    # NOTE:
+    # Through Ruby 3.3, assigning to $_ has no effect outside of a method that
+    # does it.  This assignment is kept in case that ever changes.
+    $_ = nil
+    nil
+  end
+
+  ##
+  # Returns the internal encoding of the stream, if any.
+  #
+  # @return [Encoding] the Encoding object that represents the encoding of the
+  #   internal string conversion
+  # @return [nil] if no encoding is specified
+  #
+  # @raise [IOError] if the stream is closed and Ruby version is less than 3.1
+  def internal_encoding
+    assert_open if RBVER_LT_3_1
+    delegate.character_io.internal_encoding
+  end
+
+  ##
+  # For compatibility with `IO`.
+  alias_method :isatty, :tty?
+
+  ##
+  # Returns the current line number of the stream.
+  #
+  # More accurately the number of times {#gets} is called on the stream and
+  # returns a non-`nil` result, either explicitly or implicitly via methods such
+  # as {#each_line}, {#readline}, {#readlines}, etc. is returned.  This may
+  # differ from the number of lines if `$/` is changed from the default or if
+  # {#gets} is called with a different separator.
+  #
+  # @return [Integer] the current line number of the stream
+  #
+  # @raise [IOError] if the stream is not open for reading
+  def lineno
+    assert_readable
+
+    @lineno ||= 0
+  end
+
+  ##
+  # Sets the current line number of the stream to the given value.  `$.` is
+  # updated by the _next_ call to {#gets}.  If the object given is not an
+  # Integer, it is converted to one using the `Integer` method.
+  #
+  # @return [Integer] the current line number of the stream
+  #
+  # @raise [IOError] if the stream is not open for reading
+  def lineno=(integer)
+    assert_readable
+
+    @lineno = ensure_integer(integer)
+  end
+
+  if RBVER_LT_3_0
+  ##
+  # @deprecated Use {#each_line} instead.
+  #
+  # @version < Ruby 3.0
+  def lines(*args, &block)
+    warn('warning: IO#lines is deprecated; use #each_line instead')
+    each_line(*args, &block)
+  end
+  end
+
+  ##
+  # @return [Integer] the number of bytes that can be read without blocking or
+  #   `0` if unknown
+  #
+  # @raise [IOError] if the stream is not open for reading
+  def nread
+    assert_readable
+
+    unless delegate_r.character_io.buffer_empty?
+      raise IOError, 'byte oriented read for character buffered IO'
     end
+    delegate_r.nread
+  end
+
+  ##
+  # Returns the process ID of a child process associated with this stream, if
+  # any.
+  #
+  # @return [Integer] a process ID
+  # @return [nil] if there is no associated child process
+  #
+  # @raise [IOError] if the stream is closed
+  def pid
+    assert_open
+    return @pid unless nil == @pid
+    super
+  end
+
+  ##
+  # @note This method will block if writing the stream blocks and there is data
+  #   in the write buffer.
+  #
+  # @return [Integer] the current byte offset of the stream
+  #
+  # @raise [IOError] if the stream is closed
+  # @raise [Errno::ESPIPE] if the stream is not seekable
+  def pos
+    assert_open
+
+    flush
+    delegate.seek(0, IO::SEEK_CUR)
+  end
+  alias_method :tell, :pos
+
+  ##
+  # Sets the position of the stream to the given byte offset.
+  #
+  # @param position [Integer] the byte offset to which the stream will be set
+  #
+  # @return [Integer] the given byte offset
+  #
+  # @raise [IOError] if the stream is closed
+  # @raise [Errno::ESPIPE] if the stream is not seekable
+  def pos=(position)
+    seek(position, IO::SEEK_SET)
+    position
+  end
+
+  ##
+  # Reads at most `maxlen` bytes from the stream starting at `offset` without
+  # modifying the read position in the stream.
+  #
+  # @param maxlen [Integer] the maximum number of bytes to read
+  # @param offset [Integer] the offset from the beginning of the stream at which
+  #   to begin reading
+  # @param buffer [String] if provided, a buffer into which the bytes should be
+  #   placed
+  #
+  # @return [String] a new String containing the bytes read if `buffer` is `nil`
+  #   or `buffer` if provided
+  #
+  # @raise [EOFError] when reading at the end of the stream
+  # @raise [IOError] if the stream is not readable
+  def pread(maxlen, offset, buffer = nil)
+    maxlen = ensure_integer(maxlen)
+    raise ArgumentError, 'negative string size (or size too big)' if maxlen < 0
+    buffer = nil == buffer ? ''.b : ensure_string(buffer)
+
+    return buffer if maxlen == 0
 
-    # call-seq:
-    #   ios.flush_size       -> integer
-    #
-    # Returns the number of bytes at which the internal write buffer is flushed
-    # automatically to the data stream.  Unless set explicitly via #flush_size=,
-    # this defaults to 4096.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError unless
-    # #writable? returns +true+.
-    def flush_size
-      raise IOError, 'closed stream' if closed?
-      raise IOError, 'not opened for writing' unless writable?
-
-      @__io_like__flush_size ||= 4096
+    offset = ensure_integer(offset)
+    raise Errno::EINVAL if offset < 0
+
+    assert_readable
+
+    if maxlen > buffer.bytesize
+      buffer << "\0" * (maxlen - buffer.bytesize)
     end
+    bytes_read = delegate_r.pread(maxlen, offset, buffer: buffer)
+    buffer.slice!(bytes_read..-1)
+
+    buffer
+  end
 
-    # call-seq:
-    #   ios.flush_size = integer -> integer
-    #
-    # Sets the number of bytes at which the internal write buffer is flushed
-    # automatically to the data stream.  The new value must be a number greater
-    # than or equal to 0.  Setting this to 0 effectively disables buffering.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError unless
-    # #writable? returns +true+.
-    def flush_size=(flush_size)
-      raise IOError, 'closed stream' if closed?
-      raise IOError, 'not opened for writing' unless writable?
-
-      unless flush_size >= 0 then
-        raise ArgumentError, "non-positive flush_size #{flush_size} given"
+  ##
+  # Writes the given object(s), if any, to the stream using {#write}.
+  #
+  # If no objects are given, `$_` is written.  The field separator (`$,`) is
+  # written between successive objects if it is not `nil`.  The output record
+  # separator (`$\`) is written after all other data if it is not `nil`.
+  #
+  # @param args [Array<Object>] zero or more objects to write to the stream
+  #
+  # @return [nil]
+  #
+  # @raise [IOError] if the stream is not open for writing
+  def print(*args)
+    # NOTE:
+    # Through Ruby 3.1, $_ is always nil on entry to a Ruby method.  This
+    # assignment is kept in case that ever changes.
+    args << $_ if args.empty?
+    first_arg = true
+    args.each do |arg|
+      # Write a field separator before writing each argument after the first
+      # one unless no field separator is specified.
+      if first_arg
+        first_arg = false
+      else
+        write($,)
       end
-      @__io_like__flush_size = flush_size
-    end
 
-    # call-seq:
-    #   ios.getc             -> nil or integer
-    #
-    # Calls #readchar and either returns the result or +nil+ if #readchar raises
-    # EOFError.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError unless
-    # #readable? returns +true+.  Raises all errors raised by #unbuffered_read
-    # except for EOFError.
-    #
-    # <b>NOTE:</b> This method ignores Errno::EAGAIN and Errno::EINTR raised by
-    # #unbuffered_read.  Therefore, this method always blocks.  Aside from that
-    # exception and the conversion of EOFError results into +nil+ results, this
-    # method will also raise the same errors and block at the same times as
-    # #unbuffered_read.
-    def getc
-      readchar
-    rescue EOFError
-      nil
+      write(arg)
     end
 
-    # call-seq:
-    #   ios.gets(sep_string = $/) -> nil or string
-    #
-    # Calls #readline with _sep_string_ as an argument and either returns the
-    # result or +nil+ if #readline raises EOFError.  If #readline returns some
-    # data, <tt>$.</tt> is set to the value of #lineno.
-    #
-    # <b>NOTE:</b> Due to limitations of MRI up to version 1.9.x when running
-    # managed (Ruby) code, this method fails to set <tt>$_</tt> to the returned
-    # data; however, other implementations may allow it.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError unless
-    # #readable? returns +true+.  Raises all errors raised by #unbuffered_read
-    # except for EOFError.
-    #
-    # <b>NOTE:</b> When _sep_string_ is not +nil+, this method ignores
-    # Errno::EAGAIN and Errno::EINTR raised by #unbuffered_read.  Therefore,
-    # this method will always block in that case.  Aside from that exception,
-    # this method will raise the same errors and block at the same times as
-    # #unbuffered_read.
-    def gets(sep_string = $/)
-      # Set the last read line in the global.
-      $_ = readline(sep_string)
-      # Set the last line number in the global.
-      $. = lineno
-      # Return the last read line.
-      $_
-    rescue EOFError
-      nil
+    # Write the output record separator if one is specified.
+    write($\) if $\
+    nil
+  end
+
+  ##
+  # Writes the String returned by calling `Kernel.sprintf` using the given
+  # arguments.
+  #
+  # @param args [Array] arguments to pass to `Kernel.sprintf`
+  #
+  # @return [nil]
+  #
+  # @raise [IOError] if the stream is not open for writing
+  def printf(*args)
+    write(sprintf(*args))
+    nil
+  end
+
+  ##
+  # If `obj` is a String, write the first character; otherwise, convert `obj` to
+  # an Integer using the `Integer` method and write the low order byte.
+  #
+  # @param obj [String, Numeric] the character to be written
+  #
+  # @return [obj] the given parameter
+  #
+  # @raise [TypeError] if `obj` is not a String nor convertable to a Numeric
+  #   type
+  # @raise [IOError] if the stream is not open for writing
+  def putc(obj)
+    char = case obj
+           when String
+             obj[0]
+           else
+             [ensure_integer(obj)].pack('V')[0]
+           end
+    write(char)
+    obj
+  end
+
+  ##
+  # Writes the given object(s), if any, to the stream.
+  #
+  # Uses {#write} after converting objects to strings using their `to_s`
+  # methods.  Unlike {#print}, Array instances are recursively processed.  The
+  # record separator character (`$\`) is written after each object which does
+  # not end with the record separator already.
+  #
+  # If no objects are given, a single record separator is written.
+  #
+  # @param args [Array<Object>] zero or more objects to write to the stream
+  #
+  # @return [nil]
+  #
+  # @raise [IOError] if the stream is not open for writing
+  def puts(*args)
+    # Write only the record separator if no arguments are given.
+    if args.length == 0
+      write(ORS)
+      return
     end
 
-    # call-seq:
-    #   ios.isatty           -> false
-    #
-    # Returns +false+.  Just for compatibility with IO.
-    #
-    # Raises IOError if #closed? returns +true+.
-    def isatty
-      raise IOError, 'closed stream' if closed?
-      false
+    flatten_puts(args)
+    nil
+  end
+
+  ##
+  # Writes at most `string.to_s.length` bytes to the stream starting at `offset`
+  # without modifying the write position in the stream.
+  #
+  # @param string [String] the bytes to write (encoding assumed to be binary)
+  # @param offset [Integer] the offset from the beginning of the stream at which
+  #   to begin writing
+  #
+  # @return [Integer] the number of bytes written
+  #
+  # @raise [IOError] if the stream is not writable
+  def pwrite(string, offset)
+    string = string.to_s
+
+    offset = ensure_integer(offset)
+    raise Errno::EINVAL if offset < 0
+
+    assert_writable
+
+    delegate_w.pwrite(string, offset)
+  end
+
+  ##
+  # Reads data from the stream.
+  #
+  # If `length` is specified as a positive integer, at most `length` bytes are
+  # returned.  Truncated data will occur if there is insufficient data left to
+  # fulfill the request.  If the read starts at the end of data, `nil` is
+  # returned.
+  #
+  # If `length` is unspecified or `nil`, an attempt to return all remaining data
+  # is made.  Partial data will be returned if a low-level error is raised after
+  # some data is retrieved.  If no data would be returned at all, an empty
+  # String is returned.
+  #
+  # If `buffer` is specified, it will be converted to a String using its
+  # `to_str` method if necessary and will be filled with the returned data if
+  # any.
+  #
+  # @param length [Integer] the number of bytes to read
+  # @param buffer [String] the location into which data will be stored
+  #
+  # @return [String] the data read from the stream
+  # @return [nil] if `length` is non-zero but no data is left in the stream
+  #
+  # @raise [ArgumentError] if `length` is less than 0
+  # @raise [IOError] if the stream is not open for reading
+  def read(length = nil, buffer = nil)
+    length = ensure_integer(length) if nil != length
+    if nil != length && length < 0
+      raise ArgumentError, "negative length #{length} given"
     end
-    alias :tty? :isatty
-
-    # call-seq:
-    #   ios.lineno           -> integer
-    #
-    # Returns the number of times #gets was called and returned non-+nil+ data.
-    # By default this is the number of lines read, but calling #gets or any of
-    # the other line-based reading methods with a non-default value for
-    # _sep_string_ or after changing <tt>$/</tt> will affect this.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError unless
-    # #readable? returns +true+.
-    def lineno
-      raise IOError, 'closed stream' if closed?
-      raise IOError, 'not opened for reading' unless readable?
-      @__io_like__lineno ||= 0
+    buffer = ensure_string(buffer) unless nil == buffer
+
+    assert_readable
+
+    unless length
+      content = begin
+                  delegate_r.character_io.read_all
+                rescue EOFError
+                  ''.encode(
+                    internal_encoding ||
+                    external_encoding ||
+                    Encoding.default_external
+                  )
+                end
+      return content unless buffer
+      return buffer.replace(content)
     end
 
-    # call-seq:
-    #   ios.lineno = lineno  -> lineno
-    #
-    # Sets the current line number to the given value.  <tt>$.</tt> is updated
-    # by the _next_ call to #gets.  If the object given is not an integer, it is
-    # converted to one using its to_int method.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError unless
-    # #readable? returns +true+.
-    def lineno=(integer)
-      raise IOError, 'closed stream' if closed?
-      raise IOError, 'not opened for reading' unless readable?
-      if integer.nil? then
-        raise TypeError, 'no implicit conversion from nil to integer'
-      elsif ! integer.respond_to?(:to_int) then
-        raise TypeError, "can't convert #{integer.class} into Integer"
-      end
-      @__io_like__lineno = integer.to_int
+    unless delegate_r.character_io.buffer_empty?
+      raise IOError, 'byte oriented read for character buffered IO'
     end
 
-    # call-seq:
-    #   ios.path             -> nil
-    #
-    # Returns +nil+.  Just for compatibility with IO.
-    def path
-      nil
+    content = read_bytes(length)
+    if buffer
+      orig_encoding = buffer.encoding
+      buffer.replace(content)
+      buffer.force_encoding(orig_encoding)
+      content = buffer
     end
 
-    # call-seq:
-    #   ios.pos = position   -> position
-    #
-    # Sets the data position to _position_ by calling #seek.
-    #
-    # As a side effect, the internal read and write buffers are flushed.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises Errno::ESPIPE unless
-    # #seekable? returns +true+.
-    #
-    # <b>NOTE:</b> Because this method relies on #unbuffered_seek and
-    # #unbuffered_write (when the internal write buffer is not empty), it will
-    # also raise the same errors and block at the same times as those functions.
-    def pos=(position)
-      seek(position, IO::SEEK_SET)
-      position
+    return nil if content.empty? && length > 0
+    return content
+  end
+
+  ##
+  # Reads and returns at most `length` bytes from the stream.
+  #
+  # If the internal read buffer is **not** empty, only the buffer is used, even
+  # if less than `length` bytes are available.  If the internal buffer **is**
+  # empty, sets non-blocking mode via {#nonblock=} and then reads from the
+  # underlying stream.
+  #
+  # @param length [Integer] the number of bytes to read
+  # @param buffer [String] the location in which to store the data
+  # @param exception [Boolean] when `true` causes this method to raise
+  #   exceptions when no data is available; otherwise, symbols are returned
+  #
+  # @return [String] the data read from the stream
+  # @return [:wait_readable, :wait_writable] if `exception` is `false` and no
+  #   data is available
+  # @return [nil] if `exception` is `false` and reading begins at the end of the
+  #   stream
+  #
+  # @raise [EOFError] if reading begins at the end of the stream
+  # @raise [IOError] if the stream is not open for reading
+  # @raise [IO::EWOULDBLOCKWaitReadable, IO::EWOULDBLOCKWaitWritable] if
+  #   `exception` is `true` and no data is available
+  # @raise [Errno::EBADF] if non-blocking mode is not supported
+  # @raise [SystemCallError] if there are low level errors
+  def read_nonblock(length, buffer = nil, exception: true)
+    length = ensure_integer(length)
+    raise ArgumentError, 'length must be at least 0' if length < 0
+    buffer = ensure_string(buffer) if nil != buffer
+
+    assert_readable
+
+    if RBVER_LT_3_0_4 && length == 0
+      return (buffer || ''.b)
     end
 
-    # call-seq:
-    #   ios.pos              -> integer
-    #
-    # Returns the current offest of ios.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises Errno::ESPIPE unless
-    # #seekable? returns +true+.
-    #
-    # As a side effect, the internal write buffer is flushed unless this is
-    # a writable, non-duplexed object.  This is for compatibility with the
-    # behavior of IO#pos.
-    #
-    # <b>NOTE:</b> Because this method relies on #unbuffered_seek and
-    # #unbuffered_write (when the internal write buffer is not empty), it will
-    # also raise the same errors and block at the same times as those functions.
-    def pos
-      # Flush the internal write buffer for writable, non-duplexed objects.
-      __io_like__buffered_flush if writable? && ! duplexed?
-      __io_like__buffered_seek(0, IO::SEEK_CUR)
+    unless delegate_r.character_io.buffer_empty?
+      raise IOError, 'byte oriented read for character buffered IO'
     end
-    alias :tell :pos
-
-    # call-seq:
-    #   ios.print([obj, ...]) -> nil
-    #
-    # Writes the given object(s), if any, to the stream using #write after
-    # converting them to strings by calling their _to_s_ methods.  If no
-    # objects are given, <tt>$_</tt> is used.  The field separator (<tt>$,</tt>)
-    # is written between successive objects if it is not +nil+.  The output
-    # record separator (<tt>$\\</tt>) is written after all other data if it is
-    # not nil.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError unless
-    # #writable? returns +true+.
-    #
-    # <b>NOTE:</b> This method ignores Errno::EAGAIN and Errno::EINTR raised by
-    # #unbuffered_write.  Therefore, this method always blocks if unable to
-    # immediately write +[obj, ...]+ completely.  Aside from that exception,
-    # this method will also raise the same errors and block at the same times as
-    # #unbuffered_write.
-    def print(*args)
-      args << $_ if args.empty?
-      first_arg = true
-      args.each do |arg|
-        # Write a field separator before writing each argument after the first
-        # one unless no field separator is specified.
-        if first_arg then
-          first_arg = false
-        elsif ! $,.nil? then
-          write($,)
-        end
 
-        # If the argument is nil, write 'nil'; otherwise, write the stringified
-        # form of the argument.
-        if arg.nil? then
-          write('nil')
-        else
-          write(arg)
-        end
+    result = ensure_buffer(length, buffer) do |binary_buffer|
+      unless delegate_r.buffered_io.read_buffer_empty?
+        next delegate_r.read(length, buffer: binary_buffer)
       end
 
-      # Write the output record separator if one is specified.
-      write($\) unless $\.nil?
-      nil
+      self.nonblock = true
+      delegate_r.concrete_io.read(length, buffer: binary_buffer)
     end
 
-    # call-seq:
-    #   ios.printf(format_string [, obj, ...]) -> nil
-    #
-    # Writes the String returned by calling Kernel.sprintf using the given
-    # arguments.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError unless
-    # #writable? returns +true+.
-    #
-    # <b>NOTE:</b> This method ignores Errno::EAGAIN and Errno::EINTR raised by
-    # #unbuffered_write.  Therefore, this method always blocks if unable to
-    # immediately write its arguments completely.  Aside from that exception,
-    # this method will also raise the same errors and block at the same times as
-    # #unbuffered_write.
-    def printf(*args)
-      write(sprintf(*args))
-      nil
+    case result
+    when String
+      # This means that a buffer was not given and that the delegate returned a
+      # buffer with the content.
+      return result
+    when Integer
+      # This means that a buffer was given and that the content is in the
+      # buffer.
+      return buffer
+    else
+      return nonblock_response(result, exception)
     end
+  rescue EOFError
+    raise if exception
+    return nil
+  end
 
-    # call-seq:
-    #   ios.putc(obj)        -> obj
-    #
-    # If _obj_ is a String, write the first byte; otherwise, convert _obj_ to a
-    # integer using its _to_int_ method and write the low order byte.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError unless
-    # #writable? returns +true+.
-    #
-    # <b>NOTE:</b> This method ignores Errno::EAGAIN and Errno::EINTR raised by
-    # #unbuffered_write.  Therefore, this method always blocks if unable to
-    # immediately write _obj_ completely.  Aside from that exception, this
-    # method will also raise the same errors and block at the same times as
-    # #unbuffered_write.
-    def putc(obj)
-      char = case obj
-             when String
-               obj[0].chr
-             else
-               [obj.to_int].pack('V')[0].chr
-             end
-      write(char)
-      obj
-    end
+  ##
+  # @return [Integer] the next 8-bit byte (0..255) from the stream
+  #
+  # @raise [EOFError] if reading begins at the end of the stream
+  # @raise [IOError] if the stream is not open for reading
+  def readbyte
+    assert_readable
 
-    # call-seq:
-    #   ios.puts([obj, ...]) -> nil
-    #
-    # Writes the given object(s), if any, to the stream using #write after
-    # converting them to strings using their _to_s_ methods.  Unlike #print,
-    # Array instances are recursively processed.  A record separator character
-    # is written after each object which does not end with the record separator
-    # already.  If no objects are given, a single record separator is written.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError unless
-    # #writable? returns +true+.
-    #
-    # <b>NOTE:</b> This method ignores Errno::EAGAIN and Errno::EINTR raised by
-    # #unbuffered_write.  Therefore, this method always blocks if unable to
-    # immediately write +[obj, ...]+ completely.  Aside from that exception,
-    # this method will also raise the same errors and block at the same times as
-    # #unbuffered_write.
-    #
-    # <b>NOTE:</b> In order to be compatible with IO#puts, the record separator
-    # is currently hardcoded to be a single newline (<tt>"\n"</tt>) even though
-    # the documentation implies that the output record separator (<tt>$\\</tt>)
-    # should be used.
-    def puts(*args)
-      # Set the output record separator such that this method is compatible with
-      # IO#puts.
-      ors = "\n"
-
-      # Write only the record separator if no arguments are given.
-      if args.length == 0 then
-        write(ors)
-        return
-      end
+    unless delegate_r.character_io.buffer_empty?
+      raise IOError, 'byte oriented read for character buffered IO'
+    end
+    byte = delegate_r.read(1)
+    byte[0].ord
+  end
 
-      # Write each argument followed by the record separator.  Recursively
-      # process arguments which are Array instances.
-      args.each do |arg|
-        line = arg.nil? ?
-                 'nil' :
-                 arg.kind_of?(Array) ?
-                   __io_like__array_join(arg, ors) :
-                   arg.to_s
-        line += ors if line.index(ors, -ors.length).nil?
-        write(line)
-      end
+  ##
+  # @return [String] the next character from the stream
+  #
+  # @raise [EOFError] if reading begins at the end of the stream
+  # @raise [IOError] if the stream is not open for reading
+  def readchar
+    assert_readable
 
-      nil
-    end
+    delegate_r.character_io.read_char
+  end
 
-    # call-seq:
-    #   ios.read([length[, buffer]]) -> nil, buffer, or string
-    #
-    # If _length_ is specified and is a positive integer, at most length bytes
-    # are returned.  Truncated data will occur if there is insufficient data
-    # left to fulfill the request.  If the read starts at the end of data, +nil+
-    # is returned.
-    #
-    # If _length_ is unspecified or +nil+, an attempt to return all remaining
-    # data is made.  Partial data will be returned if a low-level error is
-    # raised after some data is retrieved.  If no data would be returned at all,
-    # an empty String is returned.
-    #
-    # If _buffer_ is specified, it will be converted to a String using its
-    # +to_str+ method if necessary and will be filled with the returned data if
-    # any.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError unless
-    # #readable? returns +true+.
-    #
-    # <b>NOTE:</b> Because this method relies on #unbuffered_read, it will also
-    # raise the same errors and block at the same times as that function.
-    def read(length = nil, buffer = nil)
-      # Check the validity of the method arguments.
-      unless length.nil? || length >= 0 then
-        raise ArgumentError, "negative length #{length} given"
-      end
-      buffer = buffer.nil? ? '' : buffer.to_str
-      buffer.slice!(0..-1) unless buffer.empty?
-
-      if length.nil? then
-        # Read and return everything.
-        begin
-          loop do
-            buffer << __io_like__buffered_read(4096)
-          end
-        rescue EOFError
-          # Ignore this.
-        rescue SystemCallError
-          # Reraise the error if there is nothing to return.
-          raise if buffer.empty?
-        end
-      else
-        # Read and return up to length bytes.
-        begin
-          buffer << __io_like__buffered_read(length)
-        rescue EOFError
-          # Return nil to the caller at end of file when requesting a specific
-          # amount of data.
-          return nil
-        end
+  ##
+  # Returns the next line from the stream.
+  #
+  # @overload readline(separator = $/, limit = nil, chomp: false)
+  #
+  #   @param separator [String, nil] a non-empty String that separates each
+  #     line, an empty String that equates to 2 or more successive newlines as
+  #     the separator, or `nil` to indicate reading all remaining data
+  #   @param limit [Integer, nil] an Integer limiting the number of bytes
+  #     returned in each line or `nil` to indicate no limit
+  #   @param chomp [Boolean] when `true` trailing newlines and carriage returns
+  #     will be removed from each line
+  #
+  #   @return [String] the next line in the stream
+  #
+  # @overload readline(limit, chomp: false)
+  #
+  #   @param limit [Integer] an Integer limiting the number of bytes returned in
+  #     each line or `nil` to indicate no limit
+  #   @param chomp [Boolean] when `true` trailing newlines and carriage returns
+  #     will be removed from each line
+  #
+  #   @return [String] the next line in the stream where the separator is `$/`
+  #
+  # @raise [EOFError] if reading begins at the end of the stream
+  # @raise [IOError] if the stream is not open for reading
+  def readline(*args, **opts)
+    separator, limit = parse_readline_args(*args)
+    chomp = opts.fetch(:chomp, false)
+
+    assert_readable
+
+    discard_newlines = false
+    encoding =
+      internal_encoding || external_encoding || Encoding.default_external
+
+    if separator
+      # Reading with a record separator is performed using bytes rather than
+      # characters, so ensure that the separator is correctly encoded to make
+      # this possible.
+      if separator.empty?
+        # Read by paragraph is requested.  The separator is 2 newline characters
+        # in the encoding of the character reader.
+        discard_newlines = true
+        separator = "\n\n"
+        separator = separator.b if RBVER_LT_3_4
+      elsif $/.equal?(separator)
+        # When using the default record separator character, convert it into the
+        # encoding of the character reader.
+        separator = separator.encode(encoding)
+      elsif ! (separator.encoding == encoding ||
+               (separator.ascii_only? && encoding.ascii_compatible?))
+        # Raise an error when the separator encoding doesn't match the reader
+        # encoding and ASCII compatibility is not available.
+        #
+        # NOTE:
+        # We should probably attempt to convert the encoding of the separator
+        # into the encoding of the reader before raising this error, but MRI
+        # doesn't appear to do that.
+        raise ArgumentError,
+          'encoding mismatch: %s IO with %s RS' % [encoding, separator.encoding]
       end
-      buffer
     end
 
-    # call-seq:
-    #   ios.read_ready?      -> true or false
-    #
-    # Returns +true+ when the stream may be read without error, +false+
-    # otherwise.  This method will block until one of the conditions is known.
-    #
-    # This default implementation of #read_ready? is a hack which should be able
-    # to work for both real IO objects and IO-like objects; however, it is
-    # inefficient since it merely sleeps for 1 second and then returns +true+ as
-    # long as #closed? returns +false+.  IO.select should be used for real IO
-    # objects to wait for a readable condition on platforms with support for
-    # IO.select.  Other solutions should be found as necessary to improve this
-    # implementation on a case by case basis.
-    #
-    # Basically, this method should be overridden in derivative classes.
-    def read_ready?
-      return false unless readable?
-      sleep(1)
-      true
+    buffer = delegate_r.character_io.read_line(
+      separator: separator,
+      limit: limit,
+      chomp: chomp,
+      discard_newlines: discard_newlines
+    )
+
+    # Increment the number of times this method has returned a "line".
+    self.lineno += 1
+    # Set the last line number in the global.
+    $. = lineno
+    # Set the last read line in the global and return it.
+    # NOTE:
+    # Through Ruby 3.3, assigning to $_ has no effect outside of a method that
+    # does it.  This assignment is kept in case that ever changes.
+    $_ = buffer
+  end
+
+  ##
+  # @overload readlines(separator = $/, limit = nil, chomp: false)
+  #
+  #   @param separator [String, nil] a non-empty String that separates each
+  #     line, an empty String that equates to 2 or more successive newlines as
+  #     the separator, or `nil` to indicate reading all remaining data
+  #   @param limit [Integer, nil] an Integer limiting the number of bytes
+  #     returned in each line or `nil` to indicate no limit
+  #   @param chomp [Boolean] when `true` trailing newlines and carriage returns
+  #     will be removed from each line
+  #
+  #   @return [Array<String>] the remaining lines in the stream
+  #
+  # @overload readlines(limit, chomp: false)
+  #
+  #   @param limit [Integer] an Integer limiting the number of bytes returned in
+  #     each line or `nil` to indicate no limit
+  #   @param chomp [Boolean] when `true` trailing newlines and carriage returns
+  #     will be removed from each line
+  #
+  #   @return [Array<String>] the remaining lines in the stream where the
+  #     separator is `$/`
+  #
+  # @raise [IOError] if the stream is not open for reading
+  def readlines(*args, **opts)
+    each_line(*args, **opts).to_a
+  end
+
+  ##
+  # Reads and returns at most `length` bytes from the stream.
+  #
+  # If the internal read buffer is **not** empty, only the buffer is used, even
+  # if less than `length` bytes are available.  If the internal buffer **is**
+  # empty, reads from the underlying stream.
+  #
+  # @param length [Integer] the number of bytes to read
+  # @param buffer [String] the location in which to store the data
+  #
+  # @return [String] the data read from the stream
+  #
+  # @raise [EOFError] if reading begins at the end of the stream
+  # @raise [IOError] if the stream is not open for reading
+  def readpartial(length, buffer = nil)
+    length = ensure_integer(length)
+    raise ArgumentError, 'length must be at least 0' if length < 0
+    buffer = ensure_string(buffer) if nil != buffer
+
+    assert_readable
+
+    if RBVER_LT_3_0_4 && length == 0
+      return (buffer || ''.b)
     end
 
-    # call-seq:
-    #   ios.readable?        -> true or false
-    #
-    # Returns +true+ if the stream is both open and readable, +false+ otherwise.
-    #
-    # This implementation checks to see if #unbuffered_read is defined in order
-    # to make its determination.  Override this if the implementing class always
-    # provides the #unbuffered_read method but may not always be open in a
-    # readable mode.
-    def readable?
-      ! __io_like__closed_read? && respond_to?(:unbuffered_read, true)
+    unless delegate_r.character_io.buffer_empty?
+      raise IOError, 'byte oriented read for character buffered IO'
     end
 
-    # call-seq:
-    #   ios.readbytes(length) -> string
-    #
-    # Reads and returns _length_ bytes from the data stream.
-    #
-    # Raises EOFError if reading begins at the end of the stream.  Raises
-    # IOError if #closed? returns +true+.  Raises IOError unless #readable?
-    # returns +true+.  Raises TruncatedDataError if insufficient data is
-    # immediately available to satisfy the request.
-    #
-    # In the case of TruncatedDataError being raised, the retrieved data can be
-    # fetched from the _data_ attribute of the exception.
-    #
-    # This method is basically copied from IO#readbytes.
-    #
-    # <b>NOTE:</b> Because this method relies on #unbuffered_read, it will also
-    # raise the same errors and block at the same times as that function.
-    def readbytes(length)
-      buffer = read(length)
-      if buffer.nil? then
-        raise EOFError, "end of file reached"
+    result = ensure_buffer(length, buffer) do |binary_buffer|
+      unless delegate_r.buffered_io.read_buffer_empty?
+        next delegate_r.read(length, buffer: binary_buffer)
       end
-      if buffer.length < length then
-        raise TruncatedDataError.new("data truncated", buffer)
-      end
-      buffer
-    end
 
-    # call-seq:
-    #   ios.readchar         -> integer
-    #
-    # Returns the next 8-bit byte (0..255) from the stream.
-    #
-    # Raises EOFError when there is no more data in the stream.  Raises IOError
-    # if #closed? returns +true+.  Raises IOError unless #readable? returns
-    # +true+.
-    #
-    # <b>NOTE:</b> This method ignores Errno::EAGAIN and Errno::EINTR raised by
-    # #unbuffered_read.  Therefore, this method always blocks.  Aside from that
-    # exception, this method will also raise the same errors and block at the
-    # same times as #unbuffered_read.
-    def readchar
-      __io_like__buffered_read(1)[0]
-    rescue Errno::EAGAIN, Errno::EINTR
-      retry if read_ready?
+      delegate_r.blocking_io.read(length, buffer: binary_buffer)
     end
 
-    # call-seq:
-    #   ios.readline(sep_string = $/) -> string
-    #
-    # Returns the next line from the stream, where lines are separated by
-    # _sep_string_.  Increments #lineno by <tt>1</tt> for each call regardless
-    # of the value of _sep_string_.
-    #
-    # If _sep_string_ is not +nil+ and not a String, it is first converted to a
-    # String using its +to_str+ method and processing continues as follows.
-    #
-    # If _sep_string_ is +nil+, a line is defined as the remaining contents of
-    # the stream.  Partial data will be returned if a low-level error of any
-    # kind is raised after some data is retrieved.  This is equivalent to
-    # calling #read without any arguments except that this method will raise an
-    # EOFError if called at the end of the stream.
-    #
-    # If _sep_string_ is an empty String, a paragraph is returned, where a
-    # paragraph is defined as data followed by 2 or more successive newline
-    # characters.  A maximum of 2 newlines are returned at the end of the
-    # returned data.  Fewer may be returned if the stream ends before at least 2
-    # successive newlines are seen.
-    #
-    # Any other value for _sep_string_ is used as a delimiter to mark the end of
-    # a line.  The returned data includes this delimiter unless the stream ends
-    # before the delimiter is seen.
-    #
-    # In any case, the end of the stream terminates the current line.
-    #
-    # Raises EOFError when there is no more data in the stream.  Raises IOError
-    # if #closed? returns +true+.  Raises IOError unless #readable? returns
-    # +true+.
-    #
-    # <b>NOTE:</b> When _sep_string_ is not +nil+, this method ignores
-    # Errno::EAGAIN and Errno::EINTR raised by #unbuffered_read.  Therefore,
-    # this method will always block in that case.  Aside from that exception,
-    # this method will raise the same errors and block at the same times as
-    # #unbuffered_read.
-    def readline(sep_string = $/)
-      # Ensure that sep_string is either nil or a String.
-      unless sep_string.nil? || sep_string.kind_of?(String) then
-        sep_string = sep_string.to_str
-      end
+    # The delegate returns the read content unless a buffer is given.
+    return nil == buffer ? result : buffer
+  end
+
+  ##
+  # @overload reopen(other)
+  #   @param other [Like] another IO::Like instance whose delegate(s) will be
+  #     dup'd and used as this stream's delegate(s)
+  #
+  #   @raise [IOError] if this instance is closed
+  #
+  # @overload reopen(io)
+  #   @param io [IO, #to_io] an IO instance that will be dup'd and used as this
+  #     stream's delegate
+  #
+  #   @raise [IOError] if this instance or `io` are closed
+  #
+  # @overload reopen(path, mode, **opt)
+  #   @param path [String] path to a file to open and use as a delegate for this
+  #     stream
+  #   @param mode [String] file open mode as used by `File.open`, defaults to a
+  #     mode equivalent to this stream's current read/writ-ability
+  #   @param opts [Hash] options hash as used by `File.open`
+  #
+  #   @raise all errors raised by `File.open`
+  #
+  # Replaces the delegate(s) of this stream with another instance's delegate(s)
+  # or an IO instance.
+  #
+  # @return [self]
+  def reopen(*args, **opts)
+    unless args.size == 1 || args.size == 2
+      raise ArgumentError,
+        "wrong number of arguments (given #{args.size}, expected 1..2)"
+    end
 
-      buffer = ''
+    if args.size == 1
       begin
-        if sep_string.nil? then
-          # A nil line separator means that the user wants to capture all the
-          # remaining input.
-          loop do
-            buffer << __io_like__buffered_read(4096)
-          end
-        else
-          begin
-            # Record if the user requested paragraphs rather than lines.
-            paragraph_requested = sep_string.empty?
-            # An empty line separator string indicates that the user wants to
-            # return paragraphs.  A pair of newlines in the stream is used to
-            # mark this.
-            sep_string = "\n\n" if paragraph_requested
-
-            # Add each character from the input to the buffer until either the
-            # buffer has the right ending or the end of the input is reached.
-            while buffer.index(sep_string, -sep_string.length).nil? &&
-                  (char = __io_like__buffered_read(1)) do
-              buffer << char
-            end
-
-            if paragraph_requested then
-              # If the user requested paragraphs instead of lines, we need to
-              # consume and discard all newlines remaining at the front of the
-              # input.
-              while char == "\n" && (char = __io_like__buffered_read(1)) do
-                nil
-              end
-              # Put back the last character.
-              ungetc(char[0])
-            end
-          rescue Errno::EAGAIN, Errno::EINTR
-            retry if read_ready?
-          end
+        io = args[0]
+        io = args[0].to_io unless IO::Like === io
+
+        if IO::Like === io
+          assert_open
+          new_delegate_r = io.delegate_r.concrete_io.dup
+          new_delegate_w = io.duplexed? ? io.delegate_w.concrete_io.dup : new_delegate_r
+          close
+          initialize(
+            new_delegate_r,
+            new_delegate_w,
+            binmode: io.binmode?,
+            internal_encoding: delegate_r.character_io.internal_encoding,
+            external_encoding: delegate_r.character_io.external_encoding,
+            sync: io.sync,
+            pid: io.pid,
+            pipeline_class: @pipeline_class
+          )
+          return self
+        end
+
+        unless IO === io
+          raise TypeError,
+            "can't convert #{args[0].class} to IO (#{args[0].class}#to_io gives #{io.class})"
         end
-      rescue EOFError, SystemCallError
-        # Reraise the error if there is nothing to return.
-        raise if buffer.empty?
+
+        assert_open
+        io = io.dup
+      rescue NoMethodError
+        mode = (readable? ? 'r' : 'w').dup
+        mode << '+' if readable? && writable?
+        mode << 'b'
+        io = File.open(args[0], mode)
       end
-      # Increment the number of times this method has returned a "line".
-      self.lineno += 1
-      buffer
+    else
+      io = File.open(*args, **opts)
     end
 
-    # call-seq:
-    #   ios.readlines(sep_string = $/) -> array
-    #
-    # Returns an Array containing the lines in the stream using #each_line.
-    #
-    # If _sep_string_ is +nil+, a line is defined as the remaining contents of
-    # the stream.  If _sep_string_ is not a String, it is converted to one using
-    # its +to_str+ method.  If _sep_string_ is empty, a paragraph is returned,
-    # where a paragraph is defined as data followed by 2 or more successive
-    # newline characters (only 2 newlines are returned at the end of the
-    # returned data).
-    #
-    # In any case, the end of the stream terminates the current line.
-    #
-    # Raises EOFError when there is no more data in the stream.  Raises IOError
-    # if #closed? returns +true+.  Raises IOError unless #readable? returns
-    # +true+.
-    #
-    # <b>NOTE:</b> When _sep_string_ is not +nil+, this method ignores
-    # Errno::EAGAIN and Errno::EINTR raised by #unbuffered_read.  Therefore,
-    # this method always blocks.  Aside from that exception, this method will
-    # also raise the same errors and block at the same times as
-    # #unbuffered_read.
-    def readlines(sep_string = $/)
-      lines = []
-      each_line(sep_string) { |line| lines << line }
-      lines
-    end
+    close
+    initialize(
+      IO::LikeHelpers::IOWrapper.new(io),
+      binmode: io.binmode?,
+      internal_encoding: delegate_r.character_io.internal_encoding,
+      external_encoding: delegate_r.character_io.external_encoding,
+      sync: io.sync,
+      pid: io.pid,
+      pipeline_class: @pipeline_class
+    )
+
+    self
+  end
 
-    # call-seq:
-    #   ios.readpartial(length[, buffer]) -> string or buffer
-    #
-    # Returns at most _length_ bytes from the data stream using only the
-    # internal read buffer if the buffer is not empty.  Falls back to reading
-    # from the stream if the buffer is empty.  Blocks if no data is available
-    # from either the internal read buffer or the data stream regardless of
-    # whether or not the data stream would block.
-    #
-    # Raises EOFError when there is no more data in the stream.  Raises IOError
-    # if #closed? returns +true+.  Raises IOError unless #readable? returns
-    # +true+.
-    #
-    # <b>NOTE:</b> This method ignores Errno::EAGAIN and Errno::EINTR raised by
-    # #unbuffered_read.  Therefore, this method always blocks if unable to
-    # immediately return _length_ bytes.  Aside from that exception, this method
-    # will also raise the same errors and block at the same times as
-    # #unbuffered_read.
-    def readpartial(length, buffer = nil)
-      # Check the validity of the method arguments.
-      unless length >= 0 then
-        raise ArgumentError, "negative length #{length} given"
-      end
-      buffer = '' if buffer.nil?
-      # Flush the buffer.
-      buffer.slice!(0..-1)
-
-      # Read and return up to length bytes.
-      if __io_like__internal_read_buffer.empty? then
-        begin
-          buffer << __io_like__buffered_read(length)
-        rescue Errno::EAGAIN, Errno::EINTR
-          retry if read_ready?
-        end
-      else
-        raise IOError, 'closed stream' if closed?
-        raise IOError, 'not opened for reading' unless readable?
+  ##
+  # Sets the position of the file pointer to the beginning of the stream.
+  #
+  # The `lineno` attribute is reset to `0` if successful and the stream is
+  # readable.
+  #
+  # @return [0]
+  #
+  # @raise [IOError] if the stream is closed
+  # @raise [Errno::ESPIPE] if the stream is not seekable
+  def rewind
+    seek(0, IO::SEEK_SET)
+    self.lineno = 0 if readable?
+    0
+  end
 
-        buffer << __io_like__internal_read_buffer.slice!(0, length)
-      end
-      buffer
+  ##
+  # Sets the current stream position to `amount` based on the setting of
+  # `whence`.
+  #
+  # | `whence` | `amount` Interpretation |
+  # | -------- | ----------------------- |
+  # | `:CUR` or `IO::SEEK_CUR` | `amount` added to current stream position |
+  # | `:END` or `IO::SEEK_END` | `amount` added to end of stream position (`amount` will usually be negative here) |
+  # | `:SET` or `IO::SEEK_SET` | `amount` used as absolute position |
+  #
+  # @param amount [Integer] the amount to move the position in bytes
+  # @param whence [Integer, Symbol] the position alias from which to consider
+  #   `amount`
+  #
+  # @return [0]
+  #
+  # @raise [IOError] if the stream is closed
+  # @raise [Errno::ESPIPE] if the stream is not seekable
+  def seek(amount, whence = IO::SEEK_SET)
+    super
+    # This also clears the byte oriented read buffer, so calling
+    # delegate_r.buffered_io.flush would be redundant.
+    delegate_r.character_io.clear
+    0
+  end
+
+  ##
+  # @overload set_encoding(encoding, **opts)
+  #   @param encoding [Encoding, String, nil] the external encoding or both the
+  #     external and internal encoding if specified as `"ext_enc:int_enc"`
+  #   @param opts [Hash] encoding conversion options used character or newline
+  #     conversion is performed
+  #
+  # @overload set_encoding(external, internal, **opts)
+  #   @param external [Encoding, String, nil] the external encoding
+  #   @param internal [Encoding, String, nil] the internal encoding
+  #   @param opts [Hash] encoding conversion options used character or newline
+  #     conversion is performed
+  #
+  # Sets the external and internal encodings of the stream.
+  #
+  # When the given external encoding is not `nil` or `Encoding::BINARY` or an
+  # equivalent and the internal encoding is either not given or `nil`, the
+  # current value of `Encoding.default_internal` is used for the internal
+  # encoding.
+  #
+  # When the given external encoding is `nil` and the internal encoding is either
+  # not given or `nil`, the current values of `Encoding.default_external` and
+  # `Encoding.default_internal` are used, respectively, unless
+  # `Encoding.default_external` is `Encoding::BINARY` or an equivalent **or**
+  # `Encoding.default_internal` is `nil`, in which case `nil` is used for both.
+  #
+  # Setting the given internal encoding to `"-"` indicates no character
+  # conversion should be performed.  The internal encoding of the stream will be
+  # set to `nil`.  This is needed in cases where `Encoding.default_internal` is
+  # not `nil` but character conversion is not desired.
+  #
+  # @return [self]
+  #
+  # @raise [TypeError] if the given external encoding is `nil` and the internal
+  #   encoding is given and **not** `nil`
+  # @raise [ArgumentError] if an encoding given as a string is invalid
+  def set_encoding(ext_enc, int_enc = nil, **opts)
+    assert_open
+
+    # Check that any given newline option is valid.
+    if opts.key?(:newline) &&
+      ! %i{cr lf crlf universal}.include?(opts[:newline])
+      message = 'unexpected value for newline option'
+      message += ": #{opts[:newline]}" if Symbol === opts[:newline]
+      raise ArgumentError, message
     end
 
-    # call-seq:
-    #   ios.rewind           -> 0
-    #
-    # Sets the position of the file pointer to the beginning of the stream and
-    # returns 0 when complete.  The lineno attribute is reset to 0 if
-    # successful and the stream is readable according to #readable?.
-    #
-    # As a side effect, the internal read and write buffers are flushed.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises Errno::ESPIPE unless
-    # #seekable? returns +true+.
-    #
-    # <b>NOTE:</b> Because this method relies on #unbuffered_seek and
-    # #unbuffered_write (when the internal write buffer is not empty), it will
-    # also raise the same errors and block at the same times as those functions.
-    def rewind
-      seek(0, IO::SEEK_SET)
-      self.lineno = 0 if readable?
-      0
+    # Newline handling is not allowed in binary mode.
+    if binmode? &&
+      (opts.key?(:newline) ||
+       opts[:cr_newline] || opts[:crlf_newline] || opts[:lf_newline] ||
+       opts[:universal_newline])
+      raise ArgumentError, 'newline decorator with binary mode'
     end
 
-    # call-seq:
-    #   seek(offset[, whence]) -> 0
-    #
-    # Sets the current data position to _offset_ based on the setting of
-    # _whence_.  If _whence_ is unspecified or IO::SEEK_SET, _offset_ counts
-    # from the beginning of the data.  If _whence_ is IO::SEEK_END, _offset_
-    # counts from the end of the data (_offset_ should be negative here).  If
-    # _whence_ is IO::SEEK_CUR, _offset_ is relative to the current position.
-    #
-    # As a side effect, the internal read and write buffers are flushed except
-    # when seeking relative to the current position (whence is IO::SEEK_CUR) to
-    # a location within the internal read buffer.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises Errno::ESPIPE unless
-    # #seekable? returns +true+.
-    #
-    # <b>NOTE:</b> Because this method relies on #unbuffered_seek and
-    # #unbuffered_write (when the internal write buffer is not empty), it will
-    # also raise the same errors and block at the same times as those functions.
-    def seek(offset, whence = IO::SEEK_SET)
-      __io_like__buffered_seek(offset, whence)
-      0
+    # Ruby 3.2 and below have a bug (#18899) handling the internal encoding
+    # correctly when the external encoding is binary that only happens when they
+    # are supplied individually to this method.
+    bug_18899_compatibility = RBVER_LT_3_3
+    # Convert the argument(s) into Encoding objects.
+    if ! (nil == ext_enc || Encoding === ext_enc) && nil == int_enc
+      string_arg = ensure_string(ext_enc)
+      begin
+        e, _, i = string_arg.rpartition(':')
+        # Bug #18899 compatibility is unnecessary when the encodings are passed
+        # together as a colon speparated string.
+        ext_enc, int_enc, bug_18899_compatibility = e, i, false unless e.empty?
+      rescue Encoding::CompatibilityError
+        # This is caused by failure to split on colon when the string argument
+        # is not ASCII compatible.  Ignore it and use the argument as is.
+      end
     end
 
-    # call-seq:
-    #   ios.seekable?        -> true or false
-    #
-    # Returns +true+ if the stream is seekable, +false+ otherwise.
-    #
-    # This implementation always returns +false+ for duplexed objects and
-    # checks to see if #unbuffered_seek is defined in order to make its
-    # determination otherwise.  Override this if the implementing class always
-    # provides the #unbuffered_seek method but may not always be seekable.
-    def seekable?
-      ! duplexed? && respond_to?(:unbuffered_seek, true)
+    # Potential values:
+    # ext_enc        int_enc
+    # ======================
+    # nil            Object    => error
+    # nil            nil       => maybe copy default encodings
+    # Object         Object    => use given encodings
+    # Object         nil       => maybe copy default internal encoding
+    if nil == ext_enc && nil == int_enc
+      unless Encoding::BINARY == Encoding.default_external ||
+             nil == Encoding.default_internal
+        ext_enc = Encoding.default_external
+        int_enc = Encoding.default_internal
+      end
+    else
+      ext_enc = Encoding.find(ext_enc)
+      int_enc = case int_enc
+                when nil
+                  RBVER_LT_3_3 ? nil : Encoding.default_internal
+                when '-'
+                  # Allows explicit request of no conversion when
+                  # Encoding.default_internal is set.
+                  nil
+                else
+                  Encoding.find(int_enc)
+                end
     end
 
-    # call-seq:
-    #   ios.sync             -> true or false
-    #
-    # Returns true if the internal write buffer is currently being bypassed,
-    # false otherwise.
-    #
-    # Raises IOError if #closed? returns +true+.
-    def sync
-      raise IOError, 'closed stream' if closed?
-      @__io_like__sync ||= false
+    # Ignore the chosen internal encoding when no conversion will be performed.
+    if int_enc == ext_enc ||
+       Encoding::BINARY == ext_enc && ! bug_18899_compatibility
+      int_enc = nil
     end
 
-    # call-seq:
-    #   ios.sync = boolean   -> boolean
-    #
-    # When set to +true+ the internal write buffer will be bypassed.  Any data
-    # currently in the buffer will be flushed prior to the next output
-    # operation.  When set to +false+, the internal write buffer will be
-    # enabled.
-    #
-    # Raises IOError if #closed? returns +true+.
-    def sync=(sync)
-      raise IOError, 'closed stream' if closed?
-      @__io_like__sync = sync ? true : false
+    # ASCII incompatible external encoding without conversion when reading
+    # requires binmode.
+    if ! binmode? && readable? && nil == int_enc &&
+      ! (ext_enc || Encoding.default_external).ascii_compatible?
+      raise ArgumentError, 'ASCII incompatible encoding needs binmode'
     end
 
-    # call-seq:
-    #   ios.sysread(length)  -> string
-    #
-    # Reads and returns up to _length_ bytes directly from the data stream,
-    # bypassing the internal read buffer.
-    #
-    # Returns <tt>""</tt> if _length_ is 0 regardless of the status of the data
-    # stream.  This is for compatibility with IO#sysread.
-    #
-    # Raises EOFError if reading begins at the end of the stream.  Raises
-    # IOError if the internal read buffer is not empty.  Raises IOError if
-    # #closed? returns +true+.
-    #
-    # <b>NOTE:</b> Because this method relies on #unbuffered_read, it will also
-    # raise the same errors and block at the same times as that function.
-    def sysread(length, buffer = nil)
-      buffer = buffer.nil? ? '' : buffer.to_str
-      buffer.slice!(0..-1) unless buffer.empty?
-      return buffer if length == 0
-
-      raise IOError, 'closed stream' if closed?
-      raise IOError, 'not opened for reading' unless readable?
-      unless __io_like__internal_read_buffer.empty? then
-        raise IOError, 'sysread on buffered IO'
-      end
+    delegate_r.character_io.set_encoding(ext_enc, int_enc, **opts)
+    if duplexed?
+      delegate_w.character_io.set_encoding(ext_enc, int_enc, **opts)
+    end
 
-      # Flush the internal write buffer for writable, non-duplexed objects.
-      __io_like__buffered_flush if writable? && ! duplexed?
+    self
+  end
 
-      buffer << unbuffered_read(length)
+  ##
+  # Sets the external encoding of the stream based on a byte order mark (BOM)
+  # in the next bytes of the stream if found or to `nil` if not found.
+  #
+  # @return [nil] if no byte order mark is found
+  # @return [Encoding] the encoding indicated by the byte order mark
+  #
+  # @raise [ArgumentError] if the stream is not in binary mode, an internal
+  #   encoding is set, or the external encoding is set to anything other than
+  #   `Encoding::BINARY`
+  #
+  # @version \>= Ruby 2.7
+  def set_encoding_by_bom
+    unless binmode?
+      raise ArgumentError, 'ASCII incompatible encoding needs binmode'
+    end
+    if nil != internal_encoding
+      raise ArgumentError, 'encoding conversion is set'
+    elsif nil != external_encoding && Encoding::BINARY != external_encoding
+      raise ArgumentError, "encoding is set to #{external_encoding} already"
     end
 
-    # call-seq:
-    #   ios.sysseek(offset[, whence]) -> integer
-    #
-    # Sets the current data position to _offset_ based on the setting of
-    # _whence_.  If _whence_ is unspecified or IO::SEEK_SET, _offset_ counts
-    # from the beginning of the data.  If _whence_ is IO::SEEK_END, _offset_
-    # counts from the end of the data (_offset_ should be negative here).  If
-    # _whence_ is IO::SEEK_CUR, _offset_ is relative to the current position.
-    #
-    # Raises IOError if the internal read buffer is not empty.  Raises IOError
-    # if #closed? returns +true+.  Raises Errno::ESPIPE unless #seekable?
-    # returns +true+.
-    #
-    # <b>NOTE:</b> Because this method relies on #unbuffered_seek, it will also
-    # raise the same errors and block at the same times as that function.
-    def sysseek(offset, whence = IO::SEEK_SET)
-      raise IOError, 'closed stream' if closed?
-      raise Errno::ESPIPE unless seekable?
-      unless __io_like__internal_read_buffer.empty? then
-        raise IOError, 'sysseek on buffered IO'
+    return nil unless readable?
+
+    case b1 = getbyte
+    when nil
+    when 0xEF
+      case b2 = getbyte
+      when nil
+      when 0xBB
+        case b3 = getbyte
+        when nil
+        when 0xBF
+          set_encoding(Encoding::UTF_8)
+          return Encoding::UTF_8
+        end
+        ungetbyte(b3)
       end
-      unless __io_like__internal_write_buffer.empty? then
-        warn('warning: sysseek on buffered IO')
+      ungetbyte(b2)
+    when 0xFE
+      case b2 = getbyte
+      when nil
+      when 0xFF
+        set_encoding(Encoding::UTF_16BE)
+        return Encoding::UTF_16BE
       end
-
-      unbuffered_seek(offset, whence)
+      ungetbyte(b2)
+    when 0xFF
+      case b2 = getbyte
+      when nil
+      when 0xFE
+        case b3 = getbyte
+        when nil
+        when 0x00
+          case b4 = getbyte
+          when nil
+          when 0x00
+            set_encoding(Encoding::UTF_32LE)
+            return Encoding::UTF_32LE
+          end
+          ungetbyte(b4)
+        end
+        ungetbyte(b3)
+        set_encoding(Encoding::UTF_16LE)
+        return Encoding::UTF_16LE
+      end
+      ungetbyte(b2)
+    when 0x00
+      case b2 = getbyte
+      when nil
+      when 0x00
+        case b3 = getbyte
+        when nil
+        when 0xFE
+          case b4 = getbyte
+          when nil
+          when 0xFF
+            set_encoding(Encoding::UTF_32BE)
+            return Encoding::UTF_32BE
+          end
+          ungetbyte(b4)
+        end
+        ungetbyte(b3)
+      end
+      ungetbyte(b2)
     end
+    ungetbyte(b1)
 
-    # call-seq:
-    #   ios.syswrite(string) -> integer
-    #
-    # Writes _string_ directly to the data stream, bypassing the internal write
-    # buffer and returns the number of bytes written.
-    #
-    # As a side effect for non-duplex objects, the internal read buffer is
-    # flushed.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError unless
-    # #writable? returns +true+.
-    #
-    # <b>NOTE:</b> Because this method relies on #unbuffered_write, it will also
-    # raise the same errors and block at the same times as that function.
-    def syswrite(string)
-      raise IOError, 'closed stream' if closed?
-      raise IOError, 'not opened for writing' unless writable?
-      unless __io_like__internal_write_buffer.empty? then
-        warn('warning: syswrite on buffered IO')
-      end
+    return nil
+  end
 
-      # Flush the internal read buffer and set the unbuffered position to the
-      # buffered position when dealing with non-duplexed objects.
-      unless duplexed? || __io_like__internal_read_buffer.empty? then
-        unbuffered_seek(-__io_like__internal_read_buffer.length, IO::SEEK_CUR)
-        __io_like__internal_read_buffer.slice!(0..-1)
-      end
+  ##
+  # Returns `true` if the internal write buffer is being bypassed and `false`
+  # otherwise.
+  #
+  # @return [Boolean]
+  #
+  # @raise [IOError] if the stream is closed
+  def sync
+    assert_open
+    delegate_w.character_io.sync?
+  end
 
-      unbuffered_write(string)
-    end
+  ##
+  # When set to `true` the internal write buffer will be bypassed.  Any data
+  # currently in the buffer will be flushed prior to the next output operation.
+  # When set to `false`, the internal write buffer will be enabled.
+  #
+  # @param sync [Boolean] the sync mode
+  #
+  # @return [Boolean] the given value for `sync`
+  #
+  # @raise [IOError] if the stream is closed
+  def sync=(sync)
+    assert_open
+    delegate_w.character_io.sync = sync
+  end
 
-    # call-seq:
-    #   ios.to_io            -> ios
-    #
-    # Returns _ios_.
-    def to_io
-      self
+  ##
+  # Reads and returns up to `length` bytes directly from the data stream,
+  # bypassing the internal read buffer.
+  #
+  # If `buffer` is given, it is used to store the bytes that are read;
+  # otherwise, a new buffer is created.
+  #
+  # Returns an empty String if `length` is `0` regardless of the status of the
+  # data stream.  This is for compatibility with `IO#sysread`.
+  #
+  # @param length [Integer] the number of bytes to read
+  # @param buffer [String] a buffer into which bytes will be read
+  #
+  # @return [String] the bytes that were read
+  #
+  # @raise [EOFError] if reading begins at the end of the stream
+  # @raise [IOError] if the internal read buffer is not empty
+  # @raise [IOError] if the stream is not open for reading
+  def sysread(length, buffer = nil)
+    length = ensure_integer(length)
+    raise ArgumentError, "negative length #{length} given" if length < 0
+    buffer = ensure_string(buffer) unless nil == buffer
+
+    return (buffer || ''.b) if length == 0
+
+    assert_readable
+
+    if ! delegate_r.buffered_io.read_buffer_empty?
+      raise IOError, 'sysread for buffered IO'
+    elsif ! delegate_r.character_io.buffer_empty?
+      raise IOError, 'byte oriented read for character buffered IO'
     end
 
-    # call-seq:
-    #   ios.ungetc(integer)  -> nil
-    #
-    # Calls #unread with <tt>integer.chr</tt> as an argument.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError unless
-    # #readable? returns +true+.
-    def ungetc(integer)
-      unread(integer.chr)
+    result = ensure_buffer(length, buffer) do |binary_buffer|
+      delegate_r.blocking_io.read(length, buffer: binary_buffer)
     end
 
-    # call-seq:
-    #   ios.unread(string)  -> nil
-    #
-    # Pushes the given string onto the front of the internal read buffer and
-    # returns +nil+.  If _string_ is not a String, it is converted to one using
-    # its +to_s+ method.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError unless
-    # #readable? returns +true+.
-    def unread(string)
-      raise IOError, 'closed stream' if closed?
-      raise IOError, 'not opened for reading' unless readable?
-      __io_like__internal_read_buffer.insert(0, string.to_s)
-      nil
-    end
+    # The delegate returns the read content unless a buffer is given.
+    return buffer ? buffer : result
+  end
 
-    # call-seq:
-    #   ios.write_ready?        -> true or false
-    #
-    # Returns +true+ when the stream may be written without error, +false+
-    # otherwise.  This method will block until one of the conditions is known.
-    #
-    # This default implementation of #write_ready? is a hack which should be
-    # able to work for both real IO objects and IO-like objects; however, it is
-    # inefficient since it merely sleeps for 1 second and then returns +true+ as
-    # long as #closed? returns +false+.  IO.select should be used for real
-    # IO objects to wait for a writeable condition on platforms with support for
-    # IO.select.  Other solutions should be found as necessary to improve this
-    # implementation on a case by case basis.
-    #
-    # Basically, this method should be overridden in derivative classes.
-    def write_ready?
-      return false unless writable?
-      sleep(1)
-      true
+  ##
+  # Sets the current, unbuffered stream position to `amount` based on the
+  # setting of `whence`.
+  #
+  # | `whence` | `amount` Interpretation |
+  # | -------- | ----------------------- |
+  # | `:CUR` or `IO::SEEK_CUR` | `amount` added to current stream position |
+  # | `:END` or `IO::SEEK_END` | `amount` added to end of stream position (`amount` will usually be negative here) |
+  # | `:SET` or `IO::SEEK_SET` | `amount` used as absolute position |
+  #
+  # @param offset [Integer] the amount to move the position in bytes
+  # @param whence [Integer, Symbol] the position alias from which to consider
+  #   `amount`
+  #
+  # @return [Integer] the new stream position
+  #
+  # @raise [IOError] if the internal read buffer is not empty
+  # @raise [IOError] if the stream is closed
+  # @raise [Errno::ESPIPE] if the stream is not seekable
+  def sysseek(offset, whence = IO::SEEK_SET)
+    assert_open
+    if ! delegate_r.buffered_io.read_buffer_empty? ||
+       ! delegate_r.character_io.buffer_empty?
+      raise IOError, 'sysseek for buffered IO'
+    end
+    unless delegate_w.buffered_io.write_buffer_empty?
+      warn('warning: sysseek for buffered IO')
     end
 
-    # call-seq:
-    #   ios.writable?        -> true or false
-    #
-    # Returns +true+ if the stream is both open and writable, +false+ otherwise.
-    #
-    # This implementation checks to see if #unbuffered_write is defined in order
-    # to make its determination.  Override this if the implementing class always
-    # provides the #unbuffered_write method but may not always be open in a
-    # writable mode.
-    def writable?
-      ! __io_like__closed_write? && respond_to?(:unbuffered_write, true)
+    delegate.blocking_io.seek(offset, whence)
+  end
+
+  ##
+  # Writes `string` directly to the data stream, bypassing the internal
+  # write buffer.
+  #
+  # @param string [String] a string of bytes to be written
+  #
+  # @return [Integer] the number of bytes written
+  #
+  # @raise [IOError] if the stream is not open for writing
+  def syswrite(string)
+    assert_writable
+    unless delegate_w.buffered_io.write_buffer_empty?
+      warn('warning: syswrite for buffered IO')
     end
 
-    # call-seq:
-    #   ios.write(string)    -> integer
-    #
-    # Writes the given string to the stream and returns the number of bytes
-    # written.  If _string_ is not a String, its +to_s+ method is used to
-    # convert it into one.  The entire contents of _string_ are written,
-    # blocking as necessary even if the data stream does not block.
-    #
-    # Raises IOError if #closed? returns +true+.  Raises IOError unless
-    # #writable? returns +true+.
-    #
-    # <b>NOTE:</b> This method ignores Errno::EAGAIN and Errno::EINTR raised by
-    # #unbuffered_write.  Therefore, this method always blocks if unable to
-    # immediately write _string_ completely.  Aside from that exception, this
-    # method will also raise the same errors and block at the same times as
-    # #unbuffered_write.
-    def write(string)
-      string = string.to_s
-      return 0 if string.empty?
-
-      bytes_written = 0
-      while bytes_written < string.length do
-        begin
-          bytes_written +=
-            __io_like__buffered_write(string.to_s.slice(bytes_written..-1))
-        rescue Errno::EAGAIN, Errno::EINTR
-          retry if write_ready?
+    delegate_w.buffered_io.flush || delegate_w.blocking_io.write(string.to_s.b)
+  end
+
+  ##
+  # This is for compatibility with IO.
+  alias_method :to_i, :fileno
+
+  ##
+  # @overload ungetbyte(string)
+  #   @param string [String] a string of bytes to push onto the internal read
+  #     buffer
+  #
+  # @overload ungetbyte(integer)
+  #   @param integer [Integer] a number whose low order byte will be pushed
+  #     onto the internal read buffer
+  #
+  # Pushes bytes onto the internal read buffer such that subsequent read
+  # operations will return them first.
+  #
+  # @return [nil]
+  #
+  # @raise [IOError] if the stream is not open for reading
+  # @raise [IOError] if the internal read buffer does not have enough space
+  def ungetbyte(obj)
+    assert_readable
+
+    return if nil == obj
+
+    string = case obj
+             when String
+               obj
+             when Integer
+               (obj & 255).chr
+             else
+               ensure_string(obj)
+             end
+
+    delegate_r.character_io.unread(string.b)
+
+    nil
+  end
+
+  ##
+  # @overload ungetc(string)
+  #   @param string [String] a string of characters to push onto the internal
+  #     read buffer
+  #
+  # @overload ungetc(integer)
+  #   @param integer [Integer] a number that will be converted into a character
+  #     using the stream's external encoding and pushed onto the internal read
+  #     buffer
+  #
+  # Pushes characters onto the internal read buffer such that subsequent read
+  # operations will return them first.
+  #
+  # @return [nil]
+  #
+  # @raise [IOError] if the stream is not open for reading
+  # @raise [IOError] if the internal read buffer does not have enough space
+  def ungetc(string)
+    assert_readable
+
+    return if nil == string && RBVER_LT_3_0
+
+    string = case string
+             when String
+               string.dup
+             when Integer
+               encoding = internal_encoding || external_encoding
+               nil == encoding ? string.chr : string.chr(encoding)
+             else
+               ensure_string(string)
+             end
+
+    delegate_r.character_io.unread(string.b)
+
+    nil
+  end
+
+  ##
+  # @overload wait(events, timeout)
+  #   @param events [Integer] a bit mask of `IO::READABLE`, `IO::WRITABLE`, or
+  #     `IO::PRIORITY`
+  #   @param timeout [Numeric, nil] the timeout in seconds or no timeout if
+  #     `nil`
+  #
+  # @overload wait(timeout = nil, mode = :read)
+  #   @param timeout [Numeric]
+  #   @param mode [Symbol]
+  #
+  #   @deprecated Included for compability with Ruby 2.7 and earlier
+  #
+  # @return [self] if the stream becomes ready for at least one of the given
+  #   events
+  # @return [nil] if the IO does not become ready before the timeout
+  #
+  # @raise [IOError] if the stream is closed
+  def wait(*args)
+    events = 0
+    timeout = nil
+    if RBVER_LT_3_0
+      # Ruby <=2.7 compatibility mode while running Ruby <=2.7.
+      args.each do |arg|
+        case arg
+        when Symbol
+          events |= wait_event_from_symbol(arg)
+        else
+          timeout = arg
+          if nil != timeout && timeout < 0
+            raise ArgumentError, 'time interval must not be negative'
+          end
         end
       end
-      bytes_written
+    else
+      if args.size < 2 || args.size >= 2 && Symbol === args[1]
+        # Ruby <=2.7 compatibility mode while running Ruby >=3.0.
+        timeout = args[0] if args.size > 0
+        if nil != timeout && timeout < 0
+          raise ArgumentError, 'time interval must not be negative'
+        end
+        events = args[1..-1]
+          .map { |mode| wait_event_from_symbol(mode) }
+          .inject(0) { |memo, value| memo | value }
+      elsif args.size == 2
+        # Ruby >=3.0 mode.
+        events = ensure_integer(args[0])
+        timeout = args[1]
+        if nil != timeout && timeout < 0
+          raise ArgumentError, 'time interval must not be negative'
+        end
+      else
+        # Arguments are invalid, but punt like Ruby 3.0 does.
+        return nil
+      end
     end
+    events = IO::READABLE if events == 0
 
-    private
-
-    # call-seq:
-    #   ios.__io_like__buffered_flush   -> 0
-    #
-    # Attempts to completely flush the internal write buffer to the data stream.
-    #
-    # Raises IOError unless #writable? returns +true+.
-    #
-    # <b>NOTE:</b> Because this method relies on #unbuffered_write, it raises
-    # all errors raised by #unbuffered_write and blocks when #unbuffered_write
-    # blocks.
-    def __io_like__buffered_flush
-      raise IOError, 'closed stream' if closed?
-      raise IOError, 'not opened for writing' unless writable?
-
-      until __io_like__internal_write_buffer.empty? do
-        __io_like__internal_write_buffer.slice!(
-          0, unbuffered_write(__io_like__internal_write_buffer)
-        )
-      end
-      0
+    assert_open
+
+    return self if super(events, timeout)
+    return nil
+  end
+
+  unless RBVER_LT_3_0
+  ##
+  # Waits until the stream is priority or until `timeout` is reached.
+  #
+  # Returns `true` immediately if buffered data is available to read.
+  #
+  # @return [self] when the stream is priority
+  # @return [nil] when the call times out
+  #
+  # @raise [IOError] if the stream is not open for reading
+  #
+  # @version \>= Ruby 3.0
+  def wait_priority(timeout = nil)
+    assert_readable
+
+    return self if delegate.wait(IO::PRIORITY, timeout)
+    return nil
+  end
+  end
+
+  ##
+  # Waits until the stream is readable or until `timeout` is reached.
+  #
+  # Returns `true` immediately if buffered data is available to read.
+  #
+  # @return [self] when the stream is readable
+  # @return [nil] when the call times out
+  #
+  # @raise [IOError] if the stream is not open for reading
+  def wait_readable(timeout = nil)
+    assert_readable
+
+    return self if delegate.wait(IO::READABLE, timeout)
+    return nil
+  end
+
+  ##
+  # Waits until the stream is writable or until `timeout` is reached.
+  #
+  # @return [self] when the stream is writable
+  # @return [nil] when the call times out
+  #
+  # @raise [IOError] if the stream is not open for writing
+  def wait_writable(timeout = nil)
+    assert_writable
+
+    return self if delegate.wait(IO::WRITABLE, timeout)
+    return nil
+  end
+
+  ##
+  # Writes the given arguments to the stream via an internal buffer and returns
+  # the number of bytes written.
+  #
+  # If an argument is not a `String`, its `to_s` method is used to convert it
+  # into one.  The entire contents of all arguments are written, blocking as
+  # necessary even if the underlying stream does not block.
+  #
+  # @param strings [Array<Object>] bytes to write to the stream
+  #
+  # @return [Integer] the total number of bytes written
+  #
+  # @raise [IOError] if the stream is not open for writing
+  def write(*strings)
+    # This short circuit is for compatibility with old Ruby versions where this
+    # method took a single argument and would return 0 when the argument
+    # resulted in a 0 length string without first checking if the stream was
+    # already closed.
+    if strings.size == 1
+      # This satisfies rubyspec by ensuring that the argument's #to_s method is
+      # only called once in the case where it results in a non-empty string and
+      # the short circuit is skipped.
+      strings[0] = strings[0].to_s
+      return 0 if strings[0].empty?
     end
 
-    # call-seq:
-    #   ios.__io_like__buffered_read(length) -> string
-    #
-    # Reads at most _length_ bytes first from an internal read buffer followed
-    # by the underlying stream if necessary and returns the resulting buffer.
-    #
-    # Raises EOFError if the internal read buffer is empty and reading begins at
-    # the end of the stream.  Raises IOError unless #readable? returns +true+.
-    #
-    # <b>NOTE:</b> Because this method relies on #unbuffered_read, it raises all
-    # errors raised by #unbuffered_read and blocks when #unbuffered_read blocks
-    # whenever the internal read buffer is unable to fulfill the request.
-    def __io_like__buffered_read(length)
-      # Check the validity of the method arguments.
-      raise ArgumentError, "non-positive length #{length} given" if length < 0
-
-      raise IOError, 'closed stream' if closed?
-      raise IOError, 'not opened for reading' unless readable?
-
-      # Flush the internal write buffer for writable, non-duplexed objects.
-      __io_like__buffered_flush if writable? && ! duplexed?
-
-      # Ensure that the internal read buffer has at least enough data to satisfy
-      # the request.
-      if __io_like__internal_read_buffer.length < length then
-        unbuffered_length = length - __io_like__internal_read_buffer.length
-        unbuffered_length = fill_size if unbuffered_length < fill_size
-
-        begin
-          __io_like__internal_read_buffer << unbuffered_read(unbuffered_length)
-        rescue EOFError, SystemCallError
-          # Reraise the error if there is no data to return.
-          raise if __io_like__internal_read_buffer.empty?
-        end
-      end
+    assert_writable
 
-      # Read from the internal read buffer.
-      buffer = __io_like__internal_read_buffer.slice!(0, length)
+    delegate_w.buffered_io.flush if sync
 
-      buffer
+    bytes_written = 0
+    strings.each do |string|
+      bytes_written += delegate_w.character_io.write(string.to_s)
     end
 
-    # call-seq:
-    #   ios.__io_like__buffered_seek(offset[, whence]) -> integer
-    #
-    # Sets the current data position to _offset_ based on the setting of
-    # _whence_.  If _whence_ is unspecified or IO::SEEK_SET, _offset_ counts
-    # from the beginning of the data.  If _whence_ is IO::SEEK_END, _offset_
-    # counts from the end of the data (_offset_ should be negative here).  If
-    # _whence_ is IO::SEEK_CUR, _offset_ is relative to the current position.
-    #
-    # As a side effect, the internal read and write buffers are flushed except
-    # when seeking relative to the current position (whence is IO::SEEK_CUR) to
-    # a location within the internal read buffer.
-    #
-    # Raises Errno::ESPIPE unless #seekable? returns +true+.
-    #
-    # See #seek for the usage of _offset_ and _whence_.
-    #
-    # <b>NOTE:</b> Because this method relies on #unbuffered_seek and
-    # #unbuffered_write (when the internal write buffer is not empty), it will
-    # raise the same errors and block at the same times as those functions.
-    def __io_like__buffered_seek(offset, whence = IO::SEEK_SET)
-      raise IOError, 'closed stream' if closed?
-      raise Errno::ESPIPE unless seekable?
-
-      if whence == IO::SEEK_CUR && offset == 0 then
-        # The seek is only determining the current position, so return the
-        # buffered position based on the read buffer if it's not empty and the
-        # write buffer otherwise.
-        __io_like__internal_read_buffer.empty? ?
-          unbuffered_seek(0, IO::SEEK_CUR) +
-            __io_like__internal_write_buffer.length :
-          unbuffered_seek(0, IO::SEEK_CUR) -
-            __io_like__internal_read_buffer.length
-      elsif whence == IO::SEEK_CUR && offset > 0 &&
-            __io_like__internal_write_buffer.empty? &&
-            offset <= __io_like__internal_read_buffer.length then
-        # The seek is within the read buffer, so just discard a sufficient
-        # amount of the buffer and report the new buffered position.
-        __io_like__internal_read_buffer.slice!(0, offset)
-        unbuffered_seek(0, IO::SEEK_CUR) -
-          __io_like__internal_read_buffer.length
-      else
-        # The seek target is outside of the buffers, so flush the buffers and
-        # jump to the new position.
-        if whence == IO::SEEK_CUR then
-          # Adjust relative offsets based on the current buffered offset.
-          offset += __io_like__internal_read_buffer.empty? ?
-            __io_like__internal_write_buffer.length :
-            -__io_like__internal_read_buffer.length
-        end
+    bytes_written
+  end
 
-        # Flush the internal buffers.
-        __io_like__internal_read_buffer.slice!(0..-1)
-        __io_like__buffered_flush if writable?
+  ##
+  # Enables blocking mode on the stream (via #nonblock=), flushes any buffered
+  # data, and then directly writes `string`, bypassing the internal buffer.
+  #
+  # If `string` is not a `String`, its `to_s` method is used to convert it into
+  # one.  If any of `string` is written, this method returns the number of bytes
+  # written, which may be less than all requested bytes (partial write).
+  #
+  # @param string [Object] bytes to write to the stream
+  # @param exception [Boolean] when `true` causes this method to raise
+  #   exceptions when writing would block; otherwise, symbols are returned
+  #
+  # @return [Integer] the total number of bytes written
+  # @return [:wait_readable, :wait_writable] if `exception` is `false` and
+  #   writing to the stream would block
+  #
+  # @raise [IOError] if the stream is not open for writing
+  # @raise [IO::EWOULDBLOCKWaitReadable, IO::EWOULDBLOCKWaitWritable] if
+  #   `exception` is `true` and writing to the stream would block
+  # @raise [Errno::EBADF] if non-blocking mode is not supported
+  # @raise [SystemCallError] if there are low level errors
+  def write_nonblock(string, exception: true)
+    assert_writable
+
+    string = string.to_s
+
+    self.nonblock = true
+    result = delegate_w.buffered_io.flush || delegate_w.concrete_io.write(string.b)
+    case result
+    when Integer
+      return result
+    else
+      return nonblock_response(result, exception)
+    end
+  end
 
-        # Move the data stream's position as requested.
-        unbuffered_seek(offset, whence)
-      end
+  # Expose these to other instances of this class for use with #reopen.
+  protected :delegate_r, :delegate_w
+
+  # Hide these to preserve the interface of IO.
+  private :readable?, :writable?
+
+  private
+
+  ##
+  # This returns the class name as a string for all objects including those
+  # where #class is not defined such as descendants of BasicObject.
+  #
+  # @param object [any] an object instance of any class
+  #
+  # @return [String] the class name of `object`
+  def class_name_of(object)
+    # This ensures that the standard #class method is used whether object
+    # implements its own #inspect implementation or does not implement it at
+    # all, such as for BasicObject descendants.
+    Kernel.instance_method(:class).bind(object).call.to_s
+  end
+
+  ##
+  # Ensures that a buffer, if provided, is large enough to hold the requested
+  # number of bytes and is then truncated to the returned number of bytes while
+  # ensuring that the encoding is preserved.
+  #
+  # @param length [Integer] the minimum size of the buffer in bytes
+  # @param buffer [String, nil] the buffer
+  #
+  # @yieldparam binary_buffer [String, nil] a binary encoded String based on
+  #   `buffer` (if non-nil) that is at least `length` bytes long
+  # @yieldreturn [Integer, String, Symbol] the result of a low level read
+  #   operation. (See {IO::LikeHelpers::AbstractIO#read})
+  #
+  # @return the result of the given block
+  def ensure_buffer(length, buffer)
+    if nil != buffer
+      orig_encoding = buffer.encoding
+      buffer.force_encoding(Encoding::BINARY)
+
+      # Ensure the given buffer is large enough to hold the requested number of
+      # bytes.
+      buffer << "\0".b * (length - buffer.bytesize) if length > buffer.bytesize
     end
 
-    # call-seq:
-    #   ios.__io_like__buffered_write(string) -> integer
-    #
-    # Writes _string_ to the internal write buffer and returns the number of
-    # bytes written.  If the internal write buffer is overfilled by _string_, it
-    # is repeatedly flushed until that last of _string_ is consumed.  A partial
-    # write will occur if part of _string_ fills the internal write buffer but
-    # the internal write buffer cannot be immediately flushed due to the
-    # underlying stream not blocking when unable to accept more data.
-    #
-    # <b>NOTE:</b> Because this method relies on #unbuffered_write, it raises
-    # all errors raised by #unbuffered_write and blocks when #unbuffered_write
-    # blocks whenever the internal write buffer is unable to fulfill the
-    # request.
-    def __io_like__buffered_write(string)
-      raise IOError, 'closed stream' if closed?
-      raise IOError, 'not opened for writing' unless writable?
-
-      # Flush the internal read buffer and set the unbuffered position to the
-      # buffered position when dealing with non-duplexed objects.
-      unless duplexed? || __io_like__internal_read_buffer.empty? then
-        unbuffered_seek(-__io_like__internal_read_buffer.length, IO::SEEK_CUR)
-        __io_like__internal_read_buffer.slice!(0..-1)
-      end
+    result = yield(buffer)
+  ensure
+    if nil != buffer
+      # A buffer was given to fill, so the delegate returned the number of bytes
+      # read.  Truncate the buffer if necessary and restore its original
+      # encoding.
+      buffer.slice!((result || 0)..-1)
+      buffer.force_encoding(orig_encoding)
+    end
+  end
 
-      bytes_written = 0
-      if sync then
-        # Flush the internal write buffer and then bypass it when in synchronous
-        # mode.
-        __io_like__buffered_flush
-        bytes_written = unbuffered_write(string)
-      else
-        if __io_like__internal_write_buffer.length + string.length >= flush_size then
-          # The tipping point for the write buffer would be surpassed by this
-          # request, so flush everything.
-          __io_like__buffered_flush
-          bytes_written = unbuffered_write(string)
-        else
-          # The buffer can absorb the entire request.
-          __io_like__internal_write_buffer << string
-          bytes_written = string.length
-        end
-      end
-      return bytes_written
+  ##
+  # Attempt to perform implicit conversion of `object` to an `Integer`.
+  #
+  # @param object [Object] an object to be converted via its `#to_int` method
+  #
+  # This method exists solely to make the message of any raised `TypeError`
+  # exceptions exactly match what IO methods would produce in order to appease
+  # overly prescriptive rubyspec tests; otherwise, the `Integer()` method would
+  # suffice.
+  #
+  # @return [Integer] the converted value
+  #
+  # @raise [TypeError] when conversion fails
+  def ensure_integer(object)
+    object.to_int
+  rescue NoMethodError
+    if nil == object
+      raise TypeError, 'no implicit conversion from nil to integer'
     end
 
-    # Returns a reference to the internal read buffer.
-    def __io_like__internal_read_buffer
-      @__io_like__read_buffer ||= ''
+    name = case object
+           when nil
+             'nil'
+           when false
+             'false'
+           when true
+             'true'
+           else
+             class_name_of(object)
+           end
+    raise TypeError,
+      'no implicit conversion of %s into Integer' % [name]
+  end
+
+  ##
+  # Attempt to perform implicit conversion of `object` to a `String`.
+  #
+  # @param object [Object] an object to be converted via its `#to_str` method
+  #
+  # This method exists because no other method is strict about implicit string
+  # conversion while also raising `TypeError` for failures.  For instance,
+  # `String.new` first calls `#to_str` on its argument but then falls back to
+  # `#to_s` if the former call fails.  Some rubyspec tests require a `TypeError`
+  # to be raised when implicit conversion fails, and directly calling `#to_str`
+  # raises NoMethodError if the method does not exist.
+  #
+  # @return [String] the converted value
+  #
+  # @raise [TypeError] when conversion fails
+  def ensure_string(object)
+    begin
+      result = object.to_str
+      return result if String === result
+    rescue NoMethodError
+      name = case object
+             when nil
+               'nil'
+             when false
+               'false'
+             when true
+               'true'
+             else
+               class_name_of(object)
+             end
+      raise TypeError,
+        'no implicit conversion of %s into String' % [name]
     end
 
-    # Returns a reference to the internal write buffer.
-    def __io_like__internal_write_buffer
-      @__io_like__write_buffer ||= ''
+    object_class = class_name_of(object)
+    result_class = class_name_of(result)
+    raise TypeError,
+      'can\'t convert %s to String (%s#to_str gives %s)' %
+      [object_class, object_class, result_class]
+  end
+
+  ##
+  # Write `item` followed by the record separator.  Recursively process
+  # elements of `item` if it responds to `#to_ary` with a non-`nil` result.
+  #
+  # @param item [Object] the item to be `String`-ified and written to the stream
+  # @param seen [Array] a list of `Objects` that have already been printed
+  #
+  # @return [nil]
+  def flatten_puts(item, seen = [])
+    if seen.include?(item.__id__)
+      write('[...]')
+      write(ORS)
+      return
     end
 
-    # Returns +true+ if this object has been closed for reading; otherwise,
-    # returns +false+.
-    def __io_like__closed_read?
-      @__io_like__closed_read ||= false
+    seen.push(item.__id__)
+
+    array = item.to_ary rescue nil
+    if nil == array
+      string = item.to_s
+      unless String === string
+        # This ensures that #inspect-like output is generated even if item
+        # implements its own #inspect implementation or does not implement it at
+        # all, such as for BasicObject descendants.
+        string =
+          Kernel.instance_method(:inspect).bind(item).call.sub(%r{ .*}, '>')
+      end
+      write(string)
+      write(ORS) unless string.end_with?(ORS)
+    else
+      array.each { |i| flatten_puts(i, seen) }
     end
 
-    # Arranges for #__io_like__closed_read? to return +true+.
-    def __io_like__close_read
-      @__io_like__closed_read = true
-      nil
+    seen.pop
+
+    nil
+  end
+
+  ##
+  # Converts non-blocking responses into exceptions if requested.
+  #
+  # @param type [:wait_readable, :wait_writable] the type of non-blocking
+  #   response
+  # @param exception [Boolean] if `true`, raise an exception for `type`
+  #
+  # @return [:wait_readable, :wait_writable] if `exception` is `false`
+  def nonblock_response(type, exception)
+    case type
+    when :wait_readable
+      return type unless exception
+      raise IO::EWOULDBLOCKWaitReadable
+    when :wait_writable
+      return type unless exception
+      raise IO::EWOULDBLOCKWaitWritable
+    else
+      raise ArgumentError, "Invalid type: #{type}"
     end
+  end
 
-    # Returns +true+ if this object has been closed for writing; otherwise,
-    # returns +false+.
-    def __io_like__closed_write?
-      @__io_like__closed_write ||= false
+  ##
+  # Parses the positional arguments for #readline, #gets, and related methods.
+  #
+  # @return [[String, Integer]] an array containing the separator string and the
+  #   maximum length
+  def parse_readline_args(*args)
+    if args.size > 2
+      raise ArgumentError,
+        "wrong number of arguments (given #{args.size}, expected 0..2)"
+    elsif args.size == 2
+      sep_string = nil == args[0] ? nil : ensure_string(args[0])
+      limit = nil == args[1] ? nil : ensure_integer(args[1])
+    elsif args.size == 1
+      begin
+        sep_string = nil == args[0] ? nil : ensure_string(args[0])
+        limit = nil
+      rescue TypeError
+        limit = ensure_integer(args[0])
+        sep_string = $/
+      end
+    else
+      sep_string = $/
+      limit = nil
     end
 
-    # Arranges for #__io_like__closed_write? to return +true+.
-    def __io_like__close_write
-      @__io_like__closed_write = true
-      nil
+    return [sep_string, limit]
+  end
+
+  ##
+  # Reads and returns up to `length` bytes from this stream.
+  #
+  # This method always blocks, even when the stream is in non-blocking mode.  An
+  # empty `String` is returned if reading begins at the end of the stream.
+  #
+  # @param length [Integer] the number of bytes to read
+  #
+  # @return [String] up to `length` bytes read from this stream
+  def read_bytes(length)
+    buffer = ''.b
+
+    if delegate_r.buffered_io.read_buffer_empty?
+      # Flush any pending write data in the buffered IO in preparation for
+      # reading directly from the delegate behind it.
+      delegate_r.buffered_io.flush
+    else
+      buffer << delegate_r.buffered_io.read(length)
+      length -= buffer.bytesize
     end
 
-    # This method joins the elements of _array_ together with _separator_
-    # between each element and returns the result.  _seen_ is a list of object
-    # IDs representing arrays which have already started processing.
-    #
-    # This method exists only because Array#join apparently behaves in an
-    # implementation dependent manner when joining recursive arrays and so does
-    # not always produce the expected results.  Specifically, MRI 1.8.6 and
-    # 1.8.7 behave as follows:
-    #
-    #   x = []
-    #   x << 1 << x << 2
-    #   x.join(', ')              => "1, 1, [...], 2, 2"
-    #
-    # The expected and necessary result for use with #puts is:
-    #
-    #   "1, [...], 2"
-    #
-    # Things get progressively worse as the nesting and recursion become more
-    # convoluted.
-    def __io_like__array_join(array, separator, seen = [])
-      seen.push(array.object_id)
-      need_separator = false
-      result = array.inject('') do |memo, item|
-        memo << separator if need_separator
-        need_separator = true
-
-        memo << if item.kind_of?(Array) then
-                  if seen.include?(item.object_id) then
-                    '[...]'
-                  else
-                    __io_like__array_join(item, separator, seen)
-                  end
-                else
-                  item.to_s
-                end
+    begin
+      while length > 0 do
+        bytes = delegate_r.blocking_io.read(length)
+        length -= bytes.bytesize
+        buffer << bytes
       end
-      seen.pop
+    rescue EOFError
+    end
 
-      result
+    buffer
+  end
+
+  ##
+  # @return [Symbol] a `Symbol` equivalent to the given `mode` for Ruby 2.7 and
+  #   lower for use with `#wait`
+  def wait_event_from_symbol(mode)
+    case mode
+    when :r, :read, :readable
+      IO::READABLE
+    when :w, :write, :writable
+      IO::WRITABLE
+    when :rw, :read_write, :readable_writable
+      IO::READABLE || IO::WRITABLE
+    else
+      raise ArgumentError, "unsupported mode: #{mode}"
     end
   end
 end
+end
 
 # vim: ts=2 sw=2 et