creek 1.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 362e390640c6143db12fdf1cf83d45a2d70b1cf3
+  data.tar.gz: c11e75bfc31e009513f32f14711b3396732ffd1e
+SHA512:
+  metadata.gz: 5339ab0325a1f9034f245c73767a6d615958521286170853d489e2c53d242fba5794c25212acac61001d5759260d6be6156d39cb02cd0952fcdbeb7a8b7c9d74
+  data.tar.gz: 27126fdd4c896abce8480174b80316025deb427f28d89275775da807f8049f5ac12a862134fc52b6fc63e4fcd54014d7cb5ab55d32d17fb2a826ffcb15117742

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in creek.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 TODO: Write your name
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,76 @@
+= Creek -- Stream parser for large Excel(xlsx and xlsm) files.
+
+Creek is a Ruby gem that provide a fast, simple and efficient method of parsing large Excel(xlsx and xlsm) files.
+
+
+== Installation
+
+Creek can be used from the command line or as part of a Ruby web framework. To install the gem using terminal, run the following command:
+
+    gem install creek
+
+To use it in Rails, add this line to your Gemfile:
+
+    gem "creek"
+
+
+== Basic Usage
+Creek can simply parse an Excel file by looping through the rows enumerator:
+
+    require 'creek'
+    creek = Creek::Book.new "specs/fixtures/sample.xlsx"
+    sheet= creek.sheets[0]
+
+    sheet.rows.each do |row|
+      puts row # => {"A1"=>"Content 1", "B1"=>nil, C1"=>nil, "D1"=>"Content 3"}
+    end
+
+
+    sheet.rows_with_meta_data.each do |row|
+      puts row # => {"collapsed"=>"false", "customFormat"=>"false", "customHeight"=>"true", "hidden"=>"false", "ht"=>"12.1", "outlineLevel"=>"0", "r"=>"1", "cells"=>{"A1"=>"Content 1", "B1"=>nil, C1"=>nil, "D1"=>"Content 3"}}
+    end
+
+
+    sheet.state   # => 'visible'
+    sheet.name    # => 'Sheet1'
+    sheet.rid     # => 'rId2'
+
+== Filename considerations
+By default, Creek will ensure that the file extension is either *.xlsx or *.xlsm, but this check can be circumvented as needed:
+
+    path = 'sample-as-zip.zip'
+    Creek::Book.new path, :check_file_extension => false
+
+By default, the Rails {file_field_tag}[http://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html#method-i-file_field_tag] uploads to a temporary location and stores the original filename with the StringIO object. (See {this section}[http://guides.rubyonrails.org/form_helpers.html#uploading-files] of the Rails Guides for more information.)
+
+Creek can parse this directly without the need for file upload gems such as Carrierwave or Paperclip by passing the original filename as an option:
+
+    # Import endpoint in Rails controller
+    def import
+      file = params[:file]
+      Creek::Book.new file.path, check_file_extension: false
+    end
+
+== Contributing
+
+Contributions are welcomed. You can fork a repository, add your code changes to the forked branch, ensure all existing unit tests pass, create new unit tests cover your new changes and finally create a pull request.
+
+After forking and then cloning the repository locally, install Bundler and then use it
+to install the development gem dependecies:
+
+    gem install bundler
+    bundle install
+
+Once this is complete, you should be able to run the test suite:
+
+    rake
+
+
+== Bug Reporting
+
+Please use the {Issues}[https://github.com/pythonicrubyist/creek/issues] page to report bugs or suggest new enhancements.
+
+
+== License
+
+Creek has been published under {MIT License}[https://github.com/pythonicrubyist/creek/blob/master/LICENSE.txt]

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+# If you want to make this the default task
+task :default => :spec

data/creek.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'creek/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "creek"
+  spec.version       = Creek::VERSION
+  spec.authors       = ["pythonicrubyist"]
+  spec.email         = ["pythonicrubyist@gmail.com"]
+  spec.description   = %q{A Ruby gem that streams and parses large Excel(xlsx and xlsm) files fast and efficiently.}
+  spec.summary       = %q{A Ruby gem for parsing large Excel(xlsx and xlsm) files.}
+  spec.homepage      = "https://github.com/pythonicrubyist/creek"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = '>= 1.9.2'
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency 'rspec', '~> 2.13.0'
+
+  spec.add_dependency 'nokogiri', '~> 1.6.0'
+  spec.add_dependency 'rubyzip', '>= 1.0.0'
+end

data/lib/creek.rb

@@ -0,0 +1,8 @@
+require "creek/version"
+require 'creek/book'
+require 'creek/sheet'
+require 'creek/shared_strings'
+
+module Creek
+  # Your code goes here...
+end

data/lib/creek/book.rb

@@ -0,0 +1,34 @@
+require 'zip/filesystem'
+require 'nokogiri'
+
+module Creek
+
+  class Creek::Book
+
+    attr_reader :files,
+                :sheets,
+                :shared_strings
+
+    def initialize path, options = {}
+      check_file_extension = options.fetch(:check_file_extension, true)
+      if check_file_extension
+        extension = File.extname(options[:original_filename] || path).downcase
+        raise 'Not a valid file format.' unless (['.xlsx', '.xlsm'].include? extension)
+      end
+      @files = Zip::File.open path
+      @shared_strings = SharedStrings.new(self)
+    end
+
+    def sheets
+      doc = @files.file.open "xl/workbook.xml"
+      xml = Nokogiri::XML::Document.parse doc
+      @sheets = xml.css('sheet').each_with_index.map  do |sheet, i|
+        Sheet.new(self, sheet.attr("name"), sheet.attr("sheetid"),  sheet.attr("state"), sheet.attr("visible"), sheet.attr("r:id"), i+1)
+      end
+    end
+
+    def close
+      @files.close
+    end
+  end
+end

data/lib/creek/shared_strings.rb

@@ -0,0 +1,27 @@
+require 'zip/filesystem'
+require 'nokogiri'
+
+module Creek
+
+  class Creek::SharedStrings
+
+    attr_reader :book, :dictionary
+
+    def initialize book
+      @book = book
+      parse_shared_shared_strings
+    end
+
+    def parse_shared_shared_strings
+      path = "xl/sharedStrings.xml"
+      @dictionary = Hash.new
+      if @book.files.file.exist?(path)
+        doc = @book.files.file.open path
+        xml = Nokogiri::XML::Document.parse doc
+        xml.css('t').each_with_index.map  do |str, i|
+          @dictionary[i] = str.content
+        end
+      end
+    end
+  end
+end

data/lib/creek/sheet.rb

@@ -0,0 +1,116 @@
+require 'zip/filesystem'
+require 'nokogiri'
+
+module Creek
+  class Creek::Sheet
+
+    attr_reader :book,
+                :name,
+                :sheetid,
+                :state,
+                :visible,
+                :rid,
+                :index
+
+
+    def initialize book, name, sheetid, state, visible, rid, index
+      @book = book
+      @name = name
+      @sheetid = sheetid
+      @visible = visible
+      @rid = rid
+      @state = state
+      @index = index
+
+      # An XLS file has only 256 columns, however, an XLSX or XLSM file can contain up to 16384 columns.
+      # This function creates a hash with all valid XLSX column names and associated indices.
+      @@excel_col_names = Hash.new
+      (0...16384).each do |i|
+        @@excel_col_names[col_name(i)] = i
+      end
+    end
+
+    ##
+    # Provides an Enumerator that returns a hash representing each row.
+    # The key of the hash is the Cell id and the value is the value of the cell.
+    def rows
+      rows_generator
+    end
+
+    ##
+    # Provides an Enumerator that returns a hash representing each row.
+    # The hash contains meta data of the row and a 'cells' embended hash which contains the cell contents.
+    def rows_with_meta_data
+      rows_generator true
+    end
+
+    private
+    ##
+    # Returns valid Excel column name for a given column index.
+    # For example, returns "A" for 0, "B" for 1 and "AQ" for 42.
+    def col_name i
+      quot = i/26
+      (quot>0 ? col_name(quot-1) : "") + (i%26+65).chr
+    end
+
+    ##
+    # Returns a hash per row that includes the cell ids and values.
+    # Empty cells will be also included in the hash with a nil value.
+    def rows_generator include_meta_data=false
+      path = "xl/worksheets/sheet#{@index}.xml"
+      if @book.files.file.exist?(path)
+        # SAX parsing, Each element in the stream comes through as two events:
+        # one to open the element and one to close it.
+        opener = Nokogiri::XML::Reader::TYPE_ELEMENT
+        closer = Nokogiri::XML::Reader::TYPE_END_ELEMENT
+        Enumerator.new do |y|
+          shared, row, cells, cell = false, nil, {}, nil
+          @book.files.file.open(path) do |xml|
+            Nokogiri::XML::Reader.from_io(xml).each do |node|
+              if (node.name.eql? 'row') and (node.node_type.eql? opener)
+                row = node.attributes
+                row['cells'] = Hash.new
+                cells = Hash.new
+                y << (include_meta_data ? row : cells) if node.self_closing?
+              elsif (node.name.eql? 'row') and (node.node_type.eql? closer)
+                processed_cells = fill_in_empty_cells(cells, row['r'], cell)
+                row['cells'] = processed_cells
+                y << (include_meta_data ? row : processed_cells)
+              elsif (node.name.eql? 'c') and (node.node_type.eql? opener)
+                  shared = node.attribute('t').eql? 's'
+                  cell = node.attribute('r')
+              elsif node.value?
+                if shared
+                  cells[cell] = @book.shared_strings.dictionary[node.value.to_i] if @book.shared_strings.dictionary.has_key? node.value.to_i
+                else
+                  cells[cell] = node.value
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+    ##
+    # The unzipped XML file does not contain any node for empty cells.
+    # Empty cells are being padded in using this function
+    def fill_in_empty_cells cells, row_number, last_col
+      new_cells = Hash.new
+      unless cells.empty?
+        keys = cells.keys.sort
+        last_col = last_col.gsub(row_number, '')
+        last_col_index = @@excel_col_names[last_col]
+        [*(0..last_col_index)].each do |i|
+          col = col_name i
+          id = "#{col}#{row_number}"
+          unless cells.has_key? id
+              new_cells[id] = nil
+          else
+            new_cells[id] = cells[id]
+          end
+        end
+      end
+      new_cells
+    end
+  end
+end

data/lib/creek/version.rb

@@ -0,0 +1,3 @@
+module Creek
+  VERSION = "1.0.4"
+end

data/spec/test_spec.rb

@@ -0,0 +1,82 @@
+require 'creek'
+
+describe 'Creek trying to parsing an invalid file.' do
+  it 'Fail to open a legacy xls file.' do
+    lambda { Creek::Book.new 'spec/fixtures/invalid.xls' }.should raise_error 'Not a valid file format.'
+  end
+
+  it 'Ignore file extensions on request.' do
+    path = 'spec/fixtures/sample-as-zip.zip'
+    lambda { Creek::Book.new path, :check_file_extension => false }.should_not raise_error
+  end
+
+  it 'Check file extension when requested.' do
+    open_book = lambda { Creek::Book.new 'spec/fixtures/invalid.xls', :check_file_extension => true }
+    open_book.should raise_error 'Not a valid file format.'
+  end
+
+  it 'Check file extension of original_filename if passed.' do
+    path = 'spec/fixtures/temp_string_io_file_path_with_no_extension'
+    lambda { Creek::Book.new path, :original_filename => 'invalid.xls' }.should raise_error 'Not a valid file format.'
+    lambda { Creek::Book.new path, :original_filename => 'valid.xlsx' }.should_not raise_error
+  end
+
+end
+
+describe 'Creek parsing a sample XLSX file' do
+  before(:all) do
+    @creek = Creek::Book.new 'spec/fixtures/sample.xlsx'
+    @expected_rows = [{'A1'=>'Content 1', 'B1'=>nil, 'C1'=>'Content 2', 'D1'=>nil, 'E1'=>'Content 3'},
+                    {'A2'=>nil, 'B2'=>'Content 4', 'C2'=>nil, 'D2'=>'Content 5', 'E2'=>nil, 'F2'=>'Content 6'},
+                    {},
+                    {'A4'=>'Content 7', 'B4'=>'Content 8', 'C4'=>'Content 9', 'D4'=>'Content 10', 'E4'=>'Content 11', 'F4'=>'Content 12'},
+                    {'A5'=>nil, 'B5'=>nil, 'C5'=>nil, 'D5'=>nil, 'E5'=>nil, 'F5'=>nil, 'G5'=>nil, 'H5'=>nil, 'I5'=>nil, 'J5'=>nil, 'K5'=>nil, 'L5'=>nil, 'M5'=>nil, 'N5'=>nil, 'O5'=>nil, 'P5'=>nil, 'Q5'=>nil, 'R5'=>nil, 'S5'=>nil, 'T5'=>nil, 'U5'=>nil, 'V5'=>nil, 'W5'=>nil, 'X5'=>nil, 'Y5'=>nil, 'Z5'=>'Z Content', 'AA5'=>nil, 'AB5'=>nil, 'AC5'=>nil, 'AD5'=>nil, 'AE5'=>nil, 'AF5'=>nil, 'AG5'=>nil, 'AH5'=>nil, 'AI5'=>nil, 'AJ5'=>nil, 'AK5'=>nil, 'AL5'=>nil, 'AM5'=>nil, 'AN5'=>nil, 'AO5'=>nil, 'AP5'=>nil, 'AQ5'=>nil, 'AR5'=>nil, 'AS5'=>nil, 'AT5'=>nil, 'AU5'=>nil, 'AV5'=>nil, 'AW5'=>nil, 'AX5'=>nil, 'AY5'=>nil, 'AZ5'=>'Content 13'},
+                    {'A6'=>'1', 'B6'=>'2', 'C6'=>'3'}, {'A7'=>'Content 15', 'B7'=>'Content 16', 'C7'=>'Content 18', 'D7'=>'Content 19'},
+                    {'A8'=>nil, 'B8'=>'Content 20', 'C8'=>nil, 'D8'=>nil, 'E8'=>nil, 'F8'=>'Content 21'}]
+  end
+
+  after(:all) do
+    @creek.close
+  end
+
+  it 'open an XLSX file successfully.' do
+    @creek.should_not be_nil
+  end
+
+  it 'find sheets successfully.' do
+    @creek.sheets.count.should == 1
+    sheet = @creek.sheets.first
+    sheet.state.should eql nil
+    sheet.name.should eql 'Sheet1'
+    sheet.rid.should eql 'rId1'
+  end
+
+  it 'Parse rows with empty cells successfully.' do
+    rows = Array.new
+    row_count = 0
+    @creek.sheets[0].rows.each do |row|
+      rows << row
+      row_count += 1
+    end
+
+    rows[0].should == @expected_rows[0]
+    rows[1].should == @expected_rows[1]
+    rows[2].should == @expected_rows[2]
+    rows[3].should == @expected_rows[3]
+    rows[4].should == @expected_rows[4]
+    rows[5].should == @expected_rows[5]
+    rows[6].should == @expected_rows[6]
+    rows[7].should == @expected_rows[7]
+    row_count.should == 8
+  end
+
+  it 'Parse rows with empty cells and meta data successfully.' do
+    rows = Array.new
+    row_count = 0
+    @creek.sheets[0].rows_with_meta_data.each do |row|
+      rows << row
+      row_count += 1
+    end
+    rows.map{|r| r['cells']}.should == @expected_rows
+  end
+end

metadata

@@ -0,0 +1,136 @@
+--- !ruby/object:Gem::Specification
+name: creek
+version: !ruby/object:Gem::Version
+  version: 1.0.4
+platform: ruby
+authors:
+- pythonicrubyist
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.13.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.13.0
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.6.0
+- !ruby/object:Gem::Dependency
+  name: rubyzip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+description: A Ruby gem that streams and parses large Excel(xlsx and xlsm) files fast
+  and efficiently.
+email:
+- pythonicrubyist@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.rdoc
+- Rakefile
+- creek.gemspec
+- lib/creek.rb
+- lib/creek/book.rb
+- lib/creek/shared_strings.rb
+- lib/creek/sheet.rb
+- lib/creek/version.rb
+- spec/fixtures/invalid.xls
+- spec/fixtures/sample-as-zip.zip
+- spec/fixtures/sample.xlsx
+- spec/fixtures/temp_string_io_file_path_with_no_extension
+- spec/test_spec.rb
+homepage: https://github.com/pythonicrubyist/creek
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.0.rc.1
+signing_key: 
+specification_version: 4
+summary: A Ruby gem for parsing large Excel(xlsx and xlsm) files.
+test_files:
+- spec/fixtures/invalid.xls
+- spec/fixtures/sample-as-zip.zip
+- spec/fixtures/sample.xlsx
+- spec/fixtures/temp_string_io_file_path_with_no_extension
+- spec/test_spec.rb