csv_row_model 0.4.1 → 1.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 44a0bf8c6a12a2a9a8c3cb74cf3563928313ac96
-  data.tar.gz: a75edbc43ee598166facf68baf98555355e15660
+  metadata.gz: 620b2a84648e1723419994992518ecd9e77609d3
+  data.tar.gz: 5b331bc69fb075b9ca84bf53db592c0e6db15dde
 SHA512:
-  metadata.gz: 9fa219f5da727166844f7d75519670fe0df6d98926caf0d72abafa8a84961af0513a87b69be00219671d5af2161edec57740e0128160d26952e7ef72db9cf69d
-  data.tar.gz: 26a27334de6c098629a3d446eda5aece191bcd9080d732476e65e1534e79b7fb3e8501c22ae5f72ec3cfceef62e9600610b5fabec8a6405c4e43bb190fed7c17
+  metadata.gz: 5e10d1f2a7fd7115e632fadee715a852d9aa05bf5f1d69d04c79fc1503d598118bb75dfbb1707af4cf5afa6692c2338bd1d1e93125b39d1175445f34197dacad
+  data.tar.gz: 78994103e5eab1c176f5a2e9c7306073071a7da9adfc94344393e16cdd32fff6023c3f1e8e018b2f6ed8178f2720bbfc7149abba232a3b4414393ae6bc6bb8cf

data/README.md

@@ -29,7 +29,7 @@ class ProjectExportRowModel < ProjectRowModel
 end
 
 export_file = CsvRowModel::Export::File.new(ProjectExportRowModel)
-export_file.generate { |csv| csv << project }
+export_file.generate { |csv| csv << project } # `project` is the `source_model` in `ProjectExportRowModel`
 export_file.file # => <Tempfile>
 export_file.to_s # => export_file.file.read
 ```
@@ -86,10 +86,10 @@ To generate a header value, the following pseudocode is executed:
 ```ruby
 def header(column_name)
   # 1. Header Option
-  header = options(column_name)[:header]
+  header = options_for(column_name)[:header]
 
   # 2. format_header
-  header || format_header(column_name)
+  header || format_header(column_name, column_index, context)
 end
 ```
 
@@ -108,7 +108,7 @@ Override the `format_header` method to format column header names:
 class ProjectExportRowModel < ProjectRowModel
   include CsvRowModel::Export
   class << self
-    def format_header(column_name)
+    def format_header(column_name, column_index, context)
       column_name.to_s.titleize
     end
   end
@@ -137,9 +137,8 @@ def original_attribute(column_name)
   end
 end
 
-def original_attributes; @original_attributes ||= { id: original_attribute(:id) } end
-
-def id; original_attribute[:id] end
+def original_attributes; { id: original_attribute(:id) } end
+def id; original_attribute(:id) end
 ```
 
 #### Format Cell
@@ -148,7 +147,7 @@ Override the `format_cell` method to clean/format every cell:
 class ProjectImportRowModel < ProjectRowModel
   include CsvRowModel::Import
   class << self
-    def format_cell(cell, column_name, column_index, context={})
+    def format_cell(cell, column_name, column_index, context)
       cell = cell.strip
       cell.blank? ? nil : cell
     end
@@ -173,7 +172,7 @@ class ProjectImportRowModel
 end
 ```
 
-There are validators for different types: `Boolean`, `Date`, `DateTime`, `Float`, `Integer`. See [Validations](#validations) for more.
+There are validators for different types: `Boolean`, `Date`, `DateTime`, `Float`, `Integer`. See [Type Format](#type-format) for more.
 
 #### Default
 Sets the default value of the cell:
@@ -193,157 +192,37 @@ 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.
+`DefaultChangeValidator` is provided to allows to add warnings when defaults are set. See [Default Changes](#default-changes) for more.
 
-## Advanced Import
+### Validations
 
-### Children
+[`ActiveModel::Validations`](http://api.rubyonrails.org/classes/ActiveModel/Validations.html) and [`ActiveWarnings`](https://github.com/s12chung/active_warnings)
+are included for errors and warnings.
 
-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
-
-# the three layers:
-# 1. csv_string_model - represents the row BEFORE parsing (attributes are always strings)
-row_model.csv_string_model
-
-# 2. RowModel - represents the row AFTER parsing
-row_model
-
-# 3. Presenter - an abstraction of a row
-row_model.presenter
-```
-
-#### CsvStringModel
-The `CsvStringModel` represents a row before parsing to add parsing validations.
+There are layers to validations.
 
 ```ruby
 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
+  
+  # Errors - by default, an Error will make the row skip
+  validates :id, numericality: { greater_than: 0 } # ActiveModel::Validations
+  
+  # Warnings - a message you want the user to see, but will not make the row skip
+  warnings do # ActiveWarnings, see: https://github.com/s12chung/active_warnings
+    validates :some_custom_string, presence: true
   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"]
-```
-
-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
-
-  presenter do
-    # define your presenter here
-
-    # this is shorthand for the psuedo_code:
-    # def project
-    #  return if row_model.id.blank? || row_model.name.blank?
-    #
-    #  # 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
+  
+  # This is for validation of the strings before parsing. See: https://github.com/FinalCAD/csv_row_model#csvstringmodel
+  csv_string_model do
+    validates :id, presence: true
+    # can do warnings too
   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
-presenter.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 `blank?`, the attribute block is not called and the attribute returns `nil`.
-  - When any of the dependencies are `invalid?`, `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: `presenter.errors.keys # => [:id, :name]`
-
-## Import Validations
-
-Use [`ActiveModel::Validations`](http://api.rubyonrails.org/classes/ActiveModel/Validations.html) the `RowModel`'s [Layers](#layers).
-Please read [Layers](#layers) for more information.
-
-Included is [`ActiveWarnings`](https://github.com/s12chung/active_warnings) on `Model` and `Presenter` for warnings.
-
-
-### Type Format
+#### Type Format
 Notice that there are validators given for different types: `Boolean`, `Date`, `DateTime`, `Float`, `Integer`:
 
 ```ruby
@@ -364,8 +243,8 @@ row_model.valid? # => false
 row_model.errors.full_messages # => ["Id is not a Integer format"]
 ```
 
-### Default Changes
-[Default Changes](#default) are tracked within [`ActiveWarnings`](https://github.com/s12chung/active_warnings).
+#### Default Changes
+A custom validator for [Default Changes](#default).
 
 ```ruby
 class ProjectImportRowModel
@@ -373,17 +252,13 @@ class ProjectImportRowModel
   include CsvRowModel::Input
 
   column :id, default: 1
-
-  warnings do
-    validates :id, default_change: true
-  end
+  validates :id, default_change: true
 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"]
+row_model.valid? # => false
+row_model.errors.full_messages # => ["Id changed by default"]
 row_model.default_changes # => { id: ["", 1] }
 ```
 
@@ -396,13 +271,13 @@ abort logic:
 class ProjectImportRowModel
   # always skip
   def skip?
-    true # original implementation: !valid? || presenter.skip?
+    true # original implementation: !valid?
   end
 end
 
-CsvRowModel::Import::File.new(file_path, ProjectImportRowModel).each do |project_import_model|
-  # never yields here
-end
+import_file = CsvRowModel::Import::File.new(file_path, ProjectImportRowModel)
+import_file.each { |project_import_model| puts "does not yield here" }
+import_file.next # does not skip or abort
 ```
 
 ### Import Callbacks
@@ -432,6 +307,128 @@ class ImportFile < CsvRowModel::Import::File
 end
 ```
 
+## Advanced Import
+
+### CsvStringModel
+The `CsvStringModel` represents a row BEFORE parsing to add validations.
+
+```ruby
+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, presence: 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"]
+```
+
+Note that `CsvStringModel` validations are calculated after [Format Cell](#format-cell).
+
+### Represents
+A CSV is often a representation of database model(s), much like how JSON parameters represents models in requests.
+However, CSVs schemas are **flat** and **static** and JSON parameters are **tree structured** and **dynamic** (but often static).
+Because CSVs are flat, `RowModel`s are also flat, but they can represent various models. The `represents` interface attempts to simplify this for importing.
+
+```ruby
+class ProjectImportRowModel < ProjectRowModel
+  include CsvRowModel::Import
+
+  # this is shorthand for the psuedo_code:
+  # def project
+  #  return if id.blank? || name.blank?
+  #
+  #  # 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 id.invalid? || name.invalid?
+  #   errors.empty?
+  # end
+  represents_one :project, dependencies: [:id, :name] do
+     project = Project.where(id: id).first
+                           
+     # project not found, invalid.
+     return unless project
+
+     project.name = name
+     project
+   end
+   
+   # same as above, but: returns [] if name.blank?
+   represents_many :projects, dependencies: [:name] do
+     Project.where(name: name)
+   end
+end
+
+# Importing is the same
+import_file = CsvRowModel::Import::File.new(file_path, ProjectImportRowModel)
+row_model = import_file.next
+row_model.project.name # => "Some Project Name"
+```
+
+The `represents_one` method defines a dynamic `#project` method that:
+
+1. Memoizes by default, turn off with `memoize: false` option
+2. Handles dependencies:
+  - When any of the dependencies are `blank?`, the attribute block is not called and the representation returns `nil`.
+  - When any of the dependencies are `invalid?`, `row_model.errors` for dependencies are cleaned. For the example above, if `id/name` are `invalid?`, then
+the `:project` key is removed from the errors, so: `row_model.errors.keys # => [:id, :name]` (applies to warnings as well)
+
+`represents_many` is also available, except it returns `[]` when any of the dependencies are `blank?`.
+
+### 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>, ...]
+```
+
 ## Dynamic columns
 Dynamic columns are columns that can expand to many columns. Currently, we can only one dynamic column after all other standard columns.
 The following:
@@ -456,6 +453,9 @@ represents this table:
 | Mike       | Jackson    |   Yes  |   Yes  |
 
 
+The `format_dynamic_column_header(header_model, column_name, dynamic_column_index, index_of_column, context)` can
+be used to defined like `format_header`. Defined in both import and export due to headers being used for both.
+
 ### Export
 Dynamic column attributes are arrays, but each item in the array is defined via singular attribute method like
 normal columns:
@@ -494,7 +494,7 @@ class DynamicColumnImportModel < DynamicColumnModel
     # Clean/format every dynamic_column attribute array
     #
     # this is an override with the default implementation
-    def format_dynamic_column_cells(cells, column_name)
+    def format_dynamic_column_cells(cells, column_name, column_index, context)
       cells
     end
   end
@@ -518,7 +518,7 @@ class FileRowModel
   row :string1
   row :string2, header: 'String 2'
 
-  def self.format_header(column_name, context={})
+  def self.format_header(column_name, column_index, context)
     ":: - #{column_name} - ::"
   end
 end

data/csv_row_model.gemspec

@@ -19,5 +19,6 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "activemodel", "~> 4.2"
-  spec.add_dependency "active_warnings", ">= 0.1.2"
+  spec.add_dependency "active_warnings", "~> 0.1.2"
+  spec.add_dependency "inherited_class_var", ">= 0.2.2"
 end

data/lib/csv_row_model/concerns/{invalid_options.rb → check_options.rb}

@@ -1,15 +1,13 @@
 module CsvRowModel
   module Concerns
-    module InvalidOptions
+    module CheckOptions
       extend ActiveSupport::Concern
 
       class_methods do
-        protected
-        def check_and_merge_options(options, default_options)
-          invalid_options = options.keys - default_options.keys
+        def check_options(options)
+          invalid_options = options.keys - self::VALID_OPTIONS
           raise ArgumentError.new("Invalid option(s): #{invalid_options}") if invalid_options.present?
-
-          options.reverse_merge(default_options)
+          true
         end
       end
     end

data/lib/csv_row_model/export/attributes.rb

@@ -1,3 +1,5 @@
+require 'csv_row_model/export/cell'
+
 module CsvRowModel
   module Export
     module Attributes
@@ -7,35 +9,24 @@ module CsvRowModel
         self.column_names.each { |*args| define_attribute_method(*args) }
       end
 
-      # @return [Hash] a map of `column_name => self.class.format_cell(public_send(column_name))`
+      def cell_objects
+        @cell_objects ||= array_to_block_hash(self.class.column_names) { |column_name| Cell.new(column_name, self) }
+      end
+
+      # @return [Hash] a map of `column_name => formatted_attributes`
       def formatted_attributes
-        formatted_attributes_from_column_names self.class.column_names
+        array_to_block_hash(self.class.column_names) { |column_name| formatted_attribute(column_name) }
       end
 
       def formatted_attribute(column_name)
-        return public_send(column_name) if self.class.is_dynamic_column?(column_name)
-
-        self.class.format_cell(
-          public_send(column_name),
-          column_name,
-          self.class.index(column_name),
-          context
-        )
+        cell_objects[column_name].try(:value)
       end
 
-      protected
-      def formatted_attributes_from_column_names(column_names)
-        array_to_block_hash(column_names) { |column_name| formatted_attribute(column_name) }
+      def source_attribute(column_name)
+        cell_objects[column_name].try(:source_value)
       end
 
       class_methods do
-        # Safe to override. Method applied to each cell by default
-        #
-        # @param cell [Object] the cell's value
-        def format_cell(cell, column_name, column_index, context={})
-          cell
-        end
-
         protected
         # See {Model#column}
         def column(column_name, options={})

data/lib/csv_row_model/export/base.rb

@@ -4,15 +4,15 @@ module CsvRowModel
       extend ActiveSupport::Concern
 
       included do
-        attr_reader :source_model, :context
+        attr_reader :source_model
         validates :source_model, presence: true
       end
 
       # @param [Model] source_model object to export to CSV
       # @param [Hash]  context
-      def initialize(source_model, context={})
+      def initialize(source_model=nil, context={})
         @source_model = source_model
-        @context      = OpenStruct.new(context)
+        super(context: context)
       end
 
       def to_rows

data/lib/csv_row_model/export/cell.rb

@@ -0,0 +1,24 @@
+module CsvRowModel
+  module Export
+    class Cell
+      attr_reader :column_name, :row_model
+
+      def initialize(column_name, row_model)
+        @column_name = column_name
+        @row_model = row_model
+      end
+
+      def value
+        formatted_value
+      end
+
+      def formatted_value
+        @formatted_value ||= row_model.class.format_cell(source_value, column_name, row_model.class.index(column_name), row_model.context)
+      end
+
+      def source_value
+        row_model.public_send(column_name)
+      end
+    end
+  end
+end

data/lib/csv_row_model/export/dynamic_column_cell.rb

@@ -0,0 +1,29 @@
+module CsvRowModel
+  module Export
+    class DynamicColumnCell < CsvRowModel::Model::DynamicColumnCell
+      def unformatted_value
+        formatted_cells
+      end
+
+      def formatted_cells
+        cells.map.with_index.map do |cell, index|
+          row_model.class.format_cell(cell, column_name, dynamic_column_index + index, row_model.context)
+        end
+      end
+
+      def cells
+        header_models.map { |header_model| call_process_cell(header_model) }
+      end
+
+      def header_models
+        row_model.context.public_send(column_name)
+      end
+
+      class << self
+        def define_process_cell(row_model_class, column_name)
+          super { |header_model| header_model }
+        end
+      end
+    end
+  end
+end

data/lib/csv_row_model/export/dynamic_columns.rb

@@ -1,3 +1,5 @@
+require 'csv_row_model/export/dynamic_column_cell'
+
 module CsvRowModel
   module Export
     module DynamicColumns
@@ -7,6 +9,12 @@ module CsvRowModel
         self.dynamic_column_names.each { |*args| define_dynamic_attribute_method(*args) }
       end
 
+      def cell_objects
+        @dynamic_column_cell_objects ||= super.merge(array_to_block_hash(self.class.dynamic_column_names) do |column_name|
+          DynamicColumnCell.new(column_name, self)
+        end)
+      end
+
       # @return [Array] an array of public_send(column_name) of the CSV model
       def to_row
         super.flatten
@@ -14,7 +22,7 @@ module CsvRowModel
 
       # See Model::Export#formatted_attributes
       def formatted_attributes
-        super.merge(formatted_attributes_from_column_names(self.class.dynamic_column_names))
+        super.merge!(array_to_block_hash(self.class.dynamic_column_names) { |column_name| formatted_attribute(column_name) })
       end
 
       class_methods do
@@ -29,18 +37,8 @@ module CsvRowModel
         # Define default attribute method for a dynamic_column
         # @param column_name [Symbol] the cell's column_name
         def define_dynamic_attribute_method(column_name)
-          define_method(column_name) do
-            context.public_send(column_name).map do |header_model|
-              self.class.format_cell(
-                public_send(self.class.singular_dynamic_attribute_method_name(column_name), header_model),
-                column_name,
-                self.class.dynamic_index(column_name),
-                context
-              )
-            end
-          end
-
-          define_method(singular_dynamic_attribute_method_name(column_name)) { |header_model| header_model }
+          define_method(column_name) { formatted_attribute(column_name) }
+          DynamicColumnCell.define_process_cell(self, column_name)
         end
       end
     end