iostreams 2.1.0 → 2.2.0

data/lib/io_streams/bzip2/reader.rb

@@ -8,9 +8,25 @@ module IOStreams
         nil
       end
 
+      # Returns [Array<Symbol>] the options that this class takes, which v3.0 declares as its `option_names`, see
+      # `IOStreams::Deprecation::OptionNames#known_option_names`, so that an option that neither it nor the writer takes
+      # is reported as deprecated when it is set, while one of the writer is not, since v3.0 accepts it, and ignores it,
+      # and so that a path opens it with these alone, and logs the others, see `IOStreams::Builder#taken_options`.
+      def self.known_option_names
+        OPTION_NAMES
+      end
+
+      # Returns [Array<Symbol>] the methods that the stream that v3.0 supplies to a reader block, in place of the
+      # `Bzip2::FFI::Reader` that this reader yields, answers: those of an IO that read, see
+      # `IOStreams::Reader.v3_stream_methods`.
+      def self.v3_stream_methods(_options)
+        V3_READ_METHODS
+      end
+
       # Read from a Bzip2 stream, decompressing the contents as it is read
       #
-      # Any other option is ignored and logs a warning. It will raise `ArgumentError` in v3.0.
+      # Any other option is ignored, and logs a warning. One that the writer does not take either also reports a
+      # deprecation warning when it is set, see .known_option_names, since it will raise `ArgumentError` in v3.0.
       #
       # Parameters are passed through to `Bzip2::FFI::Reader`:
       #   autoclose: [true|false]
@@ -25,7 +41,7 @@ module IOStreams
       #     Use an alternative decompression algorithm that uses less memory but is slower.
       #     Default: false
       def self.stream(input_stream, autoclose: false, first_only: false, small: false, **unknown)
-        Utils.warn_unknown_options(unknown, :bz2, "reading", OPTION_NAMES)
+        Utils.warn_unknown_options(unknown, :bz2, :reader, OPTION_NAMES)
         Utils.load_soft_dependency("bzip2-ffi", "Bzip2", "bzip2/ffi") unless defined?(::Bzip2::FFI)
 
         begin

data/lib/io_streams/bzip2/writer.rb

@@ -8,9 +8,18 @@ module IOStreams
         nil
       end
 
+      # Returns [Array<Symbol>] the options that this class takes, which v3.0 declares as its `option_names`, see
+      # `IOStreams::Deprecation::OptionNames#known_option_names`, so that an option that neither it nor the reader takes
+      # is reported as deprecated when it is set, while one of the reader is not, since v3.0 accepts it, and ignores it,
+      # and so that a path opens it with these alone, and logs the others, see `IOStreams::Builder#taken_options`.
+      def self.known_option_names
+        OPTION_NAMES
+      end
+
       # Write to a stream, compressing with Bzip2
       #
-      # Any other option is ignored and logs a warning. It will raise `ArgumentError` in v3.0.
+      # Any other option is ignored, and logs a warning. One that the reader does not take either also reports a
+      # deprecation warning when it is set, see .known_option_names, since it will raise `ArgumentError` in v3.0.
       #
       # Parameters are passed through to `Bzip2::FFI::Writer`:
       #   autoclose: [true|false]
@@ -26,7 +35,7 @@ module IOStreams
       #     to a slower algorithm, from 0 to 250. 0 uses the libbz2 default.
       #     Default: 0
       def self.stream(input_stream, autoclose: false, block_size: nil, work_factor: nil, **unknown)
-        Utils.warn_unknown_options(unknown, :bz2, "writing", OPTION_NAMES)
+        Utils.warn_unknown_options(unknown, :bz2, :writer, OPTION_NAMES)
         Utils.load_soft_dependency("bzip2-ffi", "Bzip2", "bzip2/ffi") unless defined?(::Bzip2::FFI)
 
         begin

data/lib/io_streams/deprecation/methods.rb

