davidlee-state-fu 0.0.1

data/lib/state_fu/core_ext.rb

@@ -0,0 +1,23 @@
+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 ..
+    def <=> other
+      self.to_s <=> other.to_s
+    end
+  end
+end

data/lib/state_fu/event.rb

@@ -0,0 +1,98 @@
+module StateFu
+  class Event < StateFu::Sprocket
+
+    attr_reader :origins, :targets, :requirements
+
+    #
+    # TODO - event guards
+    #
+
+    def initialize(machine, name, options={})
+      @requirements = [].extend ArrayWithSymbolAccessor
+      super( machine, name, options )
+    end
+
+    def origin_names
+      origins ? origins.map(&:to_sym) : nil
+    end
+
+    def target_names
+      targets ? targets.map(&:to_sym) : nil
+    end
+
+    def to?( state )
+      target_names.include?( state.to_sym )
+    end
+
+    def from?( state )
+      origin_names.include?( state.to_sym )
+    end
+
+    def origins=( *args )
+      if [args].flatten == [:ALL]
+        @origins = machine.states
+      else
+        @origins = machine.find_or_create_states_by_name( *args.flatten ) #.extend( StateArray )
+      end
+    end
+
+    def targets=( *args )
+      if [args].flatten == [:ALL]
+        @targets = machine.states
+      else
+        @targets = machine.find_or_create_states_by_name( *args.flatten ) # .extend( StateArray )
+      end
+    end
+
+    # complete?(:origins) # do we have an origins?
+    # complete?          # do we have an origins and targets?
+    def complete?( field = nil )
+      ( field && [field] ||  [:origins, :targets] ).
+        map{ |s| send(s) }.
+        all?{ |f| !(f.nil? || f.empty?) }
+    end
+
+    def origin
+      origins && origins.length == 1 && origins[0] || nil
+    end
+
+    def target
+      targets && targets.length == 1 && targets[0] || nil
+    end
+
+    def simple?
+      !! ( origins && target )
+    end
+
+    def from *args
+      options = args.extract_options!.symbolize_keys!
+      args.flatten!
+      to = options.delete(:to)
+      if args.empty? && !to
+        if options.length == 1
+          self.origins= options.keys[0]
+          self.targets= options.values[0]
+        else
+          raise options.inspect
+        end
+      else
+        self.origins= *args
+        self.targets= to unless to.nil?
+      end
+    end
+
+    def to *args
+      options = args.extract_options!.symbolize_keys!
+      args.flatten!
+      raise options.inspect unless options.empty?
+      self.targets= *args
+    end
+
+    def fireable_by?( binding )
+      requirements.reject do |r|
+        binding.evaluate_requirement( r )
+      end.empty?
+    end
+
+  end
+end

data/lib/state_fu/exceptions.rb

@@ -0,0 +1,42 @@
+module StateFu
+
+  class Exception < ::Exception
+    attr_reader :binding, :options
+  end
+
+  class RequirementError < Exception
+  end
+
+  class TransitionHalted < Exception
+    attr_reader :transition
+
+    DEFAULT_MESSAGE = "The transition was halted"
+
+    def initialize( transition, message=DEFAULT_MESSAGE, options={})
+      @transition = transition
+      @options    = options
+      super( message )
+    end
+  end
+
+  class InvalidTransition < Exception
+    attr_reader :binding, :origin, :target, :event, :args
+
+    DEFAULT_MESSAGE = "An invalid transition was attempted"
+
+    def initialize( binding,
+                    event,
+                    origin,
+                    target,
+                    message=DEFAULT_MESSAGE,
+                    options={})
+      @binding = binding
+      @event   = event
+      @origin  = origin
+      @target  = target
+      @options = options
+      super( message )
+    end
+  end
+
+end

data/lib/state_fu/fu_space.rb

