drx 0.4.2 → 0.4.3

data/examples/drx_activerecord.rb

@@ -0,0 +1,44 @@
+require 'rubygems'
+require 'activerecord'
+
+#
+# This is part of a blogging website. Users write posts. A post
+# belongs to a user.
+#
+
+ActiveRecord::Base.logger = Logger.new(STDERR)
+ActiveRecord::Base.colorize_logging = false
+
+ActiveRecord::Base.establish_connection(
+  :adapter => 'sqlite3',
+  :database  => ':memory:'
+)
+
+ActiveRecord::Schema.define do
+  create_table :users do |table|
+    table.column :name, :string
+    table.column :mail, :string
+  end
+  create_table :posts do |table|
+    table.column :user_id, :integer
+    table.column :title, :string
+    table.column :body, :string
+  end
+end
+
+class User < ActiveRecord::Base
+  has_many :posts
+end
+
+class Post < ActiveRecord::Base
+  belongs_to :users
+end
+
+david = User.create(:name => 'David')
+david.posts.create(:title => 'Lies')
+david.posts.create(:title => 'Truths')
+
+post = User.find(1).posts.first
+
+require 'drx'
+post.see

data/examples/drx_sequel.rb

@@ -0,0 +1,35 @@
+require 'rubygems'
+require 'sequel'
+
+#
+# This is part of a blogging website. Users write posts. A post
+# belongs to a user.
+#
+
+DB = Sequel.sqlite(':memory:')
+
+DB.create_table :posts do
+  primary_key :id
+  Integer :user_id
+  String :title
+  String :body
+end
+
+DB.create_table :users do
+  primary_key :id
+  String :name
+  String :email
+end
+
+class Post < Sequel::Model
+  many_to_one :user
+end
+
+class User < Sequel::Model
+  one_to_many :posts
+end
+
+post = Post.create(:title => 'Lies', :user => User.create(:name => 'David'))
+
+require 'drx'
+post.see

data/lib/drx/arguments.rb

@@ -0,0 +1,103 @@
+# Adds method arguments detection to ObjInfo
+
+module Drx
+
+  class ObjInfo
+
+    class << self
+      # Whether to use the 'arguments' gem, if present.
+      # This isn't on by default because it's slow.
+      attr_accessor :use_arguments_gem
+    end
+
+    # Returns a Ruby 1.9.2-compatible array describing the arguments a method expects.
+    def method_arguments(method_name)
+      if ObjInfo.use_arguments_gem
+        _method_arguments__by_arguments_gem(method_name) || _method_arguments__by_arity(method_name)
+      else
+        _method_arguments__by_methopara(method_name) || _method_arguments__by_arity(method_name)
+      end
+    end
+
+    # Strategy: use the 'arguments' gem, which, in turn, uses either ParseTree (Ruby 1.8)
+    # or RubyParser (Ruby 1.9)
+    #
+    # pros: shows default values; works for 1.8 too.
+    # cons: very slow.
+    def _method_arguments__by_arguments_gem(method_name)
+      @@once__arguments ||= begin
+        begin
+          require 'arguments'
+        rescue LoadError
+          # Not installed.
+        end
+        1
+      end
+      return nil if not defined? Arguments
+      args = Arguments.names(the_object, method_name, false)
+      # Convert this to a Ruby 1.9.2 format:
+      return args.map do |arg|
+        if arg.size == 2
+          [:opt, arg[0], arg[1]]
+        else
+          name = arg[0].to_s
+          case name[0,1]
+          when '*' then [:rest, name[1..-1]]
+          when '&' then [:block, name[1..-1]]
+          else [:req, name]
+          end
+        end
+      end
+    rescue SyntaxError => e
+      # We could just return nil here, to continue to the next strategy,
+      # but we want to inform the user of the suckiness of RubyParser.
+      raise
+    rescue Exception
+      nil
+    end
+
+    # Strategy: use Method#parameters (for ruby 1.9 only).
+    #
+    # pros: fast.
+    # cons: doesn't show default values.
+    def _method_arguments__by_methopara(method_name)
+      @@once__methopara ||= begin
+        # For ruby 1.9.0 and 1.9.1, we need to use a gem.
+        begin
+          require 'methopara'
+        rescue LoadError
+          # Not installed.
+        end
+        1
+      end
+      method = the_object.instance_method(method_name)
+      if method.respond_to? :parameters
+        return method.parameters
+      end
+    rescue NotImplementedError
+      # For some methods #parameters raises an exception. We return nil
+      # to move on to the next strategy.
+      return nil
+    end
+
+    # Strategy: simulation via Method#arity.
+    #
+    # This is used as a fallback if any of the other strategies fail.
+    #
+    # pros: fast; work without any gems.
+    # cons: doesn't show argument names.
+    def _method_arguments__by_arity(method_name)
+      method = the_object.instance_method(method_name)
+      ary, rest = method.arity, false
+      if ary < 0
+        ary = -ary - 1
+        rest = true
+      end
+      args = [[:req]] * ary
+      args << [:rest] if rest
+      return args
+    end
+
+  end
+
+end

data/lib/drx/graphviz.rb

@@ -8,7 +8,8 @@ module Drx
     # - 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'
+    # - Each {extension} token is replaced by the filepath with that extension.
+    GRAPHVIZ_COMMAND = 'dot "{dot}" -Tgif -o "{gif}" -Tcmapx -o "{map}" 2>&1'
 
     @@sizes = {
       '100%' => "
@@ -128,7 +129,7 @@ module Drx
       out
     end
 
-    def dot_fragment(opts = {}, &block) # :yield:
+    def dot_fragment(opts = {}, ancestors = [], &block) # :yield:
       out = ''
       # Note: since 'obj' may be a T_ICLASS, it doesn't respond to many methods,
       # including is_a?. So when we're querying things we're using Drx calls
@@ -147,9 +148,9 @@ module Drx
       return '' if seen
 
       if class_like?
-        if spr = self.super and display_super?(spr)
-          out << spr.dot_fragment(opts, &block)
-          if insignificant_super_arrow?(opts)
+        if spr = self.super and display_super?(spr, ancestors)
+          out << spr.dot_fragment(opts, ancestors + [self], &block)
+          if insignificant_super_arrow?(opts, ancestors)
             # 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"
@@ -172,6 +173,12 @@ module Drx
         # (To see the effect of this, set the weight unconditionally to '0' and
         # see the graph for DataMapper.)
         weight = t_iclass? ? 1 : 0
+
+        # However, here's a special case. DOT seems to have a bug: it sometimes
+        # doesn't draw the arrows going out of Class and Module (to their
+        # singletons). Making their weight 1 makes DOT draw them.
+        weight = 1 if self == _Class or self == _Module
+
         out << "#{dot_id} -> #{kls.dot_id} [style=dotted, weight=#{weight}];" "\n"
         out << "{ rank=same; #{dot_id}; #{kls.dot_id}; }" "\n"
       end
@@ -187,11 +194,13 @@ module Drx
     # following method is to break the cycle. Normally we break the cycle at
     # Module (and its singleton). When the user is examining a module, we
     # instead break the cycle at Class (and its singleton).
-    def insignificant_super_arrow?(opts)
+    def insignificant_super_arrow?(opts, my_ancestors)
       if opts[:base].t_module?
-        [Class, ObjInfo.new(Class).klass.the_object].include? the_object
+        self == _ClassS or
+          (self.super == _Module and (my_ancestors + [self]).include? _Class)
       else
-        [Module, ObjInfo.new(Module).klass.the_object].include? the_object
+        self == _ModuleS or
+          (self.super == _Object and (my_ancestors + [self]).include? _Module)
       end
     end
 
@@ -203,7 +212,17 @@ module Drx
         # Usually 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
+
+        # Unfortunately, here is a special treatment for the 'arguments' gem,
+        # which our GUI uses. That gem includes the 'Arguments' module in both
+        # Class and Module (this is redundant!) and having the singleton twice
+        # in our graph may break its nice rectangular structure. So we don't
+        # show its singleton.
+        if defined? ::Arguments
+           return false if ::Arguments == klass.the_object
+        end
+
+        return kls != _Module
       else
         # Displaying a singleton's klass is confusing and usually unneeded.
         return !singleton?
@@ -211,16 +230,19 @@ module Drx
     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
+    def display_super?(spr, my_ancestors)
+      if spr == _Module
+        # Many objects have Module as their super (e.g., singletones
+        # of included modules, or modules included in them). To prevent
+        # clutter we print the arrow to Module only if it comes from
+        # Class (or a module included in it).
+        return (my_ancestors + [self]).include? _Class
+        #
+        # A somewhat irrelevant note (I don't have a better place to put it):
+        #
+        # "Singletons of included modules" often exist solely for their
+        # #included method. For example, DataMapper#Resource has
+        # such a singleton.
       end
       return true
     end
@@ -237,8 +259,19 @@ module Drx
       end
     end
 
+    # Shortcuts for some specific objects. An "S" suffix
+    # denotes a singleton.
+    protected
+    def _Module; ObjInfo.new(Module); end
+    def _ModuleS; ObjInfo.new(Module).klass; end
+    def _Object; ObjInfo.new(Object); end
+    def _ObjectS; ObjInfo.new(Object).klass; end
+    def _Class; ObjInfo.new(Class); end
+    def _ClassS; ObjInfo.new(Class).klass; end
+    public
+
     # Generates a diagram of the inheritance hierarchy. It accepts a hash
-    # pointing to pathnames to write the result to. A Tempfiles hash
+    # pointing to filepaths to write the result to. A Tempfiles hash
     # can be used instead.
     #
     #   the_object = "some object"
@@ -250,7 +283,8 @@ module Drx
     def generate_diagram(files, opts = {}, &block)
       source = self.dot_source(opts, &block)
       File.open(files['dot'], 'w') { |f| f.write(source) }
-      command = GRAPHVIZ_COMMAND % [files['dot'], files['gif'], files['map']]
+      # Replace {extension} tokens with their corresponding filepaths:
+      command = GRAPHVIZ_COMMAND.gsub(/\{([a-z]+)\}/) { files[$1] }
       message = Kernel.`(command)  # `
       if $? != 0
         error = <<-EOS % [command, message]

data/lib/drx/objinfo.rb

@@ -19,6 +19,10 @@ module Drx
       Core::get_address(@obj)
     end
 
+    def ==(other)
+      other.is_a?(ObjInfo) and address == other.address
+    end
+
     def the_object
       @obj
     end
@@ -70,8 +74,9 @@ module Drx
       Core::get_iv_tbl(@obj)
     end
 
-    # @todo: this could be nicer. perhaps define an [] accessor.
-    def __get_ivar(name)
+    # Returns the value of an instance variable. Actually, of any sort
+    # of variable that's recorded in the variable-table.
+    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().
@@ -120,7 +125,7 @@ module Drx
       if t_iclass?
         'include ' + klass.repr
       elsif singleton?
-        attached = __get_ivar('__attached__') || self
+        attached = get_ivar('__attached__') || self
         attached.inspect + " 'S"
       else
         @obj.inspect

data/lib/drx/tk/app.rb

@@ -11,8 +11,23 @@ module Drx
 
     class Application
 
+      # Loads ~/.drxrc.
+      #
+      # @see Application#user_customizations
+      def self.load_rc
+        @rc_loaded ||= begin
+          rc = File.join(ENV['HOME'] || Dir.pwd, '.drxrc')
+          load rc if File.exist? rc
+          1
+        end
+      end
+
+      # Returns the top-level frame in which to show ourselves.
       def toplevel
-        @toplevel ||= TkRoot.new
+        @toplevel ||= begin
+          # We're showing ourselves inside a TkRoot, unless one already exists.
+          Application.first_window? ? TkRoot.new : TkToplevel.new
+        end
       end
 
       def initialize
@@ -56,12 +71,16 @@ module Drx
           show 'headings'
         }
         @methodsbox = Tk::Tile::Treeview.new(toplevel) {
-          columns 'name location'
+          columns 'name arguments location'
           heading_configure('name', :text => 'Name')
+          heading_configure('arguments', :text => 'Arguments')
           heading_configure('location', :text => 'Location')
           column_configure('name', :stretch => false )
+          column_configure('arguments', :stretch => false )
           column_configure('location', :stretch => false )
           show 'headings'
+          # We want the layout manager to allocate space for two columns only:
+          displaycolumns 'name location'
         }
 
         @graph_size_menu = Tk::Tile::Combobox.new(toplevel) {
@@ -83,6 +102,15 @@ module Drx
           save_graph tip
         }
 
