im-lost 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 39160aff2b7fa8320ae12c5d035fa40fbf6f96a2fbe0418ddfb31ac700c2bf72
+  data.tar.gz: 044bf4b9b4f9288f418b0cc5344cc82d1a88839d08a8ef1b8008d616ef11481c
+SHA512:
+  metadata.gz: 5d76261aafb61289cf56c23fb2acb0c0e6a0b8cc834b4e28b72d80cf0f6dfdf7966a8b613c7a0f4e8ee005eae2ba4064fe9aeb7b7520cbd53ce8e99671e33f0f
+  data.tar.gz: da598803cf6e2ee4e4baa92f8e702796050f279645daf80fccffa16c2be2eaa314cee7a69742691dde5d798f44f75d610dcb7db71d223a72c0fcabb2e65c7030

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mike Blumtritt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,144 @@
+# ImLost ![version](https://img.shields.io/gem/v/im-lost?label=)
+
+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!
+
+- Gem: [rubygems.org](https://rubygems.org/gems/im-lost)
+- Source: [github.com](https://github.com/mblumtritt/im-lost)
+- Help: [rubydoc.info](https://rubydoc.info/gems/im-lost/ImLost)
+
+## Description
+
+If you like to undertsand method call details you get a call trace with `ImLost.trace`:
+
+```ruby
+File.open('test.txt', 'w') do |file|
+  ImLost.trace(file) do
+    file << 'hello '
+    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
+```
+
+When you need to know if exceptions are raised and handled you can use `ImLost.trace_exceptions`:
+
+```ruby
+ImLost.trace_exceptions do
+  File.write('/', 'test')
+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
+```
+
+When you like to know if and when a code point is reached, `ImLost.here` will help:
+
+```ruby
+ImLost.here
+```
+
+## Example
+
+```ruby
+require 'im-lost'
+
+class Foo
+  def self.create(value:) = new(value)
+
+  attr_reader :value
+
+  def initialize(value)
+    @value = value
+  end
+
+  def foo(arg, *args, key: nil, **kw_args, &block)
+    @value = "#{arg}-#{key}-[#{args.join(',')}]-#{kw_args.inspect}-#{bar}"
+    block ? block.call(@value) : @value
+  end
+
+  def bar = :bar
+end
+
+ImLost.trace_results = true
+ImLost.trace(Foo)
+
+my_foo = Foo.create(value: :foo!)
+ImLost.trace(my_foo)
+
+my_foo.foo(1, key: :none)
+my_foo.foo(2, :a, :b, :c, key: :some, name: :value)
+my_foo.foo(3) { puts _1 }
+
+# output will look like
+#   > Foo.create(:foo!)
+#     /projects/foo.rb:25
+#   > Foo.new(*)
+#     /projects/foo.rb:6
+#   < Foo.new(*)
+#     = #<Foo:0x0000000100902418 @value=:foo!>
+#   < Foo.create(:foo!)
+#     = #<Foo:0x0000000100902418 @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"
+#   > Foo#foo(2, *[:a, :b, :c], :some, **{:name=>:value}, &nil)
+#     /projects/foo.rb:29
+#   > 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
+#   > Foo#bar()
+#     /projects/foo.rb:15
+#   < Foo#bar()
+#     = :bar
+#   3--[]-{}-bar
+#   < Foo#foo(3, *[], nil, **{}, &#<Proc:0x0000000100900578 /projects/foo.rb:30>)
+#     = nil
+```
+
+See [examples dir](./examples) for more…
+
+## Installation
+
+You can install the gem in your system with
+
+```shell
+gem install im-lost
+```
+
+or you can use [Bundler](http://gembundler.com/) to add ImLost to your own project:
+
+```shell
+bundle add im-lost
+```
+
+After that you only need one line of code to have everything together
+
+```ruby
+require 'im-lost'
+```

data/examples/foo.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative '../lib/im-lost'
+
+class Foo
+  def self.create(value:) = new(value)
+
+  attr_reader :value
+
+  def initialize(value)
+    @value = value
+  end
+
+  def foo(arg, *args, key: nil, **kw_args, &block)
+    @value = "#{arg}-#{key}-[#{args.join(',')}]-#{kw_args.inspect}-#{bar}"
+    block ? block.call(@value) : @value
+  end
+
+  def bar = :bar
+end
+
+ImLost.trace_results = true
+ImLost.trace(Foo)
+
+my_foo = Foo.create(value: :foo!)
+ImLost.trace(my_foo)
+
+my_foo.foo(1, key: :none)
+my_foo.foo(2, :a, :b, :c, key: :some, name: :value)
+my_foo.foo(3) { puts _1 }
+
+# output will look like
+#   > Foo.create(:foo!)
+#     /projects/foo.rb:25
+#   > Foo.new(*)
+#     /projects/foo.rb:6
+#   < Foo.new(*)
+#     = #<Foo:0x0000000100902418 @value=:foo!>
+#   < Foo.create(:foo!)
+#     = #<Foo:0x0000000100902418 @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"
+#   > Foo#foo(2, *[:a, :b, :c], :some, **{:name=>:value}, &nil)
+#     /projects/foo.rb:29
+#   > 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
+#   > Foo#bar()
+#     /projects/foo.rb:15
+#   < Foo#bar()
+#     = :bar
+#   3--[]-{}-bar
+#   < Foo#foo(3, *[], nil, **{}, &#<Proc:0x0000000100900578 /projects/foo.rb:30>)
+#     = nil

data/examples/kernel_calls.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+puts <<~INFO
+
+  This example traces calls for very basic Ruby objects when a new Class is
+  generated and pretty_print is automatically loaded.
+
+INFO
+
+require 'im-lost'
+
+ImLost.trace_results = true
+ImLost.trace(Kernel, Object, Module, Class, self) do
+  puts '=' * 79
+  pp Class.new
+  puts '=' * 79
+end

data/lib/im-lost/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ImLost
+  # The version number of the gem.
+  VERSION = '1.0.0'
+end

data/lib/im-lost.rb

@@ -0,0 +1,341 @@
+# frozen_string_literal: true
+
+module ImLost
+  class << self
+    #
+    # Enables/disables to include code location into traced call information.
+    # This is enabled by default.
+    #
+    # @return [Boolean] whether code location will be included
+    #
+    attr_reader :caller_locations
+
+    def caller_locations=(value)
+      @caller_locations = value ? true : false
+    end
+
+    #
+    # The output device used to write information.
+    # This should be an `IO` device or any other object responding to `#puts`.
+    #
+    # `$stderr` is configured by default.
+    #
+    # @example Write to a file
+    #   ImLost.output = File.new('./trace', 'w')
+    #
+    # @example Write temporary into a memory stream
+    #   require 'stringio'
+    #
+    #   original = ImLost.output
+    #   begin
+    #     ImLost.output = StringIO.new
+    #     # ... collect trace information
+    #     puts(ImLost.output.string) # or whatever
+    #   ensure
+    #     ImLost.output = original
+    #   end
+    #
+    # @return [#puts] the output device
+    #
+    attr_reader :output
+
+    def output=(value)
+      return @output = value if value.respond_to?(:puts)
+      raise(ArgumentError, "invalid output device - #{value.inspect}")
+    end
+
+    #
+    # Enables/disables tracing of method calls.
+    # This is enabled by default.
+    #
+    # @attribute [r] trace_calls
+    # @return [Boolean] whether method calls will be traced
+    #
+    def trace_calls = @trace_calls[0].enabled?
+
+    def trace_calls=(value)
+      if value
+        @trace_calls.each(&:enable) unless trace_calls
+      elsif trace_calls
+        @trace_calls.each(&:disable)
+      end
+    end
+
+    #
+    # Traces execptions raised within a given block.
+    #
+    # @example Trace exception and rescue handling
+    #   ImLost.trace_exceptions do
+    #     File.write('/', 'test')
+    #   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
+    #
+    # @param with_locations [Boolean] wheter the locations should be included
+    #   into the exception trace information
+    # @yieldreturn [Object] return result
+    #
+    def trace_exceptions(with_locations: true)
+      return unless block_given?
+      we = @trace_exceptions.enabled?
+      el = @exception_locations
+      @exception_locations = with_locations
+      @trace_exceptions.enable unless we
+      yield
+    ensure
+      @trace_exceptions.disable unless we
+      @exception_locations = el
+    end
+
+    #
+    # Enables/disables tracing of returned valuess of method calls.
+    # This is disabled by default.
+    #
+    # @attribute [r] trace_results
+    # @return [Boolean] whether return values will be traced
+    #
+    def trace_results = @trace_results[0].enabled?
+
+    def trace_results=(value)
+      if value
+        @trace_results.each(&:enable) unless trace_results
+      elsif trace_results
+        @trace_results.each(&:disable)
+      end
+    end
+
+    #
+    # Print the call location conditionally.
+    #
+    # @example simply print location
+    #   ImLost.here
+    #
+    # @example print location when instance variable is empty
+    #   ImLost.here(@name.empty?)
+    #
+    # @example print location when instance variable is nil or empty
+    #   ImLost.here { @name.nil? || @name.empty? }
+    #
+    # @overload here
+    #   Prints the caller location.
+    #   @return [true]
+    #
+    # @overload here(test)
+    #   Prints the caller location when given argument is truthy.
+    #   @param test [Object]
+    #   @return [Object] test
+    #
+    # @overload here
+    #   Prints the caller location when given block returns a truthy result.
+    #   @yield When the block returns a truthy result the location will be print
+    #   @yieldreturn [Object] return result
+    #
+    def here(test = true)
+      return test if !test || (block_given? && !(test = yield))
+      loc = Kernel.caller_locations(1, 1)[0]
+      @output.puts(": #{loc.path}:#{loc.lineno}")
+      test
+    end
+
+    #
+    # Trace objects.
+    #
+    # The given arguments can be any object instance or module or class.
+    #
+    # @example trace method calls of an instance variable for a while
+    #   ImLost.trace(@file)
+    #   # ...
+    #   ImLost.untrace(@file)
+    #
+    # @example temporary trace method calls
+    #   File.open('test.txt', 'w') do |file|
+    #     ImLost.trace(file) do
+    #       file << 'hello '
+    #       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
+    #
+    # @overload trace(*args)
+    #   @param args [[Object]] one or more objects to be traced
+    #   @return [[Object]] the traced object(s)
+    #   Start tracing the given objects.
+    #   @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)
+    #   @yieldreturn [Object] return result
+    #   Traces the given object(s) inside the block only.
+    #   The object(s) will not be traced any longer after the block call.
+    #
+    def trace(*args, &block)
+      return block&.call if args.empty?
+      return args.size == 1 ? _trace(args[0]) : _trace_all(args) unless block
+      args.size == 1 ? _trace_b(args[0], &block) : _trace_all_b(args, &block)
+    end
+
+    #
+    # Stop tracing objects.
+    #
+    # @example trace some objects for some code lines
+    #   traced_vars = ImLost.trace(@file, @client)
+    #   # ...
+    #   ImLost.untrace(*traced_vars)
+    #
+    # @see trace
+    #
+    # @param args [[Object]] one or more objects which should not longer be
+    #   traced
+    # @return [[Object]] the object(s) which are not longer be traced
+    # @return [nil] when none of the objects was traced before
+    #
+    def untrace(*args)
+      ret = args.filter_map { @trace.delete(_1.__id__) ? _1 : nil }
+      args.size == 1 ? ret[0] : ret
+    end
+
+    #
+    # Stop tracing any object.
+    # (When you are really lost and just like to stop tracing of all your
+    #   objects.)
+    #
+    # @see trace
+    #
+    # @return [self] itself
+    #
+    def untrace_all!
+      @trace = {}.compare_by_identity
+      self
+    end
+
+    protected
+
+    def as_sig(prefix, info, args)
+      args = args.join(', ')
+      case info.self
+      when Class, Module
+        "#{prefix} #{info.self}.#{info.method_id}(#{args})"
+      else
+        "#{prefix} #{info.defined_class}##{info.method_id}(#{args})"
+      end
+    end
+
+    private
+
+    def _trace(arg)
+      @trace[arg.__id__] = 1 if self != arg && @output != arg
+      arg
+    end
+
+    def _trace_all(args)
+      args.each do |arg|
+        @trace[arg.__id__] = 1 if arg != self && @output != 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
+    end
+
+    def _trace_all_b(args)
+      ids =
+        args.filter_map do |arg|
+          next if self == arg || @output == arg
+          @trace[id = arg.__id__] = 1
+          id
+        end
+      yield(args)
+    ensure
+      ids.each { @trace.delete(_1) }
+    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
+
+  @trace = {}.compare_by_identity
+  @caller_locations = true
+  @output = $stderr.respond_to?(:puts) ? $stderr : STDERR
+
+  @trace_calls = [
+    TracePoint.new(:c_call) do |tp|
+      next unless @trace.key?(tp.self.__id__)
+      @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__)
+      ctx = tp.binding
+      @output.puts(
+        as_sig(
+          '>',
+          tp,
+          tp.parameters.map do |kind, name|
+            next name if NO_NAME.include?(name)
+            "#{ARG_SIG[kind]}#{ctx.local_variable_get(name).inspect}"
+          end
+        )
+      )
+      next unless @caller_locations
+      loc = ctx.eval('caller_locations(4,1)')[0]
+      @output.puts("  #{loc.path}:#{loc.lineno}")
+    end
+  ]
+
+  @trace_results = [
+    TracePoint.new(:c_return) do |tp|
+      next unless @trace.key?(tp.self.__id__)
+      @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__)
+      ctx = tp.binding
+      @output.puts(
+        as_sig(
+          '<',
+          tp,
+          tp.parameters.map do |kind, name|
+            next name if %i[* ** &].include?(name)
+            "#{ARG_SIG[kind]}#{ctx.local_variable_get(name).inspect}"
+          end
+        )
+      )
+      @output.puts("  = #{tp.return_value.inspect}")
+    end
+  ]
+
+  supported = RUBY_VERSION >= '3.3.0' ? %i[raise rescue] : %i[raise]
+  @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.path}:#{tp.lineno}") if @exception_locations
+    end
+
+  self.trace_calls = true
+end

data/lib/im_lost.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'im-lost'

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: im-lost
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Mike Blumtritt
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-05-12 00:00:00.000000000 Z
+dependencies: []
+description: |
+  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!
+email:
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- LICENSE
+files:
+- LICENSE
+- README.md
+- examples/foo.rb
+- examples/kernel_calls.rb
+- lib/im-lost.rb
+- lib/im-lost/version.rb
+- lib/im_lost.rb
+homepage: https://github.com/mblumtritt/im-lost
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/mblumtritt/im-lost
+  bug_tracker_uri: https://github.com/mblumtritt/im-lost/issues
+  documentation_uri: https://rubydoc.info/gems/im-lost
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.10
+signing_key:
+specification_version: 4
+summary: Your debugging helper.
+test_files: []