ruby-state-machine 0.0.3 → 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 665d443a898a9f324aa6c3940c99287be592a92a
+  data.tar.gz: dad2a4f3bda51408aae0a0dcb9d456052bc7ee6f
+SHA512:
+  metadata.gz: e42f12cfd35f6b1e787627262d4ec3d1776bc0e6e412ac1513c883e21389cc677b7c023a4a9613869cc2ca0a8623b08ab4b3b3acf9a3ca87685031638a4f9ff2
+  data.tar.gz: 5c709191cdab80cc7b21ee2eaecb5d66d33194fea49eecb2d5e584a83baf1aded13896b528fe771aefa04e862ae1eadb46eba0922cade197ecc01fa0833ebf3d

data/README.md

@@ -0,0 +1,86 @@
+## Ruby State Machine
+Ruby State Machine (ruby-state-machine) is a full-featured state machine gem for use within ruby.  It can also be used in Rails.  This was written because we required a state machine that allowed different actions to be performed based on the previous and current events, as well as injecting logic (a "decider") to determine the next event.  
+
+## Installation:
+
+Add this line to your application's Gemfile:
+
+    gem 'ruby-state-machine'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ruby-state-machine
+
+## Location:
+Here: http://github.com/tangledpath/ruby-state-machine
+
+RDocs: http://ruby-state-mach.rubyforge.org/
+
+
+## USAGE:
+
+```ruby
+require 'ruby-state-machine/state_machine'
+
+# Note, a state machine is not created directly; instead, the behavior of a state
+# machine is added through a mixin, e.g.:
+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 # Define next state for :a_state when :x_event is sent
+  state_transition :state=>:a_state, :event=>:y_event, :next=>:a_state # Define next state for :a_state when :y_event is sent
+  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
+puts sm.current_state # :a_state
+sm.send_event(:x_event)
+puts sm.current_state # :c_state
+```
+
+For examples of other functionality, including branching, deciders, lambdas, etc, see http://ruby-state-mach.rubyforge.org/StateMachine/ClassMethods.html#state_transition-instance_method.
+
+
+## CONTRIBUTE
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2007-2013 Steven Miers
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/lib/ruby-state-machine.rb

@@ -1,6 +1,6 @@
-$:.unshift(File.dirname(__FILE__)) unless
-  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+require "ruby-state-machine/version"
+#require "ruby-state-machine/state_machine"
 
 module RubyStateMachine
-  VERSION = '0.0.3'
+  
 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,252 @@
+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.
+#
+# The {StateMachineTest} (view source) also contains examples and unit tests for most (if not all)
+# of the available functionality.  
+# Also see {http://ruby-state-mach.rubyforge.org/ README} for examples
+# @see ClassMethods#state_transition StateTransition for full details on the variations available.
+# @see StateMachineTest
+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
+      # Attempt to call super:
+      begin
+        super(args)
+      rescue ArgumentError
+        super() 
+      end
+      #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
+        # This was causing problems in unit tests:
+        # @current_state = default_state
+        # puts "Returned to default state: [#{@current_state}]."
+        raise InvalidStateError, "No valid next state for #{cs.inspect} using event #{event.inspect} (#{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/lib/ruby-state-machine/version.rb

@@ -0,0 +1,8 @@
+module RubyStateMachine
+  module VERSION
+    MAJOR = 1
+    MINOR = 2
+    TINY  = 0
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

metadata

@@ -1,85 +1,50 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: ruby-state-machine
-version: !ruby/object:Gem::Version 
-  version: 0.0.3
+version: !ruby/object:Gem::Version
+  version: 1.2.0
 platform: ruby
-authors: 
-- stevenmiers
-autorequire: 
+authors:
+- tangledpath
+autorequire:
 bindir: bin
 cert_chain: []
-
-date: 2009-08-18 00:00:00 -05:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: hoe
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: 2.3.3
-    version: 
-description: FIX (describe your package)
-email: 
+date: 2020-11-04 00:00:00.000000000 Z
+dependencies: []
+description: A ruby state machine
+email:
 - steven.miers@gmail.com
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
-- History.txt
-- Manifest.txt
-- PostInstall.txt
-- website/index.txt
-files: 
-- History.txt
-- Manifest.txt
-- PostInstall.txt
-- README.rdoc
-- Rakefile
-- config/website.yml
+extra_rdoc_files:
+- README.md
+files:
+- README.md
 - lib/ruby-state-machine.rb
-- script/console
-- script/destroy
-- script/generate
-- script/txt2html
-- test/test_helper.rb
-- test/test_state_machine.rb
-- website/index.html
-- website/index.txt
-- website/javascripts/rounded_corners_lite.inc.js
-- website/stylesheets/screen.css
-- website/template.html.erb
-has_rdoc: true
-homepage: http://github.com/#{github_username}/#{project_name}
-post_install_message: PostInstall.txt
-rdoc_options: 
-- --main
-- README.rdoc
-require_paths: 
+- lib/ruby-state-machine/bounded_array.rb
+- lib/ruby-state-machine/state_machine.rb
+- lib/ruby-state-machine/version.rb
+homepage: http://github.com/tangledpath/ruby-state-machine
+licenses: []
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  requirements: 
+- ext
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
   - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-  version: 
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  requirements: 
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
   - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-  version: 
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
-rubyforge_project: ruby-state-mach
-rubygems_version: 1.3.1
-signing_key: 
-specification_version: 2
-summary: FIX (describe your package)
-test_files: 
-- test/test_helper.rb
-- test/test_state_machine.rb
+rubyforge_project: ruby-state-machine
+rubygems_version: 2.6.10
+signing_key:
+specification_version: 4
+summary: A full-featured state machine gem for use within ruby.
+test_files: []