state-fu 0.11.1

data/lib/event.rb

@@ -0,0 +1,192 @@
+module StateFu
+  class Event < StateFu::Sprocket
+
+    attr_reader :origins, :targets, :requirements, :sequence
+
+    # called by Lathe when a new event is constructed
+    def initialize(machine, name, options={})
+      @requirements = [].extend ArrayWithSymbolAccessor    
+      @sequence     = {}
+      super( machine, name, options )
+    end
+
+    # Sequences: pretending events are state-local -
+    # probably a bad idea but here for a "compatibility mode"
+    # with eg the activemodel state machine
+    
+    # build a hash of target => [origins]
+    def add_to_sequence origin_states, target_state
+      origin_states = [origin_states].flatten
+      existing = origin_states.select {|s| target_for_origin(s) }
+      raise ArgumentError.new unless existing.empty? && !targets       
+      @sequence[target_state] ||= []
+      [origin_states].flatten.each do |o|
+        @sequence[target_state] << o
+      end
+      @sequence
+    end
+
+    def sequence?
+      !sequence.empty?
+    end
+
+    def target_for_origin origin_state
+      raise ArgumentError.new if origin_state.nil?
+      name = sequence.detect do |k,v| 
+        v.include?(origin_state.to_sym)
+      end[0] rescue nil
+      machine.states[name] if name
+    end
+    
+
+    def can_transition_from?(origin_state) 
+      ( origins && origins.include?(origin_state.to_sym) && !targets.blank?) ||
+        target_for_origin(origin_state)
+    end    
+  
+    # the names of all possible origin states
+    def origin_names
+      origins ? origins.map(&:to_sym) : nil
+    end
+
+    # the names of all possible target states
+    def target_names
+      targets ? targets.map(&:to_sym) : nil
+    end
+
+    # tests if a state or state name is in the list of targets
+    def to?( state )
+      target_names.include?( state.to_sym )
+    end
+
+    # tests if a state or state name is in the list of origins
+    def from?( state )
+      origin_names.include?( state.to_sym ) || target_for_origin(state)
+    end
+    
+    def cycle?
+      origin && (origin == target)
+    end
+
+    # *adds to* the origin states given a list of symbols / States
+    def origins=( *args )
+      update_state_collection( '@origins', *args )
+    end
+
+    # *adds to* the target states given a list of symbols / States
+    def targets=( *args )
+      update_state_collection( '@targets', *args )
+    end
+
+    # if there is a single state in #origins, returns it
+    def origin
+      origins && origins.length == 1 && origins[0] || nil
+    end
+
+    # if there is a single state in #origins, returns it
+    def target
+      targets && targets.length == 1 && targets[0] || nil
+    end
+
+    # a simple event has exactly one target, and any number of
+    # origins. It's simple because it can be triggered without
+    # supplying a target name - ie, <tt>go!<tt> vs <tt>go!(:home)<tt>
+    def simple?
+      !! ( origins && target || sequence? )
+    end
+
+    def fireable?( transition )
+      transition.valid?(true)
+    end
+
+
+    #
+    # Lathe methods
+    #
+
+    # adds an event requirement.
+    # DOCME // TODO - can this be removed?
+    def requires( *args, &block )
+      lathe.requires( *args, &block )
+    end
+
+    # generally called from a Lathe. Sets the origin(s) and optionally
+    # target(s) - that is, if you supply the :to option, or a single element
+    # hash of origins => targets ) of the event. Both origins= and
+    # targets= are accumulators.
+    def from *args
+      options = args.extract_options!.symbolize_keys!
+      args.flatten!
+      to = options.delete(:to) || options.delete(:transitions_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
+
+    # sets the target states for the event.
+    def to *args
+      options = args.extract_options!.symbolize_keys!
+      args.flatten!
+      raise options.inspect unless options.empty?
+      self.targets= *args
+    end
+
+    alias_method :transitions_to,   :to
+    alias_method :transitions_from, :from
+
+    #
+    # misc
+    # 
+    
+    # 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 requirements.empty?
+        s << " requirements=#{requirements.inspect}"
+      end
+      s << " targets=#{targets.map(&:to_sym).inspect}" if targets
+      s << " origins=#{origins.map(&:to_sym).inspect}" if origins
+      s << ">"
+      s
+    end
+
+    private
+
+    # internal method which accumulates states into an instance
+    # variable with successive invocations.
+    # ensures that calling #from multiple times adds to, rather than
+    # clobbering, the list of origins / targets.
+    def update_state_collection( ivar_name, *args)
+      raise ArgumentError if sequence?      
+      new_states = if [args].flatten == [:ALL]
+            machine.states
+          else
+            machine.find_or_create_states_by_name( *args.flatten )
+          end
+      unless new_states.is_a?( Array )
+        new_states = [new_states]
+      end
+      existing  = instance_variable_get( ivar_name )
+      # return existing if new_states.empty?
+      new_value = ((existing || [] ) + new_states).flatten.compact.uniq.extend( StateArray )
+      instance_variable_set( ivar_name, new_value )
+    end
+
+  end
+end

data/lib/executioner.rb

@@ -0,0 +1,120 @@
+module StateFu
+  #
+  # delegator class for evaluation methods / procs in the context of
+  # your object.
+  #
+    
+  class Executioner
+
+    # give us a blank slate
+    # instance_methods.each { |m| undef_method m unless m =~ /(^__|^self|^nil\?$|^send$|proxy_|^object_id|^respond_to\?|^instance_exec|^instance_eval|^method$)/ }
+
+    def initialize transition, &block
+      @transition     = transition
+      @__target__     = transition.object
+      @__self___      = self
+      yield self if block_given?
+      # forces method_missing to snap back to its pre-state-fu condition:
+      # @__target__.initialize_state_fu!
+      self
+    end
+
+    delegate :origin,  :to => :transition, :prefix => true # transition_origin
+    delegate :target,  :to => :transition, :prefix => true # transition_target
+    delegate :event,   :to => :transition, :prefix => true # transition_event
+
+    delegate :halt!,   :to => :transition
+    delegate :args,    :to => :transition
+    delegate :options, :to => :transition
+
+    def binding
+      transition.binding
+    end
+
+    attr_reader :transition, :__target__, :__self__
+
+    alias_method :t,                    :transition
+    alias_method :current_transition,   :transition
+    alias_method :context,              :transition
+    alias_method :ctx,                  :transition
+
+    alias_method :arguments,            :args
+    alias_method :transition_arguments, :args
+
+    def machine 
+      binding.machine
+    end
+    
+    def states
+      machine.states
+    end
+    # delegate :machine, :to => :transition
+
+    def evaluate_with_arguments method_name_or_proc, *arguments
+      if method_name_or_proc.is_a?(Proc) && meth = method_name_or_proc
+      elsif meth = transition.machine.named_procs[method_name_or_proc]
+      elsif respond_to?( method_name_or_proc) && meth = method(method_name_or_proc)        
+      elsif method_name_or_proc.to_s =~ /^not?_(.*)$/
+        # special case: prefix a method with no_ or not_ and get the 
+        # boolean opposite of its evaluation result
+        return !( evaluate_with_arguments $1, *args )
+      else
+        raise NoMethodError.new( "undefined method_name `#{method_name_or_proc.to_s}' for \"#{__target__}\":#{__target__.class.to_s}" )
+      end      
+
+      if arguments.length < meth.arity.abs && meth.arity != -1
+        # ensure we don't have too few arguments
+        raise ArgumentError.new([meth.arity, arguments.length].inspect) 
+      else
+        # ensure we don't pass too many arguments
+        arguments = arguments[0, meth.arity.abs]
+      end
+      
+      # execute it!
+      __target__.with_methods_on(self) do
+        self.instance_exec *arguments, &meth
+      end
+    end
+
+    def evaluate method_name_or_proc
+      arguments = [transition, args, __target__]
+      evaluate_with_arguments(method_name_or_proc, *arguments)
+    end
+
+    alias_method :executioner_respond_to?, :respond_to?
+
+    def respond_to? method_name, include_private = false
+      executioner_respond_to?(method_name, include_private) ||
+      __target__.__send__( :respond_to?, method_name, include_private )
+    end
+
+    alias_method :executioner_method, :method
+    def method method_name
+      begin
+        executioner_method(method_name)
+      rescue NameError
+        __target__.__send__ :method, method_name
+      end
+    end
+
+    private
+
+    # Forwards any missing method call to the \target.
+    # TODO / NOTE: we don't (can't ?) handle block arguments ...    
+    def method_missing(method_name, *args)
+      if __target__.respond_to?(method_name, true)
+        begin
+          meth = __target__.__send__ :method, method_name
+        rescue NameError
+          super
+        end
+        __target__.instance_exec( *args, &meth)
+      else # let's hope it's a named proc
+        evaluate_with_arguments(method_name, *args)
+      end
+      
+    end
+    
+    # NOTE: const_missing is not handled.
+  end
+end

data/lib/hooks.rb

@@ -0,0 +1,39 @@
+module StateFu
+
+  # TODO document structure / sequence of hooks elsewhere
+
+  module Hooks  #:nodoc
+
+    ALL_HOOKS = [[:machine, :before_all], # global before. prepare for any transition
+                 [:event,   :before],     # prepare for the event
+                 [:origin,  :exit],       # say goodbye!
+                 [:event,   :execute],    # do stuff here for the event
+                 [:target,  :entry],      # entry point. last chance to halt!
+                 [:event,   :after],      # clean up after transition 
+                 [:target,  :accepted],   # state is changed. Do something about it.
+                 [:machine, :after_all]]  # global after. close up shop.
+
+    EVENT_HOOKS   = ALL_HOOKS.select { |type, name| type == :event }
+    STATE_HOOKS   = ALL_HOOKS.select { |type, name| [:origin, :target].include?(type) }
+    MACHINE_HOOKS = ALL_HOOKS.select { |type, name| type == :machine }
+    HOOK_NAMES    = ALL_HOOKS.map(&:last)
+
+    # just turn the above into what each class needs
+    # and make it into a nice hash: { :name =>[ hook, ... ], ... }
+    def self.for( instance )
+      case instance
+      when State
+        STATE_HOOKS
+      when Event
+        EVENT_HOOKS
+      when Machine
+        MACHINE_HOOKS
+      when Sprocket
+        []
+      end.
+        map { |type, name| [name, [].extend( OrderedHash )] }.
+        to_h.extend( OrderedHash ).freeze
+    end
+
+  end
+end

data/lib/interface.rb

@@ -0,0 +1,132 @@
+module StateFu
+  module Interface
+    module SoftAlias
+
+      # define aliases that won't clobber existing methods - 
+      # so we can be liberal with them.
+      def soft_alias(x)
+        aliases  = [ x.to_a[0] ].flatten
+        original = aliases.shift
+        existing_method_names = (self.instance_methods | self.protected_instance_methods | self.private_instance_methods).map(&:to_sym)
+        taken, ok = aliases.partition { |a| existing_method_names.include?(a.to_sym) }
+        StateFu::Logger.debug("#{self.to_s} alias for ## #{original} already taken: #{taken.inspect}")  unless taken.empty?
+        ok.each { |a| alias_method a, original}
+      end
+      
+    end
+
+    module Aliases
+
+      def self.extended(base)
+        base.extend SoftAlias
+        base.class_eval do
+          # instance method aliases
+          soft_alias :state_fu          => [:stfu, :fu, :stateful, :workflow, :engine, :machine, :context]
+          soft_alias :state_fu_bindings => [:bindings, :workflows, :engines, :machines, :contexts]
+          soft_alias :state_fu!         => [:stfu!, :initialize_machines!, :initialize_state!]
+          class << self
+            extend SoftAlias
+            # class method aliases
+            soft_alias :state_fu_machine       => [:stfu, :state_fu, :workflow, :stateful, :statefully, :state_machine, :engine]
+            soft_alias :state_fu_machines      => [:stfus, :state_fus, :workflows, :engines]
+          end
+        end
+      end
+    end
+
+    # 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 (add :foo as class & instance accessor methods)
+
+      # 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, and definining it if a block is passed.
+      #
+      # Given a block, apply it to a StateFu::Lathe to define a
+      # machine, and return it.
+      #
+      # 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
+      #
+      # recognised options are:
+      #  :field_name - specify the field to use for persistence.
+      #  defaults to {machine_name}_field.
+      #
+      def state_fu_machine( *args, &block )
+        options = args.extract_options!.symbolize_keys!
+        name    = args[0] || DEFAULT
+        StateFu::Machine.for_class( self, name, options, &block )
+      end
+      alias_method :machine, :state_fu_machine
+
+      def state_fu_field_names
+        @_state_fu_field_names ||= {}
+      end
+
+      def state_fu_machines
+        @_state_fu_machines ||= {}
+      end
+      alias_method :machines, :state_fu_machines
+
+    end
+
+    # These methods grant access to StateFu::Binding objects, which
+    # are bundles of context encapsulating a StateFu::Machine, an instance
+    # of a class, and its current state in the machine.
+
+    module InstanceMethods
+
+      def state_fu_bindings
+        @_state_fu_bindings ||= {}
+      end
+
+      # A StateFu::Binding comes into being when it is first referenced.
+      #
+      # This is the accessor method through which an object instance (or developer)
+      # can access a StateFu::Machine, the object's current state, the
+      # methods which trigger event transitions, etc.
+
+      def state_fu_binding( name = DEFAULT )
+        name = name.to_sym 
+        if machine = self.class.state_fu_machines[name]
+          state_fu_bindings[name] ||= StateFu::Binding.new( machine, self, name )
+        else raise ArgumentError.new("No state machine called #{name} for #{self.class} #{self}")
+        end
+      end
+      alias_method :state_fu, :state_fu_binding
+
+      def current_state( name = DEFAULT )
+        state_fu_binding(name).current_state
+      end
+      
+      def next!(name = DEFAULT, *args, &block )
+        state_fu_binding(name).next! *args, &block
+      end
+      alias_method :next_state!,           :next!
+      alias_method :fire_next_transition!, :next!      
+
+      # Instantiate bindings for all machines, which ensures that persistence
+      # fields are intialized and event methods defined.
+      # 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!
+        MethodFactory.define_singleton_method(self, :initialize_state_fu!) { true }
+        self.class.state_fu_machines.keys.map { |n| state_fu_binding( n ) }
+      end
+
+    end # ClassMethods
+  end # Interface
+end # StateFu