csv_row_model 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fc063f24b8e2038004c3542d79510f7ace7c0c1e
+  data.tar.gz: 109db80efb39dbad55894fdaefe2f0e83c2920c3
+SHA512:
+  metadata.gz: fecf7a046226eb066808d1773129f0a5487c658fcc07b9428317a1309b05304349c3ac2fc365fae8ca6753d96665b145d757814d22d9a8f829ec0a5be1f37a7c
+  data.tar.gz: 1e5b55b8784e2407d78e89a5f0b9d09fbcec78b80942e961d87c553e251e008ad17c149f9e006b85982f09d43f372cc4498bd73cc2a9f066b88080bcfd1e4452

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.idea/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.ruby-gemset

@@ -0,0 +1 @@
+csv_row_model

data/.ruby-version

@@ -0,0 +1 @@
+2.2.2

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+script: bundle exec rspec
+rvm:
+  - 2.1.0
+  - ruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+env:
+  - CODECLIMATE_REPO_TOKEN=6b3e0fb12a56a7aba4b43ca8662d8a5383c831d98b92fc818ea731f4e70e73cd bundle exec rake

data/.yardopts

@@ -0,0 +1,10 @@
+--no-cache
+--verbose
+--markup markdown
+--markup-provider redcarpet
+
+--plugin activesupport-concern
+--plugin yard-delegate
+
+--protected
+--private

data/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+# Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/csv_row_model/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Gemfile

