tracer 0.2.1 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 13d3b55fac8c903711f78ccb14e872f8c312dde28dda5ed7f5fa664d04dd2a3b
4
- data.tar.gz: 71c21f53b34f98870d4e6b49c84432867375c24f56c3d3a4ebd47e4d6bdaeef5
3
+ metadata.gz: c764c7aa6783d3fb081718acd01a2cac909ea95bc8295206560469658cee5a80
4
+ data.tar.gz: 748f9c168bca973deee9b27e6b29b87e26e09c1bf190fdd09e8c38703498c8f6
5
5
  SHA512:
6
- metadata.gz: 54cb3be80359764539089df166a7ad922dea9ebea0cb8450a815f1956fbd780c3d6ed31bd5ea8e01cbf24689131c6463a5edb156220313b0c12e024f54d99565
7
- data.tar.gz: 683343e41cb7150fdd256c4427a4ca9971a87b592093721e5d3f00a40141136eeaf884a9242e7b20f46a0e47f35f445eede9c2b612731f12a38f5f1c20ad6c3a
6
+ metadata.gz: 0ce73f5cfcdaa82595d3abead931fa0d400025f87f7bf3e6f46bdc40856d9310b573f453c6096c40f0d47e326542801f4be849be9643bb877d03a0cfb5774abb
7
+ data.tar.gz: fe2b4c36c2b4ea19421fea09732dbc8c70323d7957fe9122d364f63c8cd453e0adb9b806856fed5f537994187c5f5df382623e244963ccb2f57da670a1dc5b92
data/Gemfile CHANGED
@@ -9,5 +9,3 @@ gem "rake", "~> 13.0"
9
9
  gem "irb"
10
10
 
11
11
  gem "test-unit", "~> 3.0"
12
-
13
- gem "ruby-lsp"
data/Gemfile.lock CHANGED
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- tracer (0.2.1)
4
+ tracer (0.2.2)
5
5
 
6
6
  GEM
7
7
  remote: https://rubygems.org/
@@ -9,19 +9,10 @@ GEM
9
9
  io-console (0.6.0)
10
10
  irb (1.6.2)
11
11
  reline (>= 0.3.0)
12
- language_server-protocol (3.17.0.3)
13
12
  power_assert (2.0.2)
14
- prettier_print (1.2.0)
15
13
  rake (13.0.6)
16
14
  reline (0.3.2)
17
15
  io-console (~> 0.5)
18
- ruby-lsp (0.3.8)
19
- language_server-protocol (~> 3.17.0)
20
- sorbet-runtime
21
- syntax_tree (>= 5.0.0, < 6)
22
- sorbet-runtime (0.5.10648)
23
- syntax_tree (5.3.0)
24
- prettier_print (>= 1.2.0)
25
16
  test-unit (3.5.5)
26
17
  power_assert
27
18
 
@@ -33,7 +24,6 @@ PLATFORMS
33
24
  DEPENDENCIES
34
25
  irb
35
26
  rake (~> 13.0)
36
- ruby-lsp
37
27
  test-unit (~> 3.0)
38
28
  tracer!
39
29
 
data/README.md CHANGED
@@ -1,6 +1,18 @@
1
1
  # Tracer
2
2
 
3
- 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.
3
+ [![Ruby](https://github.com/ruby/tracer/actions/workflows/main.yml/badge.svg)](https://github.com/ruby/tracer/actions/workflows/main.yml)
4
+ [![Gem Version](https://badge.fury.io/rb/tracer.svg)](https://badge.fury.io/rb/tracer)
5
+
6
+ The `tracer` gem provides helpful tracing utilities to help users observe their program's runtime behaviour.
7
+
8
+ The currently supported tracers are:
9
+
10
+ - [`ObjectTracer`](#objecttracer)
11
+ - [`CallTracer`](#calltracer)
12
+ - [`ExceptionTracer`](#exceptiontracer)
13
+ - [`LineTracer`](#linetracer)
14
+
15
+ It also comes with experimental [IRB integration](#irb-integration) to allow quick access from REPL.
4
16
 
5
17
  ## Installation
6
18
 
@@ -8,6 +20,14 @@ Tracer is an extraction of [`ruby/debug`](https://github.com/ruby/debug)'s [powe
8
20
  $ bundle add tracer --group=development,test
9
21
  ```
10
22
 
23
+ Or directly add it to your `Gemfile`
24
+
25
+ ```rb
26
+ group :development, :test do
27
+ gem "tracer"
28
+ end
29
+ ```
30
+
11
31
  If bundler is not being used to manage dependencies, install the gem by executing:
12
32
 
13
33
  ```shell
@@ -54,49 +74,6 @@ trace_call { ... } # trace method calls in the given block
54
74
  trace_exception { ... } # trace exceptions in the given block
55
75
  ```
56
76
 
57
- ### IRB-integration
58
-
59
- Once required, `tracer` registers a few IRB commands to help you trace Ruby expressions:
60
-
61
- ```
62
- trace Trace the target object (or self) in the given expression. Usage: `trace [target,] <expression>`
63
- trace_call Trace method calls in the given expression. Usage: `trace_call <expression>`
64
- trace_exception Trace exceptions in the given expression. Usage: `trace_exception <expression>`
65
- ```
66
-
67
- **Example**
68
-
69
- ```rb
70
- # test.rb
71
- require "tracer"
72
-
73
- obj = Object.new
74
-
75
- def obj.foo
76
- 100
77
- end
78
-
79
- def bar(obj)
80
- obj.foo
81
- end
82
-
83
- binding.irb
84
- ```
85
-
86
-
87
- ```
88
- irb(main):001:0> trace obj, bar(obj)
89
- #depth:23 #<Object:0x0000000107a86648> is used as a parameter obj of Object#bar at (eval):1:in `<main>'
90
- #depth:24 #<Object:0x0000000107a86648> receives .foo at test.rb:10:in `bar'
91
- => 100
92
- irb(main):002:0> trace_call bar(obj)
93
- #depth:23> Object#bar at (eval):1:in `<main>'
94
- #depth:24> #<Object:0x0000000107a86648>.foo at test.rb:10:in `bar'
95
- #depth:24< #<Object:0x0000000107a86648>.foo #=> 100 at test.rb:10:in `bar'
96
- #depth:23< Object#bar #=> 100 at (eval):1:in `<main>'
97
- => 100
98
- ```
99
-
100
77
  ### Tracer Classes
101
78
 
102
79
  If you want to have more control over individual traces, you can use individual tracer classes:
@@ -197,13 +174,56 @@ end
197
174
  #depth:5 at test.rb:8
198
175
  ```
199
176
 
177
+ ### IRB-integration
178
+
179
+ Once required, `tracer` registers a few IRB commands to help you trace Ruby expressions:
180
+
181
+ ```
182
+ trace Trace the target object (or self) in the given expression. Usage: `trace [target,] <expression>`
183
+ trace_call Trace method calls in the given expression. Usage: `trace_call <expression>`
184
+ trace_exception Trace exceptions in the given expression. Usage: `trace_exception <expression>`
185
+ ```
186
+
187
+ **Example**
188
+
189
+ ```rb
190
+ # test.rb
191
+ require "tracer"
192
+
193
+ obj = Object.new
194
+
195
+ def obj.foo
196
+ 100
197
+ end
198
+
199
+ def bar(obj)
200
+ obj.foo
201
+ end
202
+
203
+ binding.irb
204
+ ```
205
+
206
+ ```shell
207
+ irb(main):001:0> trace obj, bar(obj)
208
+ #depth:23 #<Object:0x0000000107a86648> is used as a parameter obj of Object#bar at (eval):1:in `<main>'
209
+ #depth:24 #<Object:0x0000000107a86648> receives .foo at test.rb:10:in `bar'
210
+ => 100
211
+ irb(main):002:0> trace_call bar(obj)
212
+ #depth:23> Object#bar at (eval):1:in `<main>'
213
+ #depth:24> #<Object:0x0000000107a86648>.foo at test.rb:10:in `bar'
214
+ #depth:24< #<Object:0x0000000107a86648>.foo #=> 100 at test.rb:10:in `bar'
215
+ #depth:23< Object#bar #=> 100 at (eval):1:in `<main>'
216
+ => 100
217
+ ```
218
+
200
219
  ## Customization
201
220
 
202
221
  TBD
203
222
 
204
- ## Acknowledgement
223
+ ## Acknowledgements
205
224
 
206
- [@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.
225
+ A big shout-out to [@ko1](https://github.com/ko1) (Koichi Sasada) for his awesome work on [`ruby/debug`](https://github.com/ruby/debug).
226
+ 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.
207
227
 
208
228
  ## Development
209
229
 
data/lib/tracer/base.rb CHANGED
@@ -70,12 +70,21 @@ module Tracer
70
70
  end
71
71
  end
72
72
 
73
- def initialize(output: STDOUT, pattern: nil, colorize: nil, depth_offset: 0)
73
+ attr_reader :header
74
+
75
+ def initialize(
76
+ output: STDOUT,
77
+ pattern: nil,
78
+ colorize: nil,
79
+ depth_offset: 0,
80
+ header: nil
81
+ )
74
82
  @name = self.class.name
75
83
  @type = @name.sub(/Tracer\z/, "")
76
84
  @output = output
77
85
  @depth_offset = depth_offset
78
86
  @colorize = colorize || colorizable?
87
+ @header = header
79
88
 
80
89
  if pattern
81
90
  @pattern = Regexp.compile(pattern)
@@ -90,10 +99,6 @@ module Tracer
90
99
  [@type, @pattern, @into].freeze
91
100
  end
92
101
 
93
- def header
94
- ""
95
- end
96
-
97
102
  def to_s
98
103
  s = "#{@name} #{description}"
99
104
  s += " with pattern #{@pattern.inspect}" if @pattern
@@ -141,10 +146,14 @@ module Tracer
141
146
 
142
147
  def out(tp, msg = nil, depth: caller.size - 1, location: nil)
143
148
  location ||= "#{tp.path}:#{tp.lineno}"
144
- buff =
145
- "#{header} \#depth:#{"%-2d" % depth}#{msg} at #{colorize("#{location}", [:GREEN])}"
149
+ if header
150
+ str = +"#{header} "
151
+ else
152
+ str = +""
153
+ end
154
+ str << "\#depth:#{"%-2d" % depth}#{msg} at #{colorize("#{location}", [:GREEN])}"
146
155
 
147
- puts buff
156
+ puts str
148
157
  end
149
158
 
150
159
  def puts(msg)
data/lib/tracer/irb.rb CHANGED
@@ -1,7 +1,15 @@
1
- require_relative "../tracer"
2
1
  require "irb/cmd/nop"
3
2
  require "irb"
4
3
 
4
+ if Gem::Version.new(IRB::VERSION) < Gem::Version.new("1.6.0")
5
+ warn <<~MSG
6
+ Your version of IRB is too old so Tracer cannot register its commands.
7
+ Please upgrade IRB by adding `gem "irb", "~> 1.6.0"` to your Gemfile.
8
+ MSG
9
+
10
+ return
11
+ end
12
+
5
13
  module Tracer
6
14
  def self.register_irb_commands
7
15
  ec = IRB::ExtendCommandBundle.instance_variable_get(:@EXTEND_COMMANDS)
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Tracer
4
- VERSION = "0.2.1"
4
+ VERSION = "0.2.2"
5
5
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: tracer
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.1
4
+ version: 0.2.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Stan Lo
@@ -9,7 +9,7 @@ authors:
9
9
  autorequire:
10
10
  bindir: exe
11
11
  cert_chain: []
12
- date: 2023-05-19 00:00:00.000000000 Z
12
+ date: 2023-05-28 00:00:00.000000000 Z
13
13
  dependencies: []
14
14
  description: A Ruby tracer
15
15
  email: