im-lost 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39160aff2b7fa8320ae12c5d035fa40fbf6f96a2fbe0418ddfb31ac700c2bf72
-  data.tar.gz: 044bf4b9b4f9288f418b0cc5344cc82d1a88839d08a8ef1b8008d616ef11481c
+  metadata.gz: 8b3508c022462842507ce749828e2c74c4db9e9097496e68cedc758018017cb5
+  data.tar.gz: 93ac54d98ae6474d4f7144b116cf0e2784c88babf57ff592a317b463caa7ee13
 SHA512:
-  metadata.gz: 5d76261aafb61289cf56c23fb2acb0c0e6a0b8cc834b4e28b72d80cf0f6dfdf7966a8b613c7a0f4e8ee005eae2ba4064fe9aeb7b7520cbd53ce8e99671e33f0f
-  data.tar.gz: da598803cf6e2ee4e4baa92f8e702796050f279645daf80fccffa16c2be2eaa314cee7a69742691dde5d798f44f75d610dcb7db71d223a72c0fcabb2e65c7030
+  metadata.gz: 4d45f27c98a6ed477ce4e696f4c41286ca24c105de1668889bf64fc0d57d3947e04c026b40fa7f5f79e2ce5016fcc8327e3c9a8b20a1e6ae0561900efae4f5f3
+  data.tar.gz: 1502147a826924c39988f9272d62e3c0274dc8cdb961f25c405a229cf6273142579ad136af1972c06874d13af110486b79db45907c219bd3082a91cd507220ab

data/README.md

@@ -20,14 +20,14 @@ File.open('test.txt', 'w') do |file|
   end
 end
 # output will look like
-#   > IO#<<(?)
-#     /projects/test.rb:1
-#   > IO#write(*)
-#     /projects/test.rb:1
-#   > IO#puts(*)
-#     /projects/test.rb:2
-#   > IO#write(*)
-#     /projects/test.rb:2
+#  > IO#<<(?)
+#    /projects/test.rb:1
+#  > IO#write(*)
+#    /projects/test.rb:1
+#  > IO#puts(*)
+#    /projects/test.rb:2
+#  > IO#write(*)
+#    /projects/test.rb:2
 ```
 
 When you need to know if exceptions are raised and handled you can use `ImLost.trace_exceptions`:
@@ -39,12 +39,12 @@ rescue SystemCallError
   raise('something went wrong!')
 end
 # output will look like
-#   x Errno::EEXIST: File exists @ rb_sysopen - /
-#   /projects/test.rb:2
-#   ! Errno::EEXIST: File exists @ rb_sysopen - /
-#   /projects/test.rb:3
-#   x RuntimeError: something went wrong!
-#   /projects/test.rb:4
+#  x Errno::EEXIST: File exists @ rb_sysopen - /
+#    /projects/test.rb:2
+#  ! Errno::EEXIST: File exists @ rb_sysopen - /
+#    /projects/test.rb:3
+#  x RuntimeError: something went wrong!
+#    /projects/test.rb:4
 ```
 
 When you like to know if and when a code point is reached, `ImLost.here` will help:
@@ -53,11 +53,28 @@ When you like to know if and when a code point is reached, `ImLost.here` will he
 ImLost.here
 ```
 
+If you like to know the instance variables values of an object, use
+`ImLost.vars`:
+
+```ruby
+ImLost.vars(self)
+```
+
+Or you can print the current local variables:
+
+```ruby
+ImLost.vars(binding)
+```
+
+See the [online help](https://rubydoc.info/gems/im-lost/ImLost) for more!
+
 ## Example
 
 ```ruby
 require 'im-lost'
 
+require_relative '../lib/im-lost'
+
 class Foo
   def self.create(value:) = new(value)
 
@@ -82,8 +99,13 @@ my_foo = Foo.create(value: :foo!)
 ImLost.trace(my_foo)
 
 my_foo.foo(1, key: :none)
+ImLost.vars(my_foo)
+
 my_foo.foo(2, :a, :b, :c, key: :some, name: :value)
+ImLost.vars(my_foo)
+
 my_foo.foo(3) { puts _1 }
