state-fu 0.11.1

data/lib/transition.rb

@@ -0,0 +1,338 @@
+module StateFu
+
+  # A 'context' class, created when an event is fired, or needs to be
+  # validated.
+  #
+  # This is what gets yielded to event hooks; it also gets attached
+  # to any TransitionHalted exceptions raised.
+
+  # TODO - make transition evaluate as true if accepted, false if failed, or nil unless fired
+
+  class Transition
+    include Applicable
+    include HasOptions
+
+    attr_reader :binding,
+                :machine,
+                :origin,
+                :target,
+                :event,
+                :args,
+                :errors,
+                :object,
+                :current_hook_slot,
+                :current_hook 
+
+    alias_method :arguments, :args   
+    
+    def initialize( binding, event, target=nil, *argument_list, &block )
+      # 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
+            
+      # 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     = []
+            
+      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 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 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 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 with?(*args)
+      valid?
+    end
+    alias_method :valid_with?, :with?
+    
+    #
+    # Requirements
+    #
+    
+    def requirements
+      origin.exit_requirements + target.entry_requirements + event.requirements
+    end
+
+    def unmet_requirements(revalidate=false, fail_fast=false) 
+      if revalidate
+        @unmet_requirements = nil
+      else
+        return @unmet_requirements if @unmet_requirements
+      end
+      result = [requirements].flatten.uniq.inject([]) do |unmet, requirement|
+        unmet << requirement unless evaluate(requirement)
+        break(unmet) if fail_fast && !unmet.empty?
+        unmet
+      end
+      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
+    
+    def first_unmet_requirement(revalidate=false)
+      unmet_requirements(revalidate, fail_fast=true)[0]
+    end
+
+    def unmet_requirement_messages(revalidate=false, fail_fast=false) # TODO
+      unmet_requirements(revalidate, fail_fast).map do |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_message(revalidate=false)
+      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
+
+    def requirements_met?(revalidate=false, fail_fast=false) # TODO
+      unmet_requirements(revalidate, fail_fast).empty?
+    end
+    
+    #
+    # Hooks
+    #
+    def hooks_for(element, slot)
+      send(element).hooks[slot]
+    end
+
+    def hooks
+      StateFu::Hooks::ALL_HOOKS.map do |owner, slot|
+        [ [owner, slot], send(owner).hooks[slot] ]
+      end
+    end
+
+    def run_hook hook 
+      evaluate hook 
+    end
+
+    #
+    # Halt a transition mid-execution
+    #
+
+    # halt a transition with a message
+    # can be used to back out of a transition inside eg a state entry hook
+    def halt! message 
+      raise TransitionHalted.new( self, message )
+    end
+
+    #
+    # Fire!
+    #
+    
+    # actually fire the transition
+    def fire!(*arguments) # block? 
+      raise TransitionAlreadyFired.new(self) if fired?
+      self.args = arguments unless arguments.empty?
+            
+      check_requirements!
+      @fired = true
+      begin
+        # duplicated: see #hooks method
+        StateFu::Hooks::ALL_HOOKS.map do |owner, slot|
+          [ [owner, slot], send(owner).hooks[slot] ]
+        end.each do |address, hooks|
+          Logger.info("running #{address.inspect} hooks for #{object.class} #{object}")
+          owner,slot = *address
+          hooks.each do |hook|
+            Logger.info("running hook #{hooks} for #{object.class} #{object}")
+            @current_hook_slot = address
+            @current_hook      = hook
+            run_hook hook 
+          end
+          if slot == :entry
+            @accepted                        = true
+            @binding.persister.current_state = @target
+            Logger.info("State is now :#{@target.name} for #{object.class} #{object}")
+          end
+        end
+        # transition complete
+        @current_hook_slot               = nil
+        @current_hook                    = nil
+      rescue TransitionHalted => e
+        Logger.info("Transition halted for #{object.class} #{object}: #{e.inspect}")
+        @errors << e
+      end
+      self
+    end
+    
+    #
+    # It can pretend it's a hash; so the transition makes a good argument to be
+    # passed to methods.
+    # 
+    include Enumerable
+
+    def each *a, &b 
+      options.each *a, &b 
+    end
+
+    def halted?
+      !@errors.empty?
+    end
+
+    def fired?
+      !!@fired
+    end
+
+    def accepted?
+      !!@accepted
+    end
+    alias_method :complete?, :accepted?
+    
+    def current_state
+      binding.current_state
+    end
+    
+    # a little convenience for debugging / display
+    def destination
+      [event, target].map(&:to_sym)
+    end
+   
+    #
+    # give as many choices as possible
+    #
+
+    alias_method :obj,            :object
+    alias_method :instance,       :object
+    alias_method :model,          :object
+    alias_method :instance,       :object
+
+    alias_method :destination,    :target
+    alias_method :final_state,    :target
+    alias_method :to,             :target
+
+    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
+    # same for === (for case equality)
+    def == other
+      case other
+      when true
+        accepted?
+      when false
+        !accepted?
+      when State, Symbol
+        current_state == other.to_sym
+      when Transition
+        inspect == other.inspect
+      else
+        super( other )
+      end
+    end
+
+    # display nice and short
+    def inspect
+      s = self.to_s
+      s = s[0,s.length-1]
+      s << " event=#{event.to_sym.inspect}" if event
+      s << " origin=#{origin.to_sym.inspect}" if origin
+      s << " target=#{target.to_sym.inspect}" if target
+      s << " args=#{args.inspect}" if args
+      s << " options=#{options.inspect}" if options
+      s << ">"
+      s
+    end
+
+    private
+
+    def executioner
+      @executioner ||= Executioner.new( self ) do |ex|
+        machine.inject_helpers_into( ex )
+        machine.inject_methods_into( ex )
+      end
+    end
+
+    def evaluate(method_name_or_proc)
+      executioner.evaluate(method_name_or_proc)
+    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 ] 
+      when NilClass
+        evt.respond_to?(:target) && evt.target
+      else
+        raise ArgumentError.new( "#{tgt.class} is not a Symbol, StateFu::State or nil (#{evt})" )
+      end
+    end
+
+  end
+end

data/lib/transition_query.rb

@@ -0,0 +1,224 @@
+module StateFu
+  class TransitionQuery
+    attr_accessor :binding, :options, :result, :args, :block
+
+    def initialize(binding, options={})
+      defaults = { :valid => true, :cyclic => nil }
+      @options = defaults.merge(options).symbolize_keys
+      @binding = binding
+    end
+
+    include Enumerable
+    
+    def each *a, &b
+      result.each *a, &b
+    end
+
+    # calling result() will cause the set of transitions to be calculated -
+    # the cat will then be either dead or alive; until then it's a litte from
+    # column A, a little from column B.
+    def method_missing(method_name, *args, &block)
+      if result.respond_to?(method_name, true)
+        result.__send__(method_name, *args, &block)
+      else
+        super(method_name, *args, &block)
+      end
+    end
+                
+    # prepare the query with arguments / block
+    # so that they can be applied to the transition once one is selected
+    def with(*args, &block)
+      @args  = args
+      @block = block if block_given?
+      self
+    end
+    
+    # build a list of possible transition destinations ([event, target])
+    # without actually constructing any transition objects
+    # def all_destinations
+    #   binding.events.inject([]){ |arr, evt| arr += evt.targets.map{|tgt| [evt,tgt] }; arr}.uniq
+    # end
+    # 
+    # def all_destination_names
+    #   all_destinations.map {|tuple| tuple.map(&:to_sym) }
+    # end
+
+    #
+    # Chainable Filters
+    #     
+    
+    def cyclic
+      @options.merge! :cyclic => true
+      self
+    end
+
+    def not_cyclic
+      @options.merge! :cyclic => false
+      self
+    end
+
+    def valid
+      @options.merge! :valid => true
+      self
+    end
+
+    def not_valid
+      @options.merge! :valid => false
+      self
+    end
+    alias_method :invalid, :not_valid
+
+    def to state
+      @options.merge! :target => state
+      self
+    end
+
+    def for_event event
+      @options.merge! :event => event
+      self
+    end
+
+    def simple
+      @options.merge! :simple => true
+      self
+    end
+    
+    #
+    # Means to an outcome
+    #
+    
+    # find a transition by event and optionally (optional if it can be inferred) target.
+    def find(destination=nil, &block)
+      # use the prepared event & target, and block, if none are supplied
+      event, target = destination.nil? ? [options[:event], options[:target]] : parse_destination(destination)
+      block ||= @block
+      returning Transition.new(binding, event, target, &block) do |transition|
+        if @args
+          transition.args = @args 
+        end
+      end        
+    end
+  
+    def singular
+      result.first if result.length == 1
+    end
+
+    def singular?
+      !!singular
+    end
+
+    def next
+      @options[:cyclic] ||= false
+      singular
+    end
+    
+    def next_state
+      @options[:cyclic] ||= false
+      if result.map(&:target).uniq.length == 1
+        result.first.target
+      end
+    end
+
+    def next_event
+      @options[:cyclic] ||= false
+      if result.map(&:event).uniq.length == 1
+        result.first.event
+      end
+    end
+    
+    def events
+      map {|t| t.event }.extend EventArray
+    end
+
+    def targets
+      map {|t| t.target }.extend StateArray
+    end
+
+    private
+
+    # extend result with this to provide a few conveniences   
+    module Result
+      def states
+        map(&:target).uniq.extend StateArray
+      end
+      alias_method :targets, :states
+      alias_method :next_states, :states
+
+      def events
+        map(&:event).uniq.extend EventArray
+      end
+    end # Result
+
+    # looks a little complex because of all the places that previously set
+    # options can filter the set of transitions - but all it's doing is
+    # looping over each event, and each event's possible targets, and building
+    # a list of transitions.
+    
+    def result
+      @result = binding.events.select do |e| 
+        case options[:cyclic]
+        when true
+          e.cycle?
+        when false
+          !e.cycle?
+        else
+          true
+        end
+      end.map do |event|
+        next if options[:event] and event != options[:event]
+        returning [] do |ts|
+
+          # TODO hmm ... "sequences" ... undecided on these. see Event / Lathe for more detail          
+          if options[:sequences]
+            if target = event.target_for_origin(current_state)
+              ts << binding.transition([event,target], *args) unless options[:cyclic]
+            end
+          end
+
+          # build a list of transitions from the possible events and their targets
+          if event.targets
+            next unless event.target if options[:simple]
+            event.targets.flatten.each do |target|
+              next if options[:target] and target != options[:target]
+              t = Transition.new(binding, event, target, *args)
+              ts << t if (t.valid? or !options[:valid])
+            end
+          end
+
+        end
+      end.flatten.extend(Result)
+      
+      if @args || @block
+        @result.each do |t|
+          t.apply!( &@block) if @block 
+          t.args = @args     if @args
+        end
+      end
+      
+      @result
+    end # result 
+
+    # sanitizes / extracts destination for find.
+    #
+    # 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(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, State],[Event, NilClass]].include?( [event,target].map(&:class) )
+      [event, target]
+    end # parse_destination
+
+  end
+end
+