roo 2.3.0 → 2.10.1

data/README.md

@@ -1,6 +1,6 @@
 # Roo
 
-[![Build Status](https://img.shields.io/travis/roo-rb/roo.svg?style=flat-square)](https://travis-ci.org/roo-rb/roo) [![Code Climate](https://img.shields.io/codeclimate/github/roo-rb/roo.svg?style=flat-square)](https://codeclimate.com/github/roo-rb/roo) [![Coverage Status](https://img.shields.io/coveralls/roo-rb/roo.svg?style=flat-square)](https://coveralls.io/r/roo-rb/roo) [![Gem Version](https://img.shields.io/gem/v/roo.svg?style=flat-square)](https://rubygems.org/gems/roo)
+[![Build Status](https://img.shields.io/travis/roo-rb/roo.svg?style=flat-square)](https://travis-ci.org/roo-rb/roo) [![Maintainability](https://api.codeclimate.com/v1/badges/be8d7bf34e2aeaf67c62/maintainability)](https://codeclimate.com/github/roo-rb/roo/maintainability) [![Coverage Status](https://img.shields.io/coveralls/roo-rb/roo.svg?style=flat-square)](https://coveralls.io/r/roo-rb/roo) [![Gem Version](https://img.shields.io/gem/v/roo.svg?style=flat-square)](https://rubygems.org/gems/roo)
 
 Roo implements read access for all common spreadsheet types. It can handle:
 * Excel 2007 - 2013 formats (xlsx, xlsm)
@@ -18,26 +18,41 @@ Install as a gem
 Or add it to your Gemfile
 
 ```ruby
-gem 'roo', '~> 2.1.0'
+gem "roo", "~> 2.10.0"
 ```
 ## Usage
 
-Opening a spreadsheet
+### Opening a spreadsheet
 
+You can use the `Roo::Spreadsheet` class so `roo` automatically detects which [parser class](https://github.com/roo-rb/roo/blob/master/lib/roo.rb#L17) to use for you.
 ```ruby
 require 'roo'
 
-xlsx = Roo::Spreadsheet.open('./new_prices.xlsx')
-xlsx = Roo::Excelx.new("./new_prices.xlsx")
+file_name = './new_prices.xlsx'
+xlsx = Roo::Spreadsheet.open(file_name)
+xlsx.info
+# => Returns basic info about the spreadsheet file
+```
 
-# Use the extension option if the extension is ambiguous.
-xlsx = Roo::Spreadsheet.open('./rails_temp_upload', extension: :xlsx)
+``Roo::Spreadsheet.open`` can accept both string paths and ``File`` instances. Also, you can provide the extension of the file as an option: 
 
+```ruby
+require 'roo'
+
+file_name = './rails_temp_upload'
+xlsx = Roo::Spreadsheet.open(file_name, extension: :xlsx)
 xlsx.info
 # => Returns basic info about the spreadsheet file
 ```
 
-``Roo::Spreadsheet.open`` can accept both paths and ``File`` instances.
+On the other hand, if you know what the file extension is, you can use the specific parser class instead:
+```ruby
+require 'roo'
+
+xlsx = Roo::Excelx.new("./new_prices.xlsx")
+xlsx.info
+# => Returns basic info about the spreadsheet file
+```
 
 ### Working with sheets
 
@@ -50,7 +65,7 @@ ods.sheet(0).row(1)
 
 # Set the last sheet as the default sheet.
 ods.default_sheet = ods.sheets.last
-ods.default_sheet = s.sheets[3]
+ods.default_sheet = ods.sheets[2]
 ods.default_sheet = 'Sheet 3'
 
 # Iterate through each sheet
@@ -89,13 +104,13 @@ sheet.last_column
 You can access the top-left cell in the following ways
 
 ```ruby
-s.cell(1,1)
-s.cell('A',1)
-s.cell(1,'A')
-s.a1
+sheet.cell(1,1)
+sheet.cell('A',1)
+sheet.cell(1,'A')
+sheet.a1
 
 # Access the second sheet's top-left cell.
-s.cell(1,'A',s.sheets[1])
+sheet.cell(1,'A',sheet.sheets[1])
 ```
 
 #### Querying a spreadsheet
@@ -113,8 +128,14 @@ end
 Use ``sheet.parse`` to return an array of rows. Column names can be a ``String`` or a ``Regexp``.
 
 ```ruby
-sheet.parse(:id => /UPC|SKU/,:qty => /ATS*\sATP\s*QTY\z/)
-# => [{:upc => 727880013358, :qty => 12}, ...]
+sheet.parse(id: /UPC|SKU/, qty: /ATS*\sATP\s*QTY\z/)
+# => [{:id => 727880013358, :qty => 12}, ...]
+```
+
+Use the ``:headers`` option to include the header row in the parsed content.
+
+```ruby
+sheet.parse(headers: true)
 ```
 
 Use the ``:header_search`` option to locate the header row and assign the header names.
@@ -126,7 +147,17 @@ sheet.parse(header_search: [/UPC*SKU/,/ATS*\sATP\s*QTY\z/])
 Use the ``:clean`` option to strip out control characters and surrounding white space.
 
 ```ruby
-sheet.parse(:clean => true)
+sheet.parse(clean: true)
+```
+
+#### Options
+
+When opening the file you can add a hash of options.
+
+##### expand_merged_ranges
+If you open a document with merged cells and do not want to end up with nil values for the rows after the first one.
+```ruby
+xlsx = Roo::Excelx.new('./roo_error.xlsx', {:expand_merged_ranges => true})
 ```
 
 ### Exporting spreadsheets
@@ -189,6 +220,9 @@ xlsx.cell(3, 'C')
 # => 600000383.0
 
 xlsx.excelx_value(row,col)
+# => '600000383'
+
+xlsx.formatted_value(row,col)
 # => '0600000383'
 ```
 
@@ -206,7 +240,7 @@ Roo::OpenOffice has support for encrypted OpenOffice spreadsheets.
 
 ```ruby
 # Load an encrypted OpenOffice Spreadsheet
-ods = Roo::OpenOffice.new("myspreadsheet.ods", :password => "password")
+ods = Roo::OpenOffice.new("myspreadsheet.ods", password: "password")
 ```
 
 ``Roo::OpenOffice`` can access celltype, comments, font information, formulas and labels.
@@ -227,20 +261,32 @@ ods.formula('A', 2)
 
 ```ruby
 # Load a CSV file
-s = Roo::CSV.new("mycsv.csv")
+csv = Roo::CSV.new("mycsv.csv")
 ```
 
-Because Roo uses the [standard CSV library](), you can use options available to that library to parse csv files. You can pass options using the ``csv_options`` key.
+Because Roo uses the standard CSV library, you can use options available to that library to parse csv files. You can pass options using the ``csv_options`` key.
 
 For instance, you can load tab-delimited files (``.tsv``), and you can use a particular encoding when opening the file.
 
 
 ```ruby
 # Load a tab-delimited csv
-s = Roo::CSV.new("mytsv.tsv", csv_options: {col_sep: "\t"})
+csv = Roo::CSV.new("mytsv.tsv", csv_options: {col_sep: "\t"})
 
 # Load a csv with an explicit encoding
-s = Roo::CSV.new("mycsv.csv", csv_options: {encoding: Encoding::ISO_8859_1})
+csv = Roo::CSV.new("mycsv.csv", csv_options: {encoding: Encoding::ISO_8859_1})
+```
+
+You can also open csv files through the Roo::Spreadsheet class (useful if you accept both CSV and Excel types from a user file upload, for example).
+
+```ruby
+# Load a spreadsheet from a file path
+# Roo figures out the right parser based on file extension
+spreadsheet = Roo::Spreadsheet.open(csv_or_xlsx_file)
+
+# Load a csv and auto-strip the BOM (byte order mark)
+# csv files saved from MS Excel typically have the BOM marker at the beginning of the file
+spreadsheet = Roo::Spreadsheet.open("mycsv.csv", { csv_options: { encoding: 'bom|utf-8' } })
 ```
 
 ## Upgrading from Roo 1.13.x
@@ -252,11 +298,22 @@ Roo's public methods have stayed relatively consistent between 1.13.x and 2.0.0,
 
 ## Contributing
 ### Features
-1. Fork it ( https://github.com/[my-github-username]/roo/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'My new feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+1. Fork it ( https://github.com/roo-rb/roo/fork )
+2. Install it (`bundle install --with local_development`)
+3. Create your feature branch (`git checkout -b my-new-feature`)
+4. Commit your changes (`git commit -am 'My new feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create a new Pull Request
+
+### Testing
+Roo uses Minitest and RSpec. The best of both worlds! Run `bundle exec rake` to
+run the tests/examples.
+
+You can run the tests/examples with Rspec like reporters by running
+`USE_REPORTERS=true bundle exec rake`
+
+Roo also has a few tests that take a long time (5+ seconds). To run these, use
+`LONG_RUN=true bundle exec rake`
 
 ### Issues
 

data/Rakefile

@@ -7,7 +7,7 @@ require 'coveralls/rake/task'
 # Test unit
 Rake::TestTask.new do |t|
   t.libs << 'test'
-  t.test_files = FileList['test/test*.rb']
+  t.test_files = FileList['test/**/test*.rb']
   t.verbose = true
 end