requires_approval 1.0.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

@@ -0,0 +1,5 @@
+--color
+--format nested
+--fail-fast
+-p
+--order random

data/Gemfile

@@ -0,0 +1,23 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+gem "activerecord", "~> 3.0.9"
+gem "activesupport", "~> 3.0.9"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "bundler"
+  gem "guard-rspec"
+  gem "guard-bundler"
+  gem "guard-spork"
+  gem "jeweler", "~> 1.8.3"
+  gem "mocha"
+  gem "rdoc"
+  gem "rspec"
+  gem "ruby-debug19", :require => "ruby-debug"
+  gem "sqlite3"
+  gem "yard"
+end

data/Gemfile.lock

@@ -0,0 +1,96 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.0.16)
+      activesupport (= 3.0.16)
+      builder (~> 2.1.2)
+      i18n (~> 0.5.0)
+    activerecord (3.0.16)
+      activemodel (= 3.0.16)
+      activesupport (= 3.0.16)
+      arel (~> 2.0.10)
+      tzinfo (~> 0.3.23)
+    activesupport (3.0.16)
+    archive-tar-minitar (0.5.2)
+    arel (2.0.10)
+    builder (2.1.2)
+    columnize (0.3.6)
+    diff-lcs (1.1.3)
+    ffi (1.1.0)
+    git (1.2.5)
+    guard (1.2.3)
+      listen (>= 0.4.2)
+      thor (>= 0.14.6)
+    guard-bundler (1.0.0)
+      bundler (~> 1.0)
+      guard (~> 1.1)
+    guard-rspec (1.2.0)
+      guard (>= 1.1)
+    guard-spork (1.1.0)
+      guard (>= 1.1)
+      spork (>= 0.8.4)
+    i18n (0.5.0)
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.7.4)
+    linecache19 (0.5.12)
+      ruby_core_source (>= 0.1.4)
+    listen (0.4.7)
+      rb-fchange (~> 0.0.5)
+      rb-fsevent (~> 0.9.1)
+      rb-inotify (~> 0.8.8)
+    metaclass (0.0.1)
+    mocha (0.12.1)
+      metaclass (~> 0.0.1)
+    rake (0.9.2.2)
+    rb-fchange (0.0.5)
+      ffi
+    rb-fsevent (0.9.1)
+    rb-inotify (0.8.8)
+      ffi (>= 0.5.0)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.1)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.11.1)
+    ruby-debug-base19 (0.11.25)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby_core_source (>= 0.1.4)
+    ruby-debug19 (0.11.6)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby-debug-base19 (>= 0.11.19)
+    ruby_core_source (0.1.5)
+      archive-tar-minitar (>= 0.5.2)
+    spork (0.9.2)
+    sqlite3 (1.3.6)
+    thor (0.15.4)
+    tzinfo (0.3.33)
+    yard (0.8.2.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord (~> 3.0.9)
+  activesupport (~> 3.0.9)
+  bundler
+  guard-bundler
+  guard-rspec
+  guard-spork
+  jeweler (~> 1.8.3)
+  mocha
+  rdoc
+  rspec
+  ruby-debug19
+  sqlite3
+  yard

data/Guardfile

@@ -0,0 +1,42 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'bundler' do
+  watch('Gemfile')
+  # Uncomment next line if Gemfile contain `gemspec' command
+  # watch(/^.+\.gemspec/)
+end
+
+guard 'spork', :cucumber_env => { 'RAILS_ENV' => 'test' }, :rspec_env => { 'RAILS_ENV' => 'test' } do
+  watch('config/application.rb')
+  watch('config/environment.rb')
+  watch('config/environments/test.rb')
+  watch(%r{^config/initializers/.+\.rb$})
+  watch('Gemfile')
+  watch('Gemfile.lock')
+  watch('spec/spec_helper.rb') { :rspec }
+  watch('test/test_helper.rb') { :test_unit }
+  watch(%r{features/support/}) { :cucumber }
+end
+
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+  # Rails example
+  watch(%r{^app/(.+)\.rb$})                           { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^app/(.*)(\.erb|\.haml)$})                 { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
+  watch(%r{^app/controllers/(.+)_(controller)\.rb$})  { |m| ["spec/routing/#{m[1]}_routing_spec.rb", "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb", "spec/acceptance/#{m[1]}_spec.rb"] }
+  watch(%r{^spec/support/(.+)\.rb$})                  { "spec" }
+  watch('config/routes.rb')                           { "spec/routing" }
+  watch('app/controllers/application_controller.rb')  { "spec/controllers" }
+  
+  # Capybara request specs
+  watch(%r{^app/views/(.+)/.*\.(erb|haml)$})          { |m| "spec/requests/#{m[1]}_spec.rb" }
+  
+  # Turnip features and steps
+  watch(%r{^spec/acceptance/(.+)\.feature$})
+  watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$})   { |m| Dir[File.join("**/#{m[1]}.feature")][0] || 'spec/acceptance' }
+end
+

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Dan Langevin
+
+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.rdoc

@@ -0,0 +1,121 @@
+= requires_approval
+
+===Installation
+
+To install, just add requires_approval to your Gemfile
+
+  # Gemfile
+  gem "requires_approval"
+
+=== Activation
+
+To activate, use the requires_approval_for method in your class definition
+
+  # app/models/user.rb
+  # 
+  # - first_name :string
+  # - last_name :string
+  # - birthday :date
+  # - created_at :datetime
+  # - updated_at :datetime
+  
+  class User < ActiveRecord::Base
+    requires_approval_for(:first_name, :last_name)
+  end
+
+And create a migration that adds the necessary table and fields for your
+requires_approval model
+
+  # db/migrate/TIMESTAMP_add_user_versions.rb
+  def self.up
+    User.prepare_tables_for_requires_approval
+  end
+
+This does the equivalent of the the following
+
+  # Generated migration
+  def self.up
+    create_table(:user_versions, :force => true) do |t|
+      t.string(:first_name)
+      t.string(:last_name)
+      t.integer(:user_id)
+      t.boolean(:is_approved)
+      t.timestamps
+    end
+    add_index(:user_versions, [:user_id, :is_approved])
+
+    # starts all new records out as frozen so they don't show up
+    add_column(:users, :is_frozen, :boolean, :default => true)
+
+  end
+
+=== Usage
+
+The first_name and last_name methods are now delegated to the user's
+latest_unapproved_version
+
+  u = User.new
+  u.first_name = "Dan"
+  u.first_name => nil
+  u.latest_unapproved_version.first_name => "Dan"
+  u.pending_changes => {
+    "first_name" => {
+      "was" => nil,
+      "became" => "Dan"
+    }
+  }
+  u.save
+
+  u.approve_attributes(:first_name)
+
+  u.first_name => "Dan"
+  
+  # it created one version and approved it
+  u.versions.count => 1
+
+  # so it won't show up as an unapproved version
+  u.latest_unapproved_version => nil
+  u.pending_changes => {}
+
+==== Denying attributes
+
+You can also deny changes.  If you do so, they just disappear from
+the latest_unapproved_version
+
+  u = User.create(:first_name => "X", :last_name => "Y")
+  u.approve_all_attributes
+
+  u.update_attribute(:first_name => "Dan")
+  u.pending_changes => {
+    "first_name" => {
+      "was" => "X",
+      "became" => "Dan"
+    }
+  }
+
+  u.deny_attributes(:first_name)
+  # no more changes
+  u.pending_changes => {}
+
+FYI, this doesn't actually remove the latest_unapproved_version, it just 
+sets its values to be the same as the values in the parent record.
+
+
+
+
+
+== Contributing to requires_approval
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2012 Dan Langevin. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,42 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "requires_approval"
+  gem.homepage = "http://github.com/LifebookerInc/requires_approval"
+  gem.license = "MIT"
+  gem.summary = %Q{Gem to handle versioning and things that require approval}
+  gem.description = %Q{Gem to handle versioning and things that require approval}
+  gem.email = "dan.langevin@lifebooker.com"
+  gem.authors = ["Dan Langevin"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/errors.rb

@@ -0,0 +1,11 @@
+module RequiresApproval
+  
+  class CustomError < StandardError; end;
+
+  class InvalidFieldsError < CustomError; end;
+
+  class DenyingNeverApprovedError < CustomError; end;
+
+  class PartialApprovalForNewObject < CustomError; end;
+
+end

data/lib/requires_approval.rb

@@ -0,0 +1,331 @@
+require 'active_record'
+require 'errors'
+
+
+module RequiresApproval
+
+  extend ActiveSupport::Concern
+
+  included do |klass|
+    klass.send(:extend, ClassMethods)
+  end
+
+  def approve_all_attributes
+    self.approve_attributes(self.fields_requiring_approval)
+  end
+
+  # # approve a list of attributes
+  def approve_attributes(*attributes)
+  
+    # validate an normalize our attributes    
+    attributes = self.check_attributes_for_approval(attributes)
+
+    # make sure that all attributes are provided if we have never
+    # been approved
+    fields_not_being_approved = (self.fields_requiring_approval - attributes)
+
+    if fields_not_being_approved.present? && self.never_approved?
+      raise PartialApprovalForNewObject.new(
+        "You must approve #{self.fields_requiring_approval.join(", ")} " + 
+        "for a new #{self.class.name}"
+      )
+    end
+
+    attributes.flatten.each do |attr|
+      write_attribute(attr, self.latest_unapproved_version.send(attr))
+    end
+
+    # if we have approved all requested changes, make our latest
+    # unapproved version approved
+    unless self.has_pending_changes?
+      self.latest_unapproved_version.update_attribute(:is_approved, true)
+    else
+      # makes our latest_unapproved_version approved and 
+      # creates another unapproved version with any remaining 
+      # attributes
+      self.create_approval_version_record
+    end
+
+    self.is_frozen = false
+
+    self.save
+    self.reload
+    true
+  end
+
+  def deny_attributes(*attributes)
+
+    unless self.has_approved_version?
+      raise DenyingNeverApprovedError.new
+    end
+
+    attributes = self.check_attributes_for_approval(attributes)
+
+    attributes.flatten.each do |attr|
+      self.latest_unapproved_version.send("#{attr}=", self.send(attr))
+      true
+    end
+
+    # if we have denied all changes, remove the record
+    unless self.has_pending_changes?
+      self.latest_unapproved_version.destroy
+    else
+      self.latest_unapproved_version.save
+    end
+    
+    self.reload
+    true
+  end
+
+  # have any of our versions ever been approved?
+  def has_approved_version?
+    self.versions.where(:is_approved => true).count > 0
+  end
+
+  # have we already approved all outstanding changes?
+  def has_pending_changes?
+    self.pending_changes.present?
+  end
+
+  # the changes users have requested since the last approval
+  def pending_changes
+    return {} if self.latest_unapproved_version.blank?
+    
+    ret = {}
+    # check each field requiring approval
+    self.fields_requiring_approval.each do |field|
+      # if it is the same in the unapproved as in the parent table
+      # we skip it
+      unless self.send(field) == self.latest_unapproved_version.send(field)
+        # otherwise we get the change set
+        ret[field] = {
+          "was" => self.send(field), 
+          "became" => self.latest_unapproved_version.send(field)
+        }
+      end
+    end
+    ret
+  end
+
+  protected
+
+  # the attributes that require approval
+  def attributes_requiring_approval
+    self.attributes.select{|k,v| self.fields_requiring_approval.include?(k)}
+  end
+
+  # check if our attributes are valid for approval
+  def check_attributes_for_approval(attributes)
+     # normalize attributes
+    attributes = Array.wrap(attributes).flatten.collect(&:to_s)
+
+    # check for invalid attributes
+    invalid_fields = (attributes - self.fields_requiring_approval)
+    # if we have fields not requiring approval, raise an error
+    if invalid_fields.present?
+      raise InvalidFieldsError.new(
+        "fields_requiring_approval don't include #{invalid_fields.join(",")}"
+      )
+    end
+    attributes
+  end
+
+  # creates the record of an individual approval
+  def create_approval_version_record
+    outstanding_changes = self.pending_attributes
+    # update our old latest_unapproved_version to reflect our changes
+    self.latest_unapproved_version.update_attributes(
+      self.attributes_requiring_approval.merge(:is_approved => true)
+    )
+    # reload so this unapproved version is out of our cache and will not 
+    # get its foreign key unassigned
+    self.latest_unapproved_version(true)
+
+    self.latest_unapproved_version = self.versions_class.new(
+      self.attributes_requiring_approval.merge(outstanding_changes)
+    )
+  end
+
+  # gets the latest unapproved version or creates a new one
+  def latest_unapproved_version_with_nil_check
+    self.latest_unapproved_version ||= begin
+      self.versions_class.new(self.attributes_requiring_approval)
+    end
+  end
+
+  # has this record never been approved?
+  def never_approved?
+    !self.has_approved_version?
+  end
+
+  # ActiveRecord-style attribute hash for the 
+  # requested changes
+  def pending_attributes
+    ret = {}
+    self.pending_changes.each_pair do |k, change|
+      ret[k] = change["became"]
+    end
+    ret
+  end
+
+  # the class which our versions are
+  def versions_class
+    self.class.versions_class
+  end
+
+  module ClassMethods
+
+    # adds the correct tables and columns for requires_approval
+    def prepare_tables_for_requires_approval
+      self.reset_column_information
+
+      # adds is_active to the parent table
+      self.add_requires_approval_fields
+      self.reset_column_information
+
+      # adds our versions table
+      self.drop_versions_table
+      self.create_versions_table
+      
+    end
+
+    def requires_approval_for(*attrs)
+      self.set_options(attrs.extract_options!)
+
+      # set up our attributes that require approval
+      self.class_attribute :fields_requiring_approval
+      self.fields_requiring_approval = attrs.collect(&:to_s)
+
+      # set up delegates
+      self.set_up_version_delegates
+
+      # create a blank version before create to handle if no
+      # attributes were ever set
+      self.before_validation(
+        :latest_unapproved_version_with_nil_check,
+        :on => :create
+      )
+      
+      # create the versions class
+      self.create_versions_class
+      self.has_many :versions, 
+        :class_name => self.versions_class.name,
+        :foreign_key => self.versions_foreign_key
+
+      self.has_one :latest_unapproved_version,
+        :autosave => true,
+        :class_name => self.versions_class.name,
+        :foreign_key => self.versions_foreign_key,
+        :conditions => [
+          "#{self.versions_table_name}.is_approved = ?", false
+        ]
+    end
+
+    def unapproved
+      includes(:latest_unapproved_version)
+        .where("#{self.versions_table_name}.id IS NOT NULL")
+    end
+
+    # the class which our versions are
+    def versions_class
+      "#{self.name}::#{self.versions_class_name}".constantize
+    end
+
+    protected
+
+    def add_requires_approval_fields
+      # add is_frozen
+      unless self.column_names.include?("is_frozen")
+        self.connection.add_column(
+          self.table_name, :is_frozen, :boolean, :default => true
+        )
+      end
+      # add is_deleted
+      unless self.column_names.include?("is_deleted")
+        self.connection.add_column(
+          self.table_name, :is_deleted, :boolean, :default => false
+        )
+      end
+      true
+    end
+
+    # create a class
+    def create_versions_class
+      versions_table_name = self.versions_table_name
+      
+      self.const_set self.versions_class_name, Class.new(ActiveRecord::Base)
+      
+      self.versions_class.class_eval do
+        self.table_name = versions_table_name
+      end
+    end
+
+    def create_versions_table
+      self.connection.create_table(self.versions_table_name) do |t|
+        self.columns.each do |column|
+          t.send(column.type, column.name, {
+            :default => column.default,
+            :limit => column.limit,
+            :null => column.null,
+            :precision => column.precision,
+            :scale => column.scale
+          })
+        end
+        t.integer self.versions_foreign_key
+        t.boolean :is_approved, :default => false
+      end
+      self.connection.add_index(
+        self.versions_table_name,
+        [self.versions_foreign_key, :is_approved]
+      )
+    end
+
+    # drop the versions table if it exists
+    def drop_versions_table
+      if self.connection.tables.include?(self.versions_table_name)
+        self.connection.drop_table(self.versions_table_name)
+      end
+    end
+
+    def set_options(opts = {})
+      @versions_class_name = opts.delete(:versions_class_name)
+      @version_foreign_key = opts.delete(:versions_foreign_key)
+      @versions_table_name = opts.delete(:versions_table_name)
+    end
+
+    def set_up_version_delegates
+      self.fields_requiring_approval.each do |f|
+        define_method("#{f}=") do |val|
+          self.send("#{f}_will_change!")
+          self.latest_unapproved_version_with_nil_check.send("#{f}=", val)
+        end
+      end
+    end
+
+    def validates_approved_field(*args)
+      self.versions_class.class_eval do
+        validates(*args)
+      end
+    end
+
+    # class name for our versions
+    def versions_class_name
+      @versions_class_name ||= "Version"
+    end
+
+    # foreign key for our class on the version table
+    def versions_foreign_key
+      @version_foreign_key ||= "#{self.base_class.name.underscore}_id"
+    end
+
+    # table name for our versions
+    def versions_table_name
+      @versions_table_name ||= "#{self.base_class.name.underscore}_versions"
+    end
+
+  end
+
+
+end
+
+ActiveRecord::Base.send(:include, RequiresApproval)