davidlee-state-fu 0.11.1 → 0.12.0

data/lib/lathe.rb

@@ -58,6 +58,17 @@ module StateFu
       machine.lathe
     end
 
+    alias_method :context, :state_or_event
+
+    def context_state
+      state_or_event if state_or_event.is_a?(State)
+    end
+
+    def context_event
+      state_or_event if state_or_event.is_a?(Event)
+    end
+
+
     #
     # methods for extending the DSL
     #
@@ -68,11 +79,17 @@ module StateFu
     end
 
     # helpers are mixed into all binding / transition contexts
-    def tool( *modules )
+    def tool( *modules, &block )
       machine.tool *modules
+      if block_given?
+        tool = Module.new
+        tool.module_eval &block
+        machine.tools << tool
+      end
       # inject them into self for immediate use
       modules.flatten.extend( ToolArray ).inject_into( self )
     end
+    alias_method :extend_dsl, :tool
 
     #
     # event definition methods
@@ -514,7 +531,7 @@ module StateFu
             end
       args.map do |name|
         self.send type, name, options.dup, &block
-      end.extend mod
+      end.extend(mod)
     end
 
   end

data/lib/machine.rb

@@ -4,7 +4,7 @@ module StateFu
     def self.BINDINGS
       @@_bindings ||= {}
     end
-
+    
     include Applicable
     include HasOptions
     
@@ -17,10 +17,9 @@ module StateFu
     def self.for_class(klass, name, options={}, &block)
       options.symbolize_keys!
       name = name.to_sym
-
       unless machine = klass.state_fu_machines[ name ]
         machine = new(options)
-        machine.bind! klass, name, options[:field_name] 
+        machine.bind! klass, name, options
       end
       if block_given?
         machine.apply! &block 
@@ -30,26 +29,36 @@ module StateFu
 
     # make it so that a class which has included StateFu has a binding to
     # this machine
-    def self.bind!( machine, owner, name, field_name)
+    def self.bind!(machine, owner, name, options={})      
       name = name.to_sym
+      options[:define_methods] = (name == DEFAULT) unless options.symbolize_keys!.has_key?(:define_methods)
+      options[:field_name] ||= Persistence.default_field_name(name)
+      options[:singleton] = true unless owner.is_a?(Class)
       # define an accessor method with the given name
-      if owner.class == Class
-        owner.state_fu_machines[name]    = machine
-        owner.state_fu_field_names[name] = field_name
+      if options[:singleton]
+        _binding = StateFu::Binding.new machine, owner, name, options
+        MethodFactory.define_singleton_method(owner, name) { _binding }
+        if alias_name = options[:alias] || options[:as]
+          MethodFactory.define_singleton_method(owner, alias_name) { _binding }
+        end      
+      else
+        owner.state_fu_machines[name] = machine
+        owner.state_fu_options[name]  = options
         # method_missing to catch NoMethodError for event methods, etc
-        StateFu::MethodFactory.define_once_only_method_missing( owner )
-        unless owner.respond_to?(name)
+        StateFu::MethodFactory.define_once_only_method_missing owner 
+        unless owner.respond_to? name          
           owner.class_eval do
             define_method name do
-              state_fu( name )
+              state_fu name
+            end
+            # allow aliases to be set up, e.g. machine(:as => :status)
+            if alias_name = options[:alias] || options[:as]
+              alias_method alias_name, name
             end
           end
         end
         # prepare the persistence field
-        StateFu::Persistence.prepare_field owner, field_name 
-      else
-        _binding = StateFu::Binding.new machine, owner, name, :field_name => field_name, :singleton => true 
-        MethodFactory.define_singleton_method(owner, name) { _binding }
+        StateFu::Persistence.prepare_field owner, options[:field_name]
       end
     end
 
@@ -116,9 +125,8 @@ module StateFu
 
     # make it so a class which has included StateFu has a binding to
     # this machine
-    def bind!( owner, name= DEFAULT, field_name = nil )
-      field_name ||= Persistence.default_field_name( name )
-      self.class.bind!(self, owner, name, field_name)
+    def bind!(owner, name=DEFAULT, options={})
+      self.class.bind!(self, owner, name, options)
     end
 
     def empty?

data/lib/method_factory.rb

@@ -7,14 +7,15 @@ module StateFu
   
   class MethodFactory
     attr_accessor :method_definitions
-    attr_reader   :binding
-    
+    attr_reader   :binding, :machine
+
     # An instance of MethodFactory is created to define methods on a specific StateFu::Binding, and
     # on the object it is bound to.
     
-    def initialize( _binding )
-      @binding                      = _binding  
-      simple_events, complex_events = @binding.machine.events.partition(&:simple?)
+    def initialize(_binding)
+      @binding                      = _binding
+      @machine                      = binding.machine
+      simple_events, complex_events = machine.events.partition &:simple?
       @method_definitions           = {}
       
       # simple event methods
@@ -95,7 +96,7 @@ module StateFu
         end unless event.targets.nil?
       end
       
-      @binding.machine.states.each do |state|
+      machine.states.each do |state|
         method_definitions["#{state.name}?"] = lambda do 
          _binding.current_state == state
         end
@@ -114,9 +115,9 @@ module StateFu
     # Note this happens when a machine is first bound to the class,
     # not when StateFu is included.
 
-    def self.prepare_class( klass )
+    def self.prepare_class(klass)
       raise caller.inspect
-      self.define_once_only_method_missing( klass )
+      self.define_once_only_method_missing(klass)
     end # prepare_class
 
     # When triggered, method_missing will first call state_fu!,
@@ -137,7 +138,7 @@ module StateFu
     # or thoroughly understand what's happening in
     # MethodFactory#define_once_only_method_missing.
 
-    def self.define_once_only_method_missing( klass )
+    def self.define_once_only_method_missing(klass)
       raise ArgumentError.new(klass.to_s) unless klass.is_a?(Class)      
       
       klass.class_eval do                
@@ -160,14 +161,14 @@ module StateFu
           end
         
           # call the newly defined method, or the original method_missing
-          if respond_to?(method_name, true) 
+          if respond_to? method_name, true
             # it was defined by calling state_fu!, which instantiated bindings
             # for its state machines, which defined singleton methods for its
             # states & events when it was constructed.
-            __send__( method_name, *args, &block )
+            __send__ method_name, *args, &block
           else 
             # call the original method_missing (method_missing_before_state_fu)
-            method_missing( method_name, *args, &block )
+            method_missing method_name, *args, &block
           end
         end # method_missing
       end # class_eval
@@ -177,8 +178,8 @@ module StateFu
     # object.  Any existing methods will not be tampered with, but a
     # warning will be issued in the logs if any methods cannot be defined.
     def install!
-      define_event_methods_on( @binding )
-      define_event_methods_on( @binding.object )
+      define_event_methods_on @binding       
+      define_event_methods_on @binding.object if @binding.options[:define_methods]
     end
 
     #
@@ -202,13 +203,13 @@ module StateFu
     # itself.  The remaining arguments are passed into the transition,
     # as with simple event methods.
     #
-    def define_event_methods_on( obj )
+    def define_event_methods_on(obj)
       method_definitions.each do |method_name, method_body|
-        define_singleton_method( obj, method_name, &method_body)
+        define_singleton_method obj, method_name, &method_body
       end
     end # define_event_methods_on
 
-    def define_singleton_method( object, method_name, &block )
+    def define_singleton_method(object, method_name, &block)
       MethodFactory.define_singleton_method object, method_name, &block
     end
 
@@ -221,8 +222,8 @@ module StateFu
     #
     # existing methods will never be overwritten.
 
-    def self.define_singleton_method( object, method_name, options={}, &block )
-      if object.respond_to?(method_name, true) 
+    def self.define_singleton_method(object, method_name, options={}, &block)
+      if object.respond_to? method_name, true
         msg = !options[:force]
         Logger.info "Existing method #{method(method_name) rescue [method_name].inspect} "\
           "for #{object.class} #{object} "\
@@ -231,7 +232,7 @@ module StateFu
       else
         metaclass = class << object; self; end
         metaclass.class_eval do
-          define_method( method_name, &block )
+          define_method method_name, &block
         end
       end
     end

data/lib/persistence.rb

@@ -39,7 +39,7 @@ module StateFu
     end
 
     # returns the appropriate persister class for the given class & field name.
-    def self.class_for( klass, field_name )
+    def self.class_for(klass, field_name)
       raise ArgumentError if [klass, field_name].any?(&:nil?)
       @@class_for[klass] ||= {}
       @@class_for[klass][field_name] ||=
@@ -52,7 +52,7 @@ module StateFu
         end
     end
 
-    def self.for_class( klass, binding, field_name )
+    def self.for_class(klass, binding, field_name)
       persister_class = class_for klass, field_name
       prepare_field( klass, field_name, persister_class)
       returning persister_class.new( binding, field_name ) do |persister|
@@ -60,7 +60,7 @@ module StateFu
       end
     end
 
-    def self.for_instance( binding, field_name )
+    def self.for_instance(binding, field_name)
       metaclass = class << binding.object; self; end
       for_class( metaclass, binding, field_name )
     end
@@ -69,7 +69,7 @@ module StateFu
     # also ensures the persister class method :prepare_field has been called
     # once for the given class & field name so the field can be set up; eg an
     # attr_accessor or a before_save hook defined
-    def self.for( binding )
+    def self.for(binding)
       field_name = binding.field_name.to_sym
       if binding.singleton?
         for_instance( binding, field_name )
@@ -95,21 +95,21 @@ module StateFu
     # checks to see if the field_name for persistence is a
     # RelaxDB attribute.
     # Safe to use (skipped) if RelaxDB is not included.
-    def self.relaxdb_document_property?( klass, field_name )
+    def self.relaxdb_document_property?(klass, field_name)
       Object.const_defined?('RelaxDB') &&
         klass.ancestors.include?( ::RelaxDB::Document ) &&
-        klass.properties.map(&:to_s).include?( field_name.to_s )
+        klass.properties.map(&:to_s).include?(field_name.to_s)
     end
 
     # checks to see if the field_name for persistence is an
     # ActiveRecord column.
     # Safe to use (skipped) if ActiveRecord is not included.
-    def self.active_record_column?( klass, field_name )
+    def self.active_record_column?(klass, field_name)
       Object.const_defined?("ActiveRecord") &&
         ::ActiveRecord.const_defined?("Base") &&
-        klass.ancestors.include?( ::ActiveRecord::Base ) &&
+        klass.ancestors.include?(::ActiveRecord::Base) &&
         klass.table_exists? &&
-        klass.columns.map(&:name).include?( field_name.to_s )
+        klass.columns.map(&:name).include?(field_name.to_s)
     end
 
   end

data/lib/state-fu.rb

@@ -16,15 +16,13 @@
 #
 # It is also delightfully elegant and easy to use for simple things.
 
-
-require 'rubygems'
-
 [ 'support/core_ext',
   'support/logger',
   'support/applicable',
   'support/arrays',
   'support/methodical',
   'support/has_options',
+  'support/vizier',
   'support/plotter',
   'support/exceptions',
   'executioner',

data/lib/support/core_ext.rb

@@ -1,5 +1,3 @@
-require 'rubygems'
-
 # if ActiveSupport is absent, install a very small subset of it for
 # some convenience methods
 unless Object.const_defined?('ActiveSupport')  #:nodoc

data/lib/support/plotter.rb

@@ -1,4 +1,3 @@
-require 'vizier'
 require 'tempfile'
 
 module StateFu

data/lib/tasks/spec_last.rake

@@ -8,39 +8,48 @@ unless Object.const_defined?('STATE_FU_PLUGIN_PATH')
   STATE_FU_PLUGIN_PATH = Object.const_defined?('RAILS_ROOT') ? File.join( RAILS_ROOT, '/vendor/plugins/state-fu' ) : STATE_FU_APP_PATH
 end
 
-namespace :spec do
-  def find_last_modified_spec
-    require 'find'
-    specs = []
-    Find.find( File.expand_path(File.join(STATE_FU_APP_PATH,'spec'))) do |f|
-      next unless f !~ /\.#/ && f =~ /_spec.rb$/
-      specs << f
+begin
+  require 'rake'
+  require 'spec'
+  require 'spec/rake/spectask'
+
+  namespace :spec do
+    def find_last_modified_spec
+      require 'find'
+      specs = []
+      Find.find( File.expand_path(File.join(STATE_FU_APP_PATH,'spec'))) do |f|
+        next unless f !~ /\.#/ && f =~ /_spec.rb$/
+        specs << f
+      end
+      spec = specs.sort_by { |spec| File.stat( spec ).mtime }.last
     end
-    spec = specs.sort_by { |spec| File.stat( spec ).mtime }.last
-  end
 
-  desc "runs the last modified spec; L=n runs only that line"
-  Spec::Rake::SpecTask.new(:last) do |t|
-    specfile = find_last_modified_spec || return
-    t.verbose = true
-    t.spec_opts = ["-c","-b","-u"]
-    if ENV['L']
-      t.spec_opts += ["-l", ENV["L"],"-f", "specdoc"]
-    else
-      t.spec_opts += ["-f", "profile"]
+    desc "runs the last modified spec; L=n runs only that line"
+    Spec::Rake::SpecTask.new(:last) do |t|
+      specfile = find_last_modified_spec || return
+      t.verbose = true
+      t.spec_opts = ["-c","-b","-u"]
+      if ENV['L']
+        t.spec_opts += ["-l", ENV["L"],"-f", "specdoc"]
+      else
+        t.spec_opts += ["-f", "profile"]
+      end
+      t.spec_files = FileList[specfile]
     end
-    t.spec_files = FileList[specfile]
-  end
 
-  desc "runs all specs, or those which last failed"
-  Spec::Rake::SpecTask.new(:faily) do |t|
-    specfile    = find_last_modified_spec || return
-    faily       = 'spec.fail'
-    t.verbose   = true
-    t.spec_opts = ["-f","failing_examples:#{faily}", "-f","n","-c","-b","-u"]
-    if File.exists?(faily) && File.read(faily).split("\n")[0] != ""
-      t.spec_opts << ["-e",faily]
+    desc "runs all specs, or those which last failed"
+    Spec::Rake::SpecTask.new(:faily) do |t|
+      specfile    = find_last_modified_spec || return
+      faily       = 'spec.fail'
+      t.verbose   = true
+      t.spec_opts = ["-f","failing_examples:#{faily}", "-f","n","-c","-b","-u"]
+      if File.exists?(faily) && File.read(faily).split("\n")[0] != ""
+        t.spec_opts << ["-e",faily]
+      end
     end
   end
 
+rescue LoadError
+  # fail quietly if rspec is not installed
 end
+

data/lib/transition.rb

@@ -256,6 +256,10 @@ module StateFu
     alias_method :original_state, :origin
     alias_method :initial_state,  :origin
     alias_method :from,           :origin
+    
+    def cycle?
+      origin == target
+    end
 
     # an accepted transition == true
     # an unaccepted transition == false

data/lib/transition_query.rb

@@ -127,11 +127,11 @@ module StateFu
     end
     
     def events
-      map {|t| t.event }
+      map {|t| t.event }.extend EventArray
     end
 
     def targets
-      map {|t| t.target }
+      map {|t| t.target }.extend StateArray
     end
 
     private

data/spec/features/machine_alias_spec.rb

@@ -0,0 +1,46 @@
+require File.expand_path("#{File.dirname(__FILE__)}/../helper")
+
+describe "defining an alias for the default machine" do
+  describe "with machine(:as => :status)" do
+    before do
+      make_pristine_class('Klass')
+      Klass.machine :as => :status do
+        state :active
+      end
+      @obj = Klass.new
+    end
+
+    it "should not prevent normal access through #state_fu" do
+      @obj.state_fu.machine.should == Klass.machine
+    end
+    
+    it "should not affect the internal name of the machine" do
+      @obj.status.method_name.should == :default
+    end
+    
+    it "should let you access the machine through #status" do
+      @obj.status.should be_kind_of(StateFu::Binding)
+      @obj.status.machine.should == Klass.machine
+      @obj.status.current_state.should == :active
+    end
+    
+  end
+end
+
+describe "defining an alias for a default singleton machine" do
+  describe "with #bind! :default, :as => :alias" do
+    before do
+      make_pristine_class('Klass')
+      @machine = StateFu::Machine.new do
+        state :exemplary
+      end
+      @obj = Klass.new
+      @machine.bind!( @obj, :default, :as => :example)
+    end
+    
+    it "should work too" do
+      @obj.example.machine.should == @machine
+    end    
+  end
+end
+

data/spec/features/singleton_machine_spec.rb

@@ -5,7 +5,7 @@ describe "singleton machines" do
     make_pristine_class('Klass')
     @m = StateFu::Machine.new do
       state :a do
-        event :beatify, :transitions_to => :b
+        event :bify, :transitions_to => :b
       end
     end
     @m.events.length.should == 1
@@ -20,9 +20,22 @@ describe "singleton machines" do
     @obj.my_binding.object.should == @obj
   end
 
-  it "should have event methods defined" do
-    %w/beatify can_beatify? beatify!/.each do |method_name|
+  it "should have methods defined on the binding by default" do
+    %w/bify can_bify? bify!/.each do |method_name|
       @obj.my_binding.should respond_to(method_name)
+    end
+  end
+  
+  it "should not have methods defined on the instance by default" do
+    %w/bify can_bify? bify!/.each do |method_name|
+      @obj.should_not respond_to(method_name)
+    end    
+  end
+  
+
+  it "should have methods defined on the instance if bound with :define_methods => true" do
+    @m.bind!( @obj, :my_binding, :define_methods => true)
+    %w/bify can_bify? bify!/.each do |method_name|
       @obj.should respond_to(method_name)
     end
   end
@@ -30,7 +43,7 @@ describe "singleton machines" do
   it "should transition" do
     @b = @obj.my_binding
     @b.current_state.should == :a
-    t = @obj.beatify!
+    t = @obj.my_binding.bify!
     t.should be_kind_of(StateFu::Transition)
     t.should be_accepted
     @b.current_state.should == :b

data/spec/features/when_methods_are_defined_spec.rb

@@ -0,0 +1,114 @@
+require File.expand_path("#{File.dirname(__FILE__)}/../helper")
+
+describe "instance methods defined for a class's machine," do
+  before do
+    make_pristine_class('Klass')
+  end
+  
+  describe "for the default machine" do
+    it "should define methods for states and events" do
+      Klass.machine do
+        event :go, :from => :a, :to => :b
+      end
+      instance = Klass.new
+      instance.state_fu!
+      instance.should respond_to(:a?)
+      instance.should respond_to(:can_go?)      
+    end   
+
+    it "should not define methods given :define_methods => false" do
+      Klass.machine :define_methods => false do
+        event :go, :from => :a, :to => :b
+      end
+      instance = Klass.new
+      instance.state_fu!
+      instance.should_not respond_to(:a?)
+      instance.should_not respond_to(:can_go?)
+    end   
+  end
+  
+  describe "for other machines" do
+    it "should not define methods" do
+      Klass.machine :other do
+        event :go, :from => :a, :to => :b
+      end
+      instance = Klass.new
+      instance.state_fu!
+      instance.should_not respond_to(:a?)
+      instance.should_not respond_to(:can_go?)      
+    end
+    
+    it "should define methods given :define_methods => true" do
+      Klass.machine :define_methods => true do
+        event :go, :from => :a, :to => :b
+      end
+      instance = Klass.new
+      instance.state_fu!
+      instance.should respond_to(:a?)
+      instance.should respond_to(:can_go?)
+    end
+  end
+end
+
+
+describe "instance methods when you #bind! a machine" do
+  before do
+    make_pristine_class('Klass')
+    @machine = StateFu::Machine.new do
+      state :hot
+      state :cold
+    end
+  end
+  
+  describe "as the default machine," do
+    describe "the default behaviour" do
+      before do
+        @machine.bind! Klass, :default, :define_methods => true
+      end
+
+      it "defines methods" do
+        instance = Klass.new
+        instance.state_fu!
+        instance.should respond_to(:hot?)      
+      end
+    end
+
+    describe "when it is bound with :define_methods => false" do
+      before do
+        @machine.bind! Klass, :default, :define_methods => false
+      end
+
+      it "should not define methods" do
+        instance = Klass.new
+        instance.state_fu!
+        instance.should_not respond_to(:hot?)      
+      end
+    end
+  end
+
+  describe "as another machine," do
+    describe "the default behaviour" do
+      before do
+        @machine.bind! Klass, :temperature
+      end
+
+      it "should not define methods" do
+        instance = Klass.new
+        instance.state_fu!
+        instance.should_not respond_to(:hot?)      
+      end
+    end
+
+    describe "when it is bound with :define_methods => true" do
+      before do
+        @machine.bind! Klass, :temperature, :define_methods => true
+      end
+
+      it "should define methods" do
+        instance = Klass.new
+        instance.state_fu!
+        instance.should respond_to(:hot?)      
+      end
+    end
+  end
+end 

data/spec/spec_helper.rb

@@ -4,7 +4,7 @@ thisdir = File.expand_path(File.dirname(__FILE__))
 # ensure we require state-fu from lib, not gems
 $LOAD_PATH.unshift( "#{thisdir}/../lib" )
 require 'state-fu'
-require 'no_stdout'
+require 'support/no_stdout'
 require 'fileutils'
 require 'rubygems'
 require 'spec'