iostreams 2.1.0 → 2.2.0

data/lib/io_streams/builder/deprecations.rb

@@ -0,0 +1,250 @@
+module IOStreams
+  class Builder
+    # What v2.2 reports about the streams, options and format of a builder as deprecation warnings: those that
+    # IOStreams v3.0 removes or rejects, and those whose results change in v3.0, with what to use instead. It is part
+    # of the Builder, which includes it, since the Builder owns the settings that it reports on.
+    module Deprecations
+      # A format set with #format= that is not the format of the text that the streams read, see #text_format, such as
+      # `:psv` for a spreadsheet, whose rows are read as CSV, is deprecated, since v3.0 raises ArgumentError when its
+      # lines, rows or records are read, rather than read them in that format. Reports a deprecation warning when they are
+      # read, as v3.0 raises then, whichever way the streams were set.
+      #
+      # So is reading them in the format that the file name names, such as `:psv` for `report.psv.xlsx`, without a format
+      # set, since v3.0 reads them in the format of the text whatever the file name, so that `format(:csv)` reads them
+      # the same in both versions.
+      #
+      # Neither is looked for while deprecation warnings are off, see `IOStreams::Deprecation.on?`, since finding the
+      # format of the text would build the pipeline once more for each read.
+      def warn_text_format
+        return unless Deprecation.on?
+
+        format = self.format
+        return if format.nil?
+
+        text_format = self.text_format
+        return if text_format.nil? || format == text_format
+
+        if @set_format
+          Deprecation.warn("format(#{format.inspect}) is deprecated when the streams read the rows as " \
+                           "#{text_format.inspect}, such as those of a spreadsheet, since v3.0 raises ArgumentError for " \
+                           "it, set format(#{text_format.inspect}) instead, or no format")
+        else
+          Deprecation.warn("the format #{format.inspect} that the file name names is deprecated when the streams read " \
+                           "the rows as #{text_format.inspect}, such as those of a spreadsheet, since v3.0 reads them as " \
+                           "#{text_format.inspect} whatever the file name, set format(#{text_format.inspect}) to read " \
+                           "them so in both versions")
+        end
+      end
+
+      # An encoding set with #encoding is deprecated when the rows and records of a spreadsheet are read, see
+      # `IOStreams::Stream#warn_cell_rows`, which are its cells rather than lines of text, since v3.0 raises ArgumentError
+      # for it then. Its lines still take it. Without it, a schema reads the text of the cells as UTF-8, see #utf8_text?,
+      # as v3.0 does.
+      def warn_cells_encoding
+        return if @encoding.nil?
+
+        Deprecation.warn("#encoding is deprecated when the rows and records of a spreadsheet are read, which are its " \
+                         "cells rather than lines of text, since v3.0 raises ArgumentError for it, so remove it, and " \
+                         "give its columns a schema, with which v2.2 reads the text of its cells as UTF-8; " \
+                         "each(:line) still takes it")
+      end
+
+      # Returns [Array(Array<Symbol>, String, Hash|nil)|nil] the methods that the stream that the application's block
+      # receives in v3.0 answers, its name for a deprecation warning, such as "the :gz stream", and what replaces each
+      # method that v3.0 removes, when the stream says, see `IOStreams::Reader.v3_stream_advice`, when the stream that it
+      # receives in v2.2 answers others, otherwise nil. The stream closest to the application decides, with its options,
+      # see `IOStreams::Reader.v3_stream_methods`. Without any streams, the block receives the IO that they would read or
+      # write, which the supplied source describes, see `IOStreams::Stream#v3_source` and `IOStreams::Stream#v3_target`.
+      #
+      # Parameters:
+      #   type: [:reader|:writer]
+      #   source: [Array(Array<Symbol>, String)|nil]
+      #     The methods and the name of the IO that the streams read or write in v3.0, when it differs from the one in
+      #     v2.2, otherwise nil.
+      #
+      # Yields, only when the stream closest to the application asks and is the only stream, to ask whether the streams
+      # read a regular local file in v3.0. The block answers true or false.
+      #
+      # Asked before the streams are opened, so it raises nothing, not even for a stream without a class of the type, which
+      # raises as before once it is opened.
+      def v3_stream(type, source)
+        streams       = pipeline
+        name, options = streams.first
+        return source if name.nil?
+
+        klass = IOStreams.extensions[name]&.public_send(:"#{type}_class")
+        return unless klass.respond_to?(:v3_stream_methods)
+
+        methods = klass.v3_stream_methods(options) { streams.size == 1 && yield }
+        return unless methods
+
+        [methods, "the #{name.inspect} stream", (klass.v3_stream_advice if klass.respond_to?(:v3_stream_advice))]
+      end
+
+      # Returns [Symbol|nil] the format that the rows and records of this file are read and written in, when IOStreams
+      # v3.0 reads and writes them in its `:text` format instead, as the text of each line: when no format was set, so
+      # that it is taken from a file name whose format extension is `.text`, see `IOStreams::Tabular.text_file_format`,
+      # unless a stream reads the lines in a format of its own, such as the CSV of a spreadsheet, which v3.0 reads them
+      # in, whatever format the file name names. Returns nil otherwise.
+      def text_file_format
+        return if format_set? || file_name.nil? || text_format
+
+        Tabular.text_file_format(file_name)
+      end
+
+      # Returns [Symbol|nil] the tabular format of the data that a copy without a mode reads from these streams, or
+      # writes to them, when IOStreams v3.0 converts the rows of such a copy between it and another format, see
+      # `IOStreams::Stream#warn_copy_format`: the format of the text that the streams read, see #text_format, such as
+      # `:csv` for a spreadsheet, otherwise #format. Returns nil when v3.0 copies the data as it is: when the format is
+      # not known, such as for an IO without a file name or a `.txt` file, when the data is read and written as it is
+      # stored, see #raw, for a file that v3.0 reads in its `:text` format, see #text_file_format, and for a format whose
+      # rows are Ruby objects rather than lines of text, such as `:array` and `:hash`, see `IOStreams::Tabular.text_rows?`.
+      def copy_format
+        return if raw? || text_file_format
+
+        format = text_format || self.format
+        format if format && Tabular.text_rows?(format)
+      end
+
+      private
+
+      # Reports a deprecation warning for supplying `:none`, see #raw, or for setting the encode stream, see #encoding,
+      # which names the method that the application called.
+      def warn_deprecated_stream(method, stream)
+        case stream
+        when :none
+          Deprecation.warn("#{method}(:none) is deprecated, use #raw to read or write the data as it is stored, " \
+                           "or #file_name to read a file that is not named for its format")
+        when :encode
+          # Like any other stream set with #stream, stream(:encode, ...) stops the streams being taken from the file
+          # name, which #encoding keeps.
+          if method == "stream"
+            Deprecation.warn("stream(:encode, ...) is deprecated, use #encoding instead, which keeps the streams that " \
+                             "the file name implies, #raw to read or write the data as it is stored, or #file_name to " \
+                             "read a file that is not named for its format")
+          else
+            Deprecation.warn("#{method}(:encode, ...) is deprecated, use #encoding instead")
+          end
+        end
+      end
+
+      # Reports a deprecation warning for each option of the stream that IOStreams 3.0 raises ArgumentError for when it is
+      # set with #option, #stream or #option_or_stream, whether or not the file name includes the stream, so that it is
+      # reported wherever the code runs, rather than only where a file name includes the stream: one that the reader or
+      # the writer of the stream replaces, with the option that replaces it, see
+      # `IOStreams::Deprecation::OptionNames#replaced_option_names`, and one that neither of them takes in IOStreams 3.0,
+      # such as a misspelled one, see #v3_option_names. An option of the other direction is not reported, since v3.0
+      # accepts it, and ignores it, nor are the options of the encode stream, which is deprecated itself, see
+      # #warn_deprecated_stream, or of `:none`, which takes none.
+      def warn_deprecated_options(stream, options)
+        return if options.empty? || %i[encode none].include?(stream)
+
+        classes  = v3_stream_classes(stream)
+        replaced = classes.each_with_object({}) do |klass, names|
+          names.merge!(klass.replaced_option_names) if klass.respond_to?(:replaced_option_names)
+        end.slice(*options.keys)
+        replaced.each_pair { |name, replacement| Deprecation.warn("#{name}: is deprecated, use #{replacement}: instead") }
+
+        known = v3_option_names(classes)
+        names = known ? options.keys - replaced.keys - known : []
+        return if names.empty?
+
+        words = Deprecation::Words.new(names)
+        Deprecation.warn("#{words.keywords} #{words.are} deprecated for a #{stream.inspect} stream, since neither its " \
+                         "reader nor its writer takes #{words.them}, so correct or remove #{words.them}")
+      end
+
+      # Returns [Array<Class|Module>] the classes that read and write the stream in IOStreams 3.0, as far as they are
+      # known: the reader and the writer registered for it, and, in place of a writer that it does not have, the stand-in
+      # for the one that IOStreams 3.0 adds, when its reader names one, such as for `.xlsx`, see
+      # `IOStreams::Xlsx::Reader.v3_writer`. None when the stream is not registered.
+      def v3_stream_classes(stream)
+        extension = IOStreams.extensions[stream]
+        return [] unless extension
+
+        reader   = extension.reader_class
+        writer   = extension.writer_class
+        writer ||= reader.v3_writer if reader.respond_to?(:v3_writer)
+        [reader, writer].compact
+      end
+
+      # Returns [Array<Symbol>|nil] the options that IOStreams 3.0 accepts when they are set for a stream of the supplied
+      # classes, see #v3_stream_classes: those that its reader or its writer takes, or nil when they are not known, since
+      # a class does not declare them, as one that an application registers need not.
+      def v3_option_names(classes)
+        names = classes.map { |klass| v3_class_option_names(klass) }
+        names.flatten.uniq unless names.empty? || names.include?(nil)
+      end
+
+      # Returns [Array<Symbol>|nil] the options that the class takes in IOStreams 3.0, see
+      # `IOStreams::Deprecation::OptionNames#known_option_names`, or those that it declares when it does not answer them,
+      # as a class that an application registers need not, or nil when it does neither.
+      def v3_class_option_names(klass)
+        return klass.known_option_names if klass.respond_to?(:known_option_names)
+
+        klass.option_names if klass.respond_to?(:option_names)
+      end
+
+      # Reports a deprecation warning, when the streams are opened, for those that are deprecated, or whose results
+      # change in IOStreams v3.0.
+      def warn_deprecated_streams
+        warn_encode_extension
+        warn_temp_file_streams
+        warn_extension_options
+      end
+
+      # A file name ending in `.encode` is deprecated, since file names do not name the encode stream, see #encoding.
+      # Once the encode stream is set, with #encoding or `option(:encode, ...)`, the file name adds nothing to it, so it
+      # is only reported when the file name is what applies the encode stream.
+      def warn_encode_extension
+        return if streams || @encoding || options&.key?(:encode)
+        return if file_name.nil? || !parse_extensions.include?(:encode)
+
+        Deprecation.warn("a file name ending in .encode is deprecated, since file names do not name the encode " \
+                         "stream, use #encoding instead")
+      end
+
+      # The path of `IOStreams.temp_file` reads and writes its data as it is stored, see #no_streams, while IOStreams v3.0
+      # applies the streams that its file name implies, so reading or writing it is deprecated while it has no streams of
+      # its own, and its file name implies some, other than `.encode`, which v3.0 no longer applies, see #raw, which reads
+      # and writes the data as it is stored on both.
+      def warn_temp_file_streams
+        return unless @temp_file && streams.empty? && file_name
+        return if (parse_extensions - [:encode]).empty?
+
+        Deprecation.warn("reading or writing the path of IOStreams.temp_file is deprecated when its extension names " \
+                         "streams, such as .gz, since v3.0 applies them, where v2.2 reads and writes the data as it is " \
+                         "stored: call #raw on the path to read and write the data as it is stored")
+      end
+
+      # The options set for another extension of the format of an extension in the file name, such as
+      # `option(:pgp, ...)` for a `.gpg` file, are ignored, while IOStreams v3.0 applies the options of a format to each of
+      # its extensions, and then those set for the extension in the file name, which take precedence. So they are
+      # deprecated unless those of the extension itself set each of them too, with which both apply the same options.
+      def warn_extension_options
+        return if streams || options.nil? || file_name.nil?
+
+        parse_extensions.each do |stream|
+          own = options[stream] || {}
+          options.each_pair do |name, opts|
+            next if name == stream || (opts.keys - own.keys).empty? || !same_format?(name, stream)
+
+            Deprecation.warn("option(:#{name}, ...) is deprecated for a file name with the extension .#{stream}, which " \
+                             "v2.2 does not apply it to, since v3.0 applies the options of a format to each of its " \
+                             "extensions: set them with option(:#{stream}, ...)")
+          end
+        end
+      end
+
+      # Returns [true|false] whether the extensions are of the same format, whose reader and writer they share, such as
+      # `.pgp` and `.gpg`, or `.gz` and `.gzip`.
+      def same_format?(extension, other)
+        registered = IOStreams.extensions[extension]
+        other      = IOStreams.extensions[other]
+        return false if registered.nil? || other.nil?
+
+        registered.reader_class == other.reader_class && registered.writer_class == other.writer_class
+      end
+    end
+  end
+end

data/lib/io_streams/builder.rb

@@ -1,86 +1,192 @@
+require "io_streams/builder/deprecations"
+
 module IOStreams
   # Build the streams that need to be applied to a path during reading or writing.
   class Builder
+    include Deprecations
+
     attr_accessor :file_name, :format_options
     attr_reader :streams, :options
 
+    # Returns [Hash|String|IOStreams::Stream|nil] the schema of the rows and records as it was set, see #schema=.
+    attr_reader :schema
+
     def initialize(file_name = nil)
       @file_name     = file_name
       @streams       = nil
       @options       = nil
-      @format        = nil
+      @named_format  = nil
+      @set_format    = nil
       @format_option = nil
+      @encoding      = nil
+      @raw           = false
+      @temp_file     = false
+      @schema        = nil
+      @schema_source = nil
+    end
+
+    # A copy has its own streams, options and encoding, so that changing them does not change the original. It shares
+    # the schema, which #schema= replaces rather than changes, so that the copies read its file once, see
+    # `IOStreams::Schema::Source`.
+    def initialize_copy(source)
+      super
+      @streams  = @streams&.transform_values(&:dup)
+      @options  = @options&.transform_values(&:dup)
+      @encoding = @encoding&.dup
+    end
+
+    # Sets the schema of the rows and records, see `IOStreams::Stream#schema`: a Hash, which is checked now, or the path
+    # or url of a JSON file that holds one, which is read the first time that a reader or writer needs it, see
+    # `IOStreams::Schema::Source`, or nil to remove it.
+    #
+    # A copy of a Hash or String is held, which is frozen, so that the caller changing the object that it supplied
+    # changes neither #schema nor the schema that is read, and a copy of a path, so that changing its path does not
+    # change the schema.
+    #
+    # Raises ArgumentError when the schema is not a Hash, a String or a path, or is a Hash that is not a valid schema.
+    def schema=(schema)
+      schema         = schema.is_a?(IOStreams::Stream) ? schema.dup : Utils.frozen_copy(schema)
+      @schema_source = schema.nil? ? nil : IOStreams::Schema::Source.new(schema)
+      @schema        = schema
+    end
+
+    # Returns [IOStreams::Schema|nil] the schema of the rows and records, reading its file the first time, see #schema=,
+    # or nil when none is set.
+    def tabular_schema
+      @schema_source&.schema
     end
 
     # Supply an option that is only applied once the file name extensions have been parsed.
     # Note:
     # - Cannot set both `stream` and `option`
