state_machine 1.1.2 → 1.2.0

data/lib/state_machine/machine.rb

@@ -489,7 +489,7 @@ module StateMachine
     @default_messages = {
       :invalid => 'is invalid',
       :invalid_event => 'cannot transition when %s',
-      :invalid_transition => 'cannot transition via "%s"'
+      :invalid_transition => 'cannot transition via "%1$s"'
     }
     
     # Whether to ignore any conflicts that are detected for helper methods that
@@ -498,7 +498,7 @@ module StateMachine
     @ignore_method_conflicts = false
     
     # The class that the machine is defined in
-    attr_accessor :owner_class
+    attr_reader :owner_class
     
     # The name of the machine, used for scoping methods generated for the
     # machine as a whole (not states or events)
@@ -542,7 +542,7 @@ module StateMachine
       
       # Find an integration that matches this machine's owner class
       if options.include?(:integration)
-        @integration = StateMachine::Integrations.find_by_name(options[:integration]) if options[:integration]
+        @integration = options[:integration] && StateMachine::Integrations.find_by_name(options[:integration])
       else
         @integration = StateMachine::Integrations.match(owner_class)
       end
@@ -566,6 +566,7 @@ module StateMachine
       @action = options[:action]
       @use_transactions = options[:use_transactions]
       @initialize_state = options[:initialize]
+      @action_hook_defined = false
       self.owner_class = owner_class
       self.initial_state = options[:initial] unless sibling_machines.any?
       
@@ -631,8 +632,19 @@ module StateMachine
       
       # Update all states to reflect the new initial state
       states.each {|state| state.initial = (state.name == @initial_state)}
+      
+      # Output a warning if there are conflicting initial states for the machine's
+      # attribute
+      initial_state = states.detect {|state| state.initial}
+      if !owner_class_attribute_default.nil? && (dynamic_initial_state? || !owner_class_attribute_default_matches?(initial_state))
+        warn(
+          "Both #{owner_class.name} and its #{name.inspect} machine have defined "\
+          "a different default for \"#{attribute}\". Use only one or the other for "\
+          "defining defaults to avoid unexpected behaviors."
+        )
+      end
     end
-    
+      
     # Gets the initial state of the machine for the given object. If a dynamic
     # initial state was configured for this machine, then the object will be
     # passed into the lambda block to help determine the actual state.
@@ -673,7 +685,7 @@ module StateMachine
     
     # Whether a dynamic initial state is being used in the machine
     def dynamic_initial_state?
-      @initial_state.is_a?(Proc)
+      instance_variable_defined?('@initial_state') && @initial_state.is_a?(Proc)
     end
     
     # Initializes the state on the given object.  Initial values are only set if
@@ -749,8 +761,8 @@ module StateMachine
         else
           name = self.name
           helper_module.class_eval do
-            define_method(method) do |*args|
-              block.call((scope == :instance ? self.class : self).state_machine(name), self, *args)
+            define_method(method) do |*block_args|
+              block.call((scope == :instance ? self.class : self).state_machine(name), self, *block_args)
             end
           end
         end
@@ -1074,7 +1086,11 @@ module StateMachine
     #   Vehicle.state_machine.read(vehicle, :event)     # => nil      # Equivalent to vehicle.state_event
     def read(object, attribute, ivar = false)
       attribute = self.attribute(attribute)
-      ivar ? object.instance_variable_get("@#{attribute}") : object.send(attribute)
+      if ivar
+        object.instance_variable_defined?("@#{attribute}") ? object.instance_variable_get("@#{attribute}") : nil
+      else
+        object.send(attribute)
+      end
     end
     
     # Sets a new value in the given object's attribute.
@@ -1445,6 +1461,7 @@ module StateMachine
       raise ArgumentError, 'Must specify :on event' unless options[:on]
       
       branches = []
+      options = options.dup
       event(*Array(options.delete(:on))) { branches << transition(options) }
       
       branches.length == 1 ? branches.first : branches
@@ -1569,7 +1586,7 @@ module StateMachine
     #   before_transition :parked => :idling, :if => :moving?, :do => ...
     #   before_transition :on => :ignite, :unless => :seatbelt_on?, :do => ...
     # 
-    # === Accessing the transition
+    # == Accessing the transition
     # 
     # In addition to passing the object being transitioned, the actual
     # transition describing the context (e.g. event, from, to) can be accessed
@@ -1597,6 +1614,40 @@ module StateMachine
     # See StateMachine::Transition for more information about the
     # attributes available on the transition.
     # 
+    # == Usage with delegates
+    # 
+    # As noted above, state_machine uses the callback method's argument list
+    # arity to determine whether to include the transition in the method call.
+    # If you're using delegates, such as those defined in ActiveSupport or
+    # Forwardable, the actual arity of the delegated method gets masked.  This
+    # means that callbacks which reference delegates will always get passed the
+    # transition as an argument.  For example:
+    # 
+    #   class Vehicle
+    #     extend Forwardable
+    #     delegate :refresh => :dashboard
+    #     
+    #     state_machine do
+    #       before_transition :refresh
+    #       ...
+    #     end
+    #     
+    #     def dashboard
+    #       @dashboard ||= Dashboard.new
+    #     end
+    #   end
+    #   
+    #   class Dashboard
+    #     def refresh(transition)
+    #       # ...
+    #     end
+    #   end
+    # 
+    # In the above example, <tt>Dashboard#refresh</tt> *must* defined a
+    # +transition+ argument.  Otherwise, an +ArgumentError+ exception will get
+    # raised.  The only way around this is to avoid the use of delegates and
+    # manually define the delegate method so that the correct arity is used.
+    # 
     # == Examples
     # 
     # Below is an example of a class with one state machine and various types
@@ -1830,7 +1881,15 @@ module StateMachine
     # Generates the message to use when invalidating the given object after
     # failing to transition on a specific event
     def generate_message(name, values = [])
-      (@messages[name] || self.class.default_messages[name]) % values.map {|value| value.last}
+      message = (@messages[name] || self.class.default_messages[name])
+      
+      # Check whether there are actually any values to interpolate to avoid
+      # any warnings
+      if message.scan(/%./).any? {|match| match != '%%'}
+        message % values.map {|value| value.last}
+      else
+        message
+      end
     end
     
     # Runs a transaction, rolling back any changes if the yielded block fails.
@@ -1863,53 +1922,22 @@ module StateMachine
     #   Default is "Arial".
     # * <tt>:orientation</tt> - The direction of the graph ("portrait" or
     #   "landscape").  Default is "portrait".
-    # * <tt>:output</tt> - Whether to generate the output of the graph
-    def draw(options = {})
-      options = {
-        :name => "#{owner_class.name}_#{name}",
-        :path => '.',
-        :format => 'png',
-        :font => 'Arial',
-        :orientation => 'portrait'
-      }.merge(options)
-      assert_valid_keys(options, :name, :path, :format, :font, :orientation)
+    # * <tt>:human_names</tt> - Whether to use human state / event names for
+    #   node labels on the graph instead of the internal name.  Default is false.
+    def draw(graph_options = {})
+      name = graph_options.delete(:name) || "#{owner_class.name}_#{self.name}"
+      draw_options = {:human_name => false}
+      draw_options[:human_name] = graph_options.delete(:human_names) if graph_options.include?(:human_names)
       
-      begin
-        # Load the graphviz library
-        require 'rubygems'
-        gem 'ruby-graphviz', '>=0.9.0'
-        require 'graphviz'
-        
-        graph = GraphViz.new('G', :rankdir => options[:orientation] == 'landscape' ? 'LR' : 'TB')
-        
-        # Add nodes
-        states.by_priority.each do |state|
-          node = state.draw(graph)
-          node.fontname = options[:font]
-        end
-        
-        # Add edges
-        events.each do |event|
-          edges = event.draw(graph)
-          edges.each {|edge| edge.fontname = options[:font]}
-        end
-        
-        # Generate the graph
-        graphvizVersion = Constants::RGV_VERSION.split('.')
-        file = File.join(options[:path], "#{options[:name]}.#{options[:format]}")
-        
-        if graphvizVersion[0] == '0' && graphvizVersion[1] == '9' && graphvizVersion[2] == '0'
-          outputOptions = {:output => options[:format], :file => file}
-        else
-          outputOptions = {options[:format] => file}
-        end
-        
-        graph.output(outputOptions)
-        graph
-      rescue LoadError => ex
-        $stderr.puts "Cannot draw the machine (#{ex.message}). `gem install ruby-graphviz` >= v0.9.0 and try again."
-        false
-      end
+      graph = Graph.new(name, graph_options)
+      
+      # Add nodes / edges
+      states.by_priority.each {|state| state.draw(graph, draw_options)}
+      events.each {|event| event.draw(graph, draw_options)}
+      
+      # Output result
+      graph.output
+      graph
     end
     
     # Determines whether an action hook was defined for firing attribute-based
@@ -2142,9 +2170,9 @@ module StateMachine
       def define_scopes(custom_plural = nil)
         plural = custom_plural || pluralize(name)
         
-        [name, plural].uniq.each do |name|
-          [:with, :without].each do |kind|
-            method = "#{kind}_#{name}"
+        [:with, :without].each do |kind|
+          [name, plural].map {|s| s.to_s}.uniq.each do |suffix|
+            method = "#{kind}_#{suffix}"
             
             if scope = send("create_#{kind}_scope", method)
               # Converts state names to their corresponding values so that they
@@ -2194,6 +2222,18 @@ module StateMachine
         yield
       end
       
+      # Gets the initial attribute value defined by the owner class (outside of
+      # the machine's definition). By default, this is always nil.
+      def owner_class_attribute_default
+        nil
+      end
+      
+      # Checks whether the given state matches the attribute default specified
+      # by the owner class
+      def owner_class_attribute_default_matches?(state)
+        state.matches?(owner_class_attribute_default)
+      end
+      
       # Updates this machine based on the configuration of other machines in the
       # owner class that share the same target attribute.
       def add_sibling_machine_configs

data/lib/state_machine/machine_collection.rb

@@ -25,7 +25,7 @@ module StateMachine
     #   writing to the object.  Default is to write directly to the object.
     def initialize_states(object, options = {})
       assert_valid_keys(options, :static, :dynamic, :to)
-      options = {:static => :force, :dynamic => true}.merge(options)
+      options = {:static => true, :dynamic => true}.merge(options)
       
       each_value do |machine| 
         machine.initialize_state(object, :force => options[:static] == :force, :to => options[:to]) unless machine.dynamic_initial_state?
@@ -55,7 +55,6 @@ module StateMachine
         
         # Get the transition that will be performed for the event
         unless transition = event.transition_for(object)
-          machine = event.machine
           event.on_failure(object)
         end
         

data/lib/state_machine/macro_methods.rb

@@ -285,6 +285,35 @@ module StateMachine
     #   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
+    #         ...
+    #       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

data/lib/state_machine/node_collection.rb

@@ -44,7 +44,7 @@ module StateMachine
       contexts = @contexts
       @nodes = []
       @contexts = []
-      @indices = @indices.inject({}) {|indices, (name, index)| indices[name] = {}; indices}
+      @indices = @indices.inject({}) {|indices, (name, *)| indices[name] = {}; indices}
       
       # Add nodes *prior* to copying over the contexts so that they don't get
       # evaluated multiple times

data/lib/state_machine/state.rb

@@ -74,11 +74,11 @@ module StateMachine
       @initial = options[:initial] == true
       
       if name
-        conflicting_machines = machine.owner_class.state_machines.select {|name, other_machine| other_machine != machine && other_machine.states[qualified_name, :qualified_name]}
+        conflicting_machines = machine.owner_class.state_machines.select {|other_name, other_machine| other_machine != machine && other_machine.states[qualified_name, :qualified_name]}
         
         # Output a warning if another machine has a conflicting qualified name
         # for a different attribute
-        if conflict = conflicting_machines.detect {|name, other_machine| other_machine.attribute != machine.attribute}
+        if conflict = conflicting_machines.detect {|other_name, other_machine| other_machine.attribute != machine.attribute}
           name, other_machine = conflict
           warn "State #{qualified_name.inspect} for #{machine.name.inspect} is already defined in #{other_machine.name.inspect}"
         elsif conflicting_machines.empty?
@@ -125,8 +125,13 @@ module StateMachine
     #   State.new(machine, :parked, :value => nil).description                # => "parked (nil)"
     #   State.new(machine, :parked, :value => 1).description                  # => "parked (1)"
     #   State.new(machine, :parked, :value => lambda {Time.now}).description  # => "parked (*)
-    def description
-      description = name ? name.to_s : name.inspect
+    # 
+    # Configuration options:
+    # * <tt>:human_name</tt> - Whether to use this state's human name in the
+    #   description or just the internal name
+    def description(options = {})
+      label = options[:human_name] ? human_name : name
+      description = label ? label.to_s : label.inspect
       description << " (#{@value.is_a?(Proc) ? '*' : @value.inspect})" unless name.to_s == @value.to_s
       description
     end
@@ -189,6 +194,7 @@ module StateMachine
         
         # Calls the method defined by the current state of the machine
         context.class_eval <<-end_eval, __FILE__, __LINE__ + 1
+          remove_method :#{method}
           def #{method}(*args, &block)
             self.class.state_machine(#{machine_name.inspect}).states.fetch(#{name.inspect}).call(self, #{method.inspect}, lambda {super(*args, &block)}, *args, &block)
           end
@@ -226,19 +232,21 @@ module StateMachine
     # * +shape+ - The actual shape of the node.  If the state is a final
     #   state, then "doublecircle", otherwise "ellipse".
     # 
-    # The actual node generated on the graph will be returned.
-    def draw(graph)
-      node = graph.add_node(name ? name.to_s : 'nil',
-        :label => description,
+    # Configuration options:
+    # * <tt>:human_name</tt> - Whether to use the state's human name for the
+    #   node's label that gets drawn on the graph
+    def draw(graph, options = {})
+      node = graph.add_nodes(name ? name.to_s : 'nil',
+        :label => description(options),
         :width => '1',
         :height => '1',
         :shape => final? ? 'doublecircle' : 'ellipse'
       )
       
       # Add open arrow for initial state
-      graph.add_edge(graph.add_node('starting_state', :shape => 'point'), node) if initial?
+      graph.add_edges(graph.add_nodes('starting_state', :shape => 'point'), node) if initial?
       
-      node
+      true
     end
     
     # Generates a nicely formatted description of this state's contents.

data/lib/state_machine/state_context.rb

@@ -116,10 +116,10 @@ module StateMachine
       
       # Replace the configuration condition with the one configured for this
       # proxy, merging together any existing conditions
-      options[:if] = lambda do |*args|
+      options[:if] = lambda do |*condition_args|
         # Block may be executed within the context of the actual object, so
         # it'll either be the first argument or the executing context
-        object = args.first || self
+        object = condition_args.first || self
         
         proxy.evaluate_method(object, proxy_condition) &&
         Array(if_condition).all? {|condition| proxy.evaluate_method(object, condition)} &&

data/lib/state_machine/transition.rb

@@ -84,12 +84,19 @@ module StateMachine
     # Whether the transition is only existing temporarily for the object
     attr_writer :transient
     
+    # Determines whether the curreny ruby implementation supports pausing and
+    # resuming transitions
+    def self.pause_supported?
+      !defined?(RUBY_ENGINE) || %w(ruby maglev).include?(RUBY_ENGINE)
+    end
+    
     # Creates a new, specific transition
     def initialize(object, machine, event, from_name, to_name, read_state = true) #:nodoc:
       @object = object
       @machine = machine
       @args = []
       @transient = false
+      @resume_block = nil
       
       @event = machine.events.fetch(event)
       @from_state = machine.states.fetch(from_name)
@@ -354,7 +361,7 @@ module StateMachine
       # around callbacks when the remainder of the callback will be executed at
       # a later point in time.
       def pause
-        raise ArgumentError, 'around_transition callbacks cannot be called in multiple execution contexts in java implementations of Ruby. Use before/after_transitions instead.' if RUBY_PLATFORM == 'java'
+        raise ArgumentError, 'around_transition callbacks cannot be called in multiple execution contexts in java implementations of Ruby. Use before/after_transitions instead.' unless self.class.pause_supported?
         
         unless @resume_block
           require 'continuation' unless defined?(callcc)

data/lib/state_machine/transition_collection.rb

@@ -73,9 +73,10 @@ module StateMachine
       end
     end
     
-    private
+    protected
       attr_reader :results #:nodoc:
       
+    private
       # Is this a valid set of transitions?  If the collection was creating with
       # any +false+ values for transitions, then the the collection will be
       # marked as invalid.

data/lib/state_machine/version.rb

@@ -1,3 +1,3 @@
 module StateMachine
-  VERSION = '1.1.2'
+  VERSION = '1.2.0'
 end

data/lib/state_machine/yard.rb

@@ -0,0 +1,8 @@
+module StateMachine
+  # YARD plugin for automated documentation
+  module YARD
+  end
+end
+
+require 'state_machine/yard/handlers'
+require 'state_machine/yard/templates'