code_node 0.0.1 → 0.0.2

data/cog/templates/code_node/generator.rb.erb

@@ -4,5 +4,9 @@
 
 # Makes a graph of the project_source_path
 CodeNode.graph '<%= @name %>' do |g|
+
+  g.ignore /ClassMethods$/
+    
+  g.ignore &:island?
   
 end

data/cog/templates/code_node/graph.dot.erb

@@ -3,46 +3,40 @@ digraph
 graph [rankdir="LR"]
 node [style="filled"]
 
-<% @graph.nodes.each do |node| %>
-<% if node.should_render? %>
-<%= node.key %> [label="<%= node.label %>" shape="<%= node.shape %>" fillcolor="<%= node.fillcolor %>" fontcolor="<%= node.fontcolor %>"];
-<% end %>
+/* Module nodes */
+node [shape="box" fillcolor="#333333" fontcolor="#ffffff"];
+<% @graph.each_module do |node| %>
+<%= node.stamp 'code_node/node.dot' %>
 <% end %>
 
-/* Contains */
-edge [color="#e8e8e8"]
-<% @graph.nodes.each do |node| %>
-<% if node.parent && node.should_render? && node.parent.should_render? %>
-<%= node.parent.key %> -> <%= node.key %>;
-<% end %>
+/* Class nodes */
+node [shape="ellipse" fillcolor="#cccccc" fontcolor="#000000"];
+<% @graph.each_class do |node| %>
+<%= node.stamp 'code_node/node.dot' %>
 <% end %>
 
-/* Extended by */
-edge [color="#000000"]
-<% @graph.nodes.each do |node| %>
-<% node.extended_by.values.sort.each do |other| %>
-<% if node.should_render? && other.should_render? %>
-<%= node.key %> -> <%= other.key %>;
-<% end %>
-<% end %>
+/* A contains B */
+edge [color="#e8e8e8"];
+<% @graph.each_containment do |a, b| %>
+<%= a.key %> -> <%= b.key %>;
 <% end %>
 
-/* Includes */
-edge [color="#336699"]
-<% @graph.nodes.each do |node| %>
-<% node.includes.values.sort.each do |other| %>
-<% if node.should_render? && other.should_render? %>
-<%= node.key %> -> <%= other.key %>;
-<% end %>
-<% end %>
+/* A inherits from B */
+edge [color="#996633"];
+<% @graph.each_inheritance do |a, b| %>
+<%= a.key %> -> <%= b.key %>;
 <% end %>
 
-/* Inherits from */
-edge [color="#996633"]
-<% @graph.nodes.each do |node| %>
-<% if node.should_render? && node.inherits_from && node.inherits_from.should_render? %>
-<%= node.key %> -> <%= node.inherits_from.key %>;
+/* A includes B */
+edge [color="#336699"];
+<% @graph.each_inclusion do |a, b| %>
+<%= a.key %> -> <%= b.key %>;
 <% end %>
+
+/* A extends B */
+edge [color="#000000"];
+<% @graph.each_extension do |a, b| %>
+<%= a.key %> -> <%= b.key %>;
 <% end %>
 
 }

data/cog/templates/code_node/node.dot.erb

@@ -0,0 +1 @@
+<%= key %> [label="<%= label %>"];

data/lib/code_node.rb

@@ -28,8 +28,9 @@ module CodeNode
     end
 
     sexp = []
-    [:find_nodes, :find_relations].each_with_index do |purpose, pass|
-      puts "#{(pass+1).ordinalize} pass: #{purpose.to_s.gsub('_', ' ')}".color(:cyan)
+    [:find_nodes, :find_relations].each_with_index do |mode, pass|
+      puts "#{(pass+1).ordinalize} pass: #{mode.to_s.gsub('_', ' ')}".color(:cyan)
+      
       Dir.glob("#{root}/**/*.rb").each_with_index do |filename, i|
         sexp[i] ||= begin
           rp.parse(File.read filename)
@@ -38,8 +39,8 @@ module CodeNode
           nil
         end
         if sexp[i]
-          walker = SexpWalker.new @graph, sexp[i]
-          walker.walk purpose
+          walker = SexpWalker.new @graph, sexp[i], :mode => mode
+          walker.walk
         end
       end
     end

data/lib/code_node/dsl/graph_definer.rb

@@ -1,12 +1,39 @@
 module CodeNode
   module DSL
 
+    # Specify rules for generating the graph
     class GraphDefiner
 
+      # @api developer
+      # @param graph [IR::Graph] a graph for which rules can be defined
       def initialize(graph)
         @graph = graph
       end
       
+      # Speficy an ignore rule for the graph.
+      # Nodes matching the ignore rule will not be included in the graph.
+      # Ignore rules can be given in one of three ways.
+      #
+      # * +String+ provide a fully qualified path
+      # * +Regexp+ provide a pattern that will be tested against the {IR::Node#path}
+      # * +Proc+ provide a block. If the block returns +true+ the node will be ignored
+      #
+      # @param name [String, Regexp, nil] fully qualified path or regular expression which will be compared to {IR::Node#path}
+      # @yield [Node] if provided, return +true+ to ignore the node
+      # @return [nil]
+      def ignore(name=nil, &block)
+        if (name.nil? && block.nil?) || (name && block)
+          raise ArgumentError.new('Provide either a name or a block') 
+        end
+        if block
+          @graph.instance_eval {@exclude_procs << block}
+        elsif name.is_a? Regexp
+          @graph.instance_eval {@exclude_patterns << name}
+        else
+          @graph.instance_eval {@exclude_paths << name}
+        end
+        nil
+      end
     end
 
   end

data/lib/code_node/ir.rb

@@ -1,5 +1,4 @@
-require 'code_node/ir/class_node'
-require 'code_node/ir/module_node'
+require 'code_node/ir/node'
 require 'code_node/ir/graph'
 
 module CodeNode

data/lib/code_node/ir/graph.rb

@@ -1,18 +1,23 @@
-require 'code_node/ir/class_node'
-require 'code_node/ir/module_node'
+require 'code_node/ir/node'
 
 module CodeNode
   module IR
 
     class Graph
 
+      # @api developer
       attr_reader :scope
-
+      
+      # @api developer
       def initialize
+        @exclude_paths = []
+        @exclude_patterns = []
+        @exclude_procs = []
         @nodes = {}
         @scope = []
       end
 
+      # @api developer
       def node_for(node_type, s, opt={}, &block)
         name = if s.is_a? Symbol
           s
@@ -35,10 +40,10 @@ module CodeNode
           if @scope.length > 1 && @scope[-2].find(name)
             @scope[-2].find name
           else
-            (node_type == :module ? ModuleNode : ClassNode).new(name)
+            Node.new name, :node_type => node_type
           end
         else
-          (node_type == :module ? ModuleNode : ClassNode).new(name, @scope.last)
+          Node.new name, :parent => @scope.last, :node_type => node_type
         end
 
         node = self << node
@@ -51,14 +56,74 @@ module CodeNode
       end
   
       def <<(node)
-        @nodes[node.key] ||= node
-        @nodes[node.key]
+        @nodes[node.path] ||= node
+        @nodes[node.path]
+      end
+      
+      # Iterate through each {Node} with {Node#class?} in the graph
+      # @yield [Node] a class node. Does not yield ignored nodes.
+      # @return [nil]
+      def each_class(&block)
+        @nodes.values.select do |node|
+          node.class? && !should_exclude?(node)
+        end.sort.each &block
+      end
+
+      # Iterate through each {Node} with {Node#module?} in the graph
+      # @yield [Node] a module node. Does not yield ignored nodes.
+      # @return [nil]
+      def each_module(&block)
+        @nodes.values.select do |node|
+          node.module? && !should_exclude?(node)
+        end.sort.each &block
+      end
+      
+      # Iterate through each containment relation in the graph
+      def each_containment(&block)
+        @nodes.values.sort.each do |node|
+          if node.parent && !should_exclude?(node) && !should_exclude?(node.parent)
+            block.call node.parent, node
+          end
+        end
       end
-      def [](key)
-        @nodes[key]
+
+      # Iterate through each inheritance relation in the graph
+      def each_inheritance(&block)
+        @nodes.values.sort.each do |node|
+          if node.super_class_node && !should_exclude?(node) && !should_exclude?(node.super_class_node)
+            block.call node, node.super_class_node
+          end
+        end
       end
-      def nodes
-        @nodes.values.sort
+
+      # Iterate through each inclusion relation in the graph
+      def each_inclusion(&block)
+        @nodes.values.sort.each do |node|
+          node.inclusions.each do |other|
+            if !should_exclude?(node) && !should_exclude?(other)
+              block.call node, other
+            end
+          end
+        end
+      end
+
+      # Iterate through each extension relation in the graph
+      def each_extension(&block)
+        @nodes.values.sort.each do |node|
+          node.extensions.each do |other|
+            if !should_exclude?(node) && !should_exclude?(other)
+              block.call node, other
+            end
+          end
+        end
+      end
+
+      private
+      
+      def should_exclude?(node)
+        @exclude_paths.any? {|path| path == node.path} ||
+        @exclude_patterns.any? {|pattern| pattern =~ node.path} ||
+        @exclude_procs.any? {|block| block.call(node)}
       end
     end
     

data/lib/code_node/ir/node.rb

@@ -1,51 +1,162 @@
+require 'cog'
+
 module CodeNode
   module IR
     
+    # A node in the {Graph}
+    # Nodes come in two flavors: {#class?} and {#module?} nodes
     class Node
-      attr_reader :name, :parent, :children, :includes, :extended_by, :inherits_from
-      def initialize(name, parent = nil)
-        parent_path = parent ? parent.instance_eval {@path} : []
+
+      include Cog::Generator
+      
+      # @return [String] the name of the node. Not necessarilly unique.
+      # @see {#path}
+      attr_reader :name
+
+      # @return [Node] node which contains this node
+      # @example
+      #   module Foo     # Foo is the parent
+      #     module Bar   # to Bar
+      #     end
+      #   end
+      attr_reader :parent
+
+      # The child nodes of this node
+      # @return [Hash<String,Node>] a mapping from node {#path} names to nodes
+      # @example
+      #   module Foo     # Foo has children
+      #     module Bar   # Bar
+      #     end          # and
+      #     class Car    # Car
+      #     end
+      #   end
+      attr_reader :children
+
+      # @param name [String, Array]
+      # @option opt [Node] :parent (nil)
+      # @option opt [Symbol] :node_type (:module) either <tt>:module</tt> or <tt>:class</tt>
+      def initialize(name, opt={})
+        @node_type = opt[:node_type] || :module
+        @parent = opt[:parent]
+        parent_path = @parent ? @parent.instance_eval {@path} : []
         @path = if name.is_a? Array
           parent_path + name
         else
           parent_path + [name]
         end
         @name = @path.last
-        @parent = parent
-        parent.children[key] = self unless parent.nil?
+        @parent.children[path] = self unless @parent.nil?
         @children = {}
+        @inherited_by = {}
         @includes = {}
+        @included_by = {}
+        @extends = {}
         @extended_by = {}
       end
+      
       def find(name)
-        key = (@path + [name].flatten).join '_'
-        @children[key] || (orphan? ? nil : @parent.find(name))
+        path = (@path + [name].flatten).join '::'
+        @children[path] || (@parent && @parent.find(name))
       end
+
+      # @return [String] fully qualified identifier for the node in the form <tt>Foo_Bar_Car</tt>. Ideal for graphviz identifiers.
       def key
         @path.join '_'
       end
+
+      # @return [String] fully qualified name of the node in the form <tt>'Foo::Bar::Car'</tt>. Not good as a graphviz identifier because of the colon (+:+) characters. Use {#key} for graphviz identifiers instead.
       def path
         @path.join '::'
       end
+
+      # @return [String] how the node will be labelled in the graph. Nodes without parents display their full {#path}, while nodes with parents only display their {#name}.
       def label
-        orphan? ? path : name
-      end
-      def to_s
-        path
+        @parent.nil? ? path : name
       end
+
+      # @return [FixNum] order nodes by {#path}
       def <=>(other)
         path <=> other.path
       end
