tracer 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13d3b55fac8c903711f78ccb14e872f8c312dde28dda5ed7f5fa664d04dd2a3b
-  data.tar.gz: 71c21f53b34f98870d4e6b49c84432867375c24f56c3d3a4ebd47e4d6bdaeef5
+  metadata.gz: 2384a62a824cb7906cd027700d16844a6b666e5dc7b04749fcb2d69ece9a2a85
+  data.tar.gz: 762568e03d81d9dafa2ad6735f9901d53507aaeaa350aac53ef3989325136757
 SHA512:
-  metadata.gz: 54cb3be80359764539089df166a7ad922dea9ebea0cb8450a815f1956fbd780c3d6ed31bd5ea8e01cbf24689131c6463a5edb156220313b0c12e024f54d99565
-  data.tar.gz: 683343e41cb7150fdd256c4427a4ca9971a87b592093721e5d3f00a40141136eeaf884a9242e7b20f46a0e47f35f445eede9c2b612731f12a38f5f1c20ad6c3a
+  metadata.gz: bbdccfb4cf5054d554a76e22f9bbffd21aa8f3e9a13e366cbfb41d076803c4de4b019697b81d8dd1278655390f7c1949190e7d7c72b2fcdc7ffa83622b89a71d
+  data.tar.gz: b0a8142e250b24964d9fbcbc674d052107061725b6673b7d573553faf55afc722559396c0b878f3639c051dcfd1a9794e285116ba38e2f493d4be9b8d17c11ae

data/README.md

@@ -1,6 +1,19 @@
 # Tracer
 
