state_machines 0.5.0 → 0.20.0

data/lib/state_machines/eval_helpers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StateMachines
   # Provides a set of helper methods for evaluating methods within the context
   # of an object.
@@ -7,62 +9,60 @@ module StateMachines
     # * Symbol
     # * Method / Proc
     # * String
-    # 
+    #
     # == Examples
-    # 
+    #
     # Below are examples of the various ways that a method can be evaluated
     # on an object:
-    # 
+    #
     #   class Person
     #     def initialize(name)
     #       @name = name
     #     end
-    #     
+    #
     #     def name
     #       @name
     #     end
     #   end
-    #   
+    #
     #   class PersonCallback
     #     def self.run(person)
     #       person.name
     #     end
     #   end
-    # 
+    #
     #   person = Person.new('John Smith')
-    #   
+    #
     #   evaluate_method(person, :name)                            # => "John Smith"
     #   evaluate_method(person, PersonCallback.method(:run))      # => "John Smith"
     #   evaluate_method(person, Proc.new {|person| person.name})  # => "John Smith"
     #   evaluate_method(person, lambda {|person| person.name})    # => "John Smith"
     #   evaluate_method(person, '@name')                          # => "John Smith"
-    # 
+    #
     # == Additional arguments
-    # 
+    #
     # Additional arguments can be passed to the methods being evaluated.  If
     # the method defines additional arguments other than the object context,
     # then all arguments are required.
-    # 
+    #
     # For example,
-    # 
+    #
     #   person = Person.new('John Smith')
-    #   
+    #
     #   evaluate_method(person, lambda {|person| person.name}, 21)                              # => "John Smith"
     #   evaluate_method(person, lambda {|person, age| "#{person.name} is #{age}"}, 21)          # => "John Smith is 21"
     #   evaluate_method(person, lambda {|person, age| "#{person.name} is #{age}"}, 21, 'male')  # => ArgumentError: wrong number of arguments (3 for 2)
-    def evaluate_method(object, method, *args, &block)
+    def evaluate_method(object, method, *args, **kwargs, &block)
       case method
         when Symbol
           klass = (class << object; self; end)
           args = [] if (klass.method_defined?(method) || klass.private_method_defined?(method)) && object.method(method).arity == 0
-          object.send(method, *args, &block)
-        when Proc, Method
+          object.send(method, *args, **kwargs, &block)
+        when Proc
           args.unshift(object)
           arity = method.arity
-          
-          # Procs don't support blocks in < Ruby 1.9, so it's tacked on as an
-          # argument for consistency across versions of Ruby
-          if block_given? && Proc === method && arity != 0
+          # Handle blocks for Procs
+          if block_given? && arity != 0
             if [1, 2].include?(arity)
               # Force the block to be either the only argument or the 2nd one
               # after the object (may mean additional arguments get discarded)
@@ -75,10 +75,39 @@ module StateMachines
             # These method types are only called with 0, 1, or n arguments
             args = args[0, arity] if [0, 1].include?(arity)
           end
-          
-          method.is_a?(Proc) ? method.call(*args) : method.call(*args, &block)
+
+        # Call the Proc with the arguments
+        method.call(*args, **kwargs)
+
+        when Method
+          args.unshift(object)
+          arity = method.arity
+
+          # Methods handle blocks via &block, not as arguments
+          # Only limit arguments if necessary based on arity
+          args = args[0, arity] if [0, 1].include?(arity)
+
+          # Call the Method with the arguments and pass the block
+          method.call(*args, **kwargs, &block)
         when String
-          eval(method, object.instance_eval {binding}, &block)
+          if block_given?
+            if StateMachines::Transition.pause_supported?
+              eval(method, object.instance_eval { binding }, &block)
+            else
+              # Support for JRuby and Truffle Ruby, which don't support binding blocks
+              eigen = class << object; self; end
+              eigen.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+                  def __temp_eval_method__(*args, &b)
+                    #{method}
+                  end
+                RUBY
+              result = object.__temp_eval_method__(*args, &block)
+              eigen.send(:remove_method, :__temp_eval_method__)
+              result
+            end
+          else
+            eval(method, object.instance_eval { binding })
+          end
         else
           raise ArgumentError, 'Methods must be a symbol denoting the method to call, a block to be invoked, or a string to be evaluated'
       end

data/lib/state_machines/event.rb

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'options_validator'
+
 module StateMachines
   # 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
@@ -12,7 +16,7 @@ module StateMachines
     # The name of the event
     attr_reader :name
 
-    # The fully-qualified name of the event, scoped by the machine's namespace 
+    # The fully-qualified name of the event, scoped by the machine's namespace
     attr_reader :qualified_name
 
     # The human-readable name for the event
@@ -27,20 +31,29 @@ module StateMachines
     attr_reader :known_states
 
     # Creates a new event within the context of the given machine
-    # 
+    #
     # Configuration options:
     # * <tt>:human_name</tt> - The human-readable version of this event's name
-    def initialize(machine, name, options = {}) #:nodoc:
-      options.assert_valid_keys(:human_name)
+    def initialize(machine, name, options = nil, human_name: nil, **extra_options) #:nodoc:
+      # Handle both old hash style and new kwargs style for backward compatibility
+      if options.is_a?(Hash)
+        # Old style: initialize(machine, name, {human_name: 'Custom Name'})
+        StateMachines::OptionsValidator.assert_valid_keys!(options, :human_name)
+        human_name = options[:human_name]
+      else
+        # New style: initialize(machine, name, human_name: 'Custom Name')
+        raise ArgumentError, "Unexpected positional argument: #{options.inspect}" unless options.nil?
+        StateMachines::OptionsValidator.assert_valid_keys!(extra_options, :human_name) unless extra_options.empty?
+      end
 
       @machine = machine
       @name = name
       @qualified_name = machine.namespace ? :"#{name}_#{machine.namespace}" : name
-      @human_name = options[:human_name] || @name.to_s.tr('_', ' ')
+      @human_name = human_name || @name.to_s.tr('_', ' ')
       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] }
+      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
@@ -70,18 +83,18 @@ module StateMachines
 
     # Creates a new transition that determines what to change the current state
     # to when this event fires.
-    # 
+    #
     # Since this transition is being defined within an event context, you do
     # *not* need to specify the <tt>:on</tt> option for the transition.  For
     # example:
-    # 
+    #
     #  state_machine do
     #    event :ignite do
     #      transition :parked => :idling, :idling => same, :if => :seatbelt_on? # Transitions to :idling if seatbelt is on
     #      transition all => :parked, :unless => :seatbelt_on?                  # Transitions to :parked if seatbelt is off
     #    end
     #  end
-    # 
+    #
     # See StateMachines::Machine#transition for a description of the possible
     # configurations for defining transitions.
     def transition(options)
@@ -89,18 +102,20 @@ module StateMachines
 
       # Only a certain subset of explicit options are allowed for transition
       # requirements
-      options.assert_valid_keys(:from, :to, :except_from, :except_to, :if, :unless) if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on, :if, :unless]).empty?
+      if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on, :if, :unless]).empty?
+        StateMachines::OptionsValidator.assert_valid_keys!(options, :from, :to, :except_from, :except_to, :if, :unless)
+      end
 
-      branches << branch = Branch.new(options.merge(:on => name))
+      branches << branch = Branch.new(options.merge(on: name))
       @known_states |= branch.known_states
       branch
     end
 
     # Determines whether any transitions can be performed for this event based
     # on the current state of the given object.
-    # 
+    #
     # If the event can't be fired, then this will return false, otherwise true.
-    # 
+    #
     # *Note* that this will not take the object context into account.  Although
     # a transition may be possible based on the state machine definition,
     # object-specific behaviors (like validations) may prevent it from firing.
@@ -110,7 +125,7 @@ module StateMachines
 
     # Finds and builds the next transition that can be performed on the given
     # object.  If no transitions can be made, then this will return nil.
-    # 
+    #
     # Valid requirement options:
     # * <tt>:from</tt> - One or more states being transitioned from.  If none
     #   are specified, then this will be the object's current state.
@@ -119,11 +134,11 @@ module StateMachines
     # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
     #   conditionals defined for each one.  Default is true.
     def transition_for(object, requirements = {})
-      requirements.assert_valid_keys(:from, :to, :guard)
-      requirements[:from] = machine.states.match!(object).name unless custom_from_state = requirements.include?(:from)
+      StateMachines::OptionsValidator.assert_valid_keys!(requirements, :from, :to, :guard)
+      requirements[:from] = machine.states.match!(object).name unless (custom_from_state = requirements.include?(:from))
 
       branches.each do |branch|
-        if match = branch.match(object, requirements)
+        if (match = branch.match(object, requirements))
           # Branch allows for the transition to occur
           from = requirements[:from]
           to = if match[:to].is_a?(LoopbackMatcher)
@@ -145,27 +160,29 @@ module StateMachines
     # Attempts to perform the next available transition on the given object.
     # If no transitions can be made, then this will return false, otherwise
     # true.
-    # 
+    #
     # Any additional arguments are passed to the StateMachines::Transition#perform
     # instance method.
     def fire(object, *args)
       machine.reset(object)
 
-      if transition = transition_for(object)
+      if (transition = transition_for(object))
         transition.perform(*args)
       else
-        on_failure(object)
+        on_failure(object, *args)
         false
       end
     end
 
     # Marks the object as invalid and runs any failure callbacks associated with
     # this event.  This should get called anytime this event fails to transition.
-    def on_failure(object)
+    def on_failure(object, *args)
       state = machine.states.match!(object)
       machine.invalidate(object, :state, :invalid_transition, [[:event, human_name(object.class)], [:state, state.human_name(object.class)]])
 
-      Transition.new(object, machine, name, state.name, state.name).run_callbacks(:before => false)
+      transition = Transition.new(object, machine, name, state.name, state.name)
+      transition.args = args if args.any?
+      transition.run_callbacks(before: false)
     end
 
     # Resets back to the initial state of the event, with no branches / known
@@ -178,14 +195,14 @@ module StateMachines
     end
 
 
-    def draw(graph, options = {})
-      fail NotImplementedError
+    def draw(graph, options = {}, io = $stdout)
+      machine.renderer.draw_event(self, graph, options, io)
     end
 
     # Generates a nicely formatted description of this event's contents.
-    # 
+    #
     # For example,
-    # 
+    #
     #   event = StateMachines::Event.new(machine, :park)
     #   event.transition all - :idling => :parked, :idling => same
     #   event   # => #<StateMachines::Event name=:park transitions=[all - :idling => :parked, :idling => same]>
@@ -199,29 +216,30 @@ module StateMachines
       "#<#{self.class} name=#{name.inspect} transitions=[#{transitions * ', '}]>"
     end
 
-    protected
+  protected
+
     # Add the various instance methods that can transition the object using
     # the current event
     def add_actions
       # Checks whether the event can be fired on the current object
-      machine.define_helper(:instance, "can_#{qualified_name}?") do |machine, object, *args|
-        machine.event(name).can_fire?(object, *args)
+      machine.define_helper(:instance, "can_#{qualified_name}?") do |machine, object, *args, **kwargs|
+        machine.event(name).can_fire?(object, *args, **kwargs)
       end
 
       # Gets the next transition that would be performed if the event were
       # fired now
-      machine.define_helper(:instance, "#{qualified_name}_transition") do |machine, object, *args|
-        machine.event(name).transition_for(object, *args)
+      machine.define_helper(:instance, "#{qualified_name}_transition") do |machine, object, *args, **kwargs|
+        machine.event(name).transition_for(object, *args, **kwargs)
       end
 
       # Fires the event
-      machine.define_helper(:instance, qualified_name) do |machine, object, *args|
-        machine.event(name).fire(object, *args)
+      machine.define_helper(:instance, qualified_name) do |machine, object, *args, **kwargs|
+        machine.event(name).fire(object, *args, **kwargs)
       end
 
       # Fires the event, raising an exception if it fails
-      machine.define_helper(:instance, "#{qualified_name}!") do |machine, object, *args|
-        object.send(qualified_name, *args) || raise(StateMachines::InvalidTransition.new(object, machine, name))
+      machine.define_helper(:instance, "#{qualified_name}!") do |machine, object, *args, **kwargs|
+        object.send(qualified_name, *args, **kwargs) || raise(StateMachines::InvalidTransition.new(object, machine, name))
       end
     end
   end

data/lib/state_machines/event_collection.rb

@@ -1,12 +1,14 @@
+# frozen_string_literal: true
+
 module StateMachines
   # Represents a collection of events in a state machine
   class EventCollection < NodeCollection
     def initialize(machine) #:nodoc:
-      super(machine, :index => [:name, :qualified_name])
+      super(machine, index: [:name, :qualified_name])
     end
 
     # Gets the list of events that can be fired on the given object.
-    # 
+    #
     # Valid requirement options:
     # * <tt>:from</tt> - One or more states being transitioned from.  If none
     #   are specified, then this will be the object's current state.
@@ -16,26 +18,26 @@ module StateMachines
     #   are specified, then this will match any event.
     # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
     #   conditionals defined for each one.  Default is true.
-    # 
+    #
     # == Examples
-    # 
+    #
     #   class Vehicle
     #     state_machine :initial => :parked do
     #       event :park do
     #         transition :idling => :parked
     #       end
-    #       
+    #
     #       event :ignite do
     #         transition :parked => :idling
     #       end
     #     end
     #   end
-    #   
+    #
     #   events = Vehicle.state_machine(:state).events
-    #   
+    #
     #   vehicle = Vehicle.new               # => #<Vehicle:0xb7c464b0 @state="parked">
     #   events.valid_for(vehicle)           # => [#<StateMachines::Event name=:ignite transitions=[:parked => :idling]>]
-    #   
+    #
     #   vehicle.state = 'idling'
     #   events.valid_for(vehicle)           # => [#<StateMachines::Event name=:park transitions=[:idling => :parked]>]
     def valid_for(object, requirements = {})
@@ -43,7 +45,7 @@ module StateMachines
     end
 
     # Gets the list of transitions that can be run on the given object.
-    # 
+    #
     # Valid requirement options:
     # * <tt>:from</tt> - One or more states being transitioned from.  If none
     #   are specified, then this will be the object's current state.
@@ -53,29 +55,29 @@ module StateMachines
     #   are specified, then this will match any event.
     # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
     #   conditionals defined for each one.  Default is true.
-    # 
+    #
     # == Examples
-    # 
+    #
     #   class Vehicle
     #     state_machine :initial => :parked do
     #       event :park do
     #         transition :idling => :parked
     #       end
-    #       
+    #
     #       event :ignite do
     #         transition :parked => :idling
     #       end
     #     end
     #   end
-    #   
+    #
     #   events = Vehicle.state_machine.events
-    #   
+    #
     #   vehicle = Vehicle.new                             # => #<Vehicle:0xb7c464b0 @state="parked">
     #   events.transitions_for(vehicle)                   # => [#<StateMachines::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
-    #   
+    #
     #   vehicle.state = 'idling'
     #   events.transitions_for(vehicle)                   # => [#<StateMachines::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>]
-    #   
+    #
     #   # 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 = {})
@@ -86,12 +88,12 @@ module StateMachines
     # given object's event attribute.  This also takes an additional parameter
     # for automatically invalidating the object if the event or transition are
     # invalid.  By default, this is turned off.
-    # 
+    #
     # *Note* that if a transition has already been generated for the event, then
     # that transition will be used.
-    # 
+    #
     # == Examples
-    # 
+    #
     #   class Vehicle < ActiveRecord::Base
     #     state_machine :initial => :parked do
     #       event :ignite do
@@ -99,16 +101,16 @@ module StateMachines
     #       end
     #     end
     #   end
-    #   
+    #
     #   vehicle = Vehicle.new                       # => #<Vehicle id: nil, state: "parked">
     #   events = Vehicle.state_machine.events
-    #   
+    #
     #   vehicle.state_event = nil
     #   events.attribute_transition_for(vehicle)    # => nil # Event isn't defined
-    #   
+    #
     #   vehicle.state_event = 'invalid'
     #   events.attribute_transition_for(vehicle)    # => false # Event is invalid
-    #   
+    #
     #   vehicle.state_event = 'ignite'
     #   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)
@@ -118,7 +120,7 @@ module StateMachines
       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
+                                                       # No valid transition: invalidate
                                                        machine.invalidate(object, :event, :invalid_event, [[:state, machine.states.match!(object).human_name(object.class)]]) if invalidate
                                                        false
                                                      end
@@ -131,7 +133,8 @@ module StateMachines
 
     end
 
-    private
+  private
+
     def match(requirements) #:nodoc:
       requirements && requirements[:on] ? [fetch(requirements.delete(:on))] : self
     end

data/lib/state_machines/extensions.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StateMachines
   module ClassMethods
     def self.extended(base) #:nodoc:
@@ -139,7 +141,7 @@ module StateMachines
       fire_events(*(events + [run_action])) || fail(StateMachines::InvalidParallelTransition.new(self, events))
     end
 
-    protected
+  protected
 
     def initialize_state_machines(options = {}, &block) #:nodoc:
       self.class.state_machines.initialize_states(self, options, &block)

data/lib/state_machines/helper_module.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StateMachines
   # Represents a type of module that defines instance / class methods for a
   # state machine
@@ -6,7 +8,7 @@ module StateMachines
       @machine = machine
       @kind = kind
     end
-    
+
     # Provides a human-readable description of the module
     def to_s
       owner_class = @machine.owner_class

data/lib/state_machines/integrations/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StateMachines
   module Integrations
     # Provides a set of base helpers for managing individual integrations

data/lib/state_machines/integrations.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StateMachines
   # Integrations allow state machines to take advantage of features within the
   # context of a particular library.  This is currently most useful with
@@ -9,10 +11,10 @@ module StateMachines
   # * Scopes
   # * Callbacks
   # * Validation errors
-  # 
+  #
   # This type of integration allows the user to work with state machines in a
   # fashion similar to other object models in their application.
-  # 
+  #
   # The integration interface is loosely defined by various unimplemented
   # methods in the StateMachines::Machine class.  See that class or the various
   # built-in integrations for more information about how to define additional
@@ -55,20 +57,20 @@ module StateMachines
       # Attempts to find an integration that matches the given class.  This will
       # look through all of the built-in integrations under the StateMachines::Integrations
       # namespace and find one that successfully matches the class.
-      # 
+      #
       # == Examples
-      # 
+      #
       #   class Vehicle
       #   end
-      #   
+      #
       #   class ActiveModelVehicle
       #     include ActiveModel::Observing
       #     include ActiveModel::Validations
       #   end
-      #   
+      #
       #   class ActiveRecordVehicle < ActiveRecord::Base
       #   end
-      #   
+      #
       #   StateMachines::Integrations.match(Vehicle)             # => nil
       #   StateMachines::Integrations.match(ActiveModelVehicle)  # => StateMachines::Integrations::ActiveModel
       #   StateMachines::Integrations.match(ActiveRecordVehicle) # => StateMachines::Integrations::ActiveRecord
@@ -100,7 +102,7 @@ module StateMachines
         integrations.detect { |integration| integration.integration_name == name } || raise(IntegrationNotFound.new(name))
       end
 
-      private
+    private
 
       def add(integration)
         if integration.respond_to?(:integration_name)

data/lib/state_machines/machine/class_methods.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module ClassMethods
+      # Attempts to find or create a state machine for the given class.  For
+      # example,
+      #
+      #   StateMachines::Machine.find_or_create(Vehicle)
+      #   StateMachines::Machine.find_or_create(Vehicle, :initial => :parked)
+      #   StateMachines::Machine.find_or_create(Vehicle, :status)
+      #   StateMachines::Machine.find_or_create(Vehicle, :status, :initial => :parked)
+      #
+      # If a machine of the given name already exists in one of the class's
+      # superclasses, then a copy of that machine will be created and stored
+      # in the new owner class (the original will remain unchanged).
+      def find_or_create(owner_class, *args, &block)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        name = args.first || :state
+
+        # Find an existing machine
+        machine = owner_class.respond_to?(:state_machines) &&
+                  (args.first && owner_class.state_machines[name] || !args.first &&
+                  owner_class.state_machines.values.first) || nil
+
+        if machine
+          # Only create a new copy if changes are being made to the machine in
+          # a subclass
+          if machine.owner_class != owner_class && (options.any? || block_given?)
+            machine = machine.clone
+            machine.initial_state = options[:initial] if options.include?(:initial)
+            machine.owner_class = owner_class
+          end
+
+          # Evaluate DSL
+          machine.instance_eval(&block) if block_given?
+        else
+          # No existing machine: create a new one
+          machine = new(owner_class, name, options, &block)
+        end
+
+        machine
+      end
+
+      def draw(*)
+        raise NotImplementedError
+      end
+
+      # Default messages to use for validation errors in ORM integrations
+      attr_accessor :ignore_method_conflicts
+
+      def default_messages
+        @default_messages ||= {
+          invalid: 'is invalid',
+          invalid_event: 'cannot transition when %s',
+          invalid_transition: 'cannot transition via "%1$s"'
+        }
+      end
+
+      def default_messages=(messages)
+        @default_messages = messages
+      end
+
+      def replace_messages(message_hash)
+        message_hash.each do |key, value|
+          default_messages[key] = value
+        end
+      end
+
+      attr_writer :renderer
+
+      def renderer
+        return @renderer if @renderer
+
+        STDIORenderer
+      end
+    end
+  end
+end