-      def orphan?
-        @parent.nil?
+
+      # @return [Boolean] whether or not this node represents a module
+      def module?
+        @node_type == :module
+      end
+
+      # @return [Boolean] whether or not this node represents a class
+      def class?
+        @node_type == :class
+      end
+
+      # @param other [Node]
+      def inherits_from(other)
+        this = self
+        @inherits_from = other
+        other.instance_eval {@inherited_by[this.path] = this}
+      end
+
+      # @return [Node,nil] the super class of this class. Will be +nil+ for modules.
+      def super_class_node
+        @inherits_from
+      end
+
+      # @param other [Node]
+      def includes(other)
+        this = self
+        @includes[other.path] = other
+        other.instance_eval {@included_by[this.path] = this}
+      end
+      
+      # @return [Array<Node>] module nodes for which this node has an +include+ statement
+      def inclusions
+        @includes.values.sort
+      end
+
+      # @param other [Node]
+      def extends(other)
+        this = self
+        @extends[other.path] = other
+        other.instance_eval {@extended_by[this.path] = this}
+      end
+
+      # @return [Array<Node>] module nodes for which this node has an +extend+ statement
+      def extensions
+        @extends.values.sort
+      end
+      
+      # Set the given class node as the super class of this node
+      # @param super_node [Node] a {#class?} node
+      # @return [nil]
+      def inherits_from=(super_node)
+        throw :NodeNotAClass unless class?
+        throw :SuperNodeNotAClass unless super_node.class?
+        @inherits_from = super_node
+      end
+      
+      # @return [Boolean] whether or not this node inherits from a given node. Note that a node does inherit from itself, according to this method. Recursively checks the ancestry of the node.
+      def inherits_from?(k)
+        key == k || @inherits_from && (@inherits_from.key == k || @inherits_from.inherits_from?(k))
+      end
+            
+      # Mark this module node as a singleton
+      # @return [nil]
+      def mark_as_singleton
+        throw :NodeNotAModule unless module?
+        @singleton = true
       end
-      def derives_from?(k)
-        key == k || @inherits_from && (@inherits_from.key == k || @inherits_from.derives_from?(k))
+      
+      # @return [Boolean] whether or not this node represents a singleton module
+      def singleton?
+        @singleton
       end
-      def should_render?
-        !(orphan? && @children.empty? && @inherits_from.nil? && @extended_by.empty? && @includes.empty?) && key != 'ActiveSupport_Concern' && !derives_from?('ActiveRecord_ActiveRecordError') && name != :ClassMethods
+      
+      # @return [Boolean] whether or not this node is an island. An island is a node with no connections to other nodes.
+      def island?
+        ([@parent, @inherits_from].all?(&:nil?) &&
+         [@children, @inherited_by, @extends, @includes, @extended_by, @included_by].all?(&:empty?))
       end
+
     end
-  
   end
 end

data/lib/code_node/sexp_walker.rb

@@ -1,40 +1,59 @@
 module CodeNode
   
+  # Walks a Sexp representing a ruby file looking for classes and modules.
   class SexpWalker
-    def initialize(graph, sexp)
+    
+    # Initialize a walker with a graph and sexp
+    #
+    # All files in a code base should be walked once in <tt>:find_nodes</tt> mode, and then walked again in <tt>:find_relations</tt> mode.
+    #
+    # @param graph [Graph] a graph to which nodes and relations will be added
+    # @param sexp [Sexp] the root sexp of a ruby file
+    # @option opt [Symbol] :mode (:find_nodes) one of <tt>:find_nodes</tt> or <tt>:find_relations</tt>
+    def initialize(graph, sexp, opt={})
       @graph = graph
       @root = sexp
+      @mode = opt[:mode] || :find_nodes
     end
-    def walk(purpose, s = nil)
+    
+    # Walk the tree rooted at the given sexp
+    # @param s [Sexp] if +nil+ will be the root sexp
+    # @return [nil]
+    def walk(s = nil)
       s ||= @root
       if [:module, :class].member?(s[0])
         @graph.node_for(s[0], s[1]) do |node|