+    #
+    # Setting the encode stream with `option(:encode, ...)` is deprecated, see #encoding, and reports a deprecation
+    # warning, see `IOStreams::Deprecation`.
     def option(stream, **options)
       stream = stream.to_sym unless stream.is_a?(Symbol)
-      raise(ArgumentError, "Invalid stream: #{stream.inspect}") unless IOStreams.extensions.include?(stream)
-      raise(ArgumentError, "Cannot call both #option and #stream on the same streams instance}") if @streams
-      raise(ArgumentError, "Cannot call #option unless the `file_name` was already set}") unless file_name
-
-      @options ||= {}
-      if (opts = @options[stream])
-        opts.merge!(options)
-      else
-        @options[stream] = options.dup
-      end
+      raise_if_raw!("#option")
+      add_option(stream, options)
+      warn_deprecated_stream("option", stream)
+      warn_deprecated_options(stream, options)
       self
     end
 
+    # Setting the encode stream with `stream(:encode, ...)` is deprecated, see #encoding. Like any other stream set
+    # with `#stream`, it still stops the streams being taken from the file name, which #encoding keeps.
+    #
+    # Supplying `:none` is deprecated, see #raw. Since it does what #raw does, it can still be supplied after #raw.
+    #
+    # Each reports a deprecation warning, see `IOStreams::Deprecation`.
     def stream(stream, **options)
       stream = stream.to_sym unless stream.is_a?(Symbol)
