davidlee-state-fu 0.10.0 → 0.11.0

data/lib/state-fu.rb

@@ -68,6 +68,7 @@ require 'rubygems'
   'machine',
   'lathe',
   'method_factory',
+  'nil_transition',
   'binding',
   'persistence',
   'persistence/base',

data/lib/state_fu/binding.rb

@@ -27,10 +27,10 @@ module StateFu
       @machine.helpers.inject_into( self )
     end
 
-    alias_method :o,         :object
-    alias_method :obj,       :object
-    alias_method :model,     :object
-    alias_method :instance,  :object
+    alias_method :o,             :object
+    alias_method :obj,           :object
+    alias_method :model,         :object
+    alias_method :instance,      :object
 
     alias_method :workflow,      :machine
     alias_method :state_machine, :machine
@@ -70,12 +70,6 @@ module StateFu
     end
     alias_method :events_from_current_state,  :events
 
-    # 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
-
     # all states which can be reached from the current_state. 
     # Does not check transition requirements, etc.
     def next_states
@@ -95,12 +89,17 @@ module StateFu
     end
 
     def valid_next_states(*args)
-      transitions.with(*args).targets
+      valid_transitions(*args).targets
     end
 
     def valid_events(*args)
-      transitions.with(*args).events
+      valid_transitions(*args).events
+    end
+    
+    def invalid_events(*args)
+      (events - valid_events(*args)).extend StateArray
     end
+    
 
     # initializes a new Transition to the given destination, with the
     # given *args (to be passed to requirements and hooks).
@@ -110,33 +109,6 @@ module StateFu
     def transition( event_or_array, *args, &block )
       return transitions.with(*args, &block).find(event_or_array)
     end
-    alias_method :fire,             :transition
-    alias_method :fire_event,       :transition
-    alias_method :trigger,          :transition
-    alias_method :trigger_event,    :transition
-    alias_method :begin_transition, :transition
-
-    # check that the event and target are valid (all requirements are
-    # met) with the given (optional) arguments
-    def fireable?( event_or_array, *args )
-      begin
-        return nil unless t = transition( event_or_array, *args )
-        !! t.requirements_met?
-      rescue InvalidTransition => e
-        nil
-      end
-    end
-
-    # 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)
-      # TODO rather than die, try to find the next valid transition and fire that
-      t = transition(event_or_array, *args, &block )
-      t.fire!
-    end
-    alias_method :trigger!,    :fire!
-    alias_method :transition!, :fire!
-
     #
     # next_transition and friends: when there's exactly one valid move
     #
@@ -155,7 +127,7 @@ module StateFu
     # if there is exactly one state reachable via a transition which
     # is valid with the given optional arguments, return it.
     def next_state(*args, &block)
-      transitions.with(*args, &block).next_state
+      transitions.with(*args, &block).next_state 
     end
 
     # if there is exactly one event which is valid with the given
@@ -165,7 +137,7 @@ module StateFu
     end
     
     # if there is a next_transition, create, fire & return it
-    # otherwise raise an InvalidTransition
+    # otherwise raise an IllegalTransition
     def next!( *args, &block )
       if t = next_transition( *args, &block )
         t.fire!
@@ -176,7 +148,7 @@ module StateFu
     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
     # otherwise, nil
@@ -202,13 +174,12 @@ module StateFu
     end
 
     # if there is a single possible cycle() transition, fire and return it
-    # otherwise raise an InvalidTransition
+    # otherwise raise an IllegalTransition
     def cycle!(event_or_array=nil, *args, &block )
-      if t = cycle(event_or_array, *args, &block )
+      returning cycle(event_or_array, *args, &block ) do |t|
+        raise TransitionNotFound.new( self, transitions.cyclic.with(*args,&block), "Cannot cycle! unless there is exactly one cyclic event") \
+          if t.nil?
         t.fire!
-        t
-      else
-        raise TransitionNotFound.new( self, transitions.cyclic.with(*args,&block), "Cannot cycle! unless there is exactly one cyclic event")
       end
     end
 
@@ -233,13 +204,13 @@ module StateFu
 
     # display something sensible that doesn't take up the whole screen
     def inspect
-      '|<= ' + self.class.to_s + ' ' +
+      '<#' + self.class.to_s + ' ' +
         attrs = [[:current_state, state_name.inspect],
                  [:object_type , @object.class],
                  [:method_name , method_name.inspect],
                  [:field_name  , field_name.inspect],
-                 [:machine     , machine.inspect]].
-        map {|x| x.join('=') }.join( " " ) + ' =>|'
+                 [:machine     , machine.to_s]].
+        map {|x| x.join('=') }.join( " " ) + '>'
     end
 
     # let's be == (and hence ===) the current_state_name as a symbol.
@@ -267,31 +238,42 @@ module StateFu
       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
+    def inspect
+      s = self.to_s
+      s = s[0,s.length-1]
+      s << " object=#{object}" 
+      s << " current_state=#{current_state.to_sym.inspect rescue nil}" 
+      s << " events=#{events.map(&:to_sym).inspect rescue nil}" 
+      s << " machine=#{machine.to_s}" 
+      s << ">"
+      s
+    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
+    # These methods are called from methods defined by MethodFactory. 
+    # You probably don't want to call them directly.
+    
+    # event_name 
+    def find_transition(event, target=nil, *args)
+      target ||= args.last[:to].to_sym rescue nil      
+      query = transitions.for_event(event).to(target).with(*args)
+      query.find || query.valid.singular || NilTransition.new      
+      # transition = binding.transitions.with(*args).search([event, target])
+    end
+
+    # event_name?
+    def can_transition?(event, target=nil, *args)
+      begin
+        if t = find_transition(event, target, *args) 
+          t.valid?(*args)
+        end
+      rescue IllegalTransition, UnknownTarget
+        nil
+      end      
+    end
+
+    # event_name!
+    def fire_transition!(event, target=nil, *args)
+      find_transition(event, target, *args).fire!
     end
 
     #

