state_machines 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6093c9c0c586ab9b799627afd14d9cf686a13881
-  data.tar.gz: f7457d8d6f8ed9df8fa7da0fed6e74599aa59712
+  metadata.gz: 3eee931d0f563b659a9e786dc0eea93ed9f9f537
+  data.tar.gz: f53da4d08eecd750e4b416f5926e31b49be341f1
 SHA512:
-  metadata.gz: 9222dfe808bb45c75521177c470dff45522cae32155b2e65e18a221d53cae07d2b59b5431a0717b8ab2f6a472efc944bf13c7f1527b2e8913295ec135335a6e3
-  data.tar.gz: b7f3fbfd31a5062b745ca131a7916739baca538c0254ed2ec495e2e57f7e13561bd4ef0da772a4aa035d560649f6f0d74f5707c87c200bf40f3de3348c05db58
+  metadata.gz: c1fde9ad6a6b0fb3a3f066a87f7f80c90d78c9f7d633f92f67ff0f3104bc01d16bddf4485f1b24ab3dc35bd14e6e348b8bc3ee8f45cce9edc89ef771869b9229
+  data.tar.gz: 9f07e5b0c0d579557d0a4648b909922a85f45653366ed37e738a3176d52e4ef5ed586471395ea1ca1fcf22109a2d3dda0139e7676f9199666348c108904cabdc

data/Gemfile

@@ -1,4 +1,2 @@
 source 'https://rubygems.org'
-
-# Specify your gem's dependencies in state_machines.gemspec
 gemspec

data/README.md

@@ -1,3 +1,5 @@
+[![Build Status](https://travis-ci.org/seuros/state_machines.svg?branch=master)](https://travis-ci.org/seuros/state_machines)
+[![Code Climate](https://codeclimate.com/github/seuros/state_machines.png)](https://codeclimate.com/github/seuros/state_machines)
 # State Machines
 
 State Machines adds support for creating state machines for attributes on any Ruby class.
@@ -20,6 +22,29 @@ Or install it yourself as:
 
 TODO: Write usage instructions here
 
+## Dependencies
+
+Ruby versions officially supported and tested:
+
+* Ruby (MRI) 1.9.3+
+* JRuby (1.9)
+* Rubinius
+
+
+
+For graphing state machine:
+
+* [state_machines-graphviz](http://github.com/seuros/state_machines-graphviz)
+
+For documenting state machines:
+
+* [state_machines-yard](http://github.com/seuros/state_machines-yard)
+
+
+## TODO
+
+Add matchers/assertions for rspec and minitest
+
 ## Contributing
 
 1. Fork it ( https://github.com/seuros/state_machines/fork )

data/Rakefile

@@ -1 +1,10 @@
-require 'bundler/gem_tasks'
+require 'rubygems'
+require 'bundler/setup'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+end
+
+desc 'Default: run all tests.'
+task :default => :spec

data/lib/state_machines/branch.rb

@@ -1,7 +1,3 @@
-require 'state_machines/matcher'
-require 'state_machines/eval_helpers'
-require 'state_machines/assertions'
-
 module StateMachines
   # Represents a set of requirements that must be met in order for a transition
   # or callback to occur.  Branches verify that the event, from state, and to

data/lib/state_machines/core.rb

@@ -3,23 +3,41 @@
 # * StateMachines::MacroMethods which adds the state_machine DSL to your class
 # * A set of initializers for setting state_machine defaults based on the current
 #   running environment (such as within Rails)
-require 'state_machines/error'
 require 'state_machines/assertions'
+require 'state_machines/error'
 
-require 'state_machines/machine_collection'
 require 'state_machines/extensions'
 
-require 'state_machines/integrations/base'
 require 'state_machines/integrations'
+require 'state_machines/integrations/base'
+
+require 'state_machines/eval_helpers'
+
+require 'singleton'
+require 'state_machines/matcher'
+require 'state_machines/matcher_helpers'
+
+require 'state_machines/transition'
+require 'state_machines/transition_collection'
+
+require 'state_machines/branch'
 
 require 'state_machines/helper_module'
 require 'state_machines/state'
-require 'state_machines/event'
 require 'state_machines/callback'
 require 'state_machines/node_collection'
+
+require 'state_machines/state_context'
+require 'state_machines/state'
 require 'state_machines/state_collection'
+
+require 'state_machines/event'
 require 'state_machines/event_collection'
+
+require 'state_machines/path'
 require 'state_machines/path_collection'
-require 'state_machines/matcher_helpers'
+
 require 'state_machines/machine'
+require 'state_machines/machine_collection'
+
 require 'state_machines/macro_methods'

data/lib/state_machines/error.rb

@@ -3,11 +3,90 @@ module StateMachines
   class Error < StandardError
     # The object that failed
     attr_reader :object
-    
+
     def initialize(object, message = nil) #:nodoc:
       @object = object
-      
+
       super(message)
     end
   end
+
+  # An invalid integration was specified
+  class IntegrationNotFound < Error
+    def initialize(name)
+      super(nil, "#{name.inspect} is an invalid integration")
+    end
+  end
+
+  # An invalid integration was registered
+  class IntegrationError < StandardError
+  end
+
+  # An invalid event was specified
+  class InvalidEvent < Error
+    # The event that was attempted to be run
+    attr_reader :event
+
+    def initialize(object, event_name) #:nodoc:
+      @event = event_name
+
+      super(object, "#{event.inspect} is an unknown state machine event")
+    end
+  end
+  # An invalid transition was attempted
+  class InvalidTransition < Error
+    # The machine attempting to be transitioned
+    attr_reader :machine
+
+    # The current state value for the machine
+    attr_reader :from
+
+    def initialize(object, machine, event) #:nodoc:
+      @machine = machine
+      @from_state = machine.states.match!(object)
+      @from = machine.read(object, :state)
+      @event = machine.events.fetch(event)
+      errors = machine.errors_for(object)
+
+      message = "Cannot transition #{machine.name} via :#{self.event} from #{from_name.inspect}"
+      message << " (Reason(s): #{errors})" unless errors.empty?
+      super(object, message)
+    end
+
+    # The event that triggered the failed transition
+    def event
+      @event.name
+    end
+
+    # The fully-qualified name of the event that triggered the failed transition
+    def qualified_event
+      @event.qualified_name
+    end
+
+    # The name for the current state
+    def from_name
+      @from_state.name
+    end
+
+    # The fully-qualified name for the current state
+    def qualified_from_name
+      @from_state.qualified_name
+    end
+  end
+
+  # A set of transition failed to run in parallel
+  class InvalidParallelTransition < Error
+    # The set of events that failed the transition(s)
+    attr_reader :events
+
+    def initialize(object, events) #:nodoc:
+      @events = events
+
+      super(object, "Cannot run events in parallel: #{events * ', '}")
+    end
+  end
+
+  # A method was called in an invalid state context
+  class InvalidContext < Error
+  end
 end

data/lib/state_machines/event.rb

@@ -1,22 +1,4 @@
-require 'state_machines/transition'
-require 'state_machines/branch'
-require 'state_machines/assertions'
-require 'state_machines/matcher_helpers'
-require 'state_machines/error'
-
 module StateMachines
-  # An invalid event was specified
-  class InvalidEvent < Error
-    # The event that was attempted to be run
-    attr_reader :event
-
-    def initialize(object, event_name) #:nodoc:
-      @event = event_name
-
-      super(object, "#{event.inspect} is an unknown state machine event")
-    end
-  end
-
   # An event defines an action that transitions an attribute from one state to
   # another.  The state that an attribute is transitioned to depends on the
   # branches configured for the event.
@@ -58,8 +40,8 @@ module StateMachines
       reset
 
       # Output a warning if another event has a conflicting qualified name
-      if conflict = machine.owner_class.state_machines.detect { |other_name, other_machine| other_machine != @machine && other_machine.events[qualified_name, :qualified_name] }
-        name, other_machine = conflict
+      if conflict = machine.owner_class.state_machines.detect { |_other_name, other_machine| other_machine != @machine && other_machine.events[qualified_name, :qualified_name] }
+        _name, other_machine = conflict
         warn "Event #{qualified_name.inspect} for #{machine.name.inspect} is already defined in #{other_machine.name.inspect}"
       else
         add_actions

data/lib/state_machines/event_collection.rb

@@ -1,12 +1,10 @@
-require 'state_machines/node_collection'
-
 module StateMachines
   # Represents a collection of events in a state machine
   class EventCollection < NodeCollection
     def initialize(machine) #:nodoc:
       super(machine, :index => [:name, :qualified_name])
     end
-    
+
     # Gets the list of events that can be fired on the given object.
     # 
     # Valid requirement options:
@@ -41,9 +39,9 @@ module StateMachines
     #   vehicle.state = 'idling'
     #   events.valid_for(vehicle)           # => [#<StateMachines::Event name=:park transitions=[:idling => :parked]>]
     def valid_for(object, requirements = {})
-      match(requirements).select {|event| event.can_fire?(object, requirements)}
+      match(requirements).select { |event| event.can_fire?(object, requirements) }
     end
-    
+
     # Gets the list of transitions that can be run on the given object.
     # 
     # Valid requirement options:
@@ -81,9 +79,9 @@ module StateMachines
     #   # Search for explicit transitions regardless of the current state
     #   events.transitions_for(vehicle, :from => :parked) # => [#<StateMachines::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
     def transitions_for(object, requirements = {})
-      match(requirements).map {|event| event.transition_for(object, requirements)}.compact
+      match(requirements).map { |event| event.transition_for(object, requirements) }.compact
     end
-    
+
     # Gets the transition that should be performed for the event stored in the
     # given object's event attribute.  This also takes an additional parameter
     # for automatically invalidating the object if the event or transition are
@@ -115,27 +113,27 @@ module StateMachines
     #   events.attribute_transition_for(vehicle)    # => #<StateMachines::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>
     def attribute_transition_for(object, invalidate = false)
       return unless machine.action
-      
-      result = machine.read(object, :event_transition) || if event_name = machine.read(object, :event)
-        if event = self[event_name.to_sym, :name]
-          event.transition_for(object) || begin
-            # No valid transition: invalidate
-            machine.invalidate(object, :event, :invalid_event, [[:state, machine.states.match!(object).human_name(object.class)]]) if invalidate
-            false
-          end
-        else
-          # Event is unknown: invalidate
-          machine.invalidate(object, :event, :invalid) if invalidate
-          false
-        end
-      end
-      
-      result
+
+      # TODO, simplify
+      machine.read(object, :event_transition) || if event_name = machine.read(object, :event)
+                                                   if event = self[event_name.to_sym, :name]
+                                                     event.transition_for(object) || begin
+                                                                                       # No valid transition: invalidate
+                                                       machine.invalidate(object, :event, :invalid_event, [[:state, machine.states.match!(object).human_name(object.class)]]) if invalidate
+                                                       false
+                                                     end
+                                                   else
+                                                     # Event is unknown: invalidate
+                                                     machine.invalidate(object, :event, :invalid) if invalidate
+                                                     false
+                                                   end
+                                                 end
+
     end
-    
+
     private
-      def match(requirements) #:nodoc:
-        requirements && requirements[:on] ? [fetch(requirements.delete(:on))] : self
-      end
+    def match(requirements) #:nodoc:
+      requirements && requirements[:on] ? [fetch(requirements.delete(:on))] : self
+    end
   end
 end

data/lib/state_machines/extensions.rb

@@ -1,4 +1,3 @@
-
 module StateMachines
   module ClassMethods
     def self.extended(base) #:nodoc:
@@ -6,20 +5,20 @@ module StateMachines
         @state_machines = MachineCollection.new
       end
     end
-    
+
     # Gets the current list of state machines defined for this class.  This
     # class-level attribute acts like an inheritable attribute.  The attribute
     # is available to each subclass, each having a copy of its superclass's
     # attribute.
-    # 
+    #
     # The hash of state machines maps <tt>:attribute</tt> => +machine+, e.g.
-    # 
+    #
     #   Vehicle.state_machines # => {:state => #<StateMachines::Machine:0xb6f6e4a4 ...>}
     def state_machines
       @state_machines ||= superclass.state_machines.dup
     end
   end
-  
+
   module InstanceMethods
     # Runs one or more events in parallel.  All events will run through the
     # following steps:
@@ -27,7 +26,7 @@ module StateMachines
     # * Persist state
     # * Invoke action
     # * After callbacks
-    # 
+    #
     # For example, if two events (for state machines A and B) are run in
     # parallel, the order in which steps are run is:
     # * A - Before transition callbacks
@@ -38,62 +37,62 @@ module StateMachines
     # * B - Invoke action (only if different than A's action)
     # * A - After transition callbacks
     # * B - After transition callbacks
-    # 
+    #
     # *Note* that multiple events on the same state machine / attribute cannot
     # be run in parallel.  If this is attempted, an ArgumentError will be
     # raised.
-    # 
+    #
     # == Halting callbacks
-    # 
+    #
     # When running multiple events in parallel, special consideration should
     # be taken with regard to how halting within callbacks affects the flow.
-    # 
+    #
     # For *before* callbacks, any <tt>:halt</tt> error that's thrown will
     # immediately cancel the perform for all transitions.  As a result, it's
     # possible for one event's transition to affect the continuation of
     # another.
-    # 
+    #
     # On the other hand, any <tt>:halt</tt> error that's thrown within an
     # *after* callback with only affect that event's transition.  Other
     # transitions will continue to run their own callbacks.
-    # 
+    #
     # == Example
-    # 
+    #
     #   class Vehicle
     #     state_machine :initial => :parked do
     #       event :ignite do
     #         transition :parked => :idling
     #       end
-    #       
+    #
     #       event :park do
     #         transition :idling => :parked
     #       end
     #     end
-    #     
+    #
     #     state_machine :alarm_state, :namespace => 'alarm', :initial => :on do
     #       event :enable do
     #         transition all => :active
     #       end
-    #       
+    #
     #       event :disable do
     #         transition all => :off
     #       end
     #     end
     #   end
-    #   
+    #
     #   vehicle = Vehicle.new                         # => #<Vehicle:0xb7c02850 @state="parked", @alarm_state="active">
     #   vehicle.state                                 # => "parked"
     #   vehicle.alarm_state                           # => "active"
-    #   
+    #
     #   vehicle.fire_events(:ignite, :disable_alarm)  # => true
     #   vehicle.state                                 # => "idling"
     #   vehicle.alarm_state                           # => "off"
-    #   
+    #
     #   # If any event fails, the entire event chain fails
     #   vehicle.fire_events(:ignite, :enable_alarm)   # => false
     #   vehicle.state                                 # => "idling"
     #   vehicle.alarm_state                           # => "off"
-    #   
+    #
     #   # Exception raised on invalid event
     #   vehicle.fire_events(:park, :invalid)          # => StateMachines::InvalidEvent: :invalid is an unknown event
     #   vehicle.state                                 # => "idling"
@@ -101,48 +100,49 @@ module StateMachines
     def fire_events(*events)
       self.class.state_machines.fire_events(self, *events)
     end
-    
+
     # Run one or more events in parallel.  If any event fails to run, then
     # a StateMachines::InvalidTransition exception will be raised.
-    # 
+    #
     # See StateMachines::InstanceMethods#fire_events for more information.
-    # 
+    #
     # == Example
-    # 
+    #
     #   class Vehicle
     #     state_machine :initial => :parked do
     #       event :ignite do
     #         transition :parked => :idling
     #       end
-    #       
+    #
     #       event :park do
     #         transition :idling => :parked
     #       end
     #     end
-    #     
+    #
     #     state_machine :alarm_state, :namespace => 'alarm', :initial => :active do
     #       event :enable do
     #         transition all => :active
     #       end
-    #       
+    #
     #       event :disable do
     #         transition all => :off
     #       end
     #     end
     #   end
-    #   
+    #
     #   vehicle = Vehicle.new                         # => #<Vehicle:0xb7c02850 @state="parked", @alarm_state="active">
     #   vehicle.fire_events(:ignite, :disable_alarm)  # => true
-    #   
+    #
     #   vehicle.fire_events!(:ignite, :disable_alarm) # => StateMachines::InvalidTranstion: Cannot run events in parallel: ignite, disable_alarm
     def fire_events!(*events)
       run_action = [true, false].include?(events.last) ? events.pop : true
-      fire_events(*(events + [run_action])) || raise(StateMachines::InvalidParallelTransition.new(self, events))
+      fire_events(*(events + [run_action])) || fail(StateMachines::InvalidParallelTransition.new(self, events))
     end
-    
+
     protected
-      def initialize_state_machines(options = {}, &block) #:nodoc:
-        self.class.state_machines.initialize_states(self, options, &block)
-      end
+
+    def initialize_state_machines(options = {}, &block) #:nodoc:
+      self.class.state_machines.initialize_states(self, options, &block)
+    end
   end
 end