enum_state_machine 0.0.1 → 0.0.2

data/lib/enum_state_machine/transition_collection.rb

@@ -1,245 +0,0 @@
-module EnumStateMachine
-  # Represents a collection of transitions in a state machine
-  class TransitionCollection < Array
-    include Assertions
-    
-    # Whether to skip running the action for each transition's machine
-    attr_reader :skip_actions
-    
-    # Whether to skip running the after callbacks
-    attr_reader :skip_after
-    
-    # Whether transitions should wrapped around a transaction block
-    attr_reader :use_transaction
-    
-    # Creates a new collection of transitions that can be run in parallel.  Each
-    # transition *must* be for a different attribute.
-    # 
-    # Configuration options:
-    # * <tt>:actions</tt> - Whether to run the action configured for each transition
-    # * <tt>:after</tt> - Whether to run after callbacks
-    # * <tt>:transaction</tt> - Whether to wrap transitions within a transaction
-    def initialize(transitions = [], options = {})
-      super(transitions)
-      
-      # Determine the validity of the transitions as a whole
-      @valid = all?
-      reject! {|transition| !transition}
-      
-      attributes = map {|transition| transition.attribute}.uniq
-      raise ArgumentError, 'Cannot perform multiple transitions in parallel for the same state machine attribute' if attributes.length != length
-      
-      assert_valid_keys(options, :actions, :after, :transaction)
-      options = {:actions => true, :after => true, :transaction => true}.merge(options)
-      @skip_actions = !options[:actions]
-      @skip_after = !options[:after]
-      @use_transaction = options[:transaction]
-    end
-    
-    # Runs each of the collection's transitions in parallel.
-    # 
-    # All transitions will run through the following steps:
-    # 1. Before callbacks
-    # 2. Persist state
-    # 3. Invoke action
-    # 4. After callbacks (if configured)
-    # 5. Rollback (if action is unsuccessful)
-    # 
-    # If a block is passed to this method, that block will be called instead
-    # of invoking each transition's action.
-    def perform(&block)
-      reset
-      
-      if valid?
-        if use_event_attributes? && !block_given?
-          each do |transition|
-            transition.transient = true
-            transition.machine.write(object, :event_transition, transition)
-          end
-          
-          run_actions
-        else
-          within_transaction do
-            catch(:halt) { run_callbacks(&block) }
-            rollback unless success?
-          end
-        end
-      end
-      
-      if actions.length == 1 && results.include?(actions.first)
-        results[actions.first]
-      else
-        success?
-      end
-    end
-    
-    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.
-      def valid?
-        @valid
-      end
-      
-      # Did each transition perform successfully?  This will only be true if the
-      # following requirements are met:
-      # * No +before+ callbacks halt
-      # * All actions run successfully (always true if skipping actions)
-      def success?
-        @success
-      end
-      
-      # Gets the object being transitioned
-      def object
-        first.object
-      end
-      
-      # Gets the list of actions to run.  If configured to skip actions, then
-      # this will return an empty collection.
-      def actions
-        empty? ? [nil] : map {|transition| transition.action}.uniq
-      end
-      
-      # Determines whether an event attribute be used to trigger the transitions
-      # in this collection or whether the transitions be run directly *outside*
-      # of the action.
-      def use_event_attributes?
-        !skip_actions && !skip_after && actions.all? && actions.length == 1 && first.machine.action_hook?
-      end
-      
-      # Resets any information tracked from previous attempts to perform the
-      # collection
-      def reset
-        @results = {}
-        @success = false
-      end
-      
-      # Runs each transition's callbacks recursively.  Once all before callbacks
-      # have been executed, the transitions will then be persisted and the
-      # configured actions will be run.
-      # 
-      # If any transition fails to run its callbacks, :halt will be thrown.
-      def run_callbacks(index = 0, &block)
-        if transition = self[index]
-          throw :halt unless transition.run_callbacks(:after => !skip_after) do
-            run_callbacks(index + 1, &block)
-            {:result => results[transition.action], :success => success?}
-          end
-        else
-          persist
-          run_actions(&block)
-        end
-      end
-      
-      # Transitions the current value of the object's states to those specified by
-      # each transition
-      def persist
-        each {|transition| transition.persist}
-      end
-      
-      # Runs the actions for each transition.  If a block is given method, then it
-      # will be called instead of invoking each transition's action.
-      # 
-      # The results of the actions will be used to determine #success?.
-      def run_actions
-        catch_exceptions do
-          @success = if block_given?
-            result = yield
-            actions.each {|action| results[action] = result}
-            !!result
-          else
-            actions.compact.each {|action| !skip_actions && results[action] = object.send(action)}
-            results.values.all?
-          end
-        end
-      end
-      
-      # Rolls back changes made to the object's states via each transition
-      def rollback
-        each {|transition| transition.rollback}
-      end
-      
-      # Wraps the given block with a rescue handler so that any exceptions that
-      # occur will automatically result in the transition rolling back any changes
-      # that were made to the object involved.
-      def catch_exceptions
-        begin
-          yield
-        rescue Exception
-          rollback
-          raise
-        end
-      end
-      
-      # Runs a block within a transaction for the object being transitioned.  If
-      # transactions are disabled, then this is a no-op.
-      def within_transaction
-        if use_transaction && !empty?
-          first.within_transaction do
-            yield
-            success?
-          end
-        else
-          yield
-        end
-      end
-  end
-  
-  # Represents a collection of transitions that were generated from attribute-
-  # based events
-  class AttributeTransitionCollection < TransitionCollection
-    def initialize(transitions = [], options = {}) #:nodoc:
-      super(transitions, {:transaction => false, :actions => false}.merge(options))
-    end
-    
-    private
-      # Hooks into running transition callbacks so that event / event transition
-      # attributes can be properly updated
-      def run_callbacks(index = 0)
-        if index == 0
-          # Clears any traces of the event attribute to prevent it from being
-          # evaluated multiple times if actions are nested
-          each do |transition|
-            transition.machine.write(object, :event, nil)
-            transition.machine.write(object, :event_transition, nil)
-          end
-          
-          # Rollback only if exceptions occur during before callbacks
-          begin
-            super
-          rescue Exception
-            rollback unless @before_run
-            raise
-          end
-          
-          # Persists transitions on the object if partial transition was successful.
-          # This allows us to reference them later to complete the transition with
-          # after callbacks.          
-          each {|transition| transition.machine.write(object, :event_transition, transition)} if skip_after && success?
-        else
-          super
-        end
-      end
-      
-      # Tracks that before callbacks have now completed
-      def persist
-        @before_run = true
-        super
-      end
-      
-      # Resets callback tracking
-      def reset
-        super
-        @before_run = false
-      end
-      
-      # Resets the event attribute so it can be re-evaluated if attempted again
-      def rollback
-        super
-        each {|transition| transition.machine.write(object, :event, transition.event) unless transition.transient?}
-      end
-  end
-end

data/lib/enum_state_machine/version.rb

@@ -1,3 +0,0 @@
-module EnumStateMachine
-  VERSION = '0.0.1'
-end

data/lib/enum_state_machine/yard.rb

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

data/lib/enum_state_machine/yard/handlers.rb

@@ -1,12 +0,0 @@
-module EnumStateMachine
-  module YARD
-    # YARD custom handlers for integrating the state_machine DSL with the
-    # YARD documentation system
-    module Handlers
-    end
-  end
-end
-
-Dir["#{File.dirname(__FILE__)}/handlers/*.rb"].sort.each do |path|
-  require "enum_state_machine/yard/handlers/#{File.basename(path)}"
-end

data/lib/enum_state_machine/yard/handlers/base.rb

@@ -1,32 +0,0 @@
-module EnumStateMachine
-  module YARD
-    module Handlers
-      # Handles and processes nodes
-      class Base < ::YARD::Handlers::Ruby::Base
-        private
-          # Extracts the value from the node as either a string or symbol
-          def extract_node_name(ast)
-            case ast.type
-            when :symbol_literal
-              ast.jump(:ident).source.to_sym
-            when :string_literal
-              ast.jump(:tstring_content).source
-            else
-              nil
-            end
-          end
-          
-          # Extracts the values from the node as either strings or symbols.
-          # If the node isn't an array, it'll be converted to an array.
-          def extract_node_names(ast, convert_to_array = true)
-            if [nil, :array].include?(ast.type)
-              ast.children.map {|child| extract_node_name(child)}
-            else
-              node_name = extract_node_name(ast)
-              convert_to_array ? [node_name] : node_name
-            end
-          end
-      end
-    end
-  end
-end

data/lib/enum_state_machine/yard/handlers/event.rb

@@ -1,25 +0,0 @@
-module EnumStateMachine
-  module YARD
-    module Handlers
-      # Handles and processes #event
-      class Event < Base
-        handles method_call(:event)
-        
-        def process
-          if owner.is_a?(EnumStateMachine::Machine)
-            handler = self
-            statement = self.statement
-            names = extract_node_names(statement.parameters(false))
-            
-            names.each do |name|
-              owner.event(name) do
-                # Parse the block
-                handler.parse_block(statement.last.last, :owner => self)
-              end
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/enum_state_machine/yard/handlers/machine.rb

@@ -1,344 +0,0 @@
-require 'tempfile'
-
-module EnumStateMachine
-  module YARD
-    module Handlers
-      # Handles and processes #state_machine
-      class Machine < Base
-        handles method_call(:state_machine)
-        namespace_only
-        
-        # The generated state machine
-        attr_reader :machine
-        
-        def process
-          # Cross-file storage for state machines
-          globals.state_machines ||= Hash.new {|h, k| h[k] = {}}
-          namespace['state_machines'] ||= {}
-          
-          # Create new machine
-          klass = inherited_machine ? Class.new(inherited_machine.owner_class) : Class.new { extend EnumStateMachine::MacroMethods }
-          @machine = klass.state_machine(name, options) {}
-          
-          # Track the state machine
-          globals.state_machines[namespace.name][name] = machine
-          namespace['state_machines'][name] = {:name => name, :description => statement.docstring}
-          
-          # Parse the block
-          parse_block(statement.last.last, :owner => machine)
-          
-          # Draw the machine for reference in the template
-          file = Tempfile.new(['enum_state_machine', '.png'])
-          begin
-            if machine.draw(:name => File.basename(file.path, '.png'), :path => File.dirname(file.path), :orientation => 'landscape')
-              namespace['state_machines'][name][:image] = file.read
-            end
-          ensure
-            # Clean up tempfile
-            file.close
-            file.unlink
-          end
-          
-          # Define auto-generated methods
-          define_macro_methods
-          define_state_methods
-          define_event_methods
-        end
-        
-        protected
-          # Extracts the machine name's
-          def name
-            @name ||= begin
-              ast = statement.parameters.first
-              if ast && [:symbol_literal, :string_literal].include?(ast.type)
-                extract_node_name(ast)
-              else
-                :state
-              end
-            end
-          end
-          
-          # Extracts the machine options.  Note that this will only extract a
-          # subset of the options supported.
-          def options
-            @options ||= begin
-              options = {}
-              ast = statement.parameters(false).last
-              
-              if !inherited_machine && ast && ![:symbol_literal, :string_literal].include?(ast.type)
-                ast.children.each do |assoc|
-                  # Only extract important options
-                  key = extract_node_name(assoc[0])
-                  next unless [:initial, :attribute, :namespace, :action].include?(key)
-                  
-                  value = extract_node_name(assoc[1])
-                  options[key] = value
-                end
-              end
-              
-              options
-            end
-          end
-          
-          # Gets the machine that was inherited from a superclass.  This also
-          # ensures each ancestor has been loaded prior to looking up their definitions.
-          def inherited_machine
-            @inherited_machine ||= begin
-              namespace.inheritance_tree.each do |ancestor|
-                begin
-                  ensure_loaded!(ancestor)
-                rescue ::YARD::Handlers::NamespaceMissingError
-                  # Ignore: just means that we can't access an ancestor
-                end
-              end
-              
-              # Find the first ancestor that has the machine
-              loaded_superclasses.detect do |superclass|
-                if superclass != namespace
-                  machine = globals.state_machines[superclass.name][name]
-                  break machine if machine
-                end
-              end
-            end
-          end
-          
-          # Gets members of this class's superclasses have already been loaded
-          # by YARD
-          def loaded_superclasses
-            namespace.inheritance_tree.select {|ancestor| ancestor.is_a?(::YARD::CodeObjects::ClassObject)}
-          end
-          
-          # Gets a list of all attributes for the current class, including those
-          # that are inherited
-          def instance_attributes
-            attributes = {}
-            loaded_superclasses.each {|superclass| attributes.merge!(superclass.instance_attributes)}
-            attributes
-          end
-          
-          # Gets the type of ORM integration being used based on the list of
-          # ancestors (including mixins)
-          def integration
-            @integration ||= Integrations.match_ancestors(namespace.inheritance_tree(true).map {|ancestor| ancestor.path})
-          end
-          
-          # Gets the class type being used to define states.  Default is "Symbol".
-          def state_type
-            @state_type ||= machine.states.any? ? machine.states.map {|state| state.name}.compact.first.class.to_s : 'Symbol'
-          end
-          
-          # Gets the class type being used to define events.  Default is "Symbol".
-          def event_type
-            @event_type ||= machine.events.any? ? machine.events.first.name.class.to_s : 'Symbol'
-          end
-          
-          # Defines auto-generated macro methods for the given machine
-          def define_macro_methods
-            return if inherited_machine
-            
-            # Human state name lookup
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "human_#{machine.attribute(:name)}", :class))
-            m.docstring = [
-              "Gets the humanized name for the given state.",
-              "@param [#{state_type}] state The state to look up",
-              "@return [String] The human state name"
-            ]
-            m.parameters = ["state"]
-            
-            # Human event name lookup
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "human_#{machine.attribute(:event_name)}", :class))
-            m.docstring = [
-              "Gets the humanized name for the given event.",
-              "@param [#{event_type}] event The event to look up",
-              "@return [String] The human event name"
-            ]
-            m.parameters = ["event"]
-            
-            # Only register attributes when the accessor isn't explicitly defined
-            # by the class / superclass *and* isn't defined by inference from the
-            # ORM being used
-            unless integration || instance_attributes.include?(machine.attribute.to_sym)
-              attribute = machine.attribute
-              namespace.attributes[:instance][attribute] = {}
-              
-              # Machine attribute getter
-              register(m = ::YARD::CodeObjects::MethodObject.new(namespace, attribute))
-              namespace.attributes[:instance][attribute][:read] = m
-              m.docstring = [
-                "Gets the current attribute value for the machine",
-                "@return The attribute value"
-              ]
-              
-              # Machine attribute setter
-              register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{attribute}="))
-              namespace.attributes[:instance][attribute][:write] = m
-              m.docstring = [
-                "Sets the current value for the machine",
-                "@param new_#{attribute} The new value to set"
-              ]
-              m.parameters = ["new_#{attribute}"]
-            end
-            
-            if integration && integration.defaults[:action] && !options.include?(:action) || options[:action]
-              attribute = "#{machine.name}_event"
-              namespace.attributes[:instance][attribute] = {}
-              
-              # Machine event attribute getter
-              register(m = ::YARD::CodeObjects::MethodObject.new(namespace, attribute))
-              namespace.attributes[:instance][attribute][:read] = m
-              m.docstring = [
-                "Gets the current event attribute value for the machine",
-                "@return The event attribute value"
-              ]
-              
-              # Machine event attribute setter
-              register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{attribute}="))
-              namespace.attributes[:instance][attribute][:write] = m
-              m.docstring = [
-                "Sets the current value for the machine",
-                "@param new_#{attribute} The new value to set"
-              ]
-              m.parameters = ["new_#{attribute}"]
-            end
-            
-            # Presence query
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{machine.name}?"))
-            m.docstring = [
-              "Checks the given state name against the current state.",
-              "@param [#{state_type}] state_name The name of the state to check",
-              "@return [Boolean] True if they are the same state, otherwise false",
-              "@raise [IndexError] If the state name is invalid"
-            ]
-            m.parameters = ["state_name"]
-            
-            # Internal state name
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, machine.attribute(:name)))
-            m.docstring = [
-              "Gets the internal name of the state for the current value.",
-              "@return [#{state_type}] The internal name of the state"
-            ]
-            
-            # Human state name
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "human_#{machine.attribute(:name)}"))
-            m.docstring = [
-              "Gets the human-readable name of the state for the current value.",
-              "@return [String] The human-readable state name"
-            ]
-            
-            # Available events
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, machine.attribute(:events)))
-            m.docstring = [
-              "Gets the list of events that can be fired on the current #{machine.name} (uses the *unqualified* event names)",
-              "@param [Hash] requirements The transition requirements to test against",
-              "@option requirements [#{state_type}] :from (the current state) One or more initial states",
-              "@option requirements [#{state_type}] :to One or more target states",
-              "@option requirements [#{event_type}] :on One or more events that fire the transition",
-              "@option requirements [Boolean] :guard Whether to guard transitions with conditionals",
-              "@return [Array<#{event_type}>] The list of event names"
-            ]
-            m.parameters = [["requirements", "{}"]]
-            
-            # Available transitions
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, machine.attribute(:transitions)))
-            m.docstring = [
-              "Gets the list of transitions that can be made for the current #{machine.name}",
-              "@param [Hash] requirements The transition requirements to test against",
-              "@option requirements [#{state_type}] :from (the current state) One or more initial states",
-              "@option requirements [#{state_type}] :to One or more target states",
-              "@option requirements [#{event_type}] :on One or more events that fire the transition",
-              "@option requirements [Boolean] :guard Whether to guard transitions with conditionals",
-              "@return [Array<EnumStateMachine::Transition>] The available transitions"
-            ]
-            m.parameters = [["requirements", "{}"]]
-            
-            # Available transition paths
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, machine.attribute(:paths)))
-            m.docstring = [
-              "Gets the list of sequences of transitions that can be run for the current #{machine.name}",
-              "@param [Hash] requirements The transition requirements to test against",
-              "@option requirements [#{state_type}] :from (the current state) The initial state",
-              "@option requirements [#{state_type}] :to The target state",
-              "@option requirements [Boolean] :deep Whether to enable deep searches for the target state",
-              "@option requirements [Boolean] :guard Whether to guard transitions with conditionals",
-              "@return [EnumStateMachine::PathCollection] The collection of paths"
-            ]
-            m.parameters = [["requirements", "{}"]]
-            
-            # Generic event fire
-            register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "fire_#{machine.attribute(:event)}"))
-            m.docstring = [
-              "Fires an arbitrary #{machine.name} event with the given argument list",
-              "@param [#{event_type}] event The name of the event to fire",
-              "@param args Optional arguments to include in the transition",
-              "@return [Boolean] +true+ if the event succeeds, otherwise +false+"
-            ]
-            m.parameters = ["event", "*args"]
-          end
-          
-          # Defines auto-generated event methods for the given machine
-          def define_event_methods
-            machine.events.each do |event|
-              next if inherited_machine && inherited_machine.events[event.name]
-              
-              # Event query
-              register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "can_#{event.qualified_name}?"))
-              m.docstring = [
-                "Checks whether #{event.name.inspect} can be fired.",
-                "@param [Hash] requirements The transition requirements to test against",
-                "@option requirements [#{state_type}] :from (the current state) One or more initial states",
-                "@option requirements [#{state_type}] :to One or more target states",
-                "@option requirements [Boolean] :guard Whether to guard transitions with conditionals",
-                "@return [Boolean] +true+ if #{event.name.inspect} can be fired, otherwise +false+"
-              ]
-              m.parameters = [["requirements", "{}"]]
-              
-              # Event transition
-              register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{event.qualified_name}_transition"))
-              m.docstring = [
-                "Gets the next transition that would be performed if #{event.name.inspect} were to be fired.",
-                "@param [Hash] requirements The transition requirements to test against",
-                "@option requirements [#{state_type}] :from (the current state) One or more initial states",
-                "@option requirements [#{state_type}] :to One or more target states",
-                "@option requirements [Boolean] :guard Whether to guard transitions with conditionals",
-                "@return [EnumStateMachine::Transition] The transition that would be performed or +nil+"
-              ]
-              m.parameters = [["requirements", "{}"]]
-              
-              # Fire event
-              register(m = ::YARD::CodeObjects::MethodObject.new(namespace, event.qualified_name))
-              m.docstring = [
-                "Fires the #{event.name.inspect} event.",
-                "@param [Array] args Optional arguments to include in transition callbacks",
-                "@return [Boolean] +true+ if the transition succeeds, otherwise +false+"
-              ]
-              m.parameters = ["*args"]
-              
-              # Fire event (raises exception)
-              register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{event.qualified_name}!"))
-              m.docstring = [
-                "Fires the #{event.name.inspect} event, raising an exception if it fails.",
-                "@param [Array] args Optional arguments to include in transition callbacks",
-                "@return [Boolean] +true+ if the transition succeeds",
-                "@raise [EnumStateMachine::InvalidTransition] If the transition fails"
-              ]
-              m.parameters = ["*args"]
-            end
-          end
-          
-          # Defines auto-generated state methods for the given machine
-          def define_state_methods
-            machine.states.each do |state|
-              next if inherited_machine && inherited_machine.states[state.name] || !state.name
-              
-              # State query
-              register(m = ::YARD::CodeObjects::MethodObject.new(namespace, "#{state.qualified_name}?"))
-              m.docstring = [
-                "Checks whether #{state.name.inspect} is the current state.",
-                "@return [Boolean] +true+ if this is the current state, otherwise +false+"
-              ]
-            end
-          end
-      end
-    end
-  end
-end