state-fu 0.11.1

data/lib/persistence/active_record.rb

@@ -0,0 +1,34 @@
+module StateFu
+  module Persistence
+    class ActiveRecord < StateFu::Persistence::Base
+
+      def self.prepare_field( klass, field_name )
+        _field_name = field_name
+        Logger.debug("Preparing ActiveRecord field #{klass}.#{field_name}")
+
+        # this adds a before_save hook to ensure that the field is initialized 
+        # (and the initial state set) before create.
+        klass.send :before_create, :state_fu!
+                
+        # it's usually a good idea to do this:
+        # validates_presence_of _field_name
+      end
+
+      private
+
+      # We already checked that they exist, or we'd be using the
+      # Attribute version, so just do the simplest thing we can.
+
+      def read_attribute
+        Logger.debug "Read attribute #{field_name}, got #{object.send(:read_attribute,field_name)} for #{object.inspect}"
+        object.send( :read_attribute, field_name )
+      end
+
+      def write_attribute( string_value )
+        Logger.debug "Write attribute #{field_name} to #{string_value} for #{object.inspect}"
+        object.send( :write_attribute, field_name, string_value )
+      end
+
+    end
+  end
+end

data/lib/persistence/attribute.rb

@@ -0,0 +1,47 @@
+module StateFu
+  module Persistence
+    class Attribute < StateFu::Persistence::Base
+
+      def self.prepare_field( klass, field_name )
+        # ensure getter exists
+        unless klass.instance_methods.map(&:to_sym).include?( field_name.to_sym )
+          Logger.debug "Adding attr_reader :#{field_name} for #{klass}"
+          _field_name = field_name
+          klass.class_eval do
+            private
+            attr_reader _field_name
+          end
+        end
+
+        # ensure setter exists
+        unless klass.instance_methods.map(&:to_sym).include?( :"#{field_name}=" )
+          Logger.debug "Adding attr_writer :#{field_name}= for #{klass}"
+          _field_name = field_name
+          klass.class_eval do
+            private
+            attr_writer _field_name
+          end
+        end
+      end
+
+  def b; binding; end
+      private
+
+      # Read / write our strings to a plain old instance variable
+      # Define it if it doesn't exist the first time we go to read it
+
+      def read_attribute
+        string = object.send( field_name )
+        Logger.debug "Read attribute #{field_name}, got #{string.inspect} for #{object.inspect}"
+        string
+      end
+
+      def write_attribute( string_value )
+        writer_method = "#{field_name}="
+        Logger.debug "Writing attribute #{field_name} -> #{string_value.inspect} for #{object.inspect}"
+        object.send( writer_method, string_value )
+      end
+
+    end
+  end
+end

data/lib/persistence/base.rb

@@ -0,0 +1,100 @@
+module StateFu
+
+  class InvalidStateName < Exception
+  end
+
+  module Persistence
+    class Base
+
+      attr_reader :binding, :field_name, :current_state
+
+      def self.prepare_class( klass )
+        unless klass.instance_methods.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 )
+              state_fu!
+              begin
+                send( method_name, *args, &block )
+              rescue NoMethodError => e
+                method_missing_before_state_fu( method_name, *args, &block )
+              end
+            end
+          end
+        end
+      end
+
+      # define this method in subclasses to do any preparation
+      def self.prepare_field( klass, field_name )
+        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()
+
+        if current_state.nil?
+          Logger.warn("undefined state for binding #{binding} on #{object} with field_name #{field_name.inspect}")
+          Logger.warn("Machine for #{object} has no states: #{machine}") if machine.states.empty?
+        else
+          persist!
+          Logger.debug("#{object} resumes #{binding.method_name} at #{current_state.name}")
+        end
+      end
+
+      def find_current_state
+        string = read_attribute()
+        if string.blank?
+          machine.initial_state
+        else
+          state_name = string.to_sym
+          state      = machine.states[ state_name ] || raise( StateFu::InvalidStateName, string )
+        end
+      end
+
+      def reload
+        @current_state = find_current_state()
+      end
+
+      def machine
+        binding.machine
+      end
+
+      def object
+        binding.object
+      end
+
+      def klass
+        binding.target
+      end
+
+      def current_state=( state )
+        raise(ArgumentError, state.inspect) unless state.is_a?(StateFu::State)
+        @current_state = state
+        persist!
+      end
+
+      def value()
+        @current_state && @current_state.name.to_s
+      end
+
+      def persist!
+        write_attribute( value() )
+      end
+
+      private
+
+      def read_attribute
+        raise "Abstract method! override me"
+      end
+
+      def write_attribute( string_value )
+        raise "Abstract method! override me"
+      end
+
+    end
+  end
+end
+

data/lib/persistence/relaxdb.rb

@@ -0,0 +1,23 @@
+module StateFu
+  module Persistence
+    class RelaxDB < StateFu::Persistence::Base
+
+      def self.prepare_field( klass, field_name )
+        _field_name = field_name
+        #puts "relaxdb.before_save?"
+      end
+
+      private
+
+      def read_attribute
+        object.send( field_name )
+      end
+
+      def write_attribute( string_value )
+        object.send( "#{field_name}=", string_value )
+      end
+
+    end
+  end
+end
+

data/lib/persistence/session.rb

@@ -0,0 +1,7 @@
+module StateFu
+  module Persistence
+    class Session
+      # Rails / etc session key
+    end
+  end
+end

data/lib/sprocket.rb

@@ -0,0 +1,58 @@
+module StateFu
+  # 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
+      @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
+
+    # 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
+
+    def deep_copy
+      raise NotImeplementedError # abstract
+    end
+
+    def to_s
+      "#<#{self.class}::#{self.object_id} @name=#{name.inspect}>"
+    end
+
+    # 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.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+#
+# State-Fu
+#
+# State-Fu is a framework for state-oriented programming in ruby.
+#
+# You can use it to define state machines, workflows, rules engines,
+# and the behaviours which relate to states and transitions between
+# them.
+#
+# It is powerful and flexible enough to drive entire applications, or
+# substantial parts of them. It is designed as a library for authors,
+# as well as users, of libraries: State-Fu goes to great lengths to
+# impose very few limits on your ability to introspect, manipulate and
+# extend the core features.
+#
+# It is also delightfully elegant and easy to use for simple things.
+
+[ 'support/core_ext',
+  'support/logger',
+  'support/applicable',
+  'support/arrays',
+  'support/methodical',
+  'support/has_options',
+  'support/vizier',
+  'support/plotter',
+  'support/exceptions',
+  'executioner',
+  'machine',
+  'lathe',
+  'method_factory',
+  'binding',
+  'persistence',
+  'persistence/base',
+  'persistence/active_record',
+  'persistence/attribute',
+  'persistence/relaxdb',
+  'sprocket',
+  'state',
+  'event',
+  'hooks',
+  'interface',
+  'transition',
+  'transition_query' ].each { |lib| require File.expand_path(File.join(File.dirname(__FILE__),lib))}
+
+module StateFu
+  DEFAULT       = :default
+  DEFAULT_FIELD = :state_fu_field
+
+  def self.included( klass )
+    klass.extend(         Interface::ClassMethods )
+    klass.send( :include, Interface::InstanceMethods )
+    klass.extend(         Interface::Aliases )
+  end
+end
+

data/lib/state.rb

@@ -0,0 +1,48 @@
+module StateFu
+  class State < StateFu::Sprocket
+
+    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
+
+    def events
+      machine.events.from(self)
+    end
+
+    def before?(other)
+      machine.states.index(self) < machine.states.index(machine.states[other])
+    end
+
+    def after?(other)
+      machine.states.index(self) > machine.states.index(machine.states[other])
+    end
+
+    # 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 entry_requirements.empty?
+        s << " entry_requirements=#{entry_requirements.inspect}"
+      end
+      unless exit_requirements.empty?
+        s << " exit_requirements=#{exit_requirements.inspect}"
+      end
+      s << ">"
+      s
+    end
+
+  end
+end

data/lib/support/active_support_lite/array.rb

@@ -0,0 +1,9 @@
+require File.join( File.dirname( __FILE__),'array/extract_options')
+require File.join( File.dirname( __FILE__),'array/random_access')
+require File.join( File.dirname( __FILE__),'array/grouping')
+
+class Array #:nodoc:all:
+  include ActiveSupport::CoreExtensions::Array::ExtractOptions
+  include ActiveSupport::CoreExtensions::Array::RandomAccess
+  include ActiveSupport::CoreExtensions::Array::Grouping
+end

data/lib/support/active_support_lite/array/access.rb

@@ -0,0 +1,60 @@
+module ActiveSupport #:nodoc:all
+  module CoreExtensions #:nodoc
+    module Array #:nodoc
+      # Makes it easier to access parts of an array.
+      module Access #:nodoc:all
+        # Returns the tail of the array from +position+.
+        #
+        #   %w( a b c d ).from(0)  # => %w( a b c d )
+        #   %w( a b c d ).from(2)  # => %w( c d )
+        #   %w( a b c d ).from(10) # => nil
+        #   %w().from(0)           # => nil
+        #:nodoc
+        def from(position)
+          self[position..-1]
+        end
+
+        # Returns the beginning of the array up to +position+.
+        #
+        #   %w( a b c d ).to(0)  # => %w( a )
+        #   %w( a b c d ).to(2)  # => %w( a b c )
+        #   %w( a b c d ).to(10) # => %w( a b c d )
+        #   %w().to(0)           # => %w()
+        #:nodoc
+        def to(position)
+          self[0..position]
+        end
+
+        # Equal to <tt>self[1]</tt>.
+        #:nodoc
+        def second
+          self[1]
+        end
+
+        # Equal to <tt>self[2]</tt>.
+        #:nodoc
+        def third
+          self[2]
+        end
+
+        # Equal to <tt>self[3]</tt>.
+        #:nodoc
+        def fourth
+          self[3]
+        end
+
+        # Equal to <tt>self[4]</tt>.
+        #:nodoc
+        def fifth
+          self[4]
+        end
+
+        # Equal to <tt>self[41]</tt>. Also known as accessing "the reddit".
+        #:nodoc
+        def forty_two
+          self[41]
+        end
+      end
+    end
+  end
+end