ruby_tracer 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 752f406d1a3b8967596a30cc918fe2176f0da30df84651316ce452fae36cc940
-  data.tar.gz: cc21e0f38a5508be8154621d7a68a247a2cc1a43d0fc9c3294176bb32ad079ca
+  metadata.gz: 0ac708e995302930fed59fa3b9396dc5b3c45ab76d4306c8bbac65fe69c49377
+  data.tar.gz: 99f23f4e5fb2d5f8ae694ff1203524707c757fd5a91cd29131ac61e79c5cb15f
 SHA512:
-  metadata.gz: ef97f505b367ef51efe01877912697208f42be67e5d531515c176aa9b2e6c14a0c795a5707b075d3a9f4b4051a96257220c905c0437bfc64f7e99a01deb942aa
-  data.tar.gz: 5162367688b0581d28c63219f6a38953eff903fcbe9473b22001edb8670ad1f945c89308f9833d7684d7b331457dc35d25e3ff6cdb4cef4d34defccee1d0ef5e
+  metadata.gz: dd1e5c1aef7115227db143c95939ad7ce180c65924334f30540dbed8f9d2f5cd468f0e3e989af1e7d6dd4e49e023798d5a1133c26cf49ccef54080eceb6f925c
+  data.tar.gz: 0dd0e49cf41d3e9fe4fd880b68364f1727d4d29bb4fb8c35b76e37ed97549979130d2678f2f2a0c720282ad17bd0abb15b0694478dea24b40dc57baf452b434b

data/Gemfile

@@ -6,6 +6,7 @@ source "https://rubygems.org"
 gemspec
 
 gem "rake", "~> 13.0"
+gem "irb"
 
 gem "test-unit", "~> 3.0"
 

data/Gemfile.lock

@@ -1,15 +1,20 @@
 PATH
   remote: .
   specs:
-    ruby_tracer (0.1.0)
+    ruby_tracer (0.3.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    io-console (0.6.0)
+    irb (1.6.2)
+      reline (>= 0.3.0)
     language_server-protocol (3.17.0.3)
     power_assert (2.0.2)
     prettier_print (1.2.0)
     rake (13.0.6)
+    reline (0.3.2)
+      io-console (~> 0.5)
     ruby-lsp (0.3.8)
       language_server-protocol (~> 3.17.0)
       sorbet-runtime
@@ -25,6 +30,7 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  irb
   rake (~> 13.0)
   ruby-lsp
   ruby_tracer!

data/README.md

@@ -1,14 +1,6 @@
 # ruby_tracer
 
-ruby_tracer is an extraction of [`ruby/debug`](https://github.com/ruby/debug)'s [powerful tracers](https://github.com/ruby/debug/blob/master/lib/debug/tracer.rb), with user-facing APIs and some improvements on accuracy.
-
-Its goal is to help users understand their Ruby programss activities by emitting useful trace information, such us:
-
-- How and where is the target object is being used (`ObjectTracer`)
-- What exceptions are raised during the execution (`ExceptionTracer`)
-- When method calls are being performed (`CallTracer`)
-- Line execution (`LineTracer`)
-
+ruby_tracer is an extraction of [`ruby/debug`](https://github.com/ruby/debug)'s [powerful tracers](https://github.com/ruby/debug/blob/master/lib/debug/tracer.rb), with user-facing APIs, IRB-integration, and improvements on accuracy.
 
 ## Installation
 
@@ -24,7 +16,92 @@ $ gem install ruby_tracer
 
 ## Usage
 
-### ObjectTracer
+```rb
+Tracer.trace(object) { ... } # trace object's activities in the given block
+Tracer.trace_call { ... } # trace method calls in the given block
+Tracer.trace_exception { ... } # trace exceptions in the given block
+```
+
+**Example**
+
+```rb
+require "ruby_tracer"
+
+obj = Object.new
+
+def obj.foo
+  100
+end
+
+def bar(obj)
+  obj.foo
+end
+
+Tracer.trace(obj) { bar(obj) }
+ #depth:1  #<Object:0x000000010903c190> is used as a parameter obj of Object#bar at test.rb:13:in `block in <main>'
+ #depth:2  #<Object:0x000000010903c190> receives .foo at test.rb:10:in `bar'
+```
+
+### `ruby_tracer/helper`
+
+If you want to avoid the `Tracer` namespace, you can do `require "ruby_tracer/helper"` instead:
+
+```rb
+require "ruby_tracer/helper"
+
+trace(object) { ... } # trace object's activities in the given block
+trace_call { ... } # trace method calls in the given block
+trace_exception { ... } # trace exceptions in the given block
+```
+
+### IRB-integration
+
+Once required, `ruby_tracer` registers a few IRB commands to help you trace Ruby expressions:
+
+```
+trace              Trace the target object (or self) in the given expression. Usage: `trace [target,] <expression>`
+trace_call         Trace method calls in the given expression. Usage: `trace_call <expression>`
+trace_exception    Trace exceptions in the given expression. Usage: `trace_exception <expression>`
+```
+
+**Example**
+
+```rb
+# test.rb
+require "ruby_tracer"
+
+obj = Object.new
+
+def obj.foo
+  100
+end
+
+def bar(obj)
+  obj.foo
+end
+
+binding.irb
+```
+
+
+```
+irb(main):001:0> trace obj, bar(obj)
+ #depth:23 #<Object:0x0000000107a86648> is used as a parameter obj of Object#bar at (eval):1:in `<main>'
+ #depth:24 #<Object:0x0000000107a86648> receives .foo at test.rb:10:in `bar'
+=> 100
+irb(main):002:0> trace_call bar(obj)
+ #depth:23>                            Object#bar at (eval):1:in `<main>'
+ #depth:24>                             #<Object:0x0000000107a86648>.foo at test.rb:10:in `bar'
+ #depth:24<                             #<Object:0x0000000107a86648>.foo #=> 100 at test.rb:10:in `bar'
+ #depth:23<                            Object#bar #=> 100 at (eval):1:in `<main>'
+=> 100
+```
+
+### Tracer Classes
+
+If you want to have more control over individual traces, you can use individual tracer classes:
+
+#### ObjectTracer
 
 ```rb
 class User
@@ -49,7 +126,7 @@ end
  #depth:4  #<User:0x000000010696cad8 @name="John"> receives #name (User#name) at test.rb:8:in `authorized?'
 ```
 
-### ExceptionTracer
+#### ExceptionTracer
 
 ```rb
 ExceptionTracer.new.start
@@ -63,7 +140,7 @@ end
  #depth:1  #<RuntimeError: boom> at test.rb:4
 ```
 
-### CallTracer
+#### CallTracer
 
 ```rb
 class User
@@ -95,7 +172,7 @@ end
  #depth:4 <    block #=> true at test.rb:16
 ```
 
-### LineTracer
+#### LineTracer
 
 ```rb
 class User
@@ -120,6 +197,10 @@ end
  #depth:5  at test.rb:8
 ```
 
+## Customization
+
+TBD
+
 ## Acknowledgement
 
 [@ko1](https://github.com/ko1) (Koichi Sasada) implemented the majority of [`ruby/debug`](https://github.com/ruby/debug), including its tracers. So this project wouldn't exist without his amazing work there.

data/lib/ruby_tracer/base.rb

@@ -70,10 +70,11 @@ module Tracer
       end
     end
 
-    def initialize(output: STDOUT, pattern: nil, colorize: nil)
+    def initialize(output: STDOUT, pattern: nil, colorize: nil, depth_offset: 0)
       @name = self.class.name
       @type = @name.sub(/Tracer\z/, "")
       @output = output
+      @depth_offset = depth_offset
       @colorize = colorize || colorizable?
 
       if pattern

data/lib/ruby_tracer/call_tracer.rb

@@ -7,22 +7,30 @@ class CallTracer < Tracer::Base
     TracePoint.new(:a_call, :a_return) do |tp|
       next if skip?(tp)
 
+      location = caller_locations(2, 1).first.to_s
+      next if location.match?(DIR) || location.match?(/<internal:/)
+
       depth = caller.size
 
       call_identifier_str = (tp.defined_class ? minfo(tp) : "block")
-
       call_identifier_str = colorize_blue(call_identifier_str)
 
       case tp.event
       when :call, :c_call, :b_call
         depth += 1 if tp.event == :c_call
         sp = " " * depth
-        out tp, ">#{sp}#{call_identifier_str}", depth: depth
+        out tp,
+            ">#{sp}#{call_identifier_str}",
+            depth: depth - 2 - @depth_offset,
+            location: location
       when :return, :c_return, :b_return
         depth += 1 if tp.event == :c_return
         sp = " " * depth
         return_str = colorize_magenta(safe_inspect(tp.return_value))
-        out tp, "<#{sp}#{call_identifier_str} #=> #{return_str}", depth: depth
+        out tp,
+            "<#{sp}#{call_identifier_str} #=> #{return_str}",
+            depth: depth - 2 - @depth_offset,
+            location: location
       end
     end
   end

data/lib/ruby_tracer/exception_tracer.rb

@@ -9,7 +9,9 @@ class ExceptionTracer < Tracer::Base
 
       exc = tp.raised_exception
 
-      out tp, " #{colorize_magenta(exc.inspect)}"
+      out tp,
+          " #{colorize_magenta(exc.inspect)}",
+          depth: caller.size - (1 + @depth_offset)
     rescue Exception => e
       p e
     end

data/lib/ruby_tracer/helper.rb

@@ -0,0 +1,3 @@
+require "ruby_tracer"
+
+Object.include(Tracer::Helper)

data/lib/ruby_tracer/irb.rb

@@ -0,0 +1,90 @@
+require "irb/cmd/nop"
+require "irb"
+
+module Tracer
+  def self.register_irb_commands
+    ec = IRB::ExtendCommandBundle.instance_variable_get(:@EXTEND_COMMANDS)
+
+    [
+      [:trace, :Trace, nil, [:trace, IRB::ExtendCommandBundle::OVERRIDE_ALL]],
+      [
+        :trace_call,
+        :TraceCall,
+        nil,
+        [:trace_call, IRB::ExtendCommandBundle::OVERRIDE_ALL]
+      ],
+      [
+        :trace_exception,
+        :TraceException,
+        nil,
+        [:trace_exception, IRB::ExtendCommandBundle::OVERRIDE_ALL]
+      ]
+    ].each do |ecconfig|
+      ec.push(ecconfig)
+      IRB::ExtendCommandBundle.def_extend_command(*ecconfig)
+    end
+  end
+end
+
+module IRB
+  module ExtendCommand
+    class TraceCommand < Nop
+      class << self
+        def transform_args(args)
+          # Return a string literal as is for backward compatibility
+          if args.empty? || string_literal?(args)
+            args
+          else # Otherwise, consider the input as a String for convenience
+            args.strip.dump
+          end
+        end
+      end
+    end
+
+    class Trace < TraceCommand
+      category "Tracing"
+      description "Trace the target object (or self) in the given expression. Usage: `trace [target,] <expression>`"
+
+      def execute(*args)
+        args = args.first.split(/,/, 2)
+
+        case args.size
+        when 1
+          target = irb_context.workspace.main
+          expression = args.first
+        when 2
+          target = eval(args.first, irb_context.workspace.binding)
+          expression = args.last
+        else
+          raise ArgumentError,
+                "wrong number of arguments (given #{args.size}, expected 1..2)"
+        end
+
+        b = irb_context.workspace.binding
+        Tracer.trace(target) { eval(expression, b) }
+      end
+    end
+
+    class TraceCall < TraceCommand
+      category "Tracing"
+      description "Trace method calls in the given expression. Usage: `trace_call <expression>`"
+
+      def execute(expression)
+        b = irb_context.workspace.binding
+        Tracer.trace_call { eval(expression, b) }
+      end
+    end
+
+    class TraceException < TraceCommand
+      category "Tracing"
+      description "Trace exceptions in the given expression. Usage: `trace_exception <expression>`"
+
+      def execute(expression)
+        b = irb_context.workspace.binding
+        Tracer.trace_exception { eval(expression, b) }
+      end
+    end
+  end
+end
+
+Tracer.register_irb_commands

data/lib/ruby_tracer/object_tracer.rb

@@ -65,7 +65,7 @@ class ObjectTracer < Tracer::Base
         out tp,
             " #{colorized_target_label} receives #{colorize_blue(method_info)}",
             location: caller_locations(internal_depth, 1).first,
-            depth: caller.size - internal_depth
+            depth: caller.size - internal_depth - @depth_offset
       elsif !tp.parameters.empty?
         b = tp.binding
         method_info = colorize_blue(minfo(tp))
@@ -82,7 +82,7 @@ class ObjectTracer < Tracer::Base
               out tp,
                   " #{colorized_target_label} is used as a parameter #{colorized_name} of #{method_info}",
                   location: caller_locations(internal_depth, 1).first,
-                  depth: caller.size - internal_depth
+                  depth: caller.size - internal_depth - @depth_offset
             end
           when :rest
             next if name == :"*"
@@ -94,7 +94,7 @@ class ObjectTracer < Tracer::Base
                 out tp,
                     " #{colorized_target_label} is used as a parameter in #{colorized_name} of #{method_info}",
                     location: caller_locations(internal_depth, 1).first,
-                    depth: caller.size - internal_depth
+                    depth: caller.size - internal_depth - @depth_offset
               end
             end
           when :keyrest
@@ -106,7 +106,7 @@ class ObjectTracer < Tracer::Base
                 out tp,
                     " #{colorized_target_label} is used as a parameter in #{colorized_name} of #{method_info}",
                     location: caller_locations(internal_depth, 1).first,
-                    depth: caller.size - internal_depth
+                    depth: caller.size - internal_depth - @depth_offset
               end
             end
           end

data/lib/ruby_tracer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tracer
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/ruby_tracer.rb

@@ -5,3 +5,28 @@ require_relative "ruby_tracer/line_tracer"
 require_relative "ruby_tracer/call_tracer"
 require_relative "ruby_tracer/exception_tracer"
 require_relative "ruby_tracer/object_tracer"
+
+module Tracer
+  module Helper
+    DEPTH_OFFSET = 3
+
+    def trace_exception(&block)
+      tracer = ExceptionTracer.new(depth_offset: DEPTH_OFFSET)
+      tracer.start(&block)
+    end
+
+    def trace_call(&block)
+      tracer = CallTracer.new(depth_offset: DEPTH_OFFSET)
+      tracer.start(&block)
+    end
+
+    def trace(target, &block)
+      tracer = ObjectTracer.new(target, depth_offset: DEPTH_OFFSET)
+      tracer.start(&block)
+    end
+  end
+
+  extend Helper
+end
+
+require_relative "ruby_tracer/irb"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_tracer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Stan Lo
@@ -29,6 +29,8 @@ files:
 - lib/ruby_tracer/call_tracer.rb
 - lib/ruby_tracer/color.rb
 - lib/ruby_tracer/exception_tracer.rb
+- lib/ruby_tracer/helper.rb
+- lib/ruby_tracer/irb.rb
 - lib/ruby_tracer/line_tracer.rb
 - lib/ruby_tracer/object_tracer.rb
 - lib/ruby_tracer/version.rb