end_state 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 04263dcaee90aaa630e9e16fd1648a71717b5c49
-  data.tar.gz: 1e5cba77cd2f71faa5792ba9374f7c14c941dda9
+  metadata.gz: a553419c7a74efd09772b41ad579948834f8c190
+  data.tar.gz: 6ab1ee4bffc24168b8bf31320cb85aa632384a72
 SHA512:
-  metadata.gz: f9e25308af4b71252f6e3709949077ffe7dee67312aea2eff0e310848b8f1215c2fa84f6259901ceee0a0560ee6e5dd6b6064c81720c87fc19cb1ce5a9962dd2
-  data.tar.gz: 4d9db32fc84ae115f6f6ae02e0a901f1f366351bc6291ae6c535f5633b12347fab002fb67322f627bb152f8084ff4c1e7adf773221fd4150b2f0fd01b5a7f979
+  metadata.gz: 9360ba21fe5b2ce44808682ef5501d6cb8542bc9e227b4510e47cc0a812f35cd5923c0b46550a687714b3f09431ee60894d556f3fa8c00b2c442b2248f09e0bb
+  data.tar.gz: 571df2a52aa71250e347e608f05fad04bd04b32628cec368c19f76492af033061fe2c673959410c35015730de329aeddaf66f468ddde5434833eb58f37be07ac

data/README.md

@@ -196,6 +196,48 @@ class Machine < EndState::StateMachine
 end
 ```
 
+## Events
+
+By using the `as` option in a transition definition you are creating an event representing that transition.
+This can allow you to exercise the machine in a more natural "verb" style interaction. When using `as` event
+definitions you can optionally set a `blocked` message on the transition. When the event is executed, if the
+machine is not in a state maching the initial state of the event, the message is added to the `failure_messages`
+array on the machine.
+
+```
+class Machine < EndState::StateMachine
+  transition a: :b, as: :go do |t|
+    t.blocked 'Cannot go!'
+  end
+end
+
+machine = Machine.new(StatefulObject.new(:a))
+
+machine.go!                 # => true
+machine.state               # => :b
+machine.go!                 # => false
+machine.failure_messages    # => ['Cannot go!']
+```
+
+## State storage
+
+You may want to use an attribute other than `state` to track the state of the machine.
+
+```
+class Machine < EndState::StateMachine
+  state_attribute :status
+end
+```
+
+Depending on how you persist the `state` (if at all) you may want what is stored in `state` to be a string instead
+of a symbol. You can tell the machine this preference.
+
+```
+class Machine < EndState::StateMachine
+  store_states_as_strings!
+end
+```
+
 ## Exceptions for failing Transitions
 
 By default `transition` will only raise an exception, `EndState::UnknownState`, if called with a state that doesn't exist.
@@ -211,6 +253,11 @@ If you install `GraphViz` and the gem `ruby-graphviz` you can create images repr
 
 `EndState::Graph.new(MyMachine).draw.output png: 'my_machine.png'`
 
+If you use events in your machine, it will add the events along the arrow representing the transition. If you don't want this,
+pass in false when contructing the Graph.
+
+`EndState::Graph.new(MyMachine, false).draw.output png: 'my_machine.png'`
+
 ## Testing
 
 Included is a custom RSpec matcher for testing your machines.

data/lib/end_state/action.rb

@@ -8,7 +8,7 @@ module EndState
     end
 
     def call
-      object.state = state
+      object.state = object.class.store_states_as_strings ? state.to_s : state.to_sym
       true
     end
 

data/lib/end_state/graph.rb

@@ -1,10 +1,11 @@
 module EndState
   class Graph < GraphViz
-    attr_reader :machine, :nodes
+    attr_reader :machine, :nodes, :event_labels
 
-    def initialize(machine)
+    def initialize(machine, event_labels=true)
       @machine = machine
       @nodes = {}
+      @event_labels = event_labels
       super machine.name.to_sym
     end
 
@@ -13,7 +14,13 @@ module EndState
         left, right = t.to_a.flatten
         nodes[left] ||= add_node(left.to_s)
         nodes[right] ||= add_node(right.to_s)
-        add_edge nodes[left], nodes[right]
+        edge = add_edge nodes[left], nodes[right]
+        if event_labels
+          event = machine.events.detect do |event, transition|
+            transition.include? t
+          end
+          edge[:label] = event.first.to_s if event
+        end
       end
       self
     end

data/lib/end_state/state_machine.rb

@@ -2,16 +2,24 @@ module EndState
   class StateMachine < SimpleDelegator
     attr_accessor :failure_messages, :success_messages
 
+    def self.store_states_as_strings!
+      @store_states_as_strings = true
+    end
+
+    def self.store_states_as_strings
+      !!@store_states_as_strings
+    end
+
     def self.transition(state_map)
       initial_states = Array(state_map.keys.first)
       final_state = state_map.values.first
       transition_alias = state_map[:as] if state_map.keys.length > 1
       transition = Transition.new(final_state)
       initial_states.each do |state|
-        transitions[{ state => final_state }] = transition
+        transitions[{ state.to_sym => final_state.to_sym }] = transition
       end
       unless transition_alias.nil?
-        aliases[transition_alias] = final_state
+        events[transition_alias.to_sym] = initial_states.map { |s| { s.to_sym => final_state.to_sym } }
       end
       yield transition if block_given?
     end
@@ -20,8 +28,8 @@ module EndState
       @transitions ||= {}
     end
 
-    def self.aliases
-      @aliases ||= {}
+    def self.events
+      @events ||= {}
     end
 
     def self.state_attribute(attribute)
@@ -41,26 +49,23 @@ module EndState
       transitions.keys.map { |state_map| state_map.values.first }.uniq
     end
 
-    def self.transition_state_for(check_state)
-      return check_state if states.include? check_state
-      return aliases[check_state] if aliases.keys.include? check_state
-    end
-
     def object
       __getobj__
     end
 
-    def can_transition?(state)
-      previous_state = self.state
+    def can_transition?(state, params = {})
+      previous_state = self.state.to_sym
+      state = state.to_sym
       transition = self.class.transitions[{ previous_state => state }]
       return block_transistion(transition, state, :soft) unless transition
-      transition.will_allow? state
+      transition.will_allow? state, params
     end
 
     def transition(state, params = {}, mode = :soft)
       @failure_messages = []
       @success_messages = []
-      previous_state = self.state
+      previous_state = self.state ? self.state.to_sym : self.state
+      state = state.to_sym
       transition = self.class.transitions[{ previous_state => state }]
       return block_transistion(transition, state, mode) unless transition
       return guard_failed(state, mode) unless transition.allowed?(self, params)
@@ -75,10 +80,11 @@ module EndState
 
     def method_missing(method, *args, &block)
       check_state = method.to_s[0..-2].to_sym
-      check_state = self.class.transition_state_for(check_state)
-      return super if check_state.nil?
+      check_state = state_for_event(check_state) || check_state
+      return false if check_state == :__invalid_event__
+      return super unless self.class.states.include?(check_state)
       if method.to_s.end_with?('?')
-        state == check_state
+        state.to_sym == check_state
       elsif method.to_s.end_with?('!')
         transition check_state, args[0]
       else
@@ -88,12 +94,25 @@ module EndState
 
     private
 
+    def state_for_event(event)
+      transitions = self.class.events[event]
+      return false unless transitions
+      return invalid_event(event) unless transitions.map { |t| t.keys.first }.include?(state)
+      transitions.first.values.first
+    end
+
+    def invalid_event(event)
+      message = self.class.transitions[self.class.events[event].first].blocked_event_message
+      @failure_messages = [message] if message
+      :__invalid_event__
+    end
+
     def block_transistion(transition, state, mode)
       if self.class.end_states.include? state
         fail UnknownTransition, "The transition: #{object.state} => #{state} is unknown." if mode == :hard
         return false
       end
-      fail UnknownState, "The state: #{state} is unknown." unless transition
+      fail UnknownState, "The state: #{state} is unknown."
     end
 
     def guard_failed(state, mode)

data/lib/end_state/transition.rb

@@ -1,6 +1,6 @@
 module EndState
   class Transition
-    attr_reader :state
+    attr_reader :state, :blocked_event_message
     attr_accessor :action, :guards, :finalizers
 
     def initialize(state)
@@ -42,6 +42,10 @@ module EndState
       finalizer Finalizers::Persistence
     end
 
+    def blocked(message)
+      @blocked_event_message = message
+    end
+
     private
 
     def rollback(finalized, object, previous_state, params)

data/lib/end_state/version.rb

@@ -1,3 +1,3 @@
 module EndState
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/tasks/end_state.rake

@@ -1,14 +1,15 @@
 namespace :end_state do
-  desc 'Draw the statemachine using GraphViz (options: machine=MyMachine, format=png, output=machine.png'
+  desc 'Draw the statemachine using GraphViz (options: machine=MyMachine, format=png, output=machine.png, event_labels=false)'
   task :draw do
     options = {}
     options[:machine] = ENV['machine']
     options[:format] = ENV['format'] || :png
     options[:output] = ENV['output'] || "#{options[:machine].to_s}.#{options[:format].to_s}"
+    options[:event_labels] = !(ENV['event_labels'] == 'false')
     if options[:machine]
       EndState::Graph.new(Object.const_get(options[:machine])).draw.output options[:format] => options[:output]
     else
       puts 'A machine is required'
     end
   end
-end
+end

data/spec/end_state/action_spec.rb

@@ -6,6 +6,8 @@ module EndState
     let(:object) { OpenStruct.new(state: nil) }
     let(:state) { :a }
 
+    before { object.stub_chain(:class, :store_states_as_strings).and_return(false) }
+
     describe '#call' do
       it 'changes the state to the new state' do
         action.call

data/spec/end_state/finalizer_spec.rb

@@ -3,7 +3,7 @@ require 'spec_helper'
 module EndState
   describe Finalizer do
     subject(:finalizer) { Finalizer.new(object, state, params) }
-    let(:object) { Struct.new('Machine', :failure_messages, :success_messages, :state).new }
+    let(:object) { Struct.new('Machine', :failure_messages, :success_messages, :state, :store_states_as_strings).new }
     let(:state) { :a }
     let(:params) { {} }
     before do

data/spec/end_state/guard_spec.rb

@@ -3,7 +3,7 @@ require 'spec_helper'
 module EndState
   describe Guard do
     subject(:guard) { Guard.new(object, state, params) }
-    let(:object) { Struct.new('Machine', :failure_messages, :success_messages, :state).new }
+    let(:object) { Struct.new('Machine', :failure_messages, :success_messages, :state, :store_states_as_strings).new }
     let(:state) { :a }
     let(:params) { {} }
     before do

data/spec/end_state/state_machine_spec.rb

@@ -7,7 +7,8 @@ module EndState
     let(:object) { OpenStruct.new(state: nil) }
     before do
       StateMachine.instance_variable_set '@transitions'.to_sym, nil
-      StateMachine.instance_variable_set '@aliases'.to_sym, nil
+      StateMachine.instance_variable_set '@events'.to_sym, nil
+      StateMachine.instance_variable_set '@store_states_as_strings'.to_sym, nil
     end
 
     describe '.transition' do
@@ -30,7 +31,7 @@ module EndState
       context 'when the :as option is used' do
         it 'creates an alias' do
           StateMachine.transition(state_map.merge(as: :go))
-          expect(StateMachine.aliases[:go]).to eq :b
+          expect(StateMachine.events[:go]).to eq [{ a: :b }]
         end
       end
     end
@@ -83,6 +84,19 @@ module EndState
       specify { expect(StateMachine.end_states).to eq [:b, :c] }
     end
 
+    describe '.store_states_as_strings!' do
+      it 'sets the flag' do
+        StateMachine.store_states_as_strings!
+        expect(StateMachine.store_states_as_strings).to be_true
+      end
+    end
+
+    describe '#store_states_as_strings' do
+      it 'is false by default' do
+        expect(StateMachine.store_states_as_strings).to be_false
+      end
+    end
+
     describe '#state' do
       context 'when the object has state :a' do
         let(:object) { OpenStruct.new(state: :a) }
@@ -121,7 +135,9 @@ module EndState
     describe '#{state}!' do
       let(:object) { OpenStruct.new(state: :a) }
       before do
-        StateMachine.transition a: :b, as: :go
+        StateMachine.transition a: :b, as: :go do |t|
+          t.blocked 'Invalid event!'
+        end
       end
 
       it 'transitions the state' do
@@ -135,10 +151,24 @@ module EndState
         expect(machine).to have_received(:transition).with(:b, { foo: 'bar', bar: 'foo' })
       end
 
-      it 'works with an alias' do
+      it 'works with an event' do
         machine.go!
         expect(machine.state).to eq :b
       end
+
+      context 'when the intial state is :c' do
+        let(:object) { OpenStruct.new(state: :c) }
+
+        it 'blocks invalid events' do
+          machine.go!
+          expect(machine.state).to eq :c
+        end
+
+        it 'adds a failure message specified by blocked' do
+          machine.go!
+          expect(machine.failure_messages).to eq ['Invalid event!']
+        end
+      end
     end
 
     describe '#can_transition?' do
@@ -182,6 +212,15 @@ module EndState
             machine.transition :b
             expect(object.state).to eq :b
           end
+
+          context 'and the machine is set to store_states_as_strings' do
+            before { StateMachine.store_states_as_strings! }
+
+            it 'transitions the state stored as a string' do
+              machine.transition :b
+              expect(object.state).to eq 'b'
+            end
+          end
         end
 
         context 'and a guard is configured' do

data/spec/end_state/transition_spec.rb

@@ -15,6 +15,13 @@ module EndState
       end
     end
 
+    describe '#blocked' do
+      it 'sets the blocked event message' do
+        transition.blocked 'This is blocked.'
+        expect(transition.blocked_event_message).to eq 'This is blocked.'
+      end
+    end
+
     describe '#guard' do
       let(:guard) { double :guard }
 
@@ -93,7 +100,10 @@ module EndState
       let(:finalizer) { double :finalizer, new: finalizer_instance }
       let(:finalizer_instance) { double :finalizer_instance, call: nil, rollback: nil }
       let(:object) { OpenStruct.new(state: :b) }
-      before { transition.finalizers << finalizer }
+      before do
+        object.stub_chain(:class, :store_states_as_strings).and_return(false)
+        transition.finalizers << finalizer
+      end
 
       context 'when all finalizers succeed' do
         before { finalizer_instance.stub(:call).and_return(true) }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: end_state
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - alexpeachey
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-30 00:00:00.000000000 Z
+date: 2014-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler