drx 0.0.2 → 0.3.0

data/{lib → examples}/drx_test.rb

@@ -1,5 +1,5 @@
 require 'rubygems'
-require 'drxtk'
+require 'drx'
 
 require 'date'
 
@@ -16,9 +16,8 @@ def zmn.koko
  9090
 end
 
-Drx.examine(zmn)
+Drx::ObjInfo.new(zmn).examine
 
 #############################
 
-Drx.examinetk(zmn)
-#Drx.examinetk("some_string")
+zmn.see

data/{lib → examples}/drx_test2.rb

@@ -1,25 +1,30 @@
 require 'rubygems'
 require 'dm-core'
 
+#
+# This is part of a blogging website. Users write posts. A post
+# belongs to a user.
+#
+
 class Post
   include DataMapper::Resource
- 
-  property :post_id,  Integer, :serial => true
+
+  property :post_id,  Serial
   property :title,    String
   property :body,     Text
-  
+
   belongs_to :user
 end
 
 class User
   include DataMapper::Resource
- 
-  property :user_uid,  Integer, :serial => true
+
+  property :user_uid,  Serial
   property :name,      String
   property :mail,      String
 end
 
 post = Post.new
 
-require 'drxtk'
-Drx.see(post)
+require 'drx'
+post.see

data/examples/drx_test3.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/ruby
+
+require 'rubygems'
+
+require 'drx'
+
+class Instrument
+  include Enumerable
+end
+
+class Guitar < Instrument
+  def initialize
+    @strings = 5
+#    puts class # .add_some
+  end
+
+  def self.add_some
+    @max_strings = 10
+    @@approved = 'by obama team'
+  end
+end
+
+require 'dm-core'
+class Post
+  include DataMapper::Resource
+  property :id, Serial
+end
+
+o = Guitar.new
+o = Post.new
+def o.unq
+  def g;end
+end
+
+o.see

data/ext/{drx_ext.c → drx_core.c}

@@ -30,7 +30,7 @@ static VALUE t_get_iv_tbl(VALUE self, VALUE obj)
   if (TYPE(obj) != T_OBJECT && TYPE(obj) != T_CLASS && TYPE(obj) != T_ICLASS && TYPE(obj) != T_MODULE) {
     rb_raise(rb_eTypeError, "Only T_OBJECT/T_CLASS/T_MODULE is expected as the argument (got %d)", TYPE(obj));
   }
-  
+
   if (ROBJECT(obj)->iv_tbl) {
     st_foreach(ROBJECT(obj)->iv_tbl, record_var, (st_data_t)hash);
   }
@@ -124,73 +124,94 @@ static VALUE t_get_address(VALUE self, VALUE obj)
 
 #define RSTR(s) rb_str_new2(s)
 
