culturecode-roo 2.0.1 → 2.0.2

data/README.md

@@ -1,121 +1,254 @@
-# Roo [![Build Status](https://travis-ci.org/roo-rb/roo.svg)](https://travis-ci.org/roo-rb/roo)[![Code Climate](https://codeclimate.com/github/roo-rb/roo/badges/gpa.svg)](https://codeclimate.com/github/roo-rb/roo)[![Coverage Status](https://coveralls.io/repos/roo-rb/roo/badge.png)](https://coveralls.io/r/roo-rb/roo)
+# 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)
+
+Roo implements read access for all common spreadsheet types. It can handle:
 
-Roo implements read access for all spreadsheet types and read/write access for
-Google spreadsheets. It can handle
 * Excelx
 * OpenOffice / LibreOffice
 * CSV
 
-## Additional libraries
+## Additional Libraries
+
+In addition, the [roo-xls](https://github.com/roo-rb/roo-xls) and [roo-google](https://github.com/roo-rb/roo-google) gems exist to extend Roo to support reading classic Excel formats (i.e. `.xls` and ``Excel2003XML``) and read/write access for Google spreadsheets.
+
+# #Installation
+
+Install as a gem
 
-In addition, the roo-xls and roo-google gems exist to Google Spreadsheet add classic Excel
-handling capabilities to roo.
+    $ gem install roo
 
-## Usage:
+Or add it to your Gemfile
+
+```ruby
+gem 'roo', '~> 2.0.0'
+```
+## Usage
+
+Opening a spreadsheet
 
 ```ruby
 require 'roo'
 
-s = Roo::OpenOffice.new("myspreadsheet.ods")      # loads an OpenOffice Spreadsheet
-s = Roo::OpenOffice.new("myspreadsheet.ods", :password => "password") # loads an encrypted OpenOffice Spreadsheet
-s = Roo::Excelx.new("myspreadsheet.xlsx")         # loads an Excel Spreadsheet for Excel .xlsx files
-s = Roo::CSV.new("mycsv.csv")                     # loads a CSV file
+xlsx = Roo::Spreadsheet.open('./new_prices.xlsx')
+xlsx = Roo::Excelx.new("./new_prices.xlsx")
 
-# You can use CSV to load TSV files, or files of a certain encoding by passing
-# in options under the :csv_options key
-s = Roo::CSV.new("mytsv.tsv", csv_options: {col_sep: "\t"}) # TSV
-s = Roo::CSV.new("mycsv.csv", csv_options: {encoding: Encoding::ISO_8859_1}) # csv with explicit encoding
+# Use the extension option if the extension is ambiguous.
+xlsx = Roo::Spreadsheet.open('./rails_temp_upload', extension: :xlsx)
 
-s.default_sheet = s.sheets.first             # first sheet in the spreadsheet file will be used
+xlsx.info
+# => Returns basic info about the spreadsheet file
+```
 
-# s.sheets is an array which holds the names of the sheets within
-# a spreadsheet.
-# you can also write
-# s.default_sheet = s.sheets[3] or
-# s.default_sheet = 'Sheet 3'
+``Roo::Spreadsheet.open`` can accept both paths and ``File`` instances.
 
-s.cell(1,1)                                 # returns the content of the first row/first cell in the sheet
-s.cell('A',1)                               # same cell
-s.cell(1,'A')                               # same cell
-s.cell(1,'A',s.sheets[0])                   # same cell
+### Working with sheets
 
-# almost all methods have an optional argument 'sheet'.
-# If this parameter is omitted, the default_sheet will be used.
+```ruby
+ods.sheets
+# => ['Info', 'Sheet 2', 'Sheet 3']   # an Array of sheet names in the workbook
 
-s.info                                      # Returns basic info about the spreadsheet file
+ods.sheet('Info').row(1)
+ods.sheet(0).row(1)
 
-s.first_row                                 # the number of the first row
-s.last_row                                  # the number of the last row
-s.first_column                              # the number of the first column
-s.last_column                               # the number of the last column
+# Set the last sheet as the default sheet.
+ods.default_sheet = ods.sheets.last
+ods.default_sheet = s.sheets[3]
+ods.default_sheet = 'Sheet 3'
 
-# limited font information is available
+# Iterate through each sheet
+ods.each_with_pagename do |name, sheet|
+  p sheet.row(1)
+end
+```
 
-s.font(1,1).bold?
-s.font(1,1).italic?
-s.font(1,1).underline?
+### Accessing rows and columns
 
+Roo uses Excel's numbering for rows, columns and cells, so `1` is the first index, not `0` as it is in an ``Array``
 
-# Roo::Spreadsheet requires spreadsheet gem
-require 'spreadsheet'
+```ruby
+sheet.row(1)
+# returns the first row of the spreadsheet.
 
-# Spreadsheet.open can accept both files and paths
+sheet.column(1)
+# returns the first column of the spreadsheet.
+```
 
-xls = Roo::Spreadsheet.open('./new_prices.xls')
+Almost all methods have an optional argument `sheet`. If this parameter is omitted, the default_sheet will be used.
 
-# If the File.path or provided path string does not have an extension, you can optionally
-# provide one as a string or symbol
+```ruby
+sheet.first_row(sheet.sheets[0])
+# => 1             # the number of the first row
+sheet.last_row
+# => 42            # the number of the last row
+sheet.first_column
+# => 1             # the number of the first column
+sheet.last_column
+# => 10            # the number of the last column
+```
 
-xls = Roo::Spreadsheet.open('./rails_temp_upload', extension: :xls)
+#### Accessing cells
 
-# no more setting xls.default_sheet, just use this
+You can access the top-left cell in the following ways
 
-xls.sheet('Info').row(1)
-xls.sheet(0).row(1)
+```ruby
+s.cell(1,1)
+s.cell('A',1)
+s.cell(1,'A')
+s.a1
 
-# excel likes to create random "Data01" sheets for macros
-# use this to find the sheet with the most data to parse
+# Access the second sheet's top-left cell.
+s.cell(1,'A',s.sheets[1])
+```
 
-xls.longest_sheet
+#### Querying a spreadsheet
+Use ``each`` with a ``block`` to iterate over each row.
 
-# this excel file has multiple worksheets, let's iterate through each of them and process
+If each is given a hash with the names of some columns, then each will generate a hash with the columns supplied for each row.
 
-xls.each_with_pagename do |name, sheet|
-  p sheet.row(1)
+```ruby
+sheet.each(id: 'ID', name: 'FULL_NAME') do |hash|
+  puts hash.inspect
+  # => { id: 1, name: 'John Smith' }
 end
+```
 
-# pull out a hash of exclusive column data (get rid of useless columns and save memory)
+Use ``sheet.parse`` to return an array of rows. Column names can be a ``String`` or a ``Regexp``.
 
-xls.each(:id => 'UPC',:qty => 'ATS') {|hash| arr << hash}
-#=> hash will appear like {:upc=>727880013358, :qty => 12}
+```ruby
+sheet.parse(:id => /UPC|SKU/,:qty => /ATS*\sATP\s*QTY\z/)
+# => [{:upc => 727880013358, :qty => 12}, ...]
+```
 
-# NOTE: .parse does the same as .each, except it returns an array (similar to each vs. map)
+Use the ``:header_search`` option to locate the header row and assign the header names.
 
-# not sure exactly what a column will be named? try a wildcard search with a regex
+```ruby
+sheet.parse(header_search: [/UPC*SKU/,/ATS*\sATP\s*QTY\z/])
+```
 
-xls.parse(:id => /UPC|SKU/,:qty => /ATS*\sATP\s*QTY\z/)
+Use the ``:clean`` option to strip out control characters and surrounding white space.
 
-# if you need to locate the header row and assign the header names themselves,
-# use the :header_search option
+```ruby
+sheet.parse(:clean => true)
+```
 
-xls.parse(:header_search => [/UPC*SKU/,/ATS*\sATP\s*QTY\z/])
-#=> each element will appear in this fashion:
-#=> {"UPC" => 123456789012, "STYLE" => "987B0", "COLOR" => "blue", "QTY" => 78}
+### Exporting spreadsheets
+Roo has the ability to export sheets using the following formats. It
+will only export the ``default_sheet``.
 
-# want to strip out annoying unicode characters and surrounding white space?
+```ruby
+sheet.to_csv
+sheet.to_matrix
+sheet.to_xml
+sheet.to_yaml
+```
+
+### Excel (xlsx) Support
 
-xls.parse(:clean => true)
+Stream rows from an Excelx spreadsheet.
 
-# another bonus feature is a patch to prevent the Spreadsheet gem from parsing
-# thousands and thousands of blank lines. i got fed up after watching my computer
-# nearly catch fire for 4 hours for a spreadsheet with only 200 ACTUAL lines
-# - located in lib/roo/worksheet.rb
+```ruby
+xlsx = Roo::Excelx.new("./test_data/test_small.xlsx")
+xlsx.each_row_streaming do |row|
+  puts row.inspect # Array of Excelx::Cell objects
+end
+```
 
-# if you want to load and stream .xlsx rows
+Iterate over each row
 
-s = Roo::Excelx.new("./test_data/test_small.xlsx")
-s.each_row_streaming do |row|
-    puts row.inspect # Array of Excelx::Cell objects
+```ruby
+xlsx.each_row do |row|
+  ...
 end
+```
+
+``Roo::Excelx`` also provides these helpful methods.
+
+```ruby
+xlsx.excelx_type(3, 'C')
+# => :numeric_or_formula
+
+xlsx.cell(3, 'C')
+# => 600000383.0
+
+xlsx.excelx_value(row,col)
+# => '0600000383'
+```
+
+``Roo::Excelx`` can access celltype, comments, font information, formulas, hyperlinks and labels.
+
+```ruby
+xlsx.comment(1,1, ods.sheets[-1])
+xlsx.font(1,1).bold?
+xlsx.formula('A', 2)
+```
+
+### OpenOffice / LibreOffice Support
+
+Roo::OpenOffice supports for encrypted OpenOffice spreadsheets.
 
+```ruby
+# Load an encrypted OpenOffice Spreadsheet
+ods = Roo::OpenOffice.new("myspreadsheet.ods", :password => "password")
+```
+
+``Roo::OpenOffice`` can access celltype, comments, font information, formulas and labels.
+
+```ruby
+ods.celltype
+# => :percentage
+
+ods.comment(1,1, ods.sheets[-1])
+
+ods.font(1,1).italic?
+# => false
+
+ods.formula('A', 2)
 ```
+
+### CSV Support
+
+```ruby
+# Load a CSV file
+s = Roo::CSV.new("mycsv.csv")
+```
+
+Because Roo uses the [standard CSV library](), and 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"})
+
+# Load a csv with an explicit encoding
+s = Roo::CSV.new("mycsv.csv", csv_options: {encoding: Encoding::ISO_8859_1})
+```
+
+## Upgrading from Roo 1.13.x
+If you use ``.xls`` or Google spreadsheets, you will need to install ``roo-xls`` or ``roo-google`` to continue using that functionality.
+
+Roo's public methods have stayed relatively consistent between 1.13.x and 2.0.0, but please check the [Changelog](https://github.com/roo-rb/roo/blob/master/CHANGELOG.md) to better understand the changes made since 1.13.x.
+
+
+
+## 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
+
+### Issues
+
+If you find an issue, please create a gist and refer to it in an issue ([sample gist](https://gist.github.com/stevendaniels/98a05849036e99bb8b3c)). Here are some instructions for creating such a gist.
+
+1. [Create a gist](https://gist.github.com) with code that creates the error.
+2. Clone the gist repo locally, add a stripped down version of the offending spreadsheet to the gist repo, and push the gist's changes master.
+3. Paste the gist url here.
+
+
+## License
+[Roo uses an MIT License](https://github.com/roo-rb/roo/blob/master/LICENSE)

data/lib/roo.rb

@@ -1,7 +1,7 @@
-module Roo
-  autoload :Spreadsheet,  'roo/spreadsheet'
-  autoload :Base,         'roo/base'
+require 'roo/spreadsheet'
+require 'roo/base'
 
+module Roo
   autoload :OpenOffice,   'roo/open_office'
   autoload :LibreOffice,  'roo/libre_office'
   autoload :Excelx,       'roo/excelx'

data/lib/roo/base.rb

@@ -9,7 +9,7 @@ require 'roo/utils'
 class Roo::Base
   include Enumerable
 
-  TEMP_PREFIX = 'roo_'
+  TEMP_PREFIX = 'roo_'.freeze
   MAX_ROW_COL = 999_999.freeze
   MIN_ROW_COL = 0.freeze
 
@@ -32,6 +32,15 @@ class Roo::Base
     @last_column = {}
 
     @header_line = 1
+  rescue => e # clean up any temp files, but only if an error was raised
+    close
+    raise e
+  end
+
+  def close
+    return nil unless @tmpdirs
+    @tmpdirs.each { |dir| ::FileUtils.remove_entry(dir) }
+    nil
   end
 
   def default_sheet
@@ -160,9 +169,8 @@ class Roo::Base
     end)
   end
 
-  # call to_s method defined on subclasses
   def inspect
-    to_s
+    "<##{ self.class }:#{ self.object_id.to_s(8) } #{ self.instance_variables.join(' ') }>"
   end
 
   # find a row either by row number or a condition
@@ -321,26 +329,6 @@ class Roo::Base
     end
   end
 
-
-  def clean_sheet_if_need(options)
-    return unless options[:clean]
-    options.delete(:clean)
-    @cleaned ||= {}
-    clean_sheet(default_sheet) unless @cleaned[default_sheet]
-  end
-
-  def search_or_set_header(options)
-    if options[:header_search]
-      @headers = nil
-      @header_line = row_with(options[:header_search])
-    elsif [:first_row, true].include?(options[:headers])
-      @headers = []
-      row(first_row).each_with_index { |x, i| @headers << [x, i + 1] }
-    else
-      set_headers(options)
-    end
-  end
-
   # by passing in headers as options, this method returns
   # specific columns from your header assignment
   # for example:
@@ -361,11 +349,13 @@ class Roo::Base
   # * is the wildcard character
 
   # you can also pass in a :clean => true option to strip the sheet of
-  # odd unicode characters and white spaces around columns
+  # control characters and white spaces around columns
 
   def each(options = {})
-    if options.empty?
-      1.upto(last_row) do |line|
+    if first_row.nil?
+      # Sheet is empty
+    elsif options.empty?
+      first_row.upto(last_row) do |line|
         yield row(line)
       end
     else
@@ -450,9 +440,37 @@ class Roo::Base
     "#{arr[0]},#{arr[1]}"
   end
 
+  def is_stream?(filename_or_stream)
+    filename_or_stream.respond_to?(:seek)
+  end
+
   private
 
+  def track_tmpdir!(tmpdir)
+    (@tmpdirs ||= []) << tmpdir
+  end
+
+  def clean_sheet_if_need(options)
+    return unless options[:clean]
+    options.delete(:clean)
+    @cleaned ||= {}
+    clean_sheet(default_sheet) unless @cleaned[default_sheet]
+  end
+
+  def search_or_set_header(options)
+    if options[:header_search]
+      @headers = nil
+      @header_line = row_with(options[:header_search])
+    elsif [:first_row, true].include?(options[:headers])
+      @headers = []
+      row(first_row).each_with_index { |x, i| @headers << [x, i + 1] }
+    else
+      set_headers(options)
+    end
+  end
+
   def local_filename(filename, tmpdir, packed)
+    return if is_stream?(filename)
     filename = download_uri(filename, tmpdir) if uri?(filename)
     filename = unzip(filename, tmpdir) if packed == :zip
     unless File.file?(filename)
@@ -518,21 +536,21 @@ class Roo::Base
     else
       TEMP_PREFIX
     end
-    Dir.mktmpdir(prefix, root || ENV['ROO_TMP'], &block)
+    ::Dir.mktmpdir(prefix, root || ENV['ROO_TMP'], &block).tap do |result|
+      block_given? || track_tmpdir!(result)
+    end
   end
 
   def clean_sheet(sheet)
     read_cells(sheet)
     @cell[sheet].each_pair do |coord, value|
-      if value.is_a?(::String)
-        @cell[sheet][coord] = sanitize_value(value)
-      end
+      @cell[sheet][coord] = sanitize_value(value) if value.is_a?(::String)
     end
     @cleaned[sheet] = true
   end
 
   def sanitize_value(v)
-    v.unpack('U*').select { |b| b < 127 }.pack('U*').strip
+    v.gsub(/[[:cntrl:]]|^[\p{Space}]+|[\p{Space}]+$/, '')
   end
 
   def set_headers(hash = {})
@@ -703,8 +721,6 @@ class Roo::Base
     end
   end
 
-  private
-
   # converts an integer value to a time string like '02:05:06'
   def integer_to_timestring(content)
     h = (content / 3600.0).floor