flattery 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rvmrc

@@ -0,0 +1 @@
+rvm use 1.9.3@flattery --create

data/.travis.yml

@@ -0,0 +1,6 @@
+# These are specific configuration settings required for travis-ci
+# see http://travis-ci.org/evendis/flattery
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in flattery.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,10 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/flattery/(.+)\.rb$})   { |m| "spec/unit/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+end
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Paul Gallagher
+
+MIT License
+
+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,70 @@
+# Flattery [![Build Status](https://secure.travis-ci.org/evendis/flattery.png?branch=master)](http://travis-ci.org/evendis/flattery)
+
+Sometimes you want to do the non-DRY thing and repeat yourself, by caching values from associated records in a master model.
+The two main reasons you might want to do this are probably:
+* for performance - to avoid joins in search queries and display
+* to save values from association records that are subject to deletion yet still have them available when looking at the master record - if you are using the [https://rubygems.org/gems/paranoid](paranoid) gem for example.
+
+Hence flattery - a gem that provides a simple declarative method for caching and maintaining such values.
+
+Flattery is primarily intended for use with relational Active::Record storage, and is only tested with sqlite and PostgreSQL.
+If you are using NoSQL, you probably wouldn't design your schema in a way for which flattery adds any value - but if you find a situation where this makes sense, then feel free to fork and add the support .. or lobby for it's inclusion!
+
+## Requirements
+
+* Ruby 1.9 or 2
+* Rails 3.x/4.x
+* ActiveRecord (only splite and PostgreQL tested. Others _should_ work; raise an issue if you find problems)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'flattery'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install flattery
+
+## Usage
+
+### How to define a model that has cached values from a :belongs_to association
+
+Given a model with a :category assoociation, and you want to cache instance.category.name as instance.category_name.
+
+First, add a migration to add :category_name column to your table with the same type as category.name.
+Then just include Flattery::ValueCache in your model and define flatten_values like this:
+
+    class Note < ActiveRecord::Base
+      belongs_to :category
+
+      include Flattery::ValueCache
+      flatten_value :category => :name
+
+    end
+
+### How to cache the value in a specific column name
+
+In the usual case, the cache column name is inferred from the association (e.g. category_name in the example above).
+If you want to store in another column name, use the :as option on the +flatten_value+ call:
+
+    class Note < ActiveRecord::Base
+      belongs_to :category
+
+      include Flattery::ValueCache
+      flatten_value :category => :name, :as => 'cat_name'
+
+    end
+
+
+## Contributing
+
+1. Fork it
+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 new Pull Request

data/Rakefile

@@ -0,0 +1,24 @@
+require 'bundler/gem_tasks'
+require 'rspec'
+require 'rspec/core/rake_task'
+
+desc "Run all test examples"
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = ["-c", "-f progress"]
+  t.pattern = 'spec/**/*_spec.rb'
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+RDoc::Task.new do |rdoc|
+  rdoc.main = "README.md"
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "Flattery"
+  rdoc.rdoc_files.include('README*', 'lib/**/*.rb')
+end
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -I lib -r flattery.rb"
+end

data/flattery.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'flattery/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "flattery"
+  spec.version       = Flattery::VERSION
+  spec.authors       = ["Paul Gallagher"]
+  spec.email         = ["paul@evendis.com"]
+  spec.description   = %q{Flatten/normalise values from ActiveModel associations}
+  spec.summary       = %q{Flatter your nicely normalised AR models}
+  spec.homepage      = "https://github.com/evendis/flattery"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "activesupport", ">= 3.0.3"
+  spec.add_runtime_dependency "activerecord", ">= 3.0.3"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rdoc"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "guard-rspec"
+  spec.add_development_dependency "rb-fsevent"
+  spec.add_development_dependency "sqlite3", ">= 1.3.2"
+
+end

data/lib/flattery.rb

@@ -0,0 +1,4 @@
+require "active_support/core_ext"
+require "active_record"
+require "flattery/version"
+require "flattery/value_cache"

data/lib/flattery/value_cache.rb

@@ -0,0 +1,64 @@
+module Flattery::ValueCache
+  extend ActiveSupport::Concern
+
+  included do
+    class_attribute :value_cache_options
+    self.value_cache_options = {}
+
+    before_save :resolve_value_cache
+  end
+
+  module ClassMethods
+
+    # Command: adds flattery definition +options+.
+    # The +options+ define a single cache setting. To define multiple cache settings, call flatten_value once for each setting.
+    #
+    # +options+ by example:
+    #    flatten_value :category => :name
+    #    # => will cache self.category.name to self.category_name
+    #    flatten_value :category => :name, :as => 'cat_name'
+    #    # => will cache self.category.name to self.cat_name
+    #
+    # When explicitly passed nil, it clears all existing settings
+    #
+    def flatten_value(options={})
+      if options.nil?
+        self.value_cache_options = {}
+        return
+      end
+
+      self.value_cache_options ||= {}
+      opt = options.symbolize_keys
+      as_setting = opt.delete(:as)
+      association_name = opt.keys.first
+      association_method = opt[association_name]
+      cache_attribute = as_setting || "#{association_name}_#{association_method}"
+
+      assoc = reflect_on_association(association_name)
+      cache_options = if assoc && assoc.belongs_to? && assoc.klass.column_names.include?("#{association_method}")
+        {
+          association_name: association_name,
+          association_method: association_method,
+          changed_on: [assoc.foreign_key]
+        }
+      end
+
+      if cache_options
+        self.value_cache_options[cache_attribute] = cache_options
+      else
+        self.value_cache_options.delete(cache_attribute)
+      end
+    end
+
+  end
+
+  def resolve_value_cache
+    self.class.value_cache_options.each do |key,options|
+      if changed & options[:changed_on]
+        self.send("#{key}=", self.send(options[:association_name]).try(:send,options[:association_method]))
+      end
+    end
+    true
+  end
+
+end

data/lib/flattery/version.rb

@@ -0,0 +1,3 @@
+module Flattery
+  VERSION = "0.0.1"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,28 @@
+require 'flattery'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  # == Mock Framework
+  #
+  # If you prefer to use mocha, flexmock or RR, uncomment the appropriate line:
+  #
+  # config.mock_with :mocha
+  # config.mock_with :flexmock
+  # config.mock_with :rr
+  config.mock_with :rspec
+
+  # Remove this line if you're not using ActiveRecord or ActiveRecord fixtures
+  # config.fixture_path = "#{::Rails.root}/spec/fixtures"
+
+  # If you're not using ActiveRecord, or you'd prefer not to run each of your
+  # examples within a transaction, remove the following line or assign false
+  # instead of true.
+  # config.use_transactional_fixtures = true
+
+  config.before do
+    truncate_records
+  end
+end

data/spec/support/active_record_fixtures.rb

@@ -0,0 +1,54 @@
+
+ActiveRecord::Base.establish_connection(:adapter => 'sqlite3', :database => ":memory:")
+
+ActiveRecord::Migration.suppress_messages do
+  ActiveRecord::Schema.define(:version => 0) do
+
+    create_table(:notes, :force => true) do |t|
+      t.string :name;
+      t.belongs_to :category;
+      t.string :category_name;
+      t.string :person_name;
+      t.string :person_email;
+    end
+
+    create_table(:categories, :force => true) do |t|
+      t.string :name;
+    end
+
+    create_table(:people, :force => true) do |t|
+      t.string :username;
+      t.string :email;
+    end
+
+  end
+end
+
+# Basic models for testing
+class Note < ActiveRecord::Base
+  belongs_to :category
+  belongs_to :person, primary_key: "username", foreign_key: "person_name"
+end
+
+class Category < ActiveRecord::Base
+  has_many :notes
+end
+
+class Person < ActiveRecord::Base
+  has_many :notes, inverse_of: :person
+end
+
+module ArHelper
+
+  # Clears any configuration
+  def truncate_records
+    Note.delete_all
+    Category.delete_all
+    Person.delete_all
+  end
+
+end
+
+RSpec.configure do |conf|
+  conf.include ArHelper
+end

data/spec/unit/value_cache_spec.rb

@@ -0,0 +1,133 @@
+require 'spec_helper.rb'
+
+class FlatteryValueCacheTestHarness < Note
+  include Flattery::ValueCache
+end
+
+describe Flattery::ValueCache do
+
+  let(:resource_class) { FlatteryValueCacheTestHarness }
+  after { resource_class.value_cache_options = {} }
+
+  describe "##included_modules" do
+    subject { resource_class.included_modules }
+    it { should include(Flattery::ValueCache) }
+  end
+
+  describe "##value_cache_options" do
+    before { resource_class.flatten_value flatten_value_options }
+    subject { resource_class.value_cache_options }
+
+    context "when set to empty" do
+      let(:flatten_value_options) { {} }
+      it { should be_empty }
+    end
+
+    context "with simple belongs_to associations" do
+
+      context "when set by association name and attribute value" do
+        let(:flatten_value_options) { {category: :name} }
+        it { should eql({
+          "category_name" => {
+            association_name: :category,
+            association_method: :name,
+            changed_on: ["category_id"]
+          }
+        }) }
+
+        context "when force reset to nil" do
+          it "should clear all settings" do
+            expect {
+              resource_class.flatten_value nil
+            }.to change {
+              resource_class.value_cache_options
+            }.to({})
+          end
+        end
+      end
+
+      context "when set by association name and invalid attribute value" do
+        let(:flatten_value_options) { {category: :bogative} }
+        it { should be_empty }
+      end
+
+    end
+
+    context "with a belongs_to association having non-standard primary and foreign keys" do
+
+      context "when set by association name and attribute value" do
+        let(:flatten_value_options) { {person: :email} }
+        it { should eql({
+          "person_email" => {
+            association_name: :person,
+            association_method: :email,
+            changed_on: ["person_name"]
+          }
+        }) }
+      end
+
+      context "when set by association name and invalid attribute value" do
+        let(:flatten_value_options) { {person: :bogative} }
+        it { should be_empty }
+      end
+
+    end
+
+
+  end
+
+  describe "#resolve_value_cache" do
+    it "should be called when record created" do
+      resource_class.any_instance.should_receive(:resolve_value_cache).and_return(true)
+      resource_class.create!
+    end
+    it "should be called when record updated" do
+      instance = resource_class.create!
+      instance.should_receive(:resolve_value_cache).and_return(true)
+      instance.save
+    end
+  end
+
+  describe "#before_save" do
+    let!(:resource) { resource_class.create }
+
+    context "with simple belongs_to associations with cached values" do
+      before { resource_class.flatten_value category: :name }
+      let!(:category) { Category.create(name: 'category_a') }
+
+      context "when association is changed by id" do
+        it "should cache the new value" do
+          expect {
+            resource.update_attributes(category_id: category.id)
+          }.to change {
+            resource.category_name
+          }.from(nil).to(category.name)
+        end
+      end
+      context "when already set" do
+        before { resource.update_attributes(category_id: category.id) }
+        context "then set to nil" do
+          it "should cache the new value" do
+            expect {
+              resource.update_attributes(category_id: nil)
+            }.to change {
+              resource.category_name
+            }.from(category.name).to(nil)
+          end
+        end
+        context "and associated record is destroyed" do
+          before { category.destroy }
+          it "should not recache the value when other values updated" do
+            expect {
+              resource.update_attributes(name: 'a new name')
+            }.to_not change {
+              resource.category_name
+            }.from(category.name)
+          end
+        end
+      end
+
+    end
+  end
+
+end

metadata

@@ -0,0 +1,208 @@
+--- !ruby/object:Gem::Specification
+name: flattery
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Paul Gallagher
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-09-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.3
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.3
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rb-fsevent
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.3.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.3.2
+description: Flatten/normalise values from ActiveModel associations
+email:
+- paul@evendis.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rvmrc
+- .travis.yml
+- Gemfile
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- flattery.gemspec
+- lib/flattery.rb
+- lib/flattery/value_cache.rb
+- lib/flattery/version.rb
+- spec/spec_helper.rb
+- spec/support/active_record_fixtures.rb
+- spec/unit/value_cache_spec.rb
+homepage: https://github.com/evendis/flattery
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Flatter your nicely normalised AR models
+test_files:
+- spec/spec_helper.rb
+- spec/support/active_record_fixtures.rb
+- spec/unit/value_cache_spec.rb