finite_machine 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d0521fc82d97ac5139abe2fcea0ed72532af05fe
-  data.tar.gz: 260b8c31a86e2c3f80018aad2640c62222cea2af
+  metadata.gz: f31937c5d49cee8c974c90b8339c1e3aa57f4866
+  data.tar.gz: 5386d3a848f6dd01d05d174d165447366c80ed19
 SHA512:
-  metadata.gz: f443039daa14568b5bc2424d6346b89da989494bde20c416e6c7186d1692dd878a1a1bae3e9dcd9a6271c4bfa2bed42d7c795b24c53883a692ffc672a9ec05bc
-  data.tar.gz: 4cc03728f4c4694f3ebac12bb3f112622b84f877efcbea2ef0f783a0005ee93d889b9317922e09e87f2f5a0ddc189d5618baa17bf498024c8263d783f1e77e83
+  metadata.gz: d8ca32da8076f07a43c53650ebdb99a22ba4e0fb4f721db972caeed7df91fb70feecde074b022e79798b5318c07ab59fddfadc91ddf131d4a4ea4d32b477e946
+  data.tar.gz: 674cc1ae00eb4fafe21adc37721a2bc92f7a482c2755599dbf1c884bb8e1e7f7591bdcaaf09922e54c2204fd3cd64042f43db5b3c9a939c7a2e0c93321ab940a

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+0.8.0 (June 22, 2014)
+
+* Add silent option for state machine events to allow turning on/off
+  selectively callbacks
+* Ensure that can? & cannot? take into account conditionl logic applied
+  to transitions
+* Add restore! method to allow to set the state directly without callbacks
+* Add ability to do dynamic conditional branching using the choice DSL or
+  grouped events with different outgoing transitions [solves #13 and #6 issue]
+
 0.7.1 (June 8, 2014)
 
 * Change to relax callback name checks to allow for duplicate state and event names

data/README.md

@@ -21,10 +21,10 @@ A minimal finite state machine with a straightforward and intuitive syntax. You
 * observers (pub/sub) for state changes
 * ability to check reachable states
 * ability to check for terminal state
-* conditional transitions
+* transition guard conditions
+* dynamic conditional branching
 * sync and async transitions
 * sync and async callbacks
-* nested/composable states (TODO)
 
 ## Installation
 
@@ -50,6 +50,7 @@ Or install it yourself as:
     * [1.5 can? and cannot?](#15-can-and-cannot)
     * [1.6 states](#16-states)
     * [1.7 target](#17-target)
+    * [1.8 restore!](#18-restore)
 * [2. Transitions](#2-transitions)
     * [2.1 Performing transitions](#21-performing-transitions)
     * [2.2 Forcing transitions](#22-forcing-transitions)
@@ -61,26 +62,27 @@ Or install it yourself as:
     * [3.2 Using a Symbol](#32-using-a-symbol)
     * [3.3 Using a String](#33-using-a-string)
     * [3.4 Combining transition conditions](#34-combining-transition-conditions)
-* [4. Callbacks](#4-callbacks)
-    * [4.1 on_enter](#41-on_enter)
-    * [4.2 on_transition](#42-on_transition)
-    * [4.3 on_exit](#43-on_exit)
-    * [4.4 on_before](#44-on_before)
-    * [4.5 on_after](#45-on_after)
-    * [4.6 once_on](#46-once_on)
-    * [4.7 Execution sequence](#47-execution-sequence)
-    * [4.8 Parameters](#48-parameters)
-    * [4.9 Same kind of callbacks](#49-same-kind-of-callbacks)
-    * [4.10 Fluid callbacks](#410-fluid-callbacks)
-    * [4.11 Executing methods inside callbacks](#411-executing-methods-inside-callbacks)
-    * [4.12 Defining callbacks](#412-defining-callbacks)
-    * [4.13 Asynchronous callbacks](#413-asynchronous-callbacks)
-    * [4.14 Cancelling inside callbacks](#414-cancelling-inside-callbacks)
-* [5. Errors](#5-errors)
-    * [5.1 Using target](#51-using-target)
-* [6. Integration](#6-integration)
-    * [6.1 ActiveRecord](#61-activerecord)
-* [7. Tips](#7-tips)
+* [4. Choice pseudostates](#4-choice-pseudostates)
+* [5. Callbacks](#5-callbacks)
+    * [5.1 on_enter](#51-on_enter)
+    * [5.2 on_transition](#52-on_transition)
+    * [5.3 on_exit](#53-on_exit)
+    * [5.4 on_before](#54-on_before)
+    * [5.5 on_after](#55-on_after)
+    * [5.6 once_on](#56-once_on)
+    * [5.7 Execution sequence](#57-execution-sequence)
+    * [5.8 Parameters](#58-parameters)
+    * [5.9 Same kind of callbacks](#59-same-kind-of-callbacks)
+    * [5.10 Fluid callbacks](#510-fluid-callbacks)
+    * [5.11 Executing methods inside callbacks](#511-executing-methods-inside-callbacks)
+    * [5.12 Defining callbacks](#512-defining-callbacks)
+    * [5.13 Asynchronous callbacks](#513-asynchronous-callbacks)
+    * [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 ActiveRecord](#71-activerecord)
+* [8. Tips](#7-tips)
 
 ## 1 Usage
 
@@ -104,7 +106,7 @@ fm = FiniteMachine.define do
 end
 ```
 
-As the example demonstrates, by calling the `define` method on **FiniteMachine** you create an instance of finite state machine. The `events` and `callbacks` scopes help to define the behaviour of the machine. Read [Transitions](#2-transitions) and [Callbacks](#4-callbacks) sections for more details.
+As the example demonstrates, by calling the `define` method on **FiniteMachine** you create an instance of finite state machine. The `events` and `callbacks` scopes help to define the behaviour of the machine. Read [Transitions](#2-transitions) and [Callbacks](#5-callbacks) sections for more details.
 
 Alternatively, you can construct the machine like a regular object without using the DSL. The same machine could be reimplemented as follows:
 
@@ -128,7 +130,7 @@ The **FiniteMachine** allows you to query the current state by calling the `curr
 
 ### 1.2 initial
 
-There are number of ways to provide the initial state  **FiniteMachine** depending on your requirements.
+There are number of ways to provide the initial state in  **FiniteMachine** depending on your requirements.
 
 By default the **FiniteMachine** will be in the `:none` state and you will need to provide an event to transition out of this state.
 
@@ -202,6 +204,19 @@ fm.start
 fm.current # => :green
 ```
 
+By default the `initial` does not trigger any callbacks. If you need to fire callbacks and any event associated actions on initial transition, pass the `silent` option set to `false` like so
+
+```ruby
+fm = FiniteMachine.define do
+  initial state: :green, silent: false  # => callbacks are triggered
+
+  events {
+    event :slow,  :green  => :yellow
+    event :stop,  :yellow => :red
+  }
+end
+```
+
 ### 1.3 terminal
 
 To specify a final state **FiniteMachine** uses the `terminal` method.
@@ -255,6 +270,25 @@ fm.cannot?(:ready) # => false
 fm.cannot?(:go)    # => true
 ```
 
+The `can?` and `cannot?` helper methods take into account the `:if` and `:unless` conditions applied to events. The set of values that `:if` or `:unless` condition takes as block parameter can be passed in directly via `can?` and `cannot?` methods' arguments, after the name of the event. For instance,
+
+```ruby
+fm = FiniteMachine.define do
+  initial :green
+
+  events {
+    event :slow,  :green  => :yellow
+    event :stop,  :yellow => :red, if: proc { |_, param| :breaks == param }
+  }
+end
+fm.can?(:slow) # => true
+fm.can?(:stop) # => false
+
+fm.slow
+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.
@@ -307,6 +341,7 @@ For more complex example see [Integration](#6-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:
 
+```ruby
 car = Car.new
 
 fm = FiniteMachine.define do
@@ -323,6 +358,17 @@ fm = FiniteMachine.define do
     end
   }
 end
+```
+
+### 1.8 restore!
+
+In order to set the machine to a given state and thus skip triggering callbacks use the `restore!` method:
+
+```ruby
+fm.restore!(:neutral)
+```
+
+This method may be suitable when used testing your state machine or in restoring the state from datastore.
 
 ## 2 Transitions
 
@@ -490,7 +536,7 @@ fm.start(true)
 fm.current       # => :one
 ```
 
-When the one-liner conditions are not enough for your needs, you can perform conditional logic inside the callbacks. See [4.10 Cancelling inside callbacks](#410-cancelling-inside-callbacks)
+When the one-liner conditions are not enough for your needs, you can perform conditional logic inside the callbacks. See [5.10 Cancelling inside callbacks](#510-cancelling-inside-callbacks)
 
 ### 3.2 Using a Symbol
 
@@ -543,7 +589,69 @@ end
 
 The transition only runs when all the `:if` conditions and none of the `unless` conditions are evaluated to `true`.
 
-## 4 Callbacks
+## 4 Choice pseudostates
+
+Choice pseudostate allows you to implement conditional branch. The conditions of an event's transitions are evaluated in order to to select only one outgoing transition.
+
+You can implement the conditional branch as ordinary events grouped under the same name and use familiar `:if/:unless` conditions:
+
+```ruby
+fsm = FiniteMachine.define do
+  initial :green
+
+  events {
+    event :next, :green => :yellow, if: -> { false }
+    event :next, :green => :red,    if: -> { true }
+  }
+end
+
+fsm.current # => :green
+fsm.next
+fsm.current # => :red
+```
+
+The same conditional logic can be implemented using much shorter and more descriptive style using `choice` method:
+
+```ruby
+fsm = FiniteMachine.define do
+  initial :green
+
+  events {
+    event :next, from: :green do
+      choice :yellow, if: -> { false }
+      choice :red,    if: -> { true }
+    end
+  }
+end
+
+fsm.current # => :green
+fsm.next
+fsm.current # => :red
+```
+
+Just as with event conditions you can make conditional logic dynamic and dependent on parameters passed in:
+
+```ruby
+fsm = FiniteMachine.define do
+  initial :green
+
+  events {
+    event :next, from: :green do
+      choice :yellow, if: -> (context, a) { a < 1 }
+      choice :red,    if: -> (context, a) { a > 1 }
+      default :red
+    end
+  }
+end
+
+fsm.current # => :green
+fsm.next(0)
+fsm.current # => :yellow
+```
+
+If more than one of the conditions evaluates to true, a first matching one is chosen. If none of the conditions evaluate to true, then the `default` state is matched. However if default state is not present and non of the conditions match, no transition is performed. To avoid such situation always specify `default` choice.
+
+## 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**:
 
@@ -578,27 +686,27 @@ fm.ready(1, 2, 3)
 fm.go('Piotr!')
 ```
 
-### 4.1 on_enter
+### 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.
 
-### 4.2 on_transition
+### 5.2 on_transition
 
 The `on_transition` callback is executed when given state change happens. By passing state name you can narrow down the listener to only watch out for transition state changes. Otherwise, all transition state changes will be watched.
 
-### 4.3 on_exit
+### 5.3 on_exit
 
 The `on_exit` callback is executed after a given state change happens. By passing state name you can narrow down the listener to only watch out for exit state changes. Otherwise, all exit state changes will be watched.
 
-### 4.4 on_before
+### 5.4 on_before
 
 The `on_before` callback is executed before a given event happens. By default it will listen out for all events, you can also listen out for specific events by passing event's name.
 
-### 4.5 on_after
+### 5.5 on_after
 
 This callback is executed after a given event happened. By default it will listen out for all events, you can also listen out for specific events by passing event's name.
 
-### 4.6 once_on
+### 5.6 once_on
 
 **FiniteMachine** allows you to listen on initial state change or when the event is fired first time by using the following 5 types of callbacks:
 
@@ -608,7 +716,7 @@ This callback is executed after a given event happened. By default it will liste
 * `once_before`
 * `once_after`
 
-### 4.7 Execution sequence
+### 5.7 Execution sequence
 
 Assuming we have the following event specified:
 
@@ -629,7 +737,7 @@ then by calling `go` event the following callbacks in the following sequence wil
 * `on_after :go` - callback after the `go` event
 * `on_after` - generic callback after `any` event
 
-### 4.8 Parameters
+### 5.8 Parameters
 
 All callbacks get the `TransitionEvent` object with the following attributes.
 
@@ -657,7 +765,7 @@ end
 fm.ready(3)   #  => 'lights switching from red to yellow in 3 seconds'
 ```
 
-### 4.9 Same kind of callbacks
+### 5.9 Same kind of callbacks
 
 You can define any number of the same kind of callback. These callbacks will be executed in the order they are specified.
 
@@ -677,7 +785,7 @@ end
 fm.slow # => will invoke both callbacks
 ```
 
-### 4.10 Fluid callbacks
+### 5.10 Fluid callbacks
 
 Callbacks can also be specified as full method calls.
 
@@ -699,7 +807,7 @@ fm = FiniteMachine.define do
 end
 ```
 
-### 4.11 Executing methods inside callbacks
+### 5.11 Executing methods inside callbacks
 
 In order to execute method from another object use `target` helper.
 
@@ -756,9 +864,9 @@ end
 fm.back   # => Go Piotr!
 ```
 
-For more complex example see [Integration](#6-integration) section.
+For more complex example see [Integration](#7-integration) section.
 
-### 4.12 Defining callbacks
+### 5.12 Defining callbacks
 
 When defining callbacks you are not limited to the `callbacks` helper. After **FiniteMachine** instance is created you can register callbacks the same way as before by calling `on` and supplying the type of notification and state/event you are interested in.
 
@@ -778,7 +886,7 @@ fm.on_enter_yellow do |event|
 end
 ```
 
-### 4.13 Asynchronous callbacks
+### 5.13 Asynchronous callbacks
 
 By default all callbacks are run synchronosuly. In order to add a callback that runs asynchronously, you need to pass second `:async` argument like so:
 
@@ -794,7 +902,7 @@ or
 
 This will ensure that when the callback is fired it will run in seperate thread outside of the main execution thread.
 
-### 4.14 Cancelling inside callbacks
+### 5.14 Cancelling inside callbacks
 
 Preferred way to handle cancelling transitions is to use [3 Conditional transitions](#3-conditional-transitions). However if the logic is more than one liner you can cancel the event, hence the transition by returning `FiniteMachine::CANCELLED` constant from the callback scope. The two ways you can affect the event are
 
@@ -821,7 +929,7 @@ fm.ready
 fm.current  # => :red
 ```
 
-## 5 Errors
+## 6 Errors
 
 By default, the **FiniteMachine** will throw an exception whenever the machine is in invalid state or fails to transition.
 
@@ -851,7 +959,7 @@ fm = FiniteMachine.define do
 end
 ```
 
-### 5.1 Using target
+### 6.1 Using target
 
 You can pass an external context via `target` helper that will be the receiver for the handler. The handler method needs to take one argument that will be called with the exception.
 
@@ -878,7 +986,7 @@ fm = FiniteMachine.define do
 end
 ```
 
-## 6 Integration
+## 7 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.
 
@@ -926,7 +1034,7 @@ class Car
 end
 ```
 
-### 6.1 ActiveRecord
+### 7.1 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.
 
@@ -968,7 +1076,7 @@ account.manage.authorize
 account.state   # => :access
 ```
 
-## 7 Tips
+## 8 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

@@ -10,6 +10,7 @@ require "finite_machine/safety"
 require "finite_machine/thread_context"
 require "finite_machine/callable"
 require "finite_machine/catchable"
+require "finite_machine/choice_merger"
 require "finite_machine/async_proxy"
 require "finite_machine/async_call"
 require "finite_machine/hook_event"

data/lib/finite_machine/choice_merger.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+
+module FiniteMachine
+  # A class responsible for merging choice options
+  class ChoiceMerger
+    include Threadable
+
+    # The context where choice is executed
+    attr_threadsafe :context
+
+    # The options passed in to the context
+    attr_threadsafe :options
+
+    # Initialize a ChoiceMerger
+    #
+    # @api private
+    def initialize(context, options)
+      self.context = context
+      self.options = options
+    end
+
+    # Create choice transition
+    #
+    # @example
+    #   event from: :green do
+    #     choice :yellow
+    #   end
+    #
+    # @param [Symbol] to
+    #   the to state
+    # @param [Hash] attrs
+    #
+    # @return [FiniteMachine::Transition]
+    #
+    # @api public
+    def choice(to, attrs = {})
+      opts = options.dup
+      opts.merge!(attrs)
+      opts.merge!(parsed_states: { options[:from] => to })
+      Transition.create(context.machine, opts)
+    end
+    alias_method :default, :choice
+  end # ChoiceMerger
+end # FiniteMachine