davidlee-state-fu 0.3.1 → 0.10.0

data/lib/state_fu/event.rb

@@ -1,14 +1,54 @@
 module StateFu
   class Event < StateFu::Sprocket
 
-    attr_reader :origins, :targets, :requirements
+    attr_reader :origins, :targets, :requirements, :sequence
 
     # called by Lathe when a new event is constructed
     def initialize(machine, name, options={})
-      @requirements = [].extend ArrayWithSymbolAccessor
+      @requirements = [].extend ArrayWithSymbolAccessor    
+      @sequence     = {}
       super( machine, name, options )
     end
 
+    # 
+    # build a hash of target => [origins]
+    #
+    def add_to_sequence origin_states, target_state
+      origin_states = [origin_states].flatten
+      existing = origin_states.select {|s| target_for_origin(s) }
+      raise ArgumentError.new unless existing.empty? && !targets       
+      @sequence[target_state] ||= []
+      [origin_states].flatten.each do |o|
+        @sequence[target_state] << o
+      end
+      @sequence
+    end
+    
+    def target_for_origin origin_state
+      raise ArgumentError.new if origin_state.nil?
+      name = sequence.detect do |k,v| 
+        v.include?(origin_state.to_sym)
+      end[0] rescue nil
+      machine.states[name] if name
+      # if t
+      #   puts t.inspect + " <============================" if t
+      #   puts "======================"
+      #   puts origin_state.class
+      #   puts origin_state.name rescue origin_state.inspect
+      # end
+      # machine.states[t.first] if t
+    end
+    
+    def can_transition_from?(origin_state) 
+      ( origins && origins.include?(origin_state.to_sym) && !targets.blank?) ||
+        target_for_origin(origin_state)
+    end
+    
+    def sequence?
+      !sequence.empty?
+    end
+    
+    
     # the names of all possible origin states
     def origin_names
       origins ? origins.map(&:to_sym) : nil
@@ -26,26 +66,11 @@ module StateFu
 
     # tests if a state or state name is in the list of origins
     def from?( state )
-      origin_names.include?( state.to_sym )
+      origin_names.include?( state.to_sym ) || target_for_origin(state)
     end
-
-    # internal method which accumulates states into an instance
-    # variable with successive invocations.
-    # ensures that calling #from multiple times adds to, rather than
-    # clobbering, the list of origins / targets.
-    def update_state_collection( ivar_name, *args)
-      new_states = if [args].flatten == [:ALL]
-            machine.states
-          else
-            machine.find_or_create_states_by_name( *args.flatten )
-          end
-      unless new_states.is_a?( Array )
-        new_states = [new_states]
-      end
-      existing  = instance_variable_get( ivar_name )
-      # return existing if new_states.empty?
-      new_value = ((existing || [] ) + new_states).flatten.compact.uniq.extend( StateArray )
-      instance_variable_set( ivar_name, new_value )
+    
+    def cycle?
+      origin && origin == target
     end
 
     # *adds to* the origin states given a list of symbols / States
@@ -58,17 +83,6 @@ module StateFu
       update_state_collection( '@targets', *args )
     end
 
-
-    # used internally
-    #
-    # <tt>complete?(:origins) # do we have origins?<tt>
-    # <tt>complete?           # do we have origins and targets?<tt>
-    def complete?( field = nil )
-      ( field && [field] ||  [:origins, :targets] ).
-        map{ |s| send(s) }.
-        all?{ |f| !(f.nil? || f.empty?) }
-    end
-
     # if there is a single state in #origins, returns it
     def origin
       origins && origins.length == 1 && origins[0] || nil
@@ -83,7 +97,22 @@ module StateFu
     # origins. It's simple because it can be triggered without
     # supplying a target name - ie, <tt>go!<tt> vs <tt>go!(:home)<tt>
     def simple?
-      !! ( origins && target )
+      !! ( origins && target || sequence? )
+    end
+
+    def fireable?( transition )
+      transition.valid?(true)
+    end
+
+
+    #
+    # Lathe methods
+    #
+
+    # adds an event requirement.
+    # DOCME // TODO - can this be removed?
+    def requires( *args, &block )
+      lathe.requires( *args, &block )
     end
 
     # generally called from a Lathe. Sets the origin(s) and optionally
@@ -93,17 +122,17 @@ module StateFu
     def from *args
       options = args.extract_options!.symbolize_keys!
       args.flatten!
-      to = options.delete(:to)
+      to = options.delete(:to) || options.delete(:transitions_to)
       if args.empty? && !to
         if options.length == 1
-          self.origins= options.keys[0]
-          self.targets= options.values[0]
+          self.origins = options.keys[0]
+          self.targets = options.values[0]
         else
           raise options.inspect
         end
       else
