iostreams 2.1.0 → 2.2.0

data/lib/io_streams/xlsx/reader.rb

@@ -7,6 +7,12 @@ module IOStreams
         []
       end
 
+      # Returns [Symbol] the tabular format of the text that a workbook is read as: CSV, one line for each row of its
+      # worksheet, see #file.
+      def self.text_format
+        :csv
+      end
+
       # Convert a xlsx, or xlsm file into CSV format.
       def self.file(file_name, &block)
         # Stream into a temp file as csv
@@ -16,6 +22,20 @@ module IOStreams
         end
       end
 
+      # Returns [Class] the class that reads a workbook for a file read with a schema, see
+      # `IOStreams::Builder#stream_class`, whose CSV text holds the text of each number cell as IOStreams 3.0 gives it,
+      # see `IOStreams::Xlsx::SchemaReader`, while this class keeps creek's text, as IOStreams 2.1 read it. A subclass,
+      # such as one that an application registers for `.xlsx`, reads a file with a schema itself.
+      def self.schema_reader
+        self == Reader ? SchemaReader : self
+      end
+
+      # Returns [Module] the stand-in for the writer of the files that this class reads, which IOStreams 3.0 adds, and
+      # IOStreams 2.2 does not have, which answers the options that it takes, see `IOStreams::Xlsx::V3Writer`.
+      def self.v3_writer
+        V3Writer
+      end
+
       def initialize(file_name)
         begin
           require "creek" unless defined?(Creek::Book)
@@ -31,6 +51,42 @@ module IOStreams
       def each
         @worksheet.rows.each { |row| yield row.values }
       end
+
+      private
+
+      # Converts each cell of the worksheet with the block, rather than with creek's `Creek::Sheet#convert`, when the
+      # block returns a value, which it calls with the text of the cell, its cell type, the index of its style, and
+      # `Creek::Sheet#converter_options`, which hold the first day of the workbook, and with creek's conversion when the
+      # block returns nil.
+      #
+      # Raises `IOStreams::Errors::Error` when the version of creek no longer has those methods, rather than let creek
+      # convert the cells itself.
+      def convert_cells(&block)
+        unless @worksheet.respond_to?(:convert, true) && @worksheet.respond_to?(:converter_options, true)
+          raise(IOStreams::Errors::Error, "creek #{Creek::VERSION} no longer has Creek::Sheet#convert and " \
+                                          "#converter_options, which IOStreams replaces to read the cells of a spreadsheet")
+        end
+
+        @worksheet.define_singleton_method(:convert) do |text, type, style_index|
+          value = block.call(text, type, style_index.to_i, converter_options)
+          value.nil? ? super(text, type, style_index) : value
+        end
+      end
+
+      # Returns [Array<Symbol|nil>] the class of the number format of each style of the workbook of the worksheet, as
+      # IOStreams 3.0 classifies it, see `IOStreams::Xlsx::Cells.number_formats`, rather than as creek does.
+      #
+      # Raises `IOStreams::Errors::Error` when the version of creek no longer has `Creek::Sheet#book` and
+      # `Creek::Styles#styles_xml`, which IOStreams reads the number formats of the workbook from.
+      def number_formats
+        unless @worksheet.respond_to?(:book) && defined?(Creek::Styles) && Creek::Styles.method_defined?(:styles_xml)
+          raise(IOStreams::Errors::Error, "creek #{Creek::VERSION} no longer has Creek::Sheet#book and " \
+                                          "Creek::Styles#styles_xml, which IOStreams reads the number formats of a " \
+                                          "spreadsheet from")
+        end
+
+        Cells.number_formats(Creek::Styles.new(@worksheet.book).styles_xml)
+      end
     end
   end
 end

data/lib/io_streams/xlsx/schema_reader.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module IOStreams
+  module Xlsx
+    # Reads a workbook into CSV text as `IOStreams::Xlsx::Reader` does, for a file read with a schema, see
+    # `IOStreams::Xlsx::Reader.schema_reader`, with the text of each number cell as IOStreams 3.0 gives it, so that a
+    # `string` field reads the same text in both, and a field of the type of the cell reads it:
+    #   a number              the number that the cell holds, to the 15 significant digits that Excel displays, without
+    #                         its number format, such as `2134` for the zip code that creek reads as the Float `2134.0`,
+    #                         `0.3` for `0.30000000000000004`, `0.125` for `12.5%`, and `12.5` for a format without
+    #                         decimals, see .displayed
+    #   a date                in ISO 8601, such as `2026-10-25`
+    #   a date and time       the time of its clock in UTC, in ISO 8601, such as `2026-10-25T09:30:00Z`, since Excel has
+    #                         no time zone, rather than in the time zone of the process
+    #   a time of day         the time of its clock, such as `09:30:00`
+    #
+    # A number cell is one of the type `n`, or without a type, as Excel writes it, whose number format is a date or a
+    # time as IOStreams 3.0 classifies it, see `IOStreams::Xlsx::Cells`, such as the custom format `yyyy-mm-dd` of a
+    # date, rather than as creek does, which takes it as a date and time. Every other cell keeps creek's text, such as a
+    # text cell, keeping `01234`. A file read without a schema keeps creek's text for every cell, as IOStreams 2.1 read
+    # it.
+    class SchemaReader < Reader
+      # The most significant digits that Excel displays of a number.
+      DISPLAYED_DIGITS = 15
+
+      # The whole numbers that a Float holds exactly are below this, so that one keeps every digit, such as a card
+      # number of 16 digits, rather than the 15 that Excel displays, see .displayed.
+      EXACT = 2**53
+
+      # Returns [String|Object] the text of the number of a cell, a Float, as IOStreams 3.0 gives it: its 15 most
+      # significant digits, which Excel displays, rounded half up from its exact value, in plain digits, without a
+      # decimal point for a whole number, such as "2134" for `2134.0`, "0.3" for `0.30000000000000004`, or
+      # "150000000000000000000" for `1.5e20`, or every digit of a whole number below 2**53, which a Float holds exactly,
+      # such as "4111111111111111". Any other value is returned as it is.
+      def self.displayed(value)
+        return value unless value.is_a?(Float) && value.finite?
+        return value.to_i.to_s if value.abs < EXACT && value == value.truncate
+
+        # The exact value of the Float, rounded half up to the digits that Excel displays, counted from the first
+        # significant digit of its shortest text, as IOStreams 3.0 rounds it, with Rational, so that reading a
+        # spreadsheet does not need bigdecimal. Rounding the exact value, rather than its text, gives the same digits on
+        # every Ruby, since JRuby writes the text of some Floats with other digits than Ruby does.
+        digits = DISPLAYED_DIGITS - exponent(Rational(value.to_s))
+        decimal_text(value.to_r.round(digits, half: :up), digits)
+      end
+
+      # Returns [String|nil] the text of a cell of a number type, see the class comment, by the class of its number
+      # format, see `IOStreams::Xlsx::Cells.number_formats`, such as `:date`, with the first day of the workbook, or nil
+      # for text that is not a finite number, which creek converts. A number of a date or time format that is not a date
+      # that Excel holds, such as a negative number, which Excel shows as `####`, is a number.
+      def self.number_text(text, style, base_date)
+        number = Float(text, exception: false)
+        return unless number&.finite?
+
+        Cells.date_text(text, style, base_date) || displayed(number)
+      end
+
+      # Returns [Integer] the exponent of the number as a BigDecimal gives it, the place of its first significant digit,
+      # such as 4 for 2134, 0 for 0.3, and -6 for 0.0000001.
+      def self.exponent(number)
+        magnitude = number.abs
+        exponent  = magnitude.numerator.to_s.length - magnitude.denominator.to_s.length
+        exponent += 1 while magnitude >= 10r**exponent
+        exponent -= 1 while magnitude < 10r**(exponent - 1)
+        exponent
+      end
+
+      # Returns [String] the text of the number rounded to the supplied digits after the decimal point, without a
+      # decimal point for a whole number, and without zeros at the end of its fraction, as `BigDecimal#to_s("F")` writes
+      # it, such as "0.0000001".
+      def self.decimal_text(number, digits)
+        return number.to_i.to_s if digits <= 0 || number.denominator == 1
+
+        scaled = (number * (10**digits)).to_i
+        text   = scaled.abs.to_s.rjust(digits + 1, "0")
+        "#{'-' if scaled.negative?}#{text[0...-digits]}.#{text[-digits..].sub(/0+\z/, '')}"
+      end
+      private_class_method :exponent, :decimal_text
+
+      # Reads the first worksheet of the workbook, with the text of each number cell as .number_text gives it.
+      def initialize(file_name)
+        super
+        formats = number_formats
+        convert_cells do |text, type, style, options|
+          self.class.number_text(text, formats[style], options[:base_date]) if type.nil? || type == "n"
+        end
+      end
+    end
+  end
+end