data/lib/state_fu/exceptions.rb

@@ -92,14 +92,15 @@ module StateFu
   class TransitionHalted < TransitionError
   end
 
-  class InvalidTransition < TransitionError
-    attr_reader :valid_transitions
+  # deprecated?
+  # class Invalid Transition < TransitionError
+
+  class IllegalTransition < TransitionError
+    attr_reader :legal_transitions
 
     def initialize transition, message=nil, valid_transitions=nil, options={}
       @valid_transitions = valid_transitions
       super transition, message, options
-    end
-    
+    end    
   end
-
 end

data/lib/state_fu/method_factory.rb

@@ -6,63 +6,103 @@ module StateFu
   # complex events will be called as: event_name! :state, *args
   
   class MethodFactory
-
+    attr_accessor :method_definitions
+    attr_reader   :binding
+    
     # An instance of MethodFactory is created to define methods on a specific StateFu::Binding, and
-    # the object it is bound to.
-    #
-    # During the initializer, it will call define_event_methods_on(the binding), which installs
-    #
+    # on the object it is bound to.
+    
     def initialize( _binding )
-      # store @binding in a local variable so it's accessible within
-      # the closures below (for define_singleton_method ).
+      @binding                      = _binding  
+      simple_events, complex_events = @binding.machine.events.partition(&:simple?)
+      @method_definitions           = {}
+      
+      # simple event methods
+      # all arguments are passed into the transition / transition query
+      
+      simple_events.each do |event|
+        method_definitions["#{event.name}"]      = lambda do |*args| 
+          _binding.find_transition(event, event.target, *args) 
+        end
+        
+        method_definitions["can_#{event.name}?"] = lambda do |*args|
+          _binding.can_transition?(event, event.target, *args)
+        end
+
+        method_definitions["#{event.name}!"]     = lambda do |*args|
+          _binding.fire_transition!(event, event.target, *args)
+        end
+      end
+
+      # complex event methods
+      # the first argument is the target state
+      # any remaining arguments are passed into the transition / transition query
+
+      # object.event_name [:target], *arguments
+      #
+      # returns a new transition. Will raise an IllegalTransition if 
+      # it is not given arguments which result in a valid combination
+      # of event and target state being deducted.
+      #
+      # object.event_name [nil] suffices if the event has only one valid 
+      # target (ie only one transition which would not raise a 
+      # RequirementError if fired) 
+      
+      # object.event_name! [:target], *arguments
+      #
+      # as per the method above, except that it also fires the event
+
+      # object.can_event_name? [:target], *arguments
+      #
+      # tests that calling event_name or event_name! would not raise an error
+      # ie, the transition is legal and is valid with the arguments supplied
+      
+      complex_events.each do |event|
+        method_definitions["#{event.name}"]      = lambda do |target, *args|
+          _binding.find_transition(event, target, *args) 
+        end
+        
+        method_definitions["can_#{event.name}?"] = lambda do |target, *args|
+          begin 
+            t = _binding.find_transition(event, target, *args) 
+            t.valid?
+          rescue IllegalTransition
+            false
+          end
+        end
 
-      # i.e, we're embedding a reference to @binding inside the method
-      @binding = _binding      
-      @defs    = {}
+        method_definitions["#{event.name}!"]     = lambda do |target, *args|
+          _binding.fire_transition!(event, target, *args)
+        end
+      end
+      
+      # methods dedicated to a combination of event and target
+      # all arguments are passed into the transition / transition query
+      
+      (simple_events + complex_events).each do |event|
+        event.targets.each do |target|
+          method_definitions["#{event.name}_to_#{target.name}"]      = lambda do |*args| 
+            _binding.find_transition(event, target, *args) 
+          end
+
+          method_definitions["can_#{event.name}_to_#{target.name}?"] = lambda do |*args|
+            _binding.can_transition?(event, target, *args)
+          end
 
+          method_definitions["#{event.name}_to_#{target.name}!"]     = lambda do |*args|
+            _binding.fire_transition!(event, target, *args)
+          end          
+        end unless event.targets.nil?
+      end
+      
       @binding.machine.states.each do |state|
-        @defs[:"#{state.name}?"] = lambda { _binding.current_state.name == state.name }
+        method_definitions["#{state.name}?"] = lambda do 
+         _binding.current_state == state
+        end
       end
       
-      # method definitions for simple events (only one possible target)
-      @binding.machine.events.each do |event|
-        @defs[event.name]           = lambda \
-        {|*args| _binding._event_method :get_transition,   event, args.shift, *args }
-        @defs[:"can_#{event.name}?"] = lambda \
-          {|*args| _binding._event_method :query_transition, event, args.shift, *args }
-        @defs[:"#{event.name}!"]     = lambda \
-          {|*args| _binding._event_method :fire_transition,  event, args.shift, *args }
-        
-        #if !event.targets.blank? # && event.targets.length > 1
-        event.targets.each do |target_state|
-          method_name = "#{event.name}_to_#{target_state.name}"
-
-          # object.event_name [:target], *arguments
-          #
-          # returns a new transition. Will raise an InvalidTransition if 
-          # it is not given arguments which result in a valid combination
-          # of event and target state being deducted.
-          #
-          # object.event_name suffices without any arguments if the event 
-          # has only one possible target, or only one valid target for 
+    end 
           
-          # object.event_name! [:target], *arguments
-          #
-          # as per the method above, except that it also
-          
-          @defs[method_name.to_sym]     = lambda \
-            {|*args| _binding._event_method :get_transition,   event, target_state, *args }
-            
-          # object.event_name! [:]
-          @defs[:"can_#{method_name}?"] = lambda \
-            {|*args| _binding._event_method :query_transition, event, target_state, *args }
-            
-          @defs[:"#{method_name}!"]     = lambda \
-            {|*args| _binding._event_method :fire_transition,  event, target_state, *args }          
-            
-        end unless event.targets.nil?
-      end    
-    end
 
     #
     # Class Methods
@@ -163,7 +203,7 @@ module StateFu
     # as with simple event methods.
     #
     def define_event_methods_on( obj )
-      @defs.each do |method_name, method_body|
+      method_definitions.each do |method_name, method_body|
         define_singleton_method( obj, method_name, &method_body)
       end
     end # define_event_methods_on
@@ -196,7 +236,7 @@ module StateFu
       end
     end
     alias_method :define_singleton_method, :define_singleton_method
-
+    
   end # class MethodFactory
 end # module StateFu
 

data/lib/state_fu/nil_transition.rb

@@ -0,0 +1,49 @@
+module StateFu
+  
+  class NilTransition
+    def method_missing(method_name, *args, &block)
+      nil
+    end
+    
+    def blank?
+      true
+    end
+    
+    def nil?
+      true
+    end
+
+    # def <=> x
+    #   false <=> x
+    # end
+    #    
+    # def | x
+    #   false
+    # end
+    # 
+    # def & x
+    #   false
+    # end
+    # 
+    # def ^ x
+    #   false
+    # end
+    #
+    # def equal? x
+    #   x.is_a? NilTransition || x == nil
+    # end
+
+    def == x
+      case x
+      when false
+        true
+      when true
+        false
+      else
+        nil
+      end
+    end
+    
+  end
+  
+end

data/lib/state_fu/transition.rb

@@ -23,57 +23,67 @@ module StateFu
                 :current_hook_slot,
                 :current_hook 
 
-    attr_accessor :test_only
     alias_method :arguments, :args
     
     def initialize( binding, event, target=nil, *argument_list, &block )
-      # ensure event is a StateFu::Event
-      if event.is_a?(Symbol) && e = binding.machine.events[event]
-        event = e
-      end
-      raise( ArgumentError, "Not an event: #{event}" ) unless event.is_a? Event 
+      # ensure we have an Event
+      event = binding.machine.events[event] if event.is_a?(Symbol)
+      raise( UnknownTarget.new(self, "Not an event: #{event} #{self.inspect}" )) unless event.is_a? Event 
 
       @binding    = binding
       @machine    = binding.machine
       @object     = binding.object
       @origin     = binding.current_state
             
-      self.args= argument_list
-      apply!(argument_list, &block ) 
-      
       # ensure we have a target
       target = find_event_target( event, target ) || raise( UnknownTarget.new(self, "target cannot be determined: #{target.inspect} #{self.inspect}"))
 
       @target     = target
       @event      = event
       @errors     = []
-      @testing    = @options.delete(:test_only)
             
       if event.target_for_origin(origin) == target
-        # ...
+        # it's a "sequence"
+        # which is a hacky way of emulating simpler state machines with
+        # state-local events - and in which case, the targets & origins are
+        # valid. Quite likely this notion will be removed in time.
       else
         # ensure target is valid for the event
         unless event.targets.include? target 
-          raise InvalidTransition.new self, "Illegal target #{target} for #{event}" 
+          raise IllegalTransition.new self, "Illegal target #{target} for #{event}" 
         end
 
         # ensure current_state is a valid origin for the event
         unless event.origins.include? origin 
-          raise InvalidTransition.new( self, "Illegal event #{event.name} for current state #{binding.state_name}" )
+          raise IllegalTransition.new( self, "Illegal event #{event.name} for current state #{binding.state_name}" )
         end
       end 
       
       machine.inject_helpers_into( self )
+      self.args = argument_list            
+      apply!(argument_list, &block )       
     end
-
-    def options=(opts={})
-      @options = opts
+    
+    
+    def valid?(*args)
+      self.args = args unless args.empty?      
+      requirements_met?(true, true) # revalidate; exit on first failure
+    end
+    
+    def args=(args)      
+      @args = args.extend(TransitionArgsArray).init(self)    
+      apply!(args) if args.last.is_a?(Hash) unless options.nil?
+    end
+    
+    def with(*args)
+      self.args = args unless args.empty?
+      self
     end
 
-    def args=(a)      
-      @args = a.extend(TransitionArgsArray).init(self)    
-      apply!(a) if a.last.is_a?(Hash)
+    def with?(*args)
+      valid?
     end
+    alias_method :valid_with?, :with?
     
     #
     # Requirements
@@ -83,18 +93,20 @@ module StateFu
       origin.exit_requirements + target.entry_requirements + event.requirements
     end
 
-    def unmet_requirements(revalidate=false, fail_fast=false) # TODO
+    def unmet_requirements(revalidate=false, fail_fast=false) 
       if revalidate
-        return @unmet_requirements if @unmet_requirements
-      else
         @unmet_requirements = nil
+      else
+        return @unmet_requirements if @unmet_requirements
       end
-      result = requirements.uniq.inject([]) do |unmet, requirement|
-        next if fail_fast && !unmet.empty?
+      result = [requirements].flatten.uniq.inject([]) do |unmet, requirement|
         unmet << requirement unless evaluate(requirement)
+        break(unmet) if fail_fast && !unmet.empty?
         unmet
       end
-      @unmet_requirements = result if (!fail_fast || unmet_requirements.length <= 1)
+      raise self.inspect if result.nil?
+      # don't cache result if it might 
+      @unmet_requirements = result unless (fail_fast && unmet_requirements.length != 0)
       result
     end
     
@@ -104,25 +116,23 @@ module StateFu
 
     def unmet_requirement_messages(revalidate=false, fail_fast=false) # TODO
       unmet_requirements(revalidate, fail_fast).map do |requirement|
-        evaluate_requirement_message requirement 
+        evaluate_requirement_message(requirement, revalidate)
       end.extend MessageArray
     end
     alias_method :error_messages, :unmet_requirement_messages
-    
+
+    # return a hash of requirement_name => evaluated message
     def requirement_errors(revalidate=false, fail_fast=false)
       unmet_requirements(revalidate, fail_fast).
         map { |requirement| [requirement, evaluate_requirement_message(requirement)]}.
         to_h
     end
-
-    def first_unmet_requirement(revalidate=false)
-      unmet_requirements(revalidate, fail_fast=true)[0]
-    end
-
+    
     def first_unmet_requirement_message(revalidate=false)
-      unmet_requirement_messages(revalidate, fail_fast=true)[0]
+      evaluate_requirement_message(first_unmet_requirement(revalidate), revalidate)
     end
 
+    # raise a RequirementError unless all requirements are met.
     def check_requirements!(revalidate=false, fail_fast=true) # TODO
       raise RequirementError.new( self, unmet_requirement_messages.inspect ) unless requirements_met?(revalidate, fail_fast)
     end
@@ -130,7 +140,6 @@ module StateFu
     def requirements_met?(revalidate=false, fail_fast=false) # TODO
       unmet_requirements(revalidate, fail_fast).empty?
     end
-    alias_method :valid?, :requirements_met?
     
     #
     # Hooks
@@ -149,8 +158,6 @@ module StateFu
       evaluate hook 
     end
 
-
-
     #
     #
     #
@@ -166,9 +173,10 @@ module StateFu
     #
     
     # actually fire the transition
-    def fire!
+    def fire!(*arguments) # block? 
       raise TransitionAlreadyFired.new(self) if fired?
-      # return false if fired? # no infinite loops please
+      self.args = arguments unless arguments.empty?
+            
       check_requirements!
       @fired = true
       begin
@@ -218,14 +226,6 @@ module StateFu
       !!@fired
     end
 
-    def testing?
-      !!@test_only
-    end
-
-    def live?
-      !testing?
-    end
-
     def accepted?
       !!@accepted
     end
@@ -256,12 +256,6 @@ module StateFu
     alias_method :initial_state,  :origin
     alias_method :from,           :origin
 
-    alias_method :test?,          :testing?
-    alias_method :test_only?,     :testing?
-    alias_method :read_only?,     :testing?
-    alias_method :only_pretend?,  :testing?
-    alias_method :dry_run?,       :testing?
-
     # an accepted transition == true
     # an unaccepted transition == false
     # same for === (for case equality)
@@ -306,26 +300,28 @@ module StateFu
       executioner.evaluate(method_name_or_proc)
     end
 
-    def evaluate_requirement_message( name )
-      msg = machine.requirement_messages[name]
-      case msg
-      when String
-        msg
-      when nil
-        name
-      when Symbol, Proc
-        evaluate msg 
-      else
-        raise msg.class.to_s
-      end
+    def evaluate_requirement_message( name, revalidate=false)
+      @requirement_messages ||= {}
+      name   = name.to_sym
+      return @requirement_messages[name] if @requirement_messages[name] && !revalidate      
+      msg    = machine.requirement_messages[name.to_sym]
+      result =  case msg
+                when String
+                  msg
+                when Symbol, Proc
+                  evaluate msg 
+                else
+                  name
+                end
+      @requirement_messages[name] = result    
     end
-
+    
     def find_event_target( evt, tgt )
       case tgt
       when StateFu::State
         tgt
       when Symbol
-        binding && binding.machine.states[ tgt ] # || raise( tgt.inspect )
+        binding && binding.machine.states[ tgt ] 
       when NilClass
         evt.respond_to?(:target) && evt.target
       else

data/lib/state_fu/transition_query.rb

@@ -1,5 +1,5 @@
 module StateFu
-  class TransitionQuery #< Array
+  class TransitionQuery
     attr_accessor :binding, :options, :result, :args, :block
 
     def initialize(binding, options={})
@@ -23,20 +23,46 @@ module StateFu
     end
             
     #
-    #
+    # 
     #
     
-    def find( event_or_array )
-      event, target = parse_destination(event_or_array)
+    # same as find, except that if there is more than one target for the event
+    # and only one is valid, it will return that one.
+    # def search(destination=nil, &block)
+    #   # use the prepared event & target if none are supplied
+    #   event, target = destination.nil? ? [options[:event], options[:target]] : parse_destination(destination)
+    #   query         = for_event(event).to(target)
+    #   query.find || query.valid.singular || NilTransition.new
+    # end
+
+    # find a transition by event and optionally (optional if it can be inferred) target.
+    def find(destination=nil, &block)
+      # use the prepared event & target if none are supplied
+      event, target = destination.nil? ? [options[:event], options[:target]] : parse_destination(destination)
       _args, _block = @args, @block
-      returning binding.new_transition(event, target) do |t|
-        t.apply!(&_block) if _block
+      returning binding.new_transition(event, target) do |transition|
+        # return NilTransition.new if transition.nil?
+        transition.apply!(&_block) if _block
         if _args
-          t.args = _args 
+          transition.args = _args 
         end
       end        
     end
     
+    # def legal?(destination=nil, &block)
+    #   # use the prepared event & target if none are supplied
+    #   event, target = destination.nil? ? [options[:event], options[:target]] : parse_destination(destination)
+    #   begin
+    #     !!search(destination, &block)
+    #   rescue IllegalTransition
+    #     false
+    #   end
+    # end
+
+    #
+    #
+    #     
+    
     def cyclic
       @options.merge! :cyclic => true
       self
@@ -63,7 +89,7 @@ module StateFu
       self
     end
 
-    def for event
+    def for_event event
       @options.merge! :event => event
       self
     end
@@ -77,9 +103,14 @@ module StateFu
     #
     #
     
-    def singular
+    def only_one
       result.first if result.length == 1
     end
+    alias_method :singular, :only_one
+
+    def only_one?
+      !!singular
+    end
 
     def next
       @options[:cyclic] ||= false
@@ -118,7 +149,7 @@ module StateFu
 
     def with(*args, &block)
       @args  = args
-      @block = block
+      @block = block if block_given?
       self
     end
     
@@ -196,17 +227,19 @@ module StateFu
     # 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 Event, Symbol
-        event  = event_or_array
-        target = nil
-      when Array
-        event, target = *event_or_array
+    def parse_destination(destination)
+      event, target = destination
+
+      unless event.is_a?(Event)
+        event = binding.machine.events[event]
+      end
+      
+      unless target.is_a?(State)
+        target = binding.machine.states[target] rescue nil
       end
+        
       raise ArgumentError.new( [event,target].inspect ) unless
-        [Event, Symbol].include?(event.class) &&
-        [State, Symbol, NilClass].include?(target.class)
+        [[Event, State],[Event, NilClass]].include?( [event,target].map(&:class) )
       [event, target]
     end # parse_destination
 

data/spec/integration/active_record_persistence_spec.rb

@@ -142,7 +142,7 @@ describe "an ActiveRecord model with StateFu included:" do
         ex = ExampleRecord.create!( :name => "exemplar" )
         ex.state_fu.state.name.should == :initial
         ex.state_fu_field.should == 'initial'
-        t =  ex.state_fu.fire!( :change )
+        t = ex.state_fu.change!
         t.should be_accepted
         ex.state_fu.state.name.should == :final
         ex.state_fu_field.should == 'final'

data/spec/integration/example_02_string_spec.rb

@@ -28,7 +28,7 @@ describe String do
         klone = clone
         begin
           klone.shell.escape!
-        rescue StateFu::InvalidTransition
+        rescue StateFu::IllegalTransition
         end
         klone
       end
@@ -55,11 +55,11 @@ describe String do
     @str.should be_clean
   end
 
-  it "should raise an InvalidTransition if shell.escape! is called more than once" do
+  it "should raise an IllegalTransition if shell.escape! is called more than once" do
     @str.shell.escape!
     @str.shell.state_name.should == :clean
 
-    lambda { @str.shell.escape! }.should raise_error( StateFu::InvalidTransition )
+    lambda { @str.shell.escape! }.should raise_error( StateFu::IllegalTransition )
   end
 
   it "should modify the string when shell.escape is called" do

data/spec/integration/requirement_reflection_spec.rb

@@ -90,7 +90,7 @@ describe "Transition requirement reflection" do
       end # unmet requirements
 
       describe "given transition.unmet_requirement_messages" do
-        it "should return a list of nils" do
+        it "should return a list of symbols" do
           @obj.state_fu.catch_plane(:america).unmet_requirement_messages.should ==
             [:papers_in_order?, :money_for_bribe?, :no_turban?, :us_visa?, :no_arrest_warrant?]
         end

data/spec/integration/transition_spec.rb

@@ -88,15 +88,6 @@ describe StateFu::Transition do
           @t.should_not be_halted
         end
 
-        it "should not be testing" do
-          @t.should_not be_test
-          @t.should_not be_testing
-        end
-
-        it "should be live" do
-          @t.should be_live
-        end
-
         it "should not be accepted" do
           @t.should_not be_accepted
         end
@@ -143,15 +134,6 @@ describe StateFu::Transition do
           @t.should_not be_halted
         end
 
-        it "should not be testing" do
-          @t.should_not be_test
-          @t.should_not be_testing
-        end
-
-        it "should be live" do
-          @t.should be_live
-        end
-
         it "should be accepted" do
           @t.should be_accepted
         end
@@ -204,14 +186,8 @@ describe StateFu::Transition do
           trans.args.should    == []
         end
 
-        it "should be a live? transition, not a test?" do
-          trans = @obj.state_fu.transition( :transfer )
-          trans.should be_live
-          trans.should_not be_test
-        end
-
         it "should define any methods declared in a block given to .transition" do
-          trans = @obj.state_fu.transition( :transfer ) do
+          trans = @obj.state_fu.transition( :transfer ) do 
             def snoo
               return [self]
             end
@@ -232,25 +208,14 @@ describe StateFu::Transition do
 
       describe "state_fu.fire!( :transfer )" do
         it "should change the state when called" do
-          @obj.state_fu.should respond_to( :fire! )
+          @obj.state_fu.should respond_to( :fire_transition! )
           @obj.state_fu.state.should == @origin
-          @obj.state_fu.fire!( :transfer )
+          @obj.state_fu.fire_transition!( :transfer )
           @obj.state_fu.state.should == @target
         end
 
