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 uploads to a temporary location and stores the original filename with the StringIO object. (See this section 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 page to report bugs or suggest new enhancements.

License¶ ↑

Creek has been published under MIT License