end_state 0.12.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b964eec779e3cb4ab2214bfaf0da1b048f4e9b43
-  data.tar.gz: c48a186f6bf7229369818e1faf01a46d287dcee3
+  metadata.gz: 4431610a8257edd10bd8ba72d453f7f6f318c19b
+  data.tar.gz: 3ed496c73b2935568bc12571c0c7d1982446d92f
 SHA512:
-  metadata.gz: aca9ba0ae25ef8eb95c988a157ebe487681225feef8785605c2b7414b01725f5b2b733b3fee830b26d65135ccf75e67bb47db6da411b679984ec46dc815f9bc7
-  data.tar.gz: 8b92ab95a97116056c9aa2331410ebf0ba1a29e641e73345ce5cc9c33ba83cd5e110b4752a5eaab3cf244a7137a39288f01aaf1df670f76dd837fa9eae92ac7a
+  metadata.gz: bdea6ed04d7c9e582264e60ed287c5d7fca801f58e1a81732aaca61e80f0ec50d773cd8a54feb3aa582f5562be6b5ed9be2615ac2faa6765d8939ac9a6dc7b1f
+  data.tar.gz: 1157ea3e2e91b2406fa9377b2ed44d86bb35015ae75e20bc405aeb58145267d9d72806e8653f4fbd5f26bf4fb8245f7dda44313e4166caf542b5963a2d769f11

data/.travis.yml

@@ -1,3 +1,3 @@
 language: ruby
 rvm:
-  - 2.1.1
+  - 2.1

data/Gemfile

@@ -2,4 +2,5 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in end_state.gemspec
 gemspec
+gem 'coveralls', require: false
 gem 'ruby-graphviz'

data/README.md

@@ -1,3 +1,7 @@
+[![Build Status](https://travis-ci.org/Originate/end_state.svg?branch=master)](https://travis-ci.org/Originate/end_state)
+[![Code Climate](https://codeclimate.com/github/Originate/end_state/badges/gpa.svg)](https://codeclimate.com/github/Originate/end_state)
+[![Coverage Status](https://coveralls.io/repos/Originate/end_state/badge.png)](https://coveralls.io/r/Originate/end_state)
+
 # EndState
 
 EndState is an unobtrusive way to add state machines to your application.
@@ -32,8 +36,8 @@ Transitions can be named by adding an `:as` option.
 class Machine < EndState::StateMachine
   transition parked: :idling, as: :start
   transition idling: :first_gear, first_gear: :second_gear, second_gear: :third_gear, as: :shift_up
-  transition third_gear: :second_gear, second_gear: :first_gear, as: shift_down
-  transition first_gear: :idling, as: idle
+  transition third_gear: :second_gear, second_gear: :first_gear, as: :shift_down
+  transition first_gear: :idling, as: :idle
   transition [:idling, :first_gear] => :parked, as: :park
 end
 ```
@@ -239,17 +243,12 @@ 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 the initial state of the event, the message is added to the `failure_messages`
-array on the machine. Events, like `transition` have both a standard and a bang (`!`) style. The bang style
-will raise an exception if there is a problem.
+This can allow you to exercise the machine in a more natural "verb" style interaction. Events, like `transition`
+have both a standard and a bang (`!`) style. The bang style will raise an exception if there is a problem.
 
 ```ruby
 class Machine < EndState::StateMachine
-  transition a: :b, as: :go do |t|
-    t.blocked 'Cannot go!'
-  end
+  transition a: :b, as: :go
 end
 
 machine = Machine.new(StatefulObject.new(:a))
@@ -257,7 +256,6 @@ machine = Machine.new(StatefulObject.new(:a))
 machine.go                  # => true
 machine.state               # => :b
 machine.go                  # => false
-machine.failure_messages    # => ['Cannot go!']
 machine.go!                 # => raises InvalidTransition
 ```
 

data/end_state.gemspec

@@ -22,4 +22,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec'
   spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'simplecov'
 end

data/lib/end_state/concluder.rb

@@ -14,7 +14,6 @@ module EndState
     end
 
     def rollback
-      true
     end
   end
 end

data/lib/end_state/graph.rb

@@ -10,19 +10,23 @@ module EndState
     end
 
     def draw
-      machine.transitions.keys.each do |t|
-        left, right = t.to_a.flatten
-        nodes[left] ||= add_nodes(left.to_s)
-        nodes[right] ||= add_nodes(right.to_s)
-        edge = add_edges 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
+      add_transitions
       self
     end
+
+    private
+
+    def add_transitions
+      machine.transition_configurations.each do |start_state, end_state, _, event|
+        add_transition(start_state, end_state, event)
+      end
+    end
+
+    def add_transition start_state, end_state, event
+      nodes[start_state] ||= add_node(start_state.to_s)
+      nodes[end_state] ||= add_node(end_state.to_s)
+      edge = add_edge nodes[start_state], nodes[end_state]
+      edge[:label] = event.to_s if event && event_labels
+    end
   end
 end

data/lib/end_state/no_graph.rb

@@ -0,0 +1,12 @@
+module EndState
+  class Graph
+    def initialize(machine, event_labels=true)
+      @machine = machine
+      @event_labels = event_labels
+    end
+
+    def draw
+      self
+    end
+  end
+end

data/lib/end_state/state_machine.rb

@@ -1,139 +1,78 @@
 module EndState
   class StateMachine < SimpleDelegator
+    extend StateMachineConfiguration
+
     attr_accessor :failure_messages, :success_messages
 
     def initialize(object)
       super
-      Action.new(self, self.class.initial_state).call if self.state.nil?
-    end
-
-    @initial_state = :__nil__
-    @mode = :soft
-
-    def self.initial_state
-      @initial_state
-    end
-
-    def self.set_initial_state(state)
-      @initial_state = state.to_sym
-    end
-
-    def self.treat_all_transitions_as_hard!
-      @mode = :hard
-    end
-
-    def self.mode
-      @mode
-    end
-
-    def self.store_states_as_strings!
-      @store_states_as_strings = true
+      Action.new(self, self.class.initial_state).call if state.nil?
     end
 
-    def self.store_states_as_strings
-      !!@store_states_as_strings
+    def object
+      __getobj__
     end
 
-    def self.transition(state_map)
-      transition_alias = state_map.delete(:as)
-      transition_alias = transition_alias.to_sym unless transition_alias.nil?
-
-      state_map.each do |start_states, end_state|
-        transition = Transition.new(end_state)
-
-        Array(start_states).each do |start_state|
-          state_mapping = StateMapping[start_state.to_sym => end_state.to_sym]
-          transitions[state_mapping] = transition
-          __sm_add_event(transition_alias, state_mapping) unless transition_alias.nil?
-        end
-
-        yield transition if block_given?
-      end
+    def can_transition?(end_state, params = {})
+      return false unless __sm_transition_configuration_for(state, end_state)
+      __sm_transition_for(end_state).will_allow?(params)
     end
 
-    def self.transitions
-      @transitions ||= {}
+    def transition(end_state, params = {}, mode = self.class.mode)
+      __sm_reset_messages
+      return __sm_block_transistion(end_state, mode) unless __sm_transition_configuration_for(state, end_state)
+      __sm_transition_for(end_state, mode).call(params)
     end
 
-    def self.events
-      @events ||= {}
+    def transition!(end_state, params = {})
+      transition end_state, params, :hard
     end
 
-    def self.state_attribute(attribute)
-      define_method(:state) { send(attribute.to_sym) }
-      define_method(:state=) { |val| send("#{attribute}=".to_sym, val) }
+    def method_missing(method, *args, &block)
+      return super unless __sm_is_method?(method)
+      return __sm_predicate(method) if __sm_is_state_predicate?(method)
+      __sm_event_transition __sm_event(method), args[0] || {}, __sm_event_mode(method)
     end
 
-    def self.states
-      (start_states + end_states).uniq
-    end
+    private
 
-    def self.start_states
-      transitions.keys.map(&:start_state).uniq
+    def __sm_is_method?(method)
+      __sm_is_state_predicate?(method) || __sm_is_event?(method)
     end
 
-    def self.end_states
-      transitions.keys.map(&:end_state).uniq
+    def __sm_predicate(method)
+      __sm_current_state? __sm_extract_state(method)
     end
 
-    def object
-      __getobj__
+    def __sm_extract_state(method)
+      method.to_s[0..-2].to_sym
     end
 
-    def can_transition?(state, params = {})
-      previous_state = self.state.to_sym
-      state = state.to_sym
-      transition = __sm_transition_for(previous_state, state)
-      return __sm_block_transistion(transition, state, :soft) unless transition
-      transition.will_allow? state, params
-    end
-
-    def transition(state, params = {}, mode = self.class.mode)
-      @failure_messages = []
-      @success_messages = []
-      previous_state = self.state ? self.state.to_sym : self.state
-      state = state.to_sym
-      transition = __sm_transition_for(previous_state, state)
-      mode = __sm_actual_mode(mode)
-      return __sm_block_transistion(transition, state, mode) unless transition
-      return __sm_guard_failed(state, mode) unless transition.allowed?(self, params)
-      return false unless transition.action.new(self, state).call
-      return __sm_conclude_failed(state, mode) unless transition.conclude(self, previous_state, params)
-      true
+    def __sm_event(method)
+      method.to_s.gsub('!','').to_sym
     end
 
-    def transition!(state, params = {})
-      transition state, params, :hard
+    def __sm_event_mode(method)
+      return :hard if method.to_s.end_with?('!')
+      __sm_actual_mode(:soft)
     end
 
-    def method_missing(method, *args, &block)
-      return super unless __sm_predicate_or_event?(method)
-      return __sm_current_state?(method) if __sm_state_predicate(method)
-      new_state, mode = __sm_event(method)
-      return false if new_state == :__invalid_event__
-      transition new_state, (args[0] || {}), mode
+    def __sm_is_state_predicate?(method)
+      method.to_s.end_with?('?') && self.class.states.include?(__sm_extract_state(method))
     end
 
-    private
-
-    def __sm_predicate_or_event?(method)
-      __sm_state_predicate(method) ||
-      __sm_event(method)
+    def __sm_is_event?(method)
+      self.class.events.include? __sm_event(method)
     end
 
-    def __sm_state_predicate(method)
-      state = method.to_s[0..-2].to_sym
-      return unless self.class.states.include?(state) && method.to_s.end_with?('?')
-      state
+    def __sm_current_state?(end_state)
+      state.to_sym == end_state
     end
 
-    def __sm_event(method)
-      event = __sm_state_for_event(method.to_sym, __sm_actual_mode(:soft))
-      return event, __sm_actual_mode(:soft) if event
-      return unless method.to_s.end_with?('!')
-      event = __sm_state_for_event(method.to_s[0..-2].to_sym, :hard)
-      return event, :hard if event
-      nil
+    def __sm_event_transition(event, params, mode)
+      end_state = __sm_state_for_event(event, mode)
+      return false if end_state == :__invalid_event__
+      transition end_state, params, mode
     end
 
     def __sm_actual_mode(mode)
@@ -141,32 +80,28 @@ module EndState
       mode
     end
 
-    def __sm_current_state?(method)
-      state.to_sym == __sm_state_predicate(method)
-    end
-
     def __sm_state_for_event(event, mode)
-      state_mappings = self.class.events[event]
-      return false unless state_mappings
-      state_mappings.each do |state_mapping|
-        return state_mapping.end_state if state_mapping.matches_start_state?(state.to_sym)
-      end
-      return __sm_invalid_event(event, mode)
+      self.class.transition_configurations.get_end_state(state.to_sym, event) || __sm_invalid_event(event, mode)
     end
 
     def __sm_invalid_event(event, mode)
       fail InvalidTransition, "Transition by event: #{event} is invalid." if mode == :hard
-      message = self.class.transitions[self.class.events[event].first].blocked_event_message
-      @failure_messages = [message] if message
       :__invalid_event__
     end
 
-    def __sm_transition_for(from, to)
-      self.class.transitions[{ from => to }] ||
-      self.class.transitions[{ any_state: to }]
+    def __sm_transition_configuration_for(start_state, end_state)
+      self.class.transition_configurations.get_configuration(start_state, end_state)
     end
 
-    def __sm_block_transistion(transition, state, mode)
+    def __sm_transition_for(end_state, mode = self.class.mode)
+      start_state = state.to_sym
+      end_state = end_state.to_sym
+      configuration = __sm_transition_configuration_for(start_state, end_state)
+      mode = __sm_actual_mode(mode)
+      Transition.new(self, start_state, end_state, configuration, mode)
+    end
+
+    def __sm_block_transistion(state, mode)
       if self.class.end_states.include? state
         fail InvalidTransition, "The transition: #{object.state} => #{state} is invalid." if mode == :hard
         return false
@@ -174,29 +109,9 @@ module EndState
       fail UnknownState, "The state: #{state} is unknown."
     end
 
-    def __sm_guard_failed(state, mode)
-      return false unless mode == :hard
-      fail GuardFailed, "The transition to #{state} was blocked: #{failure_messages.join(', ')}"
-    end
-
-    def __sm_conclude_failed(state, mode)
-      return false unless mode == :hard
-      fail ConcluderFailed, "The transition to #{state} was rolled back: #{failure_messages.join(', ')}"
-    end
-
-    def self.__sm_add_event(event, state_mapping)
-      events[event] ||= []
-      conflicting_mapping = events[event].find{ |sm| sm.conflicts?(state_mapping) }
-      if conflicting_mapping
-        message =
-          "Attempting to define :#{event} as transitioning from " \
-          ":#{state_mapping.start_state} => :#{state_mapping.end_state} when " \
-          ":#{conflicting_mapping.start_state} => :#{conflicting_mapping.end_state} already exists. " \
-          "You cannot define multiple transitions from a single state with the same event name."
-
-        fail EventConflict, message
-      end
-      events[event] << state_mapping
+    def __sm_reset_messages
+      @failure_messages = []
+      @success_messages = []
     end
   end
 end

data/lib/end_state/state_machine_configuration.rb

@@ -0,0 +1,77 @@
+module EndState
+  module StateMachineConfiguration
+    @initial_state = :__nil__
+    @mode = :soft
+
+    def initial_state
+      @initial_state
+    end
+
+    def set_initial_state(state)
+      @initial_state = state.to_sym
+    end
+
+    def treat_all_transitions_as_hard!
+      @mode = :hard
+    end
+
+    def mode
+      @mode
+    end
+
+    def store_states_as_strings!
+      @store_states_as_strings = true
+    end
+
+    def store_states_as_strings
+      !!@store_states_as_strings
+    end
+
+    def transition(state_map)
+      event = state_map.delete(:as)
+      event = event.to_sym unless event.nil?
+
+      configuration = TransitionConfiguration.new
+      yield configuration if block_given?
+
+      state_map.each do |start_states, end_state|
+        Array(start_states).each do |start_state|
+          prevent_event_conflicts(start_state, event)
+          transition_configurations.add(start_state, end_state, configuration, event)
+        end
+      end
+    end
+
+    def transition_configurations
+      @transition_configurations ||= TransitionConfigurationSet.new
+    end
+
+    def state_attribute(attribute)
+      define_method(:state) { send(attribute.to_sym) }
+      define_method(:state=) { |val| send("#{attribute}=".to_sym, val) }
+    end
+
+    def events
+      transition_configurations.events
+    end
+
+    def states
+      (start_states + end_states).uniq
+    end
+
+    def start_states
+      transition_configurations.start_states
+    end
+
+    def end_states
+      transition_configurations.end_states
+    end
+
+    private
+
+    def prevent_event_conflicts(start_state, event)
+      return unless transition_configurations.event_conflicts?(start_state, event)
+      fail EventConflict, "Attempting to define event '#{event}' on state '#{start_state}', but it is already defined. (Check duplicates and use of 'any_state')"
+    end
+  end
+end

data/lib/end_state/transition.rb

@@ -1,82 +1,68 @@
 module EndState
   class Transition
-    attr_reader :state, :blocked_event_message
-    attr_accessor :action, :guards, :concluders, :allowed_params, :required_params
+    attr_reader :configuration, :mode, :object, :previous_state, :state
 
-    def initialize(state)
+    def initialize(object, previous_state, state, configuration, mode)
+      @object = object
+      @previous_state = previous_state
       @state = state
-      @action = Action
-      @guards = []
-      @concluders = []
-      @allowed_params = []
-      @required_params = []
+      @configuration = configuration
+      @mode = mode
     end
 
-    def allowed?(object, params={})
+    def call(params={})
+      return guard_failed unless allowed?(params)
+      return false unless action.new(object, state).call
+      return conclude_failed unless conclude(params)
+      true
+    end
+
+    def allowed?(params={})
       raise "Missing params: #{missing_params(params).join(',')}" unless missing_params(params).empty?
       guards.all? { |guard| guard.new(object, state, params).allowed? }
     end
 
-    def will_allow?(object, params={})
+    def will_allow?(params={})
       return false unless missing_params(params).empty?
       guards.all? { |guard| guard.new(object, state, params).will_allow? }
     end
 
-    def conclude(object, previous_state, params={})
-      concluders.each_with_object([]) do |concluder, concluded|
-        concluded << concluder
-        return rollback(concluded, object, previous_state, params) unless run_concluder(concluder, object, state, params)
-      end
-      true
-    end
-
-    def custom_action(action)
-      @action = action
-    end
+    private
 
-    def guard(*guards)
-      Array(guards).flatten.each { |guard| self.guards << guard }
+    def failed(error, message)
+      return false unless mode == :hard
+      fail error, "The transition to #{state} was #{message}: #{object.failure_messages.join(', ')}"
     end
 
-    def concluder(*concluders)
-      Array(concluders).flatten.each { |concluder| self.concluders << concluder }
+    def guard_failed
+      failed GuardFailed, 'blocked'
     end
 
-    def persistence_on
-      concluder Concluders::Persistence
+    def conclude_failed
+      failed ConcluderFailed, 'rolled back'
     end
 
-    def allow_params(*params)
-      Array(params).flatten.each do |param|
-        self.allowed_params << param unless self.allowed_params.include? param
-      end
-    end
-
-    def require_params(*params)
-      Array(params).flatten.each do |param|
-        self.allowed_params << param unless self.allowed_params.include? param
-        self.required_params << param unless self.required_params.include? param
+    def conclude(params={})
+      concluders.each_with_object([]) do |concluder, concluded|
+        concluded << concluder
+        return rollback(concluded, params) unless concluder.new(object, state, params).call
       end
+      true
     end
 
-    def blocked(message)
-      @blocked_event_message = message
-    end
-
-    private
-
-    def rollback(concluded, object, previous_state, params)
+    def rollback(concluded, params)
+      concluded.reverse_each { |concluder| concluder.new(object, state, params).rollback }
       action.new(object, previous_state).rollback
-      concluded.reverse.each { |concluder| concluder.new(object, state, params).rollback }
       false
     end
 
-    def run_concluder(concluder, object, state, params)
-      concluder.new(object, state, params).call
-    end
-
     def missing_params(params)
       required_params.select { |key| params[key].nil? }
     end
+
+    [:action, :concluders, :guards, :required_params].each do |method|
+      define_method(method) { configuration.public_send(method) }
+      private method
+    end
   end
 end

data/lib/end_state/transition_configuration.rb

@@ -0,0 +1,49 @@
+module EndState
+  class TransitionConfiguration
+    attr_reader :action, :allowed_params, :concluders, :guards, :required_params
+
+    def initialize
+      @action = Action
+      @allowed_params = []
+      @concluders = []
+      @guards = []
+      @required_params = []
+    end
+
+    def custom_action(action)
+      @action = action
+    end
+
+    def guard(*guards)
+      Array(guards).flatten.each { |guard| self.guards << guard }
+    end
+
+    def concluder(*concluders)
+      Array(concluders).flatten.each { |concluder| self.concluders << concluder }
+    end
+
+    def persistence_on
+      concluder Concluders::Persistence
+    end
+
+    def allow_params(*params)
+      Array(params).flatten.each do |param|
+        append_unless_included(:allowed_params, param)
+      end
+    end
+
+    def require_params(*params)
+      Array(params).flatten.each do |param|
+        append_unless_included(:allowed_params, param)
+        append_unless_included(:required_params, param)
+      end
+    end
+
+    private
+
+    def append_unless_included(name, value)
+      attribute = self.send(name)
+      attribute << value unless attribute.include? value
+    end
+  end
+end