csv_row_model 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fc063f24b8e2038004c3542d79510f7ace7c0c1e
-  data.tar.gz: 109db80efb39dbad55894fdaefe2f0e83c2920c3
+  metadata.gz: 5498738789715db182f898e6d048cf27368bc5b9
+  data.tar.gz: f70ad9d361f804afd025e3c5214dc63c2734f603
 SHA512:
-  metadata.gz: fecf7a046226eb066808d1773129f0a5487c658fcc07b9428317a1309b05304349c3ac2fc365fae8ca6753d96665b145d757814d22d9a8f829ec0a5be1f37a7c
-  data.tar.gz: 1e5b55b8784e2407d78e89a5f0b9d09fbcec78b80942e961d87c553e251e008ad17c149f9e006b85982f09d43f372cc4498bd73cc2a9f066b88080bcfd1e4452
+  metadata.gz: 60d6189fe5d90a7efb8e5630080f8b2d259fcef21beab143d54781b695c512b567c5f1bef27d11a329de9ba83145a03e5684208d7dde30c55639b09c1bbb55b6
+  data.tar.gz: 266ba89a88b2df74e1fa75f33bd9651fb27bb012d5707ac41567fbcbc3cded3cd97e4536d45170c1140ddef0ea9bd35ad2a4d1d05f15e83f22c0d4abf8f4620c

data/README.md

@@ -2,6 +2,65 @@
 
 Import and export your custom CSVs with a intuitive shared Ruby interface.
 
