ruby_tracer 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed2853558a9d7a761617ee215d7f46c9b146cdb4fcb431564052f0330d84069a
-  data.tar.gz: ad54ea0f5958215ea2271f782354539cf74907af3a53bb16cc6ce7412007eceb
+  metadata.gz: 0ac708e995302930fed59fa3b9396dc5b3c45ab76d4306c8bbac65fe69c49377
+  data.tar.gz: 99f23f4e5fb2d5f8ae694ff1203524707c757fd5a91cd29131ac61e79c5cb15f
 SHA512:
-  metadata.gz: e38ef5d999c9a01a32148cc6f5709fac2b6d19430ab345823dfa7896ec37a6349f759552623ae47e6c12d61dabddde71cc9647d1ffd3213d2457bacbdff90363
-  data.tar.gz: ae263df3f94d33ae886e4d1966fc06265349839f05b9fd8538e48f81e3b7d9cb4ab7c84ae0c8299567f031480d0d53c03d645e2e97351fc7f41b64c3ad14de58
+  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.2.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
 
@@ -62,9 +54,54 @@ 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
+#### ObjectTracer
 
 ```rb
 class User
@@ -89,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
@@ -103,7 +140,7 @@ end
  #depth:1  #<RuntimeError: boom> at test.rb:4
 ```
 
-### CallTracer
+#### CallTracer
 
 ```rb
 class User
@@ -135,7 +172,7 @@ end
  #depth:4 <    block #=> true at test.rb:16
 ```
 
-### LineTracer
+#### LineTracer
 
 ```rb
 class User

data/lib/ruby_tracer/call_tracer.rb

@@ -7,8 +7,8 @@ class CallTracer < Tracer::Base
     TracePoint.new(:a_call, :a_return) do |tp|
       next if skip?(tp)
 
-      location = caller_locations(2, 1).first
-      next if location.to_s.match?(/<internal:/)
+      location = caller_locations(2, 1).first.to_s
+      next if location.match?(DIR) || location.match?(/<internal:/)
 
       depth = caller.size
 

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/version.rb

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

data/lib/ruby_tracer.rb

@@ -28,3 +28,5 @@ module Tracer
 
   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.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Stan Lo
@@ -30,6 +30,7 @@ files:
 - 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