davidlee-state-fu 0.3.1 → 0.10.0

data/lib/state_fu/lathe.rb

@@ -7,26 +7,27 @@ module StateFu
   # lifecycle, circuit, syntax, etc.
   class Lathe
 
-    # NOTE: Sprocket is the abstract superclass of Event and State
+    # @state_or_event can be either nil (the main Lathe for a Machine)
+    # or contain a State or Event (a child lathe for a nested block)
 
-    attr_reader :machine, :sprocket, :options
+    attr_reader :machine, :state_or_event, :options
 
     # you don't need to call this directly.
-    def initialize( machine, sprocket = nil, options={}, &block )
-      @machine  = machine
-      @sprocket = sprocket
-      @options  = options.symbolize_keys!
+    def initialize( machine, state_or_event = nil, options={}, &block )
+      @machine        = machine
+      @state_or_event = state_or_event
+      @options        = options.symbolize_keys!
 
       # extend ourself with any previously defined tools
       machine.tools.inject_into( self )
 
-      if sprocket
-        sprocket.apply!( options )
+      if state_or_event
+        state_or_event.apply!( options )
       end
       if block_given?
         if block.arity == 1
-          if sprocket
-            yield sprocket
+          if state_or_event
+            yield state_or_event
           else
             raise ArgumentError
           end
@@ -36,95 +37,30 @@ module StateFu
       end
     end
 
-    private
+    #
+    # utility methods
+    #
 
     # a 'child' lathe is created by apply_to, to deal with nested
-    # blocks for states / events ( which are sprockets )
-    def child?
-      !!@sprocket
+    # blocks for states / events ( which are state_or_events )
+    def nested?
+      !!state_or_event
     end
+    alias_method :child?, :nested?
 
     # is this the toplevel lathe for a machine?
     def master?
-      !child?
+      !nested?
     end
 
+    # get the top level Lathe for the machine
     def master_lathe
       machine.lathe
     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
+    #
+    # methods for extending the DSL
+    #
 
     # helpers are mixed into all binding / transition contexts
     def helper( *modules )
@@ -139,21 +75,30 @@ module StateFu
     end
 
     #
-    # event definition
+    # event definition methods
     #
 
+    # Defines an event. Any options supplied will be added to the event,
+    # except :from and :to which are used to define the origin / target
+    # states. Successive invocations will _update_ (not replace) previously
+    # defined events; origin / target states and options are always
+    # accumulated, not clobbered.
+    #
+    # Several different styles of definition are available. Consult the
+    # specs / features for examples.
+
     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)
+      valid_in_context( State, nil )
+      if nested? && state_or_event.is_a?(State) # in state block
+        targets  = options.delete(:to) || options.delete(:transitions_to)
         evt      = define_event( name, options, &block )
-        evt.from sprocket unless sprocket.nil?
+        evt.from state_or_event unless state_or_event.nil?
         evt.to( targets ) unless targets.nil?
         evt
       else # in master lathe
         origins = options.delete( :from )
-        targets = options.delete( :to )
+        targets = options.delete( :to ) || options.delete(:transitions_to)
         evt     = define_event( name, options, &block )
         evt.from origins unless origins.nil?
         evt.to   targets unless targets.nil?
@@ -161,96 +106,191 @@ module StateFu
       end
     end
 
+    # compatibility methods for activemodel state machine ##############
+    def transitions(options={})
+      valid_in_context(Event)
+      options.symbolize_keys!
+
+      target  = options[:to]
+      origins = options[:from]
+      hook    = options[:on_transition]
+      evt     = state_or_event
+
+      if hook
+        evt.lathe() { triggers hook }
+      end
+      #
+      # TODO do some type checking
+      #
+      if origins && target
+        evt.add_to_sequence origins, target
+      end
+      evt
+    end
+
+
+    def state_event name, options={}, &block
+      valid_in_context State
+      options.symbolize_keys!
+      state    = state_or_event
+      targets  = options.delete(:to) || options.delete(:transitions_to)
+      evt      = define_state_or_event( Event, state.own_events, name, options, &block)
+      evt.from state
+      evt.to(targets) unless targets.nil?
+      evt
+    end
+
+    def event name, options={}, &block
+      options.symbolize_keys!
+      valid_in_context State, nil
+      if nested? && state_or_event.is_a?(State)  # in state block
+        targets  = options.delete(:to) || options.delete(:transitions_to)
+        evt      = define_event name, options, &block
+        evt.from state_or_event unless state_or_event.nil?
+        evt.to   targets  unless targets.nil?
+        evt
+      else # in master lathe
+        origins = options.delete(:from)|| options.delete(:transitions_from)
+        targets = options.delete(:to)  || options.delete(:transitions_to)
+        evt     = define_event name, options, &block
+        evt.from origins unless origins.nil?
+        evt.to   targets unless targets.nil?
+        evt
+      end
+    end
+
+
+    #####################################
+
+    # define an event or state requirement.
+    # options:
+    #  :on => :entry|:exit|array (state only) - check requirement on state entry, exit or both?
+    #     default = :entry
+    #  :message => string|proc|proc_name_symbol - message to be returned on requirement failure.
+    #     if a proc or symbol (named proc identifier), evaluated at runtime; a proc should
+    #     take one argument, which is a StateFu::Transition.
+    #  :msg => alias for :message, for the morbidly terse
+
     def requires( *args, &block )
-      require_sprocket( StateFu::Event, StateFu::State )
+      valid_in_context Event, State
       options = args.extract_options!.symbolize_keys!
-      options.assert_valid_keys(:on, :message, :msg )
+      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
+        raise ArgumentError.new(name.inspect) unless name.is_a?(Symbol)
+        case state_or_event
+        when 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
+          state_or_event.entry_requirements << name if on.include?( :entry )
+          state_or_event.exit_requirements  << name if on.include?( :exit  )
+        when Event
+          state_or_event.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 :guard,        :requires
     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 )
+    def cycle name=nil, options={}, &block
+      _state = nil
+      if name.is_a?(Hash) && options.empty?
+        options = name
+        name    = nil
+      end
+      if _state = options.delete(:state)
+        valid_unless_nested("when :state is supplied")
+      else
+        _state = state_or_event
+        valid_in_context( State, "unless :state is supplied" )
+      end
+
+      name ||= options.delete :on
+      name ||= "cycle_#{_state.to_sym}"
       evt = define_event( name, options, &block )
-      evt.from sprocket
-      evt.to   sprocket
+      evt.from _state
+      evt.to   _state
       evt
-      # raise NotImplementedError
     end
 
     #
     # state definition
     #
 
-    def initial_state( *args, &block )
-      require_no_sprocket()
+    # define the initial_state (otherwise defaults to the first state mentioned)
+    def initial_state *args, &block
+      valid_unless_nested()
       machine.initial_state= state( *args, &block)
     end
 
-    def state( name, options={}, &block )
-      require_no_sprocket()
+    # define a state; given a block, apply the block to a Lathe for the state
+    def state name, options={}, &block
+      valid_unless_nested()
       define_state( name, options, &block )
     end
 
+    # define a named proc
+    def define method_name, &block
+      machine.named_procs[method_name] = block
+    end
+    alias_method :named_proc, :define
+
+    #
+    # Event definition
+    #
+
+    # set the origin state(s) of an event (or, given a hash of symbols / arrays
+    # of symbols, set both the origins and targets)
+    # from :my_origin
+    # from [:column_a, :column_b]
+    # from :eden => :armageddon
+    # from [:beginning, :prelogue] => [:ende, :prologue]
     def from *args, &block
-      require_sprocket( StateFu::Event )
-      sprocket.from( *args, &block )
+      valid_in_context Event
+      state_or_event.from( *args, &block )
     end
 
+    # set the target state(s) of an event
+    # to :destination
+    # to [:end, :finale, :intermission]
     def to *args, &block
-      require_sprocket( StateFu::Event )
-      sprocket.to( *args, &block )
+      valid_in_context Event
+      state_or_event.to( *args, &block )
     end
 
     #
     # define chained events and states succinctly
     # usage: chain 'state1 -event1-> state2 -event2-> state3'