-        it "should define any methods declared in the .fire! block" do
-          trans = @obj.state_fu.fire!( :transfer ) do
-            def snoo
-              return [self]
-            end
-          end
-          trans.should be_kind_of( StateFu::Transition )
-          trans.should respond_to(:snoo)
-          trans.snoo.should == [trans]
-        end
-
         it "should return a transition object" do
-          @obj.state_fu.fire!( :transfer ).should be_kind_of( StateFu::Transition )
+          @obj.state_fu.fire_transition!( :transfer ).should be_kind_of( StateFu::Transition )
         end
 
       end # state_fu.fire!
@@ -310,14 +275,6 @@ describe StateFu::Transition do
           end
         end
 
-        describe "calling fire!( :transfer, :a, :b, :c => :d )" do
-          it "should set args and options on the transition" do
-            t = @obj.state_fu.fire!( :transfer, *@args )
-            t.args.should    == [ :a, :b, {:c =>:d} ]
-            t.options.should == { :c => :d }
-          end
-        end
-
         describe "calling next!( :a, :b, :c => :d )" do
           it "should set args and options on the transition" do
             t = @obj.state_fu.next!( *@args )
@@ -443,14 +400,14 @@ describe StateFu::Transition do
         end
       end  # state_fu.transition
 
-      describe "state_fu.fire!" do
+      describe "state_fu.fire_transition!" do
         it "should raise an StateFu::UnknownTarget unless a valid targets state is supplied" do
           lambda do
-            @obj.state_fu.fire!( :go )
+            @obj.state_fu.fire_transition!( :go )
           end.should raise_error( StateFu::UnknownTarget )
 
           lambda do
-            @obj.state_fu.fire!( [ :go, :awol ] )
+            @obj.state_fu.fire_transition!( [ :go, :awol ] )
           end.should raise_error( StateFu::UnknownTarget )
         end
       end # state_fu.fire!
@@ -797,7 +754,7 @@ describe StateFu::Transition do
         #stub( @binding ).ok? { false }
         @obj.ok = false
         lambda do
-          @obj.state_fu.fire!( :go )
+          @obj.state_fu.fire_transition!( :go )
         end.should raise_error( StateFu::RequirementError )
       end
 
@@ -1065,8 +1022,8 @@ describe StateFu::Transition do
           t.should be_nil
         end
 
-        it "should raise an InvalidTransition if next! is called" do
-          lambda { @binding.next! }.should raise_error( StateFu::InvalidTransition )
+        it "should raise an IllegalTransition if next! is called" do
+          lambda { @binding.next! }.should raise_error( StateFu::IllegalTransition )
         end
       end
 

data/spec/state_fu_spec.rb

@@ -22,7 +22,7 @@ describe "A door which opens and shuts:" do
       end
       
       def method_missing(method_name, *args, &block)
-        raise NoMethodError.new("I'm just a door!")
+        raise NoMethodError.new("I'm just a door!" )
       end
 
       machine do
@@ -181,6 +181,7 @@ describe "A door which opens and shuts:" do
 
     it "#can_shut? when the current state is open" do
       @door.current_state.should == :open
+      # @door.state_fu.valid_transitions.map(&:destination).inspect
       @door.can_shut?.should     == true
       @door.can_open?.should     == nil # not a valid transition from this state -> nil
     end
@@ -194,14 +195,14 @@ describe "A door which opens and shuts:" do
       @door.current_state.should == :closed
     end
     
-    it "raises a StateFu::InvalidTransition if #shut! is called when already :closed" do
+    it "raises a StateFu::IllegalTransition if #shut! is called when already :closed" do
       @door.current_state.should == :open
       @door.shut!.should be_true
       @door.current_state.should == :closed
       lambda do 
         t = @door.shut!
         t.origin.should == :open
-      end.should raise_error(StateFu::InvalidTransition)
+      end.should raise_error(StateFu::IllegalTransition)
     end
     
     it "raises StateFu::RequirementError if #open! is called when it is locked" do
@@ -250,9 +251,15 @@ describe "A door which opens and shuts:" do
         transition.target.should == :closed        
       end
     
-      it "returns a Transition on #slam" do
-        transition = @door.slam
-        should_be_an_unfired_transition_with_the_event_slam_from_open_to_closed( transition )
+      it "returns a Transition on #slam" do                  
+        @door.slam do |transition|
+          transition.should be_kind_of(StateFu::Transition)
+          transition.fired?.should == false
+          transition.current_state.should == :open
+          transition.event.should  == :slam
+          transition.origin.should == :open
+          transition.target.should == :closed        
+        end
       end
 
       it "returns a Transition on #state_fu.slam" do
@@ -396,10 +403,10 @@ describe "a simple machine, a heart which beats:" do
       @heart.heartbeats.should == [:thumpthump]
     end
 
-    it "raise an InvalidTransition if it tries to beat after it's stopped" do
+    it "raise an IllegalTransition if it tries to beat after it's stopped" do
       @heart.stop!
       @heart.current_state.should == :stopped
-      lambda { @heart.beat! }.should raise_error(StateFu::InvalidTransition)
+      lambda { @heart.beat! }.should raise_error(StateFu::IllegalTransition)
     end
 
     it "transition to :stopped on #next!" do
@@ -838,7 +845,7 @@ describe "sitting at a poker machine" do
         @pokie.pull_lever!
         @pokie.spinning?.should be_true
         @pokie.can_pull_lever?.should == nil
-        lambda{ @pokie.pull_lever! }.should raise_error(StateFu::InvalidTransition)
+        lambda{ @pokie.pull_lever! }.should raise_error(StateFu::IllegalTransition)
       end      
       
       it "makes a spinning sound while you wait" do

