yard-state_machine 0.0.1

data/.rvmrc

@@ -0,0 +1 @@
+rvm --create use 1.9.3@yard-state_machine

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,18 @@
+PATH
+  remote: .
+  specs:
+    yard-state_machine (0.0.1)
+      ruby-graphviz (~> 1.0.0)
+      yard (~> 0.7.3)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    ruby-graphviz (1.0.0)
+    yard (0.7.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  yard-state_machine!

data/lib/yard-state_machine.rb

@@ -0,0 +1 @@
+require 'yard-state_machine/yard/state_machine'

data/lib/yard-state_machine/yard/state_machine.rb

@@ -0,0 +1,8 @@
+module YARD
+  # A YARD plugin for automatically documenting state_machine gem managed state machines.
+  module StateMachine
+  end
+end
+
+require 'yard-state_machine/yard/state_machine/handlers'
+require 'yard-state_machine/yard/state_machine/templates'

data/lib/yard-state_machine/yard/state_machine/handlers.rb

@@ -0,0 +1,14 @@
+module YARD
+  module StateMachine
+
+    # YARD custom handlers for integrating the StateMachine DSL with the
+    # YARD documentation system
+    module Handlers
+    end
+
+  end
+end
+
+require 'yard-state_machine/yard/state_machine/handlers/state_machine_macro_handler'
+require 'yard-state_machine/yard/state_machine/handlers/state_machine_event_handler'
+require 'yard-state_machine/yard/state_machine/handlers/state_machine_transition_handler'

data/lib/yard-state_machine/yard/state_machine/handlers/state_machine_event_handler.rb

@@ -0,0 +1,56 @@
+require 'yard'
+
+module YARD
+  module StateMachine
+    module Handlers
+
+      # Handles and processes the #state_machine macro
+      class StateMachineEventHandler < ::YARD::Handlers::Ruby::Base
+
+        handles method_call(:event)
+
+        def process
+          return unless called_within_state_machine_macro?
+
+          event = extract_event_from_statement(statement)
+          decorate_event_with_description event
+
+          append_event_to_owner event
+
+        end
+
+        private
+
+        def called_within_state_machine_macro?
+          owner && owner.kind_of?(Hash) && owner.respond_to?(:[]) && owner[:type] == :state_machine_macro
+        end
+
+        def extract_event_from_statement statement
+          return {
+            :name => extract_event_name(statement.parameters),
+            :type => :state_machine_event,
+            :macro => owner,
+            :description => {
+            }
+          }
+        end
+
+        def extract_event_name from_statement
+          from_statement.jump(:ident, :tstring_content).source
+        end
+
+        def decorate_event_with_description event
+          parse_block statement.last.last, :owner => event
+        end
+
+        def append_event_to_owner event
+          owner[:description][:events] ||= Hash.new
+          owner[:description][:events][event[:name].to_sym] = event
+        end
+
+      end
+
+    end
+  end
+end
+

data/lib/yard-state_machine/yard/state_machine/handlers/state_machine_macro_handler.rb

@@ -0,0 +1,67 @@
+require 'yard'
+
+module YARD
+  module StateMachine
+    module Handlers
+
+      # Handles and processes the #state_machine macro
+      class StateMachineMacroHandler < ::YARD::Handlers::Ruby::Base
+
+        handles method_call(:state_machine)
+        namespace_only
+
+        def process
+          macro = extract_macro(statement)
+          decorate_macro_with_description macro
+          append_state_machine_to_namespace macro
+        end
+
+        private
+
+        def extract_macro from_statement
+          state_machine_name_ast, state_machine_options_ast = from_statement.parameters
+
+          return {
+            :type => :state_machine_macro,
+            :name => extract_string_or_symbol_name(state_machine_name_ast),
+            :namespace => namespace,
+            :options => extract_hash_from_ast(state_machine_options_ast),
+            :description => {
+            }
+          }
+        end
+
+        def extract_string_or_symbol_name ast
+          raise 'symbol expected (state_machine name) as first argument to state_machine' unless ast.type == :symbol_literal
+
+          # tstring_content/ident nodes in the ruby AST represent the content of strings and symbols
+          ast.jump(:tstring_content, :ident).source
+        end
+
+        def extract_hash_from_ast ast
+          return nil unless ast
+          raise 'hash expected (state_machine macro options) as second argument to state_machine' unless ast.children.all?{|node| node.type == :assoc}
+
+          options_hash = Hash.new
+          ast.children.each do |assoc|
+            key = assoc[0].jump(:ident).source.to_sym
+            value = assoc[1].source
+            options_hash[key] = value
+          end
+          return options_hash
+        end
+
+        def decorate_macro_with_description for_macro
+          parse_block statement.last.last, :owner => for_macro
+        end
+
+        def append_state_machine_to_namespace macro
+          namespace['state_machine_state_machines'] ||= Hash.new
+          namespace['state_machine_state_machines'][macro[:name]] = macro
+        end
+
+      end
+
+    end
+  end
+end

data/lib/yard-state_machine/yard/state_machine/handlers/state_machine_transition_handler.rb

@@ -0,0 +1,72 @@
+require 'yard'
+
+module YARD
+  module StateMachine
+    module Handlers
+
+      # Handles and processes the #state_machine macro
+      class StateMachineTransitionHandler < ::YARD::Handlers::Ruby::Base
+
+        handles method_call(:transition)
+
+        def process
+          return unless called_within_state_machine_event?
+
+          transition = extract_transition_from_statement(statement)
+
+          append_transition_to_owner transition
+        end
+
+        private
+
+        def called_within_state_machine_event?
+          owner && owner.kind_of?(Hash) && owner.respond_to?(:[]) && owner[:type] == :state_machine_event
+        end
+
+        def extract_transition_from_statement statement
+          transition_specifier = statement.parameters.first.jump(:assoc)
+
+          raise 'expected first argument (transitions hash) to be a hash' unless transition_specifier.type == :assoc
+
+          return {
+            :type => :state_machine_transition,
+            :event => owner,
+            :from_states => extract_origin_states_from_parameters(transition_specifier),
+            :to_state => extract_destination_states_from_parameters(transition_specifier)
+          }
+        end
+
+        def extract_origin_states_from_parameters parameters
+          keys = parameters[0]
+          origin_states = case keys.type
+            when :symbol_literal
+              [ keys.jump(:ident).source.to_sym ]
+            when :array
+              keys.first.children.map do |obj| 
+                raise "expected array hash key to contain only symbols (type encountered was '#{obj.type}')" unless obj.type == :symbol_literal
+                obj.jump(:ident).source.to_sym
+              end
+            when :vcall
+              keys.jump(:ident).source.to_sym
+            else
+              raise "unrecognized parameter type for transition hash key (type was '#{keys.type}')"
+          end
+        end
+
+        def extract_destination_states_from_parameters parameters
+          values = parameters[1]
+          raise "unrecognized parameter type for transition hash value (type was '#{values.type}')" unless values.type == :symbol_literal
+          values.jump(:ident).source.to_sym
+        end
+
+        def append_transition_to_owner transition
+          owner[:description][:transitions] ||= Array.new
+          owner[:description][:transitions] << transition
+        end
+
+      end
+
+    end
+  end
+end
+

data/lib/yard-state_machine/yard/state_machine/templates.rb

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

data/lib/yard-state_machine/yard/state_machine/templates/default/class/html/setup.rb

@@ -0,0 +1,58 @@
+require 'graphviz'
+
+def init
+  super
+  sections.place(:state_machine_details).before(:children)
+end
+
+def state_machine_details
+  @state_machines = object['state_machine_state_machines']
+
+  return unless @state_machines
+
+  @state_machine_image_objects = render_state_machine_data(@state_machines)
+
+  erb(:state_machine_details)
+end
+
+
+def render_state_machine_data state_machines
+
+  state_machine_image_paths = Hash.new
+
+  images_base_path = File.dirname(serializer.serialized_path(object))
+
+  state_machines.each do |state_machine_name, state_machine|
+
+    image_file_name = object.name.to_s + '_' + state_machine_name + '.png'
+
+    image_path = File.join(images_base_path, image_file_name)
+
+    content = GraphViz.new(:G, :type => :digraph) do |graph|
+
+      state_machine[:description][:events].each do |event_name, event|
+
+        event[:description][:transitions].each do |transition|
+
+          to_state = graph.add_node(transition[:to_state].to_s)
+
+          transition[:from_states].each do |state|
+            from_state = graph.add_node(state.to_s)
+            link = graph.add_edge(from_state, to_state)
+            link.label = event[:name].to_s
+          end
+
+        end
+
+      end
+
+    end.output(:png => String)
+
+    serializer.serialize(image_path, content)
+
+    state_machine_image_paths[state_machine_name] = image_path
+  end
+
+  return state_machine_image_paths
+
+end

data/lib/yard-state_machine/yard/state_machine/templates/default/class/html/state_machine_details.erb

@@ -0,0 +1,15 @@
+<h2>State Machines</h2>
+
+This class contains <%= @state_machines.count %> state machine<%= 's' if @state_machines.count > 1 %> managed by the state_machine gem.
+
+<% @state_machines.each do |state_machine_name, state_machine| %>
+  <h3><%= h state_machine_name %></h3>
+    <% if state_machine[:docstring] %>
+      <p><%= h state_machine[:docstring] %></p>
+    <% end %>
+    <% if @state_machine_image_objects[state_machine_name] %>
+
+      <img alt="state machine diagram for state machine <%= h state_machine_name %>" src="<%= url_for(@state_machine_image_objects[state_machine_name]) %>" />
+
+    <% end %>
+<% end %>

data/lib/yard-state_machine/yard/state_machine/version.rb

@@ -0,0 +1,15 @@
+module YARD
+  module StateMachine
+
+    module Version
+      MAJOR = '0'
+      MINOR = '0'
+      PATCH = '1'
+
+      def self.to_standard_version_s
+        return [MAJOR, MINOR, PATCH].join('.')
+      end
+    end
+
+  end
+end

data/yard-state_machine.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('./lib/yard-state_machine/yard/state_machine/version')
+
+Gem::Specification.new do |gem|
+
+  gem.name = 'yard-state_machine'
+  gem.version = YARD::StateMachine::Version.to_standard_version_s
+
+  gem.authors = ["Justin Lynn"]
+  gem.email = ["justinlynn@gmail.com"]
+
+  gem.summary = %q{A YARD Plugin for state_machine integration.}
+  gem.description = %q{A YARD Plugin for state_machine integration. Automatically documents state_machine DSL defined state machines.}
+
+  gem.homepage = 'https://github.com/justinlynn/yard-state_machine'
+
+  gem.executables = `git ls-files -- bin/*`.split("\n").map{|f| File.basename f }
+  gem.test_files = `git ls-files -- {test,spec,features}/*`.split "\n"
+  gem.files = `git ls-files`.split "\n"
+
+  gem.require_paths = ['lib']
+
+  gem.required_ruby_version = '>= 1.9.3'
+  gem.required_rubygems_version = Gem::Requirement.new '>= 1.8'
+
+  gem.add_dependency 'yard', '~> 0.7.3'
+  gem.add_dependency 'ruby-graphviz', '~> 1.0.0'
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: yard-state_machine
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Justin Lynn
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-12-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &16090340 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.7.3
+  type: :runtime
+  prerelease: false
+  version_requirements: *16090340
+- !ruby/object:Gem::Dependency
+  name: ruby-graphviz
+  requirement: &16089620 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *16089620
+description: A YARD Plugin for state_machine integration. Automatically documents
+  state_machine DSL defined state machines.
+email:
+- justinlynn@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .rvmrc
+- Gemfile
+- Gemfile.lock
+- lib/yard-state_machine.rb
+- lib/yard-state_machine/yard/state_machine.rb
+- lib/yard-state_machine/yard/state_machine/handlers.rb
+- lib/yard-state_machine/yard/state_machine/handlers/state_machine_event_handler.rb
+- lib/yard-state_machine/yard/state_machine/handlers/state_machine_macro_handler.rb
+- lib/yard-state_machine/yard/state_machine/handlers/state_machine_transition_handler.rb
+- lib/yard-state_machine/yard/state_machine/templates.rb
+- lib/yard-state_machine/yard/state_machine/templates/default/class/html/setup.rb
+- lib/yard-state_machine/yard/state_machine/templates/default/class/html/state_machine_details.erb
+- lib/yard-state_machine/yard/state_machine/version.rb
+- yard-state_machine.gemspec
+homepage: https://github.com/justinlynn/yard-state_machine
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '1.8'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: A YARD Plugin for state_machine integration.
+test_files: []
+has_rdoc: