finite_machine 0.10.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: edb4b2a96673bef5c94c26d477821d2e59a5f756
-  data.tar.gz: 518346cb8ac30326a5a9550f6b0b18bea9de5918
+  metadata.gz: e70496d1e626025a2c8ad75e0c66f5dfacb5d1c5
+  data.tar.gz: 30b266427c011d60d77254c0740d34c843a55732
 SHA512:
-  metadata.gz: d179ed858abc96e2776de1f45278b261ce50f8adccf1841420c334a4f2427d0999ee3cc46e40c263bff62cadbf68284a619d491f8ea8016cfa0d3c576d1dd40c
-  data.tar.gz: 2036811dac682bb9decb39a5c39e5cc7c026109db57e97946dd3ca26b8106d109eaecffd200c6c8481cf5c5fb3a5fff6eaae5ed188b9e4bd1ab2d3ea1276aa6a
+  metadata.gz: d7e2d93b571c333c64ec880d3665abdf1ca65b8abd4ba2389b7d6451ad179e4aca67c42811829bdb6cad23a61993efdaf1c225cb6927572222b6bb76828bec88
+  data.tar.gz: d72998f62c65ed6c5f74021926db45e99cfaf065665627f4a8f2e485215397c712326d80a36aa20e281879bb9d79dcab5f670d0ca71736d7bc6e09c4edb7182a

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+0.11.0 (Oct 11, 2015)
+
+* Add UndefinedTransition to mark self transition(e.i. no transition found)
+* Add StateDefinition for state query methods
+* Add #trigger and #trigger! to StateMachine to allow manual firing of events and split between dangerous and non-dangerous versions of api.
+* Change ThreadContext to require per thread setup
+* Change Transition to stop relying on global transitions
+* Change EventChain to manage all internal transitions
+* Change Subscribers to remove unnecessary parameter dependency
+* Change StateMachine public interface to clarify available methods
+* Change HookEvent to accept event name and from state
+* Remove Event class as duplicate of Transition
+* Remove unnecessary checks for StateMachine#can?
+* Fix bug in Transition with current transition matching
+* Fix bug in Observer with cancelling inside event callback
+
 0.10.2 (July 5, 2015)
 
 * Fix to run 'on_after' callbacks even when event cancalled by @craiglittle

data/Gemfile

@@ -5,7 +5,7 @@ gemspec
 group :development do
   gem 'pry',   '~> 0.10.1'
   gem 'rake',  '~> 10.4.2'
-  gem 'rspec', '~> 3.2.0'
+  gem 'rspec', '~> 3.3.0'
   gem 'yard',  '~> 0.8.7'
 end
 

data/README.md

@@ -1,3 +1,6 @@
+<div align="center">
+  <a href="http://peter-murach.github.io/finite_machine/"><img width="236" src="https://raw.githubusercontent.com/peter-murach/finite_machine/master/assets/finite_machine_logo.png" alt="finite machine logo" /></a>
+</div>
 # FiniteMachine
 [![Gem Version](https://badge.fury.io/rb/finite_machine.svg)][gem]
 [![Build Status](https://secure.travis-ci.org/peter-murach/finite_machine.svg?branch=master)][travis]
@@ -45,18 +48,19 @@ Or install it yourself as:
 ## Contents
 
 * [1. Usage](#1-usage)
-    * [1.1 Current](#11-current)
-    * [1.2 Initial](#12-initial)
-    * [1.3 Terminal](#13-terminal)
+    * [1.1 current](#11-current)
+    * [1.2 initial](#12-initial)
+    * [1.3 terminal](#13-terminal)
     * [1.4 is?](#14-is)
     * [1.5 can? and cannot?](#15-can-and-cannot)
-    * [1.6 states](#16-states)
-    * [1.7 target](#17-target)
-    * [1.8 Alias target](#18-alias-target)
-    * [1.9 restore!](#19-restore)
+    * [1.6 target](#16-target)
+    * [1.7 Alias target](#17-alias-target)
+    * [1.8 restore!](#18-restore)
+    * [1.9 states](#19-states)
+    * [1.10 event names](#110-event-names)
 * [2. Transitions](#2-transitions)
     * [2.1 Performing transitions](#21-performing-transitions)
-    * [2.2 Forcing transitions](#22-forcing-transitions)
+    * [2.2 Dangerous transitions](#22-dangerous-transitions)
     * [2.3 Asynchronous transitions](#23-asynchronous-transitions)
     * [2.4 Multiple from states](#24-multiple-from-states)
     * [2.5 From :any state](#25-from-any-state)
@@ -158,7 +162,7 @@ fm = FiniteMachine.define do
 end
 
 fm.current # => :none
-fm.start
+fm.start   # => true
 fm.current # => :green
 ```
 
@@ -253,9 +257,9 @@ When the terminal state has been specified, you can use `terminated?` method on
 
 ```ruby
 fm.terminated?  # => false
-fm.slow
+fm.slow         # => true
 fm.terminated?  # => false
-fm.stop
+fm.stop         # => true
 fm.terminated?  # => true
 ```
 
@@ -300,20 +304,12 @@ end
 fm.can?(:slow) # => true
 fm.can?(:stop) # => false
 
-fm.slow
+fm.slow                    # => true
 fm.can?(:stop, :breaks)    # => true
 fm.can?(:stop, :no_breaks) # => false
 ```
 
-### 1.6 states
-
-You can use the `states` method to return an array of all the states for a given state machine.
-
-```ruby
-fm.states # => [:none, :green, :yellow, :red]
-```
-
-### 1.7 target
+### 1.6 target
 
 If you need to execute some external code in the context of the current state machine use `target` helper.
 
@@ -376,7 +372,7 @@ fm = FiniteMachine.define do
 end
 ```
 
-### 1.8 Alias target
+### 1.7 Alias target
 
 If you need to better express the intention behind the target name, in particular when calling actions in callbacks, you can use the `alias_target` helper:
 
@@ -401,7 +397,7 @@ fm = FiniteMachine.define do
 end
 ```
 
-### 1.9 restore!
+### 1.8 restore!
 
 In order to set the machine to a given state and thus skip triggering callbacks use the `restore!` method:
 
@@ -411,6 +407,22 @@ fm.restore!(:neutral)
 
 This method may be suitable when used testing your state machine or in restoring the state from datastore.
 
+### 1.9 states
+
+You can use the `states` method to return an array of all the states for a given state machine.
+
+```ruby
+fm.states # => [:none, :green, :yellow, :red]
+```
+
+### 1.10 event names
+
+To find out all the event names supported by the state machine issue `event_names` method:
+
+```ruby
+fm.event_names # => [:init, :ready, :go, :stop]
+```
+
 ## 2 Transitions
 
 The `events` scope exposes the `event` helper to define possible state transitions.
@@ -434,23 +446,41 @@ The following methods trigger transitions for the example state machine.
 
 ### 2.1 Performing transitions
 
-In order to transition to the next reachable state, simply call the event's name on the **FiniteMachine** instance.
+In order to transition to the next reachable state, simply call the event's name on the **FiniteMachine** instance. If the transition succeeds the `true` value is returned, otherwise `false`.
 
 ```ruby
-fm.ready
+fm.ready         # => true
 fm.current       # => :yellow
 ```
 
-Furthermore, you can pass additional parameters with the method call that will be available in the triggered callback.
+If you prefer you can also use `trigger` method to fire any event by its name:
 
 ```ruby
-fm.go('Piotr!')
+fm.trigger(:ready)  # => true
+```
+
+Furthermore, you can pass additional parameters with the method call that will be available in the triggered callback as well as used by any present guarding conditions.
+
+```ruby
+fm.go('Piotr!')  # => true
 fm.current       # => :green
 ```
 
-### 2.2 Forcing transitions
+By default **FiniteMachine** will swallow all exceptions when and return `false` on failure. If you prefer to be notified when illegal transition occurs see [Dangerous transitions](#22-dangerous-transitions).
+
+### 2.2 Dangerous transitions
+
+When you declare event, for instance `ready`, the **FiniteMachine** will provide a dangerous version with a bang `ready!`. In the case when you attempt to perform illegal transition or **FiniteMachine** throws internall error, the state machine will propagate the errors. You can use handlers to decide how to handle errors on case by case basis see [6. Errors](#6-errors)
+
+```ruby
+fm.ready!  #  => raises FiniteMachine::InvalidStateError
+```
+
+If you prefer you can also use `trigger!` method to fire event:
 
-When you declare event, for instance `ready`, the **FiniteMachine** will provide a dangerous version with a bang `ready!`. In the case when you need to perform transition disregarding current state reachable states, the `ready!` will transition without any validations or callbacks.
+```ruby
+fm.trigger!(:ready)
+```
 
 ### 2.3 Asynchronous transitions
 
@@ -607,7 +637,7 @@ fm.go(:yellow) # doesn't transition
 fm.go          # raises ArgumentError
 ```
 
-**Note** If you specify condition with a given arguments then you need to call an event with the exact number of arguments, otherwise you will get `ArgumentError`. Thus in above scenario to prevent errors specify condition like so:
+**Note** If you specify condition with a given number of arguments then you need to call an event with the exact number of arguments, otherwise you will get `ArgumentError`. Thus in above scenario to prevent errors specify condition like so:
 
 ```ruby
 if: -> (context, *args) { ... }
@@ -805,7 +835,7 @@ end
 
 ## 5 Callbacks
 
-You can watch state machine events and the information they provide by registering a callback. The following 5 types of callbacks are available in **FiniteMachine**:
+You can watch state machine events and the information they provide by registering one or more predefined callback types. The following 5 types of callbacks are available in **FiniteMachine**:
 
 * `on_enter`
 * `on_transition`
@@ -813,9 +843,15 @@ You can watch state machine events and the information they provide by registeri
 * `on_before`
 * `on_after`
 
-Use the `callbacks` scope to introduce the listeners. You can register a callback to listen for state changes or events being triggered. Use the state or event name as a first parameter to the callback followed by a list arguments that you expect to receive.
+Use the `callbacks` scope to introduce the listeners. You can register a callback to listen for state changes or events being triggered.
+
+Use the state or event name as a first parameter to the callback helper followed by block with event argument and a list arguments that you expect to receive like so:
+
+```ruby
+on_enter :green { |event, a, b, c| ... }
+```
 
-When you subscribe to the `:green` state change, the callback will be called whenever someone instruments change for that state. The same will happen on subscription to event `ready`, namely, the callback will be called each time the state transition method is called.
+When you subscribe to the `:green` state change, the callback will be called whenever someone triggers event that transitions in or out of that state. The same will happen on subscription to event `ready`, namely, the callback will be called each time the state transition method is triggered regardless of the states it transitions from or to.
 
 ```ruby
 fm = FiniteMachine.define do
@@ -838,6 +874,8 @@ fm.ready(1, 2, 3)
 fm.go('Piotr!')
 ```
 
+**Note** Regardless of how the state is entered or exited, all the associated callbacks will be executed. This provides means for guaranteed initialization and cleanup.
+
 ### 5.1 on_enter
 
 The `on_enter` callback is executed before given state change is fired. By passing state name you can narrow down the listener to only watch out for enter state changes. Otherwise, all enter state changes will be watched.
@@ -878,8 +916,8 @@ event :go, :red => :yellow
 
 then by calling `go` event the following callbacks in the following sequence will be executed:
 
-* `on_before :go` - callback before the `go` event
 * `on_before` - generic callback before `any` event
+* `on_before :go` - callback before the `go` event
 * `on_exit :red` - callback for the `:red` state exit
 * `on_exit` - generic callback for exit from `any` state
 * `on_transition :yellow` - callback for the `:red` to `:yellow` transition
@@ -1325,7 +1363,7 @@ car.reverse_lights_on? # => true
 
 In order to integrate **FiniteMachine** with ActiveRecord simply add a method with state machine definition. You can also define the state machine in separate module to aid reusability. Once the state machine is defined use the `target` helper to reference the current class. Having defined `target` you call ActiveRecord methods inside the callbacks to persist the state.
 
-You can use the `restore!` method to specify which state the **FininteMachine** should be put back into as follows:
+You can use the `restore!` method to specify which state the **FiniteMachine** should be put back into as follows:
 
 ```ruby
 class Account < ActiveRecord::Base

data/lib/finite_machine.rb

@@ -16,11 +16,8 @@ require "finite_machine/async_proxy"
 require "finite_machine/async_call"
 require "finite_machine/hook_event"
 require "finite_machine/env"
-require "finite_machine/event"
-require "finite_machine/event_definition"
 require "finite_machine/event_queue"
 require "finite_machine/events_chain"
-require "finite_machine/hooks"
 require "finite_machine/logger"
 require "finite_machine/transition"
 require "finite_machine/transition_builder"
@@ -29,7 +26,6 @@ require "finite_machine/dsl"
 require "finite_machine/definition"
 require "finite_machine/state_machine"
 require "finite_machine/subscribers"
-require "finite_machine/state_parser"
 require "finite_machine/observer"
 require "finite_machine/listener"
 require "finite_machine/two_phase_lock"
@@ -53,9 +49,6 @@ module FiniteMachine
   # Returned when transition is cancelled in callback
   CANCELLED = 2
 
-  # Returned when transition has not changed the state
-  NOTRANSITION = 3
-
   # When transition between states is invalid
   TransitionError = Class.new(::StandardError)
 

data/lib/finite_machine/async_proxy.rb

@@ -4,7 +4,6 @@ module FiniteMachine
   # An asynchronous messages proxy
   class AsyncProxy
     include Threadable
-    include ThreadContext
 
     attr_threadsafe :context
 
@@ -25,7 +24,7 @@ module FiniteMachine
       callable   = Callable.new(method_name)
       async_call = AsyncCall.new(context, callable, *args, &block)
 
-      event_queue << async_call
+      context.event_queue << async_call
     end
   end # AsyncProxy
 end # FiniteMachine

data/lib/finite_machine/dsl.rb

@@ -89,7 +89,7 @@ module FiniteMachine
     # @api public
     def initial(value, options = {})
       state = (value && !value.is_a?(Hash)) ? value : raise_missing_state
-      name, self.defer, silent = parse(options)
+      name, self.defer, silent = *parse_initial(options)
       self.initial_event = name
       event(name, FiniteMachine::DEFAULT_STATE => state, silent: silent)
     end
@@ -191,7 +191,7 @@ module FiniteMachine
     #
     # @api public
     def handlers(&block)
-      errors.call(&block)
+      errors_dsl.call(&block)
     end
 
     # Decide whether to log transitions
@@ -207,27 +207,24 @@ module FiniteMachine
     #
     # @api private
     def initialize_attrs
-      attrs[:initial]  and initial(attrs[:initial])
-      attrs[:target]   and target(attrs[:target])
-      attrs[:terminal] and terminal(attrs[:terminal])
+      attrs[:initial]  && initial(attrs[:initial])
+      attrs[:target]   && target(attrs[:target])
+      attrs[:terminal] && terminal(attrs[:terminal])
       log_transitions(attrs.fetch(:log_transitions, false))
     end
 
     # Parse initial options
     #
-    # @param [Object] value
+    # @param [Hash] options
+    #   the options to extract for initial state setup
     #
     # @return [Array[Symbol,String]]
     #
     # @api private
-    def parse(value)
-      if value.is_a?(Hash)
-        [value.fetch(:event) { FiniteMachine::DEFAULT_EVENT_NAME },
-         value.fetch(:defer) { false },
-         value.fetch(:silent) { true }]
-      else
-        [FiniteMachine::DEFAULT_EVENT_NAME, false, true]
-      end
+    def parse_initial(options)
+      [options.fetch(:event) { FiniteMachine::DEFAULT_EVENT_NAME },
+       options.fetch(:defer) { false },
+       options.fetch(:silent) { true }]
     end
 
     # Raises missing state error
@@ -246,6 +243,7 @@ module FiniteMachine
 
   # A DSL for describing events
   class EventsDSL < GenericDSL
+    include Safety
     # Create event and associate transition
     #
     # @example
@@ -257,6 +255,7 @@ module FiniteMachine
     # @api public
     def event(name, attrs = {}, &block)
       sync_exclusive do
+        detect_event_conflict!(name)
         attributes = attrs.merge!(name: name)
         if block_given?
           merger = ChoiceMerger.new(machine, attributes)

data/lib/finite_machine/event_definition.rb

@@ -9,76 +9,73 @@ module FiniteMachine
   # @api private
   class EventDefinition
     include Threadable
-    include Safety
 
     # The current state machine
     attr_threadsafe :machine
 
-    # Initialize an EventBuilder
+    # Initialize an EventDefinition
     #
-    # @param [FiniteMachine::StateMachine] machine
+    # @param [StateMachine] machine
     #
     # @api private
     def initialize(machine)
-      @machine = machine
+      self.machine = machine
     end
 
     # Define transition event names as state machine events
     #
-    # @param [Transition] transition
-    #   the transition for which event definition is created
+    # @param [Symbol] event_name
+    #   the event name for which definition is created
     #
-    # @return [Transition]
+    # @return [nil]
     #
-    # @api private
-    def apply(transition)
-      name = transition.name
-      detect_event_conflict!(name)
-      if machine.singleton_class.send(:method_defined?, name)
-        machine.events_chain.insert(name, transition)
-      else
-        define_event_transition(name, transition)
-        define_event_bang(name)
-      end
-      transition
+    # @api public
+    def apply(event_name, silent = false)
+      define_event_transition(event_name, silent)
+      define_event_bang(event_name, silent)
     end
 
     private
 
     # Define transition event
     #
-    # @param [Symbol] name
+    # @param [Symbol] event_name
     #   the event name
     #
-    # @param [FiniteMachine::Transition] transition
-    #   the transition this event is associated with
+    # @param [Boolean] silent
+    #   if true don't trigger callbacks, otherwise do
     #
     # @return [nil]
     #
     # @api private
-    def define_event_transition(name, transition)
-      silent = transition.silent
-      _event = Event.new(machine, name: name, silent: silent)
-      _event << transition
-      machine.events_chain.add(name, _event)
-
-      machine.send(:define_singleton_method, name) do |*args, &block|
-        _event.trigger(*args, &block)
+    def define_event_transition(event_name, silent)
+      machine.send(:define_singleton_method, event_name) do |*data, &block|
+        if silent
+          machine.transition(event_name, *data, &block)
+        else
+          machine.trigger(event_name, *data, &block)
+        end
       end
     end
 
-    # Define event that skips validations
+    # Define event that skips validations and callbacks
     #
-    # @param [Symbol] name
+    # @param [Symbol] event_name
     #   the event name
     #
+    # @param [Boolean] silent
+    #   if true don't trigger callbacks, otherwise do
+    #
     # @return [nil]
     #
     # @api private
-    def define_event_bang(name)
-      machine.send(:define_singleton_method, "#{name}!") do
-        transitions   = machine.transitions[name]
-        machine.state = transitions.values[0]
+    def define_event_bang(event_name, silent)
+      machine.send(:define_singleton_method, "#{event_name}!") do |*data, &block|
+        if silent
+          machine.transition!(event_name, *data, &block)
+        else
+          machine.trigger!(event_name, *data, &block)
+        end
       end
     end
   end # EventBuilder