davidlee-state-fu 0.3.1 → 0.10.0

data/lib/state_fu/binding.rb

@@ -1,8 +1,8 @@
 module StateFu
   class Binding
-    include ContextualEval
 
-    attr_reader :object, :machine, :method_name, :persister, :transitions, :options
+    attr_reader :object, :machine, :method_name, :field_name, :persister, :transitions, :options, :target
+
 
     # the constructor should not be called manually; a binding is
     # returned when an instance of a class with a StateFu::Machine
@@ -18,39 +18,31 @@ module StateFu
       @method_name   = method_name
       @transitions   = []
       @options       = options.symbolize_keys!
-      field_name     = StateFu::FuSpace.field_names[object.class][@method_name]
-      raise( ArgumentError, "No field_name" ) unless field_name
-      # ensure state field is set up (in case we created this binding
-      # manually, instead of via Machine.bind!)
-      StateFu::Persistence.prepare_field( object.class, field_name )
-      # add a persister
-      @persister     = StateFu::Persistence.for( self, field_name )
-      Logger.debug( "Persister (#{@persister.class}) added: #{method_name} as field #{field_name}" )
-
-      # define event methods on self( binding ) and @object
-      StateFu::MethodFactory.new( self ).install!
-      machine.helpers.inject_into( self )
-      # StateFu::Persistence.prepare_field( @object.class, field_name )
+      @target        = singleton? ? object : object.class
+      @field_name    = options[:field_name] || @target.state_fu_field_names[method_name]
+      @persister     = Persistence.for( self )
+
+      # define event methods on this binding and its @object
+      MethodFactory.new( self ).install!
+      @machine.helpers.inject_into( self )
     end
+
     alias_method :o,         :object
     alias_method :obj,       :object
     alias_method :model,     :object
     alias_method :instance,  :object
 
-    alias_method :machine,       :machine
     alias_method :workflow,      :machine
     alias_method :state_machine, :machine
 
-    # the perister's field_name (a symbol)
-    def field_name
-      persister.field_name
-    end
+    #
+    # current state
+    #
 
-    # the current_state, as maintained by the persister.
+    # the current State
     def current_state
       persister.current_state
     end
-    alias_method :at,    :current_state
     alias_method :now,   :current_state
     alias_method :state, :current_state
 
@@ -66,54 +58,48 @@ module StateFu
     alias_method :state_name, :current_state_name
     alias_method :to_sym,     :current_state_name
 
-    # returns a list of StateFu::Events which can fire from the current_state
+    #
+    # events
+    #
+
+    # returns a list of Events which can fire from the current_state
     def events
-      machine.events.select {|e| e.complete? && e.from?( current_state ) }.extend EventArray
+      machine.events.select do |e|
+        e.can_transition_from? current_state
+      end.extend EventArray
     end
     alias_method :events_from_current_state,  :events
 
-    # the subset of events() whose requirements for firing are met
-    # (with the arguments supplied, if any)
-    def valid_events( *args )
-      return nil unless current_state
-      return [] unless current_state.exitable_by?( self, *args )
-      events.select {|e| e.fireable_by?( self, *args ) }.extend EventArray
-    end
-
     # the subset of events() whose requirements for firing are NOT met
     # (with the arguments supplied, if any)
     def invalid_events( *args )
       ( events - valid_events( *args ) ).extend StateArray
     end
 
-    def unmet_requirements_for( event, target )
-      raise NotImplementedError
+    # all states which can be reached from the current_state. 
+    # Does not check transition requirements, etc.
+    def next_states
+      events.map(&:targets).compact.flatten.uniq.extend StateArray
+    end
+
+    #
+    # transition validation
+    #
+
+    def transitions(opts={}) # .with(*args)
+      TransitionQuery.new(self, opts)
     end
 
-    # the counterpart to valid_events - the states we can arrive at in
-    # the firing of one event, taking into account event and state
-    # transition requirements
-    def valid_next_states( *args )
-      vt = valid_transitions( *args )
-      vt && vt.values.flatten.uniq.extend( StateArray )
+    def valid_transitions(*args)
+      transitions.valid.with(*args)
     end
 
-    #
-    def next_states
-      events.map(&:targets).compact.flatten.uniq.extend StateArray
+    def valid_next_states(*args)
+      transitions.with(*args).targets
     end
 
-    # returns a hash of { event => [states] } whose transition
-    # requirements are met
-    def valid_transitions( *args )
-      h  = {}
-      return nil unless ve = valid_events( *args )
-      ve.each do |e|
-        h[e] = e.targets.select do |s|
-          s.enterable_by?( self, *args )
-        end
-      end
-      h
+    def valid_events(*args)
+      transitions.with(*args).events
     end
 
     # initializes a new Transition to the given destination, with the
@@ -122,8 +108,7 @@ module StateFu
     # If a block is given, it yields the Transition or is executed in
     # its evaluation context, depending on the arity of the block.
     def transition( event_or_array, *args, &block )
-      event, target = parse_destination( event_or_array )
-      StateFu::Transition.new( self, event, target, *args, &block )
+      return transitions.with(*args, &block).find(event_or_array)
     end
     alias_method :fire,             :transition
     alias_method :fire_event,       :transition
@@ -131,130 +116,66 @@ module StateFu
     alias_method :trigger_event,    :transition
     alias_method :begin_transition, :transition
 
-    # return a MockTransition to nowhere and passes it the given
-    # *args. Useful for evaluating requirements in spec / test code.
-    def blank_mock_transition( *args, &block )
-      StateFu::MockTransition.new( self, nil, nil, *args, &block )
-    end
-
-    # return a MockTransition; otherwise the same as #transition
-    def mock_transition( event_or_array, *args, &block )
-      event, target = nil
-      event, target = parse_destination( event_or_array )
-      StateFu::MockTransition.new( self, event, target, *args, &block )
-    end
-
-    # sanitizes / extracts destination from *args for other methods.
-    #
-    # takes a single, simple (one target only) event,
-    # or an array of [event, target],
-    # or one of the above with symbols in place of the objects themselves.
-    def parse_destination( event_or_array )
-      case event_or_array
-      when StateFu::Event, Symbol
-        event  = event_or_array
-        target = nil
-      when Array
-        event, target = *event_or_array
-      end
-      x = event_or_array.is_a?( Array ) ? event_or_array.map(&:class) : event_or_array
-      raise ArgumentError.new( x.inspect ) unless
-        [StateFu::Event, Symbol  ].include?( event.class  ) &&
-        [StateFu::State, Symbol, NilClass].include?( target.class )
-      [event, target]
-    end
-
     # check that the event and target are valid (all requirements are
     # met) with the given (optional) arguments
     def fireable?( event_or_array, *args )
-      event, target = parse_destination( event_or_array )
       begin
-        t = transition( [event, target] )
+        return nil unless t = transition( event_or_array, *args )
         !! t.requirements_met?
       rescue InvalidTransition => e
         nil
       end
     end
-    alias_method :event?,             :fireable?
-    alias_method :event_fireable?,    :fireable?
-    alias_method :can_fire?,          :fireable?
-    alias_method :can_fire_event?,    :fireable?
-    alias_method :trigger?,           :fireable?
-    alias_method :triggerable?,       :fireable?
-    alias_method :can_trigger?,       :fireable?
-    alias_method :can_trigger_event?, :fireable?
-    alias_method :event_triggerable?, :fireable?
-    alias_method :transition?,        :fireable?
-    alias_method :can_transition?,    :fireable?
-    alias_method :transitionable?,    :fireable?
-
-    # construct an event transition and fire it
+
+    # construct an event transition and fire it, returning the transition.
+    # (which is == true if the transition completed successfully.)
     def fire!( event_or_array, *args, &block)
-      event, target = parse_destination( event_or_array )
-      t = transition( [event, target], *args, &block )
+      # TODO rather than die, try to find the next valid transition and fire that
+      t = transition(event_or_array, *args, &block )
       t.fire!
-      t
     end
-    alias_method :event!,    :fire!
     alias_method :trigger!,    :fire!
     alias_method :transition!, :fire!
 
-    # evaluate a requirement depending whether it's a method or proc,
-    # and its arity - see helper.rb (ContextualEval) for the smarts
-
-    # TODO - enable requirement block / method to know the target
-
-    def evaluate_requirement_with_args( name, *args )
-      t = blank_mock_transition( *args )
-      evaluate_named_proc_or_method( name, t )
-    end
-    # alias_method :evaluate_requirement, :evaluate_requirement_with_args
-
-    alias_method :evaluate_requirement_with_transition, :evaluate_named_proc_or_method
-
-    # if there is exactly one legal transition which can be fired with
+    #
+    # next_transition and friends: when there's exactly one valid move
+    #
+    
+    # if there is exactly one legal & valid transition which can be fired with
     # the given (optional) arguments, return it.
     def next_transition( *args, &block )