@@ -0,0 +1,20 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in csv_row_model.gemspec
+gemspec
+
+gem "bundler", "> 1.3"
+gem "rake", "~> 10.0"
+
+group :test do
+  gem "rspec"
+  gem "codeclimate-test-reporter"
+  gem 'pry-byebug'
+end
+
+group :development do
+  gem "yard"
+  gem "redcarpet"
+  gem "yard-activesupport-concern"
+  gem "yard-delegate"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Steve Chung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,369 @@
+# CsvRowModel [![Build Status](https://travis-ci.org/FinalCAD/csv_row_model.svg?branch=master)](https://travis-ci.org/FinalCAD/csv_row_model) [![Code Climate](https://codeclimate.com/github/FinalCAD/csv_row_model/badges/gpa.svg)](https://codeclimate.com/github/FinalCAD/csv_row_model) [![Test Coverage](https://codeclimate.com/github/FinalCAD/csv_row_model/badges/coverage.svg)](https://codeclimate.com/github/FinalCAD/csv_row_model/coverage)
+
+Import and export your custom CSVs with a intuitive shared Ruby interface.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'csv_row_model'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install csv_row_model
+
+## RowModel
+
+Define your `RowModel`.
+
+```ruby
+class ProjectRowModel
+  include CsvRowModel::Model
+
+  # column indices are tracked with each call
+  column :id
+  column :name
+  column :owner_id, header: 'Project Manager' # optional header String, that allows to modify the header of the colmnun
+end
+```
+
+## Import
+
+Automagically maps each column of a CSV row to an attribute of the `RowModel`.
+
+```ruby
+class ProjectImportRowModel < ProjectRowModel
+  include CsvRowModel::Import
+
+  def name
+    # mapped_row is raw
+    # the calculated original_attribute[:name] is accessible as well
+    mapped_row[:name].upcase
+  end
+end
+```
+
+And to import:
+
+```ruby
+import_file = CsvRowModel::Import::File.new(file_path, ProjectImportRowModel)
+row_model = import_file.next
+
+row_model.header # => ["id", "name"]
+
+row_model.source_row # => ["1", "Some Project Name"]
+row_model.mapped_row # => { id: "1", name: "Some Project Name" }
+
+row_model.id # => 1
+row_model.name # => "SOME PROJECT NAME"
+```
+
+`Import::File` also provides the `RowModel` with the previous `RowModel` instance:
+
+```ruby
+row_model.previous # => <ProjectImportRowModel instance>
+row_model.previous.previous # => nil, save memory by avoiding a linked list
+```
+
+## Presenter
+For complex rows, you can wrap your `RowModel` with a presenter:
+
+```ruby
+class ProjectImportRowModel < ProjectRowModel
+  include CsvRowModel::Import
+
+  # same as above
+
+  presenter do
+    # define your presenter here
+
+    # this is shorthand for the psuedo_code:
+    # def project
+    #  return if row_model.id.invalid? || row_model.name.invalid?
+    #
+    #  # turn off memoziation with `memoize: false` option
+    #  @project ||= __the_code_inside_the_block__
+    # end
+    #
+    # and the psuedo_code:
+    # def valid?
+    #   super # calls ActiveModel::Errors code
+    #   errors.delete(:project) if row_model.id.invalid? || row_model.name.invalid?
+    #   errors.empty?
+    # end
+    attribute :project, dependencies: [:id, :name] do
+      project = Project.where(id: row_model.id).first
+
+      # project not found, invalid.
+      return unless project
+
+      project.name = row_model.name
+      project
+    end
+  end
+end
+
+# Importing is the same
+import_file = CsvRowModel::Import::File.new(file_path, ProjectImportRowModel)
+row_model = import_file.next
+presenter = row_model.presenter
+
+presenter.row_model # gets the row model underneath
+import_mapper.project.name == presenter.row_model.name # => "SOME PROJECT NAME"
+```
+
+The presenters are designed for another layer of validation---such as with the database.
+
+Also, the `attribute` defines a dynamic `#project` method that:
+
+1. Memoizes by default, turn off with `memoize: false` option
+2. All errors of `row_model` are propagated to the presenter when calling `presenter.valid?`
+3. Handles dependencies. When any of the dependencies are `invalid?`:
+  - The attribute block is not called and the attribute returns `nil`.
+  - `presenter.errors` for dependencies are cleaned. For the example above, if `row_model.id/name` are `invalid?`, then
+the `:project` key is removed from the errors, so: `import_mapper.errors.keys # => [:id, :name]`
+
+## Children
+
+Child `RowModel` relationships can also be defined:
+
+```ruby
+class UserImportRowModel
+  include CsvRowModel::Model
+  include CsvRowModel::Import
+
+  column :id
+  column :name
+  column :email
+
+  # uses ProjectImportRowModel#valid? to detect the child row
+  has_many :projects, ProjectImportRowModel
+end
+
+import_file = CsvRowModel::Import::File.new(file_path, UserImportRowModel)
+row_model = import_file.next
+row_model.projects # => [<ProjectImportRowModel>, ...]
+```
+
+## Column Options
+### Default Attributes
+For `Import`, `default_attributes` are calculated as thus:
+- `format_cell`
+- if `value_from_format_cell.blank?`, `default_lambda.call` or nil
+- otherwise, `parse_lambda.call`
+
+#### Format Cell
+Override the `format_cell` method to clean/format every cell:
+```ruby
+class ProjectImportRowModel < ProjectRowModel
+  include CsvRowModel::Import
+  class << self
+    def format_cell(cell, column_name, column_index)
+      cell = cell.strip
+      cell.to_i.to_s == cell ? cell.to_i : cell
+    end
+  end
+end
+```
+
+#### Default
+Called when `format_cell` is `value_from_format_cell.blank?`, it sets the default value of the cell:
+```ruby
+class ProjectImportRowModel < ProjectRowModel
+  include CsvRowModel::Import
+
+  column :id, default: 1
+  column :name, default: -> { get_name }
+
+  def get_name; "John Doe" end
+end
+row_model = ProjectImportRowModel.new(["", ""])
+row_model.id # => 1
+row_model.name # => "John Doe"
+row_model.default_changes # => { id: ["", 1], name: ["", "John Doe"] }
+
+```
+
+`DefaultChangeValidator` is provided to allows to add warnings when defaults or set:
+
+```ruby
+class ProjectImportRowModel
+  include CsvRowModel::Model
+  include CsvRowModel::Input
+
+  column :id, default: 1
+
+  warnings do
+    validates :id, default_change: true
+    # validates :id, presence: true, works too. See ActiveWarnings gem for more.
+  end
+end
+
+row_model = ProjectImportRowModel.new([""])
+
+row_model.unsafe? # => true
+row_model.has_warnings? # => true, same as `#unsafe?`
+row_model.warnings.full_messages # => ["Id changed by default"]
+```
+
+See [Validations](#validations) for more.
+
+#### Type
+Automatic type parsing.
+
+```ruby
+class ProjectImportRowModel < ProjectRowModel
+  include CsvRowModel::Import
+
+  column :id, type: Integer
+  column :name, parse: ->(original_string) { parse(original_string) }
+
+  def parse(original_string)
+    "#{id} - #{original_string}"
+  end
+end
+```
+
+## Validations
+
+Use [`ActiveModel::Validations`](http://api.rubyonrails.org/classes/ActiveModel/Validations.html)
+on your `RowModel` or `Mapper`.
+
+Included is [`ActiveWarnings`](https://github.com/s12chung/active_warnings) on `Model` and `Mapper` for warnings
+(such as setting defaults), but not errors (which by default results in a skip).
+
+`RowModel` has two validation layers on the `csv_string_model` (a model of `#mapped_row` with `::format_cell` applied) and itself:
+
+```ruby
+class ProjectRowModel
+  include CsvRowModel::Model
+  include CsvRowModel::Import
+
+  column :id, type: Integer
+
+  # this is applied to the parsed CSV on the model
+  validates :id, numericality: { greater_than: 0 }
+
+  csv_string_model do
+    # this is applied before the parsed CSV on csv_string_model
+    validates :id, integer_format: true, allow_blank: true
+  end
+end
+
+# Applied to the String
+ProjectRowModel.new(["not_a_number"])
+row_model.valid? # => false
+row_model.errors.full_messages # => ["Id is not a Integer format"]
+
+# Applied to the parsed Integer
+row_model = ProjectRowModel.new(["-1"])
+row_model.valid? # => false
+row_model.errors.full_messages # => ["Id must be greater than 0"]
+```
+
+Notice that there are validators given for different types: `Boolean`, `Date`, `Float`, `Integer`:
+
+```ruby
+class ProjectRowModel
+  include CsvRowModel::Model
+
+  # the :validate_type option does the commented code below.
+  column :id, type: Integer, validate_type: true
+
+  # csv_string_model do
+  #   validates :id, integer_format: true, allow_blank: true
+  # end
+end
+```
+
+
+## Callbacks
+`CsvRowModel::Import::File` can be subclassed to access
+[`ActiveModel::Callbacks`](http://api.rubyonrails.org/classes/ActiveModel/Callbacks.html).
+
+You can iterate through a file with the `#each` method, which calls `#next` internally:
+
+```ruby
+CsvRowModel::Import::File.new(file_path, ProjectImportRowModel).each do |project_import_model|
+end
+```
+
+Within `#each`, **Skips** and **Aborts** will be done via the `skip?` or `abort?` method on the row model,
+allowing the following callbacks:
+
+* yield - `before`, `around`, or `after` the iteration yield
+* skip - `before`
+* abort - `before`
+
+and implement the callbacks:
+```ruby
+class ImportFile < CsvRowModel::Import::File
+  around_yield :logger_track
+  before_skip :track_skip
+
+  def logger_track(&block)
+    ...
+  end
+
+  def track_skip
+    ...
+  end
+end
+```
+
+### Export RowModel
+
+Maps each attribute of the `RowModel` to a column of a CSV row.
+
+```ruby
+class ProjectExportRowModel < ProjectRowModel
+  include CsvRowModel::Export
+
+  # Optionally it's possible to override the attribute method, by default it
+  # does source_model.public_send(attribute)
+  def name
+    "#{source_model.id} - #{source_model.name}"
+  end
+end
+```
+
+### Export SingleModel
+
+Maps each attribute of the `RowModel` to a row on the CSV.
+
+```ruby
+class ProjectExportRowModel < ProjectRowModel
+  include CsvRowModel::Export
+  include CsvRowModel::Export::SingleModel
+
+
+end
+```
+
+And to export:
+
+```ruby
+export_csv = CsvRowModel::Export::Csv.new(ProjectExportRowModel)
+csv_string = export_csv.generate do |csv|
+               csv.append_model(project) #optional you can pass a context
+             end
+```
+
+#### Format Header
+Override the `format_header` method to format column header names:
+```ruby
+class ProjectExportRowModel < ProjectRowModel
+  include CsvRowModel::Export
+  class << self
+    def format_header(column_name)
+      column_name.to_s.titleize
+    end
+  end
+end
+```