@@ -0,0 +1,50 @@
+module StateFu
+  # Provides a place to stash references.
+  # In most cases you won't need to access it directly, though
+  # calling reset! before each of your tests/specs can be helpful.
+  class FuSpace
+    cattr_reader :named_machines, :class_machines, :field_names
+
+    # class_machines[ Class ][ method_name ] # => a StateFu::Machine
+    # class_machines[ Klass ][ nil ]         # => the Klass's default Machine
+    # field_names[ Class ][ method_name ] # => name of attribute / db field
+
+    # return the default machine, or an empty hash, given a missing index.
+    LAZY_HASH = lambda do |h, k|
+      if k.nil?
+        self[ StateFu::DEFAULT_MACHINE ]
+      else
+        h[k]= Hash.new()
+      end
+    end
+
+    # Add a machine to StateFu::FuSpace and register it with a given class, by a given name.
+    def self.insert!( klass, machine, name, field_name )
+      name                       = name.to_sym
+      field_name                 = field_name.to_sym
+      existing_machine              = @@class_machines[klass][name]
+      if existing_machine && !existing_machine.empty?
+        raise("#{klass} already knows a non-empty Machine #{machine} by the name #{name}.")
+      else
+        @@class_machines[klass][name] = machine
+        @@field_names[klass][name] = field_name
+      end
+    end
+    class << self
+      alias_method :insert,  :insert!
+    end
+
+    # Clears all machines and their bindings to classes.
+    # Also initializes the hashes we use to store our references.
+    def self.beginners_mind!
+      @@named_machines = Hash.new
+      @@class_machines = Hash.new( &LAZY_HASH )
+      @@field_names = Hash.new( &LAZY_HASH )
+    end
+    class << self
+      alias_method :reset!,  :beginners_mind!
+      alias_method :forget!, :beginners_mind!
+    end
+    beginners_mind!
+  end
+end

data/lib/state_fu/helper.rb

@@ -0,0 +1,189 @@
+module StateFu
+
+  # Utilities and snippets
+  module Helper
+
+    # Instance methods mixed in on inclusion of StateFu::Helper
+    module InstanceMethods
+
+      # if given a hash of options (or a splatted arglist containing
+      # one), merge them into @options. If given a block, eval it
+      # (yielding self if the block expects it)
+      def apply!( options={}, &block )
+        options.respond_to?(:keys) || options = options.extract_options!
+        @options.merge!( options.symbolize_keys! )
+        return self unless block_given?
+        case block.arity
+        when 1     # lambda{ |state| ... }
+          yield self
+        when -1, 0 # lambda{ } ( -1 in ruby 1.8.x but 0 in 1.9.x )
+          instance_eval &block
+        else
+          raise ArgumentError, "unexpected block arity: #{block.arity}"
+        end
+        self
+      end
+      alias_method :update!, :apply!
+
+    end
+
+    # Class methods mixed in on inclusion of StateFu::Helper
+    module ClassMethods
+    end
+
+    def self.included( mod )
+      mod.send( :include, InstanceMethods )
+      mod.extend( ClassMethods )
+    end
+
+  end
+
+  # Stuff shared between StateArray and EventArray
+  module ArrayWithSymbolAccessor
+    # Pass a symbol to the array and get the object with that .name
+    # [<Foo @name=:bob>][:bob]
+    # => <Foo @name=:bob>
+    def []( idx )
+      begin
+        super( idx )
+      rescue TypeError => e
+        if idx.respond_to?(:to_sym)
+          self.detect { |i| i == idx || i.respond_to?(:name) && i.name == idx.to_sym }
+        else
+          raise e
+        end
+      end
+    end
+
+    # so we can go Machine.states.names
+    # mildly helpful with irb + readline
+    def names
+      map(&:name)
+    end
+
+    # SPECME
+    def except *syms
+      reject {|el| syms.flatten.compact.map(&:to_sym).include?(el.to_sym) } #.extend ArrayWithSymbolAccessor
+    end
+
+    def only *syms
+      select {|el| syms.flatten.compact.map(&:to_sym).include?(el.to_sym) } #.extend ArrayWithSymbolAccessor
+    end
+
+  end
+
+  # Array extender. Used by Machine to keep a list of states.
+  module StateArray
+    include ArrayWithSymbolAccessor
+
+    # is there exactly one possible event to fire, with a single
+    # target event?
+    def next?
+    end
+
+    # if next?, return the state
+    def next
+    end
+
+  end
+
+  # Array extender. Used by Machine to keep a list of events.
+  module EventArray
+    include ArrayWithSymbolAccessor
+
+    # return all events transitioning from the given state
+    def from( origin )
+      select { |e| e.respond_to?(:from?) && e.from?( origin ) }
+    end
+
+    # return all events transitioning to the given state
+    def to( target )
+      select { |e| e.respond_to?(:to?) && e.to?( target ) }
+    end
+
+    # is there exactly one possible event to fire, with a single
+    # target event?
+    def next?
+    end
+
+    # if next?, return the event
+    def next
+    end
+
+  end
+
+  # Array extender. Used by Machine to keep a list of helpers to mix into
+  # context objects.
+  module HelperArray
+
+  end
+
+  # Extend an Array with this. It's a fairly compact implementation,
+  # though it won't be super fast with lots of elements.
+  # items. Internally objects are stored as a list of
+  # [:key, 'value'] pairs.
+  module OrderedHash
+    # if given a symbol / string, treat it as a key
+    def []( index )
+      begin
+        super( index )
+      rescue TypeError
+        ( x = self.detect { |i| i.first == index }) && x[1]
+      end
+    end
+
+    # hash-style setter
+    def []=( index, value )
+      begin
+        super( index, value )
+      rescue TypeError
+        ( x = self.detect { |i| i.first == index }) ?
+        x[1] = value : self << [ index, value ].extend( OrderedHash )
+      end
+    end
+
+    # poor man's Hash.keys
+    def keys
+      map(&:first)
+    end
+
+    # poor man's Hash.values
+    def values
+      map(&:last)
+    end
+  end  # OrderedHash
+
+  module ContextualEval
+    module InstanceMethods
+      def evaluate( &proc )
+        if proc.arity == 1
+          object.instance_exec( self, &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 )
+        else
+          object.send( name )
+        end
+      end
+
+      def evaluate_named_proc_or_method( name )
+        if (name.is_a?( Proc ) && proc = name) || proc = machine.named_procs[ name ]
+          evaluate &proc
+        else
+          call_on_object_with_self( name )
+        end
+      end
+    end
+
+    def self.included( klass )
+      klass.send :include, InstanceMethods
+    end
+  end
+end

data/lib/state_fu/hooks.rb

@@ -0,0 +1,28 @@
+module StateFu
+  module Hooks
+
+    ALL_HOOKS = [[:event,  :before],   # good place to start a transaction, etc
+                 [:origin, :exit],     # say goodbye!
+                 [:event,  :execute],  # do stuff here, as a rule of thumb
+                 [:target, :entry],    # last chance to halt!
+                 [:event,  :after],    # clean up all the mess
+                 [:target, :accepted]] # state changed. Quicksave!
+
+    EVENT_HOOKS = ALL_HOOKS.select { |type, name| type == :event }
+    STATE_HOOKS = ALL_HOOKS - EVENT_HOOKS
+    HOOK_NAMES  = ALL_HOOKS.map {|a| a[1] }
+
+    # just turn the above into what each class needs
+    # and make it into a nice hash: { :name =>[ hook, ... ], ... }
+    def self.for( me )
+      x = if    me.is_a?( StateFu::State ); STATE_HOOKS
+          elsif me.is_a?( StateFu::Event ); EVENT_HOOKS
+          else  {}
+          end.
+        map { |_,name| [name, [].extend( StateFu::OrderedHash )] }
+      hash = x.inject({}) {|h, a| h[a[0]] = a[1] ; h}
+      hash.extend( StateFu::OrderedHash ).freeze
+    end
+
+  end
+end

data/lib/state_fu/interface.rb

@@ -0,0 +1,139 @@
+module StateFu
+  module Interface
+    # Provides access to StateFu to your classes.  Plenty of aliases are
+    # provided so you can use whatever makes sense to you.
+    module ClassMethods
+
+      # TODO:
+      # take option :alias => false (disable aliases) or :alias
+      # => :foo (use foo as class & instance accessor)
+
+      #
+      # Given no arguments, return the default machine (:state_fu) for the
+      # class, creating it if it did not exist.
+      #
+      # Given a symbol, return the machine by that name, creating it
+      # if it didn't exist.
+      #
+      # Given a block, also define it with the contents of the block.
+      #
+      # This can be done multiple times; changes are cumulative.
+      #
+      # You can have as many machines as you like per class.
+      #
+      # Klass.machine            # the default machine named :om
+      #                          # equivalent to Klass.machine(:om)
+      # Klass.machine(:workflow) # another totally separate machine
+      #
+      # machine( name=:state_fu, options[:field_name], &block )
+
+      def machine( *args, &block )
+        options = args.extract_options!.symbolize_keys!
+        name    = args[0] || StateFu::DEFAULT_MACHINE
+        StateFu::Machine.for_class( self, name, options, &block )
+      end
+      alias_method :stfu,          :machine
+      alias_method :state_fu,      :machine
+      alias_method :workflow,      :machine
+      alias_method :statefully,    :machine
+      alias_method :state_machine, :machine
+      alias_method :stateful,      :machine
+      alias_method :workflow,      :machine
+      alias_method :engine,        :machine
+
+      # return a hash of :name => StateFu::Machine for your class.
+      def machines( *args, &block )
+        if args.empty? && !block_given?
+          StateFu::FuSpace.class_machines[self]
+        else
+          machine( *args, &block)
+        end
+      end
+      alias_method :machines,     :machines
+      alias_method :workflows,    :machines
+      alias_method :engines,      :machines
+
+      # return the list of machines names for this class
+      def machine_names()
+        StateFu::FuSpace.class_machines[self].keys
+      end
+      alias_method :machine_names,       :machine_names
+      alias_method :workflow_names,      :machine_names
+      alias_method :engine_names,        :machine_names
+    end
+
+    # Give the gift of state to your objects. These methods
+    # grant access to StateFu::Binding objects, which are bundles of
+    # context linking a StateFu::Machine to an object / instance.
+    # Again, plenty of aliases are provided so you can use whatever
+    # makes sense to you.
+    module InstanceMethods
+      private
+      def _state_fu
+        @_state_fu ||= {}
+      end
+
+      # A StateFu::Binding comes into being, linking your object and a
+      # machine, when you first call yourobject.binding() for that
+      # machine.
+      #
+      # Like the class method .machine(), calling it without any arguments
+      # is equivalent to passing :om.
+      #
+      # Essentially, this is the accessor method through which an instance
+      # can see and change its state, interact with events, etc.
+      #
+      public
+      def _binding( name=StateFu::DEFAULT_MACHINE )
+        name = name.to_sym
+        if mach = StateFu::FuSpace.class_machines[self.class][name]
+          _state_fu[name] ||= StateFu::Binding.new( mach, self, name )
+        end
+      end
+
+      alias_method :fu,          :_binding
+      alias_method :stfu,        :_binding
+      alias_method :state_fu,    :_binding
+      alias_method :stateful,    :_binding
+      alias_method :workflow,    :_binding
+      alias_method :engine,      :_binding
+      alias_method :context,     :_binding
+
+
+      # Gain awareness of all bindings (state contexts) this object
+      # has contemplated into being.
+      # Returns a Hash of { :name => <StateFu::Binding>, ... }
+      def _bindings()
+        _state_fu
+      end
+
+      alias_method :fus,          :_bindings
+      alias_method :stfus,        :_bindings
+      alias_method :state_fus,    :_bindings
+      alias_method :state_foos,   :_bindings
+      alias_method :workflows,    :_bindings
+      alias_method :engines,      :_bindings
+      alias_method :bindings,     :_bindings
+      alias_method :machines,     :_bindings # not strictly accurate, but makes sense sometimes
+      alias_method :contexts,     :_bindings
+
+      # Instantiate bindings for all machines defined for this class.
+      # It's useful to call this before_create w/
+      # ActiveRecord classes, as this will cause the database field
+      # to be populated with the default state name.
+      def state_fu!( *names )
+        if [names || [] ].flatten!.map! {|n| n.to_sym }.empty?
+          names = self.class.machine_names()
+        end
+        @state_fu_initialized = true
+        names.map { |n| _binding( n ) }
+      end
+      alias_method :fu!,               :state_fu!
+      alias_method :stfu!,             :state_fu!
+      alias_method :state_fu!,         :state_fu!
+      alias_method :init_machines!,    :state_fu!
+      alias_method :initialize_state!, :state_fu!
+      alias_method :build_workflow!,   :state_fu!
+    end
+  end
+end