+First define your schema:
+
+```ruby
+class ProjectRowModel
+  include CsvRowModel::Model
+  
+  column :id
+  column :name
+end
+```
+
+To export, define your export model like [`ActiveModel::Serializer`](https://github.com/rails-api/active_model_serializers)
+and generate the file:
+
+```ruby
+class ProjectExportRowModel < ProjectRowModel
+  include CsvRowModel::Export
+
+  # this is an override with the default implementation
+  def id
+    source_model.id
+  end
+end
+
+export_file = CsvRowModel::Export::File.new(ProjectExportRowModel)
+export_file.generate { |csv| csv << project }
+export_file.file # => <Tempfile>
+export_file.to_s # => export_file.file.read
+```
+
+To import, define your import model, which works like [`ActiveRecord`](http://guides.rubyonrails.org/active_record_querying.html),
+and iterate through a file:
+
+```ruby
+class ProjectImportRowModel < ProjectRowModel
+  include CsvRowModel::Import
+
+  # this is an override with the default implementation
+  def id
+    original_attribute(:id)
+  end
+end
+
+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" }, this is `source_row` mapped to `column_names`
+row_model.attributes # => { id: "1", name: "Some Project Name" }, this is final attribute values mapped to `column_names` 
+
+row_model.id # => 1
+row_model.name # => "Some Project Name"
+
+row_model.previous # => <ProjectImportRowModel instance>
+row_model.previous.previous # => nil, save memory by avoiding a linked list
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -18,68 +77,213 @@ Or install it yourself as:
 
     $ gem install csv_row_model
 
-## RowModel
+## Export
+
+### Header Value
+To generate a header value, the following pseudocode is executed:
+```ruby
+def header(column_name)
+  # 1. Header Option
+  header = options(column_name)[:header]
 
-Define your `RowModel`.
+  # 2. format_header
+  header || format_header(column_name)
+end
+```
 
+#### Header Option
+Specify the header manually:
 ```ruby
 class ProjectRowModel
   include CsvRowModel::Model
+  column :name, header: "NAME"
+end
+```
 
-  # 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
+#### 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
 ```
 
 ## Import
 
-Automagically maps each column of a CSV row to an attribute of the `RowModel`.
+### Attribute Values
+To generate a attribute value, the following pseudocode is executed:
 
+```ruby
+def original_attribute(column_name)
+  # 1. Get the raw CSV string value for the column
+  value = mapped_row[column_name]
+
+  # 2. Clean or format each cell
+  value = self.class.format_cell(value)
+
+  if value.present?
+    # 3a. Parse the cell value (which does nothing if no parsing is specified)
+    parse(value)
+  elsif default_exists?
+    # 3b. Set the default
+    default_for_column(column_name)
+  end
+end
+
+def original_attributes; @original_attributes ||= { id: original_attribute(:id) } end
+
+def id; original_attribute[:id] end
+```
+
+#### 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.blank? ? nil : cell
+    end
+  end
+end
+```
+
+#### Type
+Automatic type parsing.
 
-  def name
-    # mapped_row is raw
-    # the calculated original_attribute[:name] is accessible as well
-    mapped_row[:name].upcase
+```ruby
+class ProjectImportRowModel
+  include CsvRowModel::Model
+  include CsvRowModel::Import
+
+  column :id, type: Integer
+  column :name, parse: ->(original_string) { parse(original_string) }
+
+  def parse(original_string)
+    "#{id} - #{original_string}"
   end
 end
 ```
 
-And to import:
+There are validators for different types: `Boolean`, `Date`, `Float`, `Integer`. See [Validations](#validations) for more.
+
+#### Default
+Sets the default value of the cell:
+```ruby
+class ProjectImportRowModel
+  include CsvRowModel::Model
+  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 are set. See [Validations](#default-changes) for more.
+
+## Advanced Import
+
+### Children
+
+Child `RowModel` relationships can also be defined:
+
+```ruby
+class UserImportRowModel
+  include CsvRowModel::Model
+  include CsvRowModel::Import
+
+  column :id, type: Integer
+  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>, ...]
+```
+
+### Layers
+For complex `RowModel`s there are different layers you can work with:
 ```ruby
 import_file = CsvRowModel::Import::File.new(file_path, ProjectImportRowModel)
 row_model = import_file.next
 
-row_model.header # => ["id", "name"]
+# the three layers:
+# 1. csv_string_model - represents the row BEFORE parsing (attributes are always strings)
+row_model.csv_string_model
 
-row_model.source_row # => ["1", "Some Project Name"]
-row_model.mapped_row # => { id: "1", name: "Some Project Name" }
+# 2. RowModel - represents the row AFTER parsing
+row_model
 
-row_model.id # => 1
-row_model.name # => "SOME PROJECT NAME"
+# 3. Presenter - an abstraction of a row
+row_model.presenter
 ```
 
-`Import::File` also provides the `RowModel` with the previous `RowModel` instance:
+#### CsvStringModel
+The `CsvStringModel` represents a row before parsing to add parsing validations.
 
 ```ruby
-row_model.previous # => <ProjectImportRowModel instance>
-row_model.previous.previous # => nil, save memory by avoiding a linked list
+class ProjectImportRowModel
+  include CsvRowModel::Model
+  include CsvRowModel::Import
+
+  # Note the type definition here for parsing
+  column :id, type: Integer
+
+  # this is applied to the parsed CSV on the model
+  validates :id, numericality: { greater_than: 0 }
+
+  csv_string_model do
+    # define your csv_string_model here
+
+    # this is applied BEFORE the parsed CSV on csv_string_model
+    validates :id, presense: true
+
+    def random_method; "Hihi" end
+  end
+end
+
+# Applied to the String
+ProjectImportRowModel.new([""])
+csv_string_model = row_model.csv_string_model
+csv_string_model.random_method => "Hihi"
+csv_string_model.valid? => false
+csv_string_model.errors.full_messages # => ["Id can't be blank'"]
+
+# Errors are propagated for simplicity
+row_model.valid? # => false
+row_model.errors.full_messages # => ["Id can't be blank'"]
+
+# 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"]
 ```
 
-## Presenter
+Note that `CsvStringModel` validations are calculated after [Format Cell](#format-cell).
+
+#### 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
 
@@ -115,7 +319,7 @@ 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"
+presenter.project.name == presenter.row_model.name # => "Some Project Name"
 ```
 
 The presenters are designed for another layer of validation---such as with the database.
@@ -127,70 +331,39 @@ Also, the `attribute` defines a dynamic `#project` method that:
 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
+the `:project` key is removed from the errors, so: `presenter.errors.keys # => [:id, :name]`
 
-Child `RowModel` relationships can also be defined:
+## Import Validations
 
-```ruby
-class UserImportRowModel
-  include CsvRowModel::Model
-  include CsvRowModel::Import
+Use [`ActiveModel::Validations`](http://api.rubyonrails.org/classes/ActiveModel/Validations.html) the `RowModel`'s [Layers](#layers).
+Please read [Layers](#layers) for more information.
 
-  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>, ...]
-```
+Included is [`ActiveWarnings`](https://github.com/s12chung/active_warnings) on `Model` and `Presenter` for warnings.
 
-## 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
-```
+### Type Format
+Notice that there are validators given for different types: `Boolean`, `Date`, `Float`, `Integer`:
 
-#### Default
-Called when `format_cell` is `value_from_format_cell.blank?`, it sets the default value of the cell:
 ```ruby
-class ProjectImportRowModel < ProjectRowModel
+class ProjectImportRowModel
+  include CsvRowModel::Model
   include CsvRowModel::Import
 
-  column :id, default: 1
-  column :name, default: -> { get_name }
+  column :id, type: Integer, validate_type: true
 
-  def get_name; "John Doe" end
+  # the :validate_type option is the same as:
+  # csv_string_model do
+  #   validates :id, integer_format: true, allow_blank: true
+  # end
 end
-row_model = ProjectImportRowModel.new(["", ""])
-row_model.id # => 1
-row_model.name # => "John Doe"
-row_model.default_changes # => { id: ["", 1], name: ["", "John Doe"] }
 
+ProjectRowModel.new(["not_a_number"])
+row_model.valid? # => false
+row_model.errors.full_messages # => ["Id is not a Integer format"]
 ```
 
-`DefaultChangeValidator` is provided to allows to add warnings when defaults or set:
+### Default Changes
+[Default Changes](#default) are tracked within [`ActiveWarnings`](https://github.com/s12chung/active_warnings).
 
 ```ruby
 class ProjectImportRowModel
@@ -201,7 +374,6 @@ class ProjectImportRowModel
 
   warnings do
     validates :id, default_change: true
-    # validates :id, presence: true, works too. See ActiveWarnings gem for more.
   end
 end
 
@@ -210,101 +382,42 @@ 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"]
+row_model.default_changes # => { id: ["", 1] }
 ```
 
-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:
+### Skip and Abort
+You can iterate through a file with the `#each` method, which calls `#next` internally.
+`#next` will always return the next `RowModel` in the file. However, you can implement skips and
+abort logic:
 
 ```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
+class ProjectImportRowModel
+  # always skip
+  def skip?
+    true # original implementation: !valid? || presenter.skip?
   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
+CsvRowModel::Import::File.new(file_path, ProjectImportRowModel).each do |project_import_model|
+  # never yields here
 end
 ```
 
-
-## Callbacks
+### Import 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
+* each_iteration - `before`, `around`, or `after` the an iteration on `#each`.
+Use this to handle exceptions. `return` and `break` may be called within the callback for
+skips and aborts.
+* next - `before`, `around`, or `after` each change in `current_row_model`
 * skip - `before`
 * abort - `before`
 
 and implement the callbacks:
 ```ruby
 class ImportFile < CsvRowModel::Import::File
-  around_yield :logger_track
+  around_each_iteration :logger_track
   before_skip :track_skip
 
   def logger_track(&block)
@@ -315,55 +428,4 @@ class ImportFile < CsvRowModel::Import::File
     ...
   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
 ```