-      raise(ArgumentError, "Cannot call both #option and #stream on the same streams instance}") if @options
+      raise_if_raw!("#stream") unless stream == :none
+      add_stream(stream, options)
+      warn_deprecated_stream("stream", stream)
+      warn_deprecated_options(stream, options)
+      self
+    end
 
-      # To prevent any streams from being applied supply a stream named `:none`
-      if stream == :none
-        @streams = {}
-        return self
+    # Sets the encoding of the text that the application reads or writes, and the other options of the encode
+    # stream, see `IOStreams::Encode`, merging them with those already set.
+    #
+    # Unlike `#option`, it can be combined with `#stream`, and needs no file name. Unlike `#stream`, it does not stop
+    # the streams being taken from the file name. The encode stream is applied closest to the application, after
+    # every other stream when reading, with the options set by `#option` or `#stream` for `:encode`, if any, and
+    # these on top of them.
+    #
+    # Raises ArgumentError when neither an encoding nor any options are supplied, when the encoding is supplied both
+    # as an argument and as the `encoding:` option, or for an option that the encode stream does not take, or a value
+    # that it does not accept, see `IOStreams::Encode.check`. They are checked when they are set, since a writer that
+    # raised for them would have replaced its file. The options set with `#option` or `#stream` for `:encode` are
+    # deprecated, and are still only checked when the stream is opened, as before.
+    def encoding(encoding = nil, **options)
+      raise_if_raw!("#encoding")
+      if encoding
+        raise(ArgumentError, "Supply the encoding as an argument or as `encoding:`, not both") if options.key?(:encoding)
+
+        options = {encoding: encoding, **options}
       end
