tracer 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f040d7e0181c8be3aa0d41e5be786aca6d3632c1367b6180a3cfc2b19bda57bf
-  data.tar.gz: 43143d936ab079338c0039718c021f6c9d50d8ac93ba5a1a90320eeed466eaf1
+  metadata.gz: c764c7aa6783d3fb081718acd01a2cac909ea95bc8295206560469658cee5a80
+  data.tar.gz: 748f9c168bca973deee9b27e6b29b87e26e09c1bf190fdd09e8c38703498c8f6
 SHA512:
-  metadata.gz: 51e73efd3fc7eea7b783f797f6afa67b1d7cee068383e36e076046a17462d1a7f36b58b85150bcbb700f0b7c24214b5893039241bfc16c27cc72f9fea4e6665b
-  data.tar.gz: 8cb8b671a2e630a0f03b1485f858320ccd7bcb260a06c41dbb373342774377c6911335d78e50f7f473b4722df24f070e8409c02c9ce3223455c001aaff08a8e8
+  metadata.gz: 0ce73f5cfcdaa82595d3abead931fa0d400025f87f7bf3e6f46bdc40856d9310b573f453c6096c40f0d47e326542801f4be849be9643bb877d03a0cfb5774abb
+  data.tar.gz: fe2b4c36c2b4ea19421fea09732dbc8c70323d7957fe9122d364f63c8cd453e0adb9b806856fed5f537994187c5f5df382623e244963ccb2f57da670a1dc5b92

data/Gemfile

@@ -9,5 +9,3 @@ gem "rake", "~> 13.0"
 gem "irb"
 
 gem "test-unit", "~> 3.0"
-
-gem "ruby-lsp"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    tracer (0.2.0)
+    tracer (0.2.2)
 
 GEM
   remote: https://rubygems.org/
@@ -9,19 +9,10 @@ GEM
     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
 
@@ -33,7 +24,6 @@ PLATFORMS
 DEPENDENCIES
   irb
   rake (~> 13.0)
-  ruby-lsp
   test-unit (~> 3.0)
   tracer!
 

data/README.md

@@ -1,6 +1,18 @@
 # 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)
+- [`CallTracer`](#calltracer)
+- [`ExceptionTracer`](#exceptiontracer)
+- [`LineTracer`](#linetracer)
+
+It also comes with experimental [IRB integration](#irb-integration) to allow quick access from REPL.
 
 ## Installation
 
@@ -8,6 +20,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 +74,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:
@@ -197,13 +174,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

@@ -70,12 +70,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 +99,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 +146,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/irb.rb

@@ -1,6 +1,15 @@
 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)
@@ -46,6 +55,11 @@ module IRB
       description "Trace the target object (or self) in the given expression. Usage: `trace [target,] <expression>`"
 
       def execute(*args)
+        if args.empty?
+          puts "Please provide the expression to trace. Usage: `trace [target,] <expression>`"
+          return
+        end
+
         args = args.first.split(/,/, 2)
 
         case args.size
@@ -56,8 +70,13 @@ module IRB
           target = eval(args.first, irb_context.workspace.binding)
           expression = args.last
         else
-          raise ArgumentError,
-                "wrong number of arguments (given #{args.size}, expected 1..2)"
+          puts "Please provide the expression to trace. Usage: `trace [target,] <expression>`"
+          return
+        end
+
+        unless expression
+          puts "Please provide the expression to trace. Usage: `trace [target,] <expression>`"
+          return
         end
 
         b = irb_context.workspace.binding
@@ -69,7 +88,14 @@ module IRB
       category "Tracing"
       description "Trace method calls in the given expression. Usage: `trace_call <expression>`"
 
-      def execute(expression)
+      def execute(*args)
+        expression = args.first
+
+        unless expression
+          puts "Please provide the expression to trace. Usage: `trace_call <expression>`"
+          return
+        end
+
         b = irb_context.workspace.binding
         Tracer.trace_call { eval(expression, b) }
       end
@@ -79,7 +105,14 @@ module IRB
       category "Tracing"
       description "Trace exceptions in the given expression. Usage: `trace_exception <expression>`"
 
-      def execute(expression)
+      def execute(*args)
+        expression = args.first
+
+        unless expression
+          puts "Please provide the expression to trace. Usage: `trace_exception <expression>`"
+          return
+        end
+
         b = irb_context.workspace.binding
         Tracer.trace_exception { eval(expression, b) }
       end

data/lib/tracer/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tracer
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 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: 2023-05-28 00:00:00.000000000 Z
 dependencies: []
 description: A Ruby tracer
 email: