state_machines 0.5.0 → 0.6.0

data/lib/state_machines/machine_collection.rb

@@ -3,13 +3,13 @@ module StateMachines
   class MachineCollection < Hash
     # Initializes the state of each machine in the given object.  This can allow
     # states to be initialized in two groups: static and dynamic.  For example:
-    # 
+    #
     #   machines.initialize_states(object) do
     #     # After static state initialization, before dynamic state initialization
     #   end
-    # 
+    #
     # If no block is provided, then all states will still be initialized.
-    # 
+    #
     # Valid configuration options:
     # * <tt>:static</tt> - Whether to initialize static states. Unless set to
     #   false, the state will be initialized regardless of its current value.
@@ -21,19 +21,19 @@ module StateMachines
     #   writing to the object.  Default is to write directly to the object.
     def initialize_states(object, options = {}, attributes = {})
       options.assert_valid_keys( :static, :dynamic, :to)
-      options = {:static => true, :dynamic => true}.merge(options)
+      options = {static: true, dynamic: true}.merge(options)
 
       result = yield if block_given?
 
       each_value do |machine|
         unless machine.dynamic_initial_state?
           force = options[:static] == :force || !attributes.keys.map(&:to_sym).include?(machine.attribute)
-          machine.initialize_state(object, force: force, :to => options[:to])
+          machine.initialize_state(object, force: force, to: options[:to])
         end
       end if options[:static]
 
       each_value do |machine|
-        machine.initialize_state(object, :force => options[:dynamic] == :force, :to => options[:to]) if machine.dynamic_initial_state?
+        machine.initialize_state(object, force: options[:dynamic] == :force, to: options[:to]) if machine.dynamic_initial_state?
       end if options[:dynamic]
 
       result
@@ -48,12 +48,12 @@ module StateMachines
       transitions = events.collect do |event_name|
         # Find the actual event being run
         event = nil
-        detect {|name, machine| event = machine.events[event_name, :qualified_name]}
+        detect { |name, machine| event = machine.events[event_name, :qualified_name] }
 
         raise(InvalidEvent.new(object, event_name)) unless event
 
         # Get the transition that will be performed for the event
-        unless transition = event.transition_for(object)
+        unless (transition = event.transition_for(object))
           event.on_failure(object)
         end
         transition
@@ -71,7 +71,7 @@ module StateMachines
     # Builds the collection of transitions for all event attributes defined on
     # the given object.  This will only include events whose machine actions
     # match the one specified.
-    # 
+    #
     # These should only be fired as a result of the action being run.
     def transitions(object, action, options = {})
       transitions = map do |name, machine|
@@ -81,13 +81,14 @@ module StateMachines
       AttributeTransitionCollection.new(transitions.compact, {use_transactions: resolve_use_transactions}.merge(options))
     end
 
-    protected
+  protected
 
     def resolve_use_transactions
       use_transactions = nil
       each_value do |machine|
         # Determine use_transactions setting for this set of transitions.  If from multiple state_machines, the settings must match.
         raise 'Encountered mismatched use_transactions configurations for multiple state_machines' if !use_transactions.nil? && use_transactions != machine.use_transactions
+
         use_transactions = machine.use_transactions
       end
       use_transactions

data/lib/state_machines/macro_methods.rb

@@ -5,7 +5,7 @@ module StateMachines
   module MacroMethods
     # Creates a new state machine with the given name.  The default name, if not
     # specified, is <tt>:state</tt>.
-    # 
+    #
     # Configuration options:
     # * <tt>:attribute</tt> - The name of the attribute to store the state value
     #   in.  By default, this is the same as the name of the machine.
@@ -26,7 +26,7 @@ module StateMachines
     #   library-specific behavior to the machine.  Built-in integrations
     #   include :active_model, :active_record, :data_mapper, :mongo_mapper, and
     #   :sequel.  By default, this is determined automatically.
-    # 
+    #
     # Configuration options relevant to ORM integrations:
     # * <tt>:plural</tt> - The pluralized version of the name.  By default, this
     #   will attempt to call +pluralize+ on the name.  If this method is not
@@ -39,20 +39,20 @@ module StateMachines
     # * <tt>:use_transactions</tt> - Whether transactions should be used when
     #   firing events.  Default is true unless otherwise specified by the
     #   configured integration.
-    # 
+    #
     # This also expects a block which will be used to actually configure the
     # states, events and transitions for the state machine.  *Note* that this
     # block will be executed within the context of the state machine.  As a
     # result, you will not be able to access any class methods unless you refer
     # to them directly (i.e. specifying the class name).
-    # 
+    #
     # For examples on the types of state machine configurations and blocks, see
     # the section below.
-    # 
+    #
     # == Examples
-    # 
+    #
     # With the default name/attribute and no configuration:
-    # 
+    #
     #   class Vehicle
     #     state_machine do
     #       event :park do
@@ -60,37 +60,37 @@ module StateMachines
     #       end
     #     end
     #   end
-    # 
+    #
     # The above example will define a state machine named "state" that will
     # store the value in the +state+ attribute.  Every vehicle will start
     # without an initial state.
-    # 
+    #
     # With a custom name / attribute:
-    # 
+    #
     #   class Vehicle
     #     state_machine :status, :attribute => :status_value do
     #       ...
     #     end
     #   end
-    # 
+    #
     # With a static initial state:
-    # 
+    #
     #   class Vehicle
     #     state_machine :status, :initial => :parked do
     #       ...
     #     end
     #   end
-    # 
+    #
     # With a dynamic initial state:
-    # 
+    #
     #   class Vehicle
     #     state_machine :status, :initial => lambda {|vehicle| vehicle.speed == 0 ? :parked : :idling} do
     #       ...
     #     end
     #   end
-    # 
+    #
     # == Class Methods
-    # 
+    #
     # The following class methods will be automatically generated by the
     # state machine based on the *name* of the machine.  Any existing methods
     # will not be overwritten.
@@ -100,28 +100,28 @@ module StateMachines
     # * <tt>human_state_event_name(event)</tt> - Gets the humanized value for
     #   the given event.  This may be generated by internationalization
     #   libraries if supported by the integration.
-    # 
+    #
     # For example,
-    # 
+    #
     #   class Vehicle
     #     state_machine :state, :initial => :parked do
     #       event :ignite do
     #         transition :parked => :idling
     #       end
-    #       
+    #
     #       event :shift_up do
     #         transition :idling => :first_gear
     #       end
     #     end
     #   end
-    #   
+    #
     #   Vehicle.human_state_name(:parked)         # => "parked"
     #   Vehicle.human_state_name(:first_gear)     # => "first gear"
     #   Vehicle.human_state_event_name(:park)     # => "park"
     #   Vehicle.human_state_event_name(:shift_up) # => "shift up"
-    # 
+    #
     # == Instance Methods
-    # 
+    #
     # The following instance methods will be automatically generated by the
     # state machine based on the *name* of the machine.  Any existing methods
     # will not be overwritten.
@@ -142,7 +142,7 @@ module StateMachines
     # * <tt>fire_state_event(name, *args)</tt> - Fires an arbitrary event with
     #   the given argument list. This is essentially the same as calling the
     #   actual event method itself.
-    # 
+    #
     # The <tt>state_events</tt>, <tt>state_transitions</tt>, and <tt>state_paths</tt>
     # helpers all take an optional set of requirements for determining what's
     # available for the current object.  These requirements include:
@@ -154,146 +154,146 @@ module StateMachines
     #   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.
-    # 
+    #
     # For example,
-    # 
+    #
     #   class Vehicle
     #     state_machine :state, :initial => :parked do
     #       event :ignite do
     #         transition :parked => :idling
     #       end
-    #       
+    #
     #       event :park do
     #         transition :idling => :parked
     #       end
     #     end
     #   end
-    #   
+    #
     #   vehicle = Vehicle.new
     #   vehicle.state                             # => "parked"
     #   vehicle.state_name                        # => :parked
     #   vehicle.human_state_name                  # => "parked"
     #   vehicle.state?(:parked)                   # => true
-    #   
+    #
     #   # Changing state
     #   vehicle.state = 'idling'
     #   vehicle.state                             # => "idling"
     #   vehicle.state_name                        # => :idling
     #   vehicle.state?(:parked)                   # => false
-    #   
+    #
     #   # Getting current event / transition availability
     #   vehicle.state_events                      # => [:park]
     #   vehicle.park                              # => true
     #   vehicle.state_events                      # => [:ignite]
     #   vehicle.state_events(:from => :idling)    # => [:park]
     #   vehicle.state_events(:to => :parked)      # => []
-    #   
+    #
     #   vehicle.state_transitions                 # => [#<StateMachines::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
     #   vehicle.ignite                            # => true
     #   vehicle.state_transitions                 # => [#<StateMachines::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>]
-    #   
+    #
     #   vehicle.state_transitions(:on => :ignite) # => []
-    #   
+    #
     #   # Getting current path availability
     #   vehicle.state_paths                       # => [
     #                                             #     [#<StateMachines::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>,
     #                                             #      #<StateMachines::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
     #                                             #   ]
-    #   vehicle.state_paths(:guard => false)      # => 
+    #   vehicle.state_paths(:guard => false)      # =>
     #                                             #     [#<StateMachines::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>,
     #                                             #      #<StateMachines::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
     #                                             #   ]
-    #   
+    #
     #   # Fire arbitrary events
     #   vehicle.fire_state_event(:park)           # => true
-    # 
+    #
     # == Attribute initialization
-    # 
+    #
     # For most classes, the initial values for state machine attributes are
     # automatically assigned when a new object is created.  However, this
     # behavior will *not* work if the class defines an +initialize+ method
     # without properly calling +super+.
-    # 
+    #
     # For example,
-    # 
+    #
     #   class Vehicle
     #     state_machine :state, :initial => :parked do
     #       ...
     #     end
     #   end
-    #   
+    #
     #   vehicle = Vehicle.new   # => #<Vehicle:0xb7c8dbf8 @state="parked">
     #   vehicle.state           # => "parked"
-    # 
+    #
     # In the above example, no +initialize+ method is defined.  As a result,
     # the default behavior of initializing the state machine attributes is used.
-    # 
+    #
     # In the following example, a custom +initialize+ method is defined:
-    # 
+    #
     #   class Vehicle
     #     state_machine :state, :initial => :parked do
     #       ...
     #     end
-    #     
+    #
     #     def initialize
     #     end
     #   end
-    #   
+    #
     #   vehicle = Vehicle.new   # => #<Vehicle:0xb7c77678>
     #   vehicle.state           # => nil
-    # 
+    #
     # Since the +initialize+ method is defined, the state machine attributes
     # never get initialized.  In order to ensure that all initialization hooks
     # are called, the custom method *must* call +super+ without any arguments
     # like so:
-    # 
+    #
     #   class Vehicle
     #     state_machine :state, :initial => :parked do
     #       ...
     #     end
-    #     
+    #
     #     def initialize(attributes = {})
     #       ...
     #       super()
     #     end
     #   end
-    #   
+    #
     #   vehicle = Vehicle.new   # => #<Vehicle:0xb7c8dbf8 @state="parked">
     #   vehicle.state           # => "parked"
-    # 
+    #
     # Because of the way the inclusion of modules works in Ruby, calling
     # <tt>super()</tt> will not only call the superclass's +initialize+, but
     # also +initialize+ on all included modules.  This allows the original state
     # machine hook to get called properly.
-    # 
+    #
     # If you want to avoid calling the superclass's constructor, but still want
     # to initialize the state machine attributes:
-    # 
+    #
     #   class Vehicle
     #     state_machine :state, :initial => :parked do
     #       ...
     #     end
-    #     
+    #
     #     def initialize(attributes = {})
     #       ...
     #       initialize_state_machines
     #     end
     #   end
-    #   
+    #
     #   vehicle = Vehicle.new   # => #<Vehicle:0xb7c8dbf8 @state="parked">
     #   vehicle.state           # => "parked"
-    # 
+    #
     # You may also need to call the +initialize_state_machines+ helper manually
     # in cases where you want to change how static / dynamic initial states get
     # set.  For example, the following example forces the initialization of
     # static states regardless of their current value:
-    # 
+    #
     #   class Vehicle
     #     state_machine :state, :initial => :parked do
     #       state nil, :idling
     #       ...
     #     end
-    #     
+    #
     #     def initialize(attributes = {})
     #       @state = 'idling'
     #       initialize_state_machines(:static => :force) do
@@ -301,28 +301,28 @@ module StateMachines
     #       end
     #     end
     #   end
-    #   
+    #
     #   vehicle = Vehicle.new   # => #<Vehicle:0xb7c8dbf8 @state="parked">
     #   vehicle.state           # => "parked"
-    # 
+    #
     # The above example is also noteworthy because it demonstrates how to avoid
     # initialization issues when +nil+ is a valid state.  Without passing in
     # <tt>:static => :force</tt>, state_machine would never have initialized
     # the state because +nil+ (the default attribute value) would have been
     # interpreted as a valid current state.  As a result, state_machine would
     # have simply skipped initialization.
-    # 
+    #
     # == States
-    # 
+    #
     # All of the valid states for the machine are automatically tracked based
     # on the events, transitions, and callbacks defined for the machine.  If
     # there are additional states that are never referenced, these should be
     # explicitly added using the StateMachines::Machine#state or
     # StateMachines::Machine#other_states helpers.
-    # 
+    #
     # When a new state is defined, a predicate method for that state is
     # generated on the class.  For example,
-    # 
+    #
     #   class Vehicle
     #     state_machine :initial => :parked do
     #       event :ignite do
@@ -330,37 +330,37 @@ module StateMachines
     #       end
     #     end
     #   end
-    # 
+    #
     # ...will generate the following instance methods (assuming they're not
     # already defined in the class):
     # * <tt>parked?</tt>
     # * <tt>idling?</tt>
-    # 
+    #
     # Each predicate method will return true if it matches the object's
     # current state.  Otherwise, it will return false.
-    # 
+    #
     # == Attribute access
-    # 
+    #
     # The actual value for a state is stored in the attribute configured for the
     # state machine.  In most cases, this is the same as the name of the state
     # machine.  For example:
-    # 
+    #
     #   class Vehicle
     #     attr_accessor :state
-    #     
+    #
     #     state_machine :state, :initial => :parked do
     #       ...
     #       state :parked, :value => 0
     #       start :idling, :value => 1
     #     end
     #   end
-    #   
+    #
     #   vehicle = Vehicle.new # => #<Vehicle:0xb712da60 @state=0>
     #   vehicle.state         # => 0
     #   vehicle.parked?       # => true
     #   vehicle.state = 1
     #   vehicle.idling?       # => true
-    # 
+    #
     # The most important thing to note from the example above is what it means
     # to read from and write to the state machine's attribute.  In particular,
     # state_machine treats the attribute (+state+ in this case) like a basic
@@ -378,97 +378,97 @@ module StateMachines
     #   different ways an attribute can get written, state_machine just makes
     #   sure that the configured value for a state is always used when writing
     #   to the attribute.
-    # 
+    #
     # If you were interested in accessing the name of a state (instead of its
     # actual value through the attribute), you could do the following:
-    # 
+    #
     #   vehicle.state_name    # => :idling
-    # 
+    #
     # == Events and Transitions
-    # 
+    #
     # Events defined on the machine are the interface to transitioning states
     # for an object.  Events can be fired either directly (through the method
     # generated for the event) or indirectly (through attributes defined on
     # the machine).
-    # 
+    #
     # For example,
-    # 
+    #
     #   class Vehicle
     #     include DataMapper::Resource
     #     property :id, Serial
-    #     
+    #
     #     state_machine :initial => :parked do
     #       event :ignite do
     #         transition :parked => :idling
     #       end
     #     end
-    #     
+    #
     #     state_machine :alarm_state, :initial => :active do
     #       event :disable do
     #         transition all => :off
     #       end
     #     end
     #   end
-    #   
+    #
     #   # Fire +ignite+ event directly
     #   vehicle = Vehicle.create    # => #<Vehicle id=1 state="parked" alarm_state="active">
     #   vehicle.ignite              # => true
     #   vehicle.state               # => "idling"
     #   vehicle.alarm_state         # => "active"
-    #   
+    #
     #   # Fire +disable+ event automatically
     #   vehicle.alarm_state_event = 'disable'
     #   vehicle.save                # => true
     #   vehicle.alarm_state         # => "off"
-    # 
+    #
     # In the above example, the +state+ attribute is transitioned using the
     # +ignite+ action that's generated from the state machine.  On the other
     # hand, the +alarm_state+ attribute is transitioned using the +alarm_state_event+
     # attribute that automatically gets fired when the machine's action (+save+)
     # is invoked.
-    # 
+    #
     # For more information about how to configure an event and its associated
     # transitions, see StateMachines::Machine#event.
-    # 
+    #
     # == Defining callbacks
-    # 
+    #
     # Within the +state_machine+ block, you can also define callbacks for
     # transitions.  For more information about defining these callbacks,
     # see StateMachines::Machine#before_transition, StateMachines::Machine#after_transition,
     # and StateMachines::Machine#around_transition, and StateMachines::Machine#after_failure.
-    # 
+    #
     # == Namespaces
-    # 
+    #
     # When a namespace is configured for a state machine, the name provided
     # will be used in generating the instance methods for interacting with
     # states/events in the machine.  This is particularly useful when a class
     # has multiple state machines and it would be difficult to differentiate
     # between the various states / events.
-    # 
+    #
     # For example,
-    # 
+    #
     #   class Vehicle
     #     state_machine :heater_state, :initial => :off, :namespace => 'heater' do
     #       event :turn_on do
     #         transition all => :on
     #       end
-    #       
+    #
     #       event :turn_off do
     #         transition all => :off
     #       end
     #     end
-    #     
+    #
     #     state_machine :alarm_state, :initial => :active, :namespace => 'alarm' do
     #       event :turn_on do
     #         transition all => :active
     #       end
-    #       
+    #
     #       event :turn_off do
     #         transition all => :off
     #       end
     #     end
     #   end
-    # 
+    #
     # The above class defines two state machines: +heater_state+ and +alarm_state+.
     # For the +heater_state+ machine, the following methods are generated since
     # it's namespaced by "heater":
@@ -480,7 +480,7 @@ module StateMachines
     # * ..
     # * <tt>heater_off?</tt>
     # * <tt>heater_on?</tt>
-    # 
+    #
     # As shown, each method is unique to the state machine so that the states
     # and events don't conflict.  The same goes for the +alarm_state+ machine:
     # * <tt>can_turn_on_alarm?</tt>
@@ -491,25 +491,25 @@ module StateMachines
     # * ..
     # * <tt>alarm_active?</tt>
     # * <tt>alarm_off?</tt>
-    # 
+    #
     # == Scopes
-    # 
+    #
     # For integrations that support it, a group of default scope filters will
     # be automatically created for assisting in finding objects that have the
     # attribute set to one of a given set of states.
-    # 
+    #
     # For example,
-    # 
+    #
     #   Vehicle.with_state(:parked)               # => All vehicles where the state is parked
     #   Vehicle.with_states(:parked, :idling)     # => All vehicles where the state is either parked or idling
-    #   
+    #
     #   Vehicle.without_state(:parked)            # => All vehicles where the state is *not* parked
     #   Vehicle.without_states(:parked, :idling)  # => All vehicles where the state is *not* parked or idling
-    # 
+    #
     # *Note* that if class methods already exist with those names (i.e.
     # :with_state, :with_states, :without_state, or :without_states), then a
     # scope will not be defined for that name.
-    # 
+    #
     # See StateMachines::Machine for more information about using integrations
     # and the individual integration docs for information about the actual
     # scopes that are generated.