data/lib/io_streams/xlsx/v3_writer.rb

@@ -0,0 +1,16 @@
+module IOStreams
+  module Xlsx
+    # Stands for the writer of `.xlsx` and `.xlsm` files that IOStreams 3.0 adds, which IOStreams 2.2 does not have, see
+    # `IOStreams::Xlsx::Reader.v3_writer`, and answers the options that it takes, so that one of them set with `#option`,
+    # `#stream` or `#option_or_stream` is not reported as deprecated, while one that neither it nor the reader takes is,
+    # since IOStreams 3.0 raises ArgumentError for it when it is set, see `IOStreams::Builder#option`. It does not write:
+    # it is not registered, so writing a spreadsheet still raises ArgumentError.
+    module V3Writer
+      # Returns [Array<Symbol>] the options that the writer of IOStreams 3.0 takes, see
+      # `IOStreams::Deprecation::OptionNames#known_option_names`.
+      def self.known_option_names
+        %i[sheet_name auto_format use_shared_strings]
+      end
+    end
+  end
+end

data/lib/io_streams/zip/reader.rb

@@ -5,6 +5,13 @@ module IOStreams
         %i[entry_file_name]
       end
 
+      # Returns [Array<Symbol>] the methods that the stream that v3.0 supplies to a reader block, in place of the stream of
+      # the entry that this reader yields, such as a `Zip::InputStream`, 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 zip file or stream, decompressing the contents as it is read
       # The input stream from the first file found in the zip file is passed
       # to the supplied block.

data/lib/io_streams/zip/writer.rb

@@ -5,9 +5,23 @@ module IOStreams
         %i[zip_file_name entry_file_name]
       end
 
+      # `zip_file_name` is deprecated, see `entry_file_name`, which replaces it, since IOStreams 3.0 raises
+      # ArgumentError for it. `#option`, `#stream` and `#option_or_stream` report a deprecation warning when it is set,
+      # even when it is nil, see `IOStreams::Builder#option`.
+      def self.replaced_option_names
+        {zip_file_name: :entry_file_name}
+      end
+
+      # The default of `zip_file_name`, which tells that it was not supplied.
+      NO_ZIP_FILE_NAME = Object.new.freeze
+      private_constant :NO_ZIP_FILE_NAME
+
       # When writing to a file, default the entry name within the zip to the file name
       # without the `.zip` extension, unless an entry name was explicitly supplied.
-      def self.file(file_name, zip_file_name: nil, entry_file_name: zip_file_name, &)
+      #
+      # `zip_file_name` is deprecated, see .replaced_option_names.
+      def self.file(file_name, zip_file_name: NO_ZIP_FILE_NAME, entry_file_name: zip_file_name, &)
+        entry_file_name = supplied_entry_file_name(entry_file_name)
         entry_file_name = file_name.to_s[0..-5] if entry_file_name.nil? && file_name.to_s =~ /\.zip\z/i
 
         super(file_name, entry_file_name: entry_file_name, &)
