davidlee-state-fu 0.0.2 → 0.2.0

data/lib/state_fu/active_support_lite/string.rb

@@ -0,0 +1,33 @@
+class String
+  def underscore
+    self.gsub(/::/, '/').
+      gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+      gsub(/([a-z\d])([A-Z])/,'\1_\2').
+      tr("-", "_").
+      downcase
+  end
+
+  def demodulize
+    gsub(/^.*::/, '')
+  end
+
+  def constantize
+    unless /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/ =~ self
+      raise NameError, "#{self} is not a valid constant name!"
+    end
+    Object.module_eval("::#{$1}", __FILE__, __LINE__)
+  end
+
+  def classify # DOES NOT SINGULARISE
+    camelize(self.sub(/.*\./, ''))
+  end
+
+  def camelize( first_letter_in_uppercase = true)
+    if first_letter_in_uppercase
+      gsub(/\/(.?)/) { "::" + $1.upcase }.gsub(/(^|_)(.)/) { $2.upcase }
+    else
+      first + camelize(lower_case_and_underscored_word)[1..-1]
+    end
+  end
+
+end

data/lib/state_fu/active_support_lite/symbol.rb

@@ -0,0 +1,15 @@
+unless :to_proc.respond_to?(:to_proc)
+  class Symbol
+    # Turns the symbol into a simple proc, which is especially useful for enumerations. Examples:
+    #
+    #   # The same as people.collect { |p| p.name }
+    #   people.collect(&:name)
+    #
+    #   # The same as people.select { |p| p.manager? }.collect { |p| p.salary }
+    #   people.select(&:manager?).collect(&:salary)
+    def to_proc
+      Proc.new { |*args| args.shift.__send__(self, *args) }
+    end
+  end
+end
+

data/lib/state_fu/binding.rb

@@ -17,11 +17,11 @@ module StateFu
       StateFu::Persistence.prepare_field( object.class, field_name )
       # add a persister
       @persister     = StateFu::Persistence.for( self, field_name )
-      Logger.info( "Persister added: #@persister ")
+      Logger.info( "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 )
     end
     alias_method :o,         :object
@@ -45,7 +45,11 @@ module StateFu
     alias_method :state, :current_state
 
     def current_state_name
-      current_state.name
+      begin
+        current_state.name.to_sym
+      rescue NoMethodError
+        nil
+      end
     end
     alias_method :name,       :current_state_name
     alias_method :state_name, :current_state_name
@@ -58,43 +62,40 @@ module StateFu
     alias_method :events_from_current_state,  :events
 
     # the subset of events() whose requirements for firing are met
-    def valid_events
+    def valid_events( *args )
       return nil unless current_state
-      return [] unless current_state.exitable_by?( self )
-      events.select {|e| e.fireable_by?( self ) }.extend EventArray
+      return [] unless current_state.exitable_by?( self, *args )
+      events.select {|e| e.fireable_by?( self, *args ) }.extend EventArray
     end
 
-    def invalid_events
-      (events - valid_events).extend StateArray
+    def invalid_events( *args )
+      ( events - valid_events( *args ) ).extend StateArray
     end
 
-    def unmet_requirements_for(event, target)
+    def unmet_requirements_for( event, target )
       raise NotImplementedError
     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
-      valid_transitions.values.flatten.uniq.extend StateArray
+    def valid_next_states( *args )
+      vt = valid_transitions( *args )
+      vt && vt.values.flatten.uniq.extend( StateArray )
     end
 
     def next_states
       events.map(&:targets).compact.flatten.uniq.extend StateArray
     end
 
-    def invalid_next_states
-      states - valid_states
-    end
-
     # returns a hash of { event => [states] } whose transition
     # requirements are met
-    def valid_transitions
-      h = {}
-      return nil if valid_events.nil?
-      valid_events.each do |e|
+    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 )
+          s.enterable_by?( self, *args )
         end
       end
       h
@@ -105,8 +106,21 @@ module StateFu
       event, target = parse_destination( event_or_array )
       StateFu::Transition.new( self, event, target, *args, &block )
     end
-    alias_method :fire,    :transition
-    alias_method :trigger, :transition
+    alias_method :fire,             :transition
+    alias_method :fire_event,       :transition
+    alias_method :trigger,          :transition
+    alias_method :trigger_event,    :transition
+    alias_method :begin_transition, :transition
+
+    def blank_mock_transition( *args, &block )
+      StateFu::MockTransition.new( self, nil, nil, *args, &block )
+    end
+
+    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
 
     # sanitize args for fire! and fireable?
     def parse_destination( event_or_array )
@@ -125,7 +139,7 @@ module StateFu
     end
 
     # check that the event and target are "valid" (all requirements met)
-    def fireable?( event_or_array )
+    def fireable?( event_or_array, *args )
       event, target = parse_destination( event_or_array )
       begin
         t = transition( [event, target] )
@@ -134,11 +148,18 @@ module StateFu
         nil
       end
     end
-    alias_method :event?,         :fireable?
-    alias_method :trigger?,       :fireable?
-    alias_method :triggerable?,   :fireable?
-    alias_method :transition?,    :fireable?
-    alias_method :transitionable?,:fireable?
+    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
     def fire!( event_or_array, *args, &block)
@@ -153,37 +174,53 @@ module StateFu
 
     # 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( name )
-      evaluate_named_proc_or_method( name )
+      puts "DEPRECATED: evaluate_requirement #{name}"
+      evaluate_requirement_with_args( name )
     end
 
-    def evaluate_requirement_message( name, dest )
-      msg = machine.requirement_messages[name]
-      if [String, NilClass].include?( msg.class )
-        return msg
-      else
-        if dest.is_a?( StateFu::Transition )
-          t = dest
-        else
-          event, target = parse_destination( event_or_array )
-          t = transition( event, target )
-        end
-        case msg
-        when Symbol
-          t.evaluate_named_proc_or_method( msg )
-        when Proc
-          t.evaluate &msg
-        end
-      end
+    def evaluate_requirement_with_args( name, *args )
+      t = blank_mock_transition( *args )
+      evaluate_named_proc_or_method( name, t )
     end
 
+    def evaluate_requirement_with_transition( name, t )
+      evaluate_named_proc_or_method( name, t )
+    end
+
+    # TODO SPECME HACKERY CRUFT FIXME THISSUCKS and needs *args
+    # def evaluate_requirement_message( name, dest )
+    #   # puts "#{name} #{dest}"
+    #   msg = machine.requirement_messages[name]
+    #   if [String, NilClass].include?( msg.class )
+    #     return msg
+    #   else
+    #     if dest.is_a?( StateFu::Transition )
+    #       t = dest
+    #     else
+    #       event, target = parse_destination( event_or_array )
+    #       t = transition( event, target )
+    #     end
+    #     case msg
+    #     when Symbol, Proc
+    #       puts t.class
+    #       evaluate_named_proc_or_method( msg, t )
+    #     # when Proc
+    #     #   t.evaluate &msg
+    #     end
+    #   end
+    # end
+
     # if there is one simple event, return a transition for it
     # else return nil
     # TODO - not convinced about the method name / aliases - but next
     # is reserved :/
     def next_transition( *args, &block )
-      return nil if valid_transitions.nil?
-      next_transition_candidates = valid_transitions.select {|e, s| s.length == 1 }
+      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]
@@ -192,11 +229,15 @@ module StateFu
       end
     end
 
-    def next_state
-      next_transition && next_transition.target
+    def next_state( *args )
+      nt = next_transition( *args )
+      nt && nt.target
     end
 
-    alias_method :next_event, :next_transition
+    def next_event( *args )
+      nt = next_transition( *args )
+      nt && nt.event
+    end
 
     # if there is a next_transition, create, fire & return it
     # otherwise raise an InvalidTransition
@@ -205,10 +246,10 @@ module StateFu
         t.fire!
         t
       else
-        n = valid_transitions && valid_transitions.length
+        vts = valid_transitions( *args )
+        n = vts && vts.length
         raise InvalidTransition.
-          new( self, current_state, valid_transitions,
-               "there are #{n} candidate transitions, need exactly 1")
+          new( self, current_state, vts, "there are #{n} candidate transitions, need exactly 1")
       end
     end
     alias_method :next_state!, :next!
@@ -247,15 +288,29 @@ module StateFu
 
     # if there is one possible cyclical event, evaluate its
     # requirements (true/false), else nil
-    def cycle?
-      if t = cycle
+    def cycle?( *args )
+      if t = cycle( *args )
         t.requirements_met?
       end
     end
 
     # display something sensible that doesn't take up the whole screen
     def inspect
-      "#<#{self.class} ##{__id__} object_type=#{@object.class} method_name=#{method_name.inspect} field_name=#{persister.field_name.inspect} machine=#{@machine.inspect} options=#{options.inspect}>"
+      '|<= ' + self.class.to_s + ' ' +
+        attrs = [[:current_state, state_name.inspect],
+                 [:object_type , @object.class],
+                 [:method_name , method_name.inspect],
+                 [:field_name  , persister.field_name.inspect],
+                 [:machine     , machine.inspect]].
+        map {|x| x.join('=') }.join( " " ) + ' =>|'
+    end
+
+    def == other
+      if other.respond_to?(:to_sym) && current_state_name.is_a?(Symbol)
+        other.to_sym == current_state_name || super( other )
+      else
+        super( other )
+      end
     end
 
   end

data/lib/state_fu/core_ext.rb

@@ -1,18 +1,5 @@
 require 'rubygems'
 
-# unless Object.const_defined?('ActiveSupport')
-#
-#   require 'active_support/core_ext/array'
-#   require 'active_support/core_ext/blank'
-#   require 'active_support/core_ext/class'
-#   require 'active_support/core_ext/module'
-#   require 'active_support/core_ext/hash/keys'
-#
-#   class Hash #:nodoc:
-#     include ActiveSupport::CoreExtensions::Hash::Keys
-#   end
-# end
-
 class Symbol
   unless instance_methods.include?(:'<=>')
     # Logger.log ..
@@ -21,3 +8,15 @@ class Symbol
     end
   end
 end
+
+unless Object.const_defined?('ActiveSupport')
+  Dir[File.join(File.dirname( __FILE__), 'active_support_lite','**' )].sort.each do |lib|
+    next unless File.file?( lib )
+    require lib
+  end
+
+  class Hash #:nodoc:
+    include ActiveSupport::CoreExtensions::Hash::Keys
+  end
+
+end

data/lib/state_fu/event.rb

@@ -32,7 +32,7 @@ module StateFu
       if [args].flatten == [:ALL]
         @origins = machine.states
       else
-        @origins = machine.find_or_create_states_by_name( *args.flatten ) #.extend( StateArray )
+        @origins = machine.find_or_create_states_by_name( *args.flatten ).extend( StateArray )
       end
     end
 
@@ -40,7 +40,7 @@ module StateFu
       if [args].flatten == [:ALL]
         @targets = machine.states
       else
-        @targets = machine.find_or_create_states_by_name( *args.flatten ) # .extend( StateArray )
+        @targets = machine.find_or_create_states_by_name( *args.flatten ).extend( StateArray )
       end
     end
 
@@ -88,9 +88,9 @@ module StateFu
       self.targets= *args
     end
 
-    def fireable_by?( binding )
+    def fireable_by?( binding, *args )
       requirements.reject do |r|
-        binding.evaluate_requirement( r )
+        binding.evaluate_requirement_with_args( r, *args )
       end.empty?
     end
 

data/lib/state_fu/exceptions.rb

@@ -5,6 +5,18 @@ module StateFu
   end
 
   class RequirementError < Exception
+    attr_reader :transition
+    DEFAULT_MESSAGE = "The transition was halted"
+
+    def initialize( transition, message=DEFAULT_MESSAGE, options={})
+      @transition = transition
+      @options    = options
+      super( message )
+    end
+
+    def inspect
+      "<StateFu::RequirementError #{message} #{@transition.origin.name}=[#{@transition.event.name}]=>#{transition.target.name}"
+    end
   end
 
   class TransitionHalted < Exception

data/lib/state_fu/helper.rb

@@ -112,10 +112,39 @@ module StateFu
 
   end
 
+  module ModuleRefArray
+    def modules
+      self.map do |h|
+        case h
+        when String, Symbol
+          Object.const_get( h.to_s.classify )
+        when Module
+          h
+        else
+          raise ArgumentError.new( h.class.inspect )
+        end
+      end
+    end # modules
+
+    def inject_into( obj )
+      metaclass = class << obj; self; end
+      mods = self.modules()
+      metaclass.class_eval do
+        mods.each do |mod|
+          include( mod )
+        end
+      end
+    end
+  end
+
   # Array extender. Used by Machine to keep a list of helpers to mix into
   # context objects.
   module HelperArray
+    include ModuleRefArray
+  end
 
+  module ToolArray
+    include ModuleRefArray
   end
 
   # Extend an Array with this. It's a fairly compact implementation,
@@ -155,29 +184,62 @@ module StateFu
 
   module ContextualEval
     module InstanceMethods
-      def evaluate( &proc )
-        if proc.arity == 1
-          object.instance_exec( self, &proc )
+
+      # if we use &block syntax it stuffs the arity up, so we have to
+      # pass it as a normal argument
+      def limit_arguments( block, *args )
+        case block.arity
+        when -1, 0
+          nil
+        else
+          args[0 .. (block.arity - 1) ]
+        end
+      end
+
+      def evaluate( *args, &proc )
+        if proc.arity > 0
+          args = limit_arguments( proc, *args )
+          object.instance_exec( *args, &proc )
         else
           instance_eval( &proc )
         end
       end
 
-      def call_on_object_with_self( name )
-        # call a normal method on the object
-        # passing the transition as the argument if expected
-        if object.method(name).arity == 1
-          object.send( name, self )
+      def call_on_object_with_optional_args( name, *args )
+        if meth = object.method( name )
+          args = limit_arguments( meth, *args )
+          if args.nil?
+            object.send( name )
+          else
+            object.send( name, *args )
+          end
         else
-          object.send( name )
+          raise NoMethodError.new( "undefined method #{name} for #{object.inspect}" )
         end
       end
 
-      def evaluate_named_proc_or_method( name )
+      def call_on_object_with_self( name )
+        call_on_object_with_optional_args( name, self )
+      end
+
+      def evaluate_named_proc_or_method( name, *args )
         if (name.is_a?( Proc ) && proc = name) || proc = machine.named_procs[ name ]
-          evaluate &proc
+          evaluate( *args, &proc )
+        else
+          call_on_object_with_optional_args( name, *args )
+        end
+      end
+
+      def find_event_target( evt, tgt )
+        case tgt
+        when StateFu::State
+          tgt
+        when Symbol
+          binding && binding.machine.states[ tgt ] # || raise( tgt.inspect )
+        when NilClass
+          evt.respond_to?(:target) && evt.target
         else
-          call_on_object_with_self( name )
+          raise ArgumentError.new( "#{tgt.class} is not a Symbol, StateFu::State or nil (#{evt})" )
         end
       end
     end

data/lib/state_fu/lathe.rb

@@ -9,6 +9,10 @@ module StateFu
       @machine  = machine
       @sprocket = sprocket
       @options  = options.symbolize_keys!
+
+      # extend ourself with any previously defined tools
+      machine.tools.inject_into( self )
+
       if sprocket
         sprocket.apply!( options )
       end
@@ -38,6 +42,10 @@ module StateFu
       !child?
     end
 
+    def master_lathe
+      machine.lathe
+    end
+
     # instantiate a child lathe and apply the given block
     def apply_to( sprocket, options, &block )
       StateFu::Lathe.new( machine, sprocket, options, &block )
@@ -116,6 +124,13 @@ module StateFu
       machine.helper *modules
     end
 
+    # helpers are mixed into all binding / transition contexts
+    def tool( *modules )
+      machine.tool *modules
+      # inject them into self for immediate use
+      modules.flatten.extend( ToolArray ).inject_into( self )
+    end
+
     #
     # event definition
     #

data/lib/state_fu/machine.rb

@@ -20,13 +20,14 @@ module StateFu
     ## Instance Methods
     ##
 
-    attr_reader :states, :events, :options, :helpers, :named_procs, :requirement_messages
+    attr_reader :states, :events, :options, :helpers, :named_procs, :requirement_messages, :tools
 
     def initialize( name, options={}, &block )
       # TODO - name isn't actually used anywhere yet - remove from constructor
       @states  = [].extend( StateArray  )
       @events  = [].extend( EventArray  )
       @helpers = [].extend( HelperArray )
+      @tools   = [].extend( ToolArray   )
       @named_procs          = {}
       @requirement_messages = {}
       @options              = options
@@ -40,27 +41,15 @@ module StateFu
     alias_method :lathe, :apply!
 
     def helper_modules
-      helpers.map do |h|
-        case h
-        when String, Symbol
-          Object.const_get( h.to_s.classify )
-        when Module
-          h
-        else
-          raise ArgumentError.new( h.class.inspect )
-        end
-      end
+      helpers.modules
     end
 
     def inject_helpers_into( obj )
-      metaclass = class << obj; self; end
+      helpers.inject_into( obj )
+    end
 
-      mods = helper_modules()
-      metaclass.class_eval do
-        mods.each do |mod|
-          include( mod )
-        end
-      end
+    def inject_tools_into( obj )
+      tools.inject_into( obj )
     end
 
     # the modules listed here will be mixed into Binding and
@@ -77,6 +66,11 @@ module StateFu
       modules_to_add.each { |mod| helpers << mod }
     end
 
+    # same deal but for extending Lathe
+    def tool *modules_to_add
+      modules_to_add.each { |mod| tools << mod }
+    end
+
     # make it so a class which has included StateFu has a binding to
     # this machine
     def bind!( klass, name=StateFu::DEFAULT_MACHINE, field_name = nil )
@@ -144,14 +138,12 @@ module StateFu
       end
     end
 
-    def deep_copy()
-      # use Marshal as a poor man's x-ray photocopier
-      duplify = lambda { |o| Marshal.load Marshal.dump( o ) }
-      returning Machine.new( nil, duplify.call( options )) do |m|
-        @states.each { |s| m.states() << duplify.call(s) }
-        @events.each { |e| m.events() << duplify.call(e) }
-      end
+    # Marshal, the poor man's X-Ray photocopier.
+    # TODO: a version which will not break its teeth on procs
+    def deep_clone
+      Marshal::load(Marshal.dump(self))
     end
+    alias_method :deep_copy, :deep_clone
 
     def inspect
       "#<#{self.class} ##{__id__} states=#{state_names.inspect} events=#{event_names.inspect} options=#{options.inspect}>"

data/lib/state_fu/mock_transition.rb

@@ -0,0 +1,38 @@
+module StateFu
+  class MockTransition
+    include StateFu::Helper
+    include ContextualEval
+
+    attr_reader(  :binding,
+                  :machine,
+                  :origin,
+                  :target,
+                  :event,
+                  :args,
+                  :errors,
+                  :object,
+                  :options,
+                  :current_hook_slot,
+                  :current_hook )
+
+    attr_accessor :test_only, :args, :options
+
+    def initialize( binding, event, target=nil, *args, &block )
+      @options    = args.extract_options!.symbolize_keys!
+      if @binding = binding
+        @machine = binding.machine       rescue nil
+        @object  = binding.object        rescue nil
+        @origin  = binding.current_state rescue nil
+      end
+      @event   = event
+      @target  = find_event_target( event, target )
+      @args    = args
+      @errors  = []
+      @testing = true
+
+      machine.respond_to?(:inject_helpers_into) && machine.inject_helpers_into( self )
+      apply!( &block ) if block_given?
+    end
+
+  end
+end