finite_machine 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1b14a2db5bcab11179dbd4cd9abd10826cda11e1
-  data.tar.gz: 1b5046cc5cb28b7cd082bce38088ed34c66d6aba
+  metadata.gz: 605485a3bc03f37c758232982a53c6a1454f3f75
+  data.tar.gz: ea94531b99ed2901d14a801388ab26e220f0b6df
 SHA512:
-  metadata.gz: 340d0ff2ea70b6f54127e06c2d2d6f7fe44309e44f5c8c10125aee29a363d8587890369cca037a7b09d614396f8758919f7b2cea67cdca8f15ed5e2679c1315a
-  data.tar.gz: 0372935e0396e9863700879fb906330d191d2f013d844eae8af58b4853a94b23a6b547c797779da77aeaf71db5fb38d38031ef4f7134864b2708aa900633f06a
+  metadata.gz: ac08b6ac004a47a21c6ff3c104b470ebb50b083c3f692f6ce5d865ed2b6527cf0e58dce4983bfd08ed2d000ea5b80277895befada19e26e326506b6326d1bf1f
+  data.tar.gz: b00888c384d18a8f1654b11b26e53a6024c8da9127139ee4f6e3f906c1c0a03f7a5f85982f2af28f494b6097d4ddcdce86401f6bf532ead9a7bda2084418c01c

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+0.9.0 (August 3, 2014)
+
+* Add Definition class to allow to define standalone state machine
+* Upgrade RSpec dependency and refactor specs
+* Change initial helper to simply state name with options
+* Change HookEvent to be immutable and extend comparison
+* Change Event to be immutable and extend comparison
+* Add #build method to HookEvent
+* Change finished? to terminated? and allow for multiple terminal states
+* Change to require explicit context to call target methods
+
 0.8.1 (July 5, 2014)
 
 * Add EventsChain to handle internal events logic

data/Gemfile

@@ -4,7 +4,7 @@ gemspec
 
 group :development do
   gem 'rake',  '~> 10.1.0'
-  gem 'rspec', '~> 2.14.1'
+  gem 'rspec', '~> 3.0.0'
   gem 'yard',  '~> 0.8.7'
 end
 

data/README.md

@@ -17,7 +17,7 @@ A minimal finite state machine with a straightforward and intuitive syntax. You
 
 * plain object state machine
 * easy custom object integration
-* natural DSL for declaring events, exceptions and callbacks
+* natural DSL for declaring events, callbacks and exceptions
 * observers (pub/sub) for state changes
 * ability to check reachable states
 * ability to check for terminal state
@@ -57,6 +57,7 @@ Or install it yourself as:
     * [2.3 Asynchronous transitions](#23-asynchronous-transitions)
     * [2.4 Single event with multiple from states](#24-single-event-with-multiple-from-states)
     * [2.5 Grouping states under single event](#25-grouping-states-under-single-event)
+    * [2.6 Silent transitions](#26-silent-transitions)
 * [3. Conditional transitions](#3-conditional-transitions)
     * [3.1 Using a Proc](#31-using-a-proc)
     * [3.2 Using a Symbol](#32-using-a-symbol)
@@ -80,10 +81,14 @@ Or install it yourself as:
     * [5.14 Cancelling inside callbacks](#514-cancelling-inside-callbacks)
 * [6. Errors](#6-errors)
     * [6.1 Using target](#61-using-target)
-* [7. Integration](#7-integration)
-    * [7.1 Plain Ruby Objects](#71-plain-ruby-objects)
-    * [7.2 ActiveRecord](#72-activerecord)
-* [8. Tips](#7-tips)
+* [7. Stand-Alone FiniteMachine](#7-stand-alone-finitemachine)
+    * [7.1 Creating a Definition](#71-creating-a-definition)
+    * [7.2 Targeting definition](#72-targeting-definition)
+* [8. Integration](#8-integration)
+    * [8.1 Plain Ruby Objects](#81-plain-ruby-objects)
+    * [8.2 ActiveRecord](#82-activerecord)
+    * [8.3 Transactions](#83-transactions)
+* [9. Tips](#9-tips)
 
 ## 1 Usage
 
@@ -176,7 +181,7 @@ If you want to defer setting the initial state, pass the `:defer` option to the
 
 ```ruby
 fm = FiniteMachine.define do
-  initial state: :green, defer: true
+  initial :green, defer: true # Defer calling :init event
 
   events {
     event :slow,  :green  => :yellow
@@ -184,7 +189,7 @@ fm = FiniteMachine.define do
   }
 end
 fm.current # => :none
-fm.init
+fm.init    # execute initial transition
 fm.current # => :green
 ```
 
@@ -192,7 +197,7 @@ If your target object already has `init` method or one of the events names redef
 
 ```ruby
 fm = FiniteMachine.define do
-  initial state: :green, event: :start, defer: true
+  initial :green, event: :start, defer: true # Rename event from :init to :start
 
   events {
     event :slow,  :green  => :yellow
@@ -201,7 +206,7 @@ fm = FiniteMachine.define do
 end
 
 fm.current # => :none
-fm.start
+fm.start   # => call the renamed event
 fm.current # => :green
 ```
 
@@ -209,7 +214,7 @@ By default the `initial` does not trigger any callbacks. If you need to fire cal
 
 ```ruby
 fm = FiniteMachine.define do
-  initial state: :green, silent: false  # => callbacks are triggered
+  initial :green, silent: false  # callbacks are triggered
 
   events {
     event :slow,  :green  => :yellow
@@ -220,28 +225,30 @@ end
 
 ### 1.3 terminal
 
-To specify a final state **FiniteMachine** uses the `terminal` method.
+To specify a final state **FiniteMachine** uses the `terminal` method. The `terminal` can accpet more than one state.
 
 ```ruby
 fm = FiniteMachine.define do
   initial :green
+
   terminal :red
 
   events {
     event :slow, :green  => :yellow
     event :stop, :yellow => :red
+    event :go,   :red    => :green
   }
 end
 ```
 
-When the terminal state has been specified, you can use `finished?` method on the state machine instance to verify if the terminal state has been reached or not.
+When the terminal state has been specified, you can use `terminated?` method on the state machine instance to verify if the terminal state has been reached or not.
 
 ```ruby
-fm.finished?  # => false
+fm.terminated?  # => false
 fm.slow
-fm.finished?  # => false
+fm.terminated?  # => false
 fm.stop
-fm.finished?  # => true
+fm.terminated?  # => true
 ```
 
 ### 1.4 is?
@@ -317,7 +324,7 @@ fm = FiniteMachine.define do
 end
 ```
 
-Furthermore, the context created through `target` helper will allow you to reference and call methods from another object.
+Furthermore, the context created through `target` helper will allow you to reference and call methods from another object inside your callbacks. You can reference external context by calling `target`.
 
 ```ruby
 car = Car.new
@@ -332,13 +339,13 @@ fm = FiniteMachine.define do
   }
 
   callbacks {
-    on_enter_start do |event| turn_engine_on end
-    on_exit_start  do |event| turn_engine_off end
+    on_enter_start do |event| target.turn_engine_on end
+    on_exit_start  do |event| target.turn_engine_off end
   }
 end
 ```
 
-For more complex example see [Integration](#6-integration) section.
+For more complex example see [Integration](#8-integration) section.
 
 Finally, you can always reference an external context inside the **FiniteMachine** by simply calling `target`, for instance, to reference it inside a callback:
 
@@ -476,6 +483,24 @@ fm = FiniteMachine.define do
   }
 ```
 
+### 2.6 Silent transitions
+
+The **FiniteMachine** allows to selectively silence events and thus prevent any callbacks from firing. Using the `silent` option passed to event definition like so:
+
+```ruby
+fm = FiniteMachine.define do
+  initial :yellow
+
+  events {
+    event :go    :yellow => :green, silent: true
+    event :stop, :green => :red
+  }
+end
+
+fsm.go   # no callbacks
+fms.stop # callbacks are fired
+```
+
 ## 3 Conditional transitions
 
 Each event takes an optional `:if` and `:unless` options which act as a predicate for the transition. The `:if` and `:unless` can take a symbol, a string, a Proc or an array. Use `:if` option when you want to specify when the transition **should** happen. If you want to specify when the transition **should not** happen then use `:unless` option.
@@ -524,9 +549,9 @@ fm = FiniteMachine.define do
   target car
 
   events {
-    event :start, :neutral => :one, if: -> (_car, state) {
-      _car.engine_on = state
-      _car.engine_on?
+    event :start, :neutral => :one, if: -> (target, state) {
+      target.engine_on = state
+      target.engine_on?
     }
   }
 end
@@ -838,8 +863,8 @@ fm = FiniteMachine.define do
   }
 
   callbacks {
-    on_enter_reverse { |event| turn_reverse_lights_on }
-    on_exit_reverse  { |event| turn_reverse_lights_off }
+    on_enter_reverse { |event| target.turn_reverse_lights_on }
+    on_exit_reverse  { |event| target.turn_reverse_lights_off }
   }
 end
 ```
@@ -850,8 +875,6 @@ Note that you can also fire events from callbacks.
 fm = FiniteMachine.define do
   initial :neutral
 
-  target car
-
   events {
     event :forward, [:reverse, :neutral] => :one
     event :back,    [:neutral, :one] => :reverse
@@ -865,7 +888,7 @@ end
 fm.back   # => Go Piotr!
 ```
 
-For more complex example see [Integration](#7-integration) section.
+For more complex example see [Integration](#8-integration) section.
 
 ### 5.12 Defining callbacks
 
@@ -987,11 +1010,89 @@ fm = FiniteMachine.define do
 end
 ```
 
-## 7 Integration
+## 7 Stand-Alone FiniteMachine
+
+**FiniteMachine** allows you to seperate your state machine from the target class so that you can keep your concerns broken in small maintainable pieces.
+
+### 7.1 Creating a Definition
+
+You can turn a class into a **FiniteMachine** by simply subclassing `FiniteMachine::Definition`. As a rule of thumb, every single public method of the **FiniteMachine** is available inside your class:
+
+```ruby
+class Engine < FiniteMachine::Definition
+  initial :neutral
+
+  events {
+    event :forward, [:reverse, :neutral] => :one
+    event :shift, :one => :two
+    event :back,  [:neutral, :one] => :reverse
+  }
+
+  callbacks {
+    on_enter :reverse do |event|
+      target.turn_reverse_lights_on
+    end
+
+    on_exit :reverse do |event|
+      target.turn_reverse_lights_off
+    end
+  }
+
+  handlers {
+    handle FiniteMachine::InvalidStateError do |exception| ... end
+  }
+end
+```
+
+### 7.2 Targeting definition
+
+The next step is to instantiate your state machine and use `target` to load specific context.
+
+```ruby
+class Car
+  def turn_reverse_lights_off
+    @reverse_lights = false
+  end
+
+  def turn_reverse_lights_on
+    @reverse_lights = true
+  end
+
+  def reverse_lights?
+    @reverse_lights ||= false
+  end
+end
+```
+Thus, to associate `Engine` to `Car` do:
+
+```ruby
+car = Car.new
+engine = Engine.new
+engine.target car
+
+car.reverse_lignts?  # => false
+engine.back
+car.reverse_lights?  # => true
+```
+
+Alternatively, create method inside the `Car` that will do the integration like so
+
+```ruby
+class Car
+  ... #  as above
+  def engine
+    @engine ||= Engine.new
+    @engine.target(self)
+    @engine
+  end
+end
+```
+
+## 8 Integration
 
 Since **FiniteMachine** is an object in its own right, it leaves integration with other systems up to you. In contrast to other Ruby libraries, it does not extend from models (i.e. ActiveRecord) to transform them into a state machine or require mixing into exisiting classes.
 
-### 7.1 Plain Ruby Objects
+### 8.1 Plain Ruby Objects
 
 In order to use **FiniteMachine** with an object, you need to define a method that will construct the state machine. You can implement the state machine using the `define` DSL or create a seperate object that can be instantiated. To complete integration you will need to specify `target` context to allow state machine to communicate with the other methods inside the class like so:
 
@@ -1025,11 +1126,11 @@ class Car
 
       callbacks {
         on_enter :reverse do |event|
-          turn_reverse_lights_on
+          target.turn_reverse_lights_on
         end
 
         on_exit :reverse do |event|
-          turn_reverse_lights_off
+          target.turn_reverse_lights_off
         end
 
         on_transition do |event|
@@ -1055,7 +1156,7 @@ car.gears.current      # => :reverse
 car.reverse_lights_on? # => true
 ```
 
-### 7.2 ActiveRecord
+### 8.2 ActiveRecord
 
 In order to integrate **FiniteMachine** with ActiveRecord use the `target` helper to reference the current class and call ActiveRecord methods inside the callbacks to persist the state.
 
@@ -1082,8 +1183,8 @@ class Account < ActiveRecord::Base
 
       callbacks {
         on_enter_state do |event|
-          self.state = event.to
-          save
+          target.state = event.to
+          target.save
         end
       }
     end
@@ -1098,7 +1199,21 @@ account.manage.authorize
 account.state   # => :access
 ```
 
-## 8 Tips
+### 8.3 Transactions
+
+When using **FiniteMachine** with ActiveRecord it advisable to trigger state changes inside transactions to ensure integrity of the database. Given Account example from section 8.2 one can run event in transaction in the following way:
+
+```ruby
+ActiveRecord::Base.transaction do
+  account.manage.enqueue
+end
+```
+
+If the transition fails it will raise `TransitionError` which will cause the transaction to rollback.
+
+Please check the ORM of your choice if it supports database transactions.
+
+## 9 Tips
 
 Creating a standalone **FiniteMachine** brings a number of benefits, one of them being easier testing. This is especially true if the state machine is extremely complex itself. Ideally, you would test the machine in isolation and then integrate it with other objects or ORMs.
 

data/lib/finite_machine.rb

@@ -24,6 +24,7 @@ require "finite_machine/logger"
 require "finite_machine/transition"
 require "finite_machine/transition_event"
 require "finite_machine/dsl"
+require "finite_machine/definition"
 require "finite_machine/state_machine"
 require "finite_machine/subscribers"
 require "finite_machine/state_parser"

data/lib/finite_machine/catchable.rb

@@ -77,7 +77,7 @@ module FiniteMachine
     def evaluate_handler(handler)
       case handler
       when Symbol
-        method(handler)
+        target.method(handler)
       when Proc
         if handler.arity.zero?
           proc { instance_exec(&handler) }

data/lib/finite_machine/definition.rb

@@ -0,0 +1,61 @@
+# encoding: utf-8
+
+module FiniteMachine
+  # A class responsible for defining standalone state machine
+  class Definition
+    # The machine deferreds
+    #
+    # @return [Array[Proc]]
+    #
+    # @api private
+    def self.deferreds
+      @deferreds ||= []
+    end
+
+    # Add deferred
+    #
+    # @param [Proc] deferred
+    #   the deferred execution
+    #
+    # @return [Array[Proc]]
+    #
+    # @api private
+    def self.add_deferred(deferred)
+      deferreds << deferred
+    end
+
+    # Instantiate a new Definition
+    #
+    # @example
+    #   class Engine < FiniteMachine::Definition
+    #     ...
+    #   end
+    #
+    #   engine = Engine.new
+    #
+    # @return [FiniteMachine::StateMachine]
+    #
+    # @api public
+    def self.new(*args)
+      context = self
+      FiniteMachine.define(*args) do
+        context.deferreds.each { |d| d.call(self) }
+      end
+    end
+
+    # Delay lookup of DSL method
+    #
+    # @param [Symbol] method_name
+    #
+    # @return [nil]
+    #
+    # @api private
+    def self.method_missing(method_name, *arguments, &block)
+      deferred = proc do |name, args, blok, object|
+        object.send(name, *args, &blok)
+      end
+      deferred = deferred.curry(4)[method_name][arguments][block]
+      add_deferred(deferred)
+    end
+  end # Definition
+end # FiniteMachine