state_machine 1.0.2 → 1.0.3

data/lib/state_machine/integrations/mongo_mapper.rb

@@ -187,6 +187,11 @@ module StateMachine
     # Because of the way named scopes work in MongoMapper, they *cannot* be
     # chained.
     # 
+    # Note that states can also be referenced by the string version of their
+    # name:
+    # 
+    #   Vehicle.with_state('parked')
+    # 
     # == Callbacks
     # 
     # All before/after transition callbacks defined for MongoMapper models
@@ -219,6 +224,56 @@ module StateMachine
     # 
     # Note, also, that the transition can be accessed by simply defining
     # additional arguments in the callback block.
+    # 
+    # == Internationalization
+    # 
+    # Any error message that is generated from performing invalid transitions
+    # can be localized.  The following default translations are used:
+    # 
+    #   en:
+    #     mongo_mapper:
+    #       errors:
+    #         messages:
+    #           invalid: "is invalid"
+    #           # %{value} = attribute value, %{state} = Human state name
+    #           invalid_event: "cannot transition when %{state}"
+    #           # %{value} = attribute value, %{event} = Human event name, %{state} = Human current state name
+    #           invalid_transition: "cannot transition via %{event}"
+    # 
+    # You can override these for a specific model like so:
+    # 
+    #   en:
+    #     mongo_mapper:
+    #       errors:
+    #         models:
+    #           user:
+    #             invalid: "is not valid"
+    # 
+    # In addition to the above, you can also provide translations for the
+    # various states / events in each state machine.  Using the Vehicle example,
+    # state translations will be looked for using the following keys, where
+    # +model_name+ = "vehicle", +machine_name+ = "state" and +state_name+ = "parked":
+    # * <tt>mongo_mapper.state_machines.#{model_name}.#{machine_name}.states.#{state_name}</tt>
+    # * <tt>mongo_mapper.state_machines.#{model_name}.states.#{state_name}</tt>
+    # * <tt>mongo_mapper.state_machines.#{machine_name}.states.#{state_name}</tt>
+    # * <tt>mongo_mapper.state_machines.states.#{state_name}</tt>
+    # 
+    # Event translations will be looked for using the following keys, where
+    # +model_name+ = "vehicle", +machine_name+ = "state" and +event_name+ = "ignite":
+    # * <tt>mongo_mapper.state_machines.#{model_name}.#{machine_name}.events.#{event_name}</tt>
+    # * <tt>mongo_mapper.state_machines.#{model_name}.events.#{event_name}</tt>
+    # * <tt>mongo_mapper.state_machines.#{machine_name}.events.#{event_name}</tt>
+    # * <tt>mongo_mapper.state_machines.events.#{event_name}</tt>
+    # 
+    # An example translation configuration might look like so:
+    # 
+    #   es:
+    #     mongo_mapper:
+    #       state_machines:
+    #         states:
+    #           parked: 'estacionado'
+    #         events:
+    #           park: 'estacionarse'
     module MongoMapper
       include Base
       include ActiveModel

data/lib/state_machine/integrations/mongo_mapper/versions.rb

@@ -22,7 +22,7 @@ module StateMachine
       
       version '0.5.x - 0.7.x' do
         def self.active?
-          !defined?(::MongoMapper::Version) || ::MongoMapper::Version < '0.8.0'
+          !defined?(::MongoMapper::Version) || ::MongoMapper::Version =~ /^0\.[5-7]\./
         end
         
         def define_scope(name, scope)
@@ -32,7 +32,7 @@ module StateMachine
       
       version '0.5.x - 0.8.x' do
         def self.active?
-          !defined?(::MongoMapper::Version) || ::MongoMapper::Version < '0.9.0'
+          !defined?(::MongoMapper::Version) || ::MongoMapper::Version =~ /^0\.[5-8]\./
         end
         
         def invalidate(object, attribute, message, values = [])
@@ -80,7 +80,7 @@ module StateMachine
         def self.active?
           # Only 0.8.x and up has a Version string available, so Plugins is used
           # to detect when 0.7.x is active
-          defined?(::MongoMapper::Plugins) && (!defined?(::MongoMapper::Version) || ::MongoMapper::Version <= '0.8.3')
+          defined?(::MongoMapper::Plugins) && (!defined?(::MongoMapper::Version) || ::MongoMapper::Version =~ /^0\.(7|8\.[0-3])\./)
         end
         
         def define_state_initializer

data/lib/state_machine/integrations/mongoid.rb