-          if purpose == :find_relations && s[0] == :class && !s[2].nil?
+          if find_relations? && s[0] == :class && !s[2].nil?
             super_node = @graph.node_for :class, s[2], :not_sure_if_nested => true
-            unless super_node.nil?
-              node.inherits_from = super_node
-            end
+            node.inherits_from super_node unless super_node.nil?
           end
           rest = s[0] == :module ? s.slice(2..-1) : s.slice(3..-1)
           rest.each do |c|
-            walk(purpose, c) if c.class == Sexp
+            walk(c) if c.class == Sexp
           end
         end
-      elsif purpose == :find_relations && s[0] == :call && s.length >= 4 && [:extend, :include].member?(s[2]) && !@graph.scope.empty?
+      elsif find_relations? && s[0] == :call && s.length >= 4 && [:extend, :include].member?(s[2]) && !@graph.scope.empty?
         node = @graph.node_for :module, s[3], :not_sure_if_nested => true
         unless node.nil?
           if s[2] == :extend
-            @graph.scope.last.extended_by[node.key] = node
+            @graph.scope.last.extends node
           else
-            @graph.scope.last.includes[node.key] = node
+            @graph.scope.last.includes node
           end
         end
       else
         s.slice(1..-1).each do |c|
-          walk(purpose, c) if c.class == Sexp
+          walk(c) if c.class == Sexp
         end
       end
     end
+    
+    private
+    
+    # @return [Boolean] whether or not the walker should look for relations
+    def find_relations?
+      @mode == :find_relations
+    end
+
   end
-  
 end

data/lib/code_node/version.rb

@@ -1,5 +1,5 @@
 module Code_node 
   unless const_defined? :VERSION
-    VERSION = '0.0.1'
+    VERSION = '0.0.2'
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: code_node
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: 
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Kevin Tonon
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-11-18 00:00:00 Z
+date: 2012-11-19 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: cog
@@ -60,7 +60,7 @@ dependencies:
   type: :development
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
-  name: yard
+  name: redcarpet
   prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
@@ -73,6 +73,34 @@ dependencies:
         version: "0"
   type: :development
   version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id006
 description: 
 email: kevin@betweenconcepts.com
 executables: []
@@ -85,18 +113,17 @@ files:
 - LICENSE
 - cog/templates/code_node/generator.rb.erb
 - cog/templates/code_node/graph.dot.erb
+- cog/templates/code_node/node.dot.erb
 - lib/code_node/cog_tool.rb
 - lib/code_node/dsl/graph_definer.rb
 - lib/code_node/dsl.rb
-- lib/code_node/ir/class_node.rb
 - lib/code_node/ir/graph.rb
-- lib/code_node/ir/module_node.rb
 - lib/code_node/ir/node.rb
 - lib/code_node/ir.rb
 - lib/code_node/sexp_walker.rb
 - lib/code_node/version.rb
 - lib/code_node.rb
-homepage: http://betweenconcepts.com
+homepage: https://github.com/ktonon/code_node
 licenses: []
 
 post_install_message: 

data/lib/code_node/ir/class_node.rb

@@ -1,22 +0,0 @@
-require 'code_node/ir/node'
-
-module CodeNode
-  module IR
-    
-    class ClassNode < Node
-      def inherits_from=(super_node)
-        @inherits_from = super_node
-      end
-      def shape
-        :ellipse
-      end
-      def fillcolor
-        '#cccccc'
-      end
-      def fontcolor
-        '#000000'
-      end
-    end
-    
-  end  
-end

data/lib/code_node/ir/module_node.rb

@@ -1,26 +0,0 @@
-require 'code_node/ir/node'
-
-module CodeNode
-  module IR
-
-    class ModuleNode < Node
-      def shape
-        :box
-      end
-      def fillcolor
-        if children["#{key}_ClassMethods"] && extended_by['ActiveSupport_Concern']
-          '#000000'
-        else
-          '#666666'
-        end
-      end
-      def fontcolor
-        '#ffffff'
-      end
-      def mark_as_singleton
-        @singleton = true
-      end
-    end
-    
-  end  
-end