@@ -0,0 +1,51 @@
+module IOStreams
+  module Deprecation
+    # A module whose methods report a deprecation warning when the application calls them, and then call the method of
+    # the object that it extends, see .deprecate: for the methods of an object that IOStreams hands the application, such
+    # as the `Zlib::GzipReader` that a reader block receives for a `.gz` file, that the object that v3.0 hands it in its
+    # place does not answer, such as `#rewind`.
+    class Methods < ::Module
+      @modules = {}
+      @mutex   = Mutex.new
+
+      # Extends the supplied object, which IOStreams hands to the application, with a module that reports a deprecation
+      # warning for each of its public methods that the object in its place in v3.0 does not answer: those other than
+      # the supplied methods, which that object answers, and the methods of every object. Each warning is the name of the
+      # method, such as `#rewind`, followed by the supplied message, such as "is deprecated on ...", or by the message of
+      # its name when the message is a Hash, such as one that names what replaces it, otherwise that of nil.
+      #
+      # The module is prepended to the singleton class of the object, rather than extending it, so that its methods
+      # come before those that the object defines on itself, such as the `#path` of a `Zlib::GzipReader`. The object
+      # keeps its class, and answers the same methods, which each still call its own method. Only the calls that the
+      # application makes itself report a warning, see `IOStreams::Deprecation.warn_call`, and none while deprecation
+      # warnings are off. The module is built once for each class of object, and kept, so that each object costs one
+      # `prepend`, and nothing else until a deprecated method is called.
+      #
+      # Returns the object.
+      def self.deprecate(object, kept_methods, message)
+        return object if object.frozen?
+
+        key        = [object.class, object.singleton_methods.sort, kept_methods, message]
+        deprecated = @mutex.synchronize do
+          @modules[key] ||= new(object.public_methods - ::Object.public_instance_methods - kept_methods, message)
+        end
+        object.singleton_class.prepend(deprecated)
+        object
+      end
+
+      # Defines a method for each of the supplied names that reports the deprecation warning of its name, followed by the
+      # supplied message, or its own message when it is a Hash, see .deprecate, when the application calls it, and then
+      # calls the method of the object.
+      def initialize(names, message)
+        super()
+        names.each do |name|
+          warning = "##{name} #{message.is_a?(Hash) ? message.fetch(name) { message.fetch(nil) } : message}".freeze
+          define_method(name) do |*args, **kwargs, &block|
+            ::IOStreams::Deprecation.warn_call(warning) if ::Warning[:deprecated]
+            super(*args, **kwargs, &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/io_streams/deprecation/once.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module IOStreams
+  module Deprecation
+    # Reports a deprecation warning the first time that it applies, for an object that would otherwise report one for each
+    # value that it converts, such as a field of a schema, which converts a value of each row of a file. The object holds
+    # one for each of its deprecations, which is not frozen with it, so that an object that is frozen, as a field is,
+    # still reports each one once.
+    class Once
+      # Reports the deprecation warning that the block returns, see `IOStreams::Deprecation.warn`, unless this has
+      # reported it already, or deprecation warnings are off, see `IOStreams::Deprecation.on?`, when the block is not
+      # called, so that a caller builds its message only when it is reported. The block returns nil when the
+      # deprecation does not apply to the value at hand, which leaves it to be reported for a later one.
+      #
+      # Returns nil.
+      def warn
+        return if @reported || !Deprecation.on?
+
+        message = yield
+        return if message.nil?
+
+        @reported = true
+        Deprecation.warn(message)
+      end
+    end
+  end
+end

data/lib/io_streams/deprecation/option_names.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module IOStreams
+  module Deprecation
+    # The names of the options that a reader or a writer takes in IOStreams 3.0, which `IOStreams::Reader` and
+    # `IOStreams::Writer` extend, so that each of their subclasses answers them. `#option`, `#stream` and
+    # `#option_or_stream` report a deprecation warning for an option that IOStreams 3.0 raises ArgumentError for when it
+    # is set: one that the reader or the writer of the stream replaces, see #replaced_option_names, and one that neither
+    # of them takes, see #known_option_names, such as a misspelled one, see `IOStreams::Builder#option`.
+    module OptionNames
+      # Returns [Array<Symbol>] the names of the options that this class takes in IOStreams 3.0 too, or [nil] when they
+      # are not known, since it does not declare its options: by default those that it declares, see `.option_names`,
+      # other than those that it replaces, see #replaced_option_names.
+      def known_option_names
+        names = option_names
+        names && (names - replaced_option_names.keys)
+      end
+
+      # Returns [Hash<Symbol, Symbol>] the deprecated options that this class still takes, which IOStreams 3.0 does not,
+      # with the option that replaces each, which the deprecation warning names. None by default.
+      def replaced_option_names
+        {}
+      end
+    end
+  end
+end

data/lib/io_streams/deprecation/words.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module IOStreams
+  module Deprecation
+    # The words of the message of a deprecation warning that depend on how many things it is about, such as the options
+    # that are deprecated, so that each message says "is" and "it" of one, and "are" and "them" of more, see .warn.
+    class Words
+      # Parameters:
+      #   items: [Array]
+      #     The things that the message is about, such as the names of options.
+      def initialize(items)
+        @items = items
+      end
+
+      # Returns [String] the items as the keywords that a caller supplies them as, such as `compress:, level:`, and an
+      # item that is not a Symbol, which is not a keyword, as it is written, such as `"acl"`.
+      def keywords
+        @items.map { |item| item.is_a?(Symbol) ? "#{item}:" : item.inspect }.join(", ")
+      end
+
+      # Returns [true|false] whether the message is about one item.
+      def one?
+        @items.size == 1
+      end
+
+      # Returns [String] "are", or "is" of one item.
+      def are
+        one? ? "is" : "are"
+      end
+
+      # Returns [String] "them", or "it" of one item.
+      def them
+        one? ? "it" : "them"
+      end
+
+      # Returns [String] "they are", or "it is" of one item.
+      def they_are
+        one? ? "it is" : "they are"
+      end
+    end
+  end
+end

data/lib/io_streams/deprecation.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module IOStreams
+  # Reports the use of a deprecated method or option as a Ruby deprecation warning, see `Kernel#warn`, so that Ruby
+  # decides whether and where it is reported, as it does for its own deprecations, rather than a setting of IOStreams:
+  # - Only while deprecation warnings are on, see `Warning[:deprecated]`. They are off by default, so production stays
+  #   quiet, and on in tests run by Minitest or test-unit, or with `ruby -W:deprecated` or `RUBYOPT=-W:deprecated`.
+  # - Written to `$stderr`, unless the application routes them elsewhere, such as to its log, or raises them in its
+  #   tests, by overriding `Warning.warn`.
+  #
+  # Each warning names the line of the application that used what is deprecated, rather than a line of IOStreams, of
+  # Ruby itself, or of a gem that IOStreams called with a block, see .application_location.
+  module Deprecation
+    autoload :Methods,     "io_streams/deprecation/methods"
+    autoload :Once,        "io_streams/deprecation/once"
+    autoload :OptionNames, "io_streams/deprecation/option_names"
+    autoload :Words,       "io_streams/deprecation/words"
+
+    # The directory of the files of this library, whose lines are skipped when finding the line that used it.
+    LIB_DIR = "#{__dir__}/".freeze
+    private_constant :LIB_DIR
+
+    # The file that loads this library, whose lines are skipped too. Only the files of this library are skipped, rather
+    # than every file of the directory that holds them, which can hold other libraries, such as `site_ruby`, or the
+    # `lib` directory of an application that it is copied into.
+    LIB_FILE = File.expand_path("../iostreams.rb", __dir__).freeze
+    private_constant :LIB_FILE
+
+    # The text that each warning starts with, after the location of the line that used what is deprecated.
+    PREFIX = "IOStreams: "
+    private_constant :PREFIX
+
+    # A warning reported by .warn, as `Kernel#warn` passes it to `Warning.warn`, see .warning?.
+    WARNING = /\A(?:.+:\d+: warning: )?#{Regexp.escape(PREFIX)}/
+    private_constant :WARNING
+
+    # The start of the paths of the core methods that Ruby writes in Ruby, such as `Kernel#tap`, see .core?.
+    CORE_PATH = "<internal:"
+    private_constant :CORE_PATH
+
+    # The start of the paths of the standard library of JRuby, when it is loaded from its jar.
+    JAR_PATH = "uri:classloader:"
+    private_constant :JAR_PATH
+
+    # The files of this module, whose methods find the line that called a deprecated method, see .calling_location.
+    OWN_FILES = ["#{__dir__}/deprecation.rb", "#{__dir__}/deprecation/methods.rb"].freeze
+    private_constant :OWN_FILES
+
+    # The end of the names of the files of the standard library of Ruby that define its delegators: `delegate.rb`, which
+    # defines `SimpleDelegator` and `DelegateClass`, and `forwardable.rb`, which defines `Forwardable`, see .delegator?.
+    DELEGATOR_FILES = %w[/delegate.rb /forwardable.rb].freeze
+    private_constant :DELEGATOR_FILES
+
+    # The directory of the standard library of Ruby.
+    RUBY_LIB_DIRS = [RbConfig::CONFIG["rubylibdir"]].compact.map { |dir| "#{dir}/" }.freeze
+    private_constant :RUBY_LIB_DIRS
+
+    # Reports that the application used something deprecated, unless deprecation warnings are off, with the message,
+    # which says what is deprecated and what to use instead, after "IOStreams: ", at the line of the application that
+    # used it, see .application_location, in the same form as `Kernel#warn` names the line of its caller, such as
+    # `app/jobs/export_job.rb:12: warning: IOStreams: stream(:none) is deprecated, ...`, or without a line when the
+    # call stack has none outside this library.
+    #
+    # Returns nil.
+    def self.warn(message)
+      return unless on?
+
+      report(message, application_location)
+    end
+
+    # Reports, as .warn does, that the application uses something deprecated while this library is loaded, such as a
+    # version of Ruby that IOStreams 3.0 does not support, at the line of the application that loaded it, see
+    # .loading_location, rather than at a line of a gem that requires it for the application, such as Bundler.
+    #
+    # Returns nil.
+    def self.warn_on_load(message)
+      return unless on?
+
+      report(message, loading_location)
+    end
+
+    # Reports, as .warn does, that the application called a deprecated method of an object that IOStreams handed it,
+    # such as the stream that a reader block receives, which calls this from that method, see
+    # `IOStreams::Deprecation::Methods`, at the line that called the method, see .calling_location, when it is the
+    # application's own: not a line of IOStreams, which calls the methods of the object for itself, of a gem, such as the
+    # gem whose object it is, which calls its own methods, or of a library that the application handed the object to,
+    # including the standard library of Ruby, see .standard_library?. So a method that the application hands IOStreams
+    # as the block itself, such as `reader(&:rewind)`, is not reported, since IOStreams calls it, while one that it hands
+    # a core method of Ruby, such as `io.then(&:rewind)`, or calls through a delegator of Ruby that wraps the object,
+    # such as `SimpleDelegator.new(io).rewind`, is, since they call it for the application.
+    #
+    # Returns nil.
+    def self.warn_call(message)
+      return unless Warning[:deprecated]
+
+      location = calling_location
+      return if location.nil? || library?(location) || gem?(location, installed_gem_dirs) || standard_library?(location)
+
+      report(message, location)
+    end
+
+    # Returns [true|false] whether the message, as `Kernel#warn` passes it to `Warning.warn`, is a warning reported by
+    # .warn, so that an application, or its tests, can tell the deprecation warnings of IOStreams from the others.
+    def self.warning?(message)
+      WARNING.match?(message)
+    end
+
+    # Returns [true|false] whether deprecation warnings are on, see `Warning[:deprecated]`, so that .warn reports them,
+    # for a caller to find out whether something is deprecated only while they are, where finding it out costs more
+    # than the call to .warn.
+    def self.on?
+      Warning[:deprecated]
+    end
+
+    # Returns [Thread::Backtrace::Location|nil] the line of the application that used this library, or nil when the
+    # call stack has none outside this library. It is the first line of the call stack outside this library, other
+    # than:
+    # - A line of Ruby itself, see .ruby?, which runs on behalf of its caller, such as `Kernel#tap`, or `Open3.popen2e`
+    #   that this library calls with a block, as Ruby names the caller of its own core methods.
+    # - A line of a gem that this library called with a block, such as `Net::SFTP.start`, which has a line of this
+    #   library further out in the call stack. A line of a gem that called this library, such as one of Rocket Job, is
+    #   the one returned, since it is the gem that used it.
+    #
+    # The call stack is walked outward from the caller, until the line of the application is found, rather than
+    # creating all of it.
+    def self.application_location
+      gem_dirs  = installed_gem_dirs
+      candidate = nil
+      Thread.each_caller_location do |location|
+        if library?(location)
+          candidate = nil
+        elsif gem?(location, gem_dirs)
+          candidate ||= location
+        elsif !ruby?(location)
+          return candidate || location
+        end
+      end
+      candidate
+    end
+    private_class_method :application_location
+
+    # Returns [Thread::Backtrace::Location|nil] the line of the application that loaded this library, such as its
+    # `require "iostreams"`, or its `Bundler.require`: the first line of the call stack outside this library, Ruby
+    # itself, see .ruby?, and the installed gems, since a gem that loads this library, such as Bundler, Bootsnap, or a gem
+    # that requires it, loads it for the application. Otherwise the first line of an installed gem outside this library,
+    # for an application that is itself an installed gem, or nil when the call stack has neither.
+    def self.loading_location
+      gem_dirs  = installed_gem_dirs
+      candidate = nil
+      Thread.each_caller_location do |location|
+        next if library?(location) || ruby?(location)
+        return location unless gem?(location, gem_dirs)
+
+        candidate ||= location
+      end
+      candidate
+    end
+    private_class_method :loading_location
+
+    # Returns [Thread::Backtrace::Location|nil] the line that called the deprecated method that called .warn_call: the
+    # first line of the call stack outside the files of this module, other than a line of a core method, see .core?, or
+    # of a delegator of Ruby, see .delegator?, which calls the method for its caller, such as `Kernel#then` in
+    # `io.then(&:rewind)`, or the `SimpleDelegator` in `SimpleDelegator.new(io).rewind`. Ruby names the line that
+    # called a core method written in C in its place, and CRuby 4.0 does the same for one written in Ruby, so skipping
+    # the lines that earlier versions name gives the same line on each version of Ruby.
+    def self.calling_location
+      Thread.each_caller_location do |location|
+        next if OWN_FILES.include?(location.absolute_path || location.path) || core?(location) || delegator?(location)
+
+        return location
+      end
+      nil
+    end
+    private_class_method :calling_location
+
+    # Writes the message as a deprecation warning, see .warn, at the supplied line, or without a line when it is nil.
+    def self.report(message, location)
+      text = "#{PREFIX}#{message}"
+      text = "#{location.path}:#{location.lineno}: warning: #{text}" if location
+      Kernel.warn(text, category: :deprecated)
+      nil
+    end
+    private_class_method :report
+
+    # Returns [true|false] whether the line of the call stack is in a file of this library. Code run with `eval` has
+    # only the file name that it was given.
+    def self.library?(location)
+      file = location.absolute_path || location.path
+      file.start_with?(LIB_DIR) || file == LIB_FILE
+    end
+    private_class_method :library?
+
+    # Returns [true|false] whether the line of the call stack is in the code of Ruby itself: a core method, see .core?,
+    # or a file of its standard library, see .standard_library?.
+    def self.ruby?(location)
+      core?(location) || standard_library?(location)
+    end
+    private_class_method :ruby?
+
+    # Returns [true|false] whether the line of the call stack is in a core method of Ruby that is not written in C: one
+    # written in Ruby, such as `Kernel#tap`, in a file whose name starts with `<internal:`, which CRuby before 4.0 and
+    # JRuby name in the call stack, or one of JRuby written in Java. Ruby names the line that called a core method
+    # written in C in its place, as CRuby 4.0 does for one written in Ruby.
+    def self.core?(location)
+      path = location.path
+      path.start_with?(CORE_PATH) || path.end_with?(".java")
+    end
+    private_class_method :core?
+
+    # Returns [true|false] whether the line of the call stack is in a file of the standard library of Ruby, see
+    # RUBY_LIB_DIRS, or of that of JRuby, when it is loaded from its jar.
+    def self.standard_library?(location)
+      location.path.start_with?(JAR_PATH) || in_dirs?(location, RUBY_LIB_DIRS)
+    end
+    private_class_method :standard_library?
+
+    # Returns [true|false] whether the line of the call stack is in a delegator of the standard library of Ruby, see
+    # DELEGATOR_FILES, which calls the method of the object that it wraps for its caller, as a core method does: the
+    # `#method_missing` of a `SimpleDelegator`, or a method that `DelegateClass` or `Forwardable` defines. The other
+    # files of the standard library call the methods of an object for themselves, such as a library that the
+    # application hands the object to, see .warn_call.
+    def self.delegator?(location)
+      location.path.end_with?(*DELEGATOR_FILES) && standard_library?(location)
+    end
+    private_class_method :delegator?
+
+    # Returns [true|false] whether the line of the call stack is in a file of a gem, in one of the directories of the
+    # installed gems.
+    def self.gem?(location, gem_dirs)
+      in_dirs?(location, gem_dirs)
+    end
+    private_class_method :gem?
+
+    # Returns [true|false] whether the file of the line of the call stack is in one of the directories, by the path
+    # that it was loaded from, or its absolute path, which differs when the path holds a link.
+    def self.in_dirs?(location, dirs)
+      location.path.start_with?(*dirs) || location.absolute_path&.start_with?(*dirs) || false
+    end
+    private_class_method :in_dirs?
+
+    # Returns [Array<String>] the directories of the installed gems, see `Gem.path`, each ending with "/". They are kept
+    # for as long as `Gem.path` returns the same Array, since Bundler replaces it when it changes them, so that a
+    # deprecated method that a gem calls for each line, see .warn_call, builds them once, rather than on each call.
+    def self.installed_gem_dirs
+      return [] unless defined?(::Gem)
+
+      path   = ::Gem.path
+      cached = @installed_gem_dirs
+      return cached.last if cached&.first.equal?(path)
+
+      dirs                = path.map { |dir| dir.end_with?("/") ? dir : "#{dir}/" }.freeze
+      @installed_gem_dirs = [path, dirs].freeze
+      dirs
+    end
+    private_class_method :installed_gem_dirs
+  end
+end

data/lib/io_streams/encode/reader.rb

@@ -5,6 +5,23 @@ module IOStreams
         %i[encoding cleaner replace]
       end
 
+      # The methods that the stream that v3.0 supplies to a reader block for the encoding answers: those of an IO that
+      # read, and #input_stream, see .v3_stream_methods.
+      V3_METHODS = [*V3_READ_METHODS, :input_stream].freeze
+      private_constant :V3_METHODS
+
+      # Returns [Array<Symbol>] the methods that the stream that v3.0 supplies to a reader block for the encoding answers,
+      # in place of this reader, see `IOStreams::Reader.v3_stream_methods`. It has no #encoding or #cleaner, which the
+      # settings of the path replace, see .v3_stream_advice.
+      def self.v3_stream_methods(_options)
+        V3_METHODS
+      end
+
+      # Returns [Hash<Symbol:String>] what replaces #encoding and #cleaner, see `IOStreams::Reader.v3_stream_advice`.
+      def self.v3_stream_advice
+        V3_STREAM_ADVICE
+      end
+
       attr_reader :encoding, :cleaner
 
       NOT_PRINTABLE = /[^[:print:]|\r\n]/
@@ -60,7 +77,11 @@ module IOStreams
 
       # Returns [String] data returned from the input stream.
       # Returns [nil] if end of file and no further data was read.
-      def read(size = nil)
+      #
+      # As IO#read does, the data is read into the supplied buffer, which is returned, and which is empty once the end
+      # of the file was reached, so that `IO.copy_stream`, which supplies one, can read it, such as for a copy without a
+      # mode from a stream with an encoding.
+      def read(size = nil, outbuf = nil)
         block =
           if @read_cache_buffer
             begin
@@ -75,11 +96,18 @@ module IOStreams
           end
 
         # EOF reached?
-        return unless block
+        unless block
+          outbuf&.clear
+          return
+        end
 
+        block = text(block, size) if text_bytes?(block)
         block = block.encode(@encoding, **@encoding_options) unless block.encoding == @encoding
         block = @cleaner.call(block, @replace) if @cleaner
-        block
+        return outbuf.replace(block) if outbuf
+
+        # A copy of the buffer that it reads into, which the next read writes over, so that the caller keeps the data.
+        block.equal?(@read_cache_buffer) ? block.dup : block
       end
 
       def self.extract_cleaner(cleaner)
@@ -95,6 +123,29 @@ module IOStreams
           cleaner
         end
       end
+
+      private
+
+      # Returns [true|false] whether the binary data that a read returned can hold the bytes of text in the encoding,
+      # rather than text to convert into it, see #text. Without `replace:` it reads into a buffer of the encoding, whose
+      # bytes are then the text, as `IO#read` keeps the encoding of the buffer that it is supplied for a read of a length.
+      # A stream that returns the bytes as binary instead, since its `#read` takes no buffer, as `Zlib::GzipReader` on
+      # JRuby, or makes the buffer binary, as `Bzip2::FFI::Reader` does, holds the same text, as does a read of the whole
+      # of the data, which `IO#read` returns as binary, and converting it from binary would reject each character that is
+      # not ASCII. With `replace:` it is converted from binary, replacing each character that is not ASCII, as before.
+      def text_bytes?(block)
+        @replace.nil? && block.encoding == Encoding::BINARY
+      end
+
+      # Returns [String] the bytes of the binary data as text in the encoding, in a String of its own, rather than the
+      # String that the input stream returned, which it can still hold, such as a buffer that it reuses. Those of a read
+      # of a length are taken as they are, as `IO#read` reads them into a buffer of the encoding, since a character can
+      # be split between two reads. The whole of the data is taken only when it is valid in the encoding; otherwise the
+      # data itself is returned, which is converted from binary, raising for each character that is not ASCII, as before.
+      def text(block, size)
+        text = ::String.new(block, encoding: @encoding)
+        size.nil? && !text.valid_encoding? ? block : text
+      end
     end
   end
 end

data/lib/io_streams/encode/writer.rb

@@ -5,6 +5,23 @@ module IOStreams
         %i[encoding cleaner replace]
       end
 
+      # The methods that the stream that v3.0 supplies to a writer block for the encoding answers: those of an IO that
+      # write, #finish and #output_stream, see .v3_stream_methods.
+      V3_METHODS = [*V3_WRITE_METHODS, :finish, :output_stream].freeze
+      private_constant :V3_METHODS
+
+      # Returns [Array<Symbol>] the methods that the stream that v3.0 supplies to a writer block for the encoding answers,
+      # in place of this writer, see `IOStreams::Writer.v3_stream_methods`. It has no #encoding or #cleaner, which the
+      # settings of the path replace, see .v3_stream_advice.
+      def self.v3_stream_methods(_options)
+        V3_METHODS
+      end
+
+      # Returns [Hash<Symbol:String>] what replaces #encoding and #cleaner, see `IOStreams::Reader.v3_stream_advice`.
+      def self.v3_stream_advice
+        V3_STREAM_ADVICE
+      end
+
       attr_reader :encoding, :cleaner
 
       # Write a line at a time to a file or stream
@@ -50,7 +67,7 @@ module IOStreams
       # Write a line to the output stream
       #
       # Example:
-      #   IOStreams.path('a.txt').option(:encode, encoding: 'UTF-8').writer do |stream|
+      #   IOStreams.path('a.txt').encoding('UTF-8').writer do |stream|
       #     stream << 'first line' << 'second line'
       #   end
       def <<(record)
@@ -62,7 +79,7 @@ module IOStreams
       # Returns [Integer] the number of bytes written.
       #
       # Example:
-      #   IOStreams.path('a.txt').option(:encode, encoding: 'UTF-8').writer do |stream|
+      #   IOStreams.path('a.txt').encoding('UTF-8').writer do |stream|
       #     count = stream.write('first line')
       #     puts "Wrote #{count} bytes to the output file"
       #   end