-static t_do_locate_method(NODE *ND_method) {
+static VALUE t_do_locate_method(NODE *ND_method) {
   NODE *ND_scope = NULL, *ND_block = NULL;
   VALUE place;
   char line_s[20];
-  
+
   //
   // The NODE_METHOD node
   //
 
   if (nd_type(ND_method) != NODE_METHOD/*0*/) {
-    return RSTR("I'm expecting a NODE_METHOD here...");
+    return RSTR("<I'm expecting a NODE_METHOD here...>");
   }
-  
+
   //
   // The NODE_SCOPE node
   //
-  
+
   ND_scope = ND_method->u2.node;
+  if (!ND_scope) {
+     // When we use undef() to undefine a method.
+     return RSTR("<undef>");
+  }
+
+  if (nd_type(ND_scope) == NODE_FBODY/*1*/) {
+    return RSTR("<alias>");
+  }
 
   if (nd_type(ND_scope) == NODE_CFUNC/*2*/) {
-    return RSTR("That's a C function");
+    return RSTR("<c>");
   }
-  
-  if (nd_type(ND_scope) == NODE_ATTRSET/*89*/) {
-    return RSTR("That's an attr setter");
+
+  if (nd_type(ND_scope) == NODE_IVAR/*50*/) {
+    return RSTR("<attr reader>");
   }
 
-  if (nd_type(ND_scope) == NODE_FBODY/*1*/) {
-    return RSTR("That's an alias");
+  if (nd_type(ND_scope) == NODE_ATTRSET/*89*/) {
+    return RSTR("<attr setter>");
   }
-  
+
   if (nd_type(ND_scope) == NODE_ZSUPER/*41*/) {
-    // @todo The DateTime clas has a lot of these.
-    return RSTR("That's a ZSUPER, whatver the heck it means!");
+    // When we change visibility (using 'private :method' or 'public :method') of
+    // a base method, this node is created.
+    return RSTR("<zsuper>");
+  }
+
+  if (nd_type(ND_scope) == NODE_BMETHOD/*99*/) {
+    // This is created by define_method().
+    VALUE proc;
+    proc = (VALUE)ND_scope->u3.node;
+    // proc_to_s(), in eval.c, shows how to extract the location. However,
+    // for this we need access to the BLOCK structure. Unfortunately,
+    // that BLOCK is defined in eval.c, not in any .h file we can #include.
+    // So instead we resort to a dirty trick: we parse the output of Proc#to_s.
+    return rb_funcall(proc, rb_intern("_location"), 0, 0);
   }
 
   if (nd_type(ND_scope) != NODE_SCOPE/*3*/) {
     printf("I'm expecting a NODE_SCOPE HERE (got %d instead)\n", nd_type(ND_scope));
-    return RSTR("I'm expecting a NODE_SCOPE HERE...");
+    return RSTR("<I'm expecting a NODE_SCOPE HERE...>");
   }
-  
+
   //
   // The NODE_BLOCK node
   //
-  
+
   ND_block = ND_scope->u3.node;
 
-  if (nd_type(ND_block) != NODE_BLOCK/*4*/) {
-    return RSTR("I'm expecting a NODE_BLOCK here...");
+  if (!ND_block || nd_type(ND_block) != NODE_BLOCK/*4*/) {
+    return RSTR("<I'm expecting a NODE_BLOCK here...>");
   }
-  
+
   sprintf(line_s, "%d:", nd_line(ND_block));
   place = RSTR(line_s);
   rb_str_cat2(place, ND_block->nd_file);
-  
+
   return place;
 }
 
 /*
  *  call-seq:
- *     Drx.locate_method(Date, "to_s")  => str
- *  
+ *     Drx::Core::locate_method(Date, "to_s")  => str
+ *
  *  Locates the filename and line-number where a method was defined. Returns a
- *  string of the form "89:/path/to/file.rb", or nil if method doens't exist.
- *  If the method exist but isn't a Ruby method (i.e., if it's written in C),
- *  the string returned will include an erorr message, e.g. "That's a C
- *  function".
+ *  string of the form "89:/path/to/file.rb", or nil if the method doesn't exist,
+ *  or a string of the form "<identifier>".
+ *
+ *  If the method exists but isn't a Ruby method (e.g., if it's written in C),
+ *  an <identifier> string is returned. E.g., <c>, <alias>, <attr reader>.
  */
 static VALUE t_locate_method(VALUE self, VALUE obj, VALUE method_name)
 {
@@ -205,7 +226,7 @@ static VALUE t_locate_method(VALUE self, VALUE obj, VALUE method_name)
   }
   c_name = StringValuePtr(method_name);
   ID id = rb_intern(c_name);
-  if (st_lookup(RCLASS(obj)->m_tbl, id, &method_node))  {
+  if (st_lookup(RCLASS(obj)->m_tbl, id, (st_data_t *)&method_node))  {
     return t_do_locate_method(method_node);
   } else {
     return Qnil;
@@ -215,21 +236,31 @@ static VALUE t_locate_method(VALUE self, VALUE obj, VALUE method_name)
 // }}}
 
 VALUE mDrx;
+VALUE mCore;
+
+void Init_drx_core() {
+  mDrx  = rb_define_module("Drx");
+  mCore = rb_define_module_under(mDrx, "Core");
+  rb_define_module_function(mCore, "get_iv_tbl", t_get_iv_tbl, 1);
+  rb_define_module_function(mCore, "get_m_tbl", t_get_m_tbl, 1);
+  rb_define_module_function(mCore, "get_super", t_get_super, 1);
+  rb_define_module_function(mCore, "get_klass", t_get_klass, 1);
+  rb_define_module_function(mCore, "get_flags", t_get_flags, 1);
+  rb_define_module_function(mCore, "get_address", t_get_address, 1);
+  rb_define_module_function(mCore, "get_type", t_get_type, 1);
+  rb_define_module_function(mCore, "get_ivar", t_get_ivar, 2);
+  rb_define_module_function(mCore, "locate_method", t_locate_method, 2);
+  rb_define_const(mCore, "FL_SINGLETON", INT2FIX(FL_SINGLETON));
+  rb_define_const(mCore, "T_OBJECT", INT2FIX(T_OBJECT));
+  rb_define_const(mCore, "T_CLASS", INT2FIX(T_CLASS));
+  rb_define_const(mCore, "T_ICLASS", INT2FIX(T_ICLASS));
+  rb_define_const(mCore, "T_MODULE", INT2FIX(T_MODULE));
 
-void Init_drx_ext() {
-  mDrx = rb_define_module("Drx");
-  rb_define_module_function(mDrx, "get_iv_tbl", t_get_iv_tbl, 1);
-  rb_define_module_function(mDrx, "get_m_tbl", t_get_m_tbl, 1);
-  rb_define_module_function(mDrx, "get_super", t_get_super, 1);
-  rb_define_module_function(mDrx, "get_klass", t_get_klass, 1);
-  rb_define_module_function(mDrx, "get_flags", t_get_flags, 1);
-  rb_define_module_function(mDrx, "get_address", t_get_address, 1);
-  rb_define_module_function(mDrx, "get_type", t_get_type, 1);
-  rb_define_module_function(mDrx, "get_ivar", t_get_ivar, 2);
-  rb_define_module_function(mDrx, "locate_method", t_locate_method, 2);
-  rb_define_const(mDrx, "FL_SINGLETON", INT2FIX(FL_SINGLETON));
-  rb_define_const(mDrx, "T_OBJECT", INT2FIX(T_OBJECT));
-  rb_define_const(mDrx, "T_CLASS", INT2FIX(T_CLASS));
-  rb_define_const(mDrx, "T_ICLASS", INT2FIX(T_ICLASS));
-  rb_define_const(mDrx, "T_MODULE", INT2FIX(T_MODULE));
+  // For the following, see explanation in t_do_locate_method().
+  rb_eval_string("\
+    class ::Proc;\
+      def _location;\
+        if to_s =~ /@(.*?):(\\d+)>$/ then \"#$2:#$1\" end;\
+      end;\
+    end");
 }

data/ext/extconf.rb

@@ -1,2 +1,2 @@
 require 'mkmf'
-create_makefile("drx_ext")
+create_makefile("drx_core")

data/lib/drx/graphviz.rb

@@ -0,0 +1,240 @@
+# Adds Graphviz diagraming capability to ObjInfo
+
+module Drx
+
+  class ObjInfo
+
+    # Notes:
+    # - Windows' CMD.EXE too supports "2>&1"
+    # - We're generating GIF, not PNG, because that's a format Tk
+    #   supports out of the box.
+    GRAPHVIZ_COMMAND = 'dot "%s" -Tgif -o "%s" -Tcmapx -o "%s" 2>&1'
+
+    @@sizes = {
+      '100%' => "
+        node[fontsize=10]
+      ",
+      '90%' => "
+        node[fontsize=10]
+        ranksep=0.4
+        edge[arrowsize=0.8]
+      ",
+      '80%' => "
+        node[fontsize=10]
+        ranksep=0.3
+        nodesep=0.2
+        node[height=0.4]
+        edge[arrowsize=0.6]
+      ",
+      '60%' => "
+        node[fontsize=8]
+        ranksep=0.18
+        nodesep=0.2
+        node[height=0]
+        edge[arrowsize=0.5]
+      "
+    }
+
+    # Create an ID for the DOT node representing this object.
+    def dot_id
+       ('o' + address.to_s).sub('-', '_')
+    end
+
+    # Creates a pseudo URL for the HTML imagemap.
+    def dot_url
+      "http://server/obj/#{dot_id}"
+    end
+
+    # Quotes a string to be used in DOT source.
+    def dot_quote(s)
+      # @todo: find the documentation for tr()?
+      '"' + s.gsub('\\') { '\\\\' }.gsub('"', '\\"').gsub("\n", '\\n') + '"'
+    end
+
+    # Returns the DOT style for the node.
+    def dot_style__default
+      if singleton?
+        # A singleton class
+        "shape=oval,color=skyblue1,style=filled"
+      elsif t_class?
+        # A class
+        "shape=oval,color=lightblue1,style=filled"
+      elsif t_iclass? or t_module?
+        # A module
+        if repr['#']
+          # Paint anonymous modules only lightly.
+          "shape=box,style=filled,color=\"#D9FFF2\",fontcolor=gray60"
+        else
+          "shape=box,style=filled,color=aquamarine"
+        end
+      else
+        # Else: a "normal" object, or an immediate.
+        "shape=house,color=wheat1,style=filled"
+      end
+    end
+
+    # Returns the DOT style for the node.
+    def dot_style__crazy
+      craze = "distortion=#{2*rand-1},skew=#{2*rand-1},orientation=#{360*rand}"
+      crazy_oval = "shape=polygon,sides=25," + craze
+      crazy_rect = "shape=polygon,sides=#{4+rand(3)}," + craze
+      if singleton?
+        # A singleton class
+        "#{crazy_oval},color=palevioletred3,style=filled,fontcolor=white,peripheries=3"
+      elsif t_class?
+        # A class
+        "#{crazy_oval},color=palevioletred1,style=filled"
+      elsif t_iclass? or t_module?
+        # A module
+        "#{crazy_rect},color=peachpuff1,style=filled"
+      else
+        # Else: a "normal" object, or an immediate.
+        "shape=house,color=pink,style=filled"
+      end
+    end
+
+    # Returns the DOT label for the node.
+    #
+    # The representation may be quite big, so we trim it.
+    def dot_label(max = 20)
+      if class_like?
+        # Let's be more lenient when trimming a class/module name.
+        # We want to show The::Last::Component and possibly a singleton's
+        # trailing 'S.
+        max = 60 if max < 60
+      end
+      r = repr
+      if r.length > max
+        r[0, max] + ' ...'
+      else
+        r
+      end
+    end
+
+    def dot_source(level = 0, opts = {}, &block) # :yield:
+      out = ''
+      # Note: since 'obj' may be a T_ICLASS, it doesn't repond to many methods,
+      # including is_a?. So when we're querying things we're using Drx calls
+      # instead.
+
+      if level.zero?
+        out << 'digraph {' "\n"
+        out << @@sizes[opts[:size] || '100%']
+        @@seen = {}
+      end
+
+      seen = @@seen[address]
+      @@seen[address] = true
+
+      if not seen
+        dot_style = method('dot_style__' + (opts[:style] || 'default')).call
+        out << "#{dot_id} [#{dot_style}, label=#{dot_quote dot_label}, URL=#{dot_quote dot_url}];" "\n"
+      end
+
+      yield self if block_given?
+
+      return '' if seen
+
+      if class_like?
+        if spr = self.super and display_super?(spr)
+          out << spr.dot_source(level+1, opts, &block)
+          if [Module, ObjInfo.new(Module).klass.the_object].include? the_object
+            # We don't want these relatively insignificant lines to clutter the display,
+            # so we paint them lightly and tell DOT they aren't to affect the layout (width=0).
+            out << "#{dot_id} -> #{spr.dot_id} [color=gray85, weight=0];" "\n"
+          else
+            out << "#{dot_id} -> #{spr.dot_id};" "\n"
+          end
+        end
+      end
+
+      kls = effective_klass
+      if display_klass?(kls)
+        out << kls.dot_source(level+1, opts, &block)
+        out << "#{dot_id} -> #{kls.dot_id} [style=dotted];" "\n"
+        out << "{ rank=same; #{dot_id}; #{kls.dot_id}; }" "\n"
+      end
+
+      if level.zero?
+        out << '}' "\n"
+      end
+
+      return out
+    end
+
+    # Whether to display the klass.
+    def display_klass?(kls)
+      if t_iclass?
+        # We're interested in an ICLASS's klass only if it isn't Module.
+        #
+        # Usualy this means that the ICLASS has a singleton (see "Singletons
+        # of included modules" in display_super?()). We want to see this
+        # singleton.
+        return Module != kls.the_object
+      else
+        # Displaying a singletone's klass is confusing and usually unneeded.
+        return !singleton?
+      end
+    end
+
+    # Whether to display the super.
+    def display_super?(spr)
+      if (singleton? or t_iclass?) and Module == spr.the_object
+         # Singletons of included modules, and modules included in them,
+         # have their chain eventually reach Module. To prevent clutter,
+         # we don't show this final link.
+         #
+         # "Singletons of included modules" often exist only for their
+         # #included method. For example, DataMapper#Resource have
+         # such a singleton.
+        return false
+      end
+      return true
+    end
+
+    # Like klass(), but without surprises.
+    #
+    # Since the klass of an ICLASS is the module itself, we need to
+    # invoke klass() twice.
+    def effective_klass
+      if t_iclass?
+        klass.klass
+      else
+        klass
+      end
+    end
+
+    # Generates a diagram of the inheritance hierarchy. It accepts a hash
+    # pointing to pathnames to write the result to. A Tempfiles hash
+    # can be used instead.
+    #
+    #   the_object = "some object"
+    #   Tempfiles.new do |files|
+    #     ObjInfo.new(the_object).generate_diagram
+    #     system('xview ' + files['gif'])
+    #   end
+    #
+    def generate_diagram(files, opts = {}, &block)
+      source = self.dot_source(0, opts, &block)
+      File.open(files['dot'], 'w') { |f| f.write(source) }
+      command = GRAPHVIZ_COMMAND % [files['dot'], files['gif'], files['map']]
+      message = Kernel.`(command)  # `
+      if $? != 0
+        error = <<-EOS % [command, message]
+ERROR: Failed to run the 'dot' command. Make sure you have the GraphViz
+package installed and that its bin folder appears in your PATH.
+
+The command I tried to execute is this:
+
+%s
+
+And the response I got is this:
+
+%s
+        EOS
+        raise error
+      end
+    end
+
+  end
+end

data/lib/drx/objinfo.rb

@@ -0,0 +1,147 @@
+
+module Drx
+
+  # An object orieneted wrapper around the DrX::Core functions.
+  #
+  # This object lets you query various properties of an object.
+  #
+  #   info = ObjInfo.new("foo")
+  #   info.has_iv_tbl?
+  #   info.klass
+  #
+  class ObjInfo
+    def initialize(obj)
+      @obj = obj
+      @type = Core::get_type(@obj)
+    end
+
+    def address
+      Core::get_address(@obj)
+    end
+
+    def the_object
+      @obj
+    end
+
+    # Returns true if this object is either a class or a module.
+    # When true, you know it has 'm_tbl' and 'super'.
+    def class_like?
+      [Core::T_CLASS, Core::T_ICLASS, Core::T_MODULE].include? @type
+    end
+
+    # Returns the method-table of an object.
+    def m_tbl
+      Core::get_m_tbl(@obj)
+    end
+
+    # Returns the source-code position where a method is defined.
+    def locate_method(method_name)
+      Core::locate_method(@obj, method_name)
+    end
+
+    def has_iv_tbl?
+      t_object? || class_like?
+    end
+
+    # Returns the variable-table of an object.
+    def iv_tbl
+      return nil if not has_iv_tbl?
+      Core::get_iv_tbl(@obj)
+    end
+
+    # @todo: this could be nicer. perhaps define an [] accessor.
+    def __get_ivar(name)
+      if class_like? and name.to_s =~ /^[A-Z]/
+        # If it's a constant, it may be 'autoloaded'. We
+        # trigger the loading by calling const_get().
+        @obj.const_get(name)
+      end
+      Core::get_ivar(@obj, name)
+    end
+
+    def singleton?
+      class_like? && (Core::get_flags(@obj) & Core::FL_SINGLETON).nonzero?
+    end
+
+    def t_iclass?
+      @type == Core::T_ICLASS
+    end
+
+    def t_class?
+      @type == Core::T_CLASS
+    end
+
+    def t_object?
+      @type == Core::T_OBJECT
+    end
+
+    def t_module?
+      @type == Core::T_MODULE
+    end
+
+    # Note: the klass of an iclass is the included module.
+    def klass
+      ObjInfo.new Core::get_klass(@obj)
+    end
+
+    # Returns the 'super' of a class-like object. Returns nil for end of chain.
+    #
+    # Examples: Kernel has a NULL super. Modules too have NULL super, unless
+    # when 'include'ing.
+    def super
+      spr = Core::get_super(@obj)
+      # Note: we can't do 'if spr.nil?' because T_ICLASS doesn't "have" #nil.
+      spr ? ObjInfo.new(spr) : nil
+    end
+
+    # Returns a string representation of the object. Similar to Object#inspect.
+    def repr
+      if t_iclass?
+        'include ' + klass.repr
+      elsif singleton?
+        attached = __get_ivar('__attached__') || self
+        attached.inspect + " 'S"
+      else
+        @obj.inspect
+      end
+    end
+
+    # A utility function to print the inheritance hierarchy of an object.
+    def examine(level = 0, title = '', &block) # :yield:
+      # Note: since '@obj' may be a T_ICLASS, it doesn't repond to may methods,
+      # including is_a?. So when we're querying things we're using Drx calls
+      # instead.
+
+      @@seen = {} if level.zero?
+      line = ('  ' * level) + title + ' ' + repr
+
+      seen = @@seen[address]
+      @@seen[address] = true
+
+      if seen
+        line += " [seen]"
+      end
+
+      if block_given?
+        yield line, self
+      else
+        puts line
+      end
+
+      return if seen
+
+      if class_like?
+        if spr = self.super
+          spr.examine(level + 1, '[super]', &block)
+        end
+      end
+ 
+      # Displaying a T_ICLASS's klass isn't very useful, because the data
+      # is already mirrored in the m_tbl and iv_tvl of the T_ICLASS itself.
+      if not t_iclass?
+        klass.examine(level + 1, '[klass]', &block)
+      end
+    end
+  end
+
+end