callgrapher 0.0.1

data/README.md

@@ -0,0 +1,41 @@
+CallGrapher
+===========
+
+Produce class dependency graphs by tracing method calls while code runs. Outputs
+a .dot file for use with [GraphViz](http://www.graphviz.org/).
+
+Requirements
+-----------
+Ruby 1.9 or later & Graphviz on your $PATH
+
+Usage
+-----
+Require 'callgrapher' and call trace_class_dependencies, passing in a block
+containing the code you want to graph. A Hash of sets will be returned, ready
+for proccesing with make_class_graph. Calling make_class_graph uses the `dot`
+command to generate a graph & save it to /tmp/graph.png.
+
+Known Limitations
+-----------------
+It ignores dependencies created by C function calls as the filename doesn't seem
+to reported correctly in these cases.
+
+It does not pick up dependencies created by calling methods defined by the
+attr_reader, attr_writer and attr_accessor methods. (see [this][bug] bug report)
+). There's probably various other meta-programming techniques that will interact
+poorly with this as well.
+
+ [bug]: http://bugs.ruby-lang.org/issues/4583
+
+License
+-------
+Copyright (c) 2010-2012 Luke Andrew
+
+All code is distributed under the terms of the [GPL version 3][gpl]. All other
+copyrightable material is distributed under the terms of the [Creative Commons
+Attribution-ShareAlike 3.0 Unported License][cc]
+
+Copies of these licenses are available in the files `LICENSE-GPLv3` and `LICENSE-CC-BY-SA`.
+
+ [gpl]: http://www.gnu.org/licenses/gpl.html
+ [cc]:  http://creativecommons.org/licenses/by-sa/3.0/

data/lib/callgrapher.rb

@@ -0,0 +1,87 @@
+#  Copyright (C) 2012 Luke Andrew
+#
+#  This program is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# This is the main executable for the whysynth-controller project. It also
+# contains most of the code that relies on external libraries. 
+
+require 'set'
+
+module CallGrapher
+
+  # @param [Array<String>] file_whitelist
+  #   Only include classes defined in these files.
+  # @param [Integer] namespace_depth 
+  #   The number of namespaces to report. For example, a class name of
+  #   Foo::Bar::Baz, when processed with namespace_depth == 1, would be reported
+  #   as just Foo.  With namespace_depth == 2, as Foo::Bar, and so on. A
+  #   namespace_depth of 0 indicates that the entire class name should be
+  #   reported.
+  def self.trace_class_dependencies(namespace_depth = 0,
+                                    file_whitelist = nil,
+                                    class_blacklist = nil)
+    callstack = []
+    classgraph = Hash.new{ |hash, key| hash[key] = Set.new }
+
+    set_trace_func proc{ |event, file, line, id, binding, klass|
+      next if file_whitelist && !file_whitelist.include?(file)
+      next if class_blacklist && class_blacklist.include?(klass.to_s)
+      case event
+        when 'call'
+          caller = callstack[-1]
+
+          klass =
+            if namespace_depth > 0
+              klass.name.split('::').first(namespace_depth).join('::')
+            else
+              klass.name
+            end
+
+          classgraph[caller].add klass if caller && caller != klass
+          callstack.push klass
+        when 'return'
+          callstack.pop
+      end
+    }
+
+    yield
+
+    set_trace_func nil
+    classgraph
+  end
+
+  # @param [Hash<Class, Set>] call_graph
+  #   the graph to transform into a Graphviz digraph
+  def self.make_graphviz_graph(call_graph)
+
+    graph = ''
+    graph << 'digraph callgraph {'
+
+    call_graph.each do |klass, dependencies|
+      graph << "\"#{klass}\" [shape=box];\n"
+      dependencies.each do |dependency|
+        graph << "\"#{dependency}\" [shape=box];\n"
+        graph << "\"#{klass}\" -> \"#{dependency}\";\n"
+      end
+    end
+
+    graph << '}'
+  end
+
+  # @param graph a string containing a dot format digraph
+  def self.make_graph(graph, path)
+    IO.popen("dot -Tpng -o#{path}", 'w') { |out| out.write graph }
+  end
+
+end

data/test/test.rb

@@ -0,0 +1,150 @@
+#  Copyright (C) 2012 Luke Andrew
+#
+#  This program is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# This is the main executable for the whysynth-controller project. It also
+# contains most of the code that relies on external libraries. 
+
+require 'callgrapher'
+require 'minitest/autorun'
+
+class Class1
+  def initialize
+  end
+  def test
+    Class2.new.test
+  end
+end
+
+class Class2
+  def test
+    M1::M2::Class3.new.test
+    Class4.new.test
+  end
+end
+
+module M1
+  module M2
+    class Class3
+      def test
+        M3::Class5.test
+      end
+    end
+  end
+end
+
+class Class4
+  def test
+    M3::Class5.test
+  end
+end
+
+module M3
+  class Class5
+
+    def self.test
+      self.self_call
+      Class1.new
+    end
+
+    def self.self_call
+    end
+
+  end
+end
+
+class Test < MiniTest::Unit::TestCase
+
+  ExpectedTestGraph =                                           {
+      'Class1'         => Set.new(['Class2'])                   ,
+      'Class2'         => Set.new(['M1::M2::Class3', 'Class4']) ,
+      'M1::M2::Class3' => Set.new(['M3::Class5'])               ,
+      'Class4'         => Set.new(['M3::Class5'])               ,
+      'M3::Class5'     => Set.new(['Class1'])                   }
+
+  ExpectedTestGraph_NamespaceDepth1 =       {
+      'Class1' => Set.new(['Class2'])       ,
+      'Class2' => Set.new(['M1', 'Class4']) ,
+      'M1'     => Set.new(['M3'])           ,
+      'Class4' => Set.new(['M3'])           ,
+      'M3'     => Set.new(['Class1'])       }
+
+  ExpectedTestGraph_NamespaceDepth2 =               {
+      'Class1'     => Set.new(['Class2'])           ,
+      'Class2'     => Set.new(['M1::M2', 'Class4']) ,
+      'M1::M2'     => Set.new(['M3::Class5'])       ,
+      'Class4'     => Set.new(['M3::Class5'])       ,
+      'M3::Class5' => Set.new(['Class1'])           }
+
+  ExpectedTestGraph_WithoutClass4 =                                 {
+      'Class1'         => Set.new(['Class2'])                       ,
+      'Class2'         => Set.new(['M1::M2::Class3', 'M3::Class5']) ,
+      'M1::M2::Class3' => Set.new(['M3::Class5'])                   ,
+      'M3::Class5'     => Set.new(['Class1'])                       }
+
+  ExpectedGraphvizGraph = 'digraph callgraph {"Class1" [shape=box];
+"Class2" [shape=box];
+"Class1" -> "Class2";
+"Class2" [shape=box];
+"M1::M2::Class3" [shape=box];
+"Class2" -> "M1::M2::Class3";
+"Class4" [shape=box];
+"Class2" -> "Class4";
+"M1::M2::Class3" [shape=box];
+"M3::Class5" [shape=box];
+"M1::M2::Class3" -> "M3::Class5";
+"Class4" [shape=box];
+"M3::Class5" [shape=box];
+"Class4" -> "M3::Class5";
+"M3::Class5" [shape=box];
+"Class1" [shape=box];
+"M3::Class5" -> "Class1";
+}'
+
+  EmptyHash = {}
+
+  def test_class_dependency_tracing
+    assert_equal ExpectedTestGraph, CallGrapher.trace_class_dependencies{ Class1.new.test }
+  end
+
+  def test_graphviz_output
+    assert_equal ExpectedGraphvizGraph, CallGrapher.make_graphviz_graph(ExpectedTestGraph)
+  end
+
+  def test_file_whitelist
+    assert_equal EmptyHash,
+                 CallGrapher.trace_class_dependencies(0, []){ Class1.new.test }
+
+    assert_equal ExpectedTestGraph,
+                 CallGrapher.trace_class_dependencies(0, [__FILE__]) { Class1.new.test}
+  end
+
+  def test_namespace_depth
+    assert_equal ExpectedTestGraph_NamespaceDepth1,
+                 CallGrapher.trace_class_dependencies(1) { Class1.new.test }
+
+    assert_equal ExpectedTestGraph_NamespaceDepth2,
+                 CallGrapher.trace_class_dependencies(2) { Class1.new.test }
+  end
+
+  def test_class_blacklist
+    assert_equal ExpectedTestGraph_WithoutClass4, CallGrapher.trace_class_dependencies(0, [__FILE__], ['Class4']) { Class1.new.test }
+  end
+
+  # This test doesn't assert anything, it's just convenient to have the tests
+  # call Graphviz for you so you can manually inspect the output.
+  def test_make_graph
+    CallGrapher.make_graph ExpectedGraphvizGraph, './graph.png'
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: callgrapher
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Luke Andrew
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-09-02 00:00:00.000000000 Z
+dependencies: []
+description: Produce a call graph graph by tracing the method calls of running code.
+  The output is a .dot file for use with GraphViz
+email:
+- luke.callgrapher@la.id.au
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/callgrapher.rb
+- test/test.rb
+- LICENSE-CC-BY-SA
+- LICENSE-GPLv3
+- README.md
+homepage: 
+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'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Produce call graphs of your Ruby code
+test_files: []
+has_rdoc: