row_boat 0.1.0.alpha.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5341bb8c702726b4d6dd4ed105339121815f41ab
-  data.tar.gz: 8bc96cb40cc2f160df283acc73d6e9b767212cad
+  metadata.gz: 42b9a926cbca073ac25906f8f3ca224d2d665b62
+  data.tar.gz: 28e138c7db5dfa6e8ef4139c82033551da7b6dfe
 SHA512:
-  metadata.gz: 4c75ea55754040da725c9919e70f4d84efecb261db688d9f00142d454d3931bb8e81f8c99903297029349a75f627d68b2d9847ed32663f97901334f00f1baccf
-  data.tar.gz: f12351b6332d266d841ad07941fe415c0a5a9d23a35cc1e54996cafda6c91cd5ef4c629ea7fffb48419122fa38137cbe16cd2d0711a76222218b8b8dad29d9bc
+  metadata.gz: cfc989f812ad764feae56ab730d64fe5f6f5e57306eef8cf46c3940f5ba22394916bd9bd7372d2468a4f06141d9348fa82eae5a7a49f8dc47f165f0e6bf1b5ab
+  data.tar.gz: 7007c0b60355e42523f5f6b4158c7ae5c82c7d80e012f557dda2093841db42be017f8c54f7e142ee761764ef5f2476d0073af1d35b58b636be393e9b8ea24afc

data/.travis.yml

@@ -1,5 +1,18 @@
+dist: trusty
 sudo: false
 language: ruby
 rvm:
   - 2.3.3
-before_install: gem install bundler -v 1.14.6
+  - 2.4.1
+addons:
+  postgresql: '9.6'
+before_install:
+  - gem update --system
+  - gem --version
+  - gem install bundler -v 1.14.6
+before_script:
+  - bundle exec rake db:create
+  - bundle exec rake db:migrate
+cache: bundler
+gemfile:
+  - gemfiles/csv_import_1.1_and_0.18.gemfile

data/API.md