-      raise(ArgumentError, "Invalid stream: #{stream.inspect}") unless IOStreams.extensions.include?(stream)
+      raise(ArgumentError, "Supply the encoding, or options for the encode stream") if options.empty?
 
-      @streams ||= {}
-      if (opts = @streams[stream])
-        opts.merge!(options)
-      else
-        @streams[stream] = options.dup
-      end
+      merged = (@encoding || {}).merge(options)
+      Encode.check(**merged)
+      @encoding = merged
       self
     end
 
-    def option_or_stream(stream, **)
-      if streams
-        stream(stream, **)
-      elsif file_name
-        option(stream, **)
-      else
-        stream(stream, **)
-      end
+    # Reads and writes the data as it is stored: applies no streams, neither those that the file name implies nor any
+    # already set with #stream or #option, and no encoding set with #encoding. For example, to download a zip file
+    # without unzipping it, or to write data that is already compressed.
+    #
+    # Since the data is as stored, setting a stream, option or encoding afterwards raises ArgumentError.
+    def raw
+      no_streams
+      @options = nil
+      @raw     = true
+      self
+    end
+
+    # Returns [true|false] whether the data is read and written as it is stored, see #raw.
+    def raw?
+      @raw
+    end
+
+    # Returns [true|false] whether the text that the streams yield is taken as UTF-8: the text of a file with a
+    # schema, see #schema=, unless the application chose the encoding of its text, with an encode stream, whether set
+    # with #encoding, #option, #stream, or by a file name ending in `.encode`, or chose none with #raw, which reads the
+    # data as it is stored. Without a schema, the text is read as it always was.
+    def utf8_text?
+      !@schema.nil? && !raw? && !pipeline.key?(:encode)
+    end
+
+    # Applies no streams, including an encoding set with #encoding, as `stream(:none)` does, for IOStreams itself.
+    #
+    # `temp_file: true` for the path of `IOStreams.temp_file`, which reads and writes its data as it is stored, while
+    # IOStreams v3.0 applies the streams that its file name implies, so that reading or writing it reports a deprecation
+    # warning while they would apply, see #warn_temp_file_streams.
+    def no_streams(temp_file: false)
+      @streams   = {}
+      @encoding  = nil
+      @temp_file = temp_file
+      self
+    end
+
+    # Sets the options of a stream as #option does, unless streams were already set with #stream, or no file name is
+    # set, when it adds the stream as #stream does.
+    #
+    # Setting the encode stream with `option_or_stream(:encode, ...)` is deprecated, see #encoding, and reports a
+    # deprecation warning, see `IOStreams::Deprecation`.
+    def option_or_stream(stream, **options)
+      stream = stream.to_sym unless stream.is_a?(Symbol)
+      raise_if_raw!("#option_or_stream") unless stream == :none
+      streams || file_name.nil? ? add_stream(stream, options) : add_option(stream, options)
+      warn_deprecated_stream("option_or_stream", stream)
+      warn_deprecated_options(stream, options)
+      self
     end
 
     # Return the options set for either a stream or option.
     def setting(stream)
