davidlee-state-fu 0.3.1 → 0.10.0

data/lib/state_fu/persistence/base.rb

@@ -24,11 +24,13 @@ module StateFu
         end
       end
 
+      # define this method in subclasses to do any preparation
       def self.prepare_field( klass, field_name )
-        raise NotImplementedError # abstract method
+        Logger.warn("Abstract method in #{self}.prepare_field called. Override me!")
       end
 
       def initialize( binding, field_name )
+
         @binding       = binding
         @field_name    = field_name
         @current_state = find_current_state()
@@ -52,6 +54,10 @@ module StateFu
         end
       end
 
+      def reload
+        @current_state = find_current_state()
+      end
+
       def machine
         binding.machine
       end
@@ -61,13 +67,9 @@ module StateFu
       end
 
       def klass
-        object.class
+        binding.target
       end
 
-#      def method_name
-#        binding.method_name
-#      end
-
       def current_state=( state )
         raise(ArgumentError, state.inspect) unless state.is_a?(StateFu::State)
         @current_state = state

data/lib/state_fu/persistence.rb

@@ -1,10 +1,100 @@
 module StateFu
+
+  # the persistence module has a few simple tests which help decide which
+  # persistence mechanism to use
+
+  # TODO add event hooks (on_change etc) ...
+  # after benchmarking
+
+  # To create your own custom persistence mechanism,
+  # subclass StateFu::Persistence::Base
+  # and define prepare_field, read_attribute and write_attribute:
+
+
+  #  class StateFu::Persistence::MagneticCarpet < StateFu::Persistence::Base
+  #    def prepare_field
+  #
+  #
+  #    def read_attribute
+  #      object.send "magnetised_#{field_name}"
+  #    end
+  #
+  #    def write_attribute( string_value )
+  #      Logger.debug "magnetising ( #{field_name} => #{string_value} on #{object.inspect}"
+  #      object.send "magnetised_#{field_name}=", string_value
+  #    end
+  #  end
+
   module Persistence
-    DEFAULT_FIELD_NAME_SUFFIX = '_field'
+    DEFAULT_SUFFIX    = '_field'
+    @@class_for       = {}
+    @@fields_prepared = {}
+
+    #
+    # Class Methods
+    #
+
+    def self.default_field_name( machine_name )
+      machine_name == DEFAULT ? DEFAULT_FIELD : "#{machine_name.to_s.underscore.tr(' ','_')}#{DEFAULT_SUFFIX}"
+    end
+
+    # returns the appropriate persister class for the given class & field name.
+    def self.class_for( klass, field_name )
+      raise ArgumentError if [klass, field_name].any?(&:nil?)
+      @@class_for[klass] ||= {}
+      @@class_for[klass][field_name] ||=
+        if active_record_column?( klass, field_name )
+          self::ActiveRecord
+        elsif relaxdb_document_property?( klass, field_name )
+          self::RelaxDB
+        else
+          self::Attribute
+        end
+    end
+
+    def self.for_class( klass, binding, field_name )
+      persister_class = class_for klass, field_name
+      prepare_field( klass, field_name, persister_class)
+      returning persister_class.new( binding, field_name ) do |persister|
+        Logger.debug( "#{persister_class}: method #{binding.method_name} as field #{persister.field_name}" )
+      end
+    end
+
+    def self.for_instance( binding, field_name )
+      metaclass = class << binding.object; self; end
+      for_class( metaclass, binding, field_name )
+    end
+
+    # returns a new persister appropriate to the given binding and field_name
+    # also ensures the persister class method :prepare_field has been called
+    # once for the given class & field name so the field can be set up; eg an
+    # attr_accessor or a before_save hook defined
+    def self.for( binding )
+      field_name = binding.field_name.to_sym
+      if binding.singleton?
+        for_instance( binding, field_name )
+      else
+        for_class( binding.target, binding, field_name )
+      end
+    end
+
+    # ensures that <persister_class>.prepare_field is called only once
+    def self.prepare_field(klass, field_name, persister_class=nil)
+      @@fields_prepared[klass] ||= []
+      unless @@fields_prepared[klass].include?(field_name)
+        persister_class ||= class_for(klass, field_name)
+        persister_class.prepare_field( klass, field_name )
+        @@fields_prepared[klass] << field_name
+      end
+    end
+
+    #
+    # Heuristics - simple test methods to determine which persister to use
+    #
 
     # checks to see if the field_name for persistence is a
     # RelaxDB attribute.
-    # Safe to use if RelaxDB is not included.
+    # Safe to use (skipped) if RelaxDB is not included.
     def self.relaxdb_document_property?( klass, field_name )
       Object.const_defined?('RelaxDB') &&
         klass.ancestors.include?( ::RelaxDB::Document ) &&
@@ -13,33 +103,14 @@ module StateFu
 
     # checks to see if the field_name for persistence is an
     # ActiveRecord column.
-    # Safe to use if ActiveRecord is not included.
+    # Safe to use (skipped) if ActiveRecord is not included.
     def self.active_record_column?( klass, field_name )
       Object.const_defined?("ActiveRecord") &&
         ::ActiveRecord.const_defined?("Base") &&
         klass.ancestors.include?( ::ActiveRecord::Base ) &&
+        klass.table_exists? &&
         klass.columns.map(&:name).include?( field_name.to_s )
     end
 
-    # returns the appropriate persister class for the given class & field name.
-    def self.class_for( klass, field_name )
-      if active_record_column?( klass, field_name )
-        self::ActiveRecord
-      elsif relaxdb_document_property?( klass, field_name )
-        self::RelaxDB
-      else
-        self::Attribute
-      end
-    end
-
-    # returns a persister appropriate to the given binding and field_name
-    def self.for( binding, field_name )
-      class_for( binding.object.class, field_name ).new( binding, field_name )
-    end
-
-    def self.prepare_field( klass, field_name )
-      class_for( klass, field_name ).prepare_field( klass, field_name )
-    end
-
   end
 end

data/lib/state_fu/sprocket.rb

@@ -1,8 +1,11 @@
 module StateFu
-  class Sprocket # Abstract Superclass of State & Event
-    include StateFu::Helper # define apply!
-
-    attr_reader :machine, :name, :options, :hooks
+  # the abstract superclass of State & Event
+  # defines behaviours shared by both classes
+  class Sprocket 
+    include Applicable # define apply!
+    include HasOptions
+    
+    attr_reader :machine, :name, :hooks
 
     def initialize(machine, name, options={})
       @machine = machine
@@ -18,6 +21,7 @@ module StateFu
       @hooks[slot.to_sym] << [name.to_sym, value]
     end
 
+    # yields a lathe for self; useful for updating machine definitions on the fly
     def lathe(options={}, &block)
       StateFu::Lathe.new( machine, self, options, &block )
     end
@@ -30,14 +34,25 @@ module StateFu
       "#<#{self.class}::#{self.object_id} @name=#{name.inspect}>"
     end
 
-    def []v
-      options[v]
-    end
-
-    def []=v,k
-      options[v]=k
+    # allows state == <name> || event == <name> to return true
+    def == other
+      if other.is_a?(Symbol) 
+        self.name == other
+      else
+        super other
+      end
+    end 
+
+    # allows case equality tests against the state/event's name
+    # eg
+    # case state
+    # when :new
+    #   ...
+    # end
+    def === other
+      self.to_sym === other.to_sym || super(other)
     end
-
+    
   end
 end
 

data/lib/state_fu/state.rb

@@ -1,11 +1,13 @@
 module StateFu
   class State < StateFu::Sprocket
 
-    attr_reader :entry_requirements, :exit_requirements
-
+    attr_reader :entry_requirements, :exit_requirements, :own_events
+    alias_method :requirements, :entry_requirements
+    
     def initialize(machine, name, options={})
       @entry_requirements = [].extend ArrayWithSymbolAccessor
       @exit_requirements  = [].extend ArrayWithSymbolAccessor
+      @own_events         = [].extend EventArray
       super( machine, name, options )
     end
 
@@ -13,33 +15,12 @@ module StateFu
       machine.events.from(self)
     end
 
-    #
-    # Proxy methods to StateFu::Lathe
-    #
-    # TODO - build something meta to build these proxy events
-    def event( name, options={}, &block )
-      if block_given?
-        lathe.event( name, options, &block )
-      else
-        lathe.event( name, options )
-      end
-    end
-
-    def enterable_by?( binding, *args )
-      entry_requirements.reject do |r|
-        res = binding.evaluate_requirement_with_args( r, *args )
-      end.empty?
-    end
-
-    def exitable_by?( binding, *args )
-      exit_requirements.reject do |r|
-        binding.evaluate_requirement_with_args( r, *args )
-      end.empty?
+    def before?(other)
+      machine.states.index(self) < machine.states.index(machine.states[other])
     end
 
-    # allows @obj.state_fu.state === :new
-    def === other
-      self.to_sym === other.to_sym
+    def after?(other)
+      machine.states.index(self) > machine.states.index(machine.states[other])
     end
 
     # display nice and short

data/lib/state_fu/transition.rb

@@ -6,152 +6,208 @@ module StateFu
   # This is what gets yielded to event hooks; it also gets attached
   # to any TransitionHalted exceptions raised.
 
-  class Transition
-    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 )
-      @binding    = binding
-      @machine    = binding.machine
-      @object     = binding.object
-      @origin     = binding.current_state
+  # 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 
+
+    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 ]
+      if event.is_a?(Symbol) && e = binding.machine.events[event]
         event = e
       end
-      raise( ArgumentError, "Not an event: #{event}" ) unless event.is_a?( StateFu::Event )
+      raise( ArgumentError, "Not an event: #{event}" ) unless event.is_a? Event 
 
-      target = find_event_target( event, target ) || raise( ArgumentError, "target cannot be determined: #{target.inspect}" )
-
-      # ensure target is valid for the event
-      unless event.targets.include?( target )
-        raise( StateFu::InvalidTransition.new( binding, event, binding.current_state, target,
-                                               "Illegal target #{target} for #{event}" ))
-      end
-
-      # ensure current_state is a valid origin for the event
-      unless event.origins.include?( binding.current_state )
-        raise( StateFu::InvalidTransition.new( binding, event, binding.current_state, target,
-                                               "Illegal event #{event.name} for current state #{binding.state_name}" ))
-      end
+      @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}"))
 
-      @options    = args.extract_options!.symbolize_keys!
       @target     = target
       @event      = event
-      @args       = args
       @errors     = []
-      @testing    = @options.delete( :test_only )
+      @testing    = @options.delete(:test_only)
+            
+      if event.target_for_origin(origin) == target
+        # ...
+      else
+        # ensure target is valid for the event
+        unless event.targets.include? target 
+          raise InvalidTransition.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}" )
+        end
+      end 
+      
       machine.inject_helpers_into( self )
+    end
 
-      # do stuff with the transition in a block, if you like
-      apply!( &block ) if block_given?
+    def options=(opts={})
+      @options = opts
     end
 
+    def args=(a)      
+      @args = a.extend(TransitionArgsArray).init(self)    
+      apply!(a) if a.last.is_a?(Hash)
+    end
+    
+    #
+    # Requirements
+    #
+    
     def requirements
       origin.exit_requirements + target.entry_requirements + event.requirements
     end
 
-    def unmet_requirements
-      requirements.reject do |requirement|
-        binding.evaluate_requirement_with_transition( requirement, self )
+    def unmet_requirements(revalidate=false, fail_fast=false) # TODO
+      if revalidate
+        return @unmet_requirements if @unmet_requirements
+      else
+        @unmet_requirements = nil
+      end
+      result = requirements.uniq.inject([]) do |unmet, requirement|
+        next if fail_fast && !unmet.empty?
+        unmet << requirement unless evaluate(requirement)
+        unmet
       end
+      @unmet_requirements = result if (!fail_fast || unmet_requirements.length <= 1)
+      result
+    end
+    
+    def first_unmet_requirement(revalidate=false)
+      unmet_requirements(revalidate, fail_fast=true)[0]
     end
 
-    def evaluate_requirement_message( name )
-      msg = machine.requirement_messages[name]
-      case msg
-      when String, nil
-        msg
-      when Symbol, Proc
-        evaluate_named_proc_or_method( msg, self )
-      else
-        raise msg.class.to_s
-      end
+    def unmet_requirement_messages(revalidate=false, fail_fast=false) # TODO
+      unmet_requirements(revalidate, fail_fast).map do |requirement|
+        evaluate_requirement_message requirement 
+      end.extend MessageArray
+    end
+    alias_method :error_messages, :unmet_requirement_messages
+    
+    def requirement_errors(revalidate=false, fail_fast=false)
+      unmet_requirements(revalidate, fail_fast).
+        map { |requirement| [requirement, evaluate_requirement_message(requirement)]}.
+        to_h
     end
 
-    def unmet_requirement_messages
-      unmet_requirements.map do |requirement|
-        evaluate_requirement_message( requirement )
-      end
+    def first_unmet_requirement(revalidate=false)
+      unmet_requirements(revalidate, fail_fast=true)[0]
     end
 
-    def check_requirements!
-      raise RequirementError.new( self, unmet_requirements.inspect ) unless requirements_met?
+    def first_unmet_requirement_message(revalidate=false)
+      unmet_requirement_messages(revalidate, fail_fast=true)[0]
     end
 
-    def requirements_met?
-      unmet_requirements.empty?
+    def check_requirements!(revalidate=false, fail_fast=true) # TODO
+      raise RequirementError.new( self, unmet_requirement_messages.inspect ) unless requirements_met?(revalidate, fail_fast)
     end
-    alias_method :valid?, :requirements_met?
 
-    def hooks_for( element, slot )
+    def requirements_met?(revalidate=false, fail_fast=false) # TODO
+      unmet_requirements(revalidate, fail_fast).empty?
+    end
+    alias_method :valid?, :requirements_met?
+    
+    #
+    # Hooks
+    #
+    def hooks_for(element, slot)
       send(element).hooks[slot]
     end
 
-    def hooks()
+    def hooks
       StateFu::Hooks::ALL_HOOKS.map do |owner, slot|
-        [ [owner, slot], send( owner ).hooks[ slot ] ]
+        [ [owner, slot], send(owner).hooks[slot] ]
       end
     end
 
-    def current_state
-      if accepted?
-        :accepted
-      else
-        current_hook.state rescue :unfired
-      end
+    def run_hook hook 
+      evaluate hook 
     end
 
-    def run_hook( hook )
-      evaluate_named_proc_or_method( hook, self )
-    end
 
-    def halt!( message )
+
+    #
+    #
+    #
+
+    # 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
 
+    #
+    #
+    #
+    
+    # actually fire the transition
     def fire!
-      return false if fired? # no infinite loops please
+      raise TransitionAlreadyFired.new(self) if fired?
+      # return false if fired? # no infinite loops please
       check_requirements!
       @fired = true
       begin
+        # duplicated: see #hooks method
         StateFu::Hooks::ALL_HOOKS.map do |owner, slot|
-          [ [owner, slot], send( owner ).hooks[ 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 )
+            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
-      return accepted?
+      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?
@@ -173,9 +229,18 @@ module StateFu
     def accepted?
       !!@accepted
     end
-
+    alias_method :complete?, :accepted?
+    
+    def current_state
+      binding.current_state
+    end
+    
+    def destination
+      [event, target].map(&:to_sym)
+    end
+   
     #
-    # Try to give as many options (chances) as possible
+    # give as many choices as possible
     #
 
     alias_method :obj,            :object
@@ -191,24 +256,10 @@ module StateFu
     alias_method :initial_state,  :origin
     alias_method :from,           :origin
 
-    alias_method :om,             :binding
-    alias_method :stateful,       :binding
-    alias_method :binding,        :binding
-    alias_method :present,        :binding
-
-    alias_method :workflow,       :machine
-
-    alias_method :write? ,        :live?
-    alias_method :destructive?,   :live?
-    alias_method :real?,          :live?
-    alias_method :really?,        :live?
-    alias_method :seriously?,     :live?
-
     alias_method :test?,          :testing?
     alias_method :test_only?,     :testing?
     alias_method :read_only?,     :testing?
     alias_method :only_pretend?,  :testing?
-    alias_method :pretend?,       :testing?
     alias_method :dry_run?,       :testing?
 
     # an accepted transition == true
@@ -220,9 +271,67 @@ module StateFu
         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 )
+      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
+    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
+        raise ArgumentError.new( "#{tgt.class} is not a Symbol, StateFu::State or nil (#{evt})" )
+      end
+    end
+
   end
 end