calcsheet 0.1.0

data/lib/calcsheet/writers/xlsx_writer.rb

@@ -0,0 +1,350 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "date"
+require "stringio" # zip_kit 6.3 uses StringIO without requiring it
+require "zip_kit"
+require_relative "../column_letter"
+require_relative "../decimal_text"
+require_relative "../errors"
+require_relative "../excel_serial"
+require_relative "../grid"
+require_relative "xml_text"
+require_relative "zip_buffered"
+
+module Calcsheet
+  module Writers
+    # XLSX writer backend, see the contract in WriteBook. Each sheet is one deflated zip entry streamed with
+    # zip_kit as its rows arrive, built as strings in a buffer of about BUFFER_SIZE bytes: memory stays flat and the
+    # output may be non-seekable. Text is written as inline strings (no shared strings table), never evaluated, so
+    # "+39..." and "=..." stay verbatim. The parts that list every sheet (workbook, relationships, content
+    # types) and the styles, known only at the end, are written after the sheets; zip entries have no required order.
+    #
+    # Styles: the default, the bold header, and one per number format a column needs: decimals with +scale+ (the
+    # full value is stored, the format shows +scale+ decimals), dates and datetimes. They are numbered in the order
+    # the columns first use them.
+    #
+    # @api private
+    class XlsxWriter
+      include ZipBuffered
+
+      # The characters beyond the Basic Multilingual Plane (String#count ranges), which Excel counts twice.
+      ASTRAL = "\u{10000}-\u{10FFFF}"
+
+      MAIN_NS = "http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+      REL_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+      PACKAGE_REL_NS = "http://schemas.openxmlformats.org/package/2006/relationships"
+      CONTENT_TYPES_NS = "http://schemas.openxmlformats.org/package/2006/content-types"
+      OFFICE_DOCUMENT = "#{REL_NS}/officeDocument".freeze
+      WORKSHEET = "#{REL_NS}/worksheet".freeze
+      STYLES = "#{REL_NS}/styles".freeze
+      SPREADSHEET_TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml"
+      DECLARATION = %(<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n)
+      # The sheet view of a sheet whose first row is frozen.
+      FROZEN_HEADER = '<pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/>'
+
+      # The number format codes of :date and :datetime columns.
+      DATE_FORMAT = "yyyy-mm-dd"
+      DATETIME_FORMAT = "yyyy-mm-dd hh:mm:ss"
+      # Ids below are built-in formats.
+      FIRST_CUSTOM_FORMAT = 164
+      # The key of the bold header style in +@styles+, beside the number format codes.
+      HEADER_STYLE = :header
+
+
+      # @return [Integer] rows per sheet, header included
+      def self.max_rows_per_sheet
+        Grid::MAX_ROWS
+      end
+
+      # @param io [#<<] the output, never closed here
+      # @param _options [Options] as returned by WriteBook.prepare_options; XLSX has no format options
+      def initialize(io, _options)
+        @zip = ZipKit::Streamer.new(io)
+        @sheet_names = []
+        @styles = {}
+        @cell_formats = []
+        @number_formats = {}
+        @buffer = new_buffer
+        @entry = nil
+      end
+
+      # Opens the sheet's zip entry and writes its start, column widths and header row.
+      # @raise [ArgumentError] for more columns than XLSX holds
+      # @raise [WriteError] for a header longer than a cell holds
+      def start_sheet(name, columns, header:)
+        check_sheet(name, columns)
+        @sheet_names << name
+        @name = name
+        @columns = columns
+        @types = columns.map(&:type)
+        @row_number = 0
+        prepare_cells(columns)
+        @entry = @zip.write_deflated_file("xl/worksheets/sheet#{@sheet_names.size}.xml")
+        @buffer << sheet_start(columns, header)
+        write_header(columns) if header
+      end
+
+      # Writes one row of checked values (see the contract in WriteBook) from the constant parts of #prepare_cells.
+      # @raise [WriteError] for a date beyond the serials or a text longer than a cell; nothing of the row is written
+      def row(values)
+        mark = @buffer.bytesize
+        number = (@row_number + 1).to_s
+        @buffer << '<row r="' << number << '">'
+        index = 0
+        while index < values.size
+          value = values[index]
+          unless value.nil?
+            @buffer << @openings[index] << number << @middles[index]
+            cell(value, index)
+            @buffer << @closings[index]
+          end
+          index += 1
+        end
+        @buffer << "</row>"
+        @row_number += 1
+        flush if @buffer.bytesize >= BUFFER_SIZE
+      rescue StandardError
+        # Nothing of a rejected row is written (a WriteError of a date beyond the serials).
+        rollback(mark)
+        raise
+      end
+
+      # Ends the sheet's XML and closes its zip entry.
+      def end_sheet
+        @buffer << "</sheetData></worksheet>"
+        flush
+        @entry.close
+        @entry = nil
+      end
+
+      # Writes the parts that list the sheets, and the zip central directory. A workbook needs a sheet: a book without
+      # any gets an empty one.
+      def finish
+        empty_book_sheet if @sheet_names.empty?
+        write_parts("xl/styles.xml" => styles_xml, "xl/workbook.xml" => workbook_xml,
+                    "xl/_rels/workbook.xml.rels" => workbook_relationships_xml, "_rels/.rels" => package_relationships_xml,
+                    "[Content_Types].xml" => content_types_xml)
+        @zip.close
+      end
+
+      # @api private
+      # The first value of a checked row that #row would refuse, without writing anything: WriteSheet asks before it
+      # opens a continuation sheet for the row, so that a refused row leaves no sheet with only a header.
+      # @return [Array(Integer, String), nil] the column index and the reason
+      def row_problem(values)
+        values.each_with_index do |value, index|
+          next if value.nil?
+
+          reason =
+            case @types[index]
+            # A text of at most 32,767 bytes has at most as many UTF-16 code units (a UTF-8 character takes at least as
+            # many bytes as it takes units): only a longer one is counted.
+            when :string then length_reason(excel_length(value)) if value.bytesize > Grid::MAX_CELL_CHARACTERS && excel_length(value) > Grid::MAX_CELL_CHARACTERS
+            when :date, :datetime then date_reason(value) unless ExcelSerial.serial(value)
+            end
+          return [ index, reason ] if reason
+        end
+        nil
+      end
+
+      private
+
+      # @raise [ArgumentError] for more columns than XLSX holds
+      # @raise [WriteError] for a header longer than a cell holds (checked whether or not the header is written)
+      def check_sheet(name, columns)
+        check_columns(name, columns, "XLSX")
+
+        columns.each_with_index do |column, index|
+          header = column.header
+          next if header.bytesize <= Grid::MAX_CELL_CHARACTERS || (length = excel_length(header)) <= Grid::MAX_CELL_CHARACTERS
+
+          raise WriteError.at(length_reason(length), sheet: name, row: 1, column_index: index, header: header)
+        end
+      end
+
+      # The constant parts of each column's cells: "<c r=\"B" before the row number, its style and type up to the
+      # value after it, and what closes the cell.
+      def prepare_cells(columns)
+        @letters = columns.each_index.map { ColumnLetter.from_index(_1) }
+        @openings = @letters.map { %(<c r="#{_1}).freeze }
+        @middles = columns.map { |column| %("#{style_attribute(format_of(column))}#{value_opening(column.type)}).freeze }
+        @closings = columns.map { _1.type == :string ? "</t></is></c>" : "</v></c>" }
+      end
+
+      def value_opening(type)
+        case type
+        when :string then ' t="inlineStr"><is><t xml:space="preserve">'
+        when :boolean then ' t="b"><v>'
+        else "><v>"
+        end
+      end
+
+      def format_of(column)
+        case column.type
+        when :decimal then column.scale && (column.scale.zero? ? "0" : "0.#{"0" * column.scale}")
+        when :date then DATE_FORMAT
+        when :datetime then DATETIME_FORMAT
+        end
+      end
+
+      # @param key [String, Symbol, nil] a number format code, HEADER_STYLE, or nil for the default style
+      def style_attribute(key)
+        key.nil? ? "" : %( s="#{style(key)}")
+      end
+
+      # The cellXfs index of a style, registered at its first use; index 0 is the default style. Each cell format is
+      # +[numFmtId, fontId]+: the header is the General format (0) in the bold font (1, see #styles_xml), a number
+      # format its custom format in the default font (0).
+      def style(key)
+        @styles[key] ||= begin
+          @cell_formats << (key == HEADER_STYLE ? [ 0, 1 ] : [ number_format(key), 0 ])
+          @cell_formats.size
+        end
+      end
+
+      def number_format(code)
+        @number_formats[code] ||= FIRST_CUSTOM_FORMAT + @number_formats.size
+      end
+
+      def sheet_start(columns, header)
+        xml = +DECLARATION
+        xml << %(<worksheet xmlns="#{MAIN_NS}" xmlns:r="#{REL_NS}"><sheetViews><sheetView)
+        xml << ' tabSelected="1"' if @sheet_names.size == 1
+        xml << ' workbookViewId="0"'
+        xml << (header ? ">#{FROZEN_HEADER}</sheetView>" : "/>")
+        xml << "</sheetViews>"
+        xml << widths(columns)
+        xml << "<sheetData>"
+      end
+
+      def widths(columns)
+        cols = columns.each_with_index.filter_map do |column, index|
+          next if column.width.nil?
+
+          %(<col min="#{index + 1}" max="#{index + 1}" width="#{number_text(column.width)}" customWidth="1"/>)
+        end
+        cols.empty? ? "" : "<cols>#{cols.join}</cols>"
+      end
+
+      def number_text(number)
+        number.is_a?(Integer) ? number.to_s : Float(number).to_s
+      end
+
+      def write_header(columns)
+        style = style_attribute(HEADER_STYLE)
+        @buffer << '<row r="1">'
+        columns.each_with_index do |column, index|
+          @buffer << %(<c r="#{@letters[index]}1"#{style} t="inlineStr"><is><t xml:space="preserve">)
+          @buffer << XmlText.escape(column.header, ooxml: true) << "</t></is></c>"
+        end
+        @buffer << "</row>"
+        @row_number = 1
+      end
+
+      def cell(value, index)
+        case @types[index]
+        when :string
+          check_length(value, index) if value.bytesize > Grid::MAX_CELL_CHARACTERS
+          @buffer << XmlText.escape(value, ooxml: true)
+        when :integer then @buffer << value.to_s
+        when :decimal then @buffer << DecimalText.plain(value)
+        when :date then @buffer << (ExcelSerial.serial(value) || refuse(date_reason(value), index)).to_s
+        when :datetime then @buffer << datetime_serial(value, index)
+        else @buffer << (value ? "1" : "0") # :boolean
+        end
+      end
+
+      # A UTC Time whose fields are the wall clock, in whole seconds: the serial of its day plus the fraction of the
+      # day, as the double nearest to the exact value in its shortest text, as Excel writes it. Both integers are
+      # below 2**53, so the division is exact up to its correct rounding. Fewer digits would lose up to microseconds,
+      # enough for LibreOffice, which truncates to the second, to show 23:59:58 for 23:59:59.
+      def datetime_serial(time, index)
+        days, seconds = ExcelSerial.days_and_seconds(time)
+        serial = ExcelSerial.day_serial(days) or refuse(date_reason(time), index)
+        return serial.to_s if seconds.zero?
+
+        (serial * ExcelSerial::SECONDS_PER_DAY + seconds).fdiv(ExcelSerial::SECONDS_PER_DAY).to_s
+      end
+
+      # @raise [WriteError] the text has more characters than an Excel cell holds
+      def check_length(text, index)
+        length = excel_length(text)
+        refuse(length_reason(length), index) if length > Grid::MAX_CELL_CHARACTERS
+      end
+
+      def length_reason(length)
+        "an XLSX cell holds at most #{Grid::MAX_CELL_CHARACTERS} characters, got #{length}"
+      end
+
+      def date_reason(value)
+        "XLSX stores dates from 1900-01-01 to 9999-12-31, got #{value.inspect}"
+      end
+
+      # @raise [WriteError] at the row being written
+      def refuse(reason, index)
+        row = @row_number + 1
+        raise WriteError.at(reason, sheet: @name, row: row, column_index: index, header: @columns[index].header)
+      end
+
+      # The characters of +text+ as Excel counts them: one beyond the Basic Multilingual Plane counts twice.
+      def excel_length(text)
+        length = text.length
+        length += text.count(ASTRAL) unless text.ascii_only?
+        length
+      end
+
+      def styles_xml
+        formats = @number_formats.map { |code, id| %(<numFmt numFmtId="#{id}" formatCode="#{XmlText.escape(code)}"/>) }
+        xfs = [ [ 0, 0 ], *@cell_formats ].map do |format, font|
+          attributes = %(numFmtId="#{format}" fontId="#{font}" fillId="0" borderId="0" xfId="0")
+          attributes += ' applyNumberFormat="1"' unless format.zero?
+          attributes += ' applyFont="1"' unless font.zero?
+          "<xf #{attributes}/>"
+        end
+        font = '<sz val="11"/><name val="Calibri"/><family val="2"/>'
+        xml = +%(#{DECLARATION}<styleSheet xmlns="#{MAIN_NS}">)
+        xml << %(<numFmts count="#{formats.size}">#{formats.join}</numFmts>) unless formats.empty?
+        xml << %(<fonts count="2"><font>#{font}</font><font><b/>#{font}</font></fonts>)
+        xml << '<fills count="2"><fill><patternFill patternType="none"/></fill><fill><patternFill patternType="gray125"/></fill></fills>'
+        xml << '<borders count="1"><border><left/><right/><top/><bottom/><diagonal/></border></borders>'
+        xml << '<cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs>'
+        xml << %(<cellXfs count="#{xfs.size}">#{xfs.join}</cellXfs>)
+        xml << '<cellStyles count="1"><cellStyle name="Normal" xfId="0" builtinId="0"/></cellStyles></styleSheet>'
+      end
+
+      def workbook_xml
+        sheets = @sheet_names.each_with_index.map do |name, index|
+          %(<sheet name="#{XmlText.escape(name)}" sheetId="#{index + 1}" r:id="rId#{index + 1}"/>)
+        end
+        %(#{DECLARATION}<workbook xmlns="#{MAIN_NS}" xmlns:r="#{REL_NS}"><bookViews><workbookView activeTab="0"/></bookViews>) +
+          "<sheets>#{sheets.join}</sheets></workbook>"
+      end
+
+      def workbook_relationships_xml
+        relationships = @sheet_names.each_index.map do |index|
+          %(<Relationship Id="rId#{index + 1}" Type="#{WORKSHEET}" Target="worksheets/sheet#{index + 1}.xml"/>)
+        end
+        relationships << %(<Relationship Id="rId#{@sheet_names.size + 1}" Type="#{STYLES}" Target="styles.xml"/>)
+        %(#{DECLARATION}<Relationships xmlns="#{PACKAGE_REL_NS}">#{relationships.join}</Relationships>)
+      end
+
+      def package_relationships_xml
+        %(#{DECLARATION}<Relationships xmlns="#{PACKAGE_REL_NS}">) +
+          %(<Relationship Id="rId1" Type="#{OFFICE_DOCUMENT}" Target="xl/workbook.xml"/></Relationships>)
+      end
+
+      def content_types_xml
+        sheets = @sheet_names.each_index.map do |index|
+          %(<Override PartName="/xl/worksheets/sheet#{index + 1}.xml" ContentType="#{SPREADSHEET_TYPE}.worksheet+xml"/>)
+        end
+        %(#{DECLARATION}<Types xmlns="#{CONTENT_TYPES_NS}">) +
+          '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>' \
+          '<Default Extension="xml" ContentType="application/xml"/>' +
+          %(<Override PartName="/xl/workbook.xml" ContentType="#{SPREADSHEET_TYPE}.sheet.main+xml"/>) +
+          sheets.join +
+          %(<Override PartName="/xl/styles.xml" ContentType="#{SPREADSHEET_TYPE}.styles+xml"/></Types>)
+      end
+    end
+  end
+end

data/lib/calcsheet/writers/xml_text.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Calcsheet
+  module Writers
+    # Text for the XML parts of XLSX and ODS files: markup escaped, the characters XML 1.0 does not allow
+    # removed. A carriage return becomes a character reference, since XML parsers turn a literal one into a line
+    # feed. Tab and line feed stay literal, so the result is for element content (and attributes without them).
+    #
+    # @api private
+    module XmlText
+      # The characters to replace or remove: markup, the carriage return and those outside the Char production of
+      # XML 1.0 (control characters other than tab, line feed and carriage return, U+FFFE and U+FFFF; a valid UTF-8
+      # String carries no surrogate).
+      SPECIAL = /[&<>"\r\u0000-\u0008\u000B\u000C\u000E-\u001F\uFFFE\uFFFF]/
+      # Characters missing from the table are removed.
+      REPLACEMENTS = { "&" => "&amp;", "<" => "&lt;", ">" => "&gt;", '"' => "&quot;", "\r" => "&#13;" }.freeze
+      # An underscore that starts what OOXML readers decode as an escape (_xHHHH_), overlapping ones included.
+      OOXML_ESCAPE = /_(?=x\h{4}_)/
+      # The escape of "_" itself.
+      ESCAPED_UNDERSCORE = "_x005F_"
+
+      module_function
+
+      # @param text [String] UTF-8
+      # @param ooxml [Boolean] also write the underscore of a literal "_xHHHH_" as "_x005F_", so that XLSX readers,
+      #   which decode those escapes, read the text back unchanged (the XML of ODS has no such escapes)
+      # @return [String] +text+ itself when nothing changes
+      def escape(text, ooxml: false)
+        text = text.gsub(SPECIAL, REPLACEMENTS) if SPECIAL.match?(text)
+        text = text.gsub(OOXML_ESCAPE, ESCAPED_UNDERSCORE) if ooxml && text.include?("_x") && OOXML_ESCAPE.match?(text)
+        text
+      end
+    end
+  end
+end

data/lib/calcsheet/writers/zip_buffered.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "../grid"
+
+module Calcsheet
+  module Writers
+    # What the XLSX and ODS writers share: each streams a zip entry (+@entry+) from a String buffer (+@buffer+) of
+    # about BUFFER_SIZE bytes, flushed only after whole rows, so that a row the writer refuses can be taken back out of
+    # it; writes the parts known only at the end (+@zip+, a ZipKit::Streamer); and gives a book without sheets the
+    # empty one a workbook needs. The row loops stay in the writers.
+    #
+    # @api private
+    module ZipBuffered
+      # The bytes of rows the buffer collects before they go to the zip entry.
+      BUFFER_SIZE = 64 * 1024
+      # The name of the empty sheet of a book without sheets.
+      EMPTY_BOOK_SHEET = "Sheet1"
+
+      private
+
+      def new_buffer
+        String.new(capacity: BUFFER_SIZE * 2, encoding: Encoding::UTF_8)
+      end
+
+      # @param format [String] the format, for the message
+      # @raise [ArgumentError] for more columns than a sheet holds
+      def check_columns(name, columns, format)
+        return if columns.size <= Grid::MAX_COLUMNS
+
+        raise ArgumentError, "sheet '#{name}' has #{columns.size} columns, more than the #{Grid::MAX_COLUMNS} of #{format}"
+      end
+
+      # Takes back what a refused row wrote to the buffer since +mark+, its size before the row.
+      def rollback(mark)
+        @buffer.bytesplice(mark, @buffer.bytesize - mark, "")
+      end
+
+      def flush
+        @entry << @buffer
+        @buffer.clear
+      end
+
+      # The sheet of a book whose block wrote none.
+      def empty_book_sheet
+        start_sheet(EMPTY_BOOK_SHEET, [], header: false)
+        end_sheet
+      end
+
+      # @param parts [Hash{String => String}] the XML of each entry, by path
+      def write_parts(parts)
+        parts.each { |path, xml| @zip.write_deflated_file(path) { |sink| sink << xml } }
+      end
+    end
+  end
+end

data/lib/calcsheet/zip_container.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "zip"
+require "zlib"
+require_relative "entry_name"
+require_relative "zip_directory"
+require_relative "limited_inflater"
+
+module Calcsheet
+  # The single door to a zip archive (XLSX and ODS are zip files) with the zip
+  # bomb protection enforced in one place:
+  #
+  # * +max_zip_entries+ is checked from the End Of Central Directory record, and the
+  #   layout of the central directory by ZipDirectory, before rubyzip loads it;
+  # * +max_compression_ratio+ is checked per entry, above the +compression_ratio_floor+
+  #   bytes any streamed entry may inflate to (a part kept in memory gets the fixed
+  #   MEMORY_RATIO_FLOOR instead), and +max_uncompressed_size+ in total across every
+  #   stream and read of the container, both on the bytes actually inflated, never on
+  #   the sizes the archive declares;
+  # * +max_cell_bytes+ bounds the texts and tags of the XML entries (see LimitedInflater).
+  #
+  # A +nil+ limit disables that check. The container holds no resource of its own:
+  # it reads through the IO of the Source it was opened on, which stays owned by
+  # the caller (the readers hold the Source), and seeks it before every read, so
+  # any number of streams can be read side by side.
+  #
+  # @api private
+  class ZipContainer
+    # The steps of a #read bounded by +max_bytes+.
+    READ_CHUNK_BYTES = 65_536
+    # The bytes a part kept in memory (the XLSX shared strings) may inflate to whatever its ratio, instead of
+    # +compression_ratio_floor+, which does not apply to it: enough for a small file of long repetitive strings, while
+    # 16 MiB of empty strings cost about 54 MB (ADR 008).
+    MEMORY_RATIO_FLOOR = 16_777_216
+
+    # Opens an archive.
+    #
+    # @param source [Source] a source opened with +needs_seek: true+; its +io+ may be at any position
+    # @param options [Options] supplies +max_zip_entries+, +max_compression_ratio+, +compression_ratio_floor+,
+    #   +max_uncompressed_size+ and +max_cell_bytes+
+    # @yieldparam container [ZipContainer]
+    # @return [Object, ZipContainer] the block value, or the container when no block is given
+    # @raise [ZipBombError] with limit +:max_zip_entries+ when the archive has too many entries
+    # @raise [MalformedFileError] (with the zip library's error as +cause+) for a damaged archive
+    def self.open(source, options)
+      container = new(source.io, options)
+      block_given? ? yield(container) : container
+    end
+
+    # @param io [IO] a seekable binary IO
+    # @param options [Options]
+    def initialize(io, options)
+      @io = io
+      @max_ratio = options.max_compression_ratio
+      @ratio_floor = options.compression_ratio_floor || 0
+      @max_total = options.max_uncompressed_size
+      @max_entries = options.max_zip_entries
+      @max_cell_bytes = options.max_cell_bytes
+      @inflated_total = 0
+      @zip = open_archive
+    end
+
+    # @return [Array<String>] the names of the file entries, backslashes read as slashes
+    def names
+      files.map(&:name)
+    end
+
+    # @param name [String] an entry name; a leading "/" and "\" separators are tolerated
+    # @return [Boolean] whether the archive has a file (not a directory) by that name
+    def entry?(name)
+      !find(name).nil?
+    end
+
+    # Reads a whole entry; meant for small parts. The bytes count against the limits like a stream's.
+    #
+    # @param max_bytes [Integer, nil] the most bytes the entry may inflate to; checked while it is read
+    # @return [String] binary
+    # @raise [MalformedFileError] when the entry is missing, damaged or longer than +max_bytes+
+    # @raise [ZipBombError] when a limit is exceeded
+    def read(name, max_bytes: nil)
+      input = stream(name)
+      return input.read if max_bytes.nil?
+
+      data = "".b
+      while (chunk = input.read(READ_CHUNK_BYTES))
+        data << chunk
+        raise MalformedFileError, "#{name} is longer than #{max_bytes} bytes" if data.bytesize > max_bytes
+      end
+      data
+    ensure
+      input&.close
+    end
+
+    # @param bound_tokens [Boolean] bound the texts and tags by +max_cell_bytes+ (LimitedInflater), for a stream that
+    #   an XML parser reads; false for a reader that bounds what it buffers itself
+    # @param ratio_floor [Boolean] let the entry inflate to +compression_ratio_floor+ whatever its ratio; false for a
+    #   part kept in memory (the shared strings), whose cost grows with what it inflates to, which may inflate to
+    #   MEMORY_RATIO_FLOOR only
+    # @return [LimitedInflater] an IO-like object that inflates lazily and counts the inflated bytes
+    # @raise [MalformedFileError] when the entry is missing
+    # @raise [UnsupportedFormatError] for an encrypted entry or a compression method other than stored or deflate
+    def stream(name, bound_tokens: true, ratio_floor: true)
+      entry = find(name)
+      raise MalformedFileError, "the archive has no entry #{EntryName.show(name)}" if entry.nil?
+
+      check_supported(entry)
+      offset = data_offset(entry)
+      check_within_archive(entry, offset)
+      LimitedInflater.new(io: @io, entry: entry, data_offset: offset, container: self, max_ratio: @max_ratio,
+                          ratio_floor: ratio_floor ? @ratio_floor : MEMORY_RATIO_FLOOR, max_cell_bytes: (@max_cell_bytes if bound_tokens))
+    end
+
+    # The bound on the texts and tags of the entry, for the bytes of a stream opened with +bound_tokens: false+ that
+    # an XML parser reads after a byte scanner (StreamRemainder).
+    # @return [LimitedInflater::TokenBound, nil] nil without +max_cell_bytes+
+    def token_bound(name)
+      @max_cell_bytes && LimitedInflater::TokenBound.new(EntryName.show(name), @max_cell_bytes)
+    end
+
+    # Adds inflated bytes to the total of the container. Called by its streams.
+    #
+    # @raise [ZipBombError] with limit +:max_uncompressed_size+ when the total passes the limit
+    def charge(bytes)
+      @inflated_total += bytes
+      return if @max_total.nil? || @inflated_total <= @max_total
+
+      raise ZipBombError.new(limit: :max_uncompressed_size, max: @max_total, actual: @inflated_total)
+    end
+
+    private
+
+    def open_archive
+      zip, @directory_offset = ZipDirectory.open(@io, max_entries: @max_entries)
+      zip
+    end
+
+    def files
+      @files ||= @zip.entries.reject(&:directory?)
+    end
+
+    # Exact name first; then with a leading "/" removed and "\\" read as "/" on both sides (rubyzip already
+    # reads backslashes of stored names as slashes).
+    def find(name)
+      entry = @zip.find_entry(name)
+      return entry if entry && !entry.directory?
+
+      normalized[normalize(name)]
+    end
+
+    def normalized
+      @normalized ||= files.each_with_object({}) { |entry, index| index[normalize(entry.name)] ||= entry }
+    end
+
+    def normalize(name)
+      EntryName.normalize(name)
+    end
+
+    def check_supported(entry)
+      if entry.encrypted?
+        raise UnsupportedFormatError, "entry #{EntryName.show(entry.name)} is encrypted; encrypted zip entries are not supported"
+      end
+      return if [ LimitedInflater::STORED, LimitedInflater::DEFLATED ].include?(entry.compression_method)
+
+      raise UnsupportedFormatError,
+            "entry #{EntryName.show(entry.name)} uses compression method #{entry.compression_method}, which is not supported"
+    end
+
+    # The declared compressed size is the denominator of the ratio limit, so it must be real: the data
+    # has to fit in the archive, before its central directory.
+    def check_within_archive(entry, offset)
+      @io.seek(0, IO::SEEK_END)
+      return if offset + entry.compressed_size <= [ @io.pos, @directory_offset ].compact.min
+
+      raise MalformedFileError, "entry #{EntryName.show(entry.name)} is damaged: its data extends past the end of the archive"
+    end
+
+    # Position of the first byte of the entry's data: after the local header, whose name and
+    # extra field lengths may differ from the central directory's.
+    def data_offset(entry)
+      @io.seek(entry.local_header_offset, IO::SEEK_SET)
+      header = @io.read(ZipDirectory::LOCAL_HEADER_SIZE)
+      unless header&.bytesize == ZipDirectory::LOCAL_HEADER_SIZE && header.start_with?(ZipDirectory::LOCAL_SIGNATURE)
+        raise MalformedFileError, "the local header of entry #{EntryName.show(entry.name)} is missing or damaged"
+      end
+
+      name_length, extra_length = header.unpack(ZipDirectory::LOCAL_NAME_LENGTHS)
+      entry.local_header_offset + ZipDirectory::LOCAL_HEADER_SIZE + name_length + extra_length
+    end
+  end
+end