im-lost 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f3add8daa7364ab1a0f1a5058a09b529e448db9bfeda20c9f35e9e69fccbc90
-  data.tar.gz: 8bfad384dc5dfd659bb5a49eda611e90b9ee090d0bfa5dfbfd9979289591bac8
+  metadata.gz: be7b612cd1d68529fbba18b5a9a4759e60111facc52e99a20b4da140e887f8c4
+  data.tar.gz: c1aeff67c05a2e31c0dab72c6c5ed84bb27f9231e759de874882a082f0fac284
 SHA512:
-  metadata.gz: a2fa68b037ca862fc7754b9f613743e6c358aaf9ec2c299a3dc0b3fc8612ab9537696d21c2212e292530e258470db970f4e6bd2e724c38f1fea22f7b22af3376
-  data.tar.gz: 6c47d670e625de3a386cf1412278bb5e6382e8b3809a7bb0678ee7f4ef99983cddfd805655198ad931bb735a336343837c3b4b4e9887ba7bc6dd0064dd168bfc
+  metadata.gz: 9821d580f5c5e4e62133dba01fbdd9a26ec3cfd8ffe8ed6603b24760d5073184bd22bdbc6ab95317c6a39690abc56ad4e2e5afdd5df4e3d261525afc927448eb
+  data.tar.gz: b12a64d4ee2b7e9f1764c5bcb0e79a5f9b240b9b49359c10868abc2f763cefb8ea4a7844c0ba17239346157f516b10a6fc8d368386206cb0fea0c6cc330a7601

data/README.md

@@ -19,15 +19,16 @@ File.open('test.txt', 'w') do |file|
     file.puts(:world!)
   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`:
@@ -38,16 +39,17 @@ ImLost.trace_exceptions do
 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:
+When you like to know if a code point is reached, `ImLost.here` will help:
 
 ```ruby
 ImLost.here
@@ -108,31 +110,48 @@ my_foo.foo(3) { puts _1 }
 ImLost.vars(my_foo)
 
 # output will look like
-#  > Foo.create(:foo!)
-#    /projects/foo.rb25
-#  > Foo.new(*)
-#    /projects/foo.rb6
-#  < Foo.new(*)
-#    = #<Foo:0x0000000100ab1188 @value=:foo!>
-#  < Foo.create(:foo!)
-#    = #<Foo:0x0000000100ab1188 @value=:foo!>
-#  > Foo#foo(1, *[], :none, **{}, &nil)
-#    /projects/foo.rb28
-#  > Foo#bar()
-#    /projects/foo.rb15
-#  < Foo#bar()
-#    = :bar
-#  < Foo#foo(1, *[], :none, **{}, &nil)
-#    = "1-none-[]-{}-bar"
-#  = /projects/foo.rb29
-#    instance variables:
-#    @value: "1-none-[]-{}-bar"
-#  = /projects/foo.rb32
-#    instance variables:
-#    @value: "2-some-[a,b,c]-{:name=>:value}-bar"
-#  = /projects/foo.rb35
-#    instance variables:
-#    @value: "3--[]-{}-bar"
+#   > Foo.create(:foo!)
+#     /projects/foo.rb:25
+#   > Foo.new(*)
+#     /projects/foo.rb:6
+#   < Foo.new(*)
+#     = #<Foo:0x00000001030810c0 @value=:foo!>
+#   < Foo.create(:foo!)
+#     = #<Foo:0x00000001030810c0 @value=:foo!>
+#   > Foo#foo(1, *[], :none, **{}, &nil)
+#     /projects/foo.rb:28
+#   > Foo#bar()
+#     /projects/foo.rb:15
+#   < Foo#bar()
+#     = :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: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"
+#   = /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: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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative '../lib/im-lost'
+require 'im-lost'
 
 class Foo
   def self.create(value:) = new(value)
@@ -35,28 +35,45 @@ my_foo.foo(3) { puts _1 }
 ImLost.vars(my_foo)
 
 # output will look like
