finite_machine 0.6.1 → 0.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3ac2b8cf6f6e899a7d6b2f04c240703d45a4b67d
+  data.tar.gz: f556b050c651d3120b5a2fe990fd1efc94abf961
+SHA512:
+  metadata.gz: f5871e7adbd4a10e4a44a9bd4916f09843890490fd967d9bc8ce7b7c0a20033b72f2344d23fd7cd6bd2a3369cc5f622f343ea3ce1c2b817e8332909d754806fe
+  data.tar.gz: a1feb862d90d7da38db41ce326ab3a9dbcc241555a4d65e216eeb4260442f5d1a942ac474551f2b41853ab7bb6b5aeb62b474e7efab2bb2571c22a0bfe0da0bf

data/.travis.yml

@@ -16,6 +16,8 @@ matrix:
   allow_failures:
     - rvm: ruby-head
     - rvm: jruby-head
+    - rvm: jruby-20mode
+    - rvm: jruby-21mode
     - rvm: rbx
   fast_finish: true
 branches:

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+0.7.0 (May 26, 2014)
+
+* Change Event to EventHook for callback events
+* Add Event to hold the logic for event specification
+* Fix issue #8 to preserve conditionals between event specifications
+* Change to allow for self-transition - fixes issue #9
+* Change to detect attempt to overwrite already defined method - fixes issue #10
+* Fix #respond_to on state machine to include observer
+* Add string inspection to hooks
+* Fix observer missing methods resolution
+* Change to separate state and event callbacks. Introduced on_enter, on_before,
+  once_on_enter, once_on_before new event callbacks.
+* Change generic callbacks to default to any state for on_enter, on_transition,
+  on_exit and any event for on_before and on_after
+* Add check for callback name conflicts
+* Ensure proper callback lifecycle
+
 0.6.1 (May 10, 2014)
 
 * Fix stdlib requirement

data/README.md

@@ -65,14 +65,17 @@ Or install it yourself as:
     * [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 Asynchronous callbacks](#410-asynchronous-callbacks)
-    * [4.11 Cancelling inside callbacks](#411-cancelling-inside-callbacks)
+    * [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)
@@ -94,9 +97,9 @@ fm = FiniteMachine.define do
   }
 
   callbacks {
-    on_enter(:ready) { |event| ... }
-    on_exit(:go)     { |event| ... }
-    on_enter(:stop)  { |event| ... }
+    on_before(:ready) { |event| ... }
+    on_after(:go)     { |event| ... }
+    on_before(:stop)  { |event| ... }
   }
 end
 ```
@@ -110,9 +113,9 @@ fm = FiniteMachine.new initial: :red
 fm.event(:ready, :red    => :yellow)
 fm.event(:go,    :yellow => :green)
 fm.event(:stop,  :green  => :red)
-fm.on_enter(:ready) { |event| ... }
-fm.on_exit(:go)     { |event| ... }
-fm.on_enter(:stop)  { |event| ...}
+fm.on_before(:ready) { |event| ... }
+fm.on_after(:go)     { |event| ... }
+fm.on_before(:stop)  { |event| ...}
 ```
 
 ### 1.1 current
@@ -413,6 +416,19 @@ fm = FiniteMachine.define do
   }
 ```
 
+The same can be more naturally rewritten also as:
+
+```ruby
+fm = FiniteMachine.define do
+  initial :initial
+
+  events {
+    event :bump, :initial => :low
+    event :bump, :low     => :medium
+    event :bump, :medium  => :high
+  }
+```
+
 ## 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.
@@ -529,24 +545,17 @@ The transition only runs when all the `:if` conditions and none of the `unless`
 
 ## 4 Callbacks
 
-You can watch state machine events and the information they provide by registering a callback. The following 3 types of callbacks are available in **FiniteMachine**:
+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**:
 
 * `on_enter`
 * `on_transition`
 * `on_exit`
-
-In addition, you can listen for generic state changes or events fired by using the following 6 callbacks:
-
-* `on_enter_state`
-* `on_enter_event`
-* `on_transition_state`
-* `on_transition_event`
-* `on_exit_state`
-* `on_exit_event`
+* `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.
 
-When you subscribe to the `:green` state event, the callback will be called whenever someone instruments change for that state. The same will happend 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 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.
 
 ```ruby
 fm = FiniteMachine.define do
@@ -559,9 +568,9 @@ fm = FiniteMachine.define do
   }
 
   callbacks {
-    on_enter :ready { |event, time1, time2, time3| puts "#{time1} #{time2} #{time3} Go!" }
-    on_enter :go    { |event, name| puts "Going fast #{name}" }
-    on_enter :stop  { |event| ... }
+    on_before :ready { |event, time1, time2, time3| puts "#{time1} #{time2} #{time3} Go!" }
+    on_before :go    { |event, name| puts "Going fast #{name}" }
+    on_before :stop  { |event| ... }
   }
 end
 
@@ -571,31 +580,56 @@ fm.go('Piotr!')
 
 ### 4.1 on_enter
 
-This method is executed before given event or state change. If you provide only a callback without the name of the state or event to listen out for, then `:any` state and `:any` event will be observered.
-
-You can further narrow down the listener to only watch enter state changes using `on_enter_state` callback. Similarly, use `on_enter_event` to only watch for event changes.
+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
 
-This method is executed when given event or state change happens. If you provide only a callback without the name of the state or event to listen out for, then `:any` state and `:any` event will be observered.
-
-You can further narrow down the listener to only watch state transition changes using `on_transition_state` callback. Similarly, use `on_transition_event` to only watch for event transition changes.
+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
 
-This method is executed after a given event or state change happens. If you provide only a callback without the name of the state or event to listen for, then `:any` state and `:any` event will be observered.
+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.
 
-You can further narrow down the listener to only watch state exit changes using `on_exit_state` callback. Similarly, use `on_exit_event` to only watch for event exit changes.
+### 4.4 on_before
 
-### 4.4 once_on
+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.
 
-**FiniteMachine** allows you to listen on initial state change or when the event is fired first time by using the following 3 types of callbacks:
+### 4.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
+
+**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:
 
 * `once_on_enter`
 * `once_on_transition`
 * `once_on_exit`
+* `once_before`
+* `once_after`
+
+### 4.7 Execution sequence
+
+Assuming we have the following event specified:
+
+```ruby
+event :go, :red => :yellow
+```
+
+then by calling `go` event the following callbacks in the following sequence will be executed:
 
-### 4.5 Parameters
+* `on_before :go` - callback before the `go` event
+* `on_before` - generic callback before `any` 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
+* `on_transition` - callback for transition from `any` state to `any` state
+* `on_enter :yellow` - callback for the `:yellow` state entry
+* `on_enter` - generic callback for entry to `any` state
+* `on_after :go` - callback after the `go` event
+* `on_after` - generic callback after `any` event
+
+### 4.8 Parameters
 
 All callbacks get the `TransitionEvent` object with the following attributes.
 
@@ -623,7 +657,7 @@ end
 fm.ready(3)   #  => 'lights switching from red to yellow in 3 seconds'
 ```
 
-### 4.6 Same kind of callbacks
+### 4.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.
 
@@ -643,7 +677,7 @@ end
 fm.slow # => will invoke both callbacks
 ```
 
-### 4.7 Fluid callbacks
+### 4.10 Fluid callbacks
 
 Callbacks can also be specified as full method calls.
 
@@ -658,14 +692,14 @@ fm = FiniteMachine.define do
   }
 
   callbacks {
-    on_enter_ready { |event| ... }
-    on_enter_go    { |event| ... }
-    on_enter_stop  { |event| ... }
+    on_before_ready { |event| ... }
+    on_before_go    { |event| ... }
+    on_before_stop  { |event| ... }
   }
 end
 ```
 
-### 4.8 Executing methods inside callbacks
+### 4.11 Executing methods inside callbacks
 
 In order to execute method from another object use `target` helper.
 
@@ -708,7 +742,8 @@ fm = FiniteMachine.define do
   initial :neutral
 
   target car
-events {
+
+  events {
     event :forward, [:reverse, :neutral] => :one
     event :back,    [:neutral, :one] => :reverse
   }
@@ -723,7 +758,7 @@ fm.back   # => Go Piotr!
 
 For more complex example see [Integration](#6-integration) section.
 
-### 4.9 Defining callbacks
+### 4.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.
 
@@ -743,7 +778,7 @@ fm.on_enter_yellow do |event|
 end
 ```
 
-### 4.10 Asynchronous callbacks
+### 4.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:
 
@@ -759,12 +794,12 @@ or
 
 This will ensure that when the callback is fired it will run in seperate thread outside of the main execution thread.
 
-### 4.11 Cancelling inside callbacks
+### 4.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
 
 * `on_exit :state_name`
-* `on_enter :event_name`
+* `on_before :event_name`
 
 For example
 

data/lib/finite_machine.rb

@@ -6,11 +6,13 @@ require "sync"
 
 require "finite_machine/version"
 require "finite_machine/threadable"
+require "finite_machine/safety"
 require "finite_machine/thread_context"
 require "finite_machine/callable"
 require "finite_machine/catchable"
 require "finite_machine/async_proxy"
 require "finite_machine/async_call"
+require "finite_machine/hook_event"
 require "finite_machine/event"
 require "finite_machine/event_queue"
 require "finite_machine/hooks"
@@ -34,10 +36,6 @@ module FiniteMachine
 
   ANY_EVENT = :any
 
-  ANY_STATE_HOOK = :state
-
-  ANY_EVENT_HOOK = :event
-
   # Returned when transition has successfully performed
   SUCCEEDED = 1
 
@@ -67,6 +65,9 @@ module FiniteMachine
   # Raised when event queue is already dead
   EventQueueDeadError = Class.new(::StandardError)
 
+  # Raised when argument is already defined
+  AlreadyDefinedError = Class.new(::ArgumentError)
+
   Environment = Struct.new(:target)
 
   class << self

data/lib/finite_machine/dsl.rb

@@ -73,7 +73,7 @@ module FiniteMachine
         machine.initial_state = state
       end
       event = proc { event name, from: FiniteMachine::DEFAULT_STATE, to: state }
-      machine.events.call(&event)
+      machine.events_dsl.call(&event)
     end
 
     # Attach state machine to an object
@@ -84,7 +84,7 @@ module FiniteMachine
     # @example
     #   FiniteMachine.define do
     #     target :red
-    #  end
+    #   end
     #
     # @param [Object] object
     #
@@ -117,7 +117,7 @@ module FiniteMachine
     #
     # @api public
     def events(&block)
-      machine.events.call(&block)
+      machine.events_dsl.call(&block)
     end
 
     # Define state machine callbacks
@@ -184,16 +184,16 @@ module FiniteMachine
     # @api public
     def event(name, attrs = {}, &block)
       sync_exclusive do
-        _transition = Transition.new(machine, attrs.merge!(name: name))
-        _transition.define
-        _transition.define_state_methods
-        _transition.define_event
+        attributes = attrs.merge!(name: name)
+        FiniteMachine::StateParser.new(attrs).parse_states do |from, to|
+          attributes.merge!(parsed_states: { from => to })
+          Transition.create(machine, attributes)
+        end
       end
     end
   end # EventsDSL
 
   class ErrorsDSL < GenericDSL
-
     # Add error handler
     #
     # @param [Array] exceptions

data/lib/finite_machine/event.rb

@@ -1,68 +1,84 @@
 # encoding: utf-8
 
 module FiniteMachine
-  # A class responsible for event notification
+  # A class representing event with transitions
   class Event
     include Threadable
 
-    MESSAGE = :trigger
+    # The name of this event
+    attr_threadsafe :name
 
-    # Event state
-    attr_threadsafe :state
+    # The state transitions for this event
+    attr_threadsafe :state_transitions
 
-    # Event type
-    attr_threadsafe :type
+    # The reference to the state machine for this event
+    attr_threadsafe :machine
 
-    # Data associated with the event
-    attr_threadsafe :data
-
-    # Transition associated with the event
-    attr_threadsafe :transition
-
-    def initialize(state, transition, *data, &block)
-      @state = state
-      @transition = transition
-      @data  = *data
-      @type  = self.class.event_name
+    # @api private
+    def initialize(machine, attrs = {})
+      @machine = machine
+      @name    = attrs.fetch(:name, DEFAULT_STATE)
+      @state_transitions = []
+      # TODO: add event conditions
     end
 
-    def notify(subscriber, *args, &block)
-      if subscriber.respond_to? MESSAGE
-        subscriber.public_send(MESSAGE, self, *args, &block)
+    # Add transition for this event
+    #
+    # @param [FiniteMachine::Transition] transition
+    #
+    # @example
+    #   event << FiniteMachine::Transition.new machine, :a => :b
+    #
+    # @return [nil]
+    #
+    # @api public
+    def <<(transition)
+      sync_exclusive do
+        Array(transition).flatten.each { |trans| state_transitions << trans }
       end
     end
+    alias_method :add, :<<
+
+    # Find next transition
+    #
+    # @return [FiniteMachine::Transition]
+    #
+    # @api private
+    def next_transition
+      state_transitions.find do |transition|
+        transition.from_state == machine.current ||
+          transition.from_state == ANY_STATE
+      end || state_transitions.first
+    end
 
-    class Anystate < Event; end
-
-    class Enterstate < Anystate; end
-
-    class Transitionstate < Anystate; end
-
-    class Exitstate < Anystate; end
-
-    class Anyaction < Event; end
-
-    class Enteraction < Anyaction; end
-
-    class Transitionaction < Anyaction; end
-
-    class Exitaction < Anyaction; end
-
-    EVENTS = Anystate, Enterstate, Transitionstate, Exitstate,
-             Anyaction, Enteraction, Transitionaction, Exitaction
-
-    def self.event_name
-      name.split('::').last.downcase.to_sym
+    # Trigger this event
+    #
+    # @return [nil]
+    #
+    # @api public
+    def call(*args, &block)
+      sync_exclusive do
+        _transition = next_transition
+        machine.send(:transition, _transition, *args, &block)
+      end
     end
 
-    def self.to_s
-      event_name
+    # Return event name
+    #
+    # @return [String]
+    #
+    # @api public
+    def to_s
+      name.to_s
     end
 
-    EVENTS.each do |event|
-      (class << self; self; end).class_eval do
-        define_method(event.event_name) { event }
-      end
+    # Return string representation
+    #
+    # @return [String]
+    #
+    # @api public
+    def inspect
+      "<##{self.class} @name=#{@name}, @transitions=#{state_transitions.inspect}>"
     end
   end # Event
 end # FiniteMachine