-    def chain (string)
+    def chain string
       rx_word    = /([a-zA-Z0-9_]+)/
       rx_state   = /^#{rx_word}$/
-      rx_event   = /^-#{rx_word}->$/
+      rx_event   = /^(?:-|>)#{rx_word}-?>$/
       previous   = nil
       string.split.each do |chunk|
         case chunk
         when rx_state
-          current = state($1)
-          if previous.is_a?( StateFu::Event )
-            previous.to( current )
+          current = state $1
+          if previous.is_a? Event
+            previous.to current
           end
         when rx_event
-          current = event($1)
-          if previous.is_a?( StateFu::State )
-            current.from( previous )
+          current = event $1
+          if previous.is_a? State
+            current.from previous
           end
         else
           raise ArgumentError, "'#{chunk}' is not a valid token"
@@ -259,40 +299,213 @@ module StateFu
       end
     end
 
-    #
-    # do something with all states / events
-    #
-    def each_sprocket( type, *args, &block)
-
-      options = args.extract_options!.symbolize_keys!
-      if args == [:ALL] || args == []
-        args = machine.send("#{type}s").except( options.delete(:except) )
+    # chain_states :a => [:b,:c], :c => :d, :c => :d
+    # chain_states :a,:b,:c,:d, :a => :c
+    def connect_states *array, &b
+      array.flatten!
+      hash = array.extract_options!.symbolize_keys!
+      array.inject(nil) do |origin, target|
+        state target
+        if origin
+          event "#{origin.to_sym}_to_#{target.to_sym}", :from => origin, :to => target
+        end
+        origin = target
+      end
+      hash.each do |origin, target|
+        event "#{origin.to_sym}_to_#{target.to_sym}", :from => origin, :to => target
       end
-      args.map { |name| self.send( type, name, options.dup, &block) }.extend StateArray
     end
+    alias_method :connect, :connect_states
 
-    def states( *args, &block )
-      require_no_sprocket()
-      each_sprocket( 'state', *args, &block )
+    #
+    # Define a series of states at once, or return and iterate over all states yet defined
+    #
+    def states *args, &block
+      valid_unless_nested()
+      each_state_or_event 'state', *args, &block
     end
     alias_method :all_states, :states
     alias_method :each_state, :states
 
-    def events( *args, &block )
-      require_sprocket( NilClass, StateFu::State )
-      each_sprocket( 'event', *args, &block )
+    #
+    # Define a series of events at once, or return and iterate over all events yet defined
+    #
+    def events *args, &block
+      valid_in_context nil, State
+      each_state_or_event 'event', *args, &block
     end
     alias_method :all_events, :events
     alias_method :each_event, :events
 
     # Bunch of silly little methods for defining events
+    #:nodoc
+
+    def before     *a, &b; valid_in_context Event; define_hook :before,     *a, &b; end
+    def on_exit    *a, &b; valid_in_context State; define_hook :exit,       *a, &b; end
+    def execute    *a, &b; valid_in_context Event; define_hook :execute,    *a, &b; end
+    def on_entry   *a, &b; valid_in_context State; define_hook :entry,      *a, &b; end
+    def after      *a, &b; valid_in_context Event; define_hook :after,      *a, &b; end
+    def accepted   *a, &b; valid_in_context State; define_hook :accepted,   *a, &b; end
+
+    def before_all *a, &b; valid_in_context nil;   define_hook :before_all, *a, &b; end
+    def after_all  *a, &b; valid_in_context nil;   define_hook :after_all,  *a, &b; end
+
+    alias_method :after_everything,  :after_all
+    alias_method :before_everything, :before_all
+
+    def after_all *a
+    end
+
+    def will *a, &b
+      valid_in_context State, Event
+      case state_or_event
+      when State
+        define_hook :entry, *a, &b
+      when Event
+        define_hook :execute, *a, &b
+      end
+    end
+    alias_method :fire,     :will
+    alias_method :fires ,   :will
+    alias_method :firing,   :will
+    alias_method :cause,    :will
+    alias_method :causes,   :will
+    alias_method :triggers, :will
+    alias_method :trigger,  :will
+    alias_method :trigger,  :will
+
+    alias_method :on_change, :accepted
+    #
+    #
+    #
+
+    private
+
+    # require that the current state_or_event be of a given type
+    def valid_in_context *valid_types
+      if valid_types.last.is_a?(String)
+        msg = valid_types.pop << " "
+      else
+        msg = ""
+      end
+      unless valid_types.include?( state_or_event.class ) || valid_types.include?(nil) && state_or_event.nil?
+        v = valid_types.dup.map do |t|
+          {
+            nil   => "if not nested inside a block",
+            State => "inside a state definition block",
+            Event => "inside an event definition block"
+          }[t]
+        end
+        msg << "this command is only valid " << v.join(',')
+        raise ArgumentError, msg
+      end
+    end
 
-    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
+    # ensure this is not a child lathe
+    def valid_unless_nested(msg = nil)
+      valid_in_context( nil, msg )
+    end
+
+    # instantiate a child Lathe and apply the given block
+    def apply_to state_or_event, options, &block
+      StateFu::Lathe.new( machine, state_or_event, options, &block )
+      state_or_event
+    end
+
+    # abstract method for defining states / events
+    def define_state_or_event klass, collection, name, options={}, &block
+      name = name.to_sym
+      req  = nil
+      msg  = nil
+      options.symbolize_keys!
+
+      # allow requirements and messages to be added as options
+      if k = [:requires, :guard, :must, :must_be, :needs].detect {|k| options.has_key?(k) }
+        # Logger.debug("removing option #{k} - will use as requirement ..")
+        req = options.delete(k)
+        msg = options.delete(:message) || options.delete(:msg)
+        raise ArgumentError unless msg.nil? || req.is_a?(Symbol)
+        raise ArgumentError unless ([req, msg].map(&:class) - [String, Symbol, Proc, NilClass]).empty?
+      end
+      # TODO? allow hooks to be defined as options
+
+      unless state_or_event = collection[name]
+        state_or_event  = klass.new machine, name, options
+        collection << state_or_event
+      end
+
+      apply_to state_or_event, options, &block
+
+      if req # install requirements
+        state_or_event.requirements << req
+        machine.requirement_messages[req] = msg if msg
+      end
+
+      state_or_event
+    end
+
+    #:nodoc
+    def define_state name, options={}, &block
+      collection = machine.states
+      define_state_or_event State, collection, name, options, &block
+    end
+
+    #:nodoc
+    def define_event name, options={}, &block
+      collection = machine.events
+      define_state_or_event Event, collection, name, options, &block
+    end
+
+    #:nodoc
+    def define_hook slot, *method_names, &block
+      raise "wtf" unless machine.is_a?(Machine)
+      hooks = (slot.to_s =~ /_all/ ? machine.hooks : state_or_event.hooks)
+      unless hooks.has_key? slot
+        raise ArgumentError, "invalid hook type #{slot.inspect} for #{state_or_event.class}"
+      end
+      if block_given?
+        method_name = method_names.first
+        # 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 nil
+          hook = block
+          # allow only one anonymous hook per slot in the interests of
+          # sanity - replace any pre-existing ones
+          hooks[slot].delete_if { |h| Proc === h }
+        else
+          raise ArgumentError.new method_name.inspect
+        end
+        hooks[slot] << hook
+      else
+        method_names.each do |method_name|
+          if method_name.is_a? Symbol # no block
+            hook = method_name
+            # prevent duplicates
+            hooks[slot].delete_if { |h| hook == h }
+            hooks[slot] << hook
+          else
+            raise ArgumentError, "#{method_name.class} is not a symbol"
+          end
+        end
+      end
+
+    end
+
+    #:nodoc
+    def each_state_or_event type, *args, &block
+      options = args.extract_options!.symbolize_keys!
+      if args.empty? || args  == [:ALL]
+        args = machine.send("#{type}s").except options.delete(:except)
+      end
+      args.map do |name|
+        self.send type, name, options.dup, &block
+      end.extend ArrayWithSymbolAccessor
+    end
 
   end
 end