im-lost 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b3508c022462842507ce749828e2c74c4db9e9097496e68cedc758018017cb5
-  data.tar.gz: 93ac54d98ae6474d4f7144b116cf0e2784c88babf57ff592a317b463caa7ee13
+  metadata.gz: be7b612cd1d68529fbba18b5a9a4759e60111facc52e99a20b4da140e887f8c4
+  data.tar.gz: c1aeff67c05a2e31c0dab72c6c5ed84bb27f9231e759de874882a082f0fac284
 SHA512:
-  metadata.gz: 4d45f27c98a6ed477ce4e696f4c41286ca24c105de1668889bf64fc0d57d3947e04c026b40fa7f5f79e2ce5016fcc8327e3c9a8b20a1e6ae0561900efae4f5f3
-  data.tar.gz: 1502147a826924c39988f9272d62e3c0274dc8cdb961f25c405a229cf6273142579ad136af1972c06874d13af110486b79db45907c219bd3082a91cd507220ab
+  metadata.gz: 9821d580f5c5e4e62133dba01fbdd9a26ec3cfd8ffe8ed6603b24760d5073184bd22bdbc6ab95317c6a39690abc56ad4e2e5afdd5df4e3d261525afc927448eb
+  data.tar.gz: b12a64d4ee2b7e9f1764c5bcb0e79a5f9b240b9b49359c10868abc2f763cefb8ea4a7844c0ba17239346157f516b10a6fc8d368386206cb0fea0c6cc330a7601

data/README.md

@@ -19,6 +19,7 @@ File.open('test.txt', 'w') do |file|
     file.puts(:world!)
   end
 end
+
 # output will look like
 #  > IO#<<(?)
 #    /projects/test.rb:1
@@ -38,6 +39,7 @@ 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
@@ -47,7 +49,7 @@ end
 #    /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

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)

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.2'
+  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)
@@ -257,7 +265,7 @@ module ImLost
       @trace[traced] = traced if traced
     end
 
-    protected
+    private
 
     def as_sig(prefix, info, args)
       args = args.join(', ')
@@ -269,8 +277,6 @@ module ImLost
       end
     end
 
-    private
-
     def _trace(arg)
       id = arg.__id__
       @trace[id] = id if __id__ != id && @output.__id__ != id
@@ -312,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
@@ -326,16 +332,150 @@ 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 = { :* => 1, :** => 1, :& => 1 }.compare_by_identity.freeze
   private_constant :ARG_SIG, :NO_NAME
@@ -344,6 +484,15 @@ module ImLost
   @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__
@@ -383,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
         )
@@ -392,7 +541,7 @@ 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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: im-lost
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Mike Blumtritt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-13 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.5.10
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: Your debugging helper.