xsv 1.0.3 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 284b7b6ce94f03f8dfd74d77275a4ad2838f44bf9370a4ed2f5f6dba23ad513b
-  data.tar.gz: cc18f35656e7596c49c1f14e134071f12575204bb8237284cfbb49d2c924728f
+  metadata.gz: f1ebfa4e4778af72a8b295d258d899a5b5d01fd029d1294d54af5e4f1e0de05a
+  data.tar.gz: aa74ffe0d57eebc12e312bdb42107bc39203cd3a0237f2e2481205c8b3b933c9
 SHA512:
-  metadata.gz: 81ef3af200fb019556e1d5093bfc6f01457f0557c5314f088e707ba25274e74e0c90f914d3133de66a0fb27a398c5b1f8ad3e30d9c55f85772ad029160bfcd05
-  data.tar.gz: a4631f63c346ddfa449181d1e4de685eac9720f87ec296f0cd335e7487ad5ad8e9e973d1caf8893c37038b78f1665bdaeb853ada501f7b813dc8bda36e85c7b6
+  metadata.gz: 6ebbb32e48860043bdb0a5d17f6fef525252e8bb01ac63180cd0e749dfbd1b3bb08b8a82e43e9e13da2fa187c02f77e37f525e9c7453334bc3cb8fdf05400187
+  data.tar.gz: 4e1450daebcc3ddfbc0585de52f4d1f362ef2d79281e59cc641119a47924f8450b76c3643a6403a440e0a581ebfcc108431a311f902e2b48be61a1d2afd7b19e

data/.github/workflows/ruby.yml

@@ -0,0 +1,32 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.6', '2.7', '3.0', '3.1', 'jruby', 'truffleruby']
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rake

data/.standard.yml

@@ -0,0 +1 @@
+ruby_version: 2.6.9

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Xsv Changelog
 
+## 1.1.0 2022-02-13
+
+- New, shorter `Xsv.open` syntax as a drop-in replacement for `Xsv::Workbook.open`, which is still supported
+- Enable parsing of headers for all sheets by passing `parse_headers: true` to `Xsv.open`
+- Improvements in performance and test coverage
+- Dropped support for Ruby 2.5, which is EOL. Xsv 1.1.0 supports Ruby 2.6+, latest JRuby, latest TruffleRuby
+
+## 1.0.6 2022-01-07
+
+- Code cleanup, small performance improvements
+
+## 1.0.5 2022-01-05
+
+- Raise exception if given an empty buffer when opening workbook (thanks @kevin-j-m)
+
+## 1.0.4 2021-07-05
+
+- Support for custom date/time columns
+
 ## 1.0.3 2021-05-06
 
 - Handle nil number formats correctly (regression in Xsv 1.0.2, #29)

data/README.md

@@ -1,10 +1,11 @@
 # Xsv .xlsx reader
 
 [![Travis CI](https://img.shields.io/travis/martijn/xsv/master)](https://travis-ci.org/martijn/xsv)
+[![Codecov](https://img.shields.io/codecov/c/github/martijn/xsv/main)](https://app.codecov.io/gh/martijn/xsv)
 [![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/github/martijn/xsv)
 [![Gem Version](https://badge.fury.io/rb/xsv.svg)](https://badge.fury.io/rb/xsv)
 
-Xsv is a fast, lightweight, pure Ruby parser for Office Open XML spreadsheet files
+Xsv is a fast, lightweight, pure Ruby parser for ISO/IEC 29500 Office Open XML spreadsheet files
 (commonly known as Excel or .xlsx files). It strives to be minimal in the
 sense that it provides nothing a CSV reader wouldn't, meaning it only
 deals with minimal formatting and cannot create or modify documents.
@@ -41,17 +42,18 @@ when that becomes stable.
 
 ## Usage
 
+### Array and hash mode
 Xsv has two modes of operation. By default, it returns an array for
 each row in the sheet:
 
 ```ruby
-x = Xsv::Workbook.open("sheet.xlsx")
+x = Xsv.open("sheet.xlsx") # => #<Xsv::Workbook sheets=1>
 
 sheet = x.sheets[0]
 
 # Iterate over rows
-sheet.each_row do |row|
-  row # => ["header1", "header2"], etc.
+sheet.each do |row|
+  row # => ["header1", "header2"]
 end
 
 # Access row by index (zero-based)
@@ -59,40 +61,63 @@ sheet[1] # => ["value1", "value2"]
 ```
 
 Alternatively, it can load the headers from the first row and return a hash
-for every row:
+for every row by calling `parse_headers!` on the sheet or setting the `parse_headers`
+option on open:
 
 ```ruby
-x = Xsv::Workbook.open("sheet.xlsx")
+# Parse headers for all sheets on open
+
+x = Xsv.open("sheet.xlsx", parse_headers: true)
+
+x.sheets[0][1]   # => {"header1" => "value1", "header2" => "value2"}
+
+# Manually parse headers for a single sheet
+
+x = Xsv.open("sheet.xlsx")
 
 sheet = x.sheets[0]
 
-sheet.mode # => :array
+sheet[0]  # => ["header1", "header2"]
 
-# Parse headers and switch to hash mode
 sheet.parse_headers!
 
-sheet.mode # => :hash
+sheet[0] # => {"header1" => "value1", "header2" => "value2"}
+```
+
+Be aware that hash mode will lead to unpredictable results if the worksheet
+has multiple columns with the same header. `Xsv::Sheet` implements `Enumerable` so along with `#each`
+you can call methods like `#first`, `#filter`/`#select`, and `#map` on it.
+
+### Opening a string or buffer instead of filename
 
-sheet.each_row do |row|
-  row # => {"header1" => "value1", "header2" => "value2"}, etc.
+`Xsv.open` accepts a filename, or an IO or String containing a workbook. Optionally, you can pass a block
+which will be called with the workbook as parameter, like `File#open`. Example of this together:
+
+```ruby
+# Use an existing IO-like object as source
+
+file = File.open("sheet.xlsx")
+
+Xsv.open(file) do |workbook|
+  puts workbook.inspect
 end
 
-sheet[1] # => {"header1" => "value1", "header2" => "value2"}
-```
+# or even:
 
-Be aware that hash mode will lead to unpredictable results if the worksheet
-has multiple columns with the same header.
+Xsv.open(file.read) do |workbook|
+  puts workbook.inspect
+end
+```
 
-`Xsv::Workbook.open` accepts a filename, or an IO or String containing a workbook. Optionally, you can pass a block
-which will be called with the workbook as parameter, like `File#open`.
+Prior to Xsv 1.1.0, `Xsv::Workbook.open` was used instead of `Xsv.open`. The parameters are identical and
+the former is maintained for backwards compatibility.
 
-`Xsv::Sheet` implements `Enumerable` so you can call methods like `#first`,
-`#filter`/`#select`, and `#map` on it.
+### Accessing sheets by name
 
 The sheets can be accessed by index or by name:
 
 ```ruby
-x = Xsv::Workbook.open("sheet.xlsx")
+x = Xsv.open("sheet.xlsx")
 
 sheet = x.sheets[0] # gets sheet by index
 

data/Rakefile

@@ -13,4 +13,4 @@ Rake::TestTask.new(:bench) do |t|
   t.test_files = FileList["test/**/*_benchmark.rb"]
 end
 
-task :default => [:test, :bench]
+task default: [:test, :bench]

data/benchmark.rb

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+
+require "bundler/inline"
+
+gemfile do
+  source "https://rubygems.org"
+
+  gemspec
+  gem "benchmark-memory"
+  gem "benchmark-perf"
+end
+
+def bench_perf(sheet)
+  result = Benchmark::Perf.cpu(repeat: 5) do
+    sheet.each do |row|
+      row.each do |cell|
+        cell
+      end
+    end
+  end
+
+  puts "Performance benchmark: #{result.avg}s avg #{result.stdev}s stdev"
+end
+
+def bench_mem(sheet)
+  Benchmark.memory do |bm|
+    bm.report do
+      sheet.each do |row|
+        row.each do |cell|
+          cell
+        end
+      end
+    end
+  end
+end
+
+file = File.read("test/files/10k-sheet.xlsx")
+
+workbook = Xsv.open(file)
+
+puts "--- ARRAY MODE ---"
+
+bench_perf(workbook.sheets[0])
+bench_mem(workbook.sheets[0])
+
+puts "\n--- HASH MODE ---"
+
+workbook.sheets[0].parse_headers!
+
+bench_perf(workbook.sheets[0])
+bench_mem(workbook.sheets[0])

data/lib/xsv/helpers.rb

@@ -5,42 +5,42 @@ module Xsv
     # The default OOXML Spreadheet number formats according to the ECMA standard
     # User formats are appended from index 174 onward
     BUILT_IN_NUMBER_FORMATS = {
-      1 => '0',
-      2 => '0.00',
-      3 => '#, ##0',
-      4 => '#, ##0.00',
-      5 => '$#, ##0_);($#, ##0)',
-      6 => '$#, ##0_);[Red]($#, ##0)',
-      7 => '$#, ##0.00_);($#, ##0.00)',
-      8 => '$#, ##0.00_);[Red]($#, ##0.00)',
-      9 => '0%',
-      10 => '0.00%',
-      11 => '0.00E+00',
-      12 => '# ?/?',
-      13 => '# ??/??',
-      14 => 'm/d/yyyy',
-      15 => 'd-mmm-yy',
-      16 => 'd-mmm',
-      17 => 'mmm-yy',
-      18 => 'h:mm AM/PM',
-      19 => 'h:mm:ss AM/PM',
-      20 => 'h:mm',
-      21 => 'h:mm:ss',
-      22 => 'm/d/yyyy h:mm',
-      37 => '#, ##0_);(#, ##0)',
-      38 => '#, ##0_);[Red](#, ##0)',
-      39 => '#, ##0.00_);(#, ##0.00)',
-      40 => '#, ##0.00_);[Red](#, ##0.00)',
-      45 => 'mm:ss',
-      46 => '[h]:mm:ss',
-      47 => 'mm:ss.0',
-      48 => '##0.0E+0',
-      49 => '@'
+      1 => "0",
+      2 => "0.00",
+      3 => "#, ##0",
+      4 => "#, ##0.00",
+      5 => "$#, ##0_);($#, ##0)",
+      6 => "$#, ##0_);[Red]($#, ##0)",
+      7 => "$#, ##0.00_);($#, ##0.00)",
+      8 => "$#, ##0.00_);[Red]($#, ##0.00)",
+      9 => "0%",
+      10 => "0.00%",
+      11 => "0.00E+00",
+      12 => "# ?/?",
+      13 => "# ??/??",
+      14 => "m/d/yyyy",
+      15 => "d-mmm-yy",
+      16 => "d-mmm",
+      17 => "mmm-yy",
+      18 => "h:mm AM/PM",
+      19 => "h:mm:ss AM/PM",
+      20 => "h:mm",
+      21 => "h:mm:ss",
+      22 => "m/d/yyyy h:mm",
+      37 => "#, ##0_);(#, ##0)",
+      38 => "#, ##0_);[Red](#, ##0)",
+      39 => "#, ##0.00_);(#, ##0.00)",
+      40 => "#, ##0.00_);[Red](#, ##0.00)",
+      45 => "mm:ss",
+      46 => "[h]:mm:ss",
+      47 => "mm:ss.0",
+      48 => "##0.0E+0",
+      49 => "@"
     }.freeze
 
     MINUTE = 60
     HOUR = 3600
-    A_CODEPOINT = 'A'.ord.freeze
+    A_CODEPOINT = "A".ord.freeze
     # The epoch for all dates in OOXML Spreadsheet documents
     EPOCH = Date.new(1899, 12, 30).freeze
 
@@ -74,7 +74,7 @@ module Xsv
         minutes = minutes % 60
       end
 
-      format('%02d:%02d', hours, minutes)
+      format("%02d:%02d", hours, minutes)
     end
 
     # Returns a time including a date as a {Time} object
@@ -92,9 +92,9 @@ module Xsv
 
     # Returns a number as either Integer or Float
     def parse_number(string)
-      if string.include? '.'
+      if string.include? "."
         string.to_f
-      elsif string.include? 'E'
+      elsif string.include? "E"
         Complex(string).to_f
       else
         string.to_i

data/lib/xsv/relationships_handler.rb

@@ -17,7 +17,7 @@ module Xsv
     end
 
     def start_element(name, attrs)
-      @block.call(attrs.slice(:Id, :Type, :Target)) if name == 'Relationship'
+      @block.call(attrs.slice(:Id, :Type, :Target)) if name == "Relationship"
     end
   end
 end

data/lib/xsv/sax_parser.rb

@@ -5,6 +5,9 @@ module Xsv
     ATTR_REGEX = /((\S+)="(.*?)")/m
 
     def parse(io)
+      responds_to_end_element = respond_to?(:end_element)
+      responds_to_characters = respond_to?(:characters)
+
       state = :look_start
       if io.is_a?(String)
         pbuf = io.dup
@@ -29,16 +32,16 @@ module Xsv
         end
 
         if state == :look_start
-          if (o = pbuf.index('<'))
-            chars = pbuf.slice!(0, o + 1).chop!.force_encoding('utf-8')
+          if (o = pbuf.index("<"))
+            chars = pbuf.slice!(0, o + 1).chop!.force_encoding("utf-8")
 
-            if respond_to?(:characters) && !chars.empty?
-              if chars.index('&')
-                chars.gsub!('&amp;', '&')
-                chars.gsub!('&apos;', "'")
-                chars.gsub!('&gt;', '>')
-                chars.gsub!('&lt;', '<')
-                chars.gsub!('&quot;', '"')
+            if responds_to_characters && !chars.empty?
+              if chars.index("&")
+                chars.gsub!("&amp;", "&")
+                chars.gsub!("&apos;", "'")
+                chars.gsub!("&gt;", ">")
+                chars.gsub!("&lt;", "<")
+                chars.gsub!("&quot;", '"')
               end
               characters(chars)
             end
@@ -55,8 +58,8 @@ module Xsv
         end
 
         if state == :look_end
-          if (o = pbuf.index('>'))
-            if (s = pbuf.index(' ')) && s < o
+          if (o = pbuf.index(">"))
+            if (s = pbuf.index(" ")) && s < o
               tag_name = pbuf.slice!(0, s + 1).chop!
               args = pbuf.slice!(0, o - s)
             else
@@ -64,18 +67,18 @@ module Xsv
               args = nil
             end
 
-            if tag_name.start_with?('/')
-              end_element(tag_name[1..-1]) if respond_to?(:end_element)
+            if tag_name.start_with?("/")
+              end_element(tag_name[1..]) if responds_to_end_element
             elsif args.nil?
               start_element(tag_name, nil)
             else
               start_element(tag_name, args.scan(ATTR_REGEX).each_with_object({}) { |m, h| h[m[1].to_sym] = m[2] })
-              end_element(tag_name) if args.end_with?('/') && respond_to?(:end_element)
+              end_element(tag_name) if responds_to_end_element && args.end_with?("/")
             end
 
             state = :look_start
           elsif eof_reached
-            raise 'Malformed XML document, looking for end of tag beyond EOF'
+            raise Xsv::Error, "Malformed XML document, looking for end of tag beyond EOF"
           else
             must_read = true
           end

data/lib/xsv/shared_strings_parser.rb

@@ -18,29 +18,29 @@ module Xsv
 
     def start_element(name, _attrs)
       case name
-      when 'si'
-        @current_string = ''
+      when "si"
+        @current_string = ""
         @skip = false
-      when 'rPh'
+      when "rPh"
         @skip = true
-      when 't'
+      when "t"
         @state = name
       end
     end
 
     def characters(value)
-      if @state == 't' && !@skip
+      if @state == "t" && !@skip
         @current_string += value
       end
     end
 
     def end_element(name)
       case name
-      when 'si'
+      when "si"
         @block.call(@current_string)
-      when 'rPh'
+      when "rPh"
         @skip = false
-      when 't'
+      when "t"
         @state = nil
       end
     end

data/lib/xsv/sheet.rb

@@ -40,14 +40,14 @@ module Xsv
       @headers = []
       @mode = :array
       @row_skip = 0
-      @hidden = ids[:state] == 'hidden'
+      @hidden = ids[:state] == "hidden"
 
       @last_row, @column_count = SheetBoundsHandler.get_bounds(@io, @workbook)
     end
 
     # @return [String]
     def inspect
-      "#<#{self.class.name}:#{object_id}>"
+      "#<#{self.class.name}:#{object_id} mode=#{@mode}>"
     end
 
     # Returns true if the worksheet is hidden
@@ -66,7 +66,7 @@ module Xsv
       true
     end
 
-    alias each each_row
+    alias_method :each, :each_row
 
     # Get row by number, starting at 0. Returns either a hash or an array based on the current row.
     # If the specified index is out of bounds an empty row is returned.

data/lib/xsv/sheet_bounds_handler.rb

@@ -30,40 +30,40 @@ module Xsv
       @state = nil
       @cell = nil
       @row = nil
-      @maxRow = 0
-      @maxColumn = 0
+      @max_row = 0
+      @max_column = 0
       @trim_empty_rows = trim_empty_rows
     end
 
     def start_element(name, attrs)
       case name
-      when 'c'
+      when "c"
         @state = name
         @cell = attrs[:r]
-      when 'v'
+      when "v"
         col = column_index(@cell)
-        @maxColumn = col if col > @maxColumn
-        @maxRow = @row if @row > @maxRow
-      when 'row'
+        @max_column = col if col > @max_column
+        @max_row = @row if @row > @max_row
+      when "row"
         @state = name
         @row = attrs[:r].to_i
-      when 'dimension'
+      when "dimension"
         @state = name
 
-        _firstCell, lastCell = attrs[:ref].split(':')
+        _first_cell, last_cell = attrs[:ref].split(":")
 
-        if lastCell
-          @maxColumn = column_index(lastCell)
+        if last_cell
+          @max_column = column_index(last_cell)
           unless @trim_empty_rows
-            @maxRow = lastCell[/\d+$/].to_i
-            @block.call(@maxRow, @maxColumn)
+            @max_row = last_cell[/\d+$/].to_i
+            @block.call(@max_row, @max_column)
           end
         end
       end
     end
 
     def end_element(name)
-      @block.call(@maxRow, @maxColumn) if name == 'sheetData'
+      @block.call(@max_row, @max_column) if name == "sheetData"
     end
   end
 end

data/lib/xsv/sheet_rows_handler.rb

@@ -14,58 +14,50 @@ module Xsv
       @last_row = last_row - @row_skip
       @block = block
 
-      @state = nil
+      @store_characters = false
 
       @row_index = 0
       @current_row = {}
-      @current_row_attrs = {}
+      @current_row_number = 0
       @current_cell = {}
-      @current_value = String.new
+      @current_value = +""
 
       @headers = @empty_row.keys if @mode == :hash
     end
 
     def start_element(name, attrs)
       case name
-      when 'c'
-        @state = name
+      when "c"
         @current_cell = attrs
         @current_value.clear
-      when 'v', 'is'
-        @state = name
-      when 'row'
-        @state = name
+      when "v", "is", "t"
+        @store_characters = true
+      when "row"
         @current_row = @empty_row.dup
-        @current_row_attrs = attrs
-      when 't'
-        @state = nil unless @state == 'is'
-      else
-        @state = nil
+        @current_row_number = attrs[:r].to_i
       end
     end
 
     def characters(value)
-      @current_value << value if @state == 'v' || @state == 'is'
+      @current_value << value if @store_characters
     end
 
     def end_element(name)
       case name
-      when 'v'
-        @state = nil
-      when 'c'
+      when "v", "is", "t"
+        @store_characters = false
+      when "c"
         col_index = column_index(@current_cell[:r])
 
-        case @mode
-        when :array
+        if @mode == :array
           @current_row[col_index] = format_cell
-        when :hash
+        else
           @current_row[@headers[col_index]] = format_cell
         end
-      when 'row'
-        real_row_number = @current_row_attrs[:r].to_i
-        adjusted_row_number = real_row_number - @row_skip
+      when "row"
+        return if @current_row_number <= @row_skip
 
-        return if real_row_number <= @row_skip
+        adjusted_row_number = @current_row_number - @row_skip
 
         @row_index += 1
 
@@ -90,23 +82,22 @@ module Xsv
       return nil if @current_value.empty?
 
       case @current_cell[:t]
-      when 's'
+      when "s"
         @workbook.shared_strings[@current_value.to_i]
-      when 'str', 'inlineStr'
+      when "str", "inlineStr"
         @current_value.strip
-      when 'e' # N/A
+      when "e" # N/A
         nil
-      when nil, 'n'
+      when nil, "n"
         if @current_cell[:s]
-          style = @workbook.xfs[@current_cell[:s].to_i]
-          numFmt = @workbook.numFmts[style[:numFmtId].to_i]
-
-          parse_number_format(@current_value, numFmt)
+          parse_number_format(@current_value, @workbook.get_num_fmt(@current_cell[:s].to_i))
         else
           parse_number(@current_value)
         end
-      when 'b'
-        @current_value == '1'
+      when "b"
+        @current_value == "1"
+      when "d"
+        DateTime.parse(@current_value)
       else
         raise Xsv::Error, "Encountered unknown column type #{@current_cell[:t]}"
       end

data/lib/xsv/sheets_ids_handler.rb

@@ -17,7 +17,7 @@ module Xsv
     end
 
     def start_element(name, attrs)
-      @block.call(attrs.slice(:name, :sheetId, :state, :'r:id')) if name == 'sheet'
+      @block.call(attrs.slice(:name, :sheetId, :state, :'r:id')) if name == "sheet"
     end
   end
 end

data/lib/xsv/styles_handler.rb

@@ -5,39 +5,39 @@ module Xsv
   # This is used internally when opening a sheet.
   class StylesHandler < SaxParser
     def self.get_styles(io)
-      handler = new(Xsv::Helpers::BUILT_IN_NUMBER_FORMATS.dup) do |xfs, numFmts|
+      handler = new(Xsv::Helpers::BUILT_IN_NUMBER_FORMATS.dup) do |xfs, num_fmts|
         @xfs = xfs
-        @numFmts = numFmts
+        @num_fmts = num_fmts
       end
 
       handler.parse(io)
 
-      [@xfs, @numFmts]
+      [@xfs, @num_fmts]
     end
 
-    def initialize(numFmts, &block)
+    def initialize(num_fmts, &block)
       @block = block
       @state = nil
       @xfs = []
-      @numFmts = numFmts
+      @num_fmts = num_fmts
     end
 
     def start_element(name, attrs)
       case name
-      when 'cellXfs'
-        @state = 'cellXfs'
-      when 'xf'
-        @xfs << attrs if @state == 'cellXfs'
-      when 'numFmt'
-        @numFmts[attrs[:numFmtId].to_i] = attrs[:formatCode]
+      when "cellXfs"
+        @state = "cellXfs"
+      when "xf"
+        @xfs << attrs.transform_values(&:to_i) if @state == "cellXfs"
+      when "numFmt"
+        @num_fmts[attrs[:numFmtId].to_i] = attrs[:formatCode]
       end
     end
 
     def end_element(name)
       case name
-      when 'styleSheet'
-        @block.call(@xfs, @numFmts)
-      when 'cellXfs'
+      when "styleSheet"
+        @block.call(@xfs, @num_fmts)
+      when "cellXfs"
         @state = nil
       end
     end

data/lib/xsv/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Xsv
-  VERSION = '1.0.3'
+  VERSION = "1.1.0"
 end

data/lib/xsv/workbook.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'zip'
+require "zip"
 
 module Xsv
   # An OOXML Spreadsheet document is called a Workbook. A Workbook consists of
@@ -10,54 +10,36 @@ module Xsv
     # @return [Array<Sheet>]
     attr_reader :sheets
 
-    attr_reader :shared_strings, :xfs, :numFmts, :trim_empty_rows
-
-    # Open the workbook of the given filename, string or buffer. For additional
-    # options see {.initialize}
-    def self.open(data, **kws)
-      @workbook = if data.is_a?(IO) || data.respond_to?(:read) # is it a buffer?
-                    new(Zip::File.open_buffer(data), **kws)
-                  elsif data.start_with?("PK\x03\x04") # is it a string containing a file?
-                    new(Zip::File.open_buffer(data), **kws)
-                  else # must be a filename
-                    new(Zip::File.open(data), **kws)
-                  end
-
-      if block_given?
-        begin
-          yield(@workbook)
-        ensure
-          @workbook.close
-        end
-      else
-        @workbook
-      end
+    attr_reader :shared_strings, :xfs, :num_fmts, :trim_empty_rows
+
+    # @deprecated Use {Xsv.open} instead
+    def self.open(data, **kws, &block)
+      Xsv.open(data, **kws, &block)
     end
 
     # Open a workbook from an instance of {Zip::File}. Generally it's recommended
     # to use the {.open} method instead of the constructor.
     #
-    # Options:
-    #
-    #    trim_empty_rows (false) Scan sheet for end of content and don't return trailing rows
-    #
-    def initialize(zip, trim_empty_rows: false)
+    # @param trim_empty_rows [Boolean] Scan sheet for end of content and don't return trailing rows
+    # @param parse_headers [Boolean] Call `parse_headers!` on all sheets on load
+    def initialize(zip, trim_empty_rows: false, parse_headers: false)
       raise ArgumentError, "Passed argument is not an instance of Zip::File. Did you mean to use Workbook.open?" unless zip.is_a?(Zip::File)
+      raise Xsv::Error, "Zip::File is empty" if zip.size.zero?
 
       @zip = zip
       @trim_empty_rows = trim_empty_rows
 
       @sheets = []
-      @xfs, @numFmts = fetch_styles
+      @xfs, @num_fmts = fetch_styles
       @sheet_ids = fetch_sheet_ids
       @relationships = fetch_relationships
       @shared_strings = fetch_shared_strings
-      @sheets = fetch_sheets
+      @sheets = fetch_sheets(parse_headers ? :hash : :array)
     end
 
     # @return [String]
     def inspect
-      "#<#{self.class.name}:#{object_id}>"
+      "#<#{self.class.name}:#{object_id} sheets=#{sheets.count} trim_empty_rows=#{@trim_empty_rows}>"
     end
 
     # Close the handle to the workbook file and leave all resources for the GC to collect
@@ -67,7 +49,7 @@ module Xsv
       @zip = nil
       @sheets = nil
       @xfs = nil
-      @numFmts = nil
+      @num_fmts = nil
       @relationships = nil
       @shared_strings = nil
       @sheet_ids = nil
@@ -82,10 +64,15 @@ module Xsv
       @sheets.select { |s| s.name == name }
     end
 
+    # Get number format for given style index
+    def get_num_fmt(style)
+      @num_fmts[@xfs[style][:numFmtId]]
+    end
+
     private
 
     def fetch_shared_strings
-      handle = @zip.glob('xl/sharedStrings.xml').first
+      handle = @zip.glob("xl/sharedStrings.xml").first
       return if handle.nil?
 
       stream = handle.get_input_stream
@@ -95,32 +82,34 @@ module Xsv
     end
 
     def fetch_styles
-      stream = @zip.glob('xl/styles.xml').first.get_input_stream
+      stream = @zip.glob("xl/styles.xml").first.get_input_stream
 
       StylesHandler.get_styles(stream)
     ensure
       stream.close
     end
 
-    def fetch_sheets
-      @zip.glob('xl/worksheets/sheet*.xml').sort do |a, b|
+    def fetch_sheets(mode)
+      @zip.glob("xl/worksheets/sheet*.xml").sort do |a, b|
         a.name[/\d+/].to_i <=> b.name[/\d+/].to_i
       end.map do |entry|
-        rel = @relationships.detect { |r| entry.name.end_with?(r[:Target]) && r[:Type].end_with?('worksheet') }
+        rel = @relationships.detect { |r| entry.name.end_with?(r[:Target]) && r[:Type].end_with?("worksheet") }
         sheet_ids = @sheet_ids.detect { |i| i[:"r:id"] == rel[:Id] }
-        Xsv::Sheet.new(self, entry.get_input_stream, entry.size, sheet_ids)
+        Xsv::Sheet.new(self, entry.get_input_stream, entry.size, sheet_ids).tap do |sheet|
+          sheet.parse_headers! if mode == :hash
+        end
       end
     end
 
     def fetch_sheet_ids
-      stream = @zip.glob('xl/workbook.xml').first.get_input_stream
+      stream = @zip.glob("xl/workbook.xml").first.get_input_stream
       SheetsIdsHandler.get_sheets_ids(stream)
     ensure
       stream.close
     end
 
     def fetch_relationships
-      stream = @zip.glob('xl/_rels/workbook.xml.rels').first.get_input_stream
+      stream = @zip.glob("xl/_rels/workbook.xml.rels").first.get_input_stream
       RelationshipsHandler.get_relations(stream)
     ensure
       stream.close

data/lib/xsv.rb

@@ -1,18 +1,18 @@
 # frozen_string_literal: true
 
-require 'date'
+require "date"
 
-require 'xsv/helpers'
-require 'xsv/sax_parser'
-require 'xsv/relationships_handler'
-require 'xsv/shared_strings_parser'
-require 'xsv/sheet'
-require 'xsv/sheet_bounds_handler'
-require 'xsv/sheet_rows_handler'
-require 'xsv/sheets_ids_handler'
-require 'xsv/styles_handler'
-require 'xsv/version'
-require 'xsv/workbook'
+require "xsv/helpers"
+require "xsv/sax_parser"
+require "xsv/relationships_handler"
+require "xsv/shared_strings_parser"
+require "xsv/sheet"
+require "xsv/sheet_bounds_handler"
+require "xsv/sheet_rows_handler"
+require "xsv/sheets_ids_handler"
+require "xsv/styles_handler"
+require "xsv/version"
+require "xsv/workbook"
 
 # XSV is a fast, lightweight parser for Office Open XML spreadsheet files
 # (commonly known as Excel or .xlsx files). It strives to be minimal in the
@@ -24,4 +24,31 @@ module Xsv
   # An AssertionFailed error indicates an unexpected condition, meaning a bug
   # or misinterpreted .xlsx document
   class AssertionFailed < StandardError; end
+
+  # Open the workbook of the given filename, string or buffer.
+  # @param filename_or_string [String, IO] the contents or filename of a workbook
+  # @param trim_empty_rows [Boolean] Scan sheet for end of content and don't return trailing rows
+  # @param parse_headers [Boolean] Call `parse_headers!` on all sheets on load
+  # @return [Xsv::Workbook] The workbook instance
+  def self.open(filename_or_string, trim_empty_rows: false, parse_headers: false)
+    zip = if filename_or_string.is_a?(IO) || filename_or_string.respond_to?(:read) # is it a buffer?
+      Zip::File.open_buffer(filename_or_string)
+    elsif filename_or_string.start_with?("PK\x03\x04") # is it a string containing a file?
+      Zip::File.open_buffer(filename_or_string)
+    else # must be a filename
+      Zip::File.open(filename_or_string)
+    end
+
+    workbook = Xsv::Workbook.new(zip, trim_empty_rows: trim_empty_rows, parse_headers: parse_headers)
+
+    if block_given?
+      begin
+        yield(workbook)
+      ensure
+        workbook.close
+      end
+    else
+      workbook
+    end
+  end
 end

data/xsv.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
                             (commonly known as Excel or .xlsx files). It strives to be minimal in the
                             sense that it provides nothing a CSV reader wouldn't, meaning it only
                             deals with minimal formatting and cannot create or modify documents.
-                          EOF
+  EOF
   spec.homepage = "https://github.com/martijn/xsv"
   spec.license = "MIT"
 
@@ -36,11 +36,13 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = ">= 2.5"
+  spec.required_ruby_version = ">= 2.6"
 
   spec.add_dependency "rubyzip", ">= 1.3", "< 3"
 
   spec.add_development_dependency "bundler", "< 3"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "minitest", "~> 5.14.2"
+  spec.add_development_dependency "standard", "~> 1.6.0"
+  spec.add_development_dependency "codecov", ">= 0.6.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xsv
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.1.0
 platform: ruby
 authors:
 - Martijn Storck
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-05-06 00:00:00.000000000 Z
+date: 2022-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubyzip
@@ -72,6 +72,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 5.14.2
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.6.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.6.0
+- !ruby/object:Gem::Dependency
+  name: codecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.0
 description: |2
                               Xsv is a fast, lightweight parser for Office Open XML spreadsheet files
                               (commonly known as Excel or .xlsx files). It strives to be minimal in the
@@ -83,13 +111,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ruby.yml"
 - ".gitignore"
-- ".travis.yml"
+- ".standard.yml"
 - CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- benchmark.rb
 - bin/console
 - bin/setup
 - lib/xsv.rb
@@ -120,14 +150,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.15
+rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
 summary: A fast and lightweight xlsx parser that provides nothing a CSV parser wouldn't

data/.travis.yml

@@ -1,10 +0,0 @@
----
-sudo: false
-language: ruby
-cache: bundler
-rvm:
-  - 2.5.8
-  - 3.0
-  - truffleruby
-  - jruby
-before_install: gem install bundler