data/spec/units/binding_spec.rb

@@ -138,7 +138,7 @@ describe StateFu::Binding do
   describe "Instance methods" do
     before do
     end
-    describe "fireable?" do
+    describe "can_transition?" do
       before do
         reset!
         make_pristine_class("Klass")
@@ -147,7 +147,7 @@ describe StateFu::Binding do
         end
         @machine = Klass.state_fu_machine do
           state :snoo do
-            event :am_fireable, :to => :wizz do
+            event :fire, :to => :wizz do
               requires :tissue?
             end
           end
@@ -160,16 +160,15 @@ describe StateFu::Binding do
 
       describe "when called with arguments which would return a valid transition from .transition()" do
         it "should return true" do
-          @obj.state_fu.fireable?(:am_fireable).should == true
+          @obj.state_fu.can_transition?(:fire).should == true
         end
       end
 
-      describe "when called with arguments which would raise an InvalidTransition from .transition()" do
+      describe "when called with arguments which would raise an IllegalTransition from .transition()" do
         it "should return nil" do
           @obj.state_fu.name.should == :snoo
-          lambda { @obj.state_fu.transition(:not_fireable) }.should raise_error( StateFu::InvalidTransition )
-          lambda { @obj.state_fu.fireable?(:not_fireable) }.should_not raise_error( StateFu::InvalidTransition )
-          @obj.state_fu.fireable?(:not_fireable).should == nil
+          lambda { @obj.state_fu.can_transition?(:not_fire) }.should_not raise_error( StateFu::IllegalTransition )
+          @obj.state_fu.can_transition?(:not_fire).should == nil
         end
       end
 
@@ -178,10 +177,12 @@ describe StateFu::Binding do
         # This would make very little sense to someone trying to understand how to use the library.
         it "should pass the arguments to any requirements to determine transition availability" do
           pending
-          mock(@obj).tissue?() do
-            current_transition.should be_kind_of(StateFu::Transition)
+          t = nil
+          mock(@obj).tissue?(anything) do
+            # current_transition.should be_kind_of(StateFu::Transition)
+            t << current_transition
           end #{|tr| tr.args.should == [:a,:b] }
-          @obj.state_fu.am_fireable?(:a, :b)
+          @obj.state_fu.can_fire?(:a, :b)
         end
       end
 

data/spec/units/exceptions_spec.rb

@@ -46,7 +46,7 @@ describe StateFu::TransitionHalted do
   end
 end
 
-describe StateFu::InvalidTransition do
+describe StateFu::IllegalTransition do
   before do
     @binding = Object.new
     @origin  = Object.new
@@ -55,24 +55,24 @@ describe StateFu::InvalidTransition do
   end
 
   describe "constructor" do
-    it "should create an InvalidTransition given a binding, event, origin & target" do
+    it "should create an IllegalTransition given a binding, event, origin & target" do
       pending
-      e = StateFu::InvalidTransition.new( @binding, @event, @origin, @target )
-      e.should be_kind_of( StateFu::InvalidTransition )
-      e.message.should == StateFu::InvalidTransition::DEFAULT_MESSAGE
+      e = StateFu::IllegalTransition.new( @binding, @event, @origin, @target )
+      e.should be_kind_of( StateFu::IllegalTransition )
+      e.message.should == StateFu::IllegalTransition::DEFAULT_MESSAGE
     end
 
     it "should allow a custom message" do
       pending
       msg = 'helo'
-      e = StateFu::InvalidTransition.new( @binding, @event, @origin, @target, msg )
-      e.should be_kind_of( StateFu::InvalidTransition )
+      e = StateFu::IllegalTransition.new( @binding, @event, @origin, @target, msg )
+      e.should be_kind_of( StateFu::IllegalTransition )
       e.message.should == msg
     end
 
     it "should allow access to the binding, event, origin, and target" do
       pending
-      e = StateFu::InvalidTransition.new( @binding, @event, @origin, @target )
+      e = StateFu::IllegalTransition.new( @binding, @event, @origin, @target )
       e.binding.should == @binding
       e.event.should   == @event
       e.origin.should  == @origin

data/spec/units/method_factory_spec.rb

@@ -61,8 +61,8 @@ describe StateFu::MethodFactory do
         end
 
         it "should call binding.fire!( :simple_event ... ) with any specified args" do
-          mock.instance_of( StateFu::Binding ).fire!( anything, :a, :b, {:c => "d"} )
-          t = @obj.simple_event!( nil, :a, :b, :c => "d" )
+          mock.instance_of( StateFu::Binding ).fire_transition!( is_a(StateFu::Event), is_a(StateFu::State), :aa, :bb, {:cc => "dd"} )
+          t = @obj.simple_event!( :aa, :bb, :cc => "dd" )
         end
 
         it "should fire the transition" do
@@ -107,7 +107,7 @@ describe StateFu::MethodFactory do
           end
 
           it "should add any arguments / options it is called with to the transition" do
-            t = @binding.simple_event nil, :a, :b, :c, {'d' => 'e'}
+            t = @binding.simple_event :a, :b, :c, {'d' => 'e'}
             #t.should be_kind_of( StateFu::Transition )
             #t.target.should  == @machine.states[:targ]
             #t.event.should   == @machine.events[:simple_event]
@@ -116,21 +116,21 @@ describe StateFu::MethodFactory do
           end
         end # transition builder
 
-        describe "method which tests if the event is fireable?" do
+        describe "method which tests if the event is can_transition?" do
           it "should have the name of the event suffixed with ?" do
             @binding.should respond_to(:can_simple_event?)
           end
 
-          it "should be true when the binding says it\'s fireable?" do
-            @binding.fireable?( :simple_event ).should == true
+          it "should be true when the binding says it\'s can_transition?" do
+            @binding.can_transition?( :simple_event ).should == true
             @binding.can_simple_event?.should == true
           end
 
-          it "should be false when the binding says it\'s not fireable?" do
-            mock( @binding ).fireable?( anything ) { false }
+          it "should be false when the binding says it\'s not can_transition?" do
+            mock( @binding ).can_transition?( is_a(StateFu::Event), is_a(StateFu::State) ) { false }
             @binding.can_simple_event?.should == false
           end
-        end # fireable?
+        end # can_transition?
 
         describe "bang (!) method which creates, fires and returns a transition" do
           it "should have the name of the event suffixed with a bang (!)" do
@@ -144,7 +144,7 @@ describe StateFu::MethodFactory do
           end
 
           it "should pass any arguments to the transition as args / options" do
-            t = @binding.simple_event!( nil, :a, :b, {'c' => :d } )
+            t = @binding.simple_event!( :a, :b, {'c' => :d } )
             t.should be_kind_of( StateFu::Transition )
             t.args.should    == [:a, :b, {'c' => :d} ]
             t.options.should == { :c => :d }
@@ -178,15 +178,15 @@ describe StateFu::MethodFactory do
           end
 
           it "should raise an error if called without any arguments" do
-            lambda { @binding.complex_event() }.should raise_error( StateFu::UnknownTarget )
+            lambda { @binding.complex_event() }.should raise_error( ArgumentError )
           end
 
           it "should raise an ArgumentError if called with a nonexistent target state" do
             lambda { @binding.complex_event(:nonexistent) }.should raise_error( StateFu::UnknownTarget )
           end
 
-          it "should raise an InvalidTransition if called with an invalid target state" do
-            lambda { @binding.complex_event(:orphan)      }.should raise_error( StateFu::InvalidTransition )
+          it "should raise an IllegalTransition if called with an invalid target state" do
+            lambda { @binding.complex_event(:orphan)      }.should raise_error( StateFu::IllegalTransition )
           end
 
           it "should return a transition to the specified state if supplied a valid state" do
@@ -204,7 +204,7 @@ describe StateFu::MethodFactory do
           end
         end # transition builder
 
-        describe "method which tests if the event is fireable?" do
+        describe "method which tests if the event is can_transition?" do
           it "should have the name of the event suffixed with ?" do
             @binding.should respond_to(:can_complex_event?)
           end
@@ -212,20 +212,15 @@ describe StateFu::MethodFactory do
           it "should require a valid state name" do
             lambda { @binding.can_complex_event?(:nonexistent) }.should raise_error( StateFu::UnknownTarget )
             lambda { @binding.can_complex_event?(:orphan) }.should_not  raise_error()
-            @binding.can_complex_event?(:orphan).should == nil
+            @binding.can_complex_event?(:orphan).should == false
             lambda { @binding.can_complex_event?(:x) }.should_not       raise_error
           end
 
-          it "should be true when the binding says the event is fireable? " do
-            @binding.fireable?( [:complex_event, :x] ).should == true
+          it "should be true when the binding says the event is can_transition? " do
+            @binding.can_transition?( :complex_event, :x ).should == true
             @binding.can_complex_event?(:x).should == true
           end
-
-          it "should be false when the binding says the event is not fireable?" do
-            mock( @binding ).fireable?( anything ) { false }
-            @binding.can_complex_event?(:x).should == false
-          end
-        end # fireable?
+        end # can_transition?
 
         describe "bang (!) method which creates, fires and returns a transition" do
           it "should have the name of the event suffixed with a bang (!)" do
@@ -234,7 +229,7 @@ describe StateFu::MethodFactory do
 
           it "should require a valid state name" do
             lambda { @binding.complex_event!(:nonexistent) }.should raise_error( StateFu::UnknownTarget )
-            lambda { @binding.complex_event!(:orphan) }.should      raise_error( StateFu::InvalidTransition )
+            lambda { @binding.complex_event!(:orphan) }.should      raise_error( StateFu::IllegalTransition )
             lambda { @binding.complex_event!(:x) }.should_not       raise_error
           end
 
@@ -350,7 +345,7 @@ describe StateFu::MethodFactory do
             end
 
             describe "next_state!" do
-              it "should raise_error( InvalidTransition )" do
+              it "should raise_error( IllegalTransition )" do
                 lambda { @binding.next_state! }.should raise_error( StateFu::TransitionNotFound )
               end
             end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: davidlee-state-fu
 version: !ruby/object:Gem::Version 
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors: 
 - David Lee
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-08-25 00:00:00 -07:00
+date: 2009-08-26 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -58,6 +58,7 @@ files:
 - lib/state_fu/machine.rb
 - lib/state_fu/method_factory.rb
 - lib/state_fu/methodical.rb
+- lib/state_fu/nil_transition.rb
 - lib/state_fu/persistence.rb
 - lib/state_fu/persistence/active_record.rb
 - lib/state_fu/persistence/attribute.rb
@@ -110,7 +111,6 @@ files:
 - README.textile
 has_rdoc: false
 homepage: http://github.com/davidlee/state-fu
-licenses: 
 post_install_message: 
 rdoc_options: 
 - --charset=UTF-8
@@ -131,7 +131,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: state-fu
-rubygems_version: 1.3.5
+rubygems_version: 1.2.0
 signing_key: 
 specification_version: 3
 summary: A rich library for state-oriented programming with state machines / workflows