iostreams 2.1.0 → 2.2.0

data/lib/io_streams/record/reader.rb

@@ -57,94 +57,85 @@ module IOStreams
       #     false:
       #       Raises Tabular::InvalidHeader when a column is supplied that is not in the whitelist.
       #
+      #   cleanse_header: [true|false]
+      #     Whether to cleanse the header row read, see `IOStreams::Tabular::Header#cleanse!`, which the tabular that it
+      #     creates does, see `IOStreams::Tabular.new`.
+      #     With a schema it raises ArgumentError, even when nil, since the fields of the schema name the keys of the
+      #     records instead.
+      #     Default: cleanses it.
+      #
+      #   tabular: [IOStreams::Tabular]
+      #     The tabular that parses each line, such as one with a schema, see `IOStreams::Stream#schema`, in place of the
+      #     other options, which create it.
+      #
+      #   report_repeated_key: [true|false]
+      #     Whether to report a deprecation warning, before the first record, when two columns of the header row are the
+      #     same key, see #warn_repeated_key, which `IOStreams::Stream#each` and `#reader` ask for, rather than another
+      #     gem that creates a reader, which its users cannot change.
+      #     Default: false
+      #
       # Note:
       # * `allowed_columns`, `required_columns` and `skip_unknown` only apply to every input, including JSON records,
       #   supplied `columns` and `cleanse_header: false`, when `IOStreams.enforce_column_restrictions?` is true.
-      def initialize(line_reader, cleanse_header: true, original_file_name: nil, **args)
+      def initialize(line_reader, original_file_name: nil, tabular: nil, report_repeated_key: false, **args)
         unless line_reader.respond_to?(:each)
           raise(ArgumentError, "Stream must be a IOStreams::Line::Reader or implement #each")
         end
 
-        @tabular        = IOStreams::Tabular.new(file_name: original_file_name, **args)
-        @line_reader    = line_reader
-        @cleanse_header = cleanse_header
-        @warned         = false
+        if tabular && (original_file_name || !args.empty?)
+          raise(ArgumentError, "Supply either tabular: or the options that create it, not both")
+        end
 
-        # Supplied columns take the place of a header row, so apply the allowed and required columns to them.
-        restrict_columns if restricted? && !@tabular.header?
-      end
+        @tabular             = tabular || IOStreams::Tabular.new(file_name: original_file_name, **args)
+        @line_reader         = line_reader
+        @report_repeated_key = report_repeated_key
 
-      def each
-        @line_reader.each do |line|
-          if @tabular.header?
-            @tabular.parse_header(line)
-            if @cleanse_header
-              cleanse_columns
-            elsif restricted?
-              restrict_columns
-            end
-          else
-            yield restrict(@tabular.record_parse(line))
-          end
-        end
+        # Supplied columns take the place of a header row, so apply the allowed and required columns to them.
+        @tabular.restrict_columns
       end
 
-      private
+      # Yields each record, after the header row, which names their keys, see `IOStreams::Tabular#read_record_line`.
+      def each(&block)
+        return each_reporting(&block) if @report_repeated_key
 
-      def restricted?
-        @tabular.header.restricted?
+        @line_reader.each { |line| @tabular.read_record_line(line, &block) }
       end
 
-      def cleanse_columns
-        @tabular.header.cleanse!(rename: @cleanse_header)
+      # Writes each record to the writer, see `IOStreams::Record::Writer`, as a copy with a schema does, see
+      # `IOStreams::Stream#copy_from`. A blank line, or a JSON line of null, which #each yields as nil, is not a record,
+      # so it is not written.
+      #
+      # Returns the result of #each.
+      def copy_to(writer)
+        each { |record| writer << record unless record.nil? }
       end
 
-      # Apply the allowed and required columns to supplied columns, or to a header row read with
-      # `cleanse_header: false`. Unless `IOStreams.enforce_column_restrictions?`, only warn when they would
-      # change the columns.
-      def restrict_columns
-        return cleanse_columns if IOStreams.enforce_column_restrictions?
-        return if @warned
+      private
 
-        header  = @tabular.header
-        columns = header.columns
-        changed = changed_by_restriction? do
-          copy = IOStreams::Tabular::Header.new(
-            columns:          columns,
-            allowed_columns:  header.allowed_columns,
-            required_columns: header.required_columns,
-            skip_unknown:     header.skip_unknown
-          )
-          copy.cleanse!(rename: @cleanse_header)
-          copy.columns != columns
+      # Yields each record, as #each does, after reporting a deprecation warning before the first one when two columns
+      # of the header row are the same key, see #warn_repeated_key.
+      def each_reporting
+        @line_reader.each do |line|
+          @tabular.read_record_line(line) do |record|
+            warn_repeated_key if @report_repeated_key
+            yield record
+          end
         end
-        warn_restriction if changed
-      end
-
-      # Formats such as JSON have no header row, so apply the allowed and required columns to each record's keys.
-      # Unless `IOStreams.enforce_column_restrictions?`, only warn when they would change the record.
-      def restrict(record)
-        return record unless record.is_a?(Hash) && restricted? && @tabular.header.columns.nil?
-        return @tabular.header.restrict_hash(record, rename: @cleanse_header) if IOStreams.enforce_column_restrictions?
-        return record if @warned
-
-        warn_restriction if changed_by_restriction? { @tabular.header.restrict_hash(record, rename: @cleanse_header) != record }
-        record
-      end
-
-      def changed_by_restriction?
-        yield
-      rescue IOStreams::Errors::InvalidHeader
-        true
       end
 
-      # Warn once per reader, since the same columns usually apply to every record.
-      def warn_restriction
-        @warned = true
-        IOStreams.logger&.warn(
-          "allowed_columns and required_columns are not applied to this input, but would change the records read. " \
-          "In v3.0 they will apply to every input. Set `IOStreams.enforce_column_restrictions = true` to apply them now."
-        )
+      # Reports a deprecation warning, once, when two columns of the header row are the same key, see
+      # `IOStreams::Tabular#repeated_key`, such as a header row of `a,a,b`, or of `A` and `a`, which are cleansed to the
+      # same key, since each record holds the value of only the last of them, while IOStreams v3.0 raises
+      # `IOStreams::Errors::InvalidHeader` for them, rather than lose the others.
+      def warn_repeated_key
+        @report_repeated_key = false
+        key = @tabular.repeated_key
+        return if key.nil?
+
+        Deprecation.warn("records read from a header row whose columns are the same key, #{key.inspect}, are " \
+                         "deprecated, since each record holds the value of only the last of them, and v3.0 raises " \
+                         "IOStreams::Errors::InvalidHeader for them: rename the columns, or read the rows with " \
+                         "each(:array), which holds every column")
       end
     end
   end

data/lib/io_streams/record/writer.rb

@@ -58,25 +58,32 @@ module IOStreams
       #       #as_hash will skip these additional columns entirely as if they were not in the file at all.
       #     false:
       #       Raises Tabular::InvalidHeader when a column is supplied that is not in the whitelist.
-      def initialize(line_writer, columns: nil, original_file_name: nil, **args)
+      #
+      #   tabular: [IOStreams::Tabular]
+      #     The tabular that renders each record, such as one with a schema, see `IOStreams::Stream#schema`, in place of
+      #     the other options, which create it.
+      def initialize(line_writer, columns: nil, original_file_name: nil, tabular: nil, **args)
         raise(ArgumentError, "Stream must be a IOStreams::Line::Writer or implement #<<") unless line_writer.respond_to?(:<<)
 
-        @tabular     = IOStreams::Tabular.new(columns: columns, file_name: original_file_name, **args)
+        if tabular && (columns || original_file_name || !args.empty?)
+          raise(ArgumentError, "Supply either tabular: or the options that create it, not both")
+        end
+
+        IOStreams::Tabular.check_write_options(args)
+        @tabular     = tabular || IOStreams::Tabular.new(columns: columns, file_name: original_file_name, **args)
         @line_writer = line_writer
 
-        # Render header line when `columns` is supplied.
-        @line_writer << @tabular.render_header if columns && @tabular.requires_header?
+        # Render header line when `columns` is supplied, or with a schema the names of its fields, see
+        # `IOStreams::Tabular#start_records`.
+        @tabular.start_records { |line| @line_writer << line }
       end
 
+      # Writes the record, after the header line that the keys of the first record give, when neither the columns
+      # supplied nor a schema give it, see `IOStreams::Tabular#render_record`.
       def <<(hash)
         raise(ArgumentError, "#<< only accepts a Hash argument") unless hash.is_a?(Hash)
 
-        if @tabular.header?
-          # Extract header from the keys from the first row when not supplied above.
-          @tabular.header.columns = hash.keys
-          @line_writer << @tabular.render_header
-        end
-        @line_writer << @tabular.render(hash)
+        @tabular.render_record(hash) { |line| @line_writer << line }
       end
     end
   end

data/lib/io_streams/row/header_row.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module IOStreams
+  module Row
+    # The header row that `IOStreams::Stream#each(:array)` yields before the rows of a file, which names the column of
+    # each value of the rows after it. It is an Array, as every other row is, whose class says that it is the header
+    # row, so that a writer of rows takes it as the header row of the rows written after it, rather than as a row of
+    # values, see `IOStreams::Row::Writer#<<`, and so that code that reads the rows can tell it apart:
+    #
+    #   path.each(:array) do |row|
+    #     next if row.is_a?(IOStreams::Row::HeaderRow)
+    #
+    #     process(row)
+    #   end
+    #
+    # It is equal to an Array of the same columns, and the methods of an Array that return a new Array, such as `map`,
+    # return an Array rather than a header row, so that a row made from it is a row of values.
+    class HeaderRow < ::Array
+    end
+  end
+end

data/lib/io_streams/row/reader.rb

@@ -28,27 +28,64 @@ module IOStreams
       #   format: [Symbol]
       #     :csv, :hash, :array, :json, :psv, :fixed
       #
-      #   For all other parameters, see Tabular::Header.new
-      def initialize(line_reader, cleanse_header: true, original_file_name: nil, **args)
+      #   cleanse_header: [true|false]
+      #     Whether to cleanse the header row read, see `IOStreams::Tabular::Header#cleanse!`, which the tabular that it
+      #     creates does, see `IOStreams::Tabular.new`.
+      #     With a schema it raises ArgumentError, even when nil, since the fields of the schema name the keys of the
+      #     records instead.
+      #     Default: cleanses it.
+      #
+      #   tabular: [IOStreams::Tabular]
+      #     The tabular that parses each line, such as one with a schema, see `IOStreams::Stream#schema`, in place of the
+      #     other options, which create it.
+      #
+      #   For all other parameters, see IOStreams::Tabular.new
+      def initialize(line_reader, original_file_name: nil, tabular: nil, **args)
         unless line_reader.respond_to?(:each)
           raise(ArgumentError, "Stream must be a IOStreams::Line::Reader or implement #each")
         end
 
-        @tabular        = IOStreams::Tabular.new(file_name: original_file_name, **args)
-        @line_reader    = line_reader
-        @cleanse_header = cleanse_header
+        if tabular && (original_file_name || !args.empty?)
+          raise(ArgumentError, "Supply either tabular: or the options that create it, not both")
+        end
+
+        @tabular     = tabular || IOStreams::Tabular.new(file_name: original_file_name, **args)
+        @line_reader = line_reader
       end
 
-      def each
-        @line_reader.each do |line|
-          if @tabular.header?
-            columns = @tabular.parse_header(line)
-            @tabular.cleanse_header! if @cleanse_header
-            yield columns
-          else
-            yield @tabular.row_parse(line)
-          end
-        end
+      # Returns [true|false] whether the first row that #each yields is a header row, which names the column of each
+      # value of the rows after it, see `IOStreams::Tabular#rows_header?`: the header row of the file, or with a schema,
+      # the names of its fields, of a file without one, such as fixed width or JSON. False when the columns were
+      # supplied, which name the values of the rows instead. Asked before #each.
+      def header?
+        @tabular.rows_header?
+      end
+
+      # Returns [true|false] whether the rows that #each yields are the records of the file, Hashes rather than Arrays,
+      # see `IOStreams::Tabular#record_rows?`, such as those of JSON without a schema.
+      def record_rows?
+        @tabular.record_rows?
+      end
+
+      # Yields each row, an Array, after the header row of a file with one, which it yields first, see
+      # `IOStreams::Tabular#read_row`. With a schema, the header row is an `IOStreams::Row::HeaderRow` of the names of
+      # the fields, also for a file without a header row, such as fixed width or JSON.
+      def each(&block)
+        @line_reader.each { |line| @tabular.read_row(line, &block) }
+      end
+
+      # Writes each row to the writer, see `IOStreams::Row::Writer`, as a copy with a schema does, see
+      # `IOStreams::Stream#copy_from`, telling it the column of each value of the rows: the header row of the file, or
+      # for a file without one, the names of the fields of its schema, is an `IOStreams::Row::HeaderRow`, which the writer
+      # takes as the header row of the rows after it, see `IOStreams::Row::Writer#<<`, so that a target with a schema
+      # matches its columns to the fields, rather than write it as a row of values. Tabular decides which row is the
+      # header row, see `IOStreams::Tabular#start_copy` and `IOStreams::Tabular#copy_row`. A blank line, which is not a
+      # row, is not written.
+      #
+      # Returns the result of the #each of the line reader.
+      def copy_to(writer)
+        @tabular.start_copy { |columns| writer << columns }
+        @line_reader.each { |line| @tabular.copy_row(line) { |row| writer << row unless row.nil? } }
       end
     end
   end

data/lib/io_streams/row/writer.rb

@@ -35,28 +35,79 @@ module IOStreams
       #   format: [Symbol]
       #     :csv, :hash, :array, :json, :psv, :fixed
       #
+      #   tabular: [IOStreams::Tabular]
+      #     The tabular that renders each row, such as one with a schema, see `IOStreams::Stream#schema`, in place of the
+      #     other options, which create it.
+      #
+      #   report_repeated_key: [true|false]
+      #     Whether to report a deprecation warning when the header row of the rows written to a format whose rows are
+      #     records, such as JSON, has two columns of the same key, see #warn_repeated_key, which
+      #     `IOStreams::Stream#writer` asks for, rather than another gem that creates a writer, which its users cannot
+      #     change.
+      #     Default: false
+      #
       #   For all other parameters, see Tabular::Header.new
-      def initialize(line_writer, columns: nil, original_file_name: nil, **args)
+      def initialize(line_writer, columns: nil, original_file_name: nil, tabular: nil, report_repeated_key: false, **args)
         raise(ArgumentError, "Stream must be a IOStreams::Line::Writer or implement #<<") unless line_writer.respond_to?(:<<)
 
-        @tabular     = IOStreams::Tabular.new(columns: columns, file_name: original_file_name, **args)
-        @line_writer = line_writer
+        if tabular && (columns || original_file_name || !args.empty?)
+          raise(ArgumentError, "Supply either tabular: or the options that create it, not both")
+        end
+
+        IOStreams::Tabular.check_write_options(args)
+        @tabular             = tabular || IOStreams::Tabular.new(columns: columns, file_name: original_file_name, **args)
+        @line_writer         = line_writer
+        @report_repeated_key = report_repeated_key
 
-        # Render header line when `columns` is supplied.
-        line_writer << @tabular.render_header if columns && @tabular.requires_header?
+        # Render header line when `columns` is supplied, or with a schema the names of its fields, see
+        # `IOStreams::Tabular#start_rows`.
+        @tabular.start_rows { |line| @line_writer << line }
       end
 
-      # Supply a hash or an array to render
+      # Supply an array to render, otherwise it raises ArgumentError.
+      #
+      # Without a schema, the first row is the header row, unless the columns were supplied. With a schema, the header
+      # row of a file with one is the names of its fields, which is written before the rows, so every row written is
+      # the values of the fields, in order. A header row that `IOStreams::Stream#each(:array)` yields with a schema, an
+      # `IOStreams::Row::HeaderRow`, is written as the header row of the rows after it, see #write_header.
       def <<(array)
         raise(ArgumentError, "Must supply an Array") unless array.is_a?(Array)
+        return write_header(array) if array.is_a?(HeaderRow)
 
-        if @tabular.header?
-          # If header (columns) was not supplied as an argument, assume first line is the header.
-          @tabular.header.columns = array
-          @line_writer << @tabular.render_header
-        else
-          @line_writer << @tabular.render(array)
-        end
+        @tabular.render_row(array) { |line| @line_writer << line }
+      end
+
+      # Writes the header row of the rows after it, such as that of the file that is copied, see
+      # `IOStreams::Row::Reader#copy_to`, so that the value of each column of the rows after it is written to its
+      # column, or to its field with a schema, whose columns it matches to the fields, without a line. Without a schema,
+      # as the first row, see #<<, unless the format has no header row, such as JSON, and the columns are not known,
+      # when it gives the columns of the rows after it, or the columns were supplied, which name them instead, see
+      # `IOStreams::Tabular#render_header_row`.
+      #
+      # Returns self, so that calls can be chained.
+      def write_header(columns)
+        @tabular.render_header_row(columns) { |line| @line_writer << line }
+        warn_repeated_key if @report_repeated_key
+        self
+      end
+
+      private
+
+      # Reports a deprecation warning when two columns of the header row are the same key, see
+      # `IOStreams::Tabular#repeated_key`, such as a header row of `a,a,b`, and the format writes each row as a record,
+      # see `IOStreams::Tabular#record_rows?`, such as JSON, since each record holds the value of only the last of them,
+      # while IOStreams v3.0 raises `IOStreams::Errors::InvalidHeader` for them, rather than lose the others. A format
+      # whose rows are Arrays, such as CSV, writes every column.
+      def warn_repeated_key
+        return unless @tabular.record_rows?
+
+        key = @tabular.repeated_key
+        return if key.nil?
+
+        Deprecation.warn("rows written to a format whose rows are records, such as JSON, under a header row whose " \
+                         "columns are the same key, #{key.inspect}, are deprecated, since each record holds the value " \
+                         "of only the last of them, and v3.0 raises IOStreams::Errors::InvalidHeader for them: rename " \
+                         "the columns")
       end
     end
   end