enum_state_machine 0.0.2 → 0.1.0

data/lib/enum_state_machine/version.rb

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

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

@@ -0,0 +1,32 @@
+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

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,344 @@
+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

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

@@ -0,0 +1,25 @@
+module EnumStateMachine
+  module YARD
+    module Handlers
+      # Handles and processes #state
+      class State < Base
+        handles method_call(:state)
+        
+        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.state(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/transition.rb

@@ -0,0 +1,47 @@
+module EnumStateMachine
+  module YARD
+    module Handlers
+      # Handles and processes #transition
+      class Transition < Base
+        handles method_call(:transition)
+        
+        def process
+          if [EnumStateMachine::Machine, EnumStateMachine::Event, EnumStateMachine::State].include?(owner.class)
+            options = {}
+            
+            # Extract requirements
+            ast = statement.parameters.first
+            ast.children.each do |assoc|
+              # Skip conditionals
+              next if %w(if unless).include?(assoc[0].jump(:ident).source)
+              
+              options[extract_requirement(assoc[0])] = extract_requirement(assoc[1])
+            end
+            
+            owner.transition(options)
+          end
+        end
+
+        private
+          # Extracts the statement requirement from the given node
+          def extract_requirement(ast)
+            case ast.type
+            when :symbol_literal, :string_literal, :array
+              extract_node_names(ast, false)
+            when :binary
+              AllMatcher.instance - extract_node_names(ast.children.last)
+            when :var_ref, :vcall
+              case ast.source
+              when 'nil'
+                nil
+              when 'same'
+                LoopbackMatcher.instance
+              else
+                AllMatcher.instance
+              end
+            end
+          end
+      end
+    end
+  end
+end

data/lib/enum_state_machine/yard/handlers.rb

@@ -0,0 +1,12 @@
+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/templates/default/class/html/setup.rb

@@ -0,0 +1,30 @@
+require 'tempfile'
+
+# Define where state machine descriptions will be rendered
+def init
+  super
+  sections.place(:state_machine_details).before(:children)
+end
+
+# Renders state machine details in the main content of the class's documentation
+def state_machine_details
+  erb(:state_machines) if state_machines
+end
+
+# Gets a list of state machines prased for this class
+def state_machines
+  @state_machines ||= begin
+    if state_machines = object['state_machines']
+      state_machines.each do |name, machine|
+        serializer.serialize(state_machine_image_path(machine), machine[:image]) if machine[:image]
+      end
+    end
+  end
+end
+
+# Generates the image path for the given machine's visualization
+def state_machine_image_path(machine)
+  base_path = File.dirname(serializer.serialized_path(object))
+  image_name = "#{object.name}_#{machine[:name]}"
+  "#{File.join(base_path, image_name)}.png"
+end

data/lib/enum_state_machine/yard/templates/default/class/html/state_machines.erb

@@ -0,0 +1,12 @@
+<h2>State Machines</h2>
+
+This class contains <%= state_machines.count %> state machine(s).
+
+<% state_machines.each do |name, machine| %>
+  <h3><%= h(machine[:name]) %></h3>
+  <p><%= h(machine[:description]) %></p>
+  
+  <% if machine[:image] %>
+  <img alt="State machine diagram for <%= h(machine[:name]) %>" src="<%= url_for(state_machine_image_path(machine)) %>" />
+  <% end %>
+<% end %>

data/lib/enum_state_machine/yard/templates.rb

@@ -0,0 +1,3 @@
+require 'yard'
+
+YARD::Templates::Engine.register_template_path File.expand_path(File.join(File.dirname(__FILE__), 'templates'))

data/lib/enum_state_machine/yard.rb

@@ -0,0 +1,8 @@
+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.rb

@@ -0,0 +1,9 @@
+# By default, requiring "enum_state_machine" means that both the core implementation
+# *and* extensions to the Ruby core (Class in particular) will be pulled in.
+# 
+# If you want to skip the Ruby core extensions, simply require "enum_state_machine/core"
+# and extend EnumStateMachine::MacroMethods in your class.  See the README for more
+# information.
+require 'enum_state_machine/core'
+require 'enum_state_machine/core_ext'
+require 'enum_state_machine/state_enum'

data/lib/tasks/enum_state_machine.rake

@@ -0,0 +1 @@
+require File.join("#{File.dirname(__FILE__)}/enum_state_machine")

data/lib/tasks/enum_state_machine.rb

@@ -0,0 +1,24 @@
+namespace :enum_state_machine do
+  desc 'Draws state machines using GraphViz (options: CLASS=User,Vehicle; FILE=user.rb,vehicle.rb [not required in Rails]; FONT=Arial; FORMAT=png; ORIENTATION=portrait; HUMAN_NAMES=true'
+  task :draw do
+    # Build drawing options
+    options = {}
+    options[:file] = ENV['FILE'] if ENV['FILE']
+    options[:path] = ENV['TARGET'] if ENV['TARGET']
+    options[:format] = ENV['FORMAT'] if ENV['FORMAT']
+    options[:font] = ENV['FONT'] if ENV['FONT']
+    options[:orientation] = ENV['ORIENTATION'] if ENV['ORIENTATION']
+    options[:human_names] = ENV['HUMAN_NAMES'] == 'true' if ENV['HUMAN_NAMES']
+    
+    if defined?(Rails)
+      puts "Files are automatically loaded in Rails; ignoring FILE option" if options.delete(:file)
+      Rake::Task['environment'].invoke
+    else
+      # Load the library
+      $:.unshift(File.dirname(__FILE__) + '/..')
+      require 'enum_state_machine'
+    end
+    
+    EnumStateMachine::Machine.draw(ENV['CLASS'], options)
+  end
+end

data/lib/yard-enum_state_machine.rb

@@ -0,0 +1,2 @@
+require 'enum_state_machine/core'
+require 'enum_state_machine/yard'