+ImLost.vars(my_foo)
 
 # output will look like
 #   > Foo.create(:foo!)
@@ -91,9 +113,9 @@ my_foo.foo(3) { puts _1 }
 #   > Foo.new(*)
 #     /projects/foo.rb:6
 #   < Foo.new(*)
-#     = #<Foo:0x0000000100902418 @value=:foo!>
+#     = #<Foo:0x00000001030810c0 @value=:foo!>
 #   < Foo.create(:foo!)
-#     = #<Foo:0x0000000100902418 @value=:foo!>
+#     = #<Foo:0x00000001030810c0 @value=:foo!>
 #   > Foo#foo(1, *[], :none, **{}, &nil)
 #     /projects/foo.rb:28
 #   > Foo#bar()
@@ -102,23 +124,32 @@ my_foo.foo(3) { puts _1 }
 #     = :bar
 #   < Foo#foo(1, *[], :none, **{}, &nil)
 #     = "1-none-[]-{}-bar"
+#   = /projects/foo.rb:29
+#     instance variables:
+#     @value: "1-none-[]-{}-bar"
 #   > Foo#foo(2, *[:a, :b, :c], :some, **{:name=>:value}, &nil)
-#     /projects/foo.rb:29
+#     /projects/foo.rb:31
 #   > Foo#bar()
 #     /projects/foo.rb:15
 #   < Foo#bar()
 #     = :bar
 #   < Foo#foo(2, *[:a, :b, :c], :some, **{:name=>:value}, &nil)
 #     = "2-some-[a,b,c]-{:name=>:value}-bar"
-#   > Foo#foo(3, *[], nil, **{}, &#<Proc:0x0000000100900578 /projects/foo.rb:30>)
-#     /projects/foo.rb:30
+#   = /projects/foo.rb:32
+#     instance variables:
+#     @value: "2-some-[a,b,c]-{:name=>:value}-bar"
+#   > Foo#foo(3, *[], nil, **{}, &#<Proc:0x00000001030aee30 /projects/foo.rb:34>)
+#     /projects/foo.rb:34
 #   > Foo#bar()
 #     /projects/foo.rb:15
 #   < Foo#bar()
 #     = :bar
 #   3--[]-{}-bar
-#   < Foo#foo(3, *[], nil, **{}, &#<Proc:0x0000000100900578 /projects/foo.rb:30>)
+#   < Foo#foo(3, *[], nil, **{}, &#<Proc:0x00000001030aee30 /projects/foo.rb:34>)
 #     = nil
+#   = /projects/foo.rb:35
+#     instance variables:
+#     @value: "3--[]-{}-bar"
 ```
 
 See [examples dir](./examples) for more…

data/examples/foo.rb

@@ -26,8 +26,13 @@ my_foo = Foo.create(value: :foo!)
 ImLost.trace(my_foo)
 
 my_foo.foo(1, key: :none)
+ImLost.vars(my_foo)
+
 my_foo.foo(2, :a, :b, :c, key: :some, name: :value)
+ImLost.vars(my_foo)
+
 my_foo.foo(3) { puts _1 }
+ImLost.vars(my_foo)
 
 # output will look like
 #   > Foo.create(:foo!)
@@ -35,9 +40,9 @@ my_foo.foo(3) { puts _1 }
 #   > Foo.new(*)
 #     /projects/foo.rb:6
 #   < Foo.new(*)
-#     = #<Foo:0x0000000100902418 @value=:foo!>
+#     = #<Foo:0x00000001030810c0 @value=:foo!>
 #   < Foo.create(:foo!)
-#     = #<Foo:0x0000000100902418 @value=:foo!>
+#     = #<Foo:0x00000001030810c0 @value=:foo!>
 #   > Foo#foo(1, *[], :none, **{}, &nil)
 #     /projects/foo.rb:28
 #   > Foo#bar()
@@ -46,20 +51,29 @@ my_foo.foo(3) { puts _1 }
 #     = :bar
 #   < Foo#foo(1, *[], :none, **{}, &nil)
 #     = "1-none-[]-{}-bar"
+#   = /projects/foo.rb:29
+#     instance variables:
+#     @value: "1-none-[]-{}-bar"
 #   > Foo#foo(2, *[:a, :b, :c], :some, **{:name=>:value}, &nil)
-#     /projects/foo.rb:29
+#     /projects/foo.rb:31
 #   > Foo#bar()
 #     /projects/foo.rb:15
 #   < Foo#bar()
 #     = :bar
 #   < Foo#foo(2, *[:a, :b, :c], :some, **{:name=>:value}, &nil)
 #     = "2-some-[a,b,c]-{:name=>:value}-bar"
-#   > Foo#foo(3, *[], nil, **{}, &#<Proc:0x0000000100900578 /projects/foo.rb:30>)
-#     /projects/foo.rb:30
+#   = /projects/foo.rb:32
+#     instance variables:
+#     @value: "2-some-[a,b,c]-{:name=>:value}-bar"
+#   > Foo#foo(3, *[], nil, **{}, &#<Proc:0x00000001030aee30 /projects/foo.rb:34>)
+#     /projects/foo.rb:34
 #   > Foo#bar()
 #     /projects/foo.rb:15
 #   < Foo#bar()
 #     = :bar
 #   3--[]-{}-bar
-#   < Foo#foo(3, *[], nil, **{}, &#<Proc:0x0000000100900578 /projects/foo.rb:30>)
+#   < Foo#foo(3, *[], nil, **{}, &#<Proc:0x00000001030aee30 /projects/foo.rb:34>)
 #     = nil
+#   = /projects/foo.rb:35
+#     instance variables:
+#     @value: "3--[]-{}-bar"

data/lib/im-lost/version.rb

@@ -2,5 +2,5 @@
 
 module ImLost
   # The version number of the gem.
-  VERSION = '1.0.0'
+  VERSION = '1.0.2'
 end

data/lib/im-lost.rb

@@ -1,5 +1,14 @@
 # frozen_string_literal: true
 
+# If you have overlooked something again and don't really understand what your
+# code is doing. If you have to maintain this application but can't really find
+# your way around and certainly can't track down that stupid error. If you feel
+# lost in all that code, here's the gem to help you out!
+#
+# ImLost helps you by analyzing function calls of objects, informing you about
+# exceptions and logging your way through your code. In short, ImLost is your
+# debugging helper!
+#
 module ImLost
   class << self
     #
@@ -226,6 +235,28 @@ module ImLost
       self
     end
 
+    #
+    # Inspect internal variables.
+    #
+    # @overload vars(binding)
+    #   Inspect local variables of given Binding.
+    #   @param binding [Binding] which local variables should be print
+    #   @return [self] itself
+    #
+    # @overload vars(object)
+    #   Inspect instance variables of given object.
+    #   @param object [Object] which instance variables should be print
+    #   @return [Object] the given object
+    #
+    def vars(object)
+      traced = @trace.delete(object.__id__)
+      return _local_vars(object) if object.is_a?(Binding)
+      return unless object.respond_to?(:instance_variables)
+      _vars(object, Kernel.caller_locations(1, 1)[0])
+    ensure
+      @trace[traced] = traced if traced
+    end
+
     protected
 
     def as_sig(prefix, info, args)
@@ -241,41 +272,73 @@ module ImLost
     private
 
     def _trace(arg)
-      @trace[arg.__id__] = 1 if self != arg && @output != arg
+      id = arg.__id__
+      @trace[id] = id if __id__ != id && @output.__id__ != id
       arg
     end
 
     def _trace_all(args)
       args.each do |arg|
-        @trace[arg.__id__] = 1 if arg != self && @output != arg
+        arg = arg.__id__
+        @trace[arg] = arg if __id__ != arg && @output.__id__ != arg
       end
       args
     end
 
     def _trace_b(arg)
-      @trace[id = arg.__id__] = 1 if self != arg && @output != arg
-      yield(arg)
-    ensure
-      @trace.delete(id) if id
+      id = arg.__id__
+      return yield(arg) if __id__ == id || @output.__id__ == id
+      begin
+        @trace[id] = id
+        yield(arg)
+      ensure
+        @trace.delete(id) if id
+      end
     end
 
     def _trace_all_b(args)
       ids =
         args.filter_map do |arg|
-          next if self == arg || @output == arg
-          @trace[id = arg.__id__] = 1
-          id
+          arg = arg.__id__
+          @trace[arg] = arg if __id__ != arg && @output.__id__ != arg
         end
       yield(args)
     ensure
       ids.each { @trace.delete(_1) }
     end
+
+    def _vars(obj, location)
+      @output.puts("= #{location.path}:#{location.lineno}")
+      vars = obj.instance_variables
+      if vars.empty?
+        @output.puts('  <no instance variables defined>')
+      else
+        @output.puts('  instance variables:')
+        vars.sort!.each do |name|
+          @output.puts("  #{name}: #{obj.instance_variable_get(name).inspect}")
+        end
+      end
+      obj
+    end
+
+    def _local_vars(binding)
+      @output.puts("= #{binding.source_location.join(':')}")
+      vars = binding.local_variables
+      if vars.empty?
+        @output.puts('  <no local variables>')
+      else
+        @output.puts('  local variables:')
+        vars.sort!.each do |name|
+          @output.puts("  #{name}: #{binding.local_variable_get(name).inspect}")
+        end
+      end
+      self
+    end
   end
 
   ARG_SIG = { rest: '*', keyrest: '**', block: '&' }.compare_by_identity.freeze
-  NO_NAME = %i[* ** &].freeze
-  EX_PREFIX = { raise: 'x', rescue: '!' }.freeze
-  private_constant :ARG_SIG, :NO_NAME, :EX_PREFIX
+  NO_NAME = { :* => 1, :** => 1, :& => 1 }.compare_by_identity.freeze
+  private_constant :ARG_SIG, :NO_NAME
 
   @trace = {}.compare_by_identity
   @caller_locations = true
@@ -283,19 +346,19 @@ module ImLost
 
   @trace_calls = [
     TracePoint.new(:c_call) do |tp|
-      next unless @trace.key?(tp.self.__id__)
+      next if !@trace.key?(tp.self.__id__) || tp.path == __FILE__
       @output.puts(as_sig('>', tp, tp.parameters.map { ARG_SIG[_1[0]] || '?' }))
       @output.puts("  #{tp.path}:#{tp.lineno}") if @caller_locations
     end,
     TracePoint.new(:call) do |tp|
-      next unless @trace.key?(tp.self.__id__)
+      next if !@trace.key?(tp.self.__id__) || tp.path == __FILE__
       ctx = tp.binding
       @output.puts(
         as_sig(
           '>',
           tp,
           tp.parameters.map do |kind, name|
-            next name if NO_NAME.include?(name)
+            next name if NO_NAME.key?(name)
             "#{ARG_SIG[kind]}#{ctx.local_variable_get(name).inspect}"
           end
         )
@@ -308,12 +371,12 @@ module ImLost
 
   @trace_results = [
     TracePoint.new(:c_return) do |tp|
-      next unless @trace.key?(tp.self.__id__)
+      next if !@trace.key?(tp.self.__id__) || tp.path == __FILE__
       @output.puts(as_sig('<', tp, tp.parameters.map { ARG_SIG[_1[0]] || '?' }))
       @output.puts("  = #{tp.return_value.inspect}")
     end,
     TracePoint.new(:return) do |tp|
-      next unless @trace.key?(tp.self.__id__)
+      next if !@trace.key?(tp.self.__id__) || tp.path == __FILE__
       ctx = tp.binding
       @output.puts(
         as_sig(
@@ -333,7 +396,9 @@ module ImLost
   @trace_exceptions =
     TracePoint.new(*supported) do |tp|
       ex = tp.raised_exception.inspect
-      @output.puts("#{EX_PREFIX[tp.event]} #{ex[0] == '#' ? ex[2..-2] : ex}")
+      @output.puts(
+        "#{tp.event == :raise ? 'x' : '!'} #{ex[0] == '#' ? ex[2..-2] : ex}"
+      )
       @output.puts("  #{tp.path}:#{tp.lineno}") if @exception_locations
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: im-lost
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Mike Blumtritt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-12 00:00:00.000000000 Z
+date: 2024-05-13 00:00:00.000000000 Z
 dependencies: []
 description: |
   If you have overlooked something again and don't really understand what