@@ -34,7 +48,8 @@ module IOStreams
       #   then copied across. `zip_kit` streams to non-seekable outputs by emitting
       #   data descriptors instead, so we can write straight to the output stream and
       #   avoid the temp file round-trip.
-      def self.stream(output_stream, zip_file_name: nil, entry_file_name: zip_file_name)
+      def self.stream(output_stream, zip_file_name: NO_ZIP_FILE_NAME, entry_file_name: zip_file_name)
+        entry_file_name   = supplied_entry_file_name(entry_file_name)
         entry_file_name ||= "file"
 
         Utils.load_soft_dependency("zip_kit", "Zip") unless defined?(ZipKit::Streamer)
@@ -45,6 +60,13 @@ module IOStreams
         end
         result
       end
+
+      # Returns [String|nil] the entry name supplied, whose default is `zip_file_name`, or nil when neither was
+      # supplied.
+      def self.supplied_entry_file_name(entry_file_name)
+        entry_file_name unless entry_file_name.equal?(NO_ZIP_FILE_NAME)
+      end
+      private_class_method :supplied_entry_file_name
     end
   end
 end

data/lib/iostreams.rb

@@ -1,15 +1,18 @@
 require "io_streams/version"
 # @formatter:off
 module IOStreams
-  autoload :Builder,  "io_streams/builder"
-  autoload :Errors,   "io_streams/errors"
-  autoload :Path,     "io_streams/path"
-  autoload :Pgp,      "io_streams/pgp"
-  autoload :Reader,   "io_streams/reader"
-  autoload :Stream,   "io_streams/stream"
-  autoload :Tabular,  "io_streams/tabular"
-  autoload :Utils,    "io_streams/utils"
-  autoload :Writer,   "io_streams/writer"
+  autoload :Builder,     "io_streams/builder"
+  autoload :Deprecation, "io_streams/deprecation"
+  autoload :Encode,      "io_streams/encode"
+  autoload :Errors,      "io_streams/errors"
+  autoload :Path,        "io_streams/path"
+  autoload :Pgp,         "io_streams/pgp"
+  autoload :Reader,      "io_streams/reader"
+  autoload :Schema,      "io_streams/schema"
+  autoload :Stream,      "io_streams/stream"
+  autoload :Tabular,     "io_streams/tabular"
+  autoload :Utils,       "io_streams/utils"
+  autoload :Writer,      "io_streams/writer"
 
   module Paths
     autoload :File,    "io_streams/paths/file"
@@ -24,19 +27,15 @@ module IOStreams
     autoload :Writer, "io_streams/bzip2/writer"
   end
 
-  module Encode
-    autoload :Reader, "io_streams/encode/reader"
-    autoload :Writer, "io_streams/encode/writer"
-  end
-
   module Gzip
     autoload :Reader, "io_streams/gzip/reader"
     autoload :Writer, "io_streams/gzip/writer"
   end
 
   module Line
-    autoload :Reader, "io_streams/line/reader"
-    autoload :Writer, "io_streams/line/writer"
+    autoload :Reader,     "io_streams/line/reader"
+    autoload :Utf8Reader, "io_streams/line/utf8_reader"
+    autoload :Writer,     "io_streams/line/writer"
   end
 
   module Record
@@ -45,6 +44,7 @@ module IOStreams
   end
 
   module Row
+    autoload :HeaderRow, "io_streams/row/header_row"
     autoload :Reader, "io_streams/row/reader"
     autoload :Writer, "io_streams/row/writer"
   end
@@ -55,7 +55,10 @@ module IOStreams
   end
 
   module Xlsx
-    autoload :Reader, "io_streams/xlsx/reader"
+    autoload :Cells,        "io_streams/xlsx/cells"
+    autoload :Reader,       "io_streams/xlsx/reader"
+    autoload :SchemaReader, "io_streams/xlsx/schema_reader"
+    autoload :V3Writer,     "io_streams/xlsx/v3_writer"
   end
 
   module Zip
@@ -63,4 +66,5 @@ module IOStreams
     autoload :Writer, "io_streams/zip/writer"
   end
 end
