ball_gag 0.0.4 → 0.0.5

data/Readme.md

@@ -2,7 +2,7 @@
 
 Validate user-generated content against acceptable content rules.  BallGag provides a convenient interface for describing the acceptability of the attributes of Ruby objects.
 
-When an attribute is gagged, <tt>#{method}_gagged?</tt> and <tt>#{method}_not_gagged?</tt> methods are added to the class.
+When an attribute is gagged, `#{method}_gagged?` and `#{method}_not_gagged?` methods are added to the class.
 
 ## Example
 Here's a simple example demonstrating gagging of a single attribute.
@@ -29,13 +29,13 @@ Post.new('That was some fine watermelon').body_gagged?
 ````
 
 ## Using it with Rails
-BallGag integrates easily into your Rails app, allowing you validate that <tt>ActiveModel</tt> attributes are acceptable. First, add the gem to your <tt>Gemfile</tt>
+BallGag integrates easily into your Rails app, allowing you validate that `ActiveModel` attributes are acceptable. First, add the gem to your `Gemfile`
 
 ````ruby
 gem 'ball_gag'
 ````
 
-Now a <tt>NotGaggedValidator</tt> is available which you can use like this.
+Now a `NotGaggedValidator` is available which you can use like this.
 
 ````ruby
 class Post < ActiveRecord::Base
@@ -61,42 +61,60 @@ Each gagged attribute can be provided its own block to call when checking accept
 BallGag.engine = lambda { |content| !/damn/.match content }
 ````
 
