honey_format 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ec17df72ebcb22be2365a454c19632f6ee22becc155a525bf66a010f7eec4b2
-  data.tar.gz: b05efbc59d1af2da443fd4c3e72cf573d9fd43b292b644336299411e705a77e3
+  metadata.gz: 1c3b35ed8d8cac5eace438a1eb5365b4970d96e2fee1a3faece4555eae44f1a3
+  data.tar.gz: 01ed3a3b5bc973b5882c6ec2f61c647bf24d0edadd76c7155568e2a6c2cbcbbb
 SHA512:
-  metadata.gz: b802e64d2033b5ea9881b30142e88f9d326e7d89416deadd7aa3c2f49c6da3f5b7a03fda057a802a9cebff28c72d5c75cfe48e9fa3a93e68ac808beb480b3d42
-  data.tar.gz: 71682b5a17dae461bbdabece49219e76be07241494b3606849ec5e7198bcf9e6f8e470a0e5a857ff879d5cc48ea796214a93d3ac0793cffb3feb29842e15486e
+  metadata.gz: af026b70d5fa369633788e5be0796723161b8564aca45084e704fa0691ad7da1fbe1a4578262dec60806d71fe1757984630c8d3e7be1fc4df276b0c3bf3cac1f
+  data.tar.gz: 267b348cff25cffb1204e26ec4f34f60fafb4154b44afa6005599bfd71ab8946024be7fd56deca52ff5c5ee31f53fe4f4ab79fd25ead5df0ad79ece91cfdeb5d

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+# v0.7.0
+
+- Don't sanitize each row :rocket: (improves performance from ~1.4x times slower than raw CSV to ~1.1)
+- Fold `Columns` class into `Header`
+- Remove `Sanitize` class
+
 # v0.6.0
 
 * Add `CSV#to_csv` ([PR#2](https://github.com/buren/honey_format/pull/2))

data/README.md

@@ -49,11 +49,30 @@ user.id         # => "1"
 user.username   # => "buren"
 ```
 
-Custom row builder
+Minimal custom row builder
 ```ruby
 csv_string = "Id, Username\n 1, buren"
-upcase_builder = ->(o) { o.is_a?(String) ? o.upcase : o  }
-csv = HoneyFormat::CSV.new(csv_string, row_builder: upcase_builder)
+upcaser = ->(row) { row.username.upcase!; row }
+csv = HoneyFormat::CSV.new(csv_string, row_builder: upcaser)
+csv.rows # => [#<struct id="1", username="BUREN">]
+```
+
+Complete custom row builder
+```ruby
+class Anonymizer
+  def self.call(row)
+    # Return an object you want to represent the row
+    row.tap do |r|
+      r.name = '<anon>'
+      r.email = '<anon>'
+      r.ssn = '<anon>'
+      r.payment_id = '<scrubbed>'
+    end
+  end
+end
+
+csv_string = "Id, Username\n 1, buren"
+csv = HoneyFormat::CSV.new(csv_string, row_builder: Anonymizer)
 csv.rows # => [#<struct id="1", username="BUREN">]
 ```
 
@@ -65,6 +84,11 @@ csv.rows.each { |row| row.id = nil }
 csv.to_csv # => "Id, Username\n,buren\n"
 ```
 
+You can of course set the delimiter
+```ruby
+HoneyFormat::CSV.new(csv_string, delimiter: ';')
+```
+
 Validate CSV header
 ```ruby
 csv_string = "Id, Username\n 1, buren"
@@ -85,17 +109,29 @@ csv.rows.first.username # => "buren"
 ```
 
 If your header contains special chars and/or chars that can't be part of Ruby method names,
-things get a little awkward..
+things can get a little awkward..
 ```ruby
 csv_string = "ÅÄÖ\nSwedish characters"
 user = HoneyFormat::CSV.new(csv_string).rows.first
-# Note that these chars aren't "downcased",
+# Note that these chars aren't "downcased" in Ruby 2.3 and older versions of Ruby,
 # "ÅÄÖ".downcase # => "ÅÄÖ"
 user.ÅÄÖ # => "Swedish characters"
+# while on Ruby > 2.3
+user.åäö
 
-csv_string = "First-Name\nJacob"
+csv_string = "First^Name\nJacob"
 user = HoneyFormat::CSV.new(csv_string).rows.first
-user.public_send(:"first-name") # => "Jacob"
+user.public_send(:"first^name") # => "Jacob"
+```
+
+Pass your own header converter
+```ruby
+map = { 'First^Name' => :first_name }
+converter = ->(column) { map.fetch(column, column) }
+
+csv_string = "First^Name\nJacob"
+user = HoneyFormat::CSV.new(csv_string, header_converter: converter).rows.first
+user.first_name # => "Jacob"
 ```
 
 If you want to see more usage examples check out the `spec/` directory.
@@ -113,15 +149,15 @@ $ bin/benchmark file.csv
 204KB (1k lines)
 
 ```
-      stdlib CSV:   48.9 i/s
-HoneyFormat::CSV:   34.5 i/s - 1.41x  slower
+      stdlib CSV:       51.9 i/s
+HoneyFormat::CSV:       49.6 i/s - 1.05x  slower
 ```
 
 19MB (100k lines)
 
 ```
-      stdlib CSV:   0.4 i/s
-HoneyFormat::CSV:   0.3 i/s - 1.41x  slower
+      stdlib CSV:        0.4 i/s
+HoneyFormat::CSV:        0.4 i/s - 1.11x  slower
 ```
 
 ## Development

data/lib/honey_format/csv.rb

@@ -1,6 +1,5 @@
 require 'csv'
 
-require 'honey_format/sanitize'
 require 'honey_format/rows'
 require 'honey_format/header'
 
@@ -9,27 +8,29 @@ module HoneyFormat
   class CSV
     # @return [CSV] a new instance of CSV.
     # @param [String] csv string.
-    # @param [Array] valid_columns valid array of symbols representing valid columns.
-    # @param [Array] header optional argument for CSV header
+    # @param [Array<Symbol>] valid_columns valid array of symbols representing valid columns if empty all will be considered valid.
+    # @param [Array<String>] header optional argument for CSV header
     # @param [#call] row_builder will be called for each parsed row
     # @raise [MissingCSVHeaderError] raised when header is missing (empty or nil).
     # @raise [MissingCSVHeaderColumnError] raised when header column is missing.
     # @raise [UnknownCSVHeaderColumnError] raised when column is not in valid list.
-    def initialize(csv, delimiter: ',', header: nil, valid_columns: :all, header_converter: ConvertHeaderValue, row_builder: nil)
+    def initialize(csv, delimiter: ',', header: nil, valid_columns: [], header_converter: ConvertHeaderValue, row_builder: nil)
       csv = ::CSV.parse(csv, col_sep: delimiter)
       header_row = header || csv.shift
       @header = Header.new(header_row, valid: valid_columns, converter: header_converter)
       @rows = Rows.new(csv, columns, builder: row_builder)
     end
 
-    # @return [Array] of strings for sanitized header.
+    # Original CSV header
+    # @return [Array<String>] of strings for sanitized header.
     def header
-      @header.column_names
+      @header.original
     end
 
-    # @return [Array] of column identifiers.
+    # CSV columns
+    # @return [Array<Symbol>] of column identifiers.
     def columns
-      @header.columns
+      @header.to_a
     end
 
     # @return [Array] of rows.
@@ -38,11 +39,16 @@ module HoneyFormat
       @rows
     end
 
-    # @yield [row] block to receive the row.
+    # @yield [row] The given block will be passed for every row.
+    # @yieldparam [Row] a colmn in the CSV header.
+    # @return [Enumerator] If no block is given, an enumerator object will be returned.
     def each_row
+      return rows.each unless block_given?
+
       rows.each { |row| yield(row) }
     end
 
+    # Convert CSV object as CSV-string.
     # @return [String] CSV-string representation.
     def to_csv
       header.to_csv + @rows.to_csv

data/lib/honey_format/header.rb

@@ -1,32 +1,79 @@
-require 'honey_format/columns'
+require 'honey_format/convert_header_value'
 
 module HoneyFormat
   # Represents a header
   class Header
-    attr_reader :column_names
+    include Enumerable
 
+    # Instantiate a Header
     # @return [Header] a new instance of Header.
-    # @param [Array] header array of strings.
-    # @param [Array] valid array of symbols representing valid columns.
-    # @raise [MissingCSVHeaderError] raised when header is missing (empty or nil).
-    def initialize(header, valid: :all, converter: ConvertHeaderValue)
+    # @param [Array<String>] header array of strings.
+    # @param [Array<Symbol>] valid array of symbols representing valid columns if empty all columns will be considered valid.
+    # @param converter [#call] header converter that implements a #call method that takes one column (string) argument.
+    # @raise [MissingCSVHeaderColumnError] raised when header is missing
+    # @raise [UnknownCSVHeaderColumnError] raised when column is not in valid list.
+    # @example Instantiate a header with a customer converter
+    #     converter = ->(col) { col == 'username' ? 'handle' : col }
+    #     header = HoneyFormat::Header.new(['name', 'username'], converter: converter)
+    #     header.to_a # => ['name', 'handle']
+    def initialize(header, valid: [], converter: ConvertHeaderValue)
       if header.nil? || header.empty?
-        fail(MissingCSVHeaderError, "CSV header can't be empty.")
+        raise(MissingCSVHeaderError, "CSV header can't be empty.")
       end
 
-      @column_names = Sanitize.array(header)
-      @columns = Columns.new(@column_names, valid: valid, converter: converter)
+      @original_header = header.map { |col| col ? col.strip : nil }
+      @converter = converter
+      @columns = build_columns(@original_header, valid)
+    end
+
+    # @return [Array<String>] the original header
+    def original
+      @original_header
+    end
+
+    # @yield [row] The given block will be passed for every column.
+    # @yieldparam [Row] a colmn in the CSV header.
+    # @return [Enumerator]
+    #   If no block is given, an enumerator object will be returned.
+    def each(&block)
+      @columns.each(&block)
     end
 
     # Returns columns as array.
-    # @return [Array] of columns.
-    def columns
-      @columns.to_a
+    # @return [Array<Symbol>] of columns.
+    def to_a
+      @columns
     end
 
+    # Header as CSV-string
     # @return [String] CSV-string representation.
     def to_csv
-      columns.to_csv
+      @columns.to_csv
+    end
+
+    private
+
+    # Convert original header
+    # @param [Array<String>] header the original header
+    # @param [Array<Symbol>] valid list of valid column names if empty all are considered valid.
+    # @return [Array<String>] converted columns
+    def build_columns(header, valid)
+      valid = valid.map(&:to_sym)
+
+      header.map do |column|
+        column = @converter.call(column.dup)
+
+        if column.nil? || column.empty?
+          raise(MissingCSVHeaderColumnError, "CSV header column can't be empty.")
+        end
+
+        if valid.any? && !valid.include?(column)
+          err_msg = "column :#{column} not in #{valid.inspect}"
+          raise(UnknownCSVHeaderColumnError, err_msg)
+        end
+
+        column
+      end
     end
   end
 end

data/lib/honey_format/row.rb

@@ -11,9 +11,13 @@ module HoneyFormat
     # @example Create new row
     #     Row.new!([:id])
     def initialize(columns, builder: nil)
-      validate_columns!(columns)
+      if columns.empty?
+        err_msg = 'Expected array with at least one element, but was empty.'
+        raise(EmptyColumnsError, err_msg)
+      end
+
       @row_builder = RowBuilder.new(*columns)
-      @builder = builder || ->(row) { row }
+      @builder = builder
       @columns = columns
     end
 
@@ -26,27 +30,15 @@ module HoneyFormat
     #     r.build(['1']).id #=> '1'
     def build(row)
       built_row = @row_builder.call(row)
+      return built_row unless @builder
       @builder.call(built_row)
     rescue ArgumentError, 'struct size differs'
-      fail_for_struct_size_diff!(row)
-    end
-
-    private
-
-    def validate_columns!(columns)
-      return unless columns.empty?
-
-      err_msg = 'Expected array with at least one element, but was empty.'
-      fail(EmptyColumnsError, err_msg)
-    end
-
-    def fail_for_struct_size_diff!(row)
       err_msg = [
         "Row length #{row.length}",
         "for columns #{@columns.length}",
         "row: #{row.inspect}"
       ].join(', ')
-      fail(InvalidRowLengthError, err_msg)
+      raise(InvalidRowLengthError, err_msg)
     end
   end
 end

data/lib/honey_format/row_builder.rb

@@ -1,11 +1,13 @@
 module HoneyFormat
   # Default row builder
   class RowBuilder < Struct
+    # Create a row
     # @return [Struct] returns an instantiated Struct representing a row
     def self.call(row)
       new(*row)
     end
 
+    # Represent row as CSV
     # @return [String] CSV-string representation.
     def to_csv
       members.map do |column_name|

data/lib/honey_format/rows.rb

@@ -13,7 +13,7 @@ module HoneyFormat
       @rows = prepare_rows(Row.new(columns, builder: builder), rows)
     end
 
-    # @yield [row] The given block will be passed every row.
+    # @yield [row] The given block will be passed for every row.
     # @yieldparam [Row] a row in the CSV file.
     # @return [Enumerator]
     #   If no block is given, an enumerator object will be returned.
@@ -38,8 +38,8 @@ module HoneyFormat
       built_rows = []
       rows.each do |row|
         # ignore empty rows - the Ruby CSV library can return empty lines as [nil]
-        next if row.empty? || row.nil? || row == [nil]
-        built_rows << builder.build(Sanitize.array!(row))
+        next if row.nil? || row.empty? || row == [nil]
+        built_rows << builder.build(row)
       end
       built_rows
     end

data/lib/honey_format/version.rb

@@ -1,4 +1,4 @@
 module HoneyFormat
   # Gem version
-  VERSION = '0.6.0'
+  VERSION = '0.7.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: honey_format
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Jacob Burenstam
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-11 00:00:00.000000000 Z
+date: 2018-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -117,7 +117,6 @@ files:
 - bin/setup
 - honey_format.gemspec
 - lib/honey_format.rb
-- lib/honey_format/columns.rb
 - lib/honey_format/convert_header_value.rb
 - lib/honey_format/csv.rb
 - lib/honey_format/exceptions.rb
@@ -125,7 +124,6 @@ files:
 - lib/honey_format/row.rb
 - lib/honey_format/row_builder.rb
 - lib/honey_format/rows.rb
-- lib/honey_format/sanitize.rb
 - lib/honey_format/version.rb
 homepage: https://github.com/buren/honey_format
 licenses:

data/lib/honey_format/columns.rb

@@ -1,50 +0,0 @@
-require 'honey_format/convert_header_value'
-
-module HoneyFormat
-  # Represents columns.
-  class Columns
-    # @return [Columns] a new instance of Columns.
-    # @param [Array] header array of strings.
-    # @param [Array] valid array of symbols representing valid columns.
-    # @raise [MissingCSVHeaderColumnError] raised when header is missing
-    # @raise [UnknownCSVHeaderColumnError] raised when column is not in valid list.
-    def initialize(header, valid: :all, converter: ConvertHeaderValue)
-      @converter = converter
-      @columns = build_columns(header, valid)
-    end
-
-    # Returns columns as array.
-    # @return [Array] of columns.
-    def to_a
-      @columns
-    end
-
-    private
-
-    def build_columns(header, valid)
-      header.map do |column|
-        column = @converter.call(column.dup)
-        validate_column_presence!(column)
-
-        validate_column_name!(column, valid)
-        column
-      end
-    end
-
-    def validate_column_presence!(col)
-      if col.nil? || col.empty?
-        fail(MissingCSVHeaderColumnError, "CSV header column can't be empty.")
-      end
-    end
-
-    def validate_column_name!(column, valid)
-      return if valid == :all
-
-      valid.include?(column) ||
-        begin
-          err_msg = "column :#{column} not in #{valid.inspect}"
-          fail(UnknownCSVHeaderColumnError, err_msg)
-        end
-    end
-  end
-end

data/lib/honey_format/sanitize.rb

@@ -1,46 +0,0 @@
-module HoneyFormat
-  # Utility class for sanitizing various simple data types.
-  class Sanitize
-    # Returns array of cleaned strings.
-    # @return [Array<String>] the cleaned array of strings.
-    # @param [Array<String>] row the array of strings to be cleaned.
-    # @example Sanitize array
-    #     Sanitize.array(["  a "]) #=> ["a"]
-    def self.array(row)
-      row.map { |column| string(column) }
-    end
-
-    # Returns array of cleaned elements.
-    # @return [String] the cleaned array.
-    # @param [String] column the string to be cleaned.
-    # @example Sanitize string
-    #     Sanitize.string("  a ") #=> "a"
-    # @example Sanitize nil
-    #     Sanitize.string(nil) #=> nil
-    def self.string(column)
-      return column if column.nil?
-      column.strip
-    end
-
-    # Returns mutated array of cleaned strings.
-    # @return [Array<String>] the cleaned array of strings.
-    # @param [Array<String>] row the array of strings to be cleaned.
-    # @example Sanitize array
-    #     Sanitize.array!(["  a "]) #=> ["a"]
-    def self.array!(row)
-      row.map! { |column| string!(column) }
-    end
-
-    # Returns mutated and cleaned string.
-    # @return [String] the cleaned array.
-    # @param [String] column the string to be cleaned.
-    # @example Sanitize string
-    #     Sanitize.string!("  a ") #=> "a"
-    # @example Sanitize nil
-    #     Sanitize.string!(nil) #=> nil
-    def self.string!(column)
-      return if column.nil?
-      column.tap(&:strip!)
-    end
-  end
-end