ruby-state-machine 0.0.3 → 0.0.4

data/History.txt

@@ -12,3 +12,10 @@
 
 * 1 minor enhancement:
   * Change ruby-state-mach -> ruby-state-machine
+
+== 0.0.3 2009-08-19
+
+* 1 minor enhancement:
+  * Add missing files
+
+

data/Manifest.txt

@@ -5,6 +5,8 @@ README.rdoc
 Rakefile
 config/website.yml
 lib/ruby-state-machine.rb
+lib/ruby-state-machine/bounded_array.rb
+lib/ruby-state-machine/state_machine.rb
 script/console
 script/destroy
 script/generate

data/PostInstall.txt

@@ -1,7 +1 @@
-
-For more information on ruby-state-machine, see http://ruby-state-machine.rubyforge.org
-
-NOTE: Change this information in PostInstall.txt 
-You can also delete it if you don't want it.
-
-
+For more information on ruby-state-machine, see http://ruby-state-mach.rubyforge.org

data/README.rdoc

@@ -16,17 +16,17 @@ FIX (describe your package)
 
 == REQUIREMENTS:
 
-* FIX (list of requirements)
+* None
 
 == INSTALL:
 
-* FIX (sudo gem install, anything else)
+* sudo gem install ruby-state-machine
 
 == LICENSE:
 
 (The MIT License)
 
-Copyright (c) 2009 FIXME full name
+Copyright (c) 2007-2009 Steven Miers
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/config/website.yml

@@ -1,2 +1,2 @@
 host: stevenmiers@rubyforge.org
-remote_dir: /var/www/gforge-projects/ruby-state-machine
+remote_dir: /var/www/gforge-projects/ruby-state-mach

data/lib/ruby-state-machine.rb

@@ -2,5 +2,5 @@ $:.unshift(File.dirname(__FILE__)) unless
   $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
 module RubyStateMachine
-  VERSION = '0.0.3'
+  VERSION = '0.0.4'
 end

data/lib/ruby-state-machine/bounded_array.rb

@@ -0,0 +1,8 @@
+class BoundedArray < Array
+  attr_accessor :bounded_size
+  def push(args)
+    super
+    @bounded_size ||= 10
+    shift until size <= bounded_size
+  end
+end

data/lib/ruby-state-machine/state_machine.rb

@@ -0,0 +1,242 @@
+require 'ruby-state-machine/bounded_array'
+
+# StateMachine
+# Simple and flexible state machine.  Define a state machine with an array of states,
+# an array of events, and one or more transition actions.  A transition can be
+# as simple as the symbol for the next state, a lambda (code) to execute.  Primitive
+# branching can also be achieved if necessary by using a "decider" instance method.
+# Please see StateMachine.state_transition for full details on the variations
+# available.  StateMachineTest also contains examples and unit tests for most (if not all)
+# of the available functionality.  See README for example.
+module StateMachine
+  def self.included(base)
+    base.extend StateMachine::ClassMethods
+  end
+  
+  
+  module ClassMethods  
+    attr_accessor :machine    
+    
+    # Create state machine with the following options:
+    #  states Array[symbols], each symbol is name of state
+    #  events Array[symbols], each symbol is name of event
+    #  default_state symbol, symbol is one of states
+    def state_machine(opts)
+      @machine = StateMachine::Machine.new(opts)
+      self.send(:include, StateMachine::InstanceMethods)
+    end      
+
+    # Add a transition to state machine with the following keys:
+    # :state=>state (symbol) for which transition is being declared
+    # :event=>event (symbol) which causes transition
+    # :decider=>name of instance method on state machine specialization that "decides"
+    #           next state in case of multiple actions for next state (see below).
+    #           Method in question should return name of next state, or name of action
+    #           if actions are named (not required).
+    # :next=>action to take for this transition, one of:
+    #     1) state name(symbol), or special symbol (:stay), which stays at current state
+    #     2) hash{:state=>state name(symbol), :action=>code/lambda(string), :name=>id of action, for decider}
+    #     3) array of 1 and/or 2.  Decider required in this case.      
+    #
+    # Example 1:
+    #   state_transition :state=>:c_state, :event=>:w_event, :decider => :c_state_decider, 
+    #     :next=>[
+    #       {:state=>:a_state, :action=>lambda{|o, args| o.increment_value(7)} }, 
+    #       {:state=>:b_state, :action=>lambda{|o, args| o.increment_value(-10)} }
+    #     ]        
+    #
+    # Example 2 (stays at current state):
+    #   state_transition :state=>:c_state, :event=>:y_event, :next=>{:state=>:stay, :action=>lambda{|o, args| o.increment_value(-3)}}
+    #                   
+    # Example 3:
+    #   state_transition :state=>:b_state, :event=>:z_event, :next=>:a_state
+    def state_transition(opts)
+      @machine.add_transition(opts)
+    end
+    
+    def default_state; @machine.default_state; end
+    def states; @machine.states; end
+    def events; @machine.events; end
+    def transitions; @machine.transitions; end
+    def next_state(*args); @machine.next_state(*args); end
+    def next_state_instruction(*args); @machine.next_state_instruction(*args); end
+  end
+  
+  module InstanceMethods
+    attr_accessor :event_history
+
+    def initialize(args=nil)
+      @current_state = default_state
+      @event_history = BoundedArray.new
+      #puts "Current state is #{@current_state} #{@current_state.class}"
+    end
+    
+    def send_event(event)
+      # puts "Sending event: #{event}"
+      check_current_state
+      next_state_instruction = self.class.next_state_instruction(@current_state, event)
+      if next_state_instruction.nil?
+        cs = @current_state
+        @current_state = default_state
+        puts "Returned to default state: [#{@current_state}]."
+        raise InvalidStateError, "No valid next state for #{cs} using event #{event} (#{cs.class}/#{event.class})." 
+      end
+      
+      if(next_state_instruction)
+        if(!String(next_state_instruction[:decider]).empty?)
+          # Decider present, call method:
+          decide_id = execute(next_state_instruction[:decider], event)
+          
+          # Error checking:
+          if String(decide_id).empty?
+            raise InvalidStateError, 
+              "Decider returned blank/nil for #{@current_state} using event #{event}.  Next state from decider: [#{decide_id.inspect}].  Possible next states are [#{next_state_instruction[:next].inspect}]"  
+          end
+          
+          # Find next state:
+          instruction = Array(next_state_instruction[:next]).detect { |i| 
+            i[:state].to_sym==decide_id.to_sym or i[:name].to_sym==decide_id.to_sym
+          } 
+
+          # Error checking:
+          if instruction.nil?
+            raise InvalidStateError, 
+              "No valid next instruction for #{@current_state} using event #{event}.  Next state from decider: [#{decide_id.inspect}(#{decide_id.class})].  Possible next states are [#{next_state_instruction[:next].inspect}]"  
+          end
+          
+          # Do it:
+          process_instruction(instruction, event)
+        else            
+          # Do it:
+          process_instruction(next_state_instruction[:next], event)
+        end
+        @current_state
+      end
+      @event_history.push(event)
+    end
+  
+    def current_state
+      check_current_state
+      @current_state
+    end
+    
+    def current_state=state
+      @current_state = state.to_sym
+    end
+    
+    def default_state
+      (self.class.default_state) ? self.class.default_state : self.class.states.first
+    end
+
+  private 
+          
+    def process_instruction(instruction, event)
+      if instruction.nil?
+        @current_state = default_state
+        puts "Returned to default state: [#{@current_state}]."
+        raise InvalidStateError, "No valid next instruction for #{@current_state} using event #{event}" 
+      end
+      
+      if(instruction.is_a?Symbol)
+        change_state(instruction)
+      else
+        #puts "Processing action: #{instruction[:action]}"
+        execute(instruction[:action], event)
+        change_state(instruction[:state])
+      end
+    end
+    
+    def execute(action, event)
+      unless action.nil?
+        if Symbol === action
+          self.method(action).call(:event=>event) 
+        else
+          action.call(self, :event=>event)
+        end
+      end
+    end
+    
+    def change_state(state_sym)
+      case(state_sym)
+        when :back
+          raise InvalidStateError, "Back is reserved but not yet implemented." 
+        when :stay
+          @current_state = @current_state # nop, but should queue
+        else
+          @current_state = state_sym    
+      end        
+    end
+    
+    def check_current_state
+      raise InvalidStateError, "No valid current state.  Please call super() from state machine impl." if @current_state.nil?
+    end
+          
+  end
+  
+  class Machine
+    attr_accessor :states
+    attr_accessor :events
+    attr_accessor :transitions
+    attr_accessor :default_state
+    
+    def initialize(opts)
+      @states=opts[:states].collect{|state| state.to_sym}
+      @events=opts[:events].collect{|event| event.to_sym}
+      @default_state=opts[:default_state].to_sym if opts[:default_state]
+      @transitions=[]
+    end
+    
+    def add_transition(opts)
+      new_opts=strings_to_sym(opts)
+      
+      # Some validation for arrays of actions:
+      if (new_opts[:next].is_a?Array)
+        if new_opts[:next].length==1
+          new_opts[:next] = new_opts[:next].first
+        elsif new_opts[:next].length>1
+          raise ArgumentError, "A decider must be present for multiple actions." if String(new_opts[:decider]).empty?
+        end
+      end
+      
+      @transitions << new_opts
+    end
+    
+    def strings_to_sym(hash)
+      new_hash=hash.dup
+      hash.each do |k, v| 
+        unless (v.nil? or (v.respond_to?:empty? and v.empty? ))
+          if (v.is_a?(Hash))
+            new_hash[k] = strings_to_sym(v)
+          elsif (v.is_a?(Array))
+            new_array = v.dup
+            v.each_with_index do |array_hash, index|
+              new_array[index] = strings_to_sym(array_hash) if array_hash.is_a?(Hash)
+            end
+            new_hash[k]=new_array
+          elsif (v.is_a?(String))
+            new_hash[k] = v.to_sym
+          end
+        end
+      end
+      new_hash
+    end
+    
+    # Next state (symbol only) for given state and event.
+    # (equivalent to next_state_instruction(state, event)[:next_state])
+    def next_state(state, event)
+      transition = next_state_instruction(state, event)
+      ns = transition ? transition[:next] : nil
+      (ns.is_a?Symbol) ? ns : ns && ns[:state]
+    end
+    
+    # Next state instruction (as hash) for given state and event:
+    def next_state_instruction(state, event)
+      @transitions.detect{|t| t[:state]==state and t[:event]==event}
+    end
+  end
+  
+  class InvalidStateError < Exception #:nodoc:
+    
+  end
+  
+end

data/website/index.html

@@ -5,7 +5,7 @@
   <link rel="stylesheet" href="stylesheets/screen.css" type="text/css" media="screen" />
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>
-      ruby state machine
+      ruby-state-machine
   </title>
   <script src="javascripts/rounded_corners_lite.inc.js" type="text/javascript"></script>
 <style>
@@ -30,21 +30,41 @@
 <body>
 <div id="main">
 
-    <h1>ruby state machine</h1>
+    <h1>ruby-state-machine</h1>
     <div class="sidebar">
-      <div id="version" class="clickable" onclick='document.location = "http://rubyforge.org/projects/ruby-state-machine"; return false'>
+      <div id="version" class="clickable" onclick='document.location = "http://rubyforge.org/projects/ruby-state-mach"; return false'>
         <p>Get Version</p>
-        <a href="http://rubyforge.org/projects/ruby-state-machine" class="numbers">0.0.3</a>
+        <a href="http://rubyforge.org/projects/ruby-state-mach" class="numbers">0.0.3</a>
       </div>
     </div>
-    <h2>What</h2>
+    <p>An enhanced state machine gem for ruby (doesn&#8217;t require Rails). Provides more robust <span class="caps">DSL</span> state declaration syntax than other state machines. Multiple &#8220;actions&#8221; per event (i.e., next state, labmda, or a &#8220;decider&#8221;.  Fully unit-tested &amp; documented.  Has been used in production for over 2 years.</p>
 <h2>Installing</h2>
 <p><pre class='syntax'><span class="ident">sudo</span> <span class="ident">gem</span> <span class="ident">install</span> <span class="ident">ruby</span><span class="punct">-</span><span class="ident">state</span><span class="punct">-</span><span class="ident">machine</span></pre></p>
-<h2>The basics</h2>
-<h2>Demonstration of usage</h2>
+<h2>Demonstration of usage<br />
+<pre class='syntax'>
+<span class="keyword">class </span><span class="class">SampleMachine</span>
+  <span class="ident">include</span> <span class="constant">StateMachine</span>
+  <span class="ident">state_machine</span> <span class="symbol">:states</span> <span class="punct">=&gt;</span> <span class="punct">[</span><span class="symbol">:a_state</span><span class="punct">,</span> <span class="symbol">:b_state</span><span class="punct">,</span> <span class="symbol">:c_state</span><span class="punct">,</span> <span class="symbol">:d_state</span><span class="punct">],</span> <span class="symbol">:events</span> <span class="punct">=&gt;</span> <span class="punct">[</span><span class="symbol">:w_event</span><span class="punct">,</span> <span class="symbol">:x_event</span><span class="punct">,</span> <span class="symbol">:y_event</span><span class="punct">,</span> <span class="symbol">:z_event</span><span class="punct">]</span>
+  <span class="ident">state_transition</span> <span class="symbol">:state=</span><span class="punct">&gt;</span><span class="symbol">:a_state</span><span class="punct">,</span> <span class="symbol">:event=</span><span class="punct">&gt;</span><span class="symbol">:x_event</span><span class="punct">,</span> <span class="symbol">:next=</span><span class="punct">&gt;</span><span class="symbol">:c_state</span>
+  <span class="ident">state_transition</span> <span class="symbol">:state=</span><span class="punct">&gt;</span><span class="symbol">:a_state</span><span class="punct">,</span> <span class="symbol">:event=</span><span class="punct">&gt;</span><span class="symbol">:y_event</span><span class="punct">,</span> <span class="symbol">:next=</span><span class="punct">&gt;</span><span class="symbol">:a_state</span>
+  <span class="ident">state_transition</span> <span class="symbol">:state=</span><span class="punct">&gt;</span><span class="symbol">:a_state</span><span class="punct">,</span> <span class="symbol">:event=</span><span class="punct">&gt;</span><span class="symbol">:z_event</span><span class="punct">,</span> <span class="symbol">:next=</span><span class="punct">&gt;</span><span class="symbol">:b_state</span>
+                                                            
+  <span class="ident">state_transition</span> <span class="symbol">:state=</span><span class="punct">&gt;</span><span class="symbol">:b_state</span><span class="punct">,</span> <span class="symbol">:event=</span><span class="punct">&gt;</span><span class="symbol">:w_event</span><span class="punct">,</span> <span class="symbol">:next=</span><span class="punct">&gt;</span><span class="symbol">:b_state</span>
+  <span class="ident">state_transition</span> <span class="symbol">:state=</span><span class="punct">&gt;</span><span class="symbol">:b_state</span><span class="punct">,</span> <span class="symbol">:event=</span><span class="punct">&gt;</span><span class="symbol">:y_event</span><span class="punct">,</span> <span class="symbol">:next=</span><span class="punct">&gt;</span><span class="symbol">:c_state</span>
+  <span class="ident">state_transition</span> <span class="symbol">:state=</span><span class="punct">&gt;</span><span class="symbol">:b_state</span><span class="punct">,</span> <span class="symbol">:event=</span><span class="punct">&gt;</span><span class="symbol">:z_event</span><span class="punct">,</span> <span class="symbol">:next=</span><span class="punct">&gt;</span><span class="symbol">:a_state</span>
+                                                            
+  <span class="ident">state_transition</span> <span class="symbol">:state=</span><span class="punct">&gt;</span><span class="symbol">:c_state</span><span class="punct">,</span> <span class="symbol">:event=</span><span class="punct">&gt;</span><span class="symbol">:x_event</span><span class="punct">,</span> <span class="symbol">:next=</span><span class="punct">&gt;</span><span class="symbol">:b_state</span>
+<span class="keyword">end</span>
+
+<span class="ident">sm</span> <span class="punct">=</span> <span class="constant">SampleMachine</span><span class="punct">.</span><span class="ident">new</span>
+<span class="ident">assert_equal</span><span class="punct">(</span><span class="symbol">:a_state</span><span class="punct">,</span> <span class="ident">sm</span><span class="punct">.</span><span class="ident">current_state</span><span class="punct">)</span>
+<span class="ident">sm</span><span class="punct">.</span><span class="ident">send_event</span><span class="punct">(</span><span class="symbol">:x_event</span><span class="punct">)</span>
+<span class="ident">assert_equal</span><span class="punct">(</span><span class="symbol">:c_state</span><span class="punct">,</span> <span class="ident">sm</span><span class="punct">.</span><span class="ident">current_state</span><span class="punct">)</span>
+
+</pre></h2>
+<p>For examples of other functionality, including branching, deciders, lambdas, etc, see test/test_state_machine.</p>
 <h2>Forum</h2>
 <p><a href="http://groups.google.com/group/ruby-state-machine">http://groups.google.com/group/ruby-state-machine</a></p>
-<p><span class="caps">TODO</span> &#8211; create Google Group &#8211; ruby-state-machine</p>
 <h2>How to submit patches</h2>
 <p>Read the <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/">8 steps for fixing other people&#8217;s code</a> and for section <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups">8b: Submit patch to Google Groups</a>, use the Google Group above.</p>
 <p><span class="caps">TODO</span> &#8211; pick <span class="caps">SVN</span> or Git instructions</p>
@@ -52,12 +72,9 @@
 <p><span class="caps">OOOORRRR</span></p>
 <p>You can fetch the source from either:</p>
 <ul>
-	<li>rubyforge: <span class="caps">MISSING</span> IN <span class="caps">ACTION</span></li>
+	<li>rubyforge: <a href="http://rubyforge.org/scm/?group_id=8855">http://rubyforge.org/scm/?group_id=8855</a></li>
 </ul>
-<p><span class="caps">TODO</span> &#8211; You can not created a RubyForge project, OR have not run <code>rubyforge config</code><br />
-yet to refresh your local rubyforge data with this projects&#8217; id information.</p>
-<p>When you do this, this message will magically disappear!</p>
-<p>Or you can hack website/index.txt and make it all go away!!</p>
+<pre>git clone git://rubyforge.org/ruby-state-machine.git</pre>
 <ul>
 	<li>github: <a href="http://github.com/GITHUB_USERNAME/ruby-state-machine/tree/master">http://github.com/GITHUB_USERNAME/ruby-state-machine/tree/master</a></li>
 </ul>
@@ -70,7 +87,7 @@ yet to refresh your local rubyforge data with this projects&#8217; id informatio
 <h3>Build and test instructions</h3>
 <pre>cd ruby-state-machine
 rake test
-rake install_gem</pre>
+</pre>
 <h2>License</h2>
 <p>This code is free to use under the terms of the <span class="caps">MIT</span> license.</p>
 <h2>Contact</h2>

data/website/index.txt

@@ -1,26 +1,40 @@
-h1. ruby state machine
-
-
-h2. What
+h1. ruby-state-machine
 
+An enhanced state machine gem for ruby (doesn't require Rails). Provides more robust DSL state declaration syntax than other state machines. Multiple "actions" per event (i.e., next state, labmda, or a "decider".  Fully unit-tested & documented.  Has been used in production for over 2 years.
 
 h2. Installing
 
 <pre syntax="ruby">sudo gem install ruby-state-machine</pre>
 
-h2. The basics
-
-
 h2. Demonstration of usage
-
-
+<pre syntax="ruby">
+class SampleMachine
+  include StateMachine
+  state_machine :states => [:a_state, :b_state, :c_state, :d_state], :events => [:w_event, :x_event, :y_event, :z_event]
+  state_transition :state=>:a_state, :event=>:x_event, :next=>:c_state
+  state_transition :state=>:a_state, :event=>:y_event, :next=>:a_state
+  state_transition :state=>:a_state, :event=>:z_event, :next=>:b_state
+                                                            
+  state_transition :state=>:b_state, :event=>:w_event, :next=>:b_state
+  state_transition :state=>:b_state, :event=>:y_event, :next=>:c_state
+  state_transition :state=>:b_state, :event=>:z_event, :next=>:a_state
+                                                            
+  state_transition :state=>:c_state, :event=>:x_event, :next=>:b_state
+end
+
+sm = SampleMachine.new
+assert_equal(:a_state, sm.current_state)
+sm.send_event(:x_event)
+assert_equal(:c_state, sm.current_state)
+
+</pre>
+
+For examples of other functionality, including branching, deciders, lambdas, etc, see test/test_state_machine.
 
 h2. Forum
 
 "http://groups.google.com/group/ruby-state-machine":http://groups.google.com/group/ruby-state-machine
 
-TODO - create Google Group - ruby-state-machine
-
 h2. How to submit patches
 
 Read the "8 steps for fixing other people's code":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/ and for section "8b: Submit patch to Google Groups":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups, use the Google Group above.
@@ -68,7 +82,7 @@ h3. Build and test instructions
 
 <pre>cd ruby-state-machine
 rake test
-rake install_gem</pre>
+</pre>
 
 
 h2. License

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: ruby-state-machine
 version: !ruby/object:Gem::Version 
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors: 
 - stevenmiers
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-08-18 00:00:00 -05:00
+date: 2009-08-19 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -42,6 +42,8 @@ files:
 - Rakefile
 - config/website.yml
 - lib/ruby-state-machine.rb
+- lib/ruby-state-machine/bounded_array.rb
+- lib/ruby-state-machine/state_machine.rb
 - script/console
 - script/destroy
 - script/generate