excel-esv 3.0.1 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61b9d8716af48b7a32382ba6e9558a5f9f2afc71cb6ec0e6a380686dd91ea308
-  data.tar.gz: 8d737947eb7b20510cd234a5c23a033c5eaec2a8f90d22152c8c6892de99e271
+  metadata.gz: bb907e9f6b481001f01561df298d6052f3efb37f4ae3f57191b2bb807699203e
+  data.tar.gz: ea18830fa510acd5fe6d204714fbfc75114c0e167d08bd3fa969b61406893bf2
 SHA512:
-  metadata.gz: e72fa2c2685e9833c15d4ea0c6278b41ca0b8f45fe296ff81f6691652cd0b477f68e69365b9bc42b3d70024738361cd8805ab0d21885de875b028febab293d0d
-  data.tar.gz: 2dacf749dcc74944f9ad3cf2ef671e123a16f8665ecfab299541cd22c702663b9e168218675cfd75cc56ef1bac455b3d90f6f554f0d3549f71928931074808ea
+  metadata.gz: 745103dd2cbf9eda28e2d2947f4785b6a3f95372be9c3044265029cb4ac2e01c16d943923cb6e3f677387b2dfc6b5cbaba6bfddab001c0e775c97a92e967870b
+  data.tar.gz: e22bb76f26d291021847496fd679f6f982c4ecd14f0e9978674f08607f90d848b9539d5931d0a1ae038af8c22a8254814e69198af1802f755960e2fc0394ece4

data/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

data/.github/workflows/ci.yml

@@ -7,16 +7,22 @@ on:
     branches: [ master ]
 
 jobs:
-  test:
+  ruby-versions:
+    uses: ruby/actions/.github/workflows/ruby_versions.yml@master
+    with:
+      min_version: 3.2
+      engine: cruby
 
+  test:
+    needs: ruby-versions
     runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        ruby-version: ["3.0", "2.7", "2.6", "2.5"]
-
+        ruby-version: ${{ fromJson(needs.ruby-versions.outputs.versions) }}
+        
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v5
       - name: Set up Ruby ${{ matrix.ruby-version }}
         uses: ruby/setup-ruby@v1
         with:

data/.gitignore

@@ -11,4 +11,5 @@
 *.so
 *.o
 *.a
+*.gem
 mkmf.log

data/CHANGELOG.md

@@ -1,12 +1,24 @@
-# 3.0.0
+# Changelog
+
+## 3.1.0 (Nov 12, 2025)
+
+* Support specifying worksheet index when there are multiple: `ESV.parse(data, worksheet_index: 0)`.
+
+## 3.0.1 (Nov 19, 2021)
+
+* Add `ESV.parse(data, header_converters:)` [#9]
+
+[#9]: https://github.com/barsoom/excel-esv/pull/9
+
+## 3.0.0 (Nov 20, 2018)
 
 * Returns the last value of any formula cells instead of returning a `Spreadsheet::Formula`.
 * Returns the URL of any link cells instead of returning a `Spreadsheet::Link`.
 
-# 2.0.0
+## 2.0.0 (Nov 19, 2018)
 
 * `parse` now returns an actual nested `Array`, not array-like `Spreadsheet::Row` records.
 
-# 1.0.0
+## 1.0.0 (Dec 8, 2017)
 
 * `send_excel` now supports a `filename:` argument, e.g. `send_excel(data, filename: "salaries.xls")`.

data/Gemfile

@@ -4,7 +4,7 @@ source "https://rubygems.org"
 gemspec
 
 group :development do
-  gem "barsoom_utils", github: "barsoom/barsoom_utils"
+  gem "barsoom_utils"
   gem "bundler"
   gem "rake"
   gem "rspec"

data/README.md

@@ -45,7 +45,31 @@ output = ESV.parse(data)
 # => [ [ "Name", "Dogs", … ], … ]
 ```
 
-This assumes a file with a single worksheet and will raise otherwise.
+This will raise for a file with multiple worksheets unless you explicitly specify the one you want (the first worksheet is index 0):
+
+``` ruby
+ESV.parse(data, worksheet_index: 0)
+```
+
+`.parse` supports the `header_converters:` keyword argument, which takes the same arguments as `CSV.parse` does:
+
+- a Symbol name for a registered header converter
+- a Proc which takes the value and returns the converted value
+- an Array of Symbol names for registered header converters
+
+``` ruby
+require "esv"
+
+data = File.read("/tmp/test.xls")
+output = ESV.parse(data, header_converters: :symbol)
+# => [ [ :name, :dogs, … ], … ]
+```
+
+Registering a new converter:
+
+``` ruby
+ESV::HEADER_CONVERTERS[:upcase] = ->(value) { value.upcase }
+```
 
 ### Parse file
 
@@ -58,6 +82,8 @@ output = ESV.parse_file("/tmp/test.xls")
 
 This assumes a file with a single worksheet and will raise otherwise.
 
+Also supports `header_converters:`.
+
 ### Generate in Ruby on Rails
 
 In `config/initializers/mime_types.rb`:

data/excel-esv.gemspec

@@ -16,5 +16,6 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files -z`.split("\x0")
   spec.require_paths = [ "lib" ]
 
-  spec.add_dependency "spreadsheet"
+  spec.add_runtime_dependency "spreadsheet"
+  spec.add_runtime_dependency "logger"
 end

data/lib/esv/version.rb

@@ -1,3 +1,3 @@
 module ESV
-  VERSION = "3.0.1"
+  VERSION = "3.1.0"
 end

data/lib/esv.rb

@@ -16,27 +16,78 @@ module ESV
     end
   end
 
-  def self.parse(data)
+  # You can register your own header converters in this Hash.
+  #
+  # @see https://rubyapi.org/3.2/o/csv#class-CSV-label-Custom+Header+Converters
+  HEADER_CONVERTERS = {
+    downcase: ->(value) {
+      value.respond_to?(:downcase) ? value.downcase : value
+    },
+    # Details:
+    #
+    #  Strips leading and trailing whitespace.
+    #  Downcases the header.
+    #  Replaces embedded spaces with underscores.
+    #  Removes non-word characters.
+    #  Makes the string into a Symbol.
+    symbol: ->(value) {
+      value.to_s.strip.downcase.tr(" ", "_").gsub(/\W+/, "").to_sym
+    },
+  }
+
+  # @param data [Object] Spreadsheet data to be parsed.
+  # @param header_converters [nil, Symbol, Proc, Array<Symbol>] If given, can take these forms:
+  #   - a Symbol name for a registered header converter
+  #   - a Proc which takes the value and returns the converted value
+  #   - an Array of Symbol names for registered header converters
+  # @param worksheet_index [nil, Integer] If given, specifies which worksheet index to parse (first is 0). If nil, expects exactly one worksheet.
+  # @return [Array<Array>] a list of rows
+  def self.parse(data, header_converters: nil, worksheet_index: nil)
     fake_file = StringIO.new(data)
     book = Spreadsheet.open(fake_file)
 
-    # We could support multiple worksheets, but let's not until we actually need it.
-    # Until then, we prefer raising to silently ignoring worksheets.
-    worksheet_count = book.worksheets.length
-    raise "Expected 1 worksheet, found #{worksheet_count}." if worksheet_count > 1
-
-    book.worksheet(0).to_a.map(&:to_a).map { |row|
-      row.map { |cell|
-        case cell
-        when Spreadsheet::Formula then cell.value
-        when Spreadsheet::Link then cell.href
-        else cell
+    # We prefer raising to silently ignoring worksheets.
+    if !worksheet_index && book.worksheets.length > 1
+      raise "Expected 1 worksheet, found #{book.worksheets.length}."
+    end
+
+    worksheet_index ||= 0
+
+    is_first_row = true
+    book.worksheet(worksheet_index).to_a.map(&:to_a).map { |row|
+      row.each_with_index.map { |cell, index|
+        value =
+          case cell
+          when Spreadsheet::Formula then cell.value
+          when Spreadsheet::Link then cell.href
+          else cell
+          end
+
+        if header_converters && is_first_row
+          case header_converters
+          when Proc then
+            value = header_converters.call(value)
+          when Symbol then
+            value = HEADER_CONVERTERS[header_converters].call(value)
+          when Enumerable then
+            # Apply the converters in order.
+            header_converters.each { |name|
+              value = HEADER_CONVERTERS.fetch(name).call(value)
+            }
+          else
+            raise "Unsupported kind of header_converters #{header_converters.inspect}"
+          end
+          value
+        else
+          value
         end
+      }.tap {
+        is_first_row = false
       }
     }
   end
 
-  def self.parse_file(path)
-    parse File.read(path)
+  def self.parse_file(path, header_converters: nil)
+    parse(File.read(path), header_converters: header_converters)
   end
 end

data/spec/esv_spec.rb

@@ -1,114 +1,224 @@
 require "esv"
 
-RSpec.describe ESV, ".generate and .parse" do
-  it "works" do
-    data = ESV.generate do |esv|
-      esv << [ "Dogs", "Cats" ]
-      esv << [ 1, 2 ]
+RSpec.describe ESV do
+  describe ".generate and .parse" do
+    it "works" do
+      data = ESV.generate do |esv|
+        esv << [ "Dogs", "Cats" ]
+        esv << [ 1, 2 ]
+      end
+
+      output = ESV.parse(data)
+
+      expect(output).to eq [
+        [ "Dogs", "Cats" ],
+        [ 1, 2 ],
+      ]
     end
-
-    output = ESV.parse(data)
-
-    expect(output).to eq [
-      [ "Dogs", "Cats" ],
-      [ 1, 2 ],
-    ]
   end
-end
 
-RSpec.describe ESV, ".parse" do
-  it "raises if there's more than one worksheet" do
-    excel_file_with_two_worksheets = generate_excel_file do |sheet, book|
-      book.create_worksheet
+  describe "::HEADER_CONVERTERS" do
+    context "with :downcase" do
+      it "downcases string value" do
+        expect(described_class::HEADER_CONVERTERS[:downcase].call("CAT")).to eq("cat")
+      end
+
+      it "returns a non-string value" do
+        expect(described_class::HEADER_CONVERTERS[:downcase].call(1)).to eq(1)
+      end
     end
 
-    expect {
-      ESV.parse(excel_file_with_two_worksheets)
-    }.to raise_error(/Expected 1 worksheet, found 2/)
+    context "with :symbol" do
+      it "stringifies before symbolizing given value" do
+        expect(described_class::HEADER_CONVERTERS[:symbol].call(1)).to eq(:"1")
+      end
+
+      it "symbolizes given value" do
+        expect(described_class::HEADER_CONVERTERS[:symbol].call("cat")).to eq(:cat)
+      end
+
+      context "symbolizes and" do
+        it "downcases given value" do
+          expect(described_class::HEADER_CONVERTERS[:symbol].call("CAT")).to eq(:cat)
+        end
+
+        it "strips any spaces around value" do
+          expect(described_class::HEADER_CONVERTERS[:symbol].call("   CAT ")).to eq(:cat)
+        end
+
+        it "replaces embedded spaces with underscores" do
+          expect(described_class::HEADER_CONVERTERS[:symbol].call("CAT CAT")).to eq(:cat_cat)
+        end
+
+        it "removes non-word characters" do
+          expect(described_class::HEADER_CONVERTERS[:symbol].call("CAT?")).to eq(:cat)
+        end
+      end
+    end
   end
 
-  it "ignores formatting, always returning a plain array of data" do
-    excel_file_with_formatting = generate_excel_file do |sheet|
-      sheet.row(0).replace([ 1, 2 ])
-      sheet.row(0).default_format = Spreadsheet::Format.new(color: :blue)
+  describe ".parse" do
+    describe "worksheet handling" do
+      context "with more than one worksheet" do
+        let(:excel_file_with_two_worksheets) {
+          generate_excel_file do |sheet_0, book|
+            sheet_0.row(0).replace([ "I am worksheet 0" ])
+
+            sheet_1 = book.create_worksheet
+            sheet_1.row(0).replace([ "I am worksheet 1" ])
+          end
+        }
+
+        it "raises when not given a worksheet index" do
+          expect {
+            ESV.parse(excel_file_with_two_worksheets)
+          }.to raise_error(/Expected 1 worksheet, found 2/)
+        end
+
+        it "allows specifying a worksheet index" do
+          output = ESV.parse(excel_file_with_two_worksheets, worksheet_index: 0)
+          expect(output).to eq [[ "I am worksheet 0" ]]
+
+          output = ESV.parse(excel_file_with_two_worksheets, worksheet_index: 1)
+          expect(output).to eq [[ "I am worksheet 1" ]]
+        end
+      end
     end
 
-    output = ESV.parse(excel_file_with_formatting)
+    it "ignores formatting, always returning a plain array of data" do
+      excel_file_with_formatting = generate_excel_file do |sheet|
+        sheet.row(0).replace([ 1, 2 ])
+        sheet.row(0).default_format = Spreadsheet::Format.new(color: :blue)
+      end
 
-    expect(output).to eq [
-      [ 1, 2 ],
-    ]
+      output = ESV.parse(excel_file_with_formatting)
 
-    expect(output[0].class).to eq Array
-  end
+      expect(output).to eq [
+        [ 1, 2 ],
+      ]
 
-  it "returns the last value of a formula cell" do
-    excel_file_with_formula = generate_excel_file do |sheet|
-      formula = Spreadsheet::Formula.new
-      formula.value = "two"
-      sheet.row(0).replace([ "one", formula ])
+      expect(output[0].class).to eq Array
     end
 
-    output = ESV.parse(excel_file_with_formula)
+    it "returns the last value of a formula cell" do
+      excel_file_with_formula = generate_excel_file do |sheet|
+        formula = Spreadsheet::Formula.new
+        formula.value = "two"
+        sheet.row(0).replace([ "one", formula ])
+      end
 
-    expect(output).to eq [
-      [ "one", "two" ],
-    ]
-    expect(output[0].class).to eq Array
-  end
+      output = ESV.parse(excel_file_with_formula)
 
+      expect(output).to eq [
+        [ "one", "two" ],
+      ]
+      expect(output[0].class).to eq Array
+    end
 
-  it "returns the URL of a link cell" do
-    excel_file_with_link = generate_excel_file do |sheet|
-      link = Spreadsheet::Link.new("https://example.com", "desc", "foo")
-      sheet.row(0).replace([ "one", link ])
+
+    it "returns the URL of a link cell" do
+      excel_file_with_link = generate_excel_file do |sheet|
+        link = Spreadsheet::Link.new("https://example.com", "desc", "foo")
+        sheet.row(0).replace([ "one", link ])
+      end
+      output = ESV.parse(excel_file_with_link)
+      expect(output).to eq [
+        [ "one", "https://example.com#foo" ],
+      ]
+
+      expect(output[0][1].class).to eq String
     end
-    output = ESV.parse(excel_file_with_link)
-    expect(output).to eq [
-      [ "one", "https://example.com#foo" ],
-    ]
 
-    expect(output[0][1].class).to eq String
-  end
+    context "when given a header_converters: option" do
+      let(:data) {
+        ESV.generate do |esv|
+          esv << [ "Dogs", "Cats cats" ]
+          esv << [ 1, 2 ]
+        end
+      }
+
+      it "lets you specify header_converters by symbolic name" do
+        output = ESV.parse(data, header_converters: :downcase)
+
+        expect(output).to eq [
+          [ "dogs", "cats cats" ],
+          [ 1, 2 ],
+        ]
+      end
+
+      it "lets you specify header_converters as a proc" do
+        output = ESV.parse(data, header_converters: ->(value) { value.upcase })
+
+        expect(output).to eq [
+          [ "DOGS", "CATS CATS" ],
+          [ 1, 2 ],
+        ]
+      end
+
+      it "lets you register new symbolic names for header_converters and use them" do
+        ESV::HEADER_CONVERTERS[:upcase] = ->(value) { value.upcase }
+
+        output = ESV.parse(data, header_converters: :upcase)
+
+        expect(output).to eq [
+          [ "DOGS", "CATS CATS" ],
+          [ 1, 2 ],
+        ]
+
+        ESV::HEADER_CONVERTERS.delete(:upcase)
+      end
+
+      it "lets you specify header_converters by symbolic names as a list and have them apply in order" do
+        ESV::HEADER_CONVERTERS[:reverse] = ->(value) { value.reverse }
+        output = ESV.parse(data, header_converters: [ :downcase, :reverse, :symbol ])
+
+        expect(output).to eq [
+          [ :sgod, :stac_stac ],
+          [ 1, 2 ],
+        ]
+        ESV::HEADER_CONVERTERS.delete(:reverse)
+      end
+    end
 
-  private
+    private
 
-  def generate_excel_file(&block)
-    book = Spreadsheet::Workbook.new
-    sheet = book.create_worksheet
+    def generate_excel_file(&block)
+      book = Spreadsheet::Workbook.new
+      sheet = book.create_worksheet
 
-    block.call(sheet, book)
+      block.call(sheet, book)
 
-    data = ""
-    fake_file = StringIO.new(data)
-    book.write(fake_file)
-    data
+      data = ""
+      fake_file = StringIO.new(data)
+      book.write(fake_file)
+      data
+    end
   end
-end
 
-RSpec.describe ESV, ".generate_file and .parse_file" do
-  before do
-    @file = Tempfile.new("esv")
-  end
+  describe ".generate_file and .parse_file" do
+    before do
+      @file = Tempfile.new("esv")
+    end
 
-  it "works" do
-    path = @file.path
+    it "works" do
+      path = @file.path
 
-    ESV.generate_file(path) do |esv|
-      esv << [ "Dogs", "Cats" ]
-      esv << [ 1, 2 ]
-    end
+      ESV.generate_file(path) do |esv|
+        esv << [ "Dogs", "Cats" ]
+        esv << [ 1, 2 ]
+      end
 
-    output = ESV.parse_file(path)
+      output = ESV.parse_file(path)
 
-    expect(output).to eq [
-      [ "Dogs", "Cats" ],
-      [ 1, 2 ],
-    ]
-  end
+      expect(output).to eq [
+        [ "Dogs", "Cats" ],
+        [ 1, 2 ],
+      ]
+    end
 
-  after do
-    @file.close
-    @file.unlink
+    after do
+      @file.close
+      @file.unlink
+    end
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: excel-esv
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 3.1.0
 platform: ruby
 authors:
 - Henrik Nyh
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-11-19 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: spreadsheet
@@ -24,13 +23,27 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 email:
 - henrik@nyh.se
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/dependabot.yml"
 - ".github/workflows/ci.yml"
 - ".gitignore"
 - ".rspec"
@@ -53,7 +66,6 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -68,8 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.28
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Excel parsing and generation with the ease of CSV.
 test_files: []