honey_format 0.12.0 → 0.13.0

data/lib/honey_format/errors.rb

@@ -8,8 +8,6 @@ module HoneyFormat
     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
@@ -18,6 +16,12 @@ module HoneyFormat
     class EmptyRowColumnsError < RowError; end
     # Raised when row has more columns than header columns
     class InvalidRowLengthError < RowError; end
+
+    # Value conversion errors
+    # Raised when value type is unknown
+    class UnknownValueTypeError < ArgumentError; end
+    # Raised when value type already exists
+    class ValueTypeExistsError < ArgumentError; end
   end
 
   include Errors

data/lib/honey_format/header.rb

@@ -1,4 +1,4 @@
-require 'honey_format/convert_header_value'
+require 'set'
 
 module HoneyFormat
   # Represents a header
@@ -8,23 +8,26 @@ module HoneyFormat
     # Instantiate a Header
     # @return [Header] a new instance of Header.
     # @param [Array<String>] header array of strings.
-    # @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.
+    # @param converter [#call, Symbol] header converter that implements a #call method that takes one column (string) argument OR symbol for a registered value converter.
     # @raise [HeaderError] super class of errors raised when there is a CSV header error.
     # @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
+    # @example Instantiate a header with a custom 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)
+    def initialize(header, converter: HoneyFormat.header_converter)
       if header.nil? || header.empty?
         raise(Errors::MissingHeaderError, "CSV header can't be empty.")
       end
 
       @original_header = header
-      @converter = converter
-      @columns = build_columns(@original_header, valid)
+      @converter = if converter.is_a?(Symbol)
+                     HoneyFormat.value_converter[converter]
+                   else
+                     converter
+                   end
+
+      @columns = build_columns(@original_header)
     end
 
     # @return [Array<String>] the original header
@@ -32,6 +35,12 @@ module HoneyFormat
       @original_header
     end
 
+    # Returns true if columns contains no elements.
+    # @return [true, false] true if columns contains no elements.
+    def empty?
+      @columns.empty?
+    end
+
     # @yield [row] The given block will be passed for every column.
     # @yieldparam [Row] a column in the CSV header.
     # @return [Enumerator]
@@ -63,7 +72,7 @@ module HoneyFormat
     # @return [String] CSV-string representation.
     def to_csv(columns: nil)
       attributes = if columns
-                     self.columns & columns
+                     self.columns & columns.map(&:to_sym)
                    else
                      self.columns
                    end
@@ -76,24 +85,25 @@ module HoneyFormat
     # Convert original header
     # @param [Array<String>] header the original header
     # @return [Array<String>] converted columns
-    def build_columns(header, valid)
-      valid = valid.map(&:to_sym)
-
+    def build_columns(header)
       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
 
     # Convert the column value
-    # @param [Object] column the CSV header column value
+    # @param [String, Symbol] column the CSV header column value
     # @param [Integer] index the CSV header column index
-    # @return [Object] the converted object
+    # @return [Symbol] the converted column
     def convert_column(column, index)
-      return @converter.call(column) if converter_arity == 1
-      @converter.call(column, index)
+      value = if converter_arity == 1
+                @converter.call(column)
+              else
+                @converter.call(column, index)
+              end
+      value.to_sym
     end
 
     # Returns the converter#call method arity
@@ -104,18 +114,6 @@ module HoneyFormat
       @converter.method(:call).arity
     end
 
-    # Raises an error if header column is unknown
-    # @param [Object] column the CSV header column
-    # @param [Array<Symbol, String>] valid CSV columns
-    # @raise [Errors::UnknownHeaderColumnError]
-    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
-
     # Raises an error if header column is missing/empty
     # @param [Object] column the CSV header column
     # @raise [Errors::MissingHeaderColumnError]

data/lib/honey_format/{convert_header_value.rb → header_column_converter.rb}

@@ -1,6 +1,6 @@
 module HoneyFormat
   # Header column converter
