tracer 0.2.1 → 0.2.2

Sign up to get free protection for your applications and to get access to all the features.
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: