dreader 0.3.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bcf3add7cb73aec5493fff9a1c7e4d7ceb2c7ca44e99771371be01280dc37c63
-  data.tar.gz: 9bebd3462c0d08828734bca84e5479c6f9b9d9cf5e26ded612df1c003e8e839f
+  metadata.gz: 2216ea348440adb3c2cff5236ae8b3a0d916e4576002b400b4d3121da650dc8e
+  data.tar.gz: 1d22f900bf6b578ddcbf28ab30cbf835cba6121dd6904f071690939ab7b84d5d
 SHA512:
-  metadata.gz: 313d5f5f97f854d319ccd13933be2951715d263a02b04c717e5e4462c75623b3710d103141b674f0ef81c1d2796c8c4401bc826dc5f4248a9510b78efe66a6ac
-  data.tar.gz: 5c255d01803921556f6f348ba342fa5f324f4c28764dd07400ad185880ec58dd1820c4b7ca29d2ca29685e28c9d25f1ecd290606de39017d440e965beeab607f
+  metadata.gz: 15a938341dfe5075bad0255fe4c623220c2f4cbd6a3e629410df1f6da58e2554bf7e5b15f17b641a57de45b694254771b9e58911d9c324582f786c8604db35c4
+  data.tar.gz: f02e9653e465e0eedf1d0feac0aecfbb20d7ae5177b51956a917159d4405d786a049d9bb840b8520223c6aeb7239fc1f8b954ac80caa07a322fe5d06f2aeb487

data/Changelog.org

@@ -0,0 +1,9 @@
+* Version 0.4.1
+** fixed an issue with ~read~: it always required a hash as input
+** changed syntax of ~debug~, which now accepts a hash as argument
+   This makes its syntax similar to ~read~.
+** improved output of ~debug~
+   By default ~debug~ now prints the output of ~process~ and ~check~.
+   You can disable this feature by passing ~process: false~ and/or ~check:
+   false~ to the ~debug~.  Notice that ~check~ implies ~process~.
+

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    dreader (0.3.0)
+    dreader (0.4.1)
       roo
 
 GEM

data/README.md

@@ -72,8 +72,9 @@ end
 where:
 
 * (optional) `filename` is the file to read.  If not specified, you
-  will have to supply a filename when loading the file.  The extension
-  determines the file type.  **Use `tsv` for tab-separated files.**
+  will have to supply a filename when loading the file (see `read`,
+  below).  The extension determines the file type.  **Use `tsv` for
+  tab-separated files.**
 * (optional) `first_row` is the first line to read (use `2` if your
   file has a header)
 * (optional) `last_row` is the last line to read. If not specified, we
@@ -88,7 +89,7 @@ column reference:
 
 ```ruby
 # we will access column A in Ruby code using :name
-i.column :name
+i.column :name do
   colref 'A'
 end
 ```
@@ -138,14 +139,18 @@ end
 
 **Remarks:**
 
-1. `colref` can be a string (e.g., `'A'`) or an integer, in which case
+1. the column name can be anything ruby can use as a Hash key.  You
+   can use symbols, strings, and even object instances, if you wish to
+   do so.
+
+2. `colref` can be a string (e.g., `'A'`) or an integer, in which case
    the first column is one
  
-2. you need to declare only the columns you want to import.  For
+3. you need to declare only the columns you want to import.  For
    instance, we could skip the declaration for column 1, if 'Date of
    Birth' is the only data we want to import
 
-3. If `process` and `check` are specified, then `check` will receive
+4. If `process` and `check` are specified, then `check` will receive
    the result of invoking `process` on the cell value.  This makes
    sense if process is used to make the cell value more accessible to
    ruby code (e.g., transforming a string into an integer).
@@ -198,6 +203,7 @@ Notice that the data read from each row of our input data is stored in
 a hash.  The hash uses column names as the primary key and stores
 the values in the `:value` key.
 
+
 ### Start working with the data
 
 We are now all set and we can start working with the data.
@@ -209,8 +215,8 @@ into a `@table` instance variable.
 i.read
 ```
 
-Read applies all the `column` and `virtual_column` declarations and
-buils a hash with the data read.
+**Read applies all the `column` and `virtual_column` declarations and
+builds a hash with the data read.**
 
 After reading the file we can use `errors` to see whether any of the
 `check` functions failed:
@@ -232,6 +238,17 @@ i.process
 Look in the examples directory for further details and a couple of
 working examples.
 
+**Remark.** You can override some of the defaults by passing a hash as
+argument to read.  For instance:
+
+```ruby
+i.read filename: another_filepath
+```
+
+will read data from `another_filepath`, rather than from the filename
+specified in the options.  This might be useful, for instance, if the
+same specification has to be used for different files.
+
 
 ## Digging deeper
 
@@ -324,13 +341,30 @@ shows them to standard output:
 
 ```ruby
 i.debug
-i.debug 40 # read 40 lines (from first_row, if the option is declared)
-i.debug 40, filename # like above, but read from filename
+i.debug n: 40 # read 40 lines (from first_row, if the option is declared)
+i.debug n: 40, filename: filepath # like above, but read from filepath
 ```
 
 Another possibility is getting the value of the `@table` variable,
 which contains all the data read.
 
+By default `debug` invokes the `process` and `check` directives.  Pass
+the following options, if you want to disable this behavior; this
+might be useful, for instance, if you intend to check only what data
+is read:
+
+```ruby
+i.debug process: false, debug: false
+```
+
+Notice that `check` implies `process`, since `check` is invoked on the
+output of the `process` directive.`
+
+
+## Changelog
+
+See [[Changelog]].
+
 
 ## Known Limitations
 
@@ -343,6 +377,7 @@ At the moment:
   correctly parsed.
 - some testing wouldn't hurt.
 
+
 ## Known Bugs
 
 No known bugs and an unknown number of unknown bugs.

data/examples/age/age.rb

@@ -33,7 +33,7 @@ i.mapping do |row|
   puts "#{r[:name]} is #{r[:age]} years old (born on #{r[:birthdate]})"
 end
 
-i.read "Birthdays.ods"
+i.read filename: "Birthdays.ods"
 i.virtual_columns
 i.process
 

data/examples/wikipedia_us_cities/us_cities.rb

@@ -43,6 +43,10 @@ importer.column :population do |col|
     value.gsub(",", "").to_i
   end
 
+  col.check do |value|
+    value > 0
+  end
+
 end
 
 cities = []
@@ -67,7 +71,11 @@ end
 
 # print to stdout what we told dreader to read
 # (useful only for ... debugging!)
-importer.debug 10
+importer.debug n: 10
+
+# check some other features of debug:
+# disable processing and debug (e.g., to analyze the raw data read)
+importer.debug process: false, check: false
 
 # load and process
 importer.load

data/lib/dreader/version.rb

@@ -1,3 +1,3 @@
 module Dreader
-  VERSION = "0.3.1"
+  VERSION = "0.4.1"
 end

data/lib/dreader.rb

@@ -156,19 +156,27 @@ module Dreader
     end
 
     # read a file and store it internally
-    # return the data we read in the form of an array of hashes
-    def read filename = nil
-      spreadsheet = Dreader::Engine.open_spreadsheet (filename || @options[:filename])
-      sheet = spreadsheet.sheet(@options[:sheet] || 0)
+    #
+    # @param hash, a hash, possibly overriding any of the parameters
+    #              set in the initial options.  This allows you, for
+    #              instance, to apply the same column specification to
+    #              different files and different sheets
+    #
+    # @return the data read from filename, in the form of an array of
+    #         hashes
+    def read args = {}
+      hash = @options.merge(args)
+
+      spreadsheet = Dreader::Engine.open_spreadsheet (hash[:filename])
+      sheet = spreadsheet.sheet(hash[:sheet] || 0)
 
       @table = Array.new
       @errors = Array.new
 
-      first_row = @options[:first_row] || 1
-      last_row = @options[:last_row] || sheet.last_row
+      first_row = hash[:first_row] || 1
+      last_row = hash[:last_row] || sheet.last_row
 
       (first_row..last_row).each do |row_number|
-
         r = Hash.new
         @colspec.each_with_index do |colspec, index|
           cell = sheet.cell(row_number, colspec[:colref])
@@ -199,29 +207,55 @@ module Dreader
 
     # show to stdout the first `n` records we read from the file given the current
     # configuration
-    def debug n = 10, filename = nil
-      spreadsheet = Dreader::Engine.open_spreadsheet (filename || @options[:filename])
-      sheet = spreadsheet.sheet(@options[:sheet] || 0)
+    def debug args = {}
+      hash = @options.merge(args)
+
+      # apply some defaults, if not defined in the options
+      hash[:process] = true if not hash.has_key? :process # shall we apply the process function?
+      hash[:check] = true if not hash.has_key? :check     # shall we check the data read?
+      hash[:n] = 10 if not hash[:n]
+
+      spreadsheet = Dreader::Engine.open_spreadsheet (hash[:filename])
+      sheet = spreadsheet.sheet(hash[:sheet] || 0)
 
       puts "Current configuration:"
       @options.each do |k, v|
         puts "  #{k}: #{v}"
       end
-      if filename and @options[:filename] and filename != @options[:filename]
-        puts "Warning: you asked me to load a file different from the one specified in the otptions."
-      end
 
-      first_row = @options[:first_row] || 1
+      puts "Configuration used by debug:"
+      hash.each do |k, v|
+        puts "  #{k}: #{v}"
+      end
+     
+      n = hash[:n]
+      first_row = hash[:first_row] || 1
       last_row = first_row + n - 1
-      puts "I will read rows #{first_row} to #{last_row} (#{n} records) from '#{filename || @options[:filename]}'"
+
+      puts "  Last row (according to roo): #{sheet.last_row}"
+      puts "  Number of rows I will read in this session: #{n} (from #{first_row} to #{last_row})"
+      
       (first_row..last_row).each do |row_number|
         puts "Row #{row_number} is:"
         r = Hash.new
         @colspec.each_with_index do |colspec, index|
-          cell = sheet.cell(row_number, colspec[:colref])
           colname = colspec[:name]
+          cell = sheet.cell(row_number, colspec[:colref])
+
+          processed_str = ""
+          checked_str = ""
+          
+          if hash[:process]
+            processed = colspec[:process] ? colspec[:process].call(cell) : cell
+            processed_str = "processed: '#{processed}' (#{processed.class})"
+          end
+          if hash[:check]
+            processed = colspec[:process] ? colspec[:process].call(cell) : cell
+            check = colspec[:check] ? colspec[:check].call(processed) : "no check specified"
+            checked_str = "checked: '#{check}'"
+          end
 
-          puts "  #{colname} => '#{cell}' (column: '#{colspec[:colref]}')"
+          puts "  #{colname} => orig: '#{cell}' (#{cell.class}) #{processed_str} #{checked_str} (column: '#{colspec[:colref]}')"
         end
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dreader
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.1
 platform: ruby
 authors:
 - Adolfo Villafiorita
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-03-29 00:00:00.000000000 Z
+date: 2018-04-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -69,6 +69,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- Changelog.org
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt