finite_machine 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 29fd461f4bd19a780bac89bc363026b214db867f
-  data.tar.gz: 70e229f5f28433618f2408d35136aad7a0a1bb8e
+  metadata.gz: b69fcd7446203267dc8130e4c986ea334e4b26ec
+  data.tar.gz: 3a4bca63a58bf4a3c0a509cc99778d66771a535e
 SHA512:
-  metadata.gz: 00f1f997a94d5f5cb8571921d088a5bc4245001a45463f3b0fc57538094623d94e97c52df76780e957f16279c1bd43d8d0c004595a55a60005f70993fe4873d2
-  data.tar.gz: c62a75b03d74891a0f83bc91ef3bac4e22090f29b0adb9edc398f0290f39dfbcde36513d994373698be17554aa4618916bcd15018275d2afc197f93b0e6944b7
+  metadata.gz: d5c2636ea7607b138737e263771b5269d950f1403079e67dfd41d4940241f41cf62d1118cfe7ae177cfe3a716985cad9f33f76313ada9ce4424ba3fcbbd89511
+  data.tar.gz: c40fda5ae25615ca3d2ee239dc59a952596c3860f309c22b8d01e8b4b8acd10f0d7aeb7ddb2f1dc80aecd46c9bd4b3b6e0fd456b28b14dfc9f34144b7ef80fac

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+0.4.0 (April 13, 2014)
+
+* Change initial state to stop firing event notification
+* Fix initial to accept any state object
+* Add logger
+* Add ability to cancel transitions inside callbacks
+* Fix proc conditions to accept aditional arguments
+* Increase test coverage to 97%
+* Add ability to force transitions
+
 0.3.0 (March 30, 2014)
 
 * Move development dependencies to Gemfile

data/README.md

@@ -43,11 +43,38 @@ 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.4 is?](#14-is)
+    * [1.5 can? and cannot?](#15-can-and-cannot)
+    * [1.6 states](#16-states)
+    * [1.7 target](#17-target)
 * [2. Transitions](#2-transitions)
+    * [2.1 Performing transitions](#21-performing-transitions)
+    * [2.2 Forcing transitions](#22-forcing-transitions)
+    * [2.3 Asynchronous transitions](#23-asynchronous-transitions)
+    * [2.4 Single event with multiple from states](#24-single-event-with-multiple-from-states)
 * [3. Conditional transitions](#3-conditional-transitions)
+    * [3.1 Using a Proc](#31-using-a-proc)
+    * [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 once_on](#44-once_on)
+    * [4.5 parameters](#45-parameters)
+    * [4.6 Same kind of callbacks](#46-same-kind-of-callbacks)
+    * [4.7 Fluid callbacks](#47-fluid-callbacks)
+    * [4.8 Executing methods inside callbacks](#48-executing-methods-inside-callbacks)
+    * [4.9 Defining callbacks](#49-defining-callbacks)
+    * [4.10 Cancelling inside callbacks](#410-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)
 
 ## 1 Usage
@@ -98,9 +125,11 @@ fm = FiniteMachine.define do
 end
 
 fm.current # => :none
+fm.start
+fm.current # => :green
 ```
 
-If you specify initial state using the `initial` helper, an `init` event will be created and triggered when the state machine is created.
+If you specify initial state using the `initial` helper, the state machine will be created already in that state.
 
 ```ruby
 fm = FiniteMachine.define do
@@ -115,34 +144,36 @@ end
 fm.current # => :green
 ```
 
-If your target object already has `init` method or one of the events names redefines `init`, you can use different name by passing `:event` option to `initial` helper.
+If you want to defer setting the initial state, pass the `:defer` option to the `initial` helper. By default **FiniteMachine** will create `init` event that will allow to transition from `:none` state to the new state.
 
 ```ruby
 fm = FiniteMachine.define do
-  initial :green, event: :start
+  initial state: :green, defer: true
 
   events {
     event :slow,  :green  => :yellow
     event :stop,  :yellow => :red
   }
 end
-
+fm.current # => :none
+fm.init
 fm.current # => :green
 ```
 
-If you want to defer calling the initial state method pass the `:defer` option to the `initial` helper.
+If your target object already has `init` method or one of the events names redefines `init`, you can use different name by passing `:event` option to `initial` helper.
 
 ```ruby
 fm = FiniteMachine.define do
-  initial state: :green, defer: true
+  initial state: :green, event: :start, defer: true
 
   events {
     event :slow,  :green  => :yellow
     event :stop,  :yellow => :red
   }
 end
+
 fm.current # => :none
-fm.init
+fm.start
 fm.current # => :green
 ```
 
@@ -286,7 +317,11 @@ fm.go('Piotr!')
 fm.current       # => :green
 ```
 
-### 2.2 Asynchronous transitions
+### 2.2 Forcing transitions
+
+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.
+
+### 2.3 Asynchronous transitions
 
 By default the transitions will be fired synchronosuly.
 
@@ -303,7 +338,7 @@ In order to fire the event transition asynchronously use the `async` scope like
 fm.async.ready  # => executes in separate Thread
 ```
 
-### 2.3 single event with multiple from states
+### 2.4 Single event with multiple from states
 
 If an event transitions from multiple states to the same state then all the states can be grouped into an array.
 Altenatively, you can create separte events under the same name for each transition that needs combining.
@@ -342,10 +377,12 @@ fm.slow    # doesn't transition to :yellow state
 fm.current # => :green
 ```
 
-You can also execute methods on an associated object by passing it as an argument to `target` helper.
+Provided your **FiniteMachine** is associated with another object through `target` helper. Then the target object together with event arguments will be passed to the `:if` or `:unless` condition scope.
 
 ```ruby
 class Car
+  attr_accessor :engine_on
+
   def turn_engine_on
     @engine_on = true
   end
@@ -368,14 +405,21 @@ fm = FiniteMachine.define do
   target car
 
   events {
-    event :start, :neutral => :one, if: "engine_on?"
+    event :start, :neutral => :one, if: -> (_car, state) {
+      _car.engine_on = state
+      _car.engine_on?
+    }
   }
 end
 
-fm.start
-fm.current # => :one
+fm.start(false)
+fm.current       # => :neutral
+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)
+
 ### 3.2 Using a Symbol
 
 You can also use a symbol corresponding to the name of a method that will get called right before transition happens.
@@ -643,6 +687,33 @@ fm.on_enter_yellow do |event|
 end
 ```
 
+### 4.10 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
+
+* `on_exit :state_name`
+* `on_enter :event_name`
+
+For example
+
+```ruby
+fm = FiniteMachine.define do
+  initial :red
+
+  events {
+    event :ready, :red    => :yellow
+    event :go,    :yellow => :green
+    event :stop,  :green  => :red
+  }
+  callbacks {
+    on_exit :red do |event| FiniteMachine::CANCELLED end
+  }
+end
+
+fm.ready
+fm.current  # => :red
+```
+
 ## 5 Errors
 
 By default, the **FiniteMachine** will throw an exception whenever the machine is in invalid state or fails to transition.
@@ -792,7 +863,7 @@ account.state   # => :access
 
 ## 7 Tips
 
-Creating a standalone **FiniteMachine** brings few 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.
+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.
 
 ## Contributing
 

data/examples/atm.rb

@@ -0,0 +1,45 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'finite_machine'
+
+class Account
+  attr_accessor :number
+
+  def verify(account_number, pin)
+    return account_number == 123456 && pin == 666
+  end
+end
+
+account = Account.new
+
+atm = FiniteMachine.define do
+  initial :unauthorized
+
+  target account
+
+  events {
+    event :authorize, :unauthorized => :authorized, if: -> (account, account_number, pin) {
+      account.verify(account_number, pin)
+    }
+    event :deauthorize, :authorized => :unauthorized
+  }
+
+  callbacks {
+    on_exit :unauthorized do |event, account_number, pin|
+      # if verify(account_number, pin)
+        self.number = account_number
+#       else
+#         puts "Invalid Account and/or PIN"
+#         FiniteMachine::CANCELLED
+#       end
+    end
+  }
+end
+
+atm.authorize(111222, 666)
+puts "authorized: #{atm.authorized?}"
+puts "Number: #{account.number}"
+
+atm.authorize(123456, 666)
+puts "authorized: #{atm.authorized?}"
+puts "Number: #{account.number}"

data/examples/bug_system.rb

@@ -0,0 +1,145 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'finite_machine'
+
+class User
+  attr_accessor :name
+
+  def initialize(name)
+    @name = name
+  end
+end
+
+class Manager < User
+  attr_accessor :developers
+
+  def initialize(name)
+    super
+    @developers = []
+  end
+
+  def manages(developer)
+    @developers << developer
+  end
+
+  def assign(bug)
+    developer = @developers.first
+    bug.assign
+    developer.bug = bug
+  end
+end
+
+class Tester < User
+  def report(bug)
+    bug.report
+  end
+
+  def reopen(bug)
+    bug.reopen
+  end
+end
+
+class Developer < User
+  attr_accessor :bug
+
+  def work_on
+    bug.start
+  end
+
+  def resolve
+    bug.close
+  end
+end
+
+class BugSystem
+  attr_accessor :managers
+
+  def initialize(managers = [])
+    @managers = managers
+  end
+
+  def notify_manager(bug)
+    manager = @managers.first
+    manager.assign(bug)
+  end
+end
+
+class Bug
+  attr_accessor :name
+  attr_accessor :priority
+  # fake belongs_to relationship
+  attr_accessor :bug_system
+
+  def initialize(name, priority)
+    @name = name
+    @priority = priority
+  end
+
+  def report
+    status.report
+  end
+
+  def assign
+    status.assign
+  end
+
+  def start
+    status.start
+  end
+
+  def close
+    status.close
+  end
+
+  def reopen
+    status.reopen
+  end
+
+  def status
+    context = self
+    @status ||= FiniteMachine.define do
+      target context
+
+      events {
+        event :report, :none => :new
+        event :assign, :new => :assigned
+        event :start,  :assigned => :in_progress
+        event :close,  [:in_progress, :reopened] => :resolved
+        event :reopen, :resolved => :reopened
+      }
+
+      callbacks {
+        on_enter :new do |event|
+          bug_system.notify_manager(self)
+        end
+      }
+    end
+  end
+end
+
+tester    = Tester.new("John")
+manager   = Manager.new("David")
+developer = Developer.new("Piotr")
+manager.manages(developer)
+
+bug_system = BugSystem.new([manager])
+bug        = Bug.new(:trojan, :high)
+bug.bug_system = bug_system
+
+puts "A BUG's LIFE"
+puts "#1 #{bug.status.current}"
+
+tester.report(bug)
+puts "#2 #{bug.status.current}"
+
+developer.work_on
+puts "#3 #{bug.status.current}"
+
+developer.resolve
+puts "#4 #{bug.status.current}"
+
+tester.reopen(bug)
+puts "#5 #{bug.status.current}"
+
+developer.resolve
+puts "#6 #{bug.status.current}"

data/lib/finite_machine.rb

@@ -1,5 +1,6 @@
 # encoding: utf-8
 
+require "logger"
 require "thread"
 require "sync"
 
@@ -13,6 +14,7 @@ require "finite_machine/async_call"
 require "finite_machine/event"
 require "finite_machine/event_queue"
 require "finite_machine/hooks"
+require "finite_machine/logger"
 require "finite_machine/transition"
 require "finite_machine/dsl"
 require "finite_machine/state_machine"
@@ -56,11 +58,21 @@ module FiniteMachine
   # Raised when event has no transitions
   NotEnoughTransitionsError = Class.new(::ArgumentError)
 
+  # Raised when initial event specified without state name
+  MissingInitialStateError = Class.new(::StandardError)
+
   Environment = Struct.new(:target)
 
-  # TODO: this should instantiate system not the state machine
-  # and then delegate calls to StateMachine instance etc...
-  def self.define(*args, &block)
-    StateMachine.new(*args, &block)
+  class << self
+    attr_accessor :logger
+
+    # TODO: this should instantiate system not the state machine
+    # and then delegate calls to StateMachine instance etc...
+    def define(*args, &block)
+      StateMachine.new(*args, &block)
+    end
   end
+
 end # FiniteMachine
+
+FiniteMachine.logger = Logger.new(STDERR)