+        @show_arguments_chk = TkCheckbutton.new(toplevel) {
+          text 'Show arguments'
+          variable TkVariable.new(0)
+        }
+        @use_arguments_gem_chk = TkCheckbutton.new(toplevel) {
+          text "Use the 'arguments' gem (slower)"
+          variable TkVariable.new(0)
+        }
+
         layout
 
         @varsbox.bind('<TreeviewSelect>') {
@@ -141,30 +169,45 @@ module Drx
           @graph_opts[:style] = @graph_style_menu.get
           refresh
         }
+        @show_arguments_chk.variable.trace('w') do |value,|
+          if value == 1
+            @use_arguments_gem_chk.raise
+            @methodsbox.displaycolumns 'name arguments location'
+            display_methods(current_object)
+          else
+            @use_arguments_gem_chk.lower
+            @methodsbox.displaycolumns 'name location'
+          end
+        end
+        @use_arguments_gem_chk.variable.trace('w') do |value,|
+          ObjInfo.use_arguments_gem = (value == 1)
+          display_methods(current_object)
+        end
+        @show_arguments_chk.variable.value = @show_arguments_chk.variable.value # Trigger the trace handler.
 
         output "Please visit the homepage, http://drx.rubyforge.org/, for usage instructions.\n", 'info'
 
-        one_time_initialization
+        Application.load_rc
+        system_customizations
         user_customizations
       end
 
-      def one_time_initialization
-        @@one_time_initialization ||= begin
+      # Users may redefine this method in their ~/.drxrc
+      # to fine-tune the app.
+      def user_customizations
+      end
+
+      # The following are default customizations. They are subjective in
+      # nature and users may knock them out in their ~/.drxrc.
+      def system_customizations
+        if Application.first_window?
           # Try to make the Unixy GUI less ugly.
           if Tk.windowingsystem == 'x11' and Ttk.themes.include? 'clam'
             Ttk.set_theme 'clam'
           end
-          rc = File.join(ENV['HOME'] || Dir.pwd, '.drxrc')
-          load rc if File.exist? rc
-          1
         end
       end
 
-      # Users may redefine this method in their ~/.drxrc
-      # to fine-tune the app.
-      def user_customizations
-      end
-
       def vbox(*args); VBox.new(toplevel, args); end
       def hbox(*args); HBox.new(toplevel, args); end
       def separator; TkLabel.new(toplevel, :text => '  '); end
@@ -204,7 +247,8 @@ module Drx
         ), :weight => 50
         panes.add vbox(
           TkLabel.new(toplevel, :text => 'Methods (m_tbl):', :anchor => 'w'),
-          [Scrolled.new(toplevel, @methodsbox), { :expand => true, :fill => 'both' } ]
+          [Scrolled.new(toplevel, @methodsbox), { :expand => true, :fill => 'both' } ],
+          hbox(@show_arguments_chk, separator, @use_arguments_gem_chk)
         ), :weight => 10
 
         main_frame.add(panes)
@@ -221,11 +265,10 @@ module Drx
       def open_up_editor(filename, lineno)
         command = sprintf(ENV['DRX_EDITOR_COMMAND'] || EDITOR_COMMAND, lineno, filename)
         output "Executing: #{command}...\n", 'info'
-        if !fork
+        Thread.new do
           if !Kernel.system(command)
             output "Could not execute the command '#{command}'\n", 'error'
           end
-          exit!
         end
       end
 
@@ -250,7 +293,7 @@ module Drx
       end
 
       def selected_var
-        ObjInfo.new(current_object).__get_ivar(@varsbox.get_selection)
+        ObjInfo.new(current_object).get_ivar(@varsbox.get_selection)
       end
 
       def eval_code(code)
@@ -289,14 +332,20 @@ module Drx
           # Get rid of gazillions of Tk classes:
           vars = vars.reject { |v| v =~ /Tk|Ttk/ }
           vars.each do |name|
-            value = if allowed_names.any? { |p| p === name }
-                      info.__get_ivar(name).inspect
-                    else
-                      # We don't want to inspect ruby's internal variables (because
-                      # they may not be Ruby values at all).
-                      ''
-                    end
-            @varsbox.insert('', 'end', :text => name, :values => [ name, value ] )
+            begin
+              value = if allowed_names.any? { |p| p === name }
+                        info.get_ivar(name).inspect
+                      else
+                        # We don't want to inspect ruby's internal variables (because
+                        # they may not be Ruby values at all).
+                        ''
+                      end
+              @varsbox.insert('', 'end', :text => name, :values => [ name, value ] )
+            rescue NameError
+              # Referencing an autoloaded constant (in ObjInfo#get_ivar()) may
+              # raise a NameError. This happens when the source file autoloaded
+              # defines the moudle/class in the top-level. Example is Camping::Mab.
+            end
           end
         end
       end
@@ -321,6 +370,27 @@ module Drx
         end
       end
 
+      # Returns a string describing a method's arguments, for use in GUIs.
+      def pretty_arguments(info, name)
+        args = info.method_arguments(name)
+        return args.map do |arg|
+          case arg[0]
+          when :req;   (arg[1] || 'arg').to_s
+          when :opt;   (arg[1] || 'arg').to_s + '=' + (arg[2] || '?')
+          when :rest;  '*' + (arg[1] || 'args').to_s
+          when :block; '&' + (arg[1] || 'arg').to_s
+          end
+        end.join ', '
+      rescue NameError
+        return '---'
+      rescue SyntaxError => e
+        'SYNTAX ERROR: ' + e.to_s
+      end
+
+      def show_arguments?
+        @show_arguments_chk.variable == 1
+      end
+
       # Fills the methods listbox with a list of the object's methods.
       def display_methods(obj)
         @methodsbox.clear
@@ -328,7 +398,11 @@ module Drx
         if obj and info.class_like?
           methods = info.m_tbl.keys.map do |v| v.to_s end.sort
           methods.each do |name|
-            @methodsbox.insert('', 'end', :text => name, :values => [ name, pretty_location(info, name) ] )
+            @methodsbox.insert('', 'end', :text => name, :values => [
+              name,
+              show_arguments? ? pretty_arguments(info, name) : '-',
+              pretty_location(info, name)
+            ])
           end
         end
       end
@@ -357,11 +431,19 @@ module Drx
         end
       end
 
+      # Updates the window title (usually shown in the taskbar).
+      def update_title(obj)
+        toplevel.title = 'Drx: ' + begin
+          obj.is_a?(Module) ? obj.name : obj.class.name
+        end.to_s # In case of singletons, #name returns nil, so to_s enforces a string.
+      end
+
       # Makes `obj` the primary object seen (the one which is the tip of the diagram).
       def navigate_to(obj)
         @current_object = obj
         @navigation_history << obj
         display_graph(obj)
+        update_title(obj)
         # Trigger the update of the variables and methods tables by selecting this object
         # in the imagemap.
         @im.active_url = @im.urls.first
@@ -391,9 +473,17 @@ module Drx
         navigate_to(current_object)
       end
 
+      class << self
+        attr_accessor :in_loop
+        def first_window?; !in_loop; end
+      end
+
       def run
-        # @todo Skip this if Tk is already running.
+        return if Application.in_loop
+        # @todo Any other way to detect that Tk's mainloop is already running?
+        Application.in_loop = true
         Tk.mainloop
+        Application.in_loop = false
         Tk.restart # So that Tk doesn't complain 'can't invoke "frame" command: application has been destroyed' next time.
       end
     end

data/lib/drx.rb

@@ -2,6 +2,7 @@
 
 require 'drx_core' # The C extension.
 require 'drx/objinfo'
+require 'drx/arguments'
 require 'drx/graphviz'
 
 module Drx

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: drx
 version: !ruby/object:Gem::Version 
-  version: 0.4.2
+  version: 0.4.3
 platform: ruby
 authors: 
 - Mooffie
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-02 00:00:00 +03:00
+date: 2010-04-16 00:00:00 +03:00
 default_executable: 
 dependencies: []
 
@@ -27,6 +27,7 @@ files:
 - lib/drx/tk/imagemap.rb
 - lib/drx/tk/app.rb
 - lib/drx/objinfo.rb
+- lib/drx/arguments.rb
 - lib/drx/tempfiles.rb
 - lib/drx.rb
 - ext/extconf.rb
@@ -34,7 +35,8 @@ files:
 - examples/drx_datamapper.rb
 - examples/drx_date.rb
 - examples/drx_guitar.rb
-- examples/drx_datamapper19.rb
+- examples/drx_activerecord.rb
+- examples/drx_sequel.rb
 has_rdoc: true
 homepage: http://drx.rubyforge.org/
 licenses: []

data/examples/drx_datamapper19.rb

@@ -1,35 +0,0 @@
-require 'rubygems'
-require 'dm-core'
-$: << File.join('/home/mooffie/_drx.git/lib')
-require 'drx'
-
-
-
-#
-# This is part of a blogging website. Users write posts. A post
-# belongs to a user.
-#
-
-class Post
-  include DataMapper::Resource
-
-  property :post_id,  Serial
-  property :title,    String
-  property :body,     Text
-
-  belongs_to :user
-end
-
-class User
-  include DataMapper::Resource
-
-  property :user_uid,  Serial
-  property :name,      String
-  property :mail,      String
-end
-
-post = Post.new
-
-p post
-require 'drx'
-post.see