xsv 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fde081e219b3d4ae14aaa9d29de699e67df263ff0d8bfa1ffc10362099dc8eb
-  data.tar.gz: f2cd6e1ae40a06bcac62368a26f9cf09157d5394bbb7f9ab34473a90be729d37
+  metadata.gz: 14550b4494b57e9363e5b189222e242177e9c1328377d5458bb475231a6726b7
+  data.tar.gz: bddb0f2b94dcd67563f8d1b5525c6dffae2f3718fd08d4800e9e09ac21c57d59
 SHA512:
-  metadata.gz: 24a1070748166f3d18fffced8b310825efa72c121b4226ce588686c18eb07f80a8c328848b7f1c0915b4c002ea656916db263441dd2a442a60dd828e4ba8ccde
-  data.tar.gz: 01530b8f31bc60aafbeb36a563faff5958bf98577ae3a85e527e217c0c988a5b5d4ef7e614811cdd590402312835b7f60c50c0a94c4a77bc0543729e41c6e826
+  metadata.gz: 38a39e5b4484214a1a530ddb5f5add47d56c3cff4df1b20e519bc4712e693c1ab6cca6270779f3dd24c7e019835f7b98daccc16f42fc5f905a66fe02623323c0
+  data.tar.gz: b60b28263fcf0352f85b254a61866463dca7ac7e077314ff1e3584ccfd6b90ccd03d7edf8e33f3f63441db17fa15f2ed7139cb4f55ae7c912a555ea5ff008e39

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Xsv Changelog
+
+## 0.3.3
+
+Intial version with a changelog and reasonably complete YARD documentation.

data/Gemfile.lock

@@ -10,7 +10,7 @@ GEM
   specs:
     minitest (5.14.0)
     ox (2.13.2)
-    rake (10.5.0)
+    rake (13.0.1)
     rubyzip (2.2.0)
 
 PLATFORMS
@@ -19,7 +19,7 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 1.17)
   minitest (~> 5.0)
-  rake (~> 10.0)
+  rake (~> 13.0)
   xsv!
 
 BUNDLED WITH

data/Rakefile

@@ -2,9 +2,16 @@ require "bundler/gem_tasks"
 require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
   t.libs << "lib"
+  t.libs << "test"
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
-task :default => :test
+Rake::TestTask.new(:bench) do |t|
+  t.libs << "lib"
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_benchmark.rb"]
+end
+
+task :default => [:test, :bench]
+

data/lib/xsv/helpers.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 module Xsv
   module Helpers
+    # 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",
@@ -38,13 +40,15 @@ module Xsv
     MINUTE = 60.freeze
     HOUR = 3600.freeze
     A_CODEPOINT = 'A'.ord.freeze
+    # The epoch for all dates in OOXML Spreadsheet documents
     EPOCH = Date.new(1899, 12, 30).freeze
 
-    # Return the index number for the given Excel column name
+    # Return the index number for the given Excel column name (i.e. "A1" => 0)
     def column_index(col)
-      col = col[/^[A-Z]+/]
-
-      col.each_codepoint.reduce(0) { |sum, n| sum * 26 + (n - A_CODEPOINT + 1) } - 1
+      col.each_codepoint.reduce(0) do |sum, n|
+        break sum - 1 if n < A_CODEPOINT  # reached a number
+        sum * 26 + (n - A_CODEPOINT + 1)
+      end
     end
 
     # Return a Date for the given Excel date value
@@ -73,6 +77,7 @@ module Xsv
       "%02d:%02d" % [hours, minutes]
     end
 
+    # Returns a time including a date as a {Time} object
     def parse_datetime(number)
       date_base = number.truncate
       time = parse_date(date_base).to_time
@@ -85,6 +90,7 @@ module Xsv
       time + hours * HOUR + minutes.round * MINUTE
     end
 
+    # Returns a number as either Integer or Float
     def parse_number(string)
       if string.include? "."
         string.to_f
@@ -93,6 +99,7 @@ module Xsv
       end
     end
 
+    # Apply date or time number formats, if applicable
     def parse_number_format(number, format)
       number = parse_number(number) if number.is_a?(String)
 

data/lib/xsv/shared_strings_parser.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 module Xsv
+  # Interpret the sharedStrings.xml file from the workbook
+  # This is used internally when opening a sheet.
   class SharedStringsParser < Ox::Sax
     def self.parse(io)
       strings = []

data/lib/xsv/sheet.rb

@@ -1,14 +1,34 @@
 # frozen_string_literal: true
 module Xsv
+  # Sheet represents a single worksheet from a workbook and is normally accessed through {Workbook#sheets}
+  #
+  # Xsv is designed for worksheets with a single table of data, optionally with a header row. Because sheet implements
+  # {Enumerable} the rows in the worksheet can be iterated over using methods such as `#each` and `#map`
+  #
+  # By default Sheet will return rows as arrays. But by calling the {#parse_headers!} method the first row of the sheet
+  # will be parsed and Sheet will switch to hash mode, returning each row as a hash with the values from the first
+  # row as keys.
+  #
+  # If the sheet contains leading data before the first row of data or the header row, this can be skipped by setting the
+  # {row_skip} attribute.
   class Sheet
     include Enumerable
     include Xsv::Helpers
 
+    # Returns the current mode. Call {#parse_headers!} to switch to `:hash` mode
+    # @return [Symbol] `:hash` or `:array`
     attr_reader :mode
 
-    # Set a number of rows to skip at the top of the sheet (header row offset)
+    # Set a number of rows to skip at the top of the sheet (header row offset).
+    # For hash mode, do not skip the header row as this will be automatically
+    # skipped.
     attr_accessor :row_skip
 
+    # Create a new instance of Sheet. This is used internally by the {Workbook}.
+    # There is no need to create Sheets from application code.
+    #
+    # @param workbook [Workbook] The Workbook with shared data such as shared strings and styles
+    # @param io [IO] A handle to an open worksheet XML file
     def initialize(workbook, io)
       @workbook = workbook
       @io = io
@@ -19,11 +39,12 @@ module Xsv
       @last_row, @column_count = SheetBoundsHandler.get_bounds(@io, @workbook)
     end
 
+    # @return [String]
     def inspect
       "#<#{self.class.name}:#{self.object_id}>"
     end
 
-    # Iterate over rows
+    # Iterate over rows, returning either hashes or arrays based on the current mode.
     def each_row
       @io.rewind
 
@@ -38,7 +59,8 @@ module Xsv
 
     alias each each_row
 
-    # Get row by number, starting at 0
+    # 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.
     def [](number)
       each_with_index do |row, i|
         return row if i == number
@@ -49,6 +71,7 @@ module Xsv
 
     # Load headers in the top row of the worksheet. After parsing of headers
     # all methods return hashes instead of arrays
+    # @return [true]
     def parse_headers!
       @headers = parse_headers
       @mode = :hash
@@ -56,6 +79,7 @@ module Xsv
       true
     end
 
+    # Return the headers of the sheet as an array
     def headers
       if @headers.any?
         @headers

data/lib/xsv/sheet_bounds_handler.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 module Xsv
-  # SheetBoundsHandler scans a sheet looking for the outer bounds of the content within
+  # SheetBoundsHandler scans a sheet looking for the outer bounds of the content within.
+  # This is used internally when opening a sheet to deal with worksheets that do not
+  # have a correct dimension tag.
   class SheetBoundsHandler < Ox::Sax
     include Xsv::Helpers
 

data/lib/xsv/sheet_rows_handler.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 module Xsv
+  # This is the core worksheet parser, implemented as an Ox::Sax handler. This is
+  # used internally to enumerate rows.
   class SheetRowsHandler < Ox::Sax
     include Xsv::Helpers
 
     def format_cell
+      return nil if @current_value.empty?
+
       case @current_cell[:t]
       when "s"
         @workbook.shared_strings[@current_value.to_i]

data/lib/xsv/styles_handler.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 module Xsv
   # StylesHandler interprets the relevant parts of styles.xml
+  # This is used internally when opening a sheet.
   class StylesHandler < Ox::Sax
     def self.get_styles(io, numFmts)
       @xfs = nil

data/lib/xsv/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Xsv
-  VERSION = "0.3.2"
+  VERSION = "0.3.3"
 end

data/lib/xsv/workbook.rb

@@ -2,11 +2,18 @@
 require 'zip'
 
 module Xsv
+  # An OOXML Spreadsheet document is called a Workbook. A Workbook consists of
+  # multiple Sheets that are available in the array that's accessible through {#sheets}
   class Workbook
 
-    attr_reader :sheets, :shared_strings, :xfs, :numFmts, :trim_empty_rows
+    # Access the Sheet objects contained in the workbook
+    # @return [Array<Sheet>]
+    attr_reader :sheets
 
-    # Open the workbook of the given filename, string or buffer
+    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)
       if data.is_a?(IO)
         @workbook = self.new(Zip::File.open_buffer(data), **kws)
@@ -17,7 +24,8 @@ module Xsv
       end
     end
 
-    # Open a workbook from an instance of Zip::File
+    # Open a workbook from an instance of {Zip::File}. Generally it's recommended
+    # to use the {.open} method instead of the constructor.
     #
     # Options:
     #
@@ -36,10 +44,23 @@ module Xsv
       fetch_sheets
     end
 
+    # @return [String]
     def inspect
       "#<#{self.class.name}:#{self.object_id}>"
     end
 
+    # Close the handle to the workbook file and leave all resources for the GC to collect
+    # @return [true]
+    def close
+      @zip.close
+      @sheets = nil
+      @xfs = nil
+      @numFmts = nil
+      @shared_strings = nil
+
+      true
+    end
+
     private
 
     def fetch_shared_strings

data/lib/xsv.rb

@@ -11,6 +11,10 @@ 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
+# sense that it provides nothing a CSV reader wouldn't, meaning it only
+# deals with minimal formatting and cannot create or modify documents.
 module Xsv
   class Error < StandardError; end
   # An AssertionFailed error indicates an unexpected condition, meaning a bug

data/xsv.gemspec

@@ -9,7 +9,13 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Martijn Storck"]
   spec.email         = ["martijn@storck.io"]
 
-  spec.summary       = "Minimal xlsx parser that provides nothing a CSV parser wouldn't"
+  spec.summary       = "A fast and lightweiggt xlsx parser that provides nothing a CSV parser wouldn't"
+  spec.description    = <<-EOF
+                            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
+                            sense that it provides nothing a CSV reader wouldn't, meaning it only
+                            deals with minimal formatting and cannot create or modify documents.
+                          EOF
   spec.homepage      = "https://github.com/martijn/xsv"
   spec.license       = "MIT"
 
@@ -37,6 +43,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency "ox", "~> 2.13"
 
   spec.add_development_dependency "bundler", "~> 1.17"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "minitest", "~> 5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xsv
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Martijn Storck
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-02-23 00:00:00.000000000 Z
+date: 2020-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubyzip
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -80,7 +80,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
-description: 
+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
+                              sense that it provides nothing a CSV reader wouldn't, meaning it only
+                              deals with minimal formatting and cannot create or modify documents.
 email:
 - martijn@storck.io
 executables: []
@@ -89,6 +93,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -132,5 +137,5 @@ requirements: []
 rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
-summary: Minimal xlsx parser that provides nothing a CSV parser wouldn't
+summary: A fast and lightweiggt xlsx parser that provides nothing a CSV parser wouldn't
 test_files: []