potpourri 0.1.0 → 0.2.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    ZDZlMjkzYzYzOTdkY2E2ZDNkZTVmMDlhZDFhNGY1MDRiOTgzYzQwMA==
-  data.tar.gz: !binary |-
-    ODU5NjhiMTk1ZGNmODdiOWI2ZGU3ZjNkZjc2ZGRhYjNkZWM2Y2YzOQ==
+SHA1:
+  metadata.gz: 967a37b13ab8e26fda50157cb6fc92d1665e7dcd
+  data.tar.gz: 0bf7c3a2c6a2a1603a171b86044ec4da19b8fd06
 SHA512:
-  metadata.gz: !binary |-
-    ZWI0YjhhZjcwNjk4ZmE0YzllZGYxYjYzMzhjM2FlYmM3NGQzOWM5MjEwMWNh
-    NGU2MWJhNDhhOGJlZTlhZmZiMzdkNTg0YWMzYzNlMWVhY2JhZGRmNGFkNGM5
-    MjZmYzY0ZjA3Zjk0ZDhlYmYwMzc1OGZiZTliYTg1MzUxNTFhNjU=
-  data.tar.gz: !binary |-
-    MmRmNjhmMmE5NWI2NmVmYThhY2YwMWQ5OWE4ZmE3NDJhNjBmMzc2Mzk4Mzk3
-    NGRiYzU3Nzg2OWQ5YTk3MDYxN2RkMzhmZWE1OGIyNDMxODdkZDgxODllNGVi
-    ZTE2Mzk0NTljZWY4YTI0NzFkZTNjODdjNDcwOTc0MGU3ZjM1MjE=
+  metadata.gz: 7f1449404d6a6f59bc162151835488c06a8900fcc81d8753b46cb70719a38ba374243376e4649516684b62a253c3e24fec92abab5237d10a83a2380fe3415d44
+  data.tar.gz: 167ea8d0944bf69d4d5b4a4775639e284ebee459195df3854b6c65bde3edd2b58d2359693ac8b05f97b9398d77b34e9acee7bdf5b9e4be537dfe79ab39f10527

data/README.md

@@ -1,8 +1,5 @@
 # Potpourri
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/potpourri`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+A simple DSL to structure CSV importer and exporter for all of your models.
 
 ## Installation
 
@@ -22,7 +19,121 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+The basic implementation will work for models which accept a hash as the only argument. Start by defining a report class which inherits from `Potpourri::Report`.
+
+```ruby
+class Starship
+  attr_accessor :captain, :registration_number, :shield_frequency
+
+  def initialize(captain: nil, registration_number: nil, shield_frequency: nil)
+    captain, registation_number, shield_frequency = [captain, registation_number, shield_frequency]
+  end
+end
+
+class StarshipReport < Potpourri::Report
+  resource_class Starship
+
+  fields [
+    Potpourri::Field(:captain),
+    Potpourri::ExportableField(:registration_number),
+    Potpourri::ImportableField(:shield_frequency)
+  ]
+end
+```
+
+Thats it! Youll now be able to initialize a new Starship report which takes a path as its only argument:
+
+```ruby
+report = StarshipReport.new('starfleet/records/starships.csv')
+
+report.export(starships)
+# => a CSV object
+# Captain,Registration Number
+# Wharf, NX-74205
+
+# Given a csv at the specified path
+# Captain, Shield Frequency
+# Sisko, 3.14159
+
+report.import # => An array of Starship objects
+```
+
+### Customizing Fields
+
+Fields can be customized in a number of ways. It is easy to decide what fields will be imported and which are
+exported. Extra fields in an import will simply be ignored, so all generated exports are able to be imported.
+
+- Potpourri::Field           => These fields will be both imported and exported
+- Potpourri::ExportableField => These fields will only be exported
+- Potpourri::ImportableField => These fields will only be imported
+
+Fields will interpolate which methods are used to get and set values on a model. They will also use a
+variation of the Rails `#titleize` method to generate a header for the csv.
+
+`Potpourri::Field.new(:captain)` use `captain` as a getter and `captain=` as a setter.
+
+These assumptions can be easily overriden by passing some options into the Field when the report is defined.
+
+```ruby
+  fields [
+    Potpourri::Field(:registration_number),
+    Potpourri::Field(:captain),
+    Potpourri::ImportableField(:shield_frequency)
+  ]
+...
+
+fields [
+    Potpourri::Field(
+      :captain,
+      export_method: :command_officer,
+      import_method: :fearless_leader=,
+      header: 'Designation'
+    )
+]
+
+...
+
+```
+The importable and exportable fields also respond to the same methods, however of course they will only be either importable or exportable.
+
+### ActiveRecord Extension
+
+Importing and exporting dynamic models is only so useful. Enter the ActiveRecord extension. It provides a
+`Potpourri::ActiveRecord::Report` class. This class is a subclass of `Potpourri::Report` so it responds in
+much the same way, with some bells and whistles.
+
+```ruby
+class StarshipReport < Potpourri::ActiveRecord::Report
+  resource_class Starship
+
+  fields [
+    Potpourri::IdentifierField(:registration_number),
+    Potpourri::Field(:captain),
+    Potpourri::ImportableField(:shield_frequency)
+  ]
+
+  can_create_new_records
+  can_update_existing_records
+end
+```
+
+The big additions are:
+- The identifierField
+  - This field is required to import any record
+  - it can be any model field so long as it is unique
+  - it accepts all the same options as `Potpourri::Field`
+  - Is not importable
+
+- `can_create_new_records`
+  - lets the report create records if no match for the identifier can be found
+  - false by default
+  - accepts an argument and can be dynamically changed
+
+- `can_update_existing_fields`
+  - lets the report update existing records
+  - will not overwrite the identifier field
+  - false by default
+  - accepts an argument and can be dynamically changed
 
 ## Development
 

data/Rakefile

@@ -1 +1,7 @@
 require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+task :test => :spec

data/lib/extensions/active_record/active_record_extension.rb

@@ -0,0 +1,62 @@
+module Potpourri
+  module ActiveRecordExtension
+    def self.included(mod)
+      raise NotAReport unless mod.ancestors.include?(Report)
+      mod.extend ClassMethods
+    end
+
+    class MissingIdentifierField < StandardError; end
+    class RecordNotFound < StandardError; end
+
+    def can_update_existing_records?
+      self.class.instance_variable_get '@can_update_existing_records'
+    end
+
+    def can_create_new_records?
+      self.class.instance_variable_get '@can_create_new_records'
+    end
+
+
+    def identifier_field
+      fields.detect &:identifier?
+    end
+
+    def import
+      resources = super
+      resources.each { |resource| resource.save! }
+    end
+
+    private
+
+    def fetch_resource(row)
+      raise MissingIdentifierField unless importable?
+
+      return find_record(row) unless can_create_new_records?
+      return resource_class.new unless can_update_existing_records?
+
+      resource = resource_class.find_by(id_params row) || resource_class.new
+    end
+
+    def find_record(row)
+      resource = resource_class.find_by! id_params(row)
+    end
+
+    def importable?
+      (can_create_new_records? || can_update_existing_records?) && identifier_field
+    end
+
+    def id_params(row)
+      Hash[identifier_field.export_method, row[identifier_field.header]]
+    end
+
+    module ClassMethods
+      def create_new_records(flag = true)
+        @can_create_new_records = flag
+      end
+
+      def update_existing_records(flag = true)
+        @can_update_existing_records = flag
+      end
+    end
+  end
+end

data/lib/extensions/active_record/indentifier_field.rb

@@ -0,0 +1,13 @@
+module Potpourri
+  module ActiveRecord
+    class IdentifierField < Field
+      def importable?
+        false
+      end
+
+      def identifier?
+        true
+      end
+    end
+  end
+end

data/lib/lib/report_configs.rb

@@ -0,0 +1,25 @@
+module Potpourri
+  module ReportConfigs
+    def self.included(mod)
+      mod.extend ClassMethods
+    end
+
+    def fields
+      self.class.instance_variable_get '@fields'
+    end
+
+    def resource_class
+      self.class.instance_variable_get '@klass'
+    end
+
+    module ClassMethods
+      def fields(fields)
+        @fields = fields
+      end
+
+      def resource_class(klass)
+        @klass = klass
+      end
+    end
+  end
+end

data/lib/lib/titleize.rb

@@ -0,0 +1,7 @@
+module Potpourri
+  module Titleize
+    def titleize(str)
+      str.to_s.split(/ |\_/).map(&:capitalize).join(" ")
+    end
+  end
+end

data/lib/models/exportable_field.rb

@@ -0,0 +1,7 @@
+module Potpourri
+  class ExportableField < Field
+    def importable?
+      false
+    end
+  end
+end

data/lib/models/field.rb

@@ -0,0 +1,35 @@
+module Potpourri
+  class Field
+    include Potpourri::Titleize
+
+    class Unimportable < StandardError; end
+    class Unexportable < StandardError; end
+
+    attr_reader :name, :header, :export_method, :import_method
+
+    def initialize(name, options = {})
+      @export_method = options[:export_method] || name.to_sym
+      @import_method = options[:import_method] || "#{ name }=".to_sym
+      @header = options[:header] || titleize(name)
+      @name = name.to_sym
+    end
+
+    def importable?
+      true
+    end
+
+    def exportable?
+      true
+    end
+
+    def import(resource, value)
+      raise Unimportable unless importable?
+      resource.public_send import_method, value
+    end
+
+    def export(resource)
+      raise Unexportable unless exportable?
+      resource.public_send export_method
+    end
+  end
+end

data/lib/models/importable_field.rb

@@ -0,0 +1,7 @@
+module Potpourri
+  class ImportableField < Field
+    def exportable?
+      false
+    end
+  end
+end

data/lib/models/report.rb

@@ -0,0 +1,55 @@
+require 'csv'
+
+module Potpourri
+  class Report
+    include ReportConfigs
+
+    attr_reader :path
+
+    def initialize(path)
+      @path = path
+    end
+
+    def headers
+      fields.map &:header
+    end
+
+    def import
+      CSV.read(path, headers: true, converters: :numeric).map do |row|
+        resource = fetch_resource(row)
+
+        importable_fields.each do |field|
+          field.import resource, row[field.header]
+        end
+
+        resource
+      end
+    end
+
+    def export(collection)
+      CSV.open(path, 'w') do |csv|
+        csv << headers
+
+        collection.each do |item|
+          csv << exportable_fields.map { |field| field.export item }
+        end
+
+        csv
+      end
+    end
+
+    private
+
+    def importable_fields
+      fields.select &:importable?
+    end
+
+    def exportable_fields
+      fields.select &:exportable?
+    end
+
+    def fetch_resource(row)
+      resource_class.new
+    end
+  end
+end

data/lib/potpourri.rb

@@ -1,5 +1,9 @@
 require "potpourri/version"
 
+ROOT = File.expand_path '../', __FILE__
+
 module Potpourri
-  # Your code goes here...
+  Dir.glob(File.join ROOT, 'lib/**/*.rb').each { |f| require f }
+  Dir.glob(File.join ROOT, 'models/**/*.rb').each { |f| require f }
+  Dir.glob(File.join ROOT, 'extensions/**/*.rb').each { |f| require f }
 end

data/lib/potpourri/version.rb

@@ -1,3 +1,3 @@
 module Potpourri
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/potpourri.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["brendan.g.deere@gmail.com"]
 
   spec.summary       = %q{Because you're tired of writting csv importer and exporters.}
-  spec.description   = %q{A simple DSL to structure CSV importer and exporters for all of your models.}
+  spec.description   = %q{A simple DSL to structure CSV importer and exporter for all of your models.}
   spec.homepage      = "https://github.com/brendandeere/potpourri"
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
@@ -21,6 +21,12 @@ Gem::Specification.new do |spec|
   if spec.respond_to?(:metadata)
   end
 
+  spec.add_development_dependency "activerecord"
+  spec.add_development_dependency "sqlite3"
   spec.add_development_dependency "bundler", "~> 1.9"
   spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "database_cleaner"
 end

metadata

@@ -1,59 +1,150 @@
 --- !ruby/object:Gem::Specification
 name: potpourri
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - brendandeere
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-11-11 00:00:00.000000000 Z
+date: 2015-11-25 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.9'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
-description: A simple DSL to structure CSV importer and exporters for all of your
-  models.
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A simple DSL to structure CSV importer and exporter for all of your models.
 email:
 - brendan.g.deere@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rspec
-- .travis.yml
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
 - Gemfile
 - README.md
 - Rakefile
 - bin/console
 - bin/setup
+- lib/extensions/active_record/active_record_extension.rb
+- lib/extensions/active_record/indentifier_field.rb
+- lib/lib/report_configs.rb
+- lib/lib/titleize.rb
+- lib/models/exportable_field.rb
+- lib/models/field.rb
+- lib/models/importable_field.rb
+- lib/models/report.rb
 - lib/potpourri.rb
 - lib/potpourri/version.rb
 - potpourri.gemspec
@@ -66,17 +157,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.2.3
 signing_key: 
 specification_version: 4
 summary: Because you're tired of writting csv importer and exporters.