@@ -181,6 +181,11 @@ module StateMachine
     # Because of the way named scopes work in Mongoid, they *cannot* be
     # chained.
     # 
+    # Note that states can also be referenced by the string version of their
+    # name:
+    # 
+    #   Vehicle.with_state('parked')
+    # 
     # == Callbacks
     # 
     # All before/after transition callbacks defined for Mongoid models
@@ -269,6 +274,56 @@ module StateMachine
     #       Audit.log(record, transition)
     #     end
     #   end
+    # 
+    # == Internationalization
+    # 
+    # Any error message that is generated from performing invalid transitions
+    # can be localized.  The following default translations are used:
+    # 
+    #   en:
+    #     mongoid:
+    #       errors:
+    #         messages:
+    #           invalid: "is invalid"
+    #           # %{value} = attribute value, %{state} = Human state name
+    #           invalid_event: "cannot transition when %{state}"
+    #           # %{value} = attribute value, %{event} = Human event name, %{state} = Human current state name
+    #           invalid_transition: "cannot transition via %{event}"
+    # 
+    # You can override these for a specific model like so:
+    # 
+    #   en:
+    #     mongoid:
+    #       errors:
+    #         models:
+    #           user:
+    #             invalid: "is not valid"
+    # 
+    # In addition to the above, you can also provide translations for the
+    # various states / events in each state machine.  Using the Vehicle example,
+    # state translations will be looked for using the following keys, where
+    # +model_name+ = "vehicle", +machine_name+ = "state" and +state_name+ = "parked":
+    # * <tt>mongoid.state_machines.#{model_name}.#{machine_name}.states.#{state_name}</tt>
+    # * <tt>mongoid.state_machines.#{model_name}.states.#{state_name}</tt>
+    # * <tt>mongoid.state_machines.#{machine_name}.states.#{state_name}</tt>
+    # * <tt>mongoid.state_machines.states.#{state_name}</tt>
+    # 
+    # Event translations will be looked for using the following keys, where
+    # +model_name+ = "vehicle", +machine_name+ = "state" and +event_name+ = "ignite":
+    # * <tt>mongoid.state_machines.#{model_name}.#{machine_name}.events.#{event_name}</tt>
+    # * <tt>mongoid.state_machines.#{model_name}.events.#{event_name}</tt>
+    # * <tt>mongoid.state_machines.#{machine_name}.events.#{event_name}</tt>
+    # * <tt>mongoid.state_machines.events.#{event_name}</tt>
+    # 
+    # An example translation configuration might look like so:
+    # 
+    #   es:
+    #     mongoid:
+    #       state_machines:
+    #         states:
+    #           parked: 'estacionado'
+    #         events:
+    #           park: 'estacionarse'
     module Mongoid
       include Base
       include ActiveModel
@@ -307,19 +362,9 @@ module StateMachine
         # object
         def define_state_initializer
           define_helper :instance, <<-end_eval, __FILE__, __LINE__ + 1
-            # Initializes dynamic states
             def initialize(*)
-              super do |*args|
-                self.class.state_machines.initialize_states(self, :static => false)
-                yield(*args) if block_given?
-              end
-            end
-            
-            # Initializes static states
-            def apply_default_attributes(*)
-              result = super
-              self.class.state_machines.initialize_states(self, :dynamic => false, :to => result) if new_record?
-              result
+              @attributes = {}
+              self.class.state_machines.initialize_states(self) { super }
             end
           end_eval
         end

data/lib/state_machine/integrations/mongoid/versions.rb

@@ -1,10 +1,28 @@
 module StateMachine
   module Integrations #:nodoc:
     module Mongoid
-      # Assumes Mongoid 2.2+ uses ActiveModel 3.1+
-      version '2.0.x - 2.1.x' do
+      version '2.0.x - 2.2.x' do
         def self.active?
-          ::Mongoid::VERSION >= '2.0.0' && ::Mongoid::VERSION < '2.2.0'
+          ::Mongoid::VERSION =~ /^2\.[0-2]\./
+        end
+        
+        def define_state_initializer
+          define_helper :instance, <<-end_eval, __FILE__, __LINE__ + 1
+            # Initializes dynamic states
+            def initialize(*)
+              super do |*args|
+                self.class.state_machines.initialize_states(self, :static => false)
+                yield(*args) if block_given?
+              end
+            end
+            
+            # Initializes static states
+            def apply_default_attributes(*)
+              result = super
+              self.class.state_machines.initialize_states(self, :dynamic => false, :to => result) if new_record?
+              result
+            end
+          end_eval
         end
         
         def define_action_hook
@@ -16,7 +34,7 @@ module StateMachine
       
       version '2.0.x' do
         def self.active?
-          ::Mongoid::VERSION >= '2.0.0' && ::Mongoid::VERSION < '2.1.0'
+          ::Mongoid::VERSION =~ /^2\.0\./
         end
         
         # Forces the change in state to be recognized regardless of whether the

data/lib/state_machine/integrations/sequel.rb

@@ -193,6 +193,11 @@ module StateMachine
     # 
     #   Vehicle.with_state(:parked).order(:id.desc)
     # 
+    # Note that states can also be referenced by the string version of their
+    # name:
+    # 
+    #   Vehicle.with_state('parked')
+    # 
     # == Callbacks
     # 
     # All before/after transition callbacks defined for Sequel resources
@@ -224,6 +229,34 @@ module StateMachine
     # 
     # Note, also, that the transition can be accessed by simply defining
     # additional arguments in the callback block.
+    # 
+    # === Failure callbacks
+    # 
+    # +after_failure+ callbacks allow you to execute behaviors when a transition
+    # is allowed, but fails to save.  This could be useful for something like
+    # auditing transition attempts.  Since callbacks run within transactions in
+    # Sequel, a save failure will cause any records that get created in
+    # your callback to roll back.  You can work around this issue like so:
+    # 
+    #   DB = Sequel.connect('mysql://localhost/app')
+    #   DB_LOGS = Sequel.connect('mysql://localhost/app')
+    #   
+    #   class TransitionLog < Sequel::Model(DB_LOGS[:transition_logs])
+    #   end
+    #   
+    #   class Vehicle < Sequel::Model(DB[:vehicles])
+    #     state_machine do
+    #       after_failure do |transition|
+    #         TransitionLog.create(:vehicle => vehicle, :transition => transition)
+    #       end
+    #       
+    #       ...
+    #     end
+    #   end
+    # 
+    # The +TransitionLog+ model uses a second connection to the database that
+    # allows new records to be saved without being affected by rollbacks in the
+    # +Vehicle+ model's transaction.
     module Sequel
       include Base
       
@@ -276,6 +309,18 @@ module StateMachine
       end
       
       protected
+        # Initializes class-level extensions for this machine
+        def define_helpers
+          load_plugins
+          super
+        end
+        
+        # Loads all of the Sequel plugins necessary to run
+        def load_plugins
+          owner_class.plugin(:validation_class_methods)
+          owner_class.plugin(:hook_class_methods)
+        end
+        
         # Loads the built-in inflector
         def load_inflector
           require 'sequel/extensions/inflector'

data/lib/state_machine/integrations/sequel/versions.rb

@@ -73,6 +73,9 @@ module StateMachine
           !defined?(::Sequel::MAJOR) || ::Sequel::MAJOR == 2 && ::Sequel::MINOR <= 11
         end
         
+        def load_plugins
+        end
+        
         def load_inflector
         end
         

data/lib/state_machine/machine.rb

@@ -139,11 +139,60 @@ module StateMachine
   #   vehicle.save            # => true (no exception raised)
   # 
   # If you need callbacks to get triggered when an object is created, this
-  # should be done by either:
-  # * Use a <tt>before :save</tt> or equivalent hook, or
-  # * Set an initial state of nil and use the correct event to create the
+  # should be done by one of the following techniques:
+  # * Use a <tt>before :create</tt> or equivalent hook:
+  # 
+  #     class Vehicle
+  #       before :create, :track_initial_transition
+  #       
+  #       state_machine do
+  #         ...
+  #       end
+  #     end
+  # 
+  # * Set an initial state and use the correct event to create the
   #   object with the proper state, resulting in callbacks being triggered and
-  #   the object getting persisted
+  #   the object getting persisted (note that the <tt>:pending</tt> state is
+  #   actually stored as nil):
+  # 
+  #     class Vehicle
+  #        state_machine :initial => :pending
+  #         after_transition :pending => :parked, :do => :track_initial_transition
+  #         
+  #         event :park do
+  #           transition :pending => :parked
+  #         end
+  #         
+  #         state :pending, :value => nil
+  #       end
+  #     end
+  #     
+  #     vehicle = Vehicle.new
+  #     vehicle.park
+  # 
+  # * Use a default event attribute that will automatically trigger when the
+  #   configured action gets run (note that the <tt>:pending</tt> state is
+  #   actually stored as nil):
+  # 
+  #     class Vehicle < ActiveRecord::Base
+  #       state_machine :initial => :pending
+  #         after_transition :pending => :parked, :do => :track_initial_transition
+  #         
+  #         event :park do
+  #           transition :pending => :parked
+  #         end
+  #         
+  #         state :pending, :value => nil
+  #       end
+  #       
+  #       def initialize(*)
+  #         super
+  #         self.state_event = 'park'
+  #       end
+  #     end
+  #     
+  #     vehicle = Vehicle.new
+  #     vehicle.save
   # 
   # === Canceling callbacks
   # 
@@ -301,7 +350,7 @@ module StateMachine
   # module that gets included in every Object.  As a result, state_machine will
   # generate the following warning:
   # 
-  #   Instance method "open" is already defined in Object, use generic helper instead.
+  #   Instance method "open" is already defined in Object, use generic helper instead or set StateMachine::Machine.ignore_method_conflicts = true.
   # 
   # Even though you may not be using Kernel's implementation of the "open"
   # instance method, state_machine isn't aware of this and, as a result, stays
@@ -696,7 +745,7 @@ module StateMachine
       if block_given?
         if !self.class.ignore_method_conflicts && conflicting_ancestor = owner_class_ancestor_has_method?(scope, method)
           ancestor_name = conflicting_ancestor.name && !conflicting_ancestor.name.empty? ? conflicting_ancestor.name : conflicting_ancestor.to_s
-          warn "#{scope == :class ? 'Class' : 'Instance'} method \"#{method}\" is already defined in #{ancestor_name}, use generic helper instead."
+          warn "#{scope == :class ? 'Class' : 'Instance'} method \"#{method}\" is already defined in #{ancestor_name}, use generic helper instead or set StateMachine::Machine.ignore_method_conflicts = true."
         else
           name = self.name
           helper_module.class_eval do
@@ -923,6 +972,28 @@ module StateMachine
     #   vehicle.state = 'backing_up'
     #   vehicle.speed               # => NoMethodError: undefined method 'speed' for #<Vehicle:0xb7d296ac> in state "backing_up"
     # 
+    # === Using matchers
+    # 
+    # The +all+ / +any+ matchers can be used to easily define behaviors for a
+    # group of states.  Note, however, that you cannot use these matchers to
+    # set configurations for states.  Behaviors using these matchers can be
+    # defined at any point in the state machine and will always get applied to
+    # the proper states.
+    # 
+    # For example:
+    # 
+    #   state_machine :initial => :parked do
+    #     ...
+    #     
+    #     state all - [:parked, :idling, :stalled] do
+    #       validates_presence_of :speed
+    #       
+    #       def speed
+    #         gear * 10
+    #       end
+    #     end
+    #   end
+    # 
     # == State-aware class methods
     # 
     # In addition to defining scopes for instance methods that are state-aware,
@@ -959,17 +1030,29 @@ module StateMachine
       options = names.last.is_a?(Hash) ? names.pop : {}
       assert_valid_keys(options, :value, :cache, :if, :human_name)
       
-      states = add_states(names)
-      states.each do |state|
-        if options.include?(:value)
-          state.value = options[:value]
-          self.states.update(state)
-        end
+      # Store the context so that it can be used for / matched against any state
+      # that gets added
+      @states.context(names, &block) if block_given?
+      
+      if names.first.is_a?(Matcher)
+        # Add any states referenced in the matcher.  When matchers are used,
+        # states are not allowed to be configured.
+        raise ArgumentError, "Cannot configure states when using matchers (using #{options.inspect})" if options.any?
+        states = add_states(names.first.values)
+      else
+        states = add_states(names)
         
-        state.human_name = options[:human_name] if options.include?(:human_name)
-        state.cache = options[:cache] if options.include?(:cache)
-        state.matcher = options[:if] if options.include?(:if)
-        state.context(&block) if block_given?
+        # Update the configuration for the state(s)
+        states.each do |state|
+          if options.include?(:value)
+            state.value = options[:value]
+            self.states.update(state)
+          end
+          
+          state.human_name = options[:human_name] if options.include?(:human_name)
+          state.cache = options[:cache] if options.include?(:cache)
+          state.matcher = options[:if] if options.include?(:if)
+        end
       end
       
       states.length == 1 ? states.first : states
@@ -1038,14 +1121,18 @@ module StateMachine
     #   transition fails, then a StateMachine::InvalidTransition error will be
     #   raised.  If the last argument is a boolean, it will control whether the
     #   machine's action gets run.
-    # * <tt>can_park?(requirements = {})</tt> - Checks whether the "park" event can be fired given
-    #   the current state of the object.  This will *not* run validations in
-    #   ORM integrations.  To check whether an event can fire *and* passes
-    #   validations, use event attributes (e.g. state_event) as described in the
-    #   "Events" documentation of each ORM integration.
-    # * <tt>park_transition(requirements = {})</tt> -  Gets the next transition that would be
-    #   performed if the "park" event were to be fired now on the object or nil
-    #   if no transitions can be performed.
+    # * <tt>can_park?(requirements = {})</tt> - Checks whether the "park" event
+    #   can be fired given the current state of the object.  This will *not* run
+    #   validations or callbacks in ORM integrations.  It will only determine if
+    #   the state machine defines a valid transition for the event.  To check
+    #   whether an event can fire *and* passes validations, use event attributes
+    #   (e.g. state_event) as described in the "Events" documentation of each
+    #   ORM integration.
+    # * <tt>park_transition(requirements = {})</tt> -  Gets the next transition
+    #   that would be performed if the "park" event were to be fired now on the
+    #   object or nil if no transitions can be performed.  Like <tt>can_park?</tt>
+    #   this will also *not* run validations or callbacks.  It will only
+    #   determine if the state machine defines a valid transition for the event.
     # 
     # With a namespace of "car", the above names map to the following methods:
     # * <tt>can_park_car?</tt>
@@ -1199,6 +1286,24 @@ module StateMachine
     # the entire arguments list to be accessed by transition callbacks through
     # StateMachine::Transition#args.
     # 
+    # === Using matchers
+    # 
+    # The +all+ / +any+ matchers can be used to easily execute blocks for a
+    # group of events.  Note, however, that you cannot use these matchers to
+    # set configurations for events.  Blocks using these matchers can be
+    # defined at any point in the state machine and will always get applied to
+    # the proper events.
+    # 
+    # For example:
+    # 
+    #   state_machine :initial => :parked do
+    #     ...
+    #     
+    #     event all - [:crash] do
+    #       transition :stalled => :parked
+    #     end
+    #   end
+    # 
     # == Example
     # 
     #   class Vehicle
@@ -1222,16 +1327,25 @@ module StateMachine
       options = names.last.is_a?(Hash) ? names.pop : {}
       assert_valid_keys(options, :human_name)
       
-      events = add_events(names)
-      events.each do |event|
-        event.human_name = options[:human_name] if options.include?(:human_name)
+      # Store the context so that it can be used for / matched against any event
+      # that gets added
+      @events.context(names, &block) if block_given?
+      
+      if names.first.is_a?(Matcher)
+        # Add any events referenced in the matcher.  When matchers are used,
+        # events are not allowed to be configured.
+        raise ArgumentError, "Cannot configure events when using matchers (using #{options.inspect})" if options.any?
+        events = add_events(names.first.values)
+      else
+        events = add_events(names)
         
-        if block_given?
-          event.instance_eval(&block)
+        # Update the configuration for the event(s)
+        events.each do |event|
+          event.human_name = options[:human_name] if options.include?(:human_name)
+          
+          # Add any states that may have been referenced within the event
           add_states(event.known_states)
         end
-        
-        event
       end
       
       events.length == 1 ? events.first : events
@@ -1777,7 +1891,7 @@ module StateMachine
         graphvizVersion = Constants::RGV_VERSION.split('.')
         file = File.join(options[:path], "#{options[:name]}.#{options[:format]}")
         
-        if graphvizVersion[1] == '9' && graphvizVersion[2] == '0'
+        if graphvizVersion[0] == '0' && graphvizVersion[1] == '9' && graphvizVersion[2] == '0'
           outputOptions = {:output => options[:format], :file => file}
         else
           outputOptions = {options[:format] => file}
@@ -1785,8 +1899,8 @@ module StateMachine
         
         graph.output(outputOptions)
         graph
-      rescue LoadError
-        $stderr.puts 'Cannot draw the machine. `gem install ruby-graphviz` >= v0.9.0 and try again.'
+      rescue LoadError => ex
+        $stderr.puts "Cannot draw the machine (#{ex.message}). `gem install ruby-graphviz` >= v0.9.0 and try again."
         false
       end
     end