+      return encode_setting if stream == :encode && @encoding
       return streams[stream] if streams
 
       options[stream] if options
     end
 
     def reader(io_stream, &)
+      warn_deprecated_streams
       execute(:reader, pipeline, io_stream, &)
     end
 
     def writer(io_stream, &)
+      warn_deprecated_streams
       execute(:writer, pipeline, io_stream, &)
     end
 
     # Returns [Hash<Symbol:Hash>] the pipeline of streams
     # with their options that will be applied when the reader or writer is invoked.
     def pipeline
-      return streams.dup.freeze if streams
-
-      build_pipeline.freeze
+      with_encoding(streams ? streams.dup : build_pipeline).freeze
     end
 
     # Removes the named stream from the current pipeline.
@@ -88,21 +194,43 @@ module IOStreams
     # Note: Any options must be set _before_ calling this method.
     def remove_from_pipeline(stream_name)
       @streams ||= build_pipeline
+      @encoding  = nil if stream_name.to_sym == :encode
+      # The streams are now those that the application chose, see #warn_temp_file_streams.
+      @temp_file = false
       @streams.delete(stream_name.to_sym)
     end
 
     # Returns the tabular format if set, otherwise tries to autodetect the format if the file_name has been set
     # Returns [nil] if no format is set, or if it cannot be determined from the file_name
+    #
+    # The format that the file name names is kept once it is found, until a format is set, see #format=.
     def format
-      @format ||= file_name ? Tabular.format_from_file_name(file_name) : nil
+      @set_format || (@named_format ||= file_name ? Tabular.format_from_file_name(file_name) : nil)
     end
 
+    # Sets the tabular format, or nil to detect it from the file name again, see #format.
     def format=(format)
       unless format.nil? || IOStreams::Tabular.registered_formats.include?(format)
         raise(ArgumentError, "Invalid format: #{format.inspect}")
       end
 
-      @format = format
+      @set_format   = format
+      @named_format = nil
+    end
+
+    # Returns [true|false] whether a format was set, see #format=, rather than taken from the file name, see #format.
+    def format_set?
+      !@set_format.nil?
+    end
+
+    # Returns [Symbol|nil] the tabular format of the text that the stream closest to the application reads, when that
+    # stream decides it, such as `:csv` for a spreadsheet, whose rows it reads as CSV, see
+    # `IOStreams::Xlsx::Reader.text_format`, otherwise nil, for a stream whose data is the text, such as gzip. The encode
+    # stream converts that text, so it is the stream after it.
+    def text_format
+      stream = pipeline.each_key.find { |name| name != :encode }
+      klass  = stream && IOStreams.extensions[stream]&.reader_class
+      klass.text_format if klass.respond_to?(:text_format)
     end
 
     # Returns [String] the quote character within which field delimiters and newlines may be
@@ -117,8 +245,68 @@ module IOStreams
       format && IOStreams::Tabular.parser_class(format).quote_character
     end
 
+    # Returns [Hash<Symbol, Array<Symbol>>] the settings of this stream that apply to what it writes, other than the
+    # options of each call: `streams:` the names of the streams of its pipeline, see #pipeline, which #stream, #option,
+    # #encoding and the file name set, and `tabular:` the names of those of its rows and records that were set: `:format`,
+    # when it was set, see #format=, rather than taken from the file name, and `:schema`, see #schema=.
+    def writer_settings
+      tabular = []
+      tabular << :format if format_set?
+      tabular << :schema unless schema.nil?
+      {streams: pipeline.keys, tabular: tabular}
+    end
+
     private
 
+    # Sets the options of a stream that is applied once the file name extensions have been parsed, see #option.
+    def add_option(stream, options)
+      raise(ArgumentError, "Invalid stream: #{stream.inspect}") unless IOStreams.extensions.include?(stream)
+      raise(ArgumentError, "Cannot call both #option and #stream on the same streams instance}") if @streams
+      raise(ArgumentError, "Cannot call #option unless the `file_name` was already set}") unless file_name
+
+      @options ||= {}
+      if (opts = @options[stream])
+        opts.merge!(options)
+      else
+        @options[stream] = options.dup
+      end
+    end
+
+    # Adds a stream, in place of the streams that the file name implies, see #stream.
+    def add_stream(stream, options)
+      raise(ArgumentError, "Cannot call both #option and #stream on the same streams instance}") if @options
+      # `:none` applies no streams, including an encoding set with #encoding. It is the deprecated form of #raw.
+      return no_streams if stream == :none
+      raise(ArgumentError, "Invalid stream: #{stream.inspect}") unless IOStreams.extensions.include?(stream)
+
+      @streams ||= {}
+      if (opts = @streams[stream])
+        opts.merge!(options)
+      else
+        @streams[stream] = options.dup
+      end
+    end
+
+    def raise_if_raw!(method_name)
+      return unless @raw
+
+      raise(ArgumentError, "Cannot call #{method_name} after #raw, which reads and writes the data as it is stored")
+    end
+
+    # Returns [Hash] the options of the encode stream set with #option or #stream, if any, and those of #encoding.
+    def encode_setting
+      setting = streams ? streams[:encode] : options&.[](:encode)
+      (setting || {}).merge(@encoding)
+    end
+
+    # Returns [Hash<Symbol:Hash>] the pipeline, with the encode stream first, closest to the application, when an
+    # encoding was set with #encoding.
+    def with_encoding(pipeline)
+      return pipeline unless @encoding
+
+      {encode: encode_setting}.merge(pipeline.except(:encode))
+    end
+
     def build_pipeline
       return {} unless file_name
 
@@ -139,7 +327,7 @@ module IOStreams
 
     # Returns the streams for the supplied file_name
     def parse_extensions
-      parts      = ::File.basename(file_name).split(".")
+      parts      = Utils::PathName.basename(file_name).split(".")
       extensions = []
       while (extension = parts.pop)
         sym = extension.downcase.to_sym
@@ -169,9 +357,38 @@ module IOStreams
     end
 
     def open_stream(type, stream, io_stream, opts, &)
-      klass = class_for_stream(type, stream)
+      klass = stream_class(type, stream)
       validate_options(type, stream, klass, opts)
-      klass.open(io_stream, **opts, &)
+      klass.open(io_stream, **taken_options(type, stream, klass, opts), &)
+    end
+
+    # Returns [Class] the class that reads or writes the stream: the class registered for it, or, to read a file with a
+    # schema, see #schema=, the class that the registered reader answers for it, when it reads a file with a schema
+    # differently, such as the reader of a spreadsheet, see `IOStreams::Xlsx::Reader.schema_reader`.
+    def stream_class(type, stream)
+      klass = class_for_stream(type, stream)
+      return klass if type != :reader || @schema.nil? || !klass.respond_to?(:schema_reader)
+
+      klass.schema_reader
+    end
+
+    # Returns [Hash] the options of the stream that the class is opened with: all of them, unless the class takes any
+    # option, since it does not declare them, see #validate_options, while it answers those that it takes in IOStreams
+    # 3.0, as `IOStreams::Bzip2::Reader` does until v3.0, see #v3_class_option_names. It is then opened with those
+    # alone, and a warning is logged for each of the others, which it would ignore, see
+    # `IOStreams::Utils.warn_unknown_options`, naming the stream as it was set: one that the class of the other
+    # direction takes, which v3.0 accepts, and ignores, or one that neither takes, which v3.0 raises ArgumentError for.
+    def taken_options(type, stream, klass, opts)
+      known = v3_class_option_names(klass) if option_names(klass).nil?
+      return opts if known.nil?
+
+      unknown = opts.except(*known)
+      return opts if unknown.empty?
+
+      other       = IOStreams.extensions[stream].public_send(type == :reader ? :writer_class : :reader_class)
+      other_names = (v3_class_option_names(other) if other) || []
+      Utils.warn_unknown_options(unknown, stream, type, known, other_names)
+      opts.slice(*known)
     end
 
     # Options are strict: an option the stream does not accept raises instead of being ignored.