calcsheet 0.1.0

data/lib/calcsheet/readers/tag_scan.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Calcsheet
+  module Readers
+    # What the byte scanners (Xlsx::RowSkipper, Ods::Cursor) share: they search a buffer of the inflated XML for the
+    # opening of the tags they want, pass over comments, CDATA sections and processing instructions, and keep only
+    # what a tag cut by the end of a chunk needs. The including class keeps the binary +@buffer+ and the stream +@io+,
+    # and defines +located(message)+, the MalformedFileError of a message at its position.
+    #
+    # @api private
+    module TagScan
+      # The bytes read from the stream at a time.
+      CHUNK_BYTES = 65_536
+      # The longest tag a scanner buffers: a wanted start tag, or the name of one cut by a chunk boundary.
+      MAX_TAG_BYTES = 65_536
+      # A start or end tag from "<" to ">", with ">" allowed inside quoted attribute values.
+      TAG = /\G<(?>[^>"']*)(?>(?:"[^"]*"|'[^']*')(?>[^>"']*))*>/n
+      # A tag without quoted values or another "<", such as an end tag.
+      PLAIN_TAG = /\G<[^<>"']*>/n
+      # The bytes after "<" that open a processing instruction, and a comment, CDATA section or declaration.
+      QUESTION_MARK = 0x3F
+      EXCLAMATION_MARK = 0x21
+      # What ends the markup that starts with "<?", "<!--" and "<![CDATA[", and the length of each opening.
+      INSTRUCTION = [ "?>", 2 ].freeze
+      COMMENT = [ "-->", 4 ].freeze
+      CDATA = [ "]]>", 9 ].freeze
+      COMMENT_OPENING = "<!--".b.freeze
+      CDATA_OPENING = "<![CDATA[".b.freeze
+      # The "<!" markup whose text is passed over, with its terminator and opening length; another "<!" (a DOCTYPE)
+      # is passed over as a tag.
+      DECLARATIONS = [ [ COMMENT_OPENING, COMMENT ].freeze, [ CDATA_OPENING, CDATA ].freeze ].freeze
+
+      private
+
+      # @return [Array(String, Integer), Symbol, nil] the terminator and opening length of the markup at +start+;
+      #   :incomplete when the buffer ends inside what may be an opening, :other for another "<!" declaration, nil
+      #   for a tag
+      def markup_at(start)
+        case @buffer.getbyte(start + 1)
+        when QUESTION_MARK then INSTRUCTION
+        when EXCLAMATION_MARK
+          DECLARATIONS.each do |opening, markup|
+            piece = @buffer.byteslice(start, opening.bytesize)
+            return markup if piece == opening
+            return :incomplete if piece.bytesize < opening.bytesize && opening.start_with?(piece)
+          end
+          :other
+        end
+      end
+
+      # Whether the "<" at +start+ (a wanted tag or a markup opening) is not preceded by a complete tag: the search
+      # passes over the other tags without reading them, so the "<" before +start+, read with TAG's quoted values,
+      # must end before +start+. Otherwise +start+ is inside an attribute value, where a "<" is not XML but Ox would
+      # read it as text, and the scan cannot tell what the parser will see. +from+, where the search started, is
+      # always at a tag boundary (after a tag or markup, or at a "<" kept by #partial_tag), so the "<" before +start+
+      # is a tag's.
+      def enclosing_tag?(from, start)
+        return false if start == from
+
+        last = @buffer.byterindex("<", start - 1)
+        return false if last.nil? || last < from
+        # The common case without a MatchData: a tag without quotes (an end tag) that ends before the next "<".
+        return false if PLAIN_TAG.match?(@buffer, last)
+
+        match = TAG.match(@buffer, last)
+        !(match && match.end(0) <= start)
+      end
+
+      def inside_attribute
+        located("a \"<\" inside a tag, which XML does not allow")
+      end
+
+      def long_name
+        located("an element name is longer than #{MAX_TAG_BYTES} bytes")
+      end
+
+      # Reads past the markup at +start+, dropping its text as it goes.
+      # @return [Integer, nil] the position after its terminator; nil when the stream ends first
+      def skip_markup(start, terminator, opening)
+        from = start + opening
+        loop do
+          found = @buffer.byteindex(terminator, from)
+          return found + terminator.bytesize if found
+
+          # Keep only what could be the beginning of a terminator split between chunks.
+          discard([ from, @buffer.bytesize - terminator.bytesize + 1 ].max)
+          from = 0
+          return unless read_more
+        end
+      end
+
+      # Where a wanted tag cut by the end of the buffer may begin: the last "<" after +from+ when only name bytes
+      # (+partial_name+, anchored at it) follow it; the end of the buffer otherwise. A tag whose name has ended is not
+      # wanted (the search would have found it), so it is passed over unbuffered, whatever its length: the scan then
+      # resumes inside it, which is safe for well-formed XML, where no "<" occurs inside a tag (see #enclosing_tag?).
+      # @raise [MalformedFileError] for a last "<" inside the tag before it
+      def partial_tag(from, partial_name)
+        last = @buffer.byterindex("<")
+        return @buffer.bytesize if last.nil? || last < from
+        raise inside_attribute if enclosing_tag?(from, last)
+
+        @buffer.match?(partial_name, last) ? last : @buffer.bytesize
+      end
+
+      def discard(position)
+        @buffer = @buffer.byteslice(position, @buffer.bytesize - position)
+      end
+
+      # Appends the next chunk of the stream to the buffer.
+      # @return [Boolean] false at the end of the stream
+      def read_more
+        @buffer << @io.readpartial(CHUNK_BYTES).b
+        true
+      rescue EOFError
+        false
+      end
+    end
+  end
+end

data/lib/calcsheet/readers/xlsx/escapes.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Calcsheet
+  module Readers
+    module Xlsx
+      # The +_xHHHH_+ escapes OOXML uses in strings for characters XML cannot carry (control characters): HHHH is a
+      # UTF-16 code unit, so a character outside the BMP is a pair of escapes.
+      #
+      # @api private
+      module Escapes
+        # A surrogate pair of escapes (high, then low), or a single one.
+        PATTERN = /_x(D[89AB]\h\h)__x(D[C-F]\h\h)_|_x(\h{4})_/
+
+        module_function
+
+        # Decodes the escapes of +text+ in place; a lone surrogate stays as text, since it is not a character.
+        # @param text [String] a mutable UTF-8 string
+        # @return [String] +text+
+        def decode!(text)
+          text.gsub!(PATTERN) { decode(Regexp.last_match) } if text.include?("_x")
+          text
+        end
+
+        def decode(match)
+          if match[1]
+            ((match[1].hex - 0xD800) * 0x400 + (match[2].hex - 0xDC00) + 0x10000).chr(Encoding::UTF_8)
+          else
+            code = match[3].hex
+            code.between?(0xD800, 0xDFFF) ? match[0] : code.chr(Encoding::UTF_8)
+          end
+        end
+        private_class_method :decode
+      end
+    end
+  end
+end

data/lib/calcsheet/readers/xlsx/local_name.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Calcsheet
+  module Readers
+    module Xlsx
+      # Element and attribute names without their namespace prefix, because generators use other prefixes (+x:sheet+,
+      # +rel:id+). Read by bytes: a name may be ":" alone or end with ":" (an empty local name), which Ox's
+      # +strip_namespace+ refuses as damaged XML or drops, so the handlers that accept such names strip it here.
+      #
+      # @api private
+      module LocalName
+        module_function
+
+        # @param name [String, Symbol]
+        # @return [String] "" for a name that ends with ":"
+        def of(name)
+          name = name.to_s
+          colon = name.byterindex(":")
+          colon ? name.byteslice(colon + 1, name.bytesize - colon - 1) : name
+        end
+
+        # @param name [Symbol] a name as Ox symbolizes it
+        # @return [Symbol] +name+ itself when it has no prefix, so that the common name costs no String
+        def symbol(name)
+          text = name.name
+          colon = text.byterindex(":") or return name
+          text.byteslice(colon + 1, text.bytesize - colon - 1).to_sym
+        end
+
+        # The memo of local names of a SAX handler (+@local+): every name is noted the first time it comes, so that a
+        # document costs one Hash lookup per name, but only the first MEMO_ENTRIES names, so that the memo stays bounded
+        # whatever names a document holds. The handler reads +@local[name] || local_name(name)+. (Seeding the memo with
+        # the expected names was measured: no faster for unprefixed names, slower for prefixed ones, since Ruby looks
+        # up a Hash of up to 8 entries linearly.)
+        module Memo
+          # The names a memo keeps.
+          MEMO_ENTRIES = 64
+
+          private
+
+          def start_memo
+            @local = {}
+          end
+
+          def local_name(name)
+            local = LocalName.symbol(name)
+            @local[name] = local if @local.size < MEMO_ENTRIES
+            local
+          end
+        end
+      end
+    end
+  end
+end

data/lib/calcsheet/readers/xlsx/number_format.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Calcsheet
+  module Readers
+    module Xlsx
+      # Decides from a cell style's number format how a number is read: a plain number, a date, a datetime, a
+      # time or duration, or a zero-padded number. XLSX stores all of them as numbers; only the format tells them apart.
+      #
+      # @api private
+      module NumberFormat
+        # The built-in ids that are not general. Ids 14-17 and 22 are the dates and datetimes Excel defines, 18-21 and
+        # 45-47 are times and durations, and 27-36 and 50-58 are the date formats that depend on the locale (East Asian).
+        BUILT_IN = [
+          [ 14..17, :date ], [ 18..21, :time ], [ 22..22, :datetime ], [ 27..36, :date ], [ 45..47, :time ], [ 50..58, :date ]
+        ].each_with_object({}) { |(ids, kind), table| ids.each { |id| table[id] = kind } }.freeze
+
+        # The pieces of a format code: a quoted text, a backslash escape, spacing (_x) or fill (*x), a bracket section,
+        # a section separator or any other character.
+        ATOM = /"[^"]*"?|\\.|[_*].|\[[^\]]*\]?|;|./m
+        # A bracket of elapsed time: [h], [mm], [ss].
+        ELAPSED = /\A\[(?:h+|m+|s+)\]\z/i
+        # The AM/PM markers, read as a "p" (a time).
+        AM_PM = %r{am/pm|a/p}i
+        # A plain zero-padding format: two zeros or more and nothing else.
+        ONLY_ZEROS = /\A0{2,}\z/
+        # The letter runs that make a format a date (with an "m" that is a month).
+        DATE_LETTERS = %w[y d].freeze
+
+        class << self
+          # @param id [Integer] the +numFmtId+ of the cell style
+          # @param code [String, nil] the +formatCode+ of a custom format with that id; it wins over the built-in table
+          # @return [Array(Symbol, Integer | nil)] +:general+, +:date+, +:datetime+ or +:time+, and the width of a
+          #   zero-padding format (+00000+ gives +[:general, 5]+) or nil
+          def classify(id, code = nil)
+            return [ BUILT_IN.fetch(id, :general), nil ] if code.nil?
+
+            atoms = first_section(code)
+            return [ :general, atoms.join.length ] if atoms.join.match?(ONLY_ZEROS)
+
+            [ kind_of(atoms), nil ]
+          end
+
+          private
+
+          # The pieces of the code before its first unquoted ";".
+          def first_section(code)
+            code.scan(ATOM).take_while { _1 != ";" }
+          end
+
+          # The date and time letters left once quotes, escapes, spacing, fill and brackets are gone; an elapsed time
+          # bracket ([h], [mm], [ss]) stays as an h or an s.
+          def letters(atoms)
+            atoms.map { |atom| literal(atom) }.join.gsub(AM_PM, "p").downcase
+          end
+
+          def literal(atom)
+            case atom
+            when /\A["\\_*]/ then ""
+            when /\A\[/ then elapsed(atom)
+            else atom
+            end
+          end
+
+          def elapsed(atom)
+            return "" unless atom.match?(ELAPSED)
+
+            atom.downcase.start_with?("[s") ? "s" : "h"
+          end
+
+          def kind_of(atoms)
+            letters = letters(atoms)
+            runs = letters.scan(/y+|m+|d+|h+|s+/).map { _1[0] }
+            months = runs.each_index.select { |i| runs[i] == "m" && !minutes?(runs, i) }
+            date = months.any? || runs.intersect?(DATE_LETTERS)
+            time = letters.include?("p") || runs.intersect?(%w[h s]) || runs.count("m") > months.size
+            return :datetime if date && time
+
+            date ? :date : (time ? :time : :general)
+          end
+
+          # An m is minutes when the run before it is hours or the run after it is seconds; otherwise a month.
+          def minutes?(runs, index)
+            (index.positive? && runs[index - 1] == "h") || runs[index + 1] == "s"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/calcsheet/readers/xlsx/row_skipper.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require_relative "../../errors"
+require_relative "../stream_remainder"
+require_relative "../tag_scan"
+
+module Calcsheet
+  module Readers
+    module Xlsx
+      # Finds where a row starts in the inflated XML of a sheet without parsing it (+start_at:+): it scans the
+      # bytes for +<row+ start tags, with or without a namespace prefix, and reads their +r+ attribute. Rows before
+      # the wanted one cost a regexp scan, not a SAX callback per element. Comments, CDATA sections and processing
+      # instructions are passed over, so a +<row+ in their text is not taken for a row; a "<" inside the tag before a
+      # row start tag or a markup opening (in an attribute value: not XML, but Ox reads it as text) usually raises
+      # MalformedFileError (a tag cut by a chunk boundary may be passed over unchecked; ADR 008: the XML before the
+      # wanted row is assumed well-formed). An unescaped ">" inside an attribute value of a row start tag (legal XML
+      # that no known generator writes) would end the tag early.
+      #
+      # Every byte is scanned once and the buffer stays bounded: a row start tag may be at most MAX_TAG_BYTES long,
+      # other tags are passed over unbuffered whatever their length, and the text of a comment or CDATA section is
+      # dropped as it is read.
+      #
+      #   rest = RowSkipper.new(stream).skip_to(900) # => an IO beginning with '<row r="900"' (or a later row)
+      #
+      # @api private
+      class RowSkipper
+        include TagScan
+
+        # A start tag named row, with any prefix: "<row ", "<x:row>", "<row/>"; not "<rowBreaks" or "</row>"; or "<!"
+        # and "<?", which may open a comment, a CDATA section or a processing instruction. One character class for
+        # these keeps the scan as fast as one for row tags alone.
+        MARKUP = /<(?:[!?]|(?:[A-Za-z_][\w.-]*:)?row[\s>\/])/n
+        # The +r+ attribute of a row start tag.
+        NUMBER = /\sr\s*=\s*(?:"(\d+)"|'(\d+)')/n
+        # What may still become a row start tag or a markup opening at the end of the buffer: "<" and the name read so
+        # far, whatever the length of its namespace prefix; and the byte that ends such a name.
+        PARTIAL_NAME = /\G<[\w.:-]*\z/n
+        NAME_END = /[^\w.:-]/n
+
+        # The state of a scan: +@buffer+ holds the bytes read and not yet discarded (TagScan), +@last_row+ the number of
+        # the last row passed over (for errors), +@unnumbered+ whether a row without +r+ stopped the scan.
+        #
+        # @param io [#readpartial] the inflated sheet XML from its start; read forward only, never closed
+        # @param sheet [String, nil] the sheet name, for errors
+        def initialize(io, sheet: nil)
+          @io = io
+          @sheet = sheet
+          @unnumbered = false
+          @last_row = nil
+          @buffer = String.new(encoding: Encoding::BINARY)
+        end
+
+        # @return [Boolean] whether #skip_to met a row without +r+, so rows cannot be found by number
+        def unnumbered?
+          @unnumbered
+        end
+
+        # Discards the bytes before the start tag of the first row numbered +row+ or later.
+        #
+        # @param row [Integer] a row number
+        # @param prefix [String] binary bytes the rest of the stream is handed out after
+        # @param bound [LimitedInflater::TokenBound, nil] for the StreamRemainder
+        # @return [StreamRemainder, nil] +prefix+ and the rest of the stream from that start tag; nil when no such row
+        #   exists, or when a row without +r+ comes first (then #unnumbered? is true and the caller must parse from the
+        #   start)
+        # @raise [MalformedFileError] for a row start tag longer than MAX_TAG_BYTES
+        def skip_to(row, prefix: "".b, bound: nil)
+          from = 0
+          loop do
+            start = @buffer.byteindex(MARKUP, from)
+            if start.nil?
+              discard(partial_tag(from, PARTIAL_NAME))
+              return unless @buffer.match?(PARTIAL_NAME, 0) ? name_end : read_more
+
+              from = 0
+            elsif enclosing_tag?(from, start)
+              raise inside_attribute
+            elsif (markup = markup_at(start))
+              case markup
+              when :other then from = start + 1
+              when :incomplete
+                discard(start)
+                return unless read_more
+
+                from = 0
+              else from = skip_markup(start, *markup) or return
+              end
+            else
+              close = @buffer.byteindex(">", start)
+              unless close
+                discard(start)
+                start = 0
+                close = tag_end or return
+              end
+              raise too_long if close - start >= MAX_TAG_BYTES
+
+              number = row_number(@buffer.byteslice(start, close - start))
+              return unnumbered! if number.nil?
+              if number >= row
+                return StreamRemainder.new(prefix + @buffer.byteslice(start, @buffer.bytesize - start), @io, bound: bound)
+              end
+
+              @last_row = number
+              from = close + 1
+            end
+          end
+        end
+
+        private
+
+        def row_number(tag)
+          match = NUMBER.match(tag) or return
+          (match[1] || match[2]).to_i
+        end
+
+        def unnumbered!
+          @unnumbered = true
+          nil
+        end
+
+        # The buffer begins with a row start tag whose ">" has not been read: reads on until it, scanning each
+        # chunk once.
+        # @return [Integer, nil] the position of the ">"; nil when the stream ends first
+        # @raise [MalformedFileError] when the tag is already longer than MAX_TAG_BYTES (the caller checks the tag
+        #   that ends at the position returned)
+        def tag_end
+          loop do
+            from = @buffer.bytesize
+            raise too_long if from >= MAX_TAG_BYTES
+            return unless read_more
+
+            close = @buffer.byteindex(">", from)
+            return close if close
+          end
+        end
+
+        def too_long
+          located("a row start tag is longer than #{MAX_TAG_BYTES} bytes")
+        end
+
+        def located(message)
+          return MalformedFileError.at(message, sheet: @sheet, row: @last_row) if @sheet
+
+          MalformedFileError.new("the sheet#{", row #{@last_row}" if @last_row}: #{message}", row: @last_row)
+        end
+
+        # The buffer is "<" and what may be the beginning of a row start tag's name: reads on until the name ends,
+        # scanning each chunk once, so that the next scan of the buffer can tell whether it is a row.
+        # @return [Boolean] false when the stream ends first
+        # @raise [MalformedFileError] when the name alone is longer than MAX_TAG_BYTES
+        def name_end
+          loop do
+            from = @buffer.bytesize
+            raise long_name if from > MAX_TAG_BYTES
+            return false unless read_more
+            return true if @buffer.byteindex(NAME_END, from)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/calcsheet/readers/xlsx/shared_strings.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "ox"
+require_relative "../../configuration"
+require_relative "../../errors"
+require_relative "../ox_errors"
+require_relative "escapes"
+require_relative "local_name"
+require_relative "../references"
+
+module Calcsheet
+  module Readers
+    module Xlsx
+      # The shared strings table of an XLSX file (+xl/sharedStrings.xml+), kept compactly: the UTF-8 bytes of all
+      # strings in one binary buffer and the end offset of each string packed as 64-bit integers, so a million
+      # strings cost about their text plus 8 bytes each instead of a Ruby String (40+ bytes) apiece.
+      #
+      # Rich text runs are joined, phonetic runs (+rPh+) are skipped, whitespace is kept exactly, and the
+      # +_xHHHH_+ escapes OOXML uses for control characters are decoded.
+      #
+      # The offsets hold +size+ + 1 values: 0, then the end of each string, so string +i+ is the bytes from offset +i+
+      # to offset +i+ + 1 of the buffer. The strings are tagged UTF-8 as Ox hands them over, not validated: the reader
+      # of a cell checks the one it takes (SheetParser), so that a table is not checked in full for the strings a read
+      # never uses.
+      #
+      # @api private
+      class SharedStrings
+        # The pack directive of an offset: an unsigned 64-bit integer, native byte order (the table never leaves the
+        # process).
+        OFFSET_DIRECTIVE = "Q"
+        OFFSET_BYTES = 8
+        # The Builder joins the text in chunks of about this many bytes, and packs the offsets this many at a time.
+        CHUNK_BYTES = 1_048_576
+        OFFSETS_PER_CHUNK = 65_536
+
+        # @param io [#readpartial] the shared strings XML, for example +ZipContainer#stream+
+        # @param max_cell_bytes [Integer, nil] the longest string, as the XML parser hands its text over; nil for no
+        #   limit
+        # @return [SharedStrings]
+        # @raise [MalformedFileError] for damaged or empty XML (the parser or stream error is the +cause+) and for a
+        #   string longer than +max_cell_bytes+
+        # @raise [Calcsheet::Error] the error the stream itself raises, such as a ZipBombError (Ox wraps it in a
+        #   +TypeError+; it is raised again as itself)
+        def self.load(io, max_cell_bytes: Configuration::DEFAULTS[:max_cell_bytes])
+          builder = Builder.new(max_cell_bytes)
+          begin
+            # convert_special: false, so that the references reach the builder as written (see References).
+            Ox.sax_parse(builder, io, skip: :skip_none, convert_special: false, symbolize: true)
+          rescue *OxErrors::RAISED => error
+            OxErrors.raise_translated(error) { MalformedFileError.new("the shared strings cannot be parsed: #{_1}") }
+          end
+          builder.result
+        end
+
+        # @return [Integer] the number of strings
+        attr_reader :size
+
+        # @api private
+        # @return [Integer] the bytes of the decoded text of all strings (a test seam: the readers do not use it)
+        attr_reader :bytesize
+
+        # @api private
+        def initialize(buffer, offsets, size)
+          @buffer = buffer
+          @offsets = offsets
+          @size = size
+          @bytesize = buffer.bytesize
+        end
+
+        # @param index [Integer] the 0-based position of the string, the +v+ of a +t="s"+ cell
+        # @return [String] a new frozen String tagged UTF-8 (not validated)
+        # @raise [MalformedFileError] when the index is outside the table
+        def [](index)
+          unless index.is_a?(Integer) && index >= 0 && index < @size
+            raise MalformedFileError, "shared string #{index.inspect} is outside the table of #{@size} strings"
+          end
+
+          unchecked(index)
+        end
+
+        # @api private
+        # The string at an index the caller checked, as SheetParser does: without the checks of #[].
+        # @param index [Integer] 0 to +size+ - 1
+        # @return [String] a new frozen String tagged UTF-8 (not validated)
+        def unchecked(index)
+          position = index * OFFSET_BYTES
+          from = @offsets.unpack1(OFFSET_DIRECTIVE, offset: position)
+          to = @offsets.unpack1(OFFSET_DIRECTIVE, offset: position + OFFSET_BYTES)
+          @buffer.byteslice(from, to - from).force_encoding(Encoding::UTF_8).freeze
+        end
+
+        # Collects the strings while Ox streams the XML. Text and offsets go to chunks that are joined once at the
+        # end, so neither buffer keeps the spare capacity of a growing String.
+        # @api private
+        class Builder < Ox::Sax
+          include LocalName::Memo
+
+          # +@chunk+ collects the text of the strings, +@offsets+ the end offset of each (+@total+, the bytes so far);
+          # both move to +@chunks+ and +@offset_chunks+ when they reach CHUNK_BYTES and OFFSETS_PER_CHUNK. +@item+ is
+          # the string of the open +si+ (nil outside one), +@in_text+ whether a text belongs to it, +@phonetic+ the
+          # depth of +rPh+ runs, +@count+ the strings so far and +@any_element+ whether the document had an element.
+          def initialize(max_cell_bytes)
+            super()
+            start_memo
+            @max_cell_bytes = max_cell_bytes
+            @chunks = []
+            @chunk = +""
+            @offsets = []
+            @offset_chunks = []
+            @total = 0
+            @count = 0
+            @item = nil
+            @in_text = false
+            @phonetic = 0
+            @any_element = false
+            @offsets << 0
+          end
+
+          # Ox reports damaged XML here instead of raising.
+          def error(message, line, column)
+            raise MalformedFileError.new("the shared strings cannot be parsed: #{message} (line #{line})"),
+                  cause: OxErrors.parse_error(message, line, column)
+          end
+
+          # Ox's callbacks (start_element, end_element, text, cdata) collect the strings.
+          def start_element(name)
+            @any_element = true
+            case @local[name] || local_name(name)
+            when :si then @item = +""
+            when :rPh then @phonetic += 1 if @item
+            when :t then @in_text = true if @item && @phonetic.zero?
+            end
+          end
+
+          def end_element(name)
+            case @local[name] || local_name(name)
+            when :si then finish_item if @item
+            when :rPh then @phonetic -= 1 if @item && @phonetic.positive?
+            when :t then @in_text = false
+            end
+          end
+
+          def text(value)
+            return unless @in_text
+
+            value = References.line_ends(value) if value.include?("\r")
+            append(value.include?("&") ? references(value) : value)
+          end
+
+          def cdata(value)
+            append(value.include?("\r") ? References.line_ends(value) : value) if @in_text
+          end
+
+          # @return [SharedStrings]
+          # @raise [MalformedFileError] when the document has no element
+          def result
+            raise MalformedFileError, "the shared strings document is empty" unless @any_element
+
+            flush_chunk
+            flush_offsets
+            SharedStrings.new(@chunks.join.force_encoding(Encoding::BINARY), @offset_chunks.join, @count)
+          end
+
+          private
+
+          def references(value)
+            References.decode(value)
+          rescue References::Invalid => error
+            raise MalformedFileError, "the shared strings: shared string #{@count} holds #{error.message}"
+          end
+
+          # Measured before it is joined: a string longer than max_cell_bytes is never built.
+          def append(value)
+            if @max_cell_bytes && @item.bytesize + value.bytesize > @max_cell_bytes
+              raise MalformedFileError, "the shared strings: shared string #{@count} is longer than max_cell_bytes " \
+                                        "(#{@max_cell_bytes} bytes)"
+            end
+
+            @item << value
+          end
+
+          def finish_item
+            Escapes.decode!(@item)
+            @chunk << @item
+            @total += @item.bytesize
+            @offsets << @total
+            @count += 1
+            @item = nil
+            @in_text = false
+            @phonetic = 0
+            flush_chunk if @chunk.bytesize >= CHUNK_BYTES
+            flush_offsets if @offsets.size >= OFFSETS_PER_CHUNK
+          end
+
+          def flush_chunk
+            @chunks << @chunk
+            @chunk = +""
+          end
+
+          def flush_offsets
+            @offset_chunks << @offsets.pack("#{OFFSET_DIRECTIVE}*")
+            @offsets.clear
+          end
+        end
+        private_constant :Builder
+      end
+    end
+  end
+end