+require "io_streams/paths"
 require "io_streams/io_streams"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: iostreams
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Reid Morrison
@@ -46,8 +46,15 @@ files:
 - docs/tutorial.md
 - docs/upgrading.md
 - lib/io_streams/builder.rb
+- lib/io_streams/builder/deprecations.rb
 - lib/io_streams/bzip2/reader.rb
 - lib/io_streams/bzip2/writer.rb
+- lib/io_streams/deprecation.rb
+- lib/io_streams/deprecation/methods.rb
+- lib/io_streams/deprecation/once.rb
+- lib/io_streams/deprecation/option_names.rb
+- lib/io_streams/deprecation/words.rb
+- lib/io_streams/encode.rb
 - lib/io_streams/encode/reader.rb
 - lib/io_streams/encode/writer.rb
 - lib/io_streams/errors.rb
@@ -55,8 +62,10 @@ files:
 - lib/io_streams/gzip/writer.rb
 - lib/io_streams/io_streams.rb
 - lib/io_streams/line/reader.rb
+- lib/io_streams/line/utf8_reader.rb
 - lib/io_streams/line/writer.rb
 - lib/io_streams/path.rb
+- lib/io_streams/paths.rb
 - lib/io_streams/paths/file.rb
 - lib/io_streams/paths/http.rb
 - lib/io_streams/paths/matcher.rb
@@ -69,24 +78,41 @@ files:
 - lib/io_streams/reader.rb
 - lib/io_streams/record/reader.rb
 - lib/io_streams/record/writer.rb
+- lib/io_streams/row/header_row.rb
 - lib/io_streams/row/reader.rb
 - lib/io_streams/row/writer.rb
+- lib/io_streams/schema.rb
+- lib/io_streams/schema/columns.rb
+- lib/io_streams/schema/constraints.rb
+- lib/io_streams/schema/field.rb
+- lib/io_streams/schema/json_number.rb
+- lib/io_streams/schema/keys.rb
+- lib/io_streams/schema/pattern.rb
+- lib/io_streams/schema/source.rb
 - lib/io_streams/stream.rb
 - lib/io_streams/symmetric_encryption/reader.rb
 - lib/io_streams/symmetric_encryption/writer.rb
 - lib/io_streams/tabular.rb
 - lib/io_streams/tabular/header.rb
+- lib/io_streams/tabular/header_mapping.rb
+- lib/io_streams/tabular/mapping.rb
 - lib/io_streams/tabular/parser/array.rb
 - lib/io_streams/tabular/parser/base.rb
 - lib/io_streams/tabular/parser/csv.rb
 - lib/io_streams/tabular/parser/fixed.rb
+- lib/io_streams/tabular/parser/fixed_fields.rb
 - lib/io_streams/tabular/parser/hash.rb
 - lib/io_streams/tabular/parser/json.rb
+- lib/io_streams/tabular/parser/json_fields.rb
 - lib/io_streams/tabular/parser/psv.rb
+- lib/io_streams/tabular/schema_mapping.rb
 - lib/io_streams/utils.rb
 - lib/io_streams/version.rb
 - lib/io_streams/writer.rb
+- lib/io_streams/xlsx/cells.rb
 - lib/io_streams/xlsx/reader.rb
+- lib/io_streams/xlsx/schema_reader.rb
+- lib/io_streams/xlsx/v3_writer.rb
 - lib/io_streams/zip/reader.rb
 - lib/io_streams/zip/writer.rb
 - lib/iostreams.rb
@@ -98,7 +124,7 @@ metadata:
   changelog_uri: https://github.com/reidmorrison/iostreams/blob/main/CHANGELOG.md
   documentation_uri: https://iostreams.reidmorrison.com
   homepage_uri: https://iostreams.reidmorrison.com
-  source_code_uri: https://github.com/reidmorrison/iostreams/tree/v2.1.0
+  source_code_uri: https://github.com/reidmorrison/iostreams/tree/v2.2.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: