davidlee-state-fu 0.0.1

data/lib/state_fu/persistence.rb

@@ -0,0 +1,50 @@
+module StateFu
+  module Persistence
+    DEFAULT_FIELD_NAME_SUFFIX = '_field'
+
+    def self.prepare_class( klass )
+      return if ( klass.instance_methods + klass.private_methods + klass.protected_methods ).map(&:to_sym).include?( :method_missing_before_state_fu )
+      alias_method :method_missing_before_state_fu, :method_missing
+      klass.class_eval do
+        def method_missing( method_name, *args, &block )
+          args.unshift method_name
+          if @state_fu_initialized
+            method_missing_before_state_fu( *args, &block )
+          else
+            state_fu!
+            if respond_to?(method_name)
+              send( *args, &block )
+            else
+              method_missing_before_state_fu( *args, &block )
+            end
+          end
+        end # method_missing
+      end # class_eval
+    end # prepare_class
+
+
+    def self.active_record_column?( klass, field_name )
+      Object.const_defined?("ActiveRecord") &&
+        ::ActiveRecord.const_defined?("Base") &&
+        klass.ancestors.include?( ::ActiveRecord::Base ) &&
+        klass.columns.map(&:name).include?( field_name.to_s )
+    end
+
+    def self.for( binding, field_name )
+      if active_record_column?( binding.object.class, field_name )
+        self::ActiveRecord.new( binding, field_name )
+      else
+        self::Attribute.new( binding, field_name )
+      end
+    end
+
+    def self.prepare_field( klass, field_name )
+      if active_record_column?( klass, field_name )
+        self::ActiveRecord.prepare_field( klass, field_name )
+      else
+        self::Attribute.prepare_field( klass, field_name )
+      end
+    end
+
+  end
+end

data/lib/state_fu/sprocket.rb

@@ -0,0 +1,27 @@
+module StateFu
+  class Sprocket # Abstract Superclass of State & Event
+    include StateFu::Helper # define apply!
+
+    attr_reader :machine, :name, :options, :hooks
+
+    def initialize(machine, name, options={})
+      @machine = machine
+      @name    = name.to_sym
+      @options = options.symbolize_keys!
+      @hooks   = StateFu::Hooks.for( self )
+    end
+
+    # sneaky way to make some comparisons / duck typing a bit cleaner
+    alias_method :to_sym,  :name
+
+    def add_hook slot, name, value
+      @hooks[slot.to_sym] << [name.to_sym, value]
+    end
+
+    def lathe(options={}, &block)
+      StateFu::Lathe.new( machine, self, options, &block )
+    end
+
+  end
+end
+

data/lib/state_fu/state.rb

@@ -0,0 +1,45 @@
+module StateFu
+  class State < StateFu::Sprocket
+
+    attr_reader :entry_requirements, :exit_requirements
+
+    def initialize(machine, name, options={})
+      @entry_requirements = [].extend ArrayWithSymbolAccessor
+      @exit_requirements  = [].extend ArrayWithSymbolAccessor
+      super( machine, name, options )
+    end
+
+    def events
+      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 )
+      entry_requirements.reject do |r|
+        res = binding.evaluate_requirement( r )
+      end.empty?
+    end
+
+    def exitable_by?( binding )
+      exit_requirements.reject do |r|
+        binding.evaluate_requirement( r )
+      end.empty?
+    end
+
+    # allows @obj.state_fu.state === :new
+    def === other
+      self.to_sym === other.to_sym
+    end
+  end
+end

data/lib/state_fu/transition.rb

@@ -0,0 +1,213 @@
+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.
+
+  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 )
+      # 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?( StateFu::Event )
+
+      # infer target if necessary
+      case target
+      when StateFu::State # good
+      when Symbol
+        target = binding.machine.states[ target ] ||
+          raise( ArgumentError, "target cannot be determined: #{target.inspect}" )
+      when NilClass
+        unless target = event.target
+          raise( ArgumentError, "target cannot be determined: #{target.inspect}" )
+        end
+      else
+        raise ArgumentError.new( target.inspect )
+      end
+
+      # 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
+
+      @options    = args.extract_options!.symbolize_keys!
+      @binding    = binding
+      @machine    = binding.machine
+      @object     = binding.object
+      @origin     = binding.current_state
+      @target     = target
+      @event      = event
+      @args       = args
+      @errors     = []
+      @testing    = @options.delete( :test_only )
+
+      machine.inject_helpers_into( self )
+
+      # do stuff with the transition in a block, if you like
+      apply!( &block ) if block_given?
+    end
+
+    def requirements
+      origin.exit_requirements + target.entry_requirements + event.requirements
+    end
+
+    def unmet_requirements
+      requirements.reject do |requirement|
+        binding.evaluate_requirement( requirement )
+      end
+    end
+
+    def unmet_requirement_messages
+      unmet_requirements.map do |r|
+        binding.evaluate_requirement_message(r, self )
+      end
+    end
+
+    def check_requirements!
+      raise RequirementError.new( unmet_requirements.inspect ) unless requirements_met?
+    end
+
+    def requirements_met?
+      unmet_requirements.empty?
+    end
+    alias_method :valid?, :requirements_met?
+
+    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 current_state
+      if accepted?
+        :accepted
+      else
+        current_hook.state rescue :unfired
+      end
+    end
+
+    def run_hook( hook )
+      evaluate_named_proc_or_method( hook )
+    end
+
+    def halt!( message )
+      raise TransitionHalted.new( self, message )
+    end
+
+    def fire!
+      return false if fired? # no infinite loops please
+      check_requirements!
+      @fired = true
+      begin
+        StateFu::Hooks::ALL_HOOKS.map do |owner, slot|
+          [ [owner, slot], send( owner ).hooks[ slot ] ]
+        end.each do |address, hooks|
+          owner,slot = *address
+          hooks.each do |hook|
+            @current_hook_slot = address
+            @current_hook      = hook
+            run_hook( hook )
+          end
+          if slot == :entry
+            @accepted                        = true
+            @binding.persister.current_state = @target
+          end
+        end
+        # transition complete
+        @current_hook_slot               = nil
+        @current_hook                    = nil
+      rescue TransitionHalted => e
+        @errors << e
+      end
+      return accepted?
+    end
+
+    def halted?
+      !@errors.empty?
+    end
+
+    def fired?
+      !!@fired
+    end
+
+    def testing?
+      !!@test_only
+    end
+
+    def live?
+      !testing?
+    end
+
+    def accepted?
+      !!@accepted
+    end
+
+    #
+    # Try to give as many options (chances) 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
+
+    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?
+
+  end
+end

data/spec/helper.rb

@@ -0,0 +1,86 @@
+#!/usr/bin/env ruby
+thisdir = File.expand_path(File.dirname(__FILE__))
+$: << thisdir << "#{thisdir}/../lib"
+
+require 'rubygems'
+
+{"rr" => "rr", "spec" => "rspec" }.each do |lib, gem_name|
+  begin
+    require lib
+  rescue LoadError => e
+    STDERR.puts "The '#{gem_name}' gem is required to run StateFu's specs. Please install it by running (as root):\ngem install #{gem_name}\n\n"
+    exit 1;
+  end
+end
+
+require 'state-fu'
+require File.join( thisdir, '..' , 'lib', 'no_stdout' )
+
+Spec::Runner.configure do |config|
+  config.mock_with :rr
+end
+
+module MySpecHelper
+  include NoStdout
+
+  def prepare_active_record( options={}, &migration )
+    begin
+      require 'active_record'
+    rescue MissingSourceFile => e
+      pending "skipping specifications due to load error: #{e}"
+      return false
+    end
+
+    options.symbolize_keys!
+    options.assert_valid_keys( :db_config, :migration_name, :hidden )
+
+    # connect ActiveRecord
+    db_config = options.delete(:db_config) || {
+      :adapter  => 'sqlite3',
+      :database => ':memory:'
+    }
+    ActiveRecord::Base.establish_connection( db_config )
+
+    return unless block_given?
+
+    # prepare the migration
+    migration_class_name =
+      options.delete(:migration_name) || 'BeforeSpecMigration'
+    make_pristine_class( migration_class_name, ActiveRecord::Migration )
+    migration_class = migration_class_name.constantize
+    migration_class.class_eval( &migration )
+
+    # run the migration without spewing crap everywhere
+    if options.delete(:hidden) != false
+      no_stdout { migration_class.migrate( :up ) }
+    else
+      migration_class.migrate( :up )
+    end
+  end
+
+  def make_pristine_class(class_name, superklass=Object, reset_first = false)
+    reset! if reset_first
+    @class_names ||= []
+    @class_names << class_name
+    klass = Class.new( superklass )
+    klass.send( :include, StateFu )
+    Object.send(:remove_const, class_name ) if Object.const_defined?( class_name )
+    Object.const_set(class_name, klass)
+  end
+
+  def reset!
+    @class_names ||= []
+    @class_names.each do |class_name|
+      Object.send(:remove_const, class_name ) if Object.const_defined?( class_name )
+    end
+    @class_names = []
+    StateFu::FuSpace.reset!
+  end
+
+  def set_method_arity( object, method_name, needed_arity = 1 )
+    a = Object.new
+    stub( a ).arity() { needed_arity }
+    stub( object ).method(method_name) { a }
+  end
+
+end

data/spec/integration/active_record_persistence_spec.rb

@@ -0,0 +1,189 @@
+require File.expand_path("#{File.dirname(__FILE__)}/../helper")
+
+describe "an ActiveRecord model with StateFu included:" do
+
+  include MySpecHelper
+
+  before(:each) do
+    reset!
+    prepare_active_record() do
+      def self.up
+        create_table :example_records do |t|
+          t.string :name,           :null => false
+          t.string :state_fu_field, :null => false
+          t.string :description
+          t.string :status
+          t.timestamps
+        end
+      end
+    end
+
+    # class ExampleRecord < ActiveRecord::Base
+    make_pristine_class( 'ExampleRecord', ActiveRecord::Base )
+    ExampleRecord.class_eval do
+      validates_presence_of :name
+    end
+    # end class ExampleRecord
+  end
+
+  it "should be a subclass of ActiveRecord::Base" do
+    ExampleRecord.superclass.should == ActiveRecord::Base
+  end
+
+  describe "when the default machine is defined with no field_name specified" do
+    before do
+      ExampleRecord.class_eval do
+        machine do
+          state :initial do
+            event( :change, :to => :final ) { after :save! }
+          end
+        end
+      end
+      @ex = ExampleRecord.new( :name => "exemplar" )
+    end # before
+
+    it "should have an active_record string column 'state_fu_field' " do
+      col = ExampleRecord.columns.detect {|c| c.name == "state_fu_field" }
+      col.type.should == :string
+    end
+
+    describe "calling :save! via an event's after hook" do
+      it "should save the record with the new state persisted via the DB" do
+        @ex.change!
+        @ex.state_fu.name.should == :final
+        @ex.state_fu_field.should == 'final'
+        @ex.reload
+        @ex.state_fu_field.should == 'final'
+        @ex.state_fu.name.should == :final
+      end
+    end
+
+    describe "StateFu::Persistence.active_record_column?" do
+      it "should return true for ExampleRecord, :state_fu_field" do
+        StateFu::Persistence.active_record_column?( ExampleRecord, :state_fu_field ).should == true
+      end
+
+      it "should return true for ExampleRecord, :status" do
+        StateFu::Persistence.active_record_column?( ExampleRecord, :status ).should == true
+      end
+
+      it "should return false for ExampleRecord, :not_a_column" do
+        StateFu::Persistence.active_record_column?( ExampleRecord, :not_a_column ).should == false
+      end
+      it "should not clobber activerecord accessors" do
+        @ex.noodle! rescue nil
+        #        lambda { @ex.description }.should_not raise_error()
+        @ex.description.should be_nil
+        @ex.description= 'foo'
+        @ex.description.should == 'foo'
+      end
+
+      it "should have an active_record string column 'state_fu_field' " do
+        col = ExampleRecord.columns.detect {|c| c.name == "state_fu_field" }
+        col.type.should == :string
+      end
+    end
+
+    it "should have an active_record persister with the default field_name 'state_fu_field' " do
+      @ex.state_fu
+      @ex.state_fu.should be_kind_of( StateFu::Binding )
+      @ex.state_fu.persister.should be_kind_of( StateFu::Persistence::ActiveRecord )
+      @ex.state_fu.persister.field_name.should == :state_fu_field
+    end
+
+
+    # this ensures state_fu initializes the field before create to
+    # satisfy the not null constraint
+    describe "automagic state_fu! before_save filter and validations" do
+
+      it "should call state_fu! before a record is created" do
+        @ex.should be_new_record
+        mock.proxy( @ex ).state_fu!.at_least( 1 ) { }
+        @ex.save!
+      end
+
+      it "should call state_fu! before a record is updated" do
+        @ex.should be_new_record
+        mock.proxy( @ex ).state_fu!.at_least( 1 ) { }
+        @ex.save!
+      end
+
+      it "should fail to save if state_fu! does not instantiate the binding before create" do
+        pending "is this still relevant?"
+        mock( @ex ).state_fu!.at_least( 1 ) { }
+        lambda { @ex.save! }.should raise_error( ActiveRecord::StatementInvalid )
+        @ex.state_fu_field.should == nil
+      end
+
+      it "should create a record given only a name, with the field set to the initial state" do
+        ex = ExampleRecord.new( :name => "exemplar" )
+        ex.should be_valid
+        ex.state_fu_field.should == nil
+        ex.save!
+        ex.should_not be_new_record
+        ex.state_fu_field.should == 'initial'
+        ex.state_fu.state.name.should == :initial
+      end
+
+      it "should update the field after a transition is completed" 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.should be_accepted
+        ex.state_fu.state.name.should == :final
+        ex.state_fu_field.should == 'final'
+        ex.attributes['state_fu_field'].should == 'final'
+        ex.save!
+      end
+
+      describe "a saved record whose state is not the default" do
+        before do
+          @r = ExampleRecord.create!( :name => "exemplar" )
+          @r.change!
+          @r.state_fu_field.should == 'final'
+          @r.save!
+        end
+
+        it "should be reconstituted with the correct state" do
+          r = ExampleRecord.find( @r.id )
+          r.state_fu.should be_kind_of( StateFu::Binding )
+          r.state_fu.current_state.should be_kind_of( StateFu::State )
+          r.state_fu.current_state.should == ExampleRecord.machine.states[:final]
+        end
+      end # saved record after transition
+
+      describe "when a second machine named :status is defined with :field_name => 'status' " do
+        before do
+          ExampleRecord.machine(:status, :field_name => 'status') do
+            event( :go, :from => :initial, :to => :final )
+          end
+          @ex = ExampleRecord.new()
+        end
+
+        it "should have a binding for .status" do
+          @ex.status.should be_kind_of( StateFu::Binding )
+        end
+
+        it "should have an ActiveRecord persister with the field_name :status" do
+          @ex.status.persister.should be_kind_of( StateFu::Persistence::ActiveRecord )
+          @ex.status.persister.field_name.should == :status
+        end
+
+        it "should have a value of nil for the status field before state_fu is called" do
+          @ex.read_attribute('status').should be_nil
+        end
+
+        it "should have the ActiveRecord setter method .status=" do
+          @ex.status= 'damp'
+          @ex.read_attribute(:status).should == 'damp'
+        end
+
+        it "should raise StateFu::InvalidState if the status field is set to a bad value and .status is called" do
+          @ex.status= 'damp'
+          lambda { @ex.status }.should raise_error( StateFu::InvalidStateName )
+        end
+      end
+    end # second machine
+  end   # with before_create filter
+end     # default machine