honey_format 0.8.2 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50238c752453380d738cfc60c2b0db25ea5f692887c39776905bed5e91aedf6b
-  data.tar.gz: 8cbdde37fbb98d69fa2d2f0bee3bf4eca78976fc7ff0ee93a17af630b557728f
+  metadata.gz: dd242cb77ccf8589eb2df059d887e13596f9c33a14fa587a886bcd376a6d728e
+  data.tar.gz: 72842684af98946cd50f7756818a4e9ce94b6c35d6c23a1e14661f70a93d3bac
 SHA512:
-  metadata.gz: 9c69b356e531fc429be88738e96669be8acca70a224cd80a1de87bc8caf489ac6b993eb0eac79cb93deb419a27f9e725486c1856b0698ed47c5653c902156758
-  data.tar.gz: ec12724d42d2bfcdf2c0fbfebd472671ea5d91250e8713cc03b6a9406943afceea89b05c5b62e3d3da76f3edd0d9b6d48ec6e134df5627dc13de25d042e02497
+  metadata.gz: ed5f6fa7f275d7445ca2962aa1787f8c10e25125253c3c65e3a5732cb0ef40e91f7c7d6bf73fa2d49d8d684c43bfec48058369f38df2e9ed5a52522f36f59d8c
+  data.tar.gz: 987843e3c4a987112bfbd46d00fa61a885ef12b71f19005e578e49d3f6f1bbe3af9022e3666af90437e015d522dbc7557a9f3065c45e4d0dd797d48670a9667f

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+# v0.9.2
+
+:warning: This release contains some backwards compatible changes.
+
+* Add support for missing header values [[#PR10](https://github.com/buren/honey_format/pull/10)]
+* Don't mutate original CSV header [[#PR10](https://github.com/buren/honey_format/pull/10)]
+* Output converted columns, instead of original, when `#to_csv` is called [[#PR10](https://github.com/buren/honey_format/pull/10)]
+* Update error class names [[#PR10](https://github.com/buren/honey_format/pull/10)]
+  - There are now two super classes for errors `HeaderError` and `RowError`
+  - All errors are under an `Errors` namespace, which `HoneyFormat` includes
+
 # v0.8.2
 
 * _[Bugfix]_ `#to_csv` now outputs nil values as empty string instead of `""`

data/README.md

@@ -5,7 +5,7 @@ Convert CSV to an array of objects with with ease.
 Perfect for small files of test data or small import scripts.
 
 ```ruby
-csv_string = "Id, Username\n 1, buren"
+csv_string = "Id,Username\n1,buren"
 csv = HoneyFormat::CSV.new(csv_string)
 csv.header      # => ["Id", "Username"]
 user = csv.rows # => [#<struct id="1", username="buren">]
@@ -38,10 +38,10 @@ $ gem install honey_format
 By default assumes a header in the CSV file.
 
 ```ruby
-csv_string = "Id, Username\n 1, buren"
+csv_string = "Id,Username\n1,buren"
 csv = HoneyFormat::CSV.new(csv_string)
 csv.header # => ["Id", "Username"]
-csv.column # => [:id, :username]
+csv.columns # => [:id, :username]
 
 rows = csv.rows # => [#<struct id="1", username="buren">]
 user = rows.first
@@ -51,8 +51,8 @@ user.username   # => "buren"
 
 Minimal custom row builder
 ```ruby
-csv_string = "Id, Username\n 1, buren"
-upcaser = ->(row) { row.username.upcase!; row }
+csv_string = "Id,Username\n1,buren"
+upcaser = ->(row) { row.tap { |r| r.username.upcase! } }
 csv = HoneyFormat::CSV.new(csv_string, row_builder: upcaser)
 csv.rows # => [#<struct id="1", username="BUREN">]
 ```
@@ -71,17 +71,24 @@ class Anonymizer
   end
 end
 
-csv_string = "Id, Username\n 1, buren"
+csv_string = "Id,Username\n1,buren"
 csv = HoneyFormat::CSV.new(csv_string, row_builder: Anonymizer)
 csv.rows # => [#<struct id="1", username="BUREN">]
 ```
 
 Output CSV
 ```ruby
-csv_string = "Id, Username\n 1, buren"
+csv_string = "Id,Username\n1,buren"
 csv = HoneyFormat::CSV.new(csv_string)
 csv.rows.each { |row| row.id = nil }
-csv.to_csv # => "Id, Username\n,buren\n"
+csv.to_csv # => "id,username\n,buren\n"
+```
+
+Output a subset of columns to CSV
+```ruby
+csv_string = "Id, Username, Country\n1,buren,Sweden"
+csv = HoneyFormat::CSV.new(csv_string)
+csv.to_csv(columns: [:id, :country]) # => "id,country\nburen,Sweden\n"
 ```
 
 You can of course set the delimiter
@@ -91,10 +98,10 @@ HoneyFormat::CSV.new(csv_string, delimiter: ';')
 
 Validate CSV header
 ```ruby
-csv_string = "Id, Username\n 1, buren"
+csv_string = "Id,Username\n1,buren"
 # Invalid
 HoneyFormat::CSV.new(csv_string, valid_columns: [:something, :username])
-# => #<HoneyFormat::MissingCSVHeaderColumnError: key :id ("Id") not in [:something, :username]>
+# => HoneyFormat::UnknownHeaderColumnError (column :id not in [:something, :username])
 
 # Valid
 csv = HoneyFormat::CSV.new(csv_string, valid_columns: [:id, :username])
@@ -103,7 +110,7 @@ csv.rows.first.username # => "buren"
 
 Define header
 ```ruby
-csv_string = "1, buren"
+csv_string = "1,buren"
 csv = HoneyFormat::CSV.new(csv_string, header: ['Id', 'Username'])
 csv.rows.first.username # => "buren"
 ```
@@ -122,6 +129,8 @@ user.åäö
 csv_string = "First^Name\nJacob"
 user = HoneyFormat::CSV.new(csv_string).rows.first
 user.public_send(:"first^name") # => "Jacob"
+# or
+user['first^name'] # => "Jacob"
 ```
 
 Pass your own header converter
@@ -134,6 +143,30 @@ user = HoneyFormat::CSV.new(csv_string, header_converter: converter).rows.first
 user.first_name # => "Jacob"
 ```
 
+Missing header values
+```ruby
+csv_string = "first,,third\nval0,val1,val2"
+csv = HoneyFormat::CSV.new(csv_string)
+user = csv.rows.first
+user.column1 # => "val1"
+```
+
+Errors
+```ruby
+# there are two error super classes
+begin
+  HoneyFormat::CSV.new(csv_string)
+rescue HoneyFormat::HeaderError => e
+  puts 'there is a problem with the header'
+  raise(e)
+rescue HoneyFormat::RowError => e
+  puts 'there is a problem with a row'
+  raise(e)
+end
+```
+
+You can see all [available errors here](https://www.rubydoc.info/gems/honey_format/HoneyFormat/Errors).
+
 If you want to see more usage examples check out the `spec/` directory.
 
 ## Benchmark

data/lib/honey_format.rb

@@ -1,5 +1,5 @@
 require 'honey_format/version'
-require 'honey_format/exceptions'
+require 'honey_format/errors'
 require 'honey_format/csv'
 
 # Main module for HoneyFormat

data/lib/honey_format/convert_header_value.rb

@@ -20,7 +20,10 @@ module HoneyFormat
     #     ConvertHeaderValue.call("  User name ") #=> "user_name"
     # @example Convert complex header
     #     ConvertHeaderValue.call(" First name (user)") #=> :'first_name(user)'
-    def self.call(column)
+    def self.call(column, index)
+      return :"column#{index}" if column.nil? || column.empty?
+
+      column = column.dup
       column.strip!
       column.downcase!
       REPLACE_MAP.each do |data|

data/lib/honey_format/csv.rb

@@ -9,11 +9,15 @@ module HoneyFormat
     # @return [CSV] a new instance of CSV.
     # @param [String] csv string.
     # @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.
+    # @param [Array<String>] header optional argument for CSV header.
+    # @param [#call] row_builder will be called for each parsed row.
+    # @raise [HeaderError] super class of errors raised when there is a CSV header error.
+    # @raise [MissingHeaderError] raised when header is missing (empty or nil).
+    # @raise [MissingHeaderColumnError] raised when header column is missing.
+    # @raise [UnknownHeaderColumnError] raised when column is not in valid list.
+    # @raise [RowError] super class of errors raised when there is a row error.
+    # @raise [EmptyRowColumnsError] raised when row columns are empty.
+    # @raise [InvalidRowLengthError] raised when row has more columns than header columns.
     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
@@ -27,7 +31,7 @@ module HoneyFormat
       @header.original
     end
 
-    # CSV columns
+    # CSV columns converted from the original CSV header
     # @return [Array<Symbol>] of column identifiers.
     def columns
       @header.to_a
@@ -50,8 +54,8 @@ module HoneyFormat
 
     # Convert CSV object as CSV-string.
     # @return [String] CSV-string representation.
-    def to_csv
-      header.to_csv + @rows.to_csv
+    def to_csv(columns: nil)
+      @header.to_csv(columns: columns) + @rows.to_csv(columns: columns)
     end
   end
 end

data/lib/honey_format/errors.rb

@@ -0,0 +1,24 @@
+module HoneyFormat
+  # Errors
+  module Errors
+    # Header errors
+    # Super class of errors raised when there is a header error
+    class HeaderError < StandardError; end
+    # Raised when header is missing
+    class MissingHeaderError < HeaderError; end
+    # Raised when header column is missing
+    class MissingHeaderColumnError < HeaderError; end
+    # Raised when a column is not in passed valid columns
+    class UnknownHeaderColumnError < HeaderError; end
+
+    # Row errors
+    # Super class of errors raised when there is a row error
+    class RowError < StandardError; end
+    # Raised when row columns are empty
+    class EmptyRowColumnsError < RowError; end
+    # Raised when row has more columns than header columns
+    class InvalidRowLengthError < RowError; end
+  end
+
+  include Errors
+end

data/lib/honey_format/header.rb

@@ -8,20 +8,20 @@ module HoneyFormat
     # Instantiate a Header
     # @return [Header] a new instance of Header.
     # @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 [Array<Symbol, String>] valid array representing the 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.
+    # @raise [MissingHeaderColumnError] raised when header is missing
+    # @raise [UnknownHeaderColumnError] 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?
-        raise(MissingCSVHeaderError, "CSV header can't be empty.")
+        raise(Errors::MissingHeaderError, "CSV header can't be empty.")
       end
 
-      @original_header = header.map { |col| col ? col.strip : nil }
+      @original_header = header
       @converter = converter
       @columns = build_columns(@original_header, valid)
     end
@@ -36,51 +36,84 @@ module HoneyFormat
     # @return [Enumerator]
     #   If no block is given, an enumerator object will be returned.
     def each(&block)
-      @columns.each(&block)
+      columns.each(&block)
     end
 
     # Returns columns as array.
     # @return [Array<Symbol>] of columns.
-    def to_a
+    def columns
       @columns
     end
 
+    # Returns columns as array.
+    # @return [Array<Symbol>] of columns.
+    def to_a
+      columns
+    end
+
     # Return the number of header columns
     # @return [Integer] the number of header columns
     def length
-      @columns.length
+      columns.length
     end
     alias_method :size, :length
 
     # Header as CSV-string
     # @return [String] CSV-string representation.
-    def to_csv
-      ::CSV.generate_line(@columns)
+    def to_csv(columns: nil)
+      attributes = if columns
+                     self.columns & columns
+                   else
+                     self.columns
+                   end
+
+      ::CSV.generate_line(attributes)
     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.")
+      header.each_with_index.map do |header_column, index|
+        convert_column(header_column, index).tap do |column|
+          maybe_raise_missing_column!(column)
+          maybe_raise_unknown_column!(column, valid)
         end
+      end
+    end
 
-        if valid.any? && !valid.include?(column)
-          err_msg = "column :#{column} not in #{valid.inspect}"
-          raise(UnknownCSVHeaderColumnError, err_msg)
-        end
+    def convert_column(column, index)
+      return @converter.call(column) if converter_arity == 1
+      @converter.call(column, index)
+    end
 
-        column
-      end
+    def converter_arity
+      # procs and lambdas respond to #arity
+      return @converter.arity if @converter.respond_to?(:arity)
+      @converter.method(:call).arity
+    end
+
+    def maybe_raise_unknown_column!(column, valid)
+      return if valid.empty?
+      return if valid.include?(column)
+
+      err_msg = "column :#{column} not in #{valid.inspect}"
+      raise(Errors::UnknownHeaderColumnError, err_msg)
+    end
+
+    def maybe_raise_missing_column!(column)
+      return if column && !column.empty?
+
+      parts = [
+        "CSV header column can't be nil or empty!",
+        "When you pass your own converter make sure that it never returns nil or an empty string.",
+        'Instead generate unique columns names.'
+      ]
+      raise(Errors::MissingHeaderColumnError, parts.join(' '))
     end
   end
 end

data/lib/honey_format/row.rb

@@ -7,13 +7,13 @@ module HoneyFormat
     # @return [Row] a new instance of Row.
     # @param [Array] columns an array of symbols.
     # @param builder [#call, #to_csv] optional row builder
-    # @raise [EmptyColumnsError] raised when there are no columns.
+    # @raise [EmptyRowColumnsError] raised when there are no columns.
     # @example Create new row
     #     Row.new!([:id])
     def initialize(columns, builder: nil)
       if columns.empty?
         err_msg = 'Expected array with at least one element, but was empty.'
-        raise(EmptyColumnsError, err_msg)
+        raise(Errors::EmptyRowColumnsError, err_msg)
       end
 
       @row_builder = RowBuilder.new(*columns)
@@ -41,7 +41,7 @@ module HoneyFormat
         "row: #{row.inspect}",
         "orignal message: '#{e.message}'"
       ].join(', ')
-      raise(InvalidRowLengthError, err_msg)
+      raise(Errors::InvalidRowLengthError, err_msg)
     end
   end
 end

data/lib/honey_format/row_builder.rb

@@ -9,8 +9,11 @@ module HoneyFormat
 
     # Represent row as CSV
     # @return [String] CSV-string representation.
-    def to_csv
-      row = members.map do |column_name|
+    def to_csv(columns: nil)
+      attributes = members
+      attributes = columns & attributes if columns
+
+      row = attributes.map do |column_name|
         column = public_send(column_name)
         next column.to_csv if column.respond_to?(:to_csv)
         next if column.nil?

data/lib/honey_format/rows.rb

@@ -1,3 +1,4 @@
+require 'set'
 require 'honey_format/row'
 
 module HoneyFormat
@@ -35,8 +36,10 @@ module HoneyFormat
     alias_method :size, :length
 
     # @return [String] CSV-string representation.
-    def to_csv
-      to_a.map(&:to_csv).join
+    def to_csv(columns: nil)
+      # Convert columns to Set for performance
+      columns = Set.new(columns) if columns
+      to_a.map { |row| row.to_csv(columns: columns) }.join
     end
 
     private

data/lib/honey_format/version.rb

@@ -1,4 +1,4 @@
 module HoneyFormat
   # Gem version
-  VERSION = '0.8.2'
+  VERSION = '0.9.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: honey_format
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.9.0
 platform: ruby
 authors:
 - Jacob Burenstam
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-16 00:00:00.000000000 Z
+date: 2018-06-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -119,7 +119,7 @@ files:
 - lib/honey_format.rb
 - lib/honey_format/convert_header_value.rb
 - lib/honey_format/csv.rb
-- lib/honey_format/exceptions.rb
+- lib/honey_format/errors.rb
 - lib/honey_format/header.rb
 - lib/honey_format/row.rb
 - lib/honey_format/row_builder.rb

data/lib/honey_format/exceptions.rb

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