-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 some improvements.
+[![Ruby](https://github.com/ruby/tracer/actions/workflows/main.yml/badge.svg)](https://github.com/ruby/tracer/actions/workflows/main.yml)
+[![Gem Version](https://badge.fury.io/rb/tracer.svg)](https://badge.fury.io/rb/tracer)
+
+The `tracer` gem provides helpful tracing utilities to help users observe their program's runtime behaviour.
+
+The currently supported tracers are:
+
+- [`ObjectTracer`](#objecttracer)
+- [`IvarTracer`](#ivartracer)
+- [`CallTracer`](#calltracer)
+- [`ExceptionTracer`](#exceptiontracer)
+- [`LineTracer`](#linetracer)
+
+It also comes with experimental [IRB integration](#irb-integration) to allow quick access from REPL.
 
 ## Installation
 
@@ -8,6 +21,14 @@ Tracer is an extraction of [`ruby/debug`](https://github.com/ruby/debug)'s [powe
 $ bundle add tracer --group=development,test
 ```
 
+Or directly add it to your `Gemfile`
+
+```rb
+group :development, :test do
+  gem "tracer"
+end
+```
+
 If bundler is not being used to manage dependencies, install the gem by executing:
 
 ```shell
@@ -54,49 +75,6 @@ trace_call { ... } # trace method calls in the given block
 trace_exception { ... } # trace exceptions in the given block
 ```
 
-### IRB-integration
-
-Once required, `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 "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:
@@ -126,6 +104,30 @@ end
  #depth:4  #<User:0x000000010696cad8 @name="John"> receives #name (User#name) at test.rb:8:in `authorized?'
 ```
 
+#### IvarTracer
+
+> **Note**
+> Ruby 3.0 and below's accessor calls don't trigger TracePoint properly so the result may be inaccurate with those versions.
+
+```rb
+require "tracer"
+
+class Cat
+  attr_accessor :name
+end
+
+cat = Cat.new
+
+tracer = IvarTracer.new(cat, :@name)
+tracer.start do
+  cat.name = "Kitty"
+  cat.instance_variable_set(:@name, "Ketty")
+end
+
+#depth:3 Cat#name= sets @name = "Kitty" at test.rb:11
+#depth:3 Kernel#instance_variable_set sets @name = "Ketty" at test.rb:12
+```
+
 #### ExceptionTracer
 
 ```rb
@@ -137,7 +139,8 @@ rescue StandardError
   nil
 end
 
- #depth:1  #<RuntimeError: boom> at test.rb:4
+#depth:0  #<RuntimeError: boom> raised at test.rb:4
+#depth:1  #<RuntimeError: boom> rescued at test.rb:6
 ```
 
 #### CallTracer
@@ -197,13 +200,56 @@ end
  #depth:5  at test.rb:8
 ```
 
+### IRB-integration
+
+Once required, `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 "tracer"
+
+obj = Object.new
+
+def obj.foo
+  100
+end
+
+def bar(obj)
+  obj.foo
+end
+
+binding.irb
+```
+
+```shell
+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
+```
+
 ## Customization
 
 TBD
 
-## Acknowledgement
+## Acknowledgements
 
-[@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.
+A big shout-out to [@ko1](https://github.com/ko1) (Koichi Sasada) for his awesome work on [`ruby/debug`](https://github.com/ruby/debug).
+The [cool tracers in `ruby/debug`](https://github.com/ruby/debug/blob/master/lib/debug/tracer.rb) were an inspiration and laid the groundwork for this project.
 
 ## Development
 

data/lib/tracer/base.rb

@@ -10,6 +10,7 @@ module Tracer
     M_INSPECT = Object.instance_method(:inspect)
     M_CLASS = Object.instance_method(:class)
     M_IS_A = Object.instance_method(:is_a?)
+    M_INSTANCE_VARIABLE_GET = Object.instance_method(:instance_variable_get)
     HOME = ENV["HOME"] ? (ENV["HOME"] + "/") : nil
 
     include Color
@@ -70,12 +71,21 @@ module Tracer
       end
     end
 
-    def initialize(output: STDOUT, pattern: nil, colorize: nil, depth_offset: 0)
+    attr_reader :header
+
+    def initialize(
+      output: STDOUT,
+      pattern: nil,
+      colorize: nil,
+      depth_offset: 0,
+      header: nil
+    )
       @name = self.class.name
       @type = @name.sub(/Tracer\z/, "")
       @output = output
       @depth_offset = depth_offset
       @colorize = colorize || colorizable?
+      @header = header
 
       if pattern
         @pattern = Regexp.compile(pattern)
@@ -90,10 +100,6 @@ module Tracer
       [@type, @pattern, @into].freeze
     end
 
-    def header
-      ""
-    end
-
     def to_s
       s = "#{@name} #{description}"
       s += " with pattern #{@pattern.inspect}" if @pattern
@@ -141,10 +147,14 @@ module Tracer
 
     def out(tp, msg = nil, depth: caller.size - 1, location: nil)
       location ||= "#{tp.path}:#{tp.lineno}"
-      buff =
-        "#{header} \#depth:#{"%-2d" % depth}#{msg} at #{colorize("#{location}", [:GREEN])}"
+      if header
+        str = +"#{header} "
+      else
+        str = +""
+      end
+      str << "\#depth:#{"%-2d" % depth}#{msg} at #{colorize("#{location}", [:GREEN])}"
 
-      puts buff
+      puts str
     end
 
     def puts(msg)

data/lib/tracer/exception_tracer.rb

@@ -4,16 +4,32 @@ require_relative "base"
 
 class ExceptionTracer < Tracer::Base
   def setup_tp
-    TracePoint.new(:raise) do |tp|
-      next if skip?(tp)
+    if RUBY_VERSION >= "3.3.0"
+      TracePoint.new(:raise, :rescue) do |tp|
+        next if skip?(tp)
 
-      exc = tp.raised_exception
+        exc = tp.raised_exception
 
-      out tp,
-          " #{colorize_magenta(exc.inspect)}",
-          depth: caller.size - (1 + @depth_offset)
-    rescue Exception => e
-      p e
+        action = tp.event == :raise ? "raised" : "rescued"
+
+        out tp,
+            " #{colorize_magenta(exc.inspect)} #{action}",
+            depth: caller.size - (1 + @depth_offset)
+      rescue Exception => e
+        p e
+      end
+    else
+      TracePoint.new(:raise) do |tp|
+        next if skip?(tp)
+
+        exc = tp.raised_exception
+
+        out tp,
+            " #{colorize_magenta(exc.inspect)} raised",
+            depth: caller.size - (1 + @depth_offset)
+      rescue Exception => e
+        p e
+      end
     end
   end
 

data/lib/tracer/irb.rb

@@ -1,7 +1,15 @@
-require_relative "../tracer"
 require "irb/cmd/nop"
 require "irb"
 
+if Gem::Version.new(IRB::VERSION) < Gem::Version.new("1.6.0")
+  warn <<~MSG
+    Your version of IRB is too old so Tracer cannot register its commands.
+    Please upgrade IRB by adding `gem "irb", "~> 1.6.0"` to your Gemfile.
+  MSG
+
+  return
+end
+
 module Tracer
   def self.register_irb_commands
     ec = IRB::ExtendCommandBundle.instance_variable_get(:@EXTEND_COMMANDS)

data/lib/tracer/ivar_tracer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class IvarTracer < Tracer::Base
+  def initialize(target, var_name, **kw)
+    @target = target
+    @var_name = var_name
+    @original_value = M_INSTANCE_VARIABLE_GET.bind_call(target, var_name)
+    super(**kw)
+  end
+
+  def key
+    [@type, @target, @var_name, @pattern, @into].freeze
+  end
+
+  def description
+    "for #{@var_name} of #{@target} #{super}"
+  end
+
+  def setup_tp
+    TracePoint.new(:a_return) do |tp|
+      next if skip?(tp)
+
+      if tp.self == @target &&
+           value = M_INSTANCE_VARIABLE_GET.bind_call(@target, @var_name)
+        if tp.event == :c_return
+          location = nil
+        else
+          location = caller_locations(2, 1).first.to_s
+          next if location.match?(DIR) || location.match?(/<internal:/)
+        end
+
+        depth = caller.size
+        call_identifier_str = (tp.defined_class ? minfo(tp) : "block")
+        call_identifier_str = colorize_blue(call_identifier_str)
+        depth += 1 if tp.event == :c_return
+        value = safe_inspect(value)
+
+        if value != @original_value
+          out tp,
+              "#{call_identifier_str} sets #{colorize_cyan(@var_name)} = #{colorize_magenta(value)}",
+              depth: depth - 2 - @depth_offset,
+              location: location
+        end
+      end
+    end
+  end
+end

data/lib/tracer/version.rb

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

data/lib/tracer.rb

@@ -5,6 +5,7 @@ require_relative "tracer/line_tracer"
 require_relative "tracer/call_tracer"
 require_relative "tracer/exception_tracer"
 require_relative "tracer/object_tracer"
+require_relative "tracer/ivar_tracer"
 
 module Tracer
   module Helper

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tracer
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - Stan Lo
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-05-19 00:00:00.000000000 Z
+date: 2024-03-22 00:00:00.000000000 Z
 dependencies: []
 description: A Ruby tracer
 email:
@@ -21,11 +21,8 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
-- Gemfile
-- Gemfile.lock
 - LICENSE.txt
 - README.md
-- Rakefile
 - lib/tracer.rb
 - lib/tracer/base.rb
 - lib/tracer/call_tracer.rb
@@ -33,10 +30,10 @@ files:
 - lib/tracer/exception_tracer.rb
 - lib/tracer/helper.rb
 - lib/tracer/irb.rb
+- lib/tracer/ivar_tracer.rb
 - lib/tracer/line_tracer.rb
 - lib/tracer/object_tracer.rb
 - lib/tracer/version.rb
-- tracer.gemspec
 homepage: https://github.com/ruby/tracer
 licenses:
 - Ruby
@@ -60,7 +57,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.4
 signing_key:
 specification_version: 4
 summary: A Ruby tracer

data/Gemfile

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-source "https://rubygems.org"
-
-# Specify your gem's dependencies in ruby-tracer.gemspec
-gemspec
-
-gem "rake", "~> 13.0"
-gem "irb"
-
-gem "test-unit", "~> 3.0"
-
-gem "ruby-lsp"

data/Gemfile.lock

@@ -1,41 +0,0 @@
-PATH
-  remote: .
-  specs:
-    tracer (0.2.1)
-
-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
-      syntax_tree (>= 5.0.0, < 6)
-    sorbet-runtime (0.5.10648)
-    syntax_tree (5.3.0)
-      prettier_print (>= 1.2.0)
-    test-unit (3.5.5)
-      power_assert
-
-PLATFORMS
-  arm64-darwin-21
-  arm64-darwin-22
-  x86_64-linux
-
-DEPENDENCIES
-  irb
-  rake (~> 13.0)
-  ruby-lsp
-  test-unit (~> 3.0)
-  tracer!
-
-BUNDLED WITH
-   2.4.2

data/Rakefile

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rake/testtask"
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
-end
-
-task default: :test

data/tracer.gemspec

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/tracer/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "tracer"
-  spec.version = Tracer::VERSION
-  spec.authors = ["Stan Lo", "Keiju ISHITSUKA"]
-  spec.email = %w[stan001212@gmail.com keiju@ruby-lang.org]
-
-  spec.summary = "A Ruby tracer"
-  spec.description = "A Ruby tracer"
-  spec.homepage = "https://github.com/ruby/tracer"
-  spec.licenses = %w[Ruby BSD-2-Clause]
-  spec.required_ruby_version = ">= 2.7.0"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/ruby/tracer"
-  spec.metadata[
-    "changelog_uri"
-  ] = "https://github.com/ruby/tracer/blob/main/CHANGELOG.md"
-
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files =
-    Dir.chdir(__dir__) do
-      `git ls-files -z`.split("\x0")
-        .reject do |f|
-          (f == __FILE__) ||
-            f.match(
-              %r{\A(?:(?:bin|test|spec|features)/|\.(?:git|circleci)|appveyor)}
-            )
-        end
-    end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  # Uncomment to register a new dependency of your gem
-
-  # For more information and examples about making a new gem, check out our
-  # guide at: https://bundler.io/guides/creating_gem.html
-end