csv_party 0.0.1.pre9 → 1.0.0.rc4

data/lib/csv_party/dsl.rb

@@ -0,0 +1,38 @@
+module CSVParty
+  module DSL
+    def column(column, options = {}, &block)
+      config.add_column(column, options, &block)
+    end
+
+    def rows(&block)
+      config.row_importer = block
+    end
+
+    def import(&block)
+      config.file_importer = block
+    end
+
+    def errors(setting = nil, &block)
+      config.error_handler = setting || block
+    end
+
+    def skipped_rows(setting = nil, &block)
+      config.skipped_row_handler = setting || block
+    end
+
+    def aborted_rows(setting = nil, &block)
+      config.aborted_row_handler = setting || block
+    end
+
+    def depends_on(*args)
+      config.add_dependency(*args)
+      args.each do |arg|
+        attr_accessor arg
+      end
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+  end
+end

data/lib/csv_party/errors.rb

@@ -0,0 +1,157 @@
+module CSVParty
+  class Error < StandardError
+  end
+
+  class UnknownParserError < Error
+    def initialize(column, parser, named_parsers)
+      parser  = parser.to_s.gsub('parse_', '')
+      parsers = named_parsers.map { |p| p.to_s.gsub('parse_', '') }
+
+      super <<-MESSAGE
+You're trying to use the :#{parser} parser for the :#{column} column, but it
+doesn't exist. Available parsers are: :#{parsers.join(', :')}.
+      MESSAGE
+    end
+  end
+
+  class MissingCSVError < Error
+    def initialize(importer)
+      super <<-MESSAGE
+You must specify a file path, IO object, or string to import:
+
+    # File path, IO object, or string
+    csv = 'path/to/csv'
+    csv = File.open('path/to/csv')
+    csv = 'Header1,Header2\\nvalue1,value2\\n'
+
+Then, you assign that to your importer one of two ways:
+
+    importer = #{importer.class.name}.new(csv)
+    # or
+    importer = #{importer.class.name}.new
+    importer.csv = csv
+      MESSAGE
+    end
+  end
+
+  class NonexistentCSVFileError < Error
+    def initialize(file_path)
+      super <<-MESSAGE
+The CSV file you are trying to import was not found:
+
+    #{file_path}
+
+NOTE: If you are trying to import a single line CSV string, please ensure that
+your CSV string has a header row and at least one row of values. Single line
+strings are assumed to be a path to a CSV file.
+      MESSAGE
+    end
+  end
+
+  class UnrecognizedOptionsError < Error
+    def initialize(unrecognized_options, valid_data_options, valid_csv_options, dependencies)
+      @unrecognized_options = unrecognized_options
+      @valid_data_options = valid_data_options
+      @valid_csv_options = valid_csv_options
+      @dependencies = dependencies
+
+      super csv_and_data_options_message + dependency_options_message
+    end
+
+    def csv_and_data_options_message
+      <<-MESSAGE
+The following options are not recognized: :#{@unrecognized_options.join(', :')}.
+You can specify your CSV data via the :path, :file, or :content options, as well
+as any options that the CSV library understands:
+
+    :#{@valid_csv_options.join("\n    :")}
+      MESSAGE
+    end
+
+    def dependency_options_message
+      return '' unless @dependencies.any?
+
+      <<-MESSAGE
+
+Or assignments for dependencies:
+
+    :#{@dependencies.join("\n    :")}
+      MESSAGE
+    end
+  end
+
+  class DuplicateColumnError < Error
+    def initialize(name)
+      super <<-MESSAGE
+A column named :#{name} has already been defined, please choose a different name.
+      MESSAGE
+    end
+  end
+
+  class ReservedColumnNameError < Error
+    def initialize(reserved_column_names)
+      super <<-MESSAGE
+The following column names are reserved for interal use, please use a different
+column name: :#{reserved_column_names.join(', :')}.
+      MESSAGE
+    end
+  end
+
+  class MissingColumnError < Error
+    def initialize(headers, missing_columns)
+      columns = missing_columns.join("', '")
+      super <<-MESSAGE
+The CSV is missing column(s) with header(s) '#{columns}'. File has these
+headers: #{headers.join(', ')}.
+      MESSAGE
+    end
+  end
+
+  class UndefinedRowProcessorError < Error
+    def initialize
+      super <<-MESSAGE
+Your importer has to define a row processor which specifies what should be done
+with each row. It should look something like this:
+
+    rows do |row|
+      row.column  # access parsed column values
+      row.unparsed.column  # access unparsed column values
+    end
+      MESSAGE
+    end
+  end
+
+  class MissingDependencyError < Error
+    def initialize(importer, dependency)
+      super <<-MESSAGE
+This importer depends on #{dependency}, but you didn't assign it.
+You can do that when instantiating your importer:
+
+    #{importer.class.name}.new('path/to/csv', #{dependency}: #{dependency})
+
+Or any time before you import:
+
+    importer = #{importer.class.name}.new('path/to/csv')
+    importer.#{dependency} = #{dependency}
+    importer.import!
+      MESSAGE
+    end
+  end
+
+  class UnimportedRowsError < Error
+    def initialize
+      super <<-MESSAGE
+The rows in your CSV file have not been imported.
+
+You should include a call to import_rows! at the point in your import block
+where you want them to be imported. It should should look something like this:
+
+    import do
+      # do stuff before importing rows
+      import_rows!
+      # do stuff after importing rows
+    end
+      MESSAGE
+    end
+  end
+end

data/lib/csv_party/parsers.rb

@@ -0,0 +1,71 @@
+module CSVParty
+  module Parsers
+    def parse_raw(value)
+      value
+    end
+
+    def parse_string(value)
+      value.to_s.strip
+    end
+
+    def parse_boolean(value)
+      value = value.to_s.strip.downcase
+
+      if %w[1 t true].include? value
+        true
+      elsif %w[0 f false].include? value
+        false
+      else
+        nil
+      end
+    end
+
+    def parse_integer(value)
+      prepare_numeric_value(value).to_i
+    end
+
+    def parse_decimal(value)
+      BigDecimal.new(prepare_numeric_value(value))
+    end
+
+    def parse_date(value, format = nil)
+      if format.nil?
+        Date.parse(value)
+      else
+        Date.strptime(value, format)
+      end
+    rescue ArgumentError
+      nil
+    end
+
+    def parse_time(value, format = nil)
+      if format.nil?
+        DateTime.parse(value).to_time
+      else
+        DateTime.strptime(value, format).to_time
+      end
+    rescue ArgumentError
+      nil
+    end
+
+    private
+
+    def prepare_numeric_value(value)
+      value = value.to_s.strip
+      value = convert_from_accounting_notation(value)
+      strip_non_numeric_characters(value)
+    end
+
+    def convert_from_accounting_notation(value)
+      if value =~ /\A\(.*\)\z/
+        value.delete('()').insert(0, '-')
+      else
+        value
+      end
+    end
+
+    def strip_non_numeric_characters(value)
+      value.gsub(/[^\-0-9.]/, '')
+    end
+  end
+end

data/lib/csv_party/row.rb

@@ -0,0 +1,83 @@
+module CSVParty
+  class Row
+    attr_accessor :row_number, :csv_string, :unparsed
+
+    def initialize(csv_row, config, runner)
+      @csv_row = csv_row
+      @config = config
+      @runner = runner
+      @attributes = OpenStruct.new
+      parse_row!(csv_row)
+    end
+
+    private
+
+    def parse_row!(csv_row)
+      self.csv_string = csv_row.to_csv
+      self.unparsed = extract_unparsed_values(csv_row)
+
+      @config.columns.each do |column, options|
+        header = options[:header]
+        value = csv_row[header]
+        @attributes[column] = parse_value(value, options)
+      end
+    end
+
+    def extract_unparsed_values(csv_row)
+      unparsed_row = OpenStruct.new
+      config.columns.each do |column, options|
+        header = options[:header]
+        unparsed_row[column] = csv_row[header]
+      end
+
+      return unparsed_row
+    end
+
+    def parse_value(value, options)
+      return nil if options[:intercept_blanks] && is_blank?(value)
+
+      parser = options[:parser]
+
+      if parser.is_a?(Symbol)
+        parse_with_method(value, options)
+      else
+        parse_with_block(value, options)
+      end
+    end
+
+    def parse_with_method(value, options)
+      format = options[:format]
+      parser = options[:parser]
+
+      if format.nil?
+        send(parser, value)
+      else
+        send(parser, value, format)
+      end
+    end
+
+    def parse_with_block(value, options)
+      parser = options[:parser]
+
+      instance_exec(value, &parser)
+    end
+
+    def is_blank?(value)
+      value.nil? || value.strip.empty?
+    end
+
+    def respond_to_missing?(method, _include_private)
+      @attributes.respond_to?(method) || @runner.respond_to?(method, true)
+    end
+
+    def method_missing(method, *args)
+      if @attributes.respond_to?(method)
+        @attributes.send(method, *args)
+      elsif @runner.respond_to?(method, true)
+        @runner.send(method, *args)
+      else
+        super
+      end
+    end
+  end
+end

data/lib/csv_party/runner.rb

@@ -0,0 +1,219 @@
+require 'csv_party/parsers'
+
+module CSVParty
+  class Runner
+    include Parsers
+
+    attr_accessor :csv, :config, :importer
+
+    def initialize(csv, config, importer)
+      self.csv = csv
+      self.config = config
+      self.importer = importer
+      @_rows_have_been_imported = false
+      @_current_row_number = 1
+    end
+
+    def import!
+      raise_unless_row_processor_is_defined!
+      raise_unless_all_named_parsers_exist!
+      raise_unless_all_dependencies_are_present!
+      initialize_csv!
+      initialize_regex_headers!
+      raise_unless_csv_has_all_columns!
+
+      if config.file_importer
+        instance_exec(&config.file_importer)
+        raise_unless_rows_have_been_imported!
+      else
+        import_rows!
+      end
+
+      return true
+    rescue AbortedImportError => error
+      importer.aborted = true
+      importer.abort_message = error.message
+      return false
+    end
+
+    def present_columns
+      @_headers
+    end
+
+    def missing_columns
+      config.required_columns - present_columns
+    end
+
+    private
+
+    def initialize_csv!
+      csv.shift
+      @_headers = csv.headers
+      csv.rewind
+    end
+
+    def import_rows!
+      loop do
+        begin
+          row = csv.shift
+          break unless row
+          import_row!(row)
+        rescue NextRowError
+          next
+        rescue SkippedRowError => error
+          handle_skipped_row(error)
+        rescue AbortedRowError => error
+          handle_aborted_row(error)
+        rescue AbortedImportError
+          raise
+        rescue CSV::MalformedCSVError
+          raise
+        rescue StandardError => error
+          handle_error(error, @_current_row_number, row.to_csv)
+        end
+      end
+
+      @_rows_have_been_imported = true
+    end
+
+    def import_row!(csv_row)
+      @_current_row_number += 1
+      @_current_parsed_row = Row.new(csv_row, config, self)
+      @_current_parsed_row.row_number = @_current_row_number
+      instance_exec(@_current_parsed_row, &config.row_importer)
+    end
+
+    def next_row!
+      raise NextRowError
+    end
+
+    def skip_row!(message = nil)
+      raise SkippedRowError, message
+    end
+
+    def abort_row!(message = nil)
+      raise AbortedRowError, message
+    end
+
+    def abort_import!(message)
+      raise AbortedImportError, message
+    end
+
+    def handle_error(error, line_number, csv_string)
+      raise error unless config.error_handler
+
+      if config.error_handler == :ignore
+        error_rows << error_struct(error, line_number, csv_string)
+      else
+        instance_exec(error, line_number, csv_string, &config.error_handler)
+      end
+    end
+
+    def handle_skipped_row(error)
+      return if config.skipped_row_handler == :ignore
+
+      @_current_parsed_row[:skip_message] = error.message
+
+      if config.skipped_row_handler.nil?
+        importer.skipped_rows << @_current_parsed_row
+      else
+        instance_exec(@_current_parsed_row, &config.skipped_row_handler)
+      end
+    end
+
+    def handle_aborted_row(error)
+      return if config.aborted_row_handler == :ignore
+
+      @_current_parsed_row[:abort_message] = error.message
+
+      if config.aborted_row_handler.nil?
+        importer.aborted_rows << @_current_parsed_row
+      else
+        instance_exec(@_current_parsed_row, &config.aborted_row_handler)
+      end
+    end
+
+    def error_struct(error, line_number, csv_string)
+      Struct.new(:error, :line_number, :csv_string)
+            .new(error, line_number, csv_string)
+    end
+
+    def raise_unless_row_processor_is_defined!
+      return if config.row_importer
+
+      raise UndefinedRowProcessorError.new
+    end
+
+    def raise_unless_rows_have_been_imported!
+      return if @_rows_have_been_imported
+
+      raise UnimportedRowsError.new
+    end
+
+    def raise_unless_all_dependencies_are_present!
+      config.dependencies.each do |dependency|
+        next unless importer.send(dependency).nil?
+
+        raise MissingDependencyError.new(self, dependency)
+      end
+    end
+
+    # This error has to be raised at runtime because, when the class body
+    # is being executed, the parser methods won't be available unless
+    # they are defined above the column definitions in the class body
+    def raise_unless_all_named_parsers_exist!
+      config.columns_with_named_parsers.each do |name, options|
+        parser = options[:parser]
+        next if named_parsers.include? parser
+
+        raise UnknownParserError.new(name, parser, named_parsers)
+      end
+    end
+
+    def named_parsers
+      (methods +
+       private_methods +
+       importer.methods +
+       importer.private_methods).grep(/^parse_/)
+    end
+
+    def raise_unless_csv_has_all_columns!
+      return if missing_columns.empty?
+
+      raise MissingColumnError.new(present_columns, missing_columns)
+    end
+
+    def initialize_regex_headers!
+      config.columns_with_regex_headers.each do |name, options|
+        found_header = @_headers.find do |header|
+          options[:header].match(header)
+        end
+        options[:header] = found_header || name.to_s
+      end
+    end
+
+    def respond_to_missing?(method, _include_private)
+      importer.respond_to?(method, true)
+    end
+
+    def method_missing(method, *args)
+      if importer.respond_to?(method, true)
+        importer.send(method, *args)
+      else
+        super
+      end
+    end
+
+    class NextRowError < Error
+    end
+
+    class SkippedRowError < Error
+    end
+
+    class AbortedRowError < Error
+    end
+
+    class AbortedImportError < Error
+    end
+  end
+end