-Any object that responds to <tt>call</tt> can be used as an engine.
+Any object that responds to `call` can be used as an engine.
+
+Another global option that can be set is `<BallGag.only_validate_on_attribute_changed/tt>. When this is set to true, `:not_gagged` validations will not be run unless the attribute has changed. This can help you avoid writing boilerplate and can make conditionals provided to your validations more concise. Compare the following two examples to see how specifying this option simplifies validations.
+
+````ruby
+BallGag.only_validate_on_attribute_changed = true
+
+class Post < ActiveRecord::Base
+  validates :text, not_gagged: { unless: -> { author.admin? } }
+end
+````
+
+vs.
+
+````ruby
+class Post < ActiveRecord::Base
+  validates :text, not_gagged: { unless: -> { author.admin? || !text_changed? } }
+end
+````
 
 ## Signature
 
-The first argument to <tt>call</tt> is the value, or hash of values to be checked for acceptability.
+The first argument to `call` is the value, or hash of values to be checked for acceptability.
 
-If a single attribute is gagged, the <tt>call</tt> method is invoked with the value of the attribute. If multiple attributes are gagged, the <tt>call</tt> method is invoked with a hash whose keys are the gagged attribute names and whose values are the attributes' values.
+If a single attribute is gagged, the `call` method is invoked with the value of the attribute. If multiple attributes are gagged, the `call` method is invoked with a hash whose keys are the gagged attribute names and whose values are the attributes' values.
 
-The second argument to <tt>call</tt> is a hash of options. This hash has the following entries:
+The second argument to `call` is a hash of options. This hash has the following entries:
 <table>
   <tbody>
     <tr>
-      <td><tt><strong>:instance</strong></tt></td>
+      <td>`<strong>:instance</strong>`</td>
       <td>The instance on which the attribute checked was invoked.</td>
     </tr>
     <tr>
-      <td><tt><strong>:options</strong></tt></td>
-      <td>The options supplied to the specific <tt>gag</tt> call.</td>
+      <td>`<strong>:options</strong>`</td>
+      <td>The options supplied to the specific `gag` call.</td>
     </tr>
     <tr>
-      <td><tt><strong>:single</strong></tt></td>
-      <td>A boolean indicating whether the <tt>gag</tt> method was invoked with only one attribute.</td>
+      <td>`<strong>:single</strong>`</td>
+      <td>A boolean indicating whether the `gag` method was invoked with only one attribute.</td>
     </tr>
     <tr>
-      <td><tt><strong>:attr</strong></tt></td>
+      <td>`<strong>:attr</strong>`</td>
       <td>The name of the attribute being checked. This is only useful for single-attribute gags.</td>
     </tr>
   </tbody>
 </table>
 
-Since options provided to the <tt>gag</tt> method are passed through to your back-end, you can use them when building up a request to send to a 3rd-party.
+Since options provided to the `gag` method are passed through to your back-end, you can use them when building up a request to send to a 3rd-party.
 
 ## Integration with 3rd-party tools
 The real power of BallGag is in how it integrates with 3rd-party moderation services. BallGag helps you thread model-specific information through to a remote back-end.
 
-An advanced engine may need to handle accepability of single and multiple attributes. The handler can differentiate between the two types of calls by inspecting the <tt>:single</tt> key of the options it's called with.
+An advanced engine may need to handle accepability of single and multiple attributes. The handler can differentiate between the two types of calls by inspecting the `:single` key of the options it's called with.
 
 Here's an example engine that accepts single and multi-attribute calls and validates against a made-up RESTful moderation service.
 
@@ -126,7 +144,7 @@ BallGag.engine = ModerationServiceEngine
 
 ## Cloaking
 If you need flexibility in how the library is used, you can reprogram the API.
-First, an alternative top-level module called <tt>BowlingBall</tt> is provided. Include <tt>BowlingBall</tt> in your models to get access to the same functionality you would get with <tt>BallGag</tt>.
+First, an alternative top-level module called `BowlingBall` is provided. Include `BowlingBall` in your models to get access to the same functionality you would get with `BallGag`.
 You can also specify an alternate verb for gagging attributes, and an alternate preterite form of the verb for querying the attribute. The preterite form supplied also makes positive and negative validations of the same name available.
 
 ````ruby

data/lib/ball_gag/bowling_ball.rb

@@ -31,6 +31,15 @@ module BowlingBall
     def negative_preterite= preterite
       BallGag.negative_preterite = preterite
     end
+
+    def only_validate_on_attribute_changed
+      BallGag.only_validate_on_attribute_changed
+    end
+
+    def only_validate_on_attribute_changed= bool
+      BallGag.only_validate_on_attribute_changed = bool
+    end
+
   end
 end
 

data/lib/ball_gag/engine.rb

@@ -1,13 +1,11 @@
 module BallGag
   module Engine
     module ClassMethods
-      def engine
-        @engine
-      end
+      attr_accessor(
+        :engine,
+        :only_validate_on_attribute_changed
+      )
 
-      def engine= new_engine
-        @engine = new_engine
-      end
     end
   end
 

data/lib/ball_gag/gag.rb

@@ -7,6 +7,10 @@ module BallGag
     end
   end
 
+  def invalidate_gag_cache attributes
+    @gagged_attribute_results.delete(attributes)
+  end
+
   module ClassMethods
     def gagged_attributes
       clear_gagged_attributes unless @gagged_attributes
@@ -79,8 +83,15 @@ module BallGag
           gagged_attribute_negative_interpellation_name(attr)) do
             @gagged_attribute_results ||= {}
 
+            # Is the attribute dirty?
+            any_changed = attributes.any? do |attribute|
+              dirty_method_name = "#{attribute}_changed?"
+              respond_to?(dirty_method_name) &&
+                method(dirty_method_name).call
+            end
+
             # Have we performed this call already?
-            unless @gagged_attribute_results.has_key?(attributes)
+            if any_changed || !@gagged_attribute_results.has_key?(attributes)
               @gagged_attribute_results[attributes] = fn.call(self, attr)
             end
 
@@ -89,7 +100,7 @@ module BallGag
             if one_attribute
               # If only one attribute was supplied, a simple
               # boolean response is sufficient
-              return false unless call_result
+              return unless call_result
               return true unless call_result.respond_to?(:[])
             else
               raise BadResultsMappingError unless call_result.respond_to?(:[])

data/lib/ball_gag/validations.rb

@@ -1,5 +1,12 @@
 class GaggedValidator < ActiveModel::EachValidator
   def validate_each object, attribute, value
+    if BallGag.only_validate_on_attribute_changed
+      dirty_method_name = "#{attribute}_changed?"
+      if object.respond_to?(dirty_method_name)
+        return unless object.method(dirty_method_name).call
+      end
+    end
+
     unless object.method(condition_method_name(attribute)).call
       object.errors[attribute] << (options[:message] || default_message)
     end

data/lib/ball_gag/version.rb

@@ -1,4 +1,4 @@
 module BallGag
-  VERSION = '0.0.4'
+  VERSION = '0.0.5'
 end
 

data/spec/cloak_spec.rb

@@ -7,6 +7,7 @@ describe 'BallGag cloaking' do
     ExampleActiveModel.clear_gagged_attributes
     BallGag.verb = nil
     BallGag.preterite = nil
+    BallGag.only_validate_on_attribute_changed = false
   end
 
   after do
@@ -147,6 +148,11 @@ describe 'BallGag cloaking' do
       BowlingBall.engine = mock_engine
       BallGag.engine.should eq mock_engine
     end
+
+    it 'should set only_validate_on_attribute_changed' do
+      BowlingBall.only_validate_on_attribute_changed = true
+      BallGag.only_validate_on_attribute_changed.should be_true
+    end
   end
 end
 

data/spec/gag_spec.rb

@@ -238,6 +238,42 @@ describe ExampleModel do
       2.times { instance.words_gagged? }
       2.times { instance.email_gagged? }
     end
+
+    it 'can invalidate cache' do
+      callable = lambda {}
+      mock_words = mock('words')
+      ExampleModel.gag :words, callable
+
+
+      instance = ExampleModel.new
+      instance.stub!(words: mock_words)
+      callable.should_receive(:call).
+        with(mock_words, anything).
+        exactly(2).times
+
+      instance.words_gagged?
+
+      instance.invalidate_gag_cache([:words])
+
+      instance.words_gagged?
+    end
+
+    it 'should should invalidate cache when attribute changes' do
+      callable = lambda {}
+      ExampleActiveModel.gag :words, callable
+      instance = ExampleActiveModel.new
+
+      callable.should_receive(:call).
+        with(instance.words, anything).once
+      callable.should_receive(:call).
+        with(instance.words + ' you see', anything).once
+
+      instance.words_gagged?
+      instance.words = instance.words + ' you see'
+      instance.should be_words_changed
+
+      instance.words_gagged?
+    end
   end
 
   describe 'error cases' do

data/spec/support/models.rb

@@ -12,10 +12,18 @@ end
 
 class ExampleActiveModel
   include ActiveModel::Validations
+  include ActiveModel::Dirty
   include BallGag
 
+  define_attribute_methods [ :words ]
+
   def words
-    'Welcome to the place where all the creatures meet.'
+    @words || 'Welcome to the place where all the creatures meet.'
+  end
+
+  def words= words
+    words_will_change!
+    @words = words
   end
 end
 

data/spec/validations_spec.rb

@@ -4,6 +4,7 @@ describe 'ActiveModel::Validations integration' do
   before do
     ExampleActiveModel.reset_callbacks :validate
     ExampleActiveModel.clear_gagged_attributes
+    BallGag.only_validate_on_attribute_changed = false
   end
 
   describe NotGaggedValidator do
@@ -47,6 +48,23 @@ describe 'ActiveModel::Validations integration' do
       instance.should_not_receive(:words_not_gagged?)
       instance.valid?
     end
+
+    context 'when configured to only check on attribute changed' do
+      before { BallGag.only_validate_on_attribute_changed = true }
+
+      it 'should not call #{attribute}_not_gagged? if attribute is not changed' do
+        callable = lambda {}
+        ExampleActiveModel.gag :words, callable
+        ExampleActiveModel.validates :words,
+          not_gagged: true
+
+        instance = ExampleActiveModel.new
+        instance.should_not be_words_changed
+
+        callable.should_not_receive(:call)
+        instance.valid?
+      end
+    end
   end
 
   describe GaggedValidator do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ball_gag
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-11-08 00:00:00.000000000 Z
+date: 2011-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70274670743440 !ruby/object:Gem::Requirement
+  requirement: &70215291665000 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70274670743440
+  version_requirements: *70215291665000
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70274670742620 !ruby/object:Gem::Requirement
+  requirement: &70215291664360 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70274670742620
+  version_requirements: *70215291664360
 - !ruby/object:Gem::Dependency
   name: activemodel
-  requirement: &70274670741600 !ruby/object:Gem::Requirement
+  requirement: &70215291663520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70274670741600
+  version_requirements: *70215291663520
 description: Validate user input using pluggable back-ends
 email:
 - duncan@dweebd.com