-  module ConvertHeaderValue
+  module HeaderColumnConverter
     # Replace map
     REPLACE_MAP = [
       [/ \(/, '('],
@@ -16,13 +16,16 @@ module HoneyFormat
     # Returns converted value and mutates the argument.
     # @return [Symbol] the cleaned header column.
     # @param [String] column the string to be cleaned.
-    # @param [Integer] column index.
+    # @param [Integer] index the column index.
     # @example Convert simple header
-    #     ConvertHeaderValue.call("  User name ") #=> "user_name"
+    #     HeaderColumnConverter.call("  User name ") #=> "user_name"
     # @example Convert complex header
-    #     ConvertHeaderValue.call(" First name (user)") #=> :'first_name(user)'
-    def self.call(column, index)
-      return :"column#{index}" if column.nil? || column.empty?
+    #     HeaderColumnConverter.call(" First name (user)") #=> :'first_name(user)'
+    def self.call(column, index = nil)
+      if column.nil? || column.empty?
+        raise(ArgumentError, "column and column index can't be blank/nil") unless index
+        return :"column#{index}"
+      end
 
       column = column.dup
       column.strip!

data/lib/honey_format/matrix.rb

@@ -0,0 +1,90 @@
+require 'csv'
+
+require 'honey_format/rows'
+require 'honey_format/header'
+
+module HoneyFormat
+  # Represents CSV.
+  class Matrix
+    # Instantiate CSV.
+    # @return [CSV] a new instance of Matrix.
+    # @param [Array<Array<String, nil>>] matrix
+    # @param [Array<String>] header optional argument that represents header, required if the matrix lacks a header row.
+    # @param [#call] header_converter converts header columns.
+    # @param [#call] row_builder will be called for each parsed row.
+    # @param type_map [Hash] map of column_name => type conversion to perform.
+    # @raise [HeaderError] super class of errors raised when there is a header error.
+    # @raise [MissingHeaderError] raised when header is missing (empty or nil).
+    # @raise [MissingHeaderColumnError] raised when header column is missing.
+    # @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.
+    # @example
+    #   matrix = HoneyFormat::Matrix.new([%w[name id]])
+    # @example With custom header converter
+    #   converter = proc { |v| v == 'name' ? 'first_name' : v }
+    #   matrix = HoneyFormat::Matrix.new([%w[name id]], header_converter: converter)
+    #   matrix.columns # => [:first_name, :id]
+    # @example Handle errors
+    #   begin
+    #     matrix = HoneyFormat::Matrix.new([%w[name id]])
+    #   rescue HoneyFormat::HeaderError => e
+    #     puts "header error: #{e.class}, #{e.message}"
+    #   rescue HoneyFormat::RowError => e
+    #     puts "row error: #{e.class}, #{e.message}"
+    #   end
+    def initialize(
+      matrix,
+      header: nil,
+      header_converter: HoneyFormat.header_converter,
+      row_builder: nil,
+      type_map: {}
+    )
+      header_row = header || matrix.shift
+      @header = Header.new(header_row, converter: header_converter)
+      @rows = Rows.new(matrix, columns, builder: row_builder, type_map: type_map)
+    end
+
+    # Original CSV header
+    # @return [Header] object representing the CSV header.
+    def header
+      @header
+    end
+
+    # CSV columns converted from the original CSV header
+    # @return [Array<Symbol>] of column identifiers.
+    def columns
+      @header.to_a
+    end
+
+    # @return [Rows] of rows.
+    def rows
+      @rows
+    end
+
+    # @yield [row] The given block will be passed for every row.
+    # @yieldparam [Row] row in the CSV.
+    # @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 matrix to CSV-string.
+    # @param columns [Array<Symbol>, Set<Symbol>, NilClass] the columns to output, nil means all columns (default: nil)
+    # @yield [row] The given block will be passed for every row - return truthy if you want the row to be included in the output
+    # @yieldparam [Row] row
+    # @return [String] CSV-string representation.
+    # @example with selected columns
+    #   matrix.to_csv(columns: [:id, :country])
+    # @example with selected rows
+    #   matrix.to_csv { |row| row.country == 'Sweden' }
+    # @example with both selected columns and rows
+    #   matrix.to_csv(columns: [:id, :country]) { |row| row.country == 'Sweden' }
+    def to_csv(columns: nil, &block)
+      columns = columns&.map(&:to_sym)
+      @header.to_csv(columns: columns) + @rows.to_csv(columns: columns, &block)
+    end
+  end
+end

data/lib/honey_format/row.rb

@@ -18,7 +18,7 @@ module HoneyFormat
       attributes = members
       attributes = columns & attributes if columns
 
-      row = attributes.map { |column| to_csv_value(column) }
+      row = attributes.map! { |column| to_csv_value(column) }
 
       ::CSV.generate_line(row)
     end

data/lib/honey_format/row_builder.rb

@@ -6,24 +6,28 @@ module HoneyFormat
     # Returns a new instance of RowBuilder.
     # @return [RowBuilder] a new instance of RowBuilder.
     # @param [Array<Symbol>] columns an array of symbols.
-    # @param builder [#call, #to_csv] optional row builder
+    # @param builder [#call, #to_csv] optional row builder.
+    # @param type_map [Hash] map of column_name => type conversion to perform.
     # @raise [RowError] super class of errors raised when there is a row error.
     # @raise [EmptyRowColumnsError] raised when there are no columns.
     # @raise [InvalidRowLengthError] raised when row has more columns than header columns.
     # @example Create new row
     #     RowBuilder.new!([:id])
-    def initialize(columns, builder: nil)
+    def initialize(columns, builder: nil, type_map: {})
       if columns.empty?
         err_msg = 'Expected array with at least one element, but was empty.'
         raise(Errors::EmptyRowColumnsError, err_msg)
       end
 
+      @type_map = type_map
+      @converter = HoneyFormat.value_converter
+
       @row_klass = Row.new(*columns)
       @builder = builder
       @columns = columns
     end
 
-    # Returns a Struct.
+    # Returns an object representing the row.
     # @return [Row, Object] a new instance of built row.
     # @param row [Array] the row array.
     # @raise [InvalidRowLengthError] raised when there are more row elements longer than columns
@@ -31,9 +35,7 @@ module HoneyFormat
     #     r = RowBuilder.new([:id])
     #     r.build(['1']).id #=> '1'
     def build(row)
-      row = @row_klass.call(row)
-      return row unless @builder
-      @builder.call(row)
+      build_row!(row)
     rescue ArgumentError => e
       raise unless e.message == 'struct size differs'
       raise_invalid_row_length!(e, row)
@@ -41,6 +43,25 @@ module HoneyFormat
 
     private
 
+    # Returns Struct
+    # @return [Row, Object] a new instance of built row.
+    # @param row [Array] the row array.
+    # @raise [ArgumentError] raised when struct fails to build
+    # @example Build new row
+    #     r = RowBuilder.new([:id])
+    #     r.build(['1']).id #=> '1'
+    def build_row!(row)
+      row = @row_klass.call(row)
+
+      # Convert values
+      @type_map.each do |column, type|
+        row[column] = @converter.call(row[column], type)
+      end
+
+      return row unless @builder
+      @builder.call(row)
+    end
+
     # Raises invalid row length error
     # @param [StandardError] e the raised error
     # @param [Object] row

data/lib/honey_format/rows.rb

@@ -9,15 +9,22 @@ module HoneyFormat
     # 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.
+    # @param [Array<Symbol>] columns the array of column symbols.
+    # @param type_map [Hash] map of column_name => type conversion to perform.
     # @raise [RowError] super class of errors raised when there is a row error.
     # @raise [EmptyRowColumnsError] raised when there are no columns.
     # @raise [InvalidRowLengthError] raised when row has more columns than header columns.
-    def initialize(rows, columns, builder: nil)
-      builder = RowBuilder.new(columns, builder: builder)
+    def initialize(rows, columns, builder: nil, type_map: {})
+      builder = RowBuilder.new(columns, builder: builder, type_map: type_map)
       @rows = prepare_rows(builder, rows)
     end
 
+    # Returns true if rows contains no elements.
+    # @return [true, false] true if rows contains no elements.
+    def empty?
+      @rows.empty?
+    end
+
     # @yield [row] The given block will be passed for every row.
     # @yieldparam [Row] a row in the CSV file.
     # @return [Enumerator]
@@ -51,7 +58,7 @@ module HoneyFormat
     #   csv.to_csv(columns: [:id, :country]) { |row| row.country == 'Sweden' }
     def to_csv(columns: nil, &block)
       # Convert columns to Set for performance
-      columns = Set.new(columns) if columns
+      columns = Set.new(columns.map(&:to_sym)) if columns
       csv_rows = []
       each do |row|
         if !block || block.call(row)
@@ -66,7 +73,7 @@ module HoneyFormat
     def prepare_rows(builder, rows)
       built_rows = []
       rows.each do |row|
-        # ignore empty rows - the Ruby CSV library can return empty lines as [nil]
+        # ignore empty rows
         next if row.nil? || row.empty? || row == [nil]
         built_rows << builder.build(row)
       end

data/lib/honey_format/value_converter.rb

@@ -0,0 +1,112 @@
+require 'date'
+require 'time'
+require 'set'
+require 'digest'
+
+require 'honey_format/header_column_converter'
+
+module HoneyFormat
+  # Converts values
+  class ValueConverter
+    TRUTHY = Set.new(%w[t T 1 y Y true TRUE]).freeze
+    FALSY = Set.new(%w[f F 0 n N false FALSE]).freeze
+
+    CONVERT_BOOLEAN = lambda { |v|
+      value = v&.downcase
+      if TRUTHY.include?(value)
+        true
+      elsif FALSY.include?(value)
+        false
+      else
+        nil
+      end
+    }
+
+    # Default value converters
+    DEFAULT_CONVERTERS = {
+      # strict variants
+      decimal!: proc { |v| Float(v) },
+      integer!: proc { |v| Integer(v) },
+      date!: proc { |v| Date.parse(v) },
+      datetime!: proc { |v| Time.parse(v) },
+      symbol!: proc { |v| v&.to_sym || raise(ArgumentError, "can't convert nil to symbol") },
+      downcase!: proc { |v| v&.downcase || raise(ArgumentError, "can't convert nil to downcased string") },
+      upcase!: proc { |v| v&.upcase || raise(ArgumentError, "can't convert nil to upcased string") },
+      boolean!: proc { |v|
+        value = CONVERT_BOOLEAN.call(v)
+        raise(ArgumentError, "can't convert #{v} to boolean") if value.nil?
+        value
+      },
+      # safe variants
+      decimal: proc { |v| Float(v) rescue nil },
+      integer: proc { |v| Integer(v) rescue nil },
+      date: proc { |v| Date.parse(v) rescue nil },
+      datetime: proc { |v| Time.parse(v) rescue nil },
+      symbol: proc { |v| v&.to_sym },
+      downcase: proc { |v| v&.downcase },
+      upcase: proc { |v| v&.upcase },
+      boolean: proc { |v| CONVERT_BOOLEAN.call(v) },
+      md5: proc { |v| Digest::MD5.hexdigest(v) if v },
+      nil: proc {},
+      header_column: HeaderColumnConverter,
+    }.freeze
+
+    # Instantiate a value converter
+    def initialize
+      @converters = DEFAULT_CONVERTERS.dup
+    end
+
+    # Returns list of registered types
+    # @return [Array<Symbol>] list of registered types
+    def types
+      @converters.keys
+    end
+
+    # Register a value converter
+    # @param [Symbol, String] type the name of the type
+    # @param [#call] converter that responds to #call
+    # @return [ValueConverter] returns self
+    # @raise [ValueTypeExistsError] if type is already registered
+    def register(type, converter)
+      self[type] = converter
+      self
+    end
+
+    # Convert value
+    # @param [Symbol, String] type the name of the type
+    # @param [Object] value to be converted
+    def call(value, type)
+      self[type].call(value)
+    end
+
+    # Register a value converter
+    # @param [Symbol, String] type the name of the type
+    # @param [#call] converter that responds to #call
+    # @return [Object] returns the converter
+    # @raise [ValueTypeExistsError] if type is already registered
+    def []=(type, converter)
+      type = type.to_sym
+
+      if type?(type)
+        raise(Errors::ValueTypeExistsError, "type '#{type}' already exists")
+      end
+
+      @converters[type] = converter
+    end
+
+    # @param [Symbol, String] type the name of the type
+    # @return [Object] returns the converter
+    # @raise [UnknownValueTypeError] if type does not exist
+    def [](type)
+      @converters.fetch(type.to_sym) do
+        raise(Errors::UnknownValueTypeError, "unknown type '#{type}'")
+      end
+    end
+
+    # @param [Symbol, String] type the name of the type
+    # @return [true, false] true if type exists, false otherwise
+    def type?(type)
+      @converters.key?(type.to_sym)
+    end
+  end
+end