-      vts = valid_transitions( *args )
-      return nil if vts.nil?
-      next_transition_candidates = vts.select {|e, s| s.length == 1 }
-      if next_transition_candidates.length == 1
-        nt   = next_transition_candidates.first
-        evt  = nt[0]
-        targ = nt[1][0]
-        return transition( [ evt, targ], *args, &block )
-      end
+      transitions.with(*args, &block).next
+    end
+    
+    # as above but ignoring any transitions whose origin and target are the same
+    def next_transition_excluding_cycles( *args, &block )
+      transitions.not_cyclic.with(*args, &block).next
     end
 
     # if there is exactly one state reachable via a transition which
     # is valid with the given optional arguments, return it.
-    def next_state( *args )
-      nt = next_transition( *args )
-      nt && nt.target
+    def next_state(*args, &block)
+      transitions.with(*args, &block).next_state
     end
 
     # if there is exactly one event which is valid with the given
     # optional arguments, return it
     def next_event( *args )
-      nt = next_transition( *args )
-      nt && nt.event
+      transitions.with(*args, &block).next_event
     end
-
+    
     # if there is a next_transition, create, fire & return it
     # otherwise raise an InvalidTransition
     def next!( *args, &block )
       if t = next_transition( *args, &block )
         t.fire!
-        t
       else
-        vts = valid_transitions( *args )
-        n = vts && vts.length
-        raise InvalidTransition.
-          new( self, current_state, vts, "there are #{n} candidate transitions, need exactly 1")
+        raise TransitionNotFound.new( self, valid_transitions(*args), "Exactly 1 valid transition required.")
       end
     end
-    alias_method :next_state!, :next!
+    alias_method :next_transition!, :next!
     alias_method :next_event!, :next!
+    alias_method :next_state!, :next!
 
     # if there is a next_transition, return true / false depending on
     # whether its requirements are met
@@ -264,37 +185,45 @@ module StateFu
         t.requirements_met?
       end
     end
-    alias_method :next_state?, :next?
-    alias_method :next_event?, :next?
+    # alias_method :next_state?, :next?
+    # alias_method :next_event?, :next?
+
+    # Cyclic transitions (origin == target)
 
     # if there is one possible cyclical event, return a transition there
-    def cycle( *args, &block)
-      cycle_events = events.select {|e| e.target == current_state }
-      if cycle_events.length == 1
-        transition( cycle_events[0], *args, &block )
+    # otherwise, maybe we got an event name as an argument?
+    def cycle(event_or_array=nil, *args, &block)
+      if event_or_array.nil?
+        transitions.cyclic.with(*args, &block).singular ||
+          transitions.cyclic.with(*args, &block).valid.singular
+      else
+        transitions.cyclic.with(*args, &block).find(event_or_array)
       end
     end
 
-    # if there is a cycle() transition, fire and return it
+    # if there is a single possible cycle() transition, fire and return it
     # otherwise raise an InvalidTransition
-    def cycle!( *args, &block )
-      if t = cycle( *args, &block )
+    def cycle!(event_or_array=nil, *args, &block )
+      if t = cycle(event_or_array, *args, &block )
         t.fire!
         t
       else
-        err_msg = "Cannot cycle! unless there is exactly one event leading from the current state to itself"
-        raise InvalidTransition.new( self, current_state, current_state, err_msg )
+        raise TransitionNotFound.new( self, transitions.cyclic.with(*args,&block), "Cannot cycle! unless there is exactly one cyclic event")
       end
     end
 
     # if there is one possible cyclical event, evaluate its
     # requirements (true/false), else nil
-    def cycle?( *args )
-      if t = cycle( *args )
+    def cycle?(event_or_array=nil, *args )
+      if t = cycle(event_or_array, *args )
         t.requirements_met?
       end
     end
 
+    #
+    # misc
+    #
+
     # change the current state of the binding without any
     # requirements or other sanity checks, or any hooks firing.
     # Useful for test / spec scenarios, and abusing the framework.
@@ -308,12 +237,12 @@ module StateFu
         attrs = [[:current_state, state_name.inspect],
                  [:object_type , @object.class],
                  [:method_name , method_name.inspect],
-                 [:field_name  , persister.field_name.inspect],
+                 [:field_name  , field_name.inspect],
                  [:machine     , machine.inspect]].
         map {|x| x.join('=') }.join( " " ) + ' =>|'
     end
 
-    # let's be == the current_state_name as a symbol.
+    # let's be == (and hence ===) the current_state_name as a symbol.
     # a nice little convenience.
     def == other
       if other.respond_to?( :to_sym ) && current_state
@@ -323,5 +252,53 @@ module StateFu
       end
     end
 
+    # TODO better name
+    # is this a binding unique to a specific instance (not bound to a class)?
+    def singleton?
+      options[:singleton]
+    end
+
+    # SPECME DOCME OR KILLME 
+    def reload()
+      if persister.is_a?( Persistence::ActiveRecord )
+        object.reload
+      end
+      persister.reload
+      self
+    end
+
+    # This method is called from methods defined by MethodFactory. 
+    # You don't want to call it directly.
+    def _event_method(action, event, *args)
+      target_or_options = args.shift
+      options           = {}
+      case target_or_options
+      when Hash
+        options = target_or_options.symbolize_keys!
+        target  = target_or_options.delete[:to]
+      when Symbol, String
+        target  = target_or_options.to_sym
+      when nil
+        target  = nil
+      end
+
+      case action
+      when :get_transition
+        transition [event, target], *args, &lambda {|t| t.options = options}
+      when :query_transition
+        fireable?  [event, target], *args, &lambda {|t| t.options = options}
+      when :fire_transition
+        fire!      [event, target], *args, &lambda {|t| t.options = options}
+      else
+        raise ArgumentError.new(action)
+      end
+    end
+
+    #
+    # transition constructor
+    #
+    def new_transition(event, target, *args, &block)
+      Transition.new( self, event, target, *args, &block )
+    end
   end
 end

data/lib/state_fu/core_ext.rb

@@ -1,23 +1,91 @@
 require 'rubygems'
-# ruby1.9 style symbol comparability for ruby1.8
-class Symbol  # :nodoc:
-  unless instance_methods.include?(:'<=>')
-    def <=> other
-      self.to_s <=> other.to_s
-    end
-  end
-end
 
 # if ActiveSupport is absent, install a very small subset of it for
 # some convenience methods
-unless Object.const_defined?('ActiveSupport') # :nodoc:
+unless Object.const_defined?('ActiveSupport')  #:nodoc
   Dir[File.join(File.dirname( __FILE__), 'active_support_lite','**' )].sort.each do |lib|
     next unless File.file?( lib )
     require lib
   end
 
-  class Hash #:nodoc:
+  class Hash #:nodoc
     include ActiveSupport::CoreExtensions::Hash::Keys
   end
+end
+
+# ruby1.9 style symbol comparability for ruby1.8
+if RUBY_VERSION < "1.9"
+  class Symbol   #:nodoc
+    unless instance_methods.include?(:'<=>')
+      def <=> other
+        self.to_s <=> other.to_s
+      end
+    end
+  end
+end
+
+module ArrayToHash
+  def to_h
+    if RUBY_VERSION >= '1.8.7'
+      Hash[self]
+    else
+      inject({}) { |h, a| h[a.first] = a.last; h }
+    end
+  end
+end
+
+class Array
+  include ArrayToHash unless instance_methods.include?(:to_h)
+end
+
+class Object
+
+  def self.__define_method( method_name, &block )
+    self.class.class_eval do
+      define_method method_name, &block
+    end
+  end
+
+  def __define_singleton_method( method_name, &block )
+    (class << self; self; end).class_eval do
+      define_method method_name, &block
+    end
+  end
 
+
+  def with_methods_on(other)
+    (class << self; self; end).class_eval do
+      # we need some accounting to ensure that everything behaves itself when
+      # .with_methods_on is called more than once.
+      @_with_methods_on ||= []
+      if !@_with_methods_on.include?("method_missing_before_#{other.__id__}")
+        alias_method "method_missing_before_#{other.__id__}", :method_missing
+      end     
+      @_with_methods_on << "method_missing_before_#{other.__id__}"
+        
+      define_method :method_missing do |method_name, *args|
+        if _other.respond_to?(method_name, true)
+          _other.__send__( method_name, *args )
+        else
+          send "method_missing_before_#{other.__id__}", method_name, *args
+        end
+      end      
+    end
+
+    result = yield
+
+    (class << self; self; end).class_eval do
+      # heal the damage
+      if @_with_methods_on.pop != "method_missing_before_#{other.__id__}"
+        raise "there is no god"
+      end        
+      if !@_with_methods_on.include?("method_missing_before_#{other.__id__}")
+        alias_method :method_missing, "method_missing_before_#{other.__id__}"
+        undef_method "method_missing_before_#{other.__id__}"
+      end     
+    end
+
+    result
+  end # with_methods_on
 end
+