-#  > Foo.create(:foo!)
-#    /projects/foo.rb25
-#  > Foo.new(*)
-#    /projects/foo.rb6
-#  < Foo.new(*)
-#    = #<Foo:0x0000000100ab1188 @value=:foo!>
-#  < Foo.create(:foo!)
-#    = #<Foo:0x0000000100ab1188 @value=:foo!>
-#  > Foo#foo(1, *[], :none, **{}, &nil)
-#    /projects/foo.rb28
-#  > Foo#bar()
-#    /projects/foo.rb15
-#  < Foo#bar()
-#    = :bar
-#  < Foo#foo(1, *[], :none, **{}, &nil)
-#    = "1-none-[]-{}-bar"
-#  = /projects/foo.rb29
-#    instance variables:
-#    @value: "1-none-[]-{}-bar"
-#  = /projects/foo.rb32
-#    instance variables:
-#    @value: "2-some-[a,b,c]-{:name=>:value}-bar"
-#  = /projects/foo.rb35
-#    instance variables:
-#    @value: "3--[]-{}-bar"
+#   > Foo.create(:foo!)
+#     /projects/foo.rb:25
+#   > Foo.new(*)
+#     /projects/foo.rb:6
+#   < Foo.new(*)
+#     = #<Foo:0x00000001030810c0 @value=:foo!>
+#   < Foo.create(:foo!)
+#     = #<Foo:0x00000001030810c0 @value=:foo!>
+#   > Foo#foo(1, *[], :none, **{}, &nil)
+#     /projects/foo.rb:28
+#   > Foo#bar()
+#     /projects/foo.rb:15
+#   < Foo#bar()
+#     = :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: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"
+#   = /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:0x00000001030aee30 /projects/foo.rb:34>)
+#     = nil
+#   = /projects/foo.rb:35
+#     instance variables:
+#     @value: "3--[]-{}-bar"

data/examples/timer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+puts <<~INFO
+
+  This is an example how to use named and anonymous timers.
+
+INFO
+
+require_relative '../lib/im-lost'
+
+puts 'Create a named timer:'
+ImLost.timer.create(:first)
+
+puts 'Create an anonymous timer:'
+second = ImLost.timer.create
+
+sleep(0.5) # or whatever
+
+puts 'print runtime for named timer:'
+ImLost.timer[:first]
+
+puts 'print runtime for anonymous timer:'
+ImLost.timer[second]
+
+puts 'delete a named timer'
+ImLost.timer.delete(:first)
+
+puts 'delete an anonymous timer'
+ImLost.timer.delete(second)

data/lib/im-lost/version.rb

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

data/lib/im-lost.rb

@@ -1,5 +1,6 @@
 # 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
@@ -53,6 +54,12 @@ module ImLost
       raise(ArgumentError, "invalid output device - #{value.inspect}")
     end
 
+    #
+    # @return [TimerStore] the timer store used to estimate the runtime of
+    #   your code
+    #
+    attr_reader :timer
+
     #
     # Enables/disables tracing of method calls.
     # This is enabled by default.
@@ -79,6 +86,7 @@ module ImLost
     #   rescue SystemCallError
     #     raise('something went wrong!')
     #   end
+    #
     #   # output will look like
     #   #   x Errno::EEXIST: File exists @ rb_sysopen - /
     #   #   /projects/test.rb:2
@@ -170,15 +178,16 @@ module ImLost
     #       file.puts(:world!)
     #     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
+    #
+    #   # 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
     #
     # @overload trace(*args)
     #   @param args [[Object]] one or more objects to be traced
@@ -187,7 +196,6 @@ module ImLost
     #   @see untrace
     #   @see untrace_all!
     #
-    #
     # @overload trace(*args)
     #   @param args [[Object]] one or more objects to be traced
     #   @yieldparam args [Object] the traced object(s)
@@ -254,10 +262,10 @@ module ImLost
       return unless object.respond_to?(:instance_variables)
       _vars(object, Kernel.caller_locations(1, 1)[0])
     ensure
-      @trace[traced] = 1 if traced
+      @trace[traced] = traced if traced
     end
 
-    protected
+    private
 
     def as_sig(prefix, info, args)
       args = args.join(', ')
@@ -269,33 +277,36 @@ module ImLost
       end
     end
 
-    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
@@ -307,11 +318,11 @@ module ImLost
       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
+        return obj
+      end
+      @output.puts('  instance variables:')
+      vars.sort!.each do |name|
+        @output.puts("  #{name}: #{obj.instance_variable_get(name).inspect}")
       end
       obj
     end
@@ -321,25 +332,167 @@ module ImLost
       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
+        return self
+      end
+      @output.puts('  local variables:')
+      vars.sort!.each do |name|
+        @output.puts("  #{name}: #{binding.local_variable_get(name).inspect}")
       end
       self
     end
   end
 
+  #
+  # A store to create and register timers you can use to estimate the runtime of
+  # some code.
+  #
+  # All timers are identified by an unique ID or a name.
+  #
+  # @example Use a named timer
+  #   ImLost.timer.create('my_test')
+  #
+  #   # ...your code here...
+  #
+  #   ImLost.timer['my_test']
+  #   # => prints the timer name, this location and runtime so far
+  #
+  #   # ...more code here...
+  #
+  #   ImLost.timer['my_test']
+  #   # => prints the timer name, this location and runtime since the timer was created
+  #
+  #   ImLost.timer.delete('my_test')
+  #   # the timer with name 'my_test' is not longer valid now
+  #
+  #
+  # @example Use an anonymous timer (identified by ID)
+  #   tmr = ImLost.timer.create
+  #
+  #   # ...your code here...
+  #
+  #   ImLost.timer[tmr]
+  #   # => prints the timer ID, this location and runtime so far
+  #
+  #   # ...more code here...
+  #
+  #   ImLost.timer[tmr]
+  #   # => prints the timer ID, this location and runtime since the timer was created
+  #
+  #   ImLost.timer.delete(tmr)
+  #   # the timer with the ID `tmr` is not longer valid now
+  #
+  # @see ImLost.timer
+  #
+  class TimerStore
+    if defined?(Process::CLOCK_MONOTONIC)
+      # @return [Float] current time
+      def self.now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    else
+      # @return [Float] current time
+      def self.now = ::Time.now
+    end
+
+    # @attribute [r] count
+    # @return [Integer] the number of registered timers
+    def count = ids.size
+
+    # @attribute [r] empty?
+    # @return [Boolean] wheter the timer store is empty or not
+    def empty? = ids.empty?
+
+    # @attribute [r] ids
+    # @return [Array<Integer>] IDs of all registered timers
+    def ids = (@ll.keys.keep_if { _1.is_a?(Integer) })
+
+    #
+    # Create and register a new named or anonymous timer.
+    # It print the ID or name of the created timer and includes the location.
+    #
+    # @param name [#to_s] optional timer name
+    # @return [Integer] timer ID
+    #
+    def create(name = nil)
+      timer = []
+      @ll[id = timer.__id__] = timer
+      name ? @ll[name = name.to_s] = timer : name = id
+      @cb[name, Kernel.caller_locations(1, 1)[0]]
+      timer << name << self.class.now
+      id
+    end
+
+    #
+    # Delete and unregister timers.
+    #
+    # @param id_or_names [Array<Integer, #to_s>] the IDs or the names
+    # @return [nil]
+    #
+    def delete(*id_or_names)
+      id_or_names.flatten.each do |id|
+        if id.is_a?(Integer)
+          del = @ll.delete(id)
+          @ll.delete(del[0]) if del
+        else
+          del = @ll.delete(id.to_s)
+          @ll.delete(del.__id__) if del
+        end
+      end
+      nil
+    end
+
+    #
+    # Print the ID or name and the runtime since timer was created.
+    # It includes the location.
+    #
+    # @param id_or_name [Integer, #to_s] the identifier or the name of the timer
+    # @return [Integer] timer ID
+    # @raise [ArgumentError] when the given id or name is not a registered timer
+    #   identifier or name
+    #
+    def [](id_or_name)
+      time = self.class.now
+      timer = @ll[id_or_name.is_a?(Integer) ? id_or_name : id_or_name.to_s]
+      raise(ArgumentError, "not a timer - #{id_or_name.inspect}") unless timer
+      @cb[timer[0], Kernel.caller_locations(1, 1)[0], time - timer[1]]
+      timer.__id__
+    end
+
+    #
+    # Print the ID or name and the runtime of all active timers.
+    # It includes the location.
+    #
+    # @return [nil]
+    #
+    def all
+      now = self.class.now
+      loc = Kernel.caller_locations(1, 1)[0]
+      @ll.values.uniq.reverse_each { |name, start| @cb[name, loc, now - start] }
+      nil
+    end
+
+    # @!visibility private
+    def initialize(&block)
+      @cb = block
+      @ll = {}
+    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
   @output = $stderr.respond_to?(:puts) ? $stderr : STDERR
 
+  @timer =
+    TimerStore.new do |title, location, time|
+      @output.puts(
+        "T #{title}: #{time ? "#{time} sec." : 'created'}",
+        "  #{location.path}:#{location.lineno}"
+      )
+    end
+  TimerStore.private_class_method(:new)
+
   @trace_calls = [
     TracePoint.new(:c_call) do |tp|
       next if !@trace.key?(tp.self.__id__) || tp.path == __FILE__
@@ -354,7 +507,7 @@ module ImLost
           '>',
           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
         )
@@ -379,7 +532,7 @@ module ImLost
           '<',
           tp,
           tp.parameters.map do |kind, name|
-            next name if %i[* ** &].include?(name)
+            next name if NO_NAME.key?(name)
             "#{ARG_SIG[kind]}#{ctx.local_variable_get(name).inspect}"
           end
         )
@@ -388,11 +541,13 @@ module ImLost
     end
   ]
 
-  supported = RUBY_VERSION >= '3.3.0' ? %i[raise rescue] : %i[raise]
+  supported = RUBY_VERSION.to_f < 3.3 ? %i[raise] : %i[raise rescue]
   @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.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Mike Blumtritt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-12 00:00:00.000000000 Z
+date: 2024-05-29 00:00:00.000000000 Z
 dependencies: []
 description: |
   If you have overlooked something again and don't really understand what
@@ -30,6 +30,7 @@ files:
 - README.md
 - examples/foo.rb
 - examples/kernel_calls.rb
+- examples/timer.rb
 - lib/im-lost.rb
 - lib/im-lost/version.rb
 - lib/im_lost.rb
@@ -56,7 +57,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.33
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: Your debugging helper.