-        self.origins= *args
-        self.targets= to unless to.nil?
+        self.origins = *args
+        self.targets = to unless to.nil?
       end
     end
 
@@ -115,18 +144,53 @@ module StateFu
       self.targets= *args
     end
 
-    # is the event legal for the given binding, with the given
-    # (optional) arguments?
-    def fireable_by?( binding, *args )
-      requirements.reject do |r|
-        binding.evaluate_requirement_with_args( r, *args )
-      end.empty?
+    alias_method :transitions_to,   :to
+    alias_method :transitions_from, :from
+
+    #
+    # misc
+    # 
+    
+    # display nice and short
+    def inspect
+      s = self.to_s
+      s = s[0,s.length-1]
+      display_hooks = hooks.dup
+      display_hooks.each do |k,v|
+        display_hooks.delete(k) if v.empty?
+      end
+      unless display_hooks.empty?
+        s << " hooks=#{display_hooks.inspect}"
+      end
+      unless requirements.empty?
+        s << " requirements=#{requirements.inspect}"
+      end
+      s << " targets=#{targets.map(&:to_sym).inspect}" if targets
+      s << " origins=#{origins.map(&:to_sym).inspect}" if origins
+      s << ">"
+      s
     end
 
-    # adds an event requirement.
-    # TODO MOREDOC
-    def requires( *args, &block )
-      lathe.requires( *args, &block )
+    private
+
+    # internal method which accumulates states into an instance
+    # variable with successive invocations.
+    # ensures that calling #from multiple times adds to, rather than
+    # clobbering, the list of origins / targets.
+    def update_state_collection( ivar_name, *args)
+      raise ArgumentError if sequence?      
+      new_states = if [args].flatten == [:ALL]
+            machine.states
+          else
+            machine.find_or_create_states_by_name( *args.flatten )
+          end
+      unless new_states.is_a?( Array )
+        new_states = [new_states]
+      end
+      existing  = instance_variable_get( ivar_name )
+      # return existing if new_states.empty?
+      new_value = ((existing || [] ) + new_states).flatten.compact.uniq.extend( StateArray )
+      instance_variable_set( ivar_name, new_value )
     end
 
   end

data/lib/state_fu/exceptions.rb

@@ -1,59 +1,105 @@
 module StateFu
 
-  class Exception < ::Exception
+  class MagicMethodError < NoMethodError
+  end
+
+  class Error < ::StandardError
     attr_reader :binding, :options
+
+    def initialize binding, message=nil, options={}
+      @binding = binding
+      @options = options
+      super message
+    end
+    
   end
 
-  class RequirementError < Exception
-    attr_reader :transition
-    DEFAULT_MESSAGE = "The transition was halted"
+  class TransitionNotFound < Error
+    attr_reader :valid_transitions
+    attr_reader :valid_destinations    
+    DEFAULT_MESSAGE = "Transition could not be determined"
+    
+    def initialize(binding, valid_transitions, message=DEFAULT_MESSAGE, options={})
+      @valid_transitions  = valid_transitions
+      @valid_destinations = valid_transitions.map(&:destination)
+      super(binding, message, options)
+    end
 
-    # SPECME
-    def unmet_requirements
-      transition.unmet_requirements
+    def inspect
+      "<#{self.class.to_s} #{message} available=[#{valid_destinations.inspect}]>"
     end
+    
+  end
+  
+  class TransitionError < Error
+    # TODO default message
+    attr_reader :transition
 
-    def initialize( transition, message=DEFAULT_MESSAGE, options={})
-      @transition = transition
-      @options    = options
-      super( message )
+    def initialize transition, message=nil, options={}
+      raise caller.inspect unless transition.is_a?(Transition)
+      @transition = transition 
+      super transition.binding, message, options
     end
 
+    delegate :origin, :to => :transition
+    delegate :target, :to => :transition
+    delegate :event,  :to => :transition    
+    delegate :args,   :to => :transition    
+
+    # TODO capture these on initialization
+    delegate :unmet_requirements,         :to => :transition        
+    delegate :unmet_requirement_messages, :to => :transition            
+    delegate :requirement_errors,         :to => :transition            
+
     def inspect
-      "<StateFu::RequirementError #{message} #{@transition.origin.name}=[#{@transition.event.name}]=>#{transition.target.name}"
+      origin_name = origin && origin.name
+      target_name = target && target.name
+      event_name  = event  && event.name  
+      "<#{self.class.to_s} #{message} #{origin_name.inspect}=[#{event_name.inspect}]=>#{target_name.inspect}>"
     end
   end
 
-  class TransitionHalted < Exception
-    attr_reader :transition
+  class UnknownTarget < TransitionError
+  end
 
-    DEFAULT_MESSAGE = "The transition was halted"
+  class TransitionAlreadyFired < TransitionError
+  end
+  
+  class RequirementError < TransitionError
+    include Enumerable 
 
-    def initialize( transition, message=DEFAULT_MESSAGE, options={})
-      @transition = transition
-      @options    = options
-      super( message )
+    delegate :each,   :to => :to_h
+    delegate :length, :to => :to_h
+    delegate :empty?, :to => :to_h
+        
+    def to_a
+      unmet_requirement_messages
+    end
+    
+    def to_h
+      requirement_errors
+    end
+    
+    def to_s
+      inspect
+    end
+    
+    def inspect
+      "<#{self.class.to_s}::#{__id__} :#{transition.origin.to_sym}-[#{transition.event.to_sym}]->:#{transition.target.to_sym} unmet_requirements=#{to_a.inspect}>"
     end
   end
 
-  class InvalidTransition < Exception
-    attr_reader :binding, :origin, :target, :event, :args
+  class TransitionHalted < TransitionError
+  end
 
-    DEFAULT_MESSAGE = "An invalid transition was attempted"
+  class InvalidTransition < TransitionError
+    attr_reader :valid_transitions
 
-    def initialize( binding,
-                    event,
-                    origin,
-                    target,
-                    message=DEFAULT_MESSAGE,
-                    options={})
-      @binding = binding
-      @event   = event
-      @origin  = origin
-      @target  = target
-      @options = options
-      super( message )
+    def initialize transition, message=nil, valid_transitions=nil, options={}
+      @valid_transitions = valid_transitions
+      super transition, message, options
     end
+    
   end
 
 end

data/lib/state_fu/executioner.rb

@@ -0,0 +1,149 @@
+module StateFu
+  #
+  # delegator class for evaluation methods / procs in the context of
+  # your object.
+  #
+  
+  # There's a bug in ruby 1.8.x where lambda {}.arity == -1 instead of 0
+  # To get around this, turn it into a proc if conditions are dangerous.
+  def self.get_effective_arity
+    if RUBY_VERSION[0,3] == "1.8" && proc.arity == -1
+      proc.to_proc.arity
+    else
+      proc.arity
+    end    
+  end
+  
+  class Executioner
+
+    # give us a blank slate
+    # instance_methods.each { |m| undef_method m unless m =~ /(^__|^self|^nil\?$|^send$|proxy_|^object_id|^respond_to\?|^instance_exec|^instance_eval|^method$)/ }
+
+    def initialize transition, &block
+      @transition     = transition
+      @__target__     = transition.object
+      @__self___      = self
+      yield self if block_given?
+      # forces method_missing to snap back to its pre-state-fu condition:
+      # @__target__.initialize_state_fu!
+      self
+    end
+
+    # delegate :self, :to => :__target__
+
+    delegate :origin,  :to => :transition, :prefix => true # transition_origin
+    delegate :target,  :to => :transition, :prefix => true # transition_target
+    delegate :event,   :to => :transition, :prefix => true # transition_event
+
+    delegate :halt!,   :to => :transition
+    delegate :args,    :to => :transition
+    delegate :options, :to => :transition
+
+    def binding
+      transition.binding
+    end
+
+    attr_reader :transition, :__target__, :__self__
+
+    alias_method :t,                  :transition
+    alias_method :current_transition, :transition
+    alias_method :context,            :transition
+    alias_method :ctx,                :transition
+
+    alias_method :arguments,            :args
+    alias_method :transition_arguments, :args
+
+    # delegate :machine, :to => :binding
+    #delegate :states,  :to => :machine
+
+
+    def machine 
+      binding.machine
+    end
+    
+    def states
+      # puts binding
+      # puts binding.instance_eval() { @machine }
+      # puts binding.machine
+      # puts binding.machine.states.names
+      # puts machine
+      # puts machine.states
+      # machine.states
+    end
+    # delegate :machine, :to => :transition
+
+    def evaluate_with_arguments method_name_or_proc, *arguments
+      if method_name_or_proc.is_a?(Proc) && meth = method_name_or_proc
+      elsif meth = transition.machine.named_procs[method_name_or_proc]
+      elsif respond_to?( method_name_or_proc) && meth = method(method_name_or_proc)        
+      elsif method_name_or_proc.to_s =~ /^not?_(.*)$/
+        # special case: prefix a method with no_ or not_ and get the 
+        # boolean opposite of its evaluation result
+        return !( evaluate_with_arguments $1, *args )
+      else
+        raise NoMethodError.new( "undefined method_name `#{method_name_or_proc.to_s}' for \"#{__target__}\":#{__target__.class.to_s}" )
+      end      
+
+      if arguments.length < meth.arity.abs && meth.arity != -1
+        # ensure we don't have too few arguments
+        raise ArgumentError.new([meth.arity, arguments.length].inspect) 
+      else
+        # ensure we don't pass too many arguments
+        arguments = arguments[0, meth.arity.abs]
+      end
+      
+      # execute it!
+      __target__.with_methods_on(self) do
+        self.instance_exec *arguments, &meth
+      end
+    end
+
+    def evaluate method_name_or_proc
+      arguments = [transition, args, __target__]
+      evaluate_with_arguments(method_name_or_proc, *arguments)
+    end
+
+    alias_method :executioner_respond_to?, :respond_to?
+
+    def respond_to? method_name, include_private = false
+      executioner_respond_to?(method_name, include_private) ||
+      __target__.__send__( :respond_to?, method_name, include_private )
+    end
+
+    alias_method :executioner_method, :method
+    def method method_name
+      begin
+        executioner_method(method_name)
+      rescue NameError
+        __target__.__send__ :method, method_name
+      end
+    end
+
+    private
+
+    # Forwards any missing method call to the \target.
+    # TODO / FIXME / NOTE: we don't (can't ?) handle block arguments ...    
+    def method_missing(method_name, *args)
+      if __target__.respond_to?(method_name, true)
+        begin
+          meth = __target__.__send__ :method, method_name
+        rescue NameError
+          super
+        end
+        __target__.instance_exec( *args, &meth)
+      else # let's hope it's a named proc
+        evaluate_with_arguments(method_name, *args)
+      end
+      
+    end
+
+#    # Forwards any missing method call to the \target.
+#    def self.const_missing(const_name)
+#      unless __target__.class.const_defined?(const_name, true)
+#        super(const_name)
+#      end
+#      __target__.class.const_get(const_name)
+#    end
+#
+  end
+end

data/lib/state_fu/has_options.rb

@@ -0,0 +1,16 @@
+module HasOptions
+  
+  def self.included(base)
+    base.class_eval do
+      attr_accessor :options
+    end
+  end
+  
+  def []v
+    options[v]
+  end
+
+  def []=v,k
+    options[v]=k
+  end
+end

data/lib/state_fu/hooks.rb

@@ -2,29 +2,34 @@ module StateFu
 
   # TODO document structure / sequence of hooks elsewhere
 
-  module Hooks # :nodoc:
+  module Hooks  #:nodoc
 
-    ALL_HOOKS = [[:event,  :before],   # good place to start a transaction, etc
-                 [:origin, :exit],     # say goodbye!
-                 [:event,  :execute],  # do stuff here, as a rule of thumb
-                 [:target, :entry],    # last chance to halt!
-                 [:event,  :after],    # clean up all the mess
-                 [:target, :accepted]] # state changed. Quicksave!
+    ALL_HOOKS = [[:machine, :before_all], # global before. prepare for any transition
+                 [:event,   :before],     # prepare for the event
+                 [:origin,  :exit],       # say goodbye!
+                 [:event,   :execute],    # do stuff here for the event
+                 [:target,  :entry],      # entry point. last chance to halt!
+                 [:event,   :after],      # clean up after transition 
+                 [:target,  :accepted],   # state is changed. Do something about it.
+                 [:machine, :after_all]]  # global after. close up shop.
 
-    EVENT_HOOKS = ALL_HOOKS.select { |type, name| type == :event }
-    STATE_HOOKS = ALL_HOOKS - EVENT_HOOKS
-    HOOK_NAMES  = ALL_HOOKS.map {|a| a[1] }
+    EVENT_HOOKS   = ALL_HOOKS.select { |type, name| type == :event }
+    STATE_HOOKS   = ALL_HOOKS.select { |type, name| [:origin, :target].include?(type) }
+    MACHINE_HOOKS = ALL_HOOKS.select { |type, name| type == :machine }
+    HOOK_NAMES    = ALL_HOOKS.map(&:last)
 
     # just turn the above into what each class needs
     # and make it into a nice hash: { :name =>[ hook, ... ], ... }
     def self.for( me )
-      x = if    me.is_a?( StateFu::State ); STATE_HOOKS
-          elsif me.is_a?( StateFu::Event ); EVENT_HOOKS
-          else  {}
+      x = if    me.is_a?(State);   STATE_HOOKS
+          elsif me.is_a?(Event);   EVENT_HOOKS
+          elsif me.is_a?(Machine); MACHINE_HOOKS
+          elsif me.is_a?(Sprocket); [] # let specs pass
+          else  raise me
           end.
-        map { |_,name| [name, [].extend( StateFu::OrderedHash )] }
-      hash = x.inject({}) {|h, a| h[a[0]] = a[1] ; h}
-      hash.extend( StateFu::OrderedHash ).freeze
+        map { |type, name| [name, [].extend( OrderedHash )] }
+      hash = x.inject({}) {|h, a| h[a.first] = a.last; h }
+      hash.extend( OrderedHash ).freeze
     end
 
   end