honey_format 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3ba71ccfedf80d0f721f3b205a6eb8f247284704
-  data.tar.gz: e6091ac68245db3e1c1d0918e9aed66361b38a5e
+  metadata.gz: 4a3591ebdea8bbde84b5cd4cef7915917ec9b929
+  data.tar.gz: f8ae5d74d90fe3742c322e94f2f5881c879d85bb
 SHA512:
-  metadata.gz: 918906a7bdfc3d6ef900794832a8359811ee69ea9c68ab8a563bc5199308db91637fa8610f7b265bc7ddbcad13a3f74b1e6f467df5247eb0ed2d022bd9ce1bf2
-  data.tar.gz: 4f46d54f77c109349131ea3c3db982e1671aa3597ea1383b3cd7b6176a64d72bb0650fe0b772fa3542883c38761589344c23fb510ec110e21ce15a80d7845819
+  metadata.gz: 2821d59e1072042093d590f0a31883dd0403fc552b5ee8f7a5d16f2849afb37a5003dbb37c6054a620ff99b4b97eca1ea69f751118c7f156af96c2849b634367
+  data.tar.gz: 17b3aa8e0f0fc46391395ef602cff94753fbd5e6fe96cd28bf19cce859626ebefbf99b1b54460b72ac3d4698c7b71cfe7a459a02ab93d5e89548c058068ba411

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# v0.2.0
+
+* More explicit exception classes
+* Restructured internals
+
+## v0.1.0
+
+Initial release

data/README.md

@@ -1,4 +1,4 @@
-# HoneyFormat [![Build Status](https://travis-ci.org/buren/honey_format.svg)](https://travis-ci.org/buren/honey_format) [![Code Climate](https://codeclimate.com/github/buren/honey_format/badges/gpa.svg)](https://codeclimate.com/github/buren/honey_format)
+# HoneyFormat [![Build Status](https://travis-ci.org/buren/honey_format.svg)](https://travis-ci.org/buren/honey_format) [![Code Climate](https://codeclimate.com/github/buren/honey_format/badges/gpa.svg)](https://codeclimate.com/github/buren/honey_format) ![Docs badge](https://inch-ci.org/github/buren/honey_format.svg?branch=master)
 
 Convert CSV to object with one command.
 
@@ -39,11 +39,13 @@ By default assumes a header in the CSV file.
 csv_string = "Id, Username\n 1, buren"
 csv = HoneyFormat::CSV.new(csv_string)
 csv.header # => ["Id", "Username"]
+csv.column # => [:id, :username]
 
 include HoneyFormat
 # If included you can use the HoneyCSV shorthand
 csv = HoneyCSV.new(csv_string)
-user = csv.rows # => [#<struct id="1", username="buren">]
+rows = csv.rows # => [#<struct id="1", username="buren">]
+user = rows.first
 user.id         # => "1"
 user.username   # => "buren"
 ```
@@ -54,6 +56,7 @@ csv_string = "Id, Username\n 1, buren"
 # Invalid
 HoneyCSV.new(csv_string, valid_columns: [:something, :username])
 # => #<HoneyFormat::CSVHeaderColumnError: key :id ("Id") not in [:something, :username]>
+
 # Valid
 csv = HoneyCSV.new(csv_string, valid_columns: [:id, :username])
 csv.rows.first.username # => "buren"
@@ -66,26 +69,53 @@ csv = HoneyCSV.new(csv_string, header: ['Id', 'Username'])
 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..
+```ruby
+csv_string = "ÅÄÖ\nSwedish characters"
+user = HoneyCSV.new(csv_string).rows.first
+# Note that these chars aren't "downcased",
+# "ÅÄÖ".downcase # => "ÅÄÖ"
+user.ÅÄÖ # => "Swedish characters"
+
+csv_string = "First-Name\nJacob"
+user = HoneyCSV.new(csv_string).rows.first
+user.public_send(:"first-name") # => "Jacob"
+```
+
+If you want to see more usage examples check out the `spec/` directory.
+
 ## Benchmark
 
 _Note_: This gem, adds some overhead to parsing a CSV string. I've included some benchmarks below, your mileage may vary..
 
-Benchmarks for a 21MB file with 10 columns (MBP 2013 OSX 10.10).
+Benchmarks, using the `benchmark-ips` gem, CSV with 11 columns in MBP 2013 OSX 10.10.
+
+124KB (~1000 lines )
 
 ```
 Calculating -------------------------------------
-          stdlib CSV     1.000  i/100ms
-    HoneyFormat::CSV     1.000  i/100ms
+          stdlib CSV     6.000  i/100ms
+    HoneyFormat::CSV     5.000  i/100ms
 -------------------------------------------------
-          stdlib CSV      0.317  (± 0.0%) i/s -      4.000  in  12.636647s
-    HoneyFormat::CSV      0.335  (± 0.0%) i/s -      4.000  in  12.061301s
+          stdlib CSV     64.236  (± 4.7%) i/s -    642.000
+    HoneyFormat::CSV     52.762  (± 5.7%) i/s -    530.000
+
+Comparison:
+          stdlib CSV:       64.2 i/s
+    HoneyFormat::CSV:       52.8 i/s - 1.22x slower
+```
+
+20MB (~180k lines)
 
+```
 Comparison:
-    HoneyFormat::CSV:        0.3 i/s
-          stdlib CSV:        0.3 i/s - 1.06x slower
+          stdlib CSV:        0.3 i/s
+    HoneyFormat::CSV:        0.3 i/s - 1.26x slower
 ```
 
-Run the benchmark as a regular ruby file: `ruby benchmark.rb`.
+See `bin/benchmark` for details.
+Run benchmark: `bin/benchmark`.
 
 ## Development
 

data/bin/benchmark

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+require 'bundler/setup'
+require 'honey_format'
+
+require 'benchmark/ips'
+require 'csv'
+
+# Assumes that you have a file "benchmark.csv" in your current directory
+csv = File.read('benchmark-20mb.csv')
+
+Benchmark.ips do |x|
+  x.time = 10
+  x.warmup = 2
+
+  x.report('stdlib CSV')       { CSV.parse(csv) }
+  x.report('HoneyFormat::CSV') { HoneyFormat::CSV.new(csv).rows }
+
+  x.compare!
+end

data/honey_format.gemspec

@@ -20,6 +20,7 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'bundler', '~> 1.10'
   spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'benchmark-ips'
   spec.add_development_dependency 'rspec'
   spec.add_development_dependency 'simplecov'
 end

data/lib/honey_format.rb

@@ -1,6 +1,9 @@
 require 'honey_format/version'
+require 'honey_format/exceptions'
 require 'honey_format/csv'
 
+# Main module for HoneyFormat
 module HoneyFormat
+  # CSV alias
   HoneyCSV = CSV
 end

data/lib/honey_format/columns.rb

@@ -0,0 +1,56 @@
+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)
+      @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|
+        Sanitize.string!(column)
+        validate_column_presence!(column)
+
+        column = symnolize_string!(column)
+
+        validate_column_name!(column, valid)
+        column
+      end
+    end
+
+    def symnolize_string!(column)
+      column.downcase!
+      column.gsub!(/ /, '')
+      column.gsub!(/-/, '_')
+      column.to_sym
+    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/csv.rb

@@ -1,63 +1,44 @@
 require 'csv'
 
-module HoneyFormat
-  class MissingCSVHeaderError < StandardError; end
-  class CSVHeaderColumnError < StandardError; end
+require 'honey_format/sanitize'
+require 'honey_format/rows'
+require 'honey_format/header'
 
+module HoneyFormat
+  # Represents CSV.
   class CSV
-    attr_reader :header, :columns
-
+    # @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
+    # @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)
       csv = ::CSV.parse(csv, col_sep: delimiter)
-      @head = build_header(header || csv.shift)
       @csv_body = csv
-      @columns = build_columns(@head, valid_columns)
-      @struct_klass = Struct.new(*@columns)
+      @header = Header.new(header || csv.shift, valid: valid_columns)
     end
 
+    # @return [Array] of strings for sanitized header.
     def header
-      @head
-    end
-
-    def rows
-      @rows ||= @csv_body.map { |row| create_object(row) }
-    end
-
-    def row_count
-      rows.length
+      @header.column_names
     end
 
-    private
-
-    def build_header(head)
-      head || fail(MissingCSVHeaderError, 'CSV header must be present.')
-      clean_row(head)
-    end
-
-    def build_columns(keys, valid_columns)
-      columns = keys.map do |raw_col|
-        col = raw_col.downcase.gsub(/ /, '').to_sym
-        validate_column!(raw_col, col, valid_columns)
-        col
-      end
-    end
-
-    def create_object(row)
-      @struct_klass.new(*clean_row(row))
-    end
-
-    def clean_row(row)
-      row.map { |column| clean(column) }
+    # @return [Array] of column identifiers.
+    def columns
+      @header.columns
     end
 
-    def clean(column)
-      column.strip unless column.nil?
+    # @return [Array] of rows.
+    # @raise [InvalidRowLengthError] raised when there are more row elements longer than columns
+    def rows
+      @rows ||= Rows.new(@csv_body, columns).to_a
     end
 
-    def validate_column!(c, col, valid_columns)
-      unless valid_columns == :all
-        valid_columns.include?(col) || fail(CSVHeaderColumnError, "column :#{col} (\"#{c}\") not in #{valid_columns.inspect}")
-      end
+    # @yield [row] block to receive the row.
+    def each_row
+      rows.each { |row| yield(row) }
     end
   end
 end

data/lib/honey_format/exceptions.rb

@@ -0,0 +1,12 @@
+module HoneyFormat
+  # Raised when header is missing
+  class MissingCSVHeaderError < StandardError; end
+  # Raised when header column is missing
+  class MissingCSVHeaderColumnError < StandardError; end
+  # Raised when a column is not in passed valid columns
+  class UnknownCSVHeaderColumnError < StandardError; end
+  # Raised when columns are empty
+  class EmptyColumnsError < ArgumentError; end
+  # Raised when row has more columns than columns
+  class InvalidRowLengthError < ArgumentError; end
+end

data/lib/honey_format/header.rb

@@ -0,0 +1,32 @@
+require 'honey_format/columns'
+
+module HoneyFormat
+  # Represents a header
+  class Header
+    attr_reader :column_names
+
+    # @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)
+      @column_names = build_header(header)
+      @columns = Columns.new(@column_names, valid)
+    end
+
+    # Returns columns as array.
+    # @return [Array] of columns.
+    def columns
+      @columns.to_a
+    end
+
+    private
+
+    def build_header(header)
+      if header.nil? || header.empty?
+        fail(MissingCSVHeaderError, "CSV header can't be empty.")
+      end
+      Sanitize.array!(header)
+    end
+  end
+end

data/lib/honey_format/row.rb

@@ -0,0 +1,47 @@
+module HoneyFormat
+  # Holds data for a single row.
+  class Row
+    # Returns a new instance of Row.
+    # @return [Row] a new instance of Row.
+    # @param [Array] columns an array of symbols.
+    # @raise [EmptyColumnsError] raised when there are no columns.
+    # @example Create new row
+    #     Row.new!([:id])
+    def initialize(columns)
+      validate_columns!(columns)
+      @klass = Struct.new(*columns)
+      @columns = columns
+    end
+
+    # Returns a Struct.
+    # @return [Struct] a new instance of Row.
+    # @param row [Array] the row array.
+    # @raise [InvalidRowLengthError] raised when there are more row elements longer than columns
+    # @example Build new row
+    #     r = Row.new!([:id])
+    #     r.build(['1']).id #=> '1'
+    def build(row)
+      @klass.new(*row)
+    rescue ArgumentError, 'struct size differs'
+      fail_for_struct_size_diff!(row)
+    end
+
+    private
+
+    def validate_columns!(columns)
+      if columns.empty?
+        err_msg = 'Expected array with at least one element, but was empty.'
+        fail(EmptyColumnsError, err_msg)
+      end
+    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)
+    end
+  end
+end

data/lib/honey_format/rows.rb

@@ -0,0 +1,32 @@
+require 'honey_format/row'
+
+module HoneyFormat
+  # Represents rows.
+  class Rows
+    # Returns array of cleaned strings.
+    # @return [Rows] new instance of Rows.
+    # @param [Array] rows the array of rows.
+    # @param [Array] columns the array of column symbols.
+    def initialize(rows, columns)
+      @rows = prepare_rows(Row.new(columns), rows)
+    end
+
+    # Returns rows as array.
+    # @return [Array] of rows.
+    def to_a
+      @rows
+    end
+
+    private
+
+    def prepare_rows(builder, rows)
+      built_rows = []
+      rows.each do |row|
+        unless row.first.nil? # The Ruby CSV library returns empty lines as [nil], ignore them..
+          built_rows << builder.build(Sanitize.array!(row))
+        end
+      end
+      built_rows
+    end
+  end
+end

data/lib/honey_format/sanitize.rb

@@ -0,0 +1,26 @@
+module HoneyFormat
+  # Utility class for sanitizing various simple data types.
+  class Sanitize
+    # Returns array of cleaned strings.
+    # @return [Array] the cleaned array of strings.
+    # @param [Array] row the array of strings to be cleaned.
+    # @example Sanitize array
+    #     Sanitize.array!(["  a "]) #=> ["a"]
+    def self.array!(row)
+      row.map! { |column| string!(column) }
+      row
+    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)
+      column.strip! unless column.nil?
+      column
+    end
+  end
+end

data/lib/honey_format/version.rb

@@ -1,3 +1,4 @@
 module HoneyFormat
-  VERSION = '0.1.1'
+  # Gem version
+  VERSION = '0.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: honey_format
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Jacob Burenstam
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-02 00:00:00.000000000 Z
+date: 2015-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -77,17 +91,24 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
-- benchmark.rb
+- bin/benchmark
 - bin/console
 - bin/setup
 - honey_format.gemspec
 - lib/honey_format.rb
+- lib/honey_format/columns.rb
 - lib/honey_format/csv.rb
+- lib/honey_format/exceptions.rb
+- lib/honey_format/header.rb
+- lib/honey_format/row.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/benchmark.rb

@@ -1,17 +0,0 @@
-require 'benchmark/ips'
-require 'csv'
-
-require 'bundler/setup'
-require 'honey_format'
-
-csv = File.read('benchmark.csv')
-
-Benchmark.ips do |x|
-  x.time = 10
-  x.warmup = 2
-
-  x.report("stdlib CSV") { CSV.parse(csv) }
-  x.report("HoneyFormat::CSV") { HoneyFormat::CSV.new(csv) }
-
-  x.compare!
-end