davidlee-state-fu 0.0.1

data/lib/state_fu/lathe.rb

@@ -0,0 +1,247 @@
+module StateFu
+  class Lathe
+
+    # NOTE: Sprocket is the abstract superclass of Event and State
+
+    attr_reader :machine, :sprocket, :options
+
+    def initialize( machine, sprocket = nil, options={}, &block )
+      @machine  = machine
+      @sprocket = sprocket
+      @options  = options.symbolize_keys!
+      if sprocket
+        sprocket.apply!( options )
+      end
+      if block_given?
+        if block.arity == 1
+          if sprocket
+            yield sprocket
+          else
+            raise ArgumentError
+          end
+        else
+          instance_eval( &block )
+        end
+      end
+    end
+
+    private
+
+    # a 'child' lathe is created by apply_to, to deal with nested
+    # blocks for states / events ( which are sprockets )
+    def child?
+      !!@sprocket
+    end
+
+    # is this the toplevel lathe for a machine?
+    def master?
+      !child?
+    end
+
+    # instantiate a child lathe and apply the given block
+    def apply_to( sprocket, options, &block )
+      StateFu::Lathe.new( machine, sprocket, options, &block )
+      sprocket
+    end
+
+    # require that the current sprocket be of a given type
+    def require_sprocket( *valid_types )
+      raise ArgumentError.new("Lathe is for a #{sprocket.class}, not one of #{valid_types.inspect}") unless valid_types.include?( sprocket.class )
+    end
+
+    # ensure this is not a child lathe
+    def require_no_sprocket()
+      require_sprocket( NilClass )
+    end
+
+    # abstract method for defining states / events
+    def define_sprocket( type, name, options={}, &block )
+      name       = name.to_sym
+      klass      = StateFu.const_get((a=type.to_s.split('',2);[a.first.upcase, a.last].join))
+      collection = machine.send("#{type}s")
+      options.symbolize_keys!
+      if sprocket = collection[name]
+        apply_to( sprocket, options, &block )
+        sprocket
+      else
+        sprocket = klass.new( machine, name, options )
+        collection << sprocket
+        apply_to( sprocket, options, &block )
+        sprocket
+      end
+    end
+
+    def define_state( name, options={}, &block )
+      define_sprocket( :state, name, options, &block )
+    end
+
+    def define_event( name, options={}, &block )
+      define_sprocket( :event, name, options, &block )
+    end
+
+    def define_hook slot, method_name=nil, &block
+      unless sprocket.hooks.has_key?( slot )
+        raise ArgumentError, "invalid hook type #{slot.inspect} for #{sprocket.class}"
+      end
+      if block_given?
+        # unless (-1..1).include?( block.arity )
+        #   raise ArgumentError, "unexpected block arity: #{block.arity}"
+        # end
+        case method_name
+        when Symbol
+          machine.named_procs[method_name] = block
+          hook = method_name
+        when NilClass
+          hook = block
+          # allow only one anonymous hook per slot in the interests of
+          # sanity - replace any pre-existing ones
+          sprocket.hooks[slot].delete_if { |h| Proc === h }
+        else
+          raise ArgumentError.new( method_name.inspect )
+        end
+      elsif method_name.is_a?( Symbol ) # no block
+        hook = method_name
+        # prevent duplicates
+        sprocket.hooks[slot].delete_if { |h| hook == h }
+      else
+        raise ArgumentError, "#{method_name.class} is not a symbol"
+      end
+      sprocket.hooks[slot] << hook
+    end
+
+    public
+
+    # helpers are mixed into all binding / transition contexts
+    def helper( *modules )
+      machine.helper *modules
+    end
+
+    #
+    # event definition
+    #
+
+    def event( name, options={}, &block )
+      options.symbolize_keys!
+      require_sprocket( StateFu::State, NilClass )
+      if child? && sprocket.is_a?( StateFu::State ) # in state block
+        targets  = options.delete(:to)
+        evt      = define_event( name, options, &block )
+        evt.from sprocket unless evt.origins
+        evt.to( targets ) unless targets.nil?
+        evt
+      else # in master lathe
+        origins = options.delete( :from )
+        targets = options.delete( :to )
+        evt     = define_event( name, options, &block )
+        evt.from origins unless origins.nil?
+        evt.to   targets unless targets.nil?
+        evt
+      end
+    end
+
+    def requires( *args, &block )
+      require_sprocket( StateFu::Event, StateFu::State )
+      options = args.extract_options!.symbolize_keys!
+      options.assert_valid_keys(:on, :message, :msg )
+      names   = args
+      if block_given? && args.length > 1
+        raise ArgumentError.new("cannot supply a block for multiple requirements")
+      end
+      on = nil
+      names.each do |name|
+        raise ArgumentError.new( name.inspect ) unless name.is_a?( Symbol )
+        case sprocket
+        when StateFu::State
+          on ||= [(options.delete(:on) || [:entry])].flatten
+          sprocket.entry_requirements << name if on.include?( :entry )
+          sprocket.exit_requirements  << name if on.include?( :exit  )
+        when StateFu::Event
+          sprocket.requirements << name
+        end
+        if block_given?
+          machine.named_procs[name] = block
+        end
+        if msg = options.delete(:message) || options.delete(:msg)
+          # TODO - move this into machine
+          raise ArgumentError, msg.inspect unless [String, Symbol, Proc].include?(msg.class)
+          machine.requirement_messages[name] = msg
+        end
+      end
+    end
+    alias_method :must,         :requires
+    alias_method :must_be,      :requires
+    alias_method :needs,        :requires
+    alias_method :satisfy,      :requires
+    alias_method :must_satisfy, :requires
+
+    # create an event from *and* to the current state.
+    # Creates a loop, useful (only) for hooking behaviours onto.
+    def cycle( name=nil, options={}, &block )
+      name ||= "cycle_#{sprocket.name.to_s}"
+      require_sprocket( StateFu::State )
+      evt = define_event( name, options, &block )
+      evt.from sprocket
+      evt.to   sprocket
+      evt
+      # raise NotImplementedError
+    end
+
+    #
+    # state definition
+    #
+
+    def initial_state( *args, &block )
+      require_no_sprocket()
+      machine.initial_state= state( *args, &block)
+    end
+
+    def state( name, options={}, &block )
+      require_no_sprocket()
+      define_state( name, options, &block )
+    end
+
+    def from *args, &block
+      require_sprocket( StateFu::Event )
+      sprocket.from( *args, &block )
+    end
+
+    def to *args, &block
+      require_sprocket( StateFu::Event )
+      sprocket.to( *args, &block )
+    end
+
+    #
+    # do something with all states / events
+    #
+    def each_sprocket( type, *args, &block)
+      require_no_sprocket()
+      options = args.extract_options!.symbolize_keys!
+      if args == [:ALL] || args == []
+        args = machine.send("#{type}s").except( options.delete(:except) )
+      end
+      args.map { |name| self.send( type, name, options.dup, &block) }.extend StateArray
+    end
+
+    def states( *args, &block )
+      each_sprocket( 'state', *args, &block )
+    end
+    alias_method :all_states, :states
+    alias_method :each_state, :states
+
+    def events( *args, &block )
+      each_sprocket( 'event', *args, &block )
+    end
+    alias_method :all_events, :events
+    alias_method :each_event, :events
+
+    # Bunch of silly little methods for defining events
+
+    def before   *a, &b; require_sprocket( StateFu::Event ); define_hook :before,   *a, &b; end
+    def on_exit  *a, &b; require_sprocket( StateFu::State ); define_hook :exit,     *a, &b; end
+    def execute  *a, &b; require_sprocket( StateFu::Event ); define_hook :execute,  *a, &b; end
+    def on_entry *a, &b; require_sprocket( StateFu::State ); define_hook :entry,    *a, &b; end
+    def after    *a, &b; require_sprocket( StateFu::Event ); define_hook :after,    *a, &b; end
+    def accepted *a, &b; require_sprocket( StateFu::State ); define_hook :accepted, *a, &b; end
+
+  end
+end

data/lib/state_fu/logger.rb

@@ -0,0 +1,10 @@
+require 'logger'
+
+module StateFu
+  if Object.const_defined?( "RAILS_DEFAULT_LOGGER" )
+    Logger       = RAILS_DEFAULT_LOGGER
+  else
+    Logger       = ::Logger.new( STDOUT )
+    Logger.level = ::Logger.const_get( (ENV["ZEN_LOGLEVEL"] || 'WARN').upcase )
+  end
+end

data/lib/state_fu/machine.rb

@@ -0,0 +1,159 @@
+module StateFu
+  class Machine
+    include Helper
+
+
+    # meta-constructor; expects to be called via Klass.machine()
+    def self.for_class(klass, name, options={}, &block)
+      options.symbolize_keys!
+      name = name.to_sym
+      unless machine = StateFu::FuSpace.class_machines[ klass ][ name ]
+        machine = new( name, options, &block )
+        machine.bind!( klass, name, options[:field_name] )
+      end
+      if block_given?
+        machine.apply!( &block )
+      end
+      machine
+    end
+
+    ##
+    ## Instance Methods
+    ##
+
+    attr_reader :states, :events, :options, :helpers, :named_procs, :requirement_messages, :name
+
+    def initialize( name, options={}, &block )
+      # TODO - @name isn't actually used anywhere yet except
+      # in deep_clone - remove it?
+      @name    = name
+      @states  = [].extend( StateArray  )
+      @events  = [].extend( EventArray  )
+      @helpers = [].extend( HelperArray )
+      @named_procs          = {}
+      @requirement_messages = {}
+      @options              = options
+    end
+
+    def deep_clone()
+      m = Machine.new( name, options.dup )
+    end
+
+    # merge the commands in &block with the existing machine; returns
+    # a lathe for the machine.
+    def apply!( &block )
+      StateFu::Lathe.new( self, &block )
+    end
+    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
+    end
+
+    def inject_helpers_into( obj )
+      metaclass = class << obj; self; end
+
+      mods = helper_modules()
+      metaclass.class_eval do
+        mods.each do |mod|
+          include( mod )
+        end
+      end
+    end
+
+    # the modules listed here will be mixed into Binding and
+    # Transition objects for this machine. use this to define methods,
+    # references or data useful to you during transitions, event
+    # hooks, or in general use of StateFu.
+    #
+    # They can be supplied as a string/symbol (as per rails controller
+    # helpers), or a Module.
+    #
+    # To do this globally, just duck-punch StateFu::Machine /
+    # StateFu::Binding.
+    def helper *modules_to_add
+      modules_to_add.each { |mod| helpers << 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 )
+      field_name ||= name.to_s.underscore.tr(' ', '_') + StateFu::Persistence::DEFAULT_FIELD_NAME_SUFFIX
+      field_name   = field_name.to_sym
+      StateFu::FuSpace.insert!( klass, self, name, field_name )
+      # define an accessor method with the given name
+      unless name == StateFu::DEFAULT_MACHINE
+        klass.class_eval do
+          define_method name do
+            state_fu( name )
+          end
+        end
+      end
+
+      # method_missing to catch NoMethodError for event methods, etc
+      StateFu::MethodFactory.prepare_class( klass )
+
+      # prepare the persistence field
+      StateFu::Persistence.prepare_field( klass, field_name )
+      true
+    end
+
+    def empty?
+      states.empty?
+    end
+
+    def initial_state=( s )
+      case s
+      when Symbol, String, StateFu::State
+        unless init_state = states[ s.to_sym ]
+          init_state = StateFu::State.new( self, s.to_sym )
+          states << init_state
+        end
+        @initial_state = init_state
+      else
+        raise( ArgumentError, s.inspect )
+      end
+    end
+
+    def initial_state()
+      @initial_state ||= states.first
+    end
+
+    def state_names
+      states.map(&:name)
+    end
+
+    def event_names
+      events.map(&:name)
+    end
+
+    # given a messy bunch of symbols, find or create a list of
+    # matching States.
+    def find_or_create_states_by_name( *args )
+      args = args.compact.flatten
+      raise ArgumentError.new( args.inspect ) unless args.all? { |a| [Symbol, StateFu::State].include? a.class }
+      args.map do |s|
+        unless state = states[s.to_sym]
+          # TODO clean this line up
+          state = s.is_a?( StateFu::State ) ? s : StateFu::State.new( self, s )
+          self.states << state
+        end
+        state
+      end
+    end
+
+    def inspect
+      "#<#{self.class} ##{__id__} states=#{state_names.inspect} events=#{event_names.inspect} options=#{options.inspect}>"
+    end
+
+  end
+end

data/lib/state_fu/method_factory.rb

@@ -0,0 +1,95 @@
+module StateFu
+  class MethodFactory
+
+    def initialize( _binding )
+      @binding = _binding
+      define_event_methods_on( _binding )
+    end
+
+    def install!
+      define_event_methods_on( @binding.object )
+    end
+
+    # ensure the methods are available before calling state_fu
+    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 )
+      klass.class_eval do
+        alias_method :method_missing_before_state_fu, :method_missing
+
+        def method_missing( method_name, *args, &block )
+          if @state_fu_initialized
+            method_missing_before_state_fu( method_name, *args, &block )
+          else
+            state_fu!
+            if respond_to?( method_name )
+              send( method_name, *args, &block )
+            else
+              method_missing_before_state_fu( method_name, *args, &block )
+            end
+          end
+        end # method_missing
+      end # class_eval
+    end # prepare_class
+
+    def define_method_on_metaclass( object, method_name, &block )
+      return false if object.respond_to?( method_name )
+      metaclass   = class << object; self; end
+      metaclass.class_eval do
+        define_method( method_name, &block )
+      end
+    end
+
+    def define_event_methods_on( obj )
+      _binding        = @binding
+      simple, complex = @binding.machine.events.partition(&:simple? )
+
+      # method definitions for simple events (only one possible target)
+      simple.each do |event|
+        # obj.event_name( *args )
+        # returns a new transition
+        method_name = event.name
+        define_method_on_metaclass( obj, method_name ) do |*args|
+          _binding.transition( event, *args )
+        end
+
+        # obj.event_name?()
+        # true if the event is fireable? (ie, requirements met)
+        method_name = "#{event.name}?"
+        define_method_on_metaclass( obj, method_name ) do
+          _binding.fireable?( event )
+        end
+
+        # obj.event_name!( *args )
+        # creates, fires and returns a transition
+        method_name = "#{event.name}!"
+        define_method_on_metaclass( obj, method_name ) do |*args|
+          _binding.fire!( event, *args )
+        end
+      end
+
+      # method definitions for complex events (target must be specified)
+      complex.each do |event|
+        # obj.event_name( target, *args )
+        # returns a new transition
+        define_method_on_metaclass( obj, event.name ) do |target, *args|
+          _binding.transition( [event, target], *args )
+        end
+
+        # obj.event_name?( target )
+        # true if the event is fireable? (ie, requirements met)
+        method_name = "#{event.name}?"
+        define_method_on_metaclass( obj, method_name ) do |target|
+          _binding.fireable?( [event, target] )
+        end
+
+        # obj.event_name!( target, *args )
+        # creates, fires and returns a transition
+        method_name = "#{event.name}!"
+        define_method_on_metaclass( obj, method_name ) do |target,*args|
+          _binding.fire!( [event, target], *args )
+        end
+
+      end
+    end
+  end
+end

data/lib/state_fu/persistence/active_record.rb

@@ -0,0 +1,27 @@
+module StateFu
+  module Persistence
+    class ActiveRecord < StateFu::Persistence::Base
+
+      def self.prepare_field( klass, field_name )
+        _field_name = field_name
+        klass.send :before_save, :state_fu!
+          # 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
+        object.send( :read_attribute, field_name )
+      end
+
+      def write_attribute( string_value )
+        object.send( :write_attribute, field_name, string_value )
+      end
+
+    end
+  end
+end

data/lib/state_fu/persistence/attribute.rb

@@ -0,0 +1,46 @@
+module StateFu
+  module Persistence
+    class Attribute < StateFu::Persistence::Base
+
+      def self.prepare_field( klass, field_name )
+        # ensure getter exists
+        unless klass.instance_methods.include?( field_name )
+          Logger.info "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.include?( "#{field_name}=" )
+          Logger.info "Adding attr_writer :#{field_name}= for #{klass}"
+          _field_name = field_name
+          klass.class_eval do
+            private
+            attr_writer _field_name
+          end
+        end
+      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.info "Read attribute #{field_name}, got #{string} for #{object}"
+        string
+      end
+
+      def write_attribute( string_value )
+        writer_method = "#{field_name}="
+        Logger.info "Writing attribute #{field_name} -> #{string_value} for #{object}"
+        object.send( writer_method, string_value )
+      end
+
+    end
+  end
+end

data/lib/state_fu/persistence/base.rb

@@ -0,0 +1,98 @@
+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
+
+      def self.prepare_field( klass, field_name )
+        raise NotImplementedError # abstract method
+      end
+
+      def initialize( binding, field_name )
+        @binding       = binding
+        @field_name    = field_name
+        @current_state = find_current_state()
+
+        if current_state.nil?
+          Logger.info("Object has an undefined state: #{object}")
+          Logger.info("Machine has no states: #{machine}") if machine.states.empty?
+        else
+          persist!
+          Logger.debug("Object resumes at #{current_state.name}: #{object}")
+        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 machine
+        binding.machine
+      end
+
+      def object
+        binding.object
+      end
+
+      def klass
+        object.class
+      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
+        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/state_fu/persistence/session.rb

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