Volute.apply() for application on-demand

Volute.apply(object, attribute=nil, previous_value=nil, value=nil)

CHANGELOG.txt

@@ -4,6 +4,7 @@
 
 == volute - 0.1.1    not yet released
 
+- Volute.apply(object, attribute=nil, previous_value=nil, value=nil)
 - volutes /regex_on_attribute_name/ { ... }
 - volutes :not, args { ... }
 - volutes.remove(Financing) for removing top-level volutes

README.rdoc

@@ -200,6 +200,40 @@ Each volute that matches sees its block called. In order to prevent further eval
   end
 
 
+== application of the volutes on demand
+
+Up until now, this readme focused on the scenario where volute application is triggered by a change in the state of an attribute (in a class that includes Volute).
+
+It is entirely OK to have classes that do not include Volute but are the object of a volute application :
+
+  class Engine
+    attr_accessor :state
+    def turn_key!
+      @key_turned = true
+      Volute.apply(self, :key_turned)
+    end
+    def press_red_button!
+      Volute.apply(self)
+    end
+  end
+
+  volute Engine do
+    if attribute == :key_turned
+      object.state = :running
+    else
+      object.state = :off
+    end
+  end
+
+The key here is the call to
+
+  Volute.apply(object, attribute=nil, previous_value=nil, value=nil)
+
+In fact, for classes that include Volute, this is method called for each attribute getting set.
+
+This technique is also a key when building system where the volutes aren't called all the time but only right before their result should matter ('decision' versus 'reaction').
+
+
 == volute management
 
 TODO

TODO.txt

@@ -7,6 +7,7 @@
     volute Class, :attr { } --> Class OR attr
 [o] volute :not, Light { ... }
 [o] volute /^att/ { ... }
+[o] not including Volute, but triggering Volute.xxx on some changes
 
 [ ] volute /regex/ => /regex/ { ... }
 
@@ -29,5 +30,3 @@
 
 [ ] pass the object as block binding ?
 
-[ ] not including Volute, but triggering Volute.xxx on some changes
-

lib/volute.rb

@@ -88,7 +88,29 @@ def self.clear!
     @top = nil
   end
 
-  def self.apply(object, attribute, previous_value, value)
+  # Volute.apply is generally called from the setter of a class which include
+  # Volute, but it's OK to call it directly, to force volute application.
+  #
+  #   class Engine
+  #     attr_accessor :state
+  #     def turn_key!
+  #       @key_turned = true
+  #       Volute.apply(self, :key_turned)
+  #     end
+  #     def press_red_button!
+  #       Volute.apply(self)
+  #     end
+  #   end
+  #
+  #   volute Engine do
+  #     if attribute == :key_turned
+  #       object.state = :running
+  #     else
+  #       object.state = :off
+  #     end
+  #   end
+  #
+  def self.apply(object, attribute=nil, previous_value=nil, value=nil)
 
     target = Target.new(object, attribute, previous_value, value)
 

spec/apply_spec.rb

@@ -0,0 +1,52 @@
+
+require File.join(File.dirname(__FILE__), 'spec_helper.rb')
+
+
+class Engine
+  attr_accessor :state
+
+  def turn_key!
+    @key_turned = true
+    Volute.apply(self, :key_turned)
+  end
+
+  def press_red_button!
+    Volute.apply(self)
+  end
+end
+
+
+describe 'Volute.apply' do
+
+  before(:each) do
+
+    Volute.clear!
+
+    volute Engine do
+      if attribute == :key_turned
+        object.state = :running
+      else
+        object.state = :off
+      end
+    end
+
+    @engine = Engine.new
+
+    volute Package do
+      volute do
+        over if object.delivered
+      end
+      volute :location do
+        (object.comment ||= []) << value
+      end
+    end
+  end
+
+  it 'should apply volutes' do
+
+    @engine.turn_key!
+
+    @engine.state.should == :running
+  end
+end
+

volute.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |s|
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["John Mettraux"]
-  s.date = %q{2010-10-09}
+  s.date = %q{2010-10-10}
   s.description = %q{
 placing some [business] logic outside of classes
   }
@@ -29,7 +29,9 @@ placing some [business] logic outside of classes
      "examples/state_machine.rb",
      "examples/traffic.rb",
      "lib/volute.rb",
-     "spec/guard_spec.rb",
+     "spec/apply_spec.rb",
+     "spec/filter_not_spec.rb",
+     "spec/filter_spec.rb",
      "spec/include_volute_spec.rb",
      "spec/over_spec.rb",
      "spec/spec_helper.rb",
@@ -44,7 +46,9 @@ placing some [business] logic outside of classes
   s.rubygems_version = %q{1.3.7}
   s.summary = %q{placing some [business] logic outside of classes}
   s.test_files = [
-    "spec/guard_spec.rb",
+    "spec/apply_spec.rb",
+     "spec/filter_not_spec.rb",
+     "spec/filter_spec.rb",
      "spec/include_volute_spec.rb",
      "spec/over_spec.rb",
      "spec/spec_helper.rb",