@@ -0,0 +1,355 @@
+# RowBoat API
+
+This is really more of a summary of what you can do with `RowBoat::Base` since you subclass it to do everything :)
+
+## Contents
+
+- [Basic Usage](#basic-usage)
+- [`.import`](#import)
+- [`initialize`](#initialize)
+- [`import`](#import-1)
+- [`import_into`](#import_into)
+- [`csv_source`](#csv_source)
+- [`column_mapping`](#column_mapping)
+- [`preprocess_row`](#preprocess_row)
+- [`preprocess_rows`](#preprocess_rows)
+- [`options`](#options)
+- [`handle_failed_row`](#handle_failed_row)
+- [`handle_failed_rows`](#handle_failed_rows)
+- [`value_converters`](#value_converters)
+
+## Basic Usage
+
+Just subclass `RowBoat::Base` and define the [`import_into`](#import_into) and [`column_mapping`](#column_mapping) methods to get started (They're the only methods that you're required to implement).
+
+```ruby
+class ImportProduct < RowBoat::Base
+  def import_into
+    Product
+  end
+
+  def column_mapping
+    {
+      downcased_csv_column_header: :model_attribute_name,
+      another_downcased_csv_column_header: :another_model_attribute_name
+    }
+  end
+end
+```
+
+## `.import`
+
+### Description
+Imports database records form the given CSV-like object. The CSV-like object can be anything that can be passed to [`SmarterCSV.process`](https://github.com/tilo/smarter_csv#documentation) (string paths to files, files, tempfiles, instances of StringIO, etc).
+
+It returns a hash containing
+
+- `:invalid_records` - an array of all records that failed to import since they were invalid. If you've configured the `:validate` option to be `false` it will be an empty array.
+- `:total_inserted` - the total number of records inserted into the database.
+- `:inserted_ids` - an array of all of the ids of records inserted into the database.
+
+If you want to pass additional information to help import CSVs, *don't override this method*. It just passes through to [`initialize`](#initialize) so override that :)
+
+### Example
+
+#### Basic Use
+
+```ruby
+class ImportProduct < RowBoat::Base
+  # required configuration omitted for brevity
+end
+
+ImportProduct.import("path/to/my.csv")
+```
+
+#### Advanced Use
+
+```ruby
+class ImportProduct < RowBoat::Base
+  # required configuration omitted for brevity
+  def intitialize(csv_source, my_options)
+    super(csv_source)
+    @my_options = my_options
+  end
+end
+
+ImportProduct.import("path/to/my.csv", foo: "bar")
+```
+
+## `initialize`
+
+### Description
+
+Makes a new instance with the given CSV-like object. See [`.import`](#import) for more details around when and how to override this method.
+
+## `import`
+
+### Description
+
+The instance method that actually parses and imports the CSV. Generally, you wouldn't call this directly and would instead call [`.import`](#import).
+
+## `import_into`
+
+### Description
+
+It is required that you override this method to return whatever ActiveRecord class you want your CSV imported into.
+
+### Example
+
+#### Basic Use
+
+```ruby
+class ImportProduct < RowBoat::Base
+  # other required configuration omitted for brevity
+  def import_into
+    Product
+  end
+end
+```
+
+#### Advanced Use
+
+```ruby
+class ImportProduct < RowBoat::Base
+  # other required configuration omitted for brevity
+  def import_into
+    if csv_source.is_a?(String) && csv_source.match(/category/i)
+      ProductCategory
+    else
+      Product
+    end
+  end
+end
+
+ImportProduct.import("path/to/category.csv")
+ImportProduct.import("path/to/product.csv")
+```
+
+
+## `csv_source`
+
+### Description
+
+Whatever you originally passed in as the CSV source.
+
+### Example
+
+```ruby
+class ImportProduct < RowBoat::Base
+  # other required configuration omitted for brevity
+  def import_into
+    # `csv_source` is available in any of our instance methods
+    if csv_source.is_a?(String) && csv_source.match(/category/i)
+      ProductCategory
+    else
+      Product
+    end
+  end
+end
+
+ImportProduct.import("path/to/category.csv")
+ImportProduct.import("path/to/product.csv")
+```
+
+## `column_mapping`
+
+### Description
+
+It is required that you override this method with a hash that maps columns in your CSV to their preferred names.
+
+By default
+- CSV column names are downcased symbols of what they look like in the CSV.
+- CSV columns that are not mapped are ignored when processing the CSV.
+
+If you're familiar with [SmarterCSV](https://github.com/tilo/smarter_csv#documentation), this method essentially defines your `:key_mapping` and with the `:remove_unmapped_keys` setting set to `true`.
+
+You can change these defaults by overriding the [`options`](#options) method.
+
+### Example
+
+```ruby
+class ImportProduct < RowBoat::Base
+  # other required configuration omitted for brevity
+  def column_mapping
+    {
+      prdct_nm: :name,
+      "price/cost_amnt": :price_in_cents
+    }
+  end
+end
+```
+
+## `preprocess_row`
+
+### Description
+
+Implement this method if you need to do some work on the row before the record is inserted/updated.
+
+If you return `nil` from this method, the row will be skipped in the import.
+
+If the work you intend to do with the row only requires changing one attribute, it is recommended that you override [`value_converters`](#value_converters) instead of this.
+
+### Example
+
+```ruby
+  class ImportProduct < RowBoat::Base
+    # required configuration omitted for brevity
+    def preprocess_row(row)
+      { default: :value }.merge(row)
+    end
+    # or...
+    def preprocess_row(row)
+      if row[:name] && row[:price]
+        row
+      else
+        nil
+      end
+    end
+  end
+```
+
+## `preprocess_rows`
+
+### Description
+
+Override this method if you need to do something with a chunk of rows (the chunk size is determined by the `:chunk_size` option in the [`options`](#options) method).
+
+If you need to filter particular rows, it's better to just implement [`preprocess_row`](#preprocess_row) and return `nil` for the rows you want to ignore.
+
+### Example
+
+```ruby
+class ImportProduct < RowBoat::Base
+  # required configuration omitted for brevity
+  def preprocess_rows(rows)
+    if skip_batch?(rows)
+      super([])
+    else
+      super
+    end
+  end
+
+  def skip_batch?(rows)
+    # decide whether or not to skip the batch
+  end
+end
+```
+
+## `options`
+
+### Description
+
+Implement this to configure RowBoat, [SmarterCSV](https://github.com/tilo/smarter_csv), and [activerecord-import](https://github.com/zdennis/activerecord-import).
+
+Except for `:wrap_in_transaction`, all options pass through to SmarterCSV and activerecord-import.
+
+`:wrap_in_transaction` simply tells RowBoat whether or not you want your whole import wrapped in a database transaction.
+
+Whatever you define in this method will be merged into the defaults:
+
+  - `:chunk_size` - `500`
+  - `:key_mapping` - `column_mapping`
+  - `:recursive` - `true`
+  - `:remove_unmapped_keys` - `true`
+  - `:validate` - `true`
+  - `:value_converters` - `csv_value_converters`
+  - `:wrap_in_transaction` - `true`
+
+Don't provide `value_converters` or `key_mapping` options here. Implement the [`value_converters`](#value_converters) and [`column_mapping`](#column_mapping) respectively.
+
+### Example
+
+```ruby
+class ImportProduct < RowBoat::Base
+  # required configuration omitted for brevity
+  def options
+    {
+      chunk_size: 1000,
+      validate: false,
+      wrap_in_transaction: false
+    }
+  end
+end
+```
+
+## `handle_failed_row`
+
+### Description
+
+Implement this to do some work with a row that has failed to import.
+
+It's important to note that
+- This happens after the import has completed.
+- The given row is an instance of whatever class was returned by [`import_into`](#import_into).
+
+These records are also available in the return value of [`.import`](#import).
+
+### Example
+
+```ruby
+class ImportProduct < RowBoat::Base
+  # required configuration omitted for brevity
+  def handle_failed_row(row)
+    puts row.errors.full_messages.join(", ")
+  end
+end
+```
+
+## `handle_failed_rows`
+
+### Description
+
+Override this method to do some work will all of the rows that failed to import.
+
+### Example
+
+```ruby
+class ImportProduct < RowBoat::Base
+  # required configuration omitted for brevity
+  def handle_failed_rows(rows)
+    puts "Failed to import #{rows.size} rows :("
+    super
+  end
+end
+```
+
+## `value_converters`
+
+### Description
+
+Implement to specify how to translate values from the CSV into whatever sorts of objects you need.
+
+Simply return a hash that has the mapped column name (ie, what you mapped it to in the [`column_mapping`](#column_mapping) method) as a key pointing to either
+- a method name as a symbol
+- a proc or lambda
+- an object that implements `convert`
+
+Regardless of which one you choose, it takes a value and returns a converted value.
+
+This is essentially a sugared up version of `:value_converters` option in [SmarterCSV](https://github.com/tilo/smarter_csv#documentation).
+
+### Example
+
+```ruby
+class ImportProduct < RowBoat::Base
+  # required configuration omitted for brevity
+  def value_converters
+    {
+      sell_by: :convert_date,
+      name: -> (value) { value.titlelize },
+      price: proc { |value| value.to_i },
+      description: DescriptionConverter
+    }
+  end
+
+  def convert_date(value)
+    Date.parse(value) rescue nil
+  end
+end
+
+module DescriptionConverter
+  def self.convert(value)
+    value.present? ? value : "default description :("
+  end
+end
+```

data/Appraisals

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+appraise "csv_import_1.1_and_0.18" do
+  gem "activerecord-import", "~> 0.18.2"
+  gem "smarter_csv", "~> 1.1.0"
+end

data/README.md

@@ -1,13 +1,29 @@
 # RowBoat
 
+Created by &nbsp;&nbsp;&nbsp; [<img src="https://raw.githubusercontent.com/devmynd/row_boat/master/devmynd-logo.png" alt="DevMynd Logo" />](https://www.devmynd.com/)
+
+[![Gem Version](https://badge.fury.io/rb/row_boat.svg)](http://badge.fury.io/rb/row_boat) &nbsp;&nbsp;&nbsp;[![Build Status](https://travis-ci.org/devmynd/row_boat.svg?branch=master)](https://travis-ci.org/devmynd/row_boat)
+
 A simple gem to help you import CSVs into your ActiveRecord models.
 
+[Check out the documentation!](/API.md#rowboat-api)
+
+It uses [SmarterCSV](https://github.com/tilo/smarter_csv) and [`activerecord-import`](https://github.com/zdennis/activerecord-import) to import database records from your CSVs.
+
+## Contents
+
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "row_boat"
+gem "row_boat", "~> 0.1"
 ```
 
 And then execute:
@@ -18,45 +34,72 @@ Or install it yourself as:
 
     $ gem install row_boat
 
-## Usage
+## Basic Usage
+
+#### [Full documentation can be found here.](/API.md#rowboat-api)
+
+Below we're defining the required methods ([`import_into`](/API.md#import_into) and [`column_mapping`](/API.md#column_mapping)) and a few additional options as well (via [`value_converters`](/API.md#value_converters) and [`options`](/API.md#options)). Checkout [API.md](/API.md#rowboat-api) for the full documentation for more :)
 
 ```ruby
-class ProductBoat < RowBoat::Base
+class ImportProduct
   # required
   def import_into
-    Product
+    Product # The ActiveRecord class we want to import records into.
   end
 
   # required
   def column_mapping
     {
-      downcased_csv_column_header: :model_attribute_name,
-      another_downcased_csv_column_header: :another_model_attribute_name
+      # `:prdct_name` is the downcased and symbolized version
+      # of our column header, while `:name` is the attribute
+      # of our model we want to receive `:prdct_name`'s value
+      prdct_name: :name,
+      dllr_amnt: :price_in_cents,
+      desc: :description
     }
   end
 
   # optional
-  def options
-    super.merge(validate: false)
+  def value_converters
+    {
+      # Allows us to change values we want to import
+      # before we import them
+      price_in_cents: -> (value) { value * 1000 }
+    }
   end
-end
 
-# Later...
+  # optional
+  def preprocess_row(row)
+    if row[:name] && row[:description] && row[:price]
+      row
+    else
+      nil # return nil to skip a row
+    end
+    # we could also remove some attributes or do any
+    # other kind of work we want with the given row.
+  end
 
-ProductBoat.import(path_to_csv)
+  #optional
+  def options
+    {
+      # These are additional configurations that
+      # are generally passed through to SmarterCSV
+      # and activerecord-import
+      validate: false, # this defaults to `true`
+      wrap_in_transaction: false # this defaults to `true`
+    }
+  end
+end
 ```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake` to run the tests (run `appraisal install` and `appraisal rake` to run the tests against different combinations of dependencies). You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/devmynd/row_boat. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/bin/setup

@@ -6,3 +6,5 @@ set -vx
 bundle install
 
 # Do any other automated setup that you need to do here
+bundle exec rake db:create
+bundle exec rake db:migrate

data/gemfiles/csv_import_1.1_and_0.18.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord-import", "~> 0.18.2"
+gem "smarter_csv", "~> 1.1.0"
+
+gemspec path: "../"

data/gemfiles/csv_import_1.1_and_0.18.gemfile.lock

@@ -0,0 +1,144 @@
+PATH
+  remote: ..
+  specs:
+    row_boat (0.1.0)
+      activerecord (>= 5.0.0)
+      activerecord-import (~> 0.18.2)
+      smarter_csv (~> 1.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionpack (5.1.0)
+      actionview (= 5.1.0)
+      activesupport (= 5.1.0)
+      rack (~> 2.0)
+      rack-test (~> 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (5.1.0)
+      activesupport (= 5.1.0)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.3)
+    activemodel (5.1.0)
+      activesupport (= 5.1.0)
+    activerecord (5.1.0)
+      activemodel (= 5.1.0)
+      activesupport (= 5.1.0)
+      arel (~> 8.0)
+    activerecord-import (0.18.3)
+      activerecord (>= 3.2)
+    activesupport (5.1.0)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (~> 0.7)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    appraisal (2.2.0)
+      bundler
+      rake
+      thor (>= 0.14.0)
+    arel (8.0.0)
+    ast (2.3.0)
+    awesome_print (1.7.0)
+    builder (3.2.3)
+    coderay (1.1.1)
+    concurrent-ruby (1.0.5)
+    database_cleaner (1.6.1)
+    diff-lcs (1.3)
+    erubi (1.6.0)
+    i18n (0.8.1)
+    loofah (2.0.3)
+      nokogiri (>= 1.5.9)
+    method_source (0.8.2)
+    mini_portile2 (2.1.0)
+    minitest (5.10.2)
+    nokogiri (1.7.2)
+      mini_portile2 (~> 2.1.0)
+    parser (2.4.0.0)
+      ast (~> 2.2)
+    pg (0.20.0)
+    powerpack (0.1.1)
+    pry (0.10.4)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    pry-doc (0.10.0)
+      pry (~> 0.9)
+      yard (~> 0.9)
+    pry-nav (0.2.4)
+      pry (>= 0.9.10, < 0.11.0)
+    rack (2.0.2)
+    rack-test (0.6.3)
+      rack (>= 1.0)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.0.3)
+      loofah (~> 2.0)
+    railties (5.1.0)
+      actionpack (= 5.1.0)
+      activesupport (= 5.1.0)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.18.1, < 2.0)
+    rainbow (2.2.2)
+      rake
+    rake (10.5.0)
+    rspec (3.6.0)
+      rspec-core (~> 3.6.0)
+      rspec-expectations (~> 3.6.0)
+      rspec-mocks (~> 3.6.0)
+    rspec-core (3.6.0)
+      rspec-support (~> 3.6.0)
+    rspec-expectations (3.6.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.6.0)
+    rspec-mocks (3.6.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.6.0)
+    rspec-support (3.6.0)
+    rubocop (0.48.1)
+      parser (>= 2.3.3.1, < 3.0)
+      powerpack (~> 0.1)
+      rainbow (>= 1.99.1, < 3.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    ruby-progressbar (1.8.1)
+    slop (3.6.0)
+    smarter_csv (1.1.4)
+    standalone_migrations (5.2.1)
+      activerecord (>= 4.2.7, < 5.2.0)
+      railties (>= 4.2.7, < 5.2.0)
+      rake (~> 10.0)
+    thor (0.19.4)
+    thread_safe (0.3.6)
+    tzinfo (1.2.3)
+      thread_safe (~> 0.1)
+    unicode-display_width (1.2.1)
+    yard (0.9.9)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord-import (~> 0.18.2)
+  appraisal (~> 2.2.0)
+  awesome_print
+  bundler (~> 1.14)
+  database_cleaner (~> 1.6.0)
+  pg
+  pry
+  pry-doc
+  pry-nav
+  rake (~> 10.0)
+  row_boat!
+  rspec (~> 3.0)
+  rubocop (~> 0.48.1)
+  smarter_csv (~> 1.1.0)
+  standalone_migrations (~> 5.2.0)
+  yard (~> 0.9.9)
+
+BUNDLED WITH
+   1.14.6

data/lib/row_boat/base.rb

@@ -9,15 +9,36 @@ module RowBoat
     attr_reader :csv_source
 
     class << self
+      # Imports database records from the given CSV-like object.
+      #
+      # @overload import(csv_source)
+      #   @param csv_source [String, #read] a CSV-like object that SmarterCSV can read.
+      #
+      # @return [Hash] a hash with +:invalid_records+, +:total_inserted+ and +:inserted_ids+.
+      #
+      # @see https://github.com/tilo/smarter_csv#documentation SmarterCSV Docs
       def import(*args, &block)
         new(*args, &block).import
       end
     end
 
+    # Makes a new instance with the given +csv_source+.
+    #
+    # @abstract Override this method if you need additional arguments to process your CSV (like defaults).
+    #
+    # @example
+    #   def initialize(csv_source, default_name)
+    #     super(csv_source)
+    #     @default_name = default_name
+    #   end
     def initialize(csv_source)
       @csv_source = csv_source
     end
 
+    # Parses the csv and inserts/updates the database. You probably won't call this method directly,
+    # instead you would call {RowBoat::Base.import}.
+    #
+    # @return [Hash] a hash with +:invalid_records+, +:total_inserted+ and +:inserted_ids+.
     def import
       import_results = []
 
@@ -32,24 +53,71 @@ module RowBoat
       end
     end
 
+    # Override with the ActiveRecord class that the CSV should be imported into.
+    #
+    # @abstract
+    #
+    # @note You must implement this method.
+    #
+    # @example
+    #   def import_into
+    #     Product
+    #   end
     def import_into
       raise NotImplementedError, not_implemented_error_message(__method__)
     end
 
+    # Override with a hash that maps CSV column names to their preferred names.
+    #   Oftentimes these are the names of the attributes on the model class from {#import_into}.
+    #
+    # @abstract
+    #
+    # @note You must implement this method.
+    #
+    # @example
+    #   def column_mapping
+    #     {
+    #       prdct_name: :name,
+    #       price: :price,
+    #       sl_exp: :sale_expires_at
+    #     }
+    #   end
+    #
+    # @see #import_into
     def column_mapping
       raise NotImplementedError, not_implemented_error_message(__method__)
     end
 
+    # Override this method if you need to do some work on the row before the record is
+    #   inserted/updated or want to skip the row in the import. Simply return +nil+ to skip the row.
+    #
+    # @abstract
+    #
+    # @note If you only need to manipulate one attribute (ie parse a date from a string, etc), then
+    #   you should probably use {#value_converters}
+    #
+    # @return [Hash,NilClass] a hash of attributes, +nil+, or even and instance of the class returned
+    #   in {#import_into}.
+    #
+    # @see #import_into
     def preprocess_row(row)
       row
     end
 
+    # @api private
     def import_rows(rows)
       import_options = ::RowBoat::Helpers.extract_import_options(merged_options)
       preprocessed_rows = preprocess_rows(rows)
       import_into.import(preprocessed_rows, import_options)
     end
 
+    # Override this method if you need to do something with a chunk of rows.
+    #
+    # @abstract
+    #
+    # @note If you want to filter out a row, you can just return +nil+ from {#preprocess_row}.
+    #
+    # @see #preprocess_row
     def preprocess_rows(rows)
       rows.each_with_object([]) do |row, preprocessed_rows|
         preprocessed_row = preprocess_row(row)
@@ -57,10 +125,31 @@ module RowBoat
       end
     end
 
+    # Override this method to specify CSV parsing and importing options.
+    #   All SmarterCSV and activerecord-import options can be listed here along with
+    #   +:wrap_in_transaction+. The defaults provided by RowBoat can be found in {#default_options}
+    #
+    # @abstract
+    #
+    # @note If you want to use the +:value_converters+ option provided by SmarterCSV
+    #   just override {#value_converters}.
+    #
+    # @return [Hash] a hash of configuration options.
+    #
+    # @see https://github.com/tilo/smarter_csv#documentation SmarterCSV docs
+    # @see https://github.com/zdennis/activerecord-import/wiki activerecord-import docs
+    # @see #value_converters
     def options
       {}
     end
 
+    # Default options provided by RowBoat for CSV parsing and importing.
+    #
+    # @note Do not override.
+    #
+    # @return [Hash] a hash of configuration options.
+    #
+    # @api private
     def default_options
       {
         chunk_size: 500,
@@ -73,22 +162,56 @@ module RowBoat
       }
     end
 
+    # @api private
     def merged_options
       default_options.merge(options)
     end
 
+    # Override this method to do some work with a row that has failed to import.
+    #
+    # @abstract
+    #
+    # @note +row+ here is actually an instance of the class returned in {#import_into}
+    #
+    # @see #import_into
     def handle_failed_row(row)
       row
     end
 
+    # Override this method to do some work will all of the rows that failed to import.
+    #
+    # @abstract
+    #
+    # @note If you override this method and {#handle_failed_row}, be sure to call +super+.
     def handle_failed_rows(rows)
       rows.each { |row| handle_failed_row(row) }
     end
 
+    # Override this method to specify how to translate values from the CSV
+    #   into ruby objects.
+    #
+    #   You can provide an object that implements +convert+, a proc or lambda, or the
+    #   the name of a method as a Symbol
+    #
+    # @abstract
+    #
+    # @example
+    #   def value_converters
+    #     {
+    #       name: -> (value) { value.titleize }
+    #       price: :convert_price,
+    #       expires_at: CustomDateConverter
+    #     }
+    #   end
+    #
+    #   def convert_price(value)
+    #     value || 0
+    #   end
     def value_converters
       {}
     end
 
+    # @api private
     def csv_value_converters
       value_converters.each_with_object({}) do |(key, potential_converter), converters_hash|
         case potential_converter
@@ -106,19 +229,27 @@ module RowBoat
 
     private
 
+    # @api private
+    # @private
     def not_implemented_error_message(method_name)
       "Subclasses of #{self.class.name} must implement `#{method_name}`"
     end
 
+    # @api private
+    # @private
     def parse_rows(&block)
       csv_options = ::RowBoat::Helpers.extract_csv_options(merged_options)
       ::SmarterCSV.process(csv_source, csv_options, &block)
     end
 
+    # @api private
+    # @private
     def transaction_if_needed(&block)
       merged_options[:wrap_in_transaction] ? import_into.transaction(&block) : yield
     end
 
+    # @api private
+    # @private
     def process_import_results(import_results)
       import_results.each_with_object(
         invalid_records: [],

data/lib/row_boat/helpers.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module RowBoat
+  # @api private
   module Helpers
     CSV_OPTION_KEYS = %i[
       chunk_size

data/lib/row_boat/value_converter.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module RowBoat
+  # @api private
   class ValueConverter
     attr_reader :converter
 

data/lib/row_boat/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RowBoat
-  VERSION = "0.1.0.alpha.3"
+  VERSION = "0.1.0"
 end

data/row_boat.gemspec

@@ -27,6 +27,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "activerecord-import", "~> 0.18.2"
   spec.add_dependency "smarter_csv", "~> 1.1"
 
+  spec.add_development_dependency "appraisal", "~> 2.2.0"
   spec.add_development_dependency "awesome_print"
   spec.add_development_dependency "bundler", "~> 1.14"
   spec.add_development_dependency "database_cleaner", "~> 1.6.0"
@@ -38,4 +39,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "rubocop", "~> 0.48.1"
   spec.add_development_dependency "standalone_migrations", "~> 5.2.0"
+  spec.add_development_dependency "yard", "~> 0.9.9"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: row_boat
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha.3
+  version: 0.1.0
 platform: ruby
 authors:
 - Michael Crismali
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-05-12 00:00:00.000000000 Z
+date: 2017-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.0
 - !ruby/object:Gem::Dependency
   name: awesome_print
   requirement: !ruby/object:Gem::Requirement
@@ -206,6 +220,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 5.2.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.9
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.9
 description: Turn the rows of your CSV into rows in your database
 email:
 - michael@crismali.com
@@ -218,6 +246,8 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - ".travis.yml"
+- API.md
+- Appraisals
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -228,6 +258,9 @@ files:
 - db/config.yml
 - db/migrate/20170511160154_create_products.rb
 - db/schema.rb
+- devmynd-logo.png
+- gemfiles/csv_import_1.1_and_0.18.gemfile
+- gemfiles/csv_import_1.1_and_0.18.gemfile.lock
 - lib/row_boat.rb
 - lib/row_boat/base.rb
 - lib/row_boat/helpers.rb
@@ -249,9 +282,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.6.11