xsv 1.0.6 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0755959285e8f4e588fc8f72f45c48904bc0b840c1abc7b250faf6bad978e7f0'
-  data.tar.gz: 482143461be2e72994e8d9758d1a971e87355acdd16cb027a5631956b7898927
+  metadata.gz: f1ebfa4e4778af72a8b295d258d899a5b5d01fd029d1294d54af5e4f1e0de05a
+  data.tar.gz: aa74ffe0d57eebc12e312bdb42107bc39203cd3a0237f2e2481205c8b3b933c9
 SHA512:
-  metadata.gz: a9a48303c59d254233e12994562a341854caffde500f78e5357edebfd16dca12cf7b9b39af6c3c9e1536491f1467456c0b8295bfebf4fddda0f315ab4fbe0875
-  data.tar.gz: db9fe14a1c829ca66d2d1daa59da9bab181c5b4ba17c89ebc0703369165310ad4390e8713effc329d0ad6ce9f932a822e368b7eec6ae1e3876b4ed27d4bc0969
+  metadata.gz: 6ebbb32e48860043bdb0a5d17f6fef525252e8bb01ac63180cd0e749dfbd1b3bb08b8a82e43e9e13da2fa187c02f77e37f525e9c7453334bc3cb8fdf05400187
+  data.tar.gz: 4e1450daebcc3ddfbc0585de52f4d1f362ef2d79281e59cc641119a47924f8450b76c3643a6403a440e0a581ebfcc108431a311f902e2b48be61a1d2afd7b19e

data/.github/workflows/ruby.yml

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['2.5', '2.6', '2.7', '3.0', '3.1', 'jruby', 'truffleruby']
+        ruby-version: ['2.6', '2.7', '3.0', '3.1', 'jruby', 'truffleruby']
 
     steps:
     - uses: actions/checkout@v2

data/.standard.yml

@@ -1 +1 @@
-ruby_version: 2.5.0
+ruby_version: 2.6.9

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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

data/README.md

@@ -1,6 +1,7 @@
 # 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)
 
@@ -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/benchmark.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-require 'bundler/inline'
+require "bundler/inline"
 
 gemfile do
   source "https://rubygems.org"
@@ -36,7 +36,7 @@ end
 
 file = File.read("test/files/10k-sheet.xlsx")
 
-workbook = Xsv::Workbook.open(file)
+workbook = Xsv.open(file)
 
 puts "--- ARRAY MODE ---"
 

data/lib/xsv/sax_parser.rb

@@ -68,7 +68,7 @@ module Xsv
             end
 
             if tag_name.start_with?("/")
-              end_element(tag_name[1..-1]) if responds_to_end_element
+              end_element(tag_name[1..]) if responds_to_end_element
             elsif args.nil?
               start_element(tag_name, nil)
             else
@@ -78,7 +78,7 @@ module Xsv
 
             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/sheet.rb

@@ -47,7 +47,7 @@ module Xsv
 
     # @return [String]
     def inspect
-      "#<#{self.class.name}:#{object_id}>"
+      "#<#{self.class.name}:#{object_id} mode=#{@mode}>"
     end
 
     # Returns true if the worksheet is hidden

data/lib/xsv/version.rb

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

data/lib/xsv/workbook.rb

@@ -12,36 +12,17 @@ module Xsv
 
     attr_reader :shared_strings, :xfs, :num_fmts, :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
+    # @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?
 
@@ -53,12 +34,12 @@ module Xsv
       @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
@@ -108,13 +89,15 @@ module Xsv
       stream.close
     end
 
-    def fetch_sheets
+    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") }
         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
 

data/lib/xsv.rb

@@ -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

@@ -36,7 +36,7 @@ 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"
 
@@ -44,4 +44,5 @@ Gem::Specification.new do |spec|
   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.6
+  version: 1.1.0
 platform: ruby
 authors:
 - Martijn Storck
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-01-07 00:00:00.000000000 Z
+date: 2022-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubyzip
@@ -86,6 +86,20 @@ dependencies:
     - - "~>"
       - !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
@@ -128,7 +142,7 @@ metadata:
   homepage_uri: https://github.com/martijn/xsv
   source_code_uri: https://github.com/martijn/xsv
   changelog_uri: https://github.com/martijn/xsv/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -136,15 +150,15 @@ 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.3.3
-signing_key: 
+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
 test_files: []