goodsheet 0.2.1.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4c5b7ba40c72803a5496d2c8138e45c0d12b48e0
-  data.tar.gz: 2fe40921757862d1c4e1920bb88f91716d4294cf
+  metadata.gz: 9a61094f40016b3c32594b97b5d3e134c4b59016
+  data.tar.gz: 5fc1f3d8bbbdeaf1efafbceeb2610296004bce86
 SHA512:
-  metadata.gz: 823e26db17139b66e83446d6ad5df5b527bd743cebedf68d87e78039738d7f217ff06226c7992fc2239682e7d7395d37dba3ecb0cdc67d8264db7ce30b3c665f
-  data.tar.gz: a2e4a6b75ccf0d84fdb243e5c47c795ecdcc171186d8d0f8ab8b93d19dd19982b9f5bc4351f5b35b5b6a508aa2192de64ce4c39008672d26256644e2dfa2c153
+  metadata.gz: 0ff578441474684622d97d9e7481abb007783c6ee0fb302689377c081eff0662dda889766140dbe0d51e7b99d0e9ba0e0846deb7463c0df85994fe6a8c5a3d07
+  data.tar.gz: 50dcf983da1e79799d313366c47369d0b8569aad10ff6a9312ceae7c4eeae8d5b0229ef0b49dc30dda941434e315214450349a8c2723feb699272e5eb98c21dc

data/README.md

@@ -42,24 +42,87 @@ By default:
 
 Pass your validation rules into the block passed to the read method, together with the column_names method that define the position (or index) and the name of the columns you want to read.
 
-### More information on usage
+### More on usage
 
 You can select the desired sheet by index (starting from zero) or by name:
 ```ruby
 ss = Goodsheet::Spreadsheet.new("my_data.xlsx")
 ss.sheet(2) # select the third sheet
-ss.sheet("holydays")
-ss.sheets # get the sheet names array 
+ss.sheet("Sheet4") # select the sheet named "Sheet4"
 ```
-Get the 
 
+Get the number of sheets, and their names:
+```ruby
+ss.size # => 4
+ss.sheets # => ["Sheet1", "Sheet2", "Sheet3", "Sheet4"]
+```
 
+When you init a new spreadsheet, you select a sheet or you invoke `validate` or `read` method, you can pass an hash of options.
+```ruby
+ss = Goodsheet::Spreadsheet.new("my_data.xlsx", :skip => 1, :header_row => 0, :max_errors => 0, :row_limit => 0, :force_nil => nil )
+```
+These are the valid options with their default values:
+- `:skip` allow to skip a desired number of lines when you read or validate a sheet 
+- with `:header_row` you define the index of the header row
+- with `:max_errors` you define the maximum number of errors after the validation break
+- with `:row_limit` you define the maximum number of row you wanto to read or validate
+- with `:force_nil` you can specify the value to set when a cell hold a nil value (is empty)
+
+As said you can use the same option when selecting a sheet
+```ruby
+ss.sheet(0, :skip => 2)
+```
+or read or validate a sheet:
 ```ruby
+ss.validate(0, :force_nil => 0.0) do
+  # ...
+end
+```
 
+Get the content of header row:
+```ruby
+ss.header_row # => ["year", "month", "day"]
+```
 
+Get the number of rows:
+```ruby
+ss.total_rows # => all instanced rows
+ss.rows_wo_skipped # => except the skipped ones, aliased by `rows` method
+```
+
+#### Reading and validate
+
+Use the `validate` and `read` methods to perform validation and reading. Note that the reading function include a validation call.
+Pass the previously seen `options` hash and a block to `validate`/`read` method.
+Inside the block you define columns names and indexes you want to validate/read using the `column_names` method. You can use one of these 3 forms:
+- `column_names :a => 0, :b => 1, :c => 3`
+- `column_names 0 => :a, 1 => :b, 3 => :c`
+- `column_names [:a, :b, nil, :c]`
+
+Aside from define the columns settings, into block you define the validation rules. 
+Refer to the [official guide](http://guides.rubyonrails.org/active_record_validations.html) and [ROR Api](http://api.rubyonrails.org/classes/ActiveModel/Validations/ClassMethods.html)
+
+
+Another example:
+```ruby
+ss = Goodsheet::Spreadsheet.new("my_data.xlsx")
+ss.sheet(1, :max_errors => 50, :force_nil => 0.0)
+res = ss.read do
+  column_names :item => 0, :qty => 1, :price => 2, :prod => 3
+  # same as: [:item, :qty, :price, :prod]
+  validates :item, :presence => true
+  validates :qty, :presence => true, :numericality => { :greater_than => 0.0}
+  validates :price, :presence => true, :numericality => { :greater_than => 0.0}
+  validate :product
+
+  def :product
+    if qty * price != prod
+      errors.add(:prod, "must be the product of qty and price")
+    end
+  end
+end
 ```
 
-The +read+ method include the +validate+ method, that can be invoke 
 
 
 

data/lib/goodsheet/spreadsheet.rb

@@ -3,86 +3,151 @@ require 'roo'
 module Goodsheet
 
   class Spreadsheet < Roo::Spreadsheet
-    attr_reader :time_zone, :skip, :header_row, :max_errors, :row_limit
+    attr_reader :skip, :header_row, :max_errors, :row_limit
+    attr_reader :s_opts
 
-    # Initialize a Goodsheet object
+    # Initialize a Goodsheet object. The first sheet will be selected.
     #
-    # @param filename [String] the spreadsheet filename you want to read
-    # @param [String] filename the spreadsheet filename you want to read
-    # Valid options:
-    #    :skip       : number of rows to skip (default: 1)
-    #    :header_row : header's row index (0 based, default: 0)
-    #    :time_zone  : time zone string
+    # @param filename [String] The spreadsheet filename you want to read
+    # @param [Hash] options Options to define the behaviour on reading and validation the sheets. These options are applied to all sheets, but can be overwritten by similar options when selecting the sheet or calling +read+ or +validate+ method
+    # @option options [Fixnum] :skip (1) Number of rows to skip
+    # @option options [Fixnum] :header_row (0) The header row index (0-based)
+    # @option options [Fixnum] :max_errors (0) Max number of error until stop validation
+    # @option options [Fixnum] :row_limit (0) Max number of row to read
+    # @option options [Object] :force_nil (nil) Force nils found to this value
     def initialize(filename, options={})
-      set_options(options)
+      # set_book_options(options)
       @filename = filename
       @ss = Roo::Spreadsheet.open(filename, options)
+      @s_opts = Array.new(size, {})
+      size.times do |i|
+        set_sheet_options(i, options)
+      end
     end
     
 
-    # idx can be a number or a string
+    # Select the desidered sheet.
+    #
+    # @param idx [Fixnum, String] The index (0-based) or the name of the sheet to select
+    # @param [Hash] options Options to define the behaviour on reading and validation the sheet. These options are applied only to the current sheet, but can be overwritten by similar options when calling +read+ or +validate+ method
+    # @option options [Fixnum] :skip (1) Number of rows to skip
+    # @option options [Fixnum] :header_row (0) The header row index (0-based)
+    # @option options [Fixnum] :max_errors (0) Max number of error until stop validation
+    # @option options [Fixnum] :row_limit (0) Max number of row to read
+    # @option options [Object] :force_nil (nil) Force nils found to this value
     def sheet(idx, options={})
-      set_options(options)
+      check_sheet_exists(idx)
       @ss.sheet(idx)
-      check_sheet_exists
+      set_sheet_options(idx, options)
     end
 
+    # Get the sheet names list
+    #
+    # @return [Array<String>] An array with sheet names.
     def sheets
       @ss.sheets
     end
 
+    # Get the number of sheets
+    #
+    # @return [Fixnum] Number of sheets.
+    def size
+      @ss.sheets.size
+    end
 
+    # Get the options of current sheet
+    #
+    # @return [Fixnum] Number of sheets.
+    def options
+      @s_opts[index]
+    end
+
+
+    # Get the header row of the currently selected sheet
+    #
+    # @return [Array<Object>] An array cell content objects (String, Float, ...)
     def get_header
-      @ss.row(@header_row+1) # because roo in 1-based
+      @ss.row(@s_opts[index][:header_row]+1) # because roo in 1-based
     end
 
-    # Get the currently selected sheet's name
+    # Get the name of current (default) sheet
+    #
+    # @return [String] The sheet name
     def name
       @ss.default_sheet
     end
 
+    # Get the index of current (default) sheet
+    #
+    # @return [Fixnum] The sheet index
+    def index
+      @ss.sheets.index(@ss.default_sheet)
+    end
+
+    # Get the total number of rows (of the currently selected sheet)
+    #
+    # @return [Fixnum] The number of rows
     def total_rows
       @ss.parse.size
     end
 
-    def rows_wo_header
-      @ss.parse.size - @skip
+    # Get the number of all rows minus the skipped ones (of the currently selected sheet)
+    #
+    # @return [Fixnum] The number of rows
+    def rows_wo_skipped
+      @ss.parse.size - @s_opts[index][:skip]
     end
-    alias :rows :rows_wo_header
-
-    # Valid options:
-    #    :max_errors   : The validation will be stopped if the number of errors exceed max_errors (default: 0 or don't stop)
-    #    :limit        : Max number of rows to validate (default: 0 or validate all rows)
+    alias :rows :rows_wo_skipped
 
-    # 
+    # Validate the current sheet.
+    #
+    # @param [Hash] options Validation options for the current sheet. 
+    # @option options [Fixnum] :skip (1) Number of rows to skip
+    # @option options [Fixnum] :header_row (0) The header row index (0-based)
+    # @option options [Fixnum] :max_errors (0) Max number of error until stop validation
+    # @option options [Fixnum] :row_limit (0) Max number of row to read
+    # @option options [Object] :force_nil (nil) Force nils found to this value
+    # @yield Column settings and validation rules
+    # @return [ValidationErrors] Validation errors
     def validate(options={}, &block)
-      skip = options[:skip] || @skip
-      header_row = options[:header_row] || @header_row
-      max_errors = options[:max_errors] || @max_errors
-      row_limit = options[:row_limit] || @row_limit
+      # set_current_sheet_options(options)
+      skip = options[:skip] || @s_opts[index][:skip]
+      header_row = options[:header_row] || @s_opts[index][:header_row]
+      max_errors = options[:max_errors] || @s_opts[index][:max_errors]
+      row_limit = options[:row_limit] || @s_opts[index][:row_limit]
+      force_nil = options[:force_nil] || @s_opts[index][:force_nil]
 
       validation_errors = ValidationErrors.new
 
       my_class = options[:my_custom_row_class] || build_my_class(block)
 
-      line = skip # 0-based, from the top
-      @ss.parse[skip..-1].each do |row| # row is an array of elements
+      line = @s_opts[index][:skip] # 0-based, from the top
+      @ss.parse[@s_opts[index][:skip]..-1].each do |row| # row is an array of elements
         validation_errors.add(line, my_class.new(row))
         break if max_errors>0 && validation_errors.size >= max_errors
-        break if row_limit && row_limit>0 && line>=(row_limit+skip-1)
+        break if row_limit && row_limit>0 && line>=(row_limit+@s_opts[index][:skip]-1)
         line +=1
       end
       validation_errors
     end
 
 
-    # Columns must be an hash: labe for values and the column index like {:price => 5}
+    # Validate and, if successful, read the current sheet.
+    #
+    # @param [Hash] options Reading and validation options for the current sheet. 
+    # @option options [Fixnum] :skip (1) Number of rows to skip
+    # @option options [Fixnum] :header_row (0) The header row index (0-based)
+    # @option options [Fixnum] :max_errors (0) Max number of error until stop validation
+    # @option options [Fixnum] :row_limit (0) Max number of row to read
+    # @option options [Object] :force_nil (nil) Force nils found to this value
+    # @yield Column settings and validation rules
+    # @return [ReadResult] The result
     def read(options={}, &block)
-      skip = options[:skip] || @skip
-      header_row = options[:header_row] || @header_row
-      max_errors = options[:max_errors] || @max_errors
-      row_limit = options[:row_limit] || @row_limit
-      force_nil = options[:force_nil]
+      skip = options[:skip] || @s_opts[index][:skip]
+      header_row = options[:header_row] || @s_opts[index][:header_row]
+      max_errors = options[:max_errors] || @s_opts[index][:max_errors]
+      row_limit = options[:row_limit] || @s_opts[index][:row_limit]
+      force_nil = options[:force_nil] || @s_opts[index][:force_nil]
 
       my_class = build_my_class(block)
       options[:my_custom_row_class] = my_class
@@ -107,13 +172,21 @@ module Goodsheet
       Object.const_set get_custom_row_class_name, Row.inherit(block)
     end
 
-    def check_sheet_exists
-      begin
-        @ss.cell(1,1)
-      rescue ArgumentError => e
-        raise Goodsheet::SheetNotFoundError
-      rescue RangeError => e
-        raise Goodsheet::SheetNotFoundError
+    def select_sheet_options(idx)
+      if idx.is_a? Integer
+        @s_opts[idx]
+      elsif idx.is_a? String
+        @s_opts[@ss.sheets.index(idx)]
+      end
+    end
+
+    def check_sheet_exists(idx)
+      if idx.is_a? Integer
+        raise Goodsheet::SheetNotFoundError if idx < 0 || idx > (size-1)
+      elsif idx.is_a? String
+        raise Goodsheet::SheetNotFoundError if !@ss.sheets.include?(idx)
+      else
+        raise ArgumentError, "idx must be an Integer or a String"
       end
     end
 
@@ -121,12 +194,19 @@ module Goodsheet
       "CustRow_#{(Time.now.to_f*(10**10)).to_i}"
     end
 
-    def set_options(options)
-      @time_zone = options.delete(:zone) || "Rome"
-      @skip = options.delete(:skip) || 1
-      @header_row = options.delete(:header_row) || 0
-      @max_errors = options.delete(:max_errors) || 0
-      @row_limit = options.delete(:row_limit) || 0      
+    def set_current_sheet_options(options)
+      set_sheet_options(index, options)
+    end
+
+    def set_sheet_options(idx, options)
+      i = idx.is_a?(Integer) ? idx : @ss.sheets.index(idx)
+      @s_opts[i] = {
+        :skip => options[:skip] || @s_opts[i][:skip] || 1,
+        :header_row => options[:header_row] || @s_opts[i][:header_row] || 0,
+        :max_errors => options[:max_errors] || @s_opts[i][:max_errors] || 0,
+        :row_limit => options[:row_limit] || @s_opts[i][:row_limit] || 0,
+        :force_nil => options[:force_nil] || @s_opts[i][:force_nil] || nil
+      }
     end
   end
 end

data/lib/goodsheet/version.rb

@@ -1,3 +1,3 @@
 module Goodsheet
-  VERSION = "0.2.1.1"
+  VERSION = "0.2.2"
 end

data/test/test_spreadsheet_01.rb

@@ -104,6 +104,27 @@ class TestSpreadsheet_01 < Test::Unit::TestCase
     assert_equal(3, validation_errors.size) 
   end
 
+  def test_size
+    assert_equal(4, @ss.size)
+  end
+
+  def test_options_precedence
+    assert_equal({:skip=>1, :header_row=>0, :max_errors=>0, :row_limit=>0, :force_nil=>nil}, @ss.options)
+
+    # select "Sheet4" and change option
+    @ss.sheet(3, :force_nil => 0.0)
+    assert_equal({:skip=>1, :header_row=>0, :max_errors=>0, :row_limit=>0, :force_nil=>0.0}, @ss.options)
+
+    # reselect "Sheet1" and change option
+    @ss.sheet(0)
+    assert_equal({:skip=>1, :header_row=>0, :max_errors=>0, :row_limit=>0, :force_nil=>nil}, @ss.options)
+
+    # now validate with new options, but the sheet option must be unchanged
+    result = @ss.validate(:force_nil => 0.0, :skip => 6) do
+      # none
+    end
+    assert_equal({:skip=>1, :header_row=>0, :max_errors=>0, :row_limit=>0, :force_nil=>nil}, @ss.options)
+  end
 
   def test_read_sheet4
     @ss.sheet(3)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: goodsheet
 version: !ruby/object:Gem::Version
-  version: 0.2.1.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Iwan Buetti