tracer 0.1.0 → 0.2.1

data/lib/tracer/color.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Tracer
+  module Color
+    CLEAR = 0
+    BOLD = 1
+    UNDERLINE = 4
+    REVERSE = 7
+    RED = 31
+    GREEN = 32
+    YELLOW = 33
+    BLUE = 34
+    MAGENTA = 35
+    CYAN = 36
+
+    class << self
+      def colorize(text, seq)
+        seq = seq.map { |s| "\e[#{const_get(s)}m" }.join("")
+        "#{seq}#{text}#{clear}"
+      end
+
+      def clear
+        "\e[#{CLEAR}m"
+      end
+    end
+
+    def colorize(str, seq, colorize: @colorize)
+      !colorize ? str : Color.colorize(str, seq)
+    end
+
+    def colorize_cyan(str)
+      colorize(str, %i[CYAN BOLD])
+    end
+
+    def colorize_blue(str)
+      colorize(str, %i[BLUE BOLD])
+    end
+
+    def colorize_magenta(str)
+      colorize(str, %i[MAGENTA BOLD])
+    end
+  end
+end

data/lib/tracer/exception_tracer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class ExceptionTracer < Tracer::Base
+  def setup_tp
+    TracePoint.new(:raise) do |tp|
+      next if skip?(tp)
+
+      exc = tp.raised_exception
+
+      out tp,
+          " #{colorize_magenta(exc.inspect)}",
+          depth: caller.size - (1 + @depth_offset)
+    rescue Exception => e
+      p e
+    end
+  end
+
+  def skip_with_pattern?(tp)
+    super && !tp.raised_exception.inspect.match?(@pattern)
+  end
+end

data/lib/tracer/helper.rb

@@ -0,0 +1,3 @@
+require "tracer"
+
+Object.include(Tracer::Helper)

data/lib/tracer/irb.rb

@@ -0,0 +1,115 @@
+require_relative "../tracer"
+require "irb/cmd/nop"
+require "irb"
+
+module Tracer
+  def self.register_irb_commands
+    ec = IRB::ExtendCommandBundle.instance_variable_get(:@EXTEND_COMMANDS)
+
+    [
+      [:trace, :Trace, nil, [:trace, IRB::ExtendCommandBundle::OVERRIDE_ALL]],
+      [
+        :trace_call,
+        :TraceCall,
+        nil,
+        [:trace_call, IRB::ExtendCommandBundle::OVERRIDE_ALL]
+      ],
+      [
+        :trace_exception,
+        :TraceException,
+        nil,
+        [:trace_exception, IRB::ExtendCommandBundle::OVERRIDE_ALL]
+      ]
+    ].each do |ecconfig|
+      ec.push(ecconfig)
+      IRB::ExtendCommandBundle.def_extend_command(*ecconfig)
+    end
+  end
+end
+
+module IRB
+  module ExtendCommand
+    class TraceCommand < Nop
+      class << self
+        def transform_args(args)
+          # Return a string literal as is for backward compatibility
+          if args.empty? || string_literal?(args)
+            args
+          else # Otherwise, consider the input as a String for convenience
+            args.strip.dump
+          end
+        end
+      end
+    end
+
+    class Trace < TraceCommand
+      category "Tracing"
+      description "Trace the target object (or self) in the given expression. Usage: `trace [target,] <expression>`"
+
+      def execute(*args)
+        if args.empty?
+          puts "Please provide the expression to trace. Usage: `trace [target,] <expression>`"
+          return
+        end
+
+        args = args.first.split(/,/, 2)
+
+        case args.size
+        when 1
+          target = irb_context.workspace.main
+          expression = args.first
+        when 2
+          target = eval(args.first, irb_context.workspace.binding)
+          expression = args.last
+        else
+          puts "Please provide the expression to trace. Usage: `trace [target,] <expression>`"
+          return
+        end
+
+        unless expression
+          puts "Please provide the expression to trace. Usage: `trace [target,] <expression>`"
+          return
+        end
+
+        b = irb_context.workspace.binding
+        Tracer.trace(target) { eval(expression, b) }
+      end
+    end
+
+    class TraceCall < TraceCommand
+      category "Tracing"
+      description "Trace method calls in the given expression. Usage: `trace_call <expression>`"
+
+      def execute(*args)
+        expression = args.first
+
+        unless expression
+          puts "Please provide the expression to trace. Usage: `trace_call <expression>`"
+          return
+        end
+
+        b = irb_context.workspace.binding
+        Tracer.trace_call { eval(expression, b) }
+      end
+    end
+
+    class TraceException < TraceCommand
+      category "Tracing"
+      description "Trace exceptions in the given expression. Usage: `trace_exception <expression>`"
+
+      def execute(*args)
+        expression = args.first
+
+        unless expression
+          puts "Please provide the expression to trace. Usage: `trace_exception <expression>`"
+          return
+        end
+
+        b = irb_context.workspace.binding
+        Tracer.trace_exception { eval(expression, b) }
+      end
+    end
+  end
+end
+
+Tracer.register_irb_commands

data/lib/tracer/line_tracer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class LineTracer < Tracer::Base
+  def setup_tp
+    TracePoint.new(:line) do |tp|
+      next if skip?(tp)
+      # pp tp.object_id, caller(0)
+      out tp
+    end
+  end
+end

data/lib/tracer/object_tracer.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+class ObjectTracer < Tracer::Base
+  attr_reader :target_id, :target_label
+
+  def initialize(target = nil, target_id: nil, target_label: nil, **kw)
+    unless target || target_id
+      raise ArgumentError, "target or target_id is required"
+    end
+
+    @target_id = target_id || M_OBJECT_ID.bind_call(target)
+    @target_label =
+      (target ? safe_inspect(target) : target_label || "<unlabelled>")
+    super(**kw)
+  end
+
+  def key
+    [@type, @target_id, @pattern, @into].freeze
+  end
+
+  def description
+    "for #{@target_label} #{super}"
+  end
+
+  def colorized_target_label
+    colorize_magenta(@target_label)
+  end
+
+  PRIMITIVE_METHOD_SOURCES = [Module, Class, Object, Kernel]
+
+  def setup_tp
+    TracePoint.new(:a_call) do |tp|
+      next if skip?(tp)
+
+      if M_OBJECT_ID.bind_call(tp.self) == @target_id
+        if PRIMITIVE_METHOD_SOURCES.any? { |klass| klass == tp.defined_class }
+          next
+        end
+
+        internal_depth = 2
+        klass = tp.defined_class
+        method = tp.method_id
+        method_info =
+          method_info =
+            if klass
+              if klass.singleton_class?
+                if M_IS_A.bind_call(tp.self, Class)
+                  ".#{method} (#{klass}.#{method})"
+                else
+                  ".#{method}"
+                end
+              else
+                "##{method} (#{klass}##{method})"
+              end
+            else
+              if method
+                "##{method} (<unknown>##{method})"
+              else
+                "<eval or exec with &block>"
+              end
+            end
+
+        out tp,
+            " #{colorized_target_label} receives #{colorize_blue(method_info)}",
+            location: caller_locations(internal_depth, 1).first,
+            depth: caller.size - internal_depth - @depth_offset
+      elsif !tp.parameters.empty?
+        b = tp.binding
+        method_info = colorize_blue(minfo(tp))
+
+        tp.parameters.each do |type, name|
+          next unless name
+
+          colorized_name = colorize_cyan(name)
+
+          case type
+          when :req, :opt, :key, :keyreq
+            if M_OBJECT_ID.bind_call(b.local_variable_get(name)) == @target_id
+              internal_depth = 4
+              out tp,
+                  " #{colorized_target_label} is used as a parameter #{colorized_name} of #{method_info}",
+                  location: caller_locations(internal_depth, 1).first,
+                  depth: caller.size - internal_depth - @depth_offset
+            end
+          when :rest
+            next if name == :"*"
+
+            internal_depth = 6
+            ary = b.local_variable_get(name)
+            ary.each do |e|
+              if M_OBJECT_ID.bind_call(e) == @target_id
+                out tp,
+                    " #{colorized_target_label} is used as a parameter in #{colorized_name} of #{method_info}",
+                    location: caller_locations(internal_depth, 1).first,
+                    depth: caller.size - internal_depth - @depth_offset
+              end
+            end
+          when :keyrest
+            next if name == :"**"
+            internal_depth = 6
+            h = b.local_variable_get(name)
+            h.each do |k, e|
+              if M_OBJECT_ID.bind_call(e) == @target_id
+                out tp,
+                    " #{colorized_target_label} is used as a parameter in #{colorized_name} of #{method_info}",
+                    location: caller_locations(internal_depth, 1).first,
+                    depth: caller.size - internal_depth - @depth_offset
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tracer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-class Tracer
-  VERSION = "0.1.0"
+module Tracer
+  VERSION = "0.2.1"
 end

data/lib/tracer.rb

@@ -1,287 +1,32 @@
-# frozen_string_literal: false
-#--
-# $Release Version: 0.3$
-# $Revision: 1.12 $
+# frozen_string_literal: true
 
-##
-# Outputs a source level execution trace of a Ruby program.
-#
-# It does this by registering an event handler with Kernel#set_trace_func for
-# processing incoming events.  It also provides methods for filtering unwanted
-# trace output (see Tracer.add_filter, Tracer.on, and Tracer.off).
-#
-# == Example
-#
-# Consider the following Ruby script
-#
-#   class A
-#     def square(a)
-#       return a*a
-#     end
-#   end
-#
-#   a = A.new
-#   a.square(5)
-#
-# Running the above script using <code>ruby -r tracer example.rb</code> will
-# output the following trace to STDOUT (Note you can also explicitly
-# <code>require 'tracer'</code>)
-#
-#   #0:<internal:lib/rubygems/custom_require>:38:Kernel:<: -
-#   #0:example.rb:3::-: class A
-#   #0:example.rb:3::C: class A
-#   #0:example.rb:4::-:   def square(a)
-#   #0:example.rb:7::E: end
-#   #0:example.rb:9::-: a = A.new
-#   #0:example.rb:10::-: a.square(5)
-#   #0:example.rb:4:A:>:   def square(a)
-#   #0:example.rb:5:A:-:     return a*a
-#   #0:example.rb:6:A:<:   end
-#    |  |         | |  |
-#    |  |         | |   ---------------------+ event
-#    |  |         |  ------------------------+ class
-#    |  |          --------------------------+ line
-#    |   ------------------------------------+ filename
-#     ---------------------------------------+ thread
-#
-# Symbol table used for displaying incoming events:
-#
-# +}+:: call a C-language routine
-# +{+:: return from a C-language routine
-# +>+:: call a Ruby method
-# +C+:: start a class or module definition
-# +E+:: finish a class or module definition
-# +-+:: execute code on a new line
-# +^+:: raise an exception
-# +<+:: return from a Ruby method
-#
-# == Copyright
-#
-# by Keiju ISHITSUKA(keiju@ishitsuka.com)
-#
-class Tracer
+require_relative "tracer/version"
+require_relative "tracer/line_tracer"
+require_relative "tracer/call_tracer"
+require_relative "tracer/exception_tracer"
+require_relative "tracer/object_tracer"
 
-  class << self
-    # display additional debug information (defaults to false)
-    attr_accessor :verbose
-    alias verbose? verbose
+module Tracer
+  module Helper
+    DEPTH_OFFSET = 3
 
-    # output stream used to output trace (defaults to STDOUT)
-    attr_accessor :stdout
-
-    # mutex lock used by tracer for displaying trace output
-    attr_reader :stdout_mutex
-
-    # display process id in trace output (defaults to false)
-    attr_accessor :display_process_id
-    alias display_process_id? display_process_id
-
-    # display thread id in trace output (defaults to true)
-    attr_accessor :display_thread_id
-    alias display_thread_id? display_thread_id
-
-    # display C-routine calls in trace output (defaults to false)
-    attr_accessor :display_c_call
-    alias display_c_call? display_c_call
-  end
-
-  Tracer::stdout = STDOUT
-  Tracer::verbose = false
-  Tracer::display_process_id = false
-  Tracer::display_thread_id = true
-  Tracer::display_c_call = false
-
-  @stdout_mutex = Thread::Mutex.new
-
-  # Symbol table used for displaying trace information
-  EVENT_SYMBOL = {
-    "line" => "-",
-    "call" => ">",
-    "return" => "<",
-    "class" => "C",
-    "end" => "E",
-    "raise" => "^",
-    "c-call" => "}",
-    "c-return" => "{",
-    "unknown" => "?"
-  }
-
-  def initialize # :nodoc:
-    @threads = Hash.new
-    if defined? Thread.main
-      @threads[Thread.main.object_id] = 0
-    else
-      @threads[Thread.current.object_id] = 0
+    def trace_exception(&block)
+      tracer = ExceptionTracer.new(depth_offset: DEPTH_OFFSET)
+      tracer.start(&block)
     end
 
-    @get_line_procs = {}
-
-    @filters = []
-  end
-
-  def stdout # :nodoc:
-    Tracer.stdout
-  end
-
-  def on # :nodoc:
-    if block_given?
-      on
-      begin
-        yield
-      ensure
-        off
-      end
-    else
-      set_trace_func method(:trace_func).to_proc
-      stdout.print "Trace on\n" if Tracer.verbose?
+    def trace_call(&block)
+      tracer = CallTracer.new(depth_offset: DEPTH_OFFSET)
+      tracer.start(&block)
     end
-  end
-
-  def off # :nodoc:
-    set_trace_func nil
-    stdout.print "Trace off\n" if Tracer.verbose?
-  end
-
-  def add_filter(p = proc) # :nodoc:
-    @filters.push p
-  end
-
-  def set_get_line_procs(file, p = proc) # :nodoc:
-    @get_line_procs[file] = p
-  end
 
-  def get_line(file, line) # :nodoc:
-    if p = @get_line_procs[file]
-      return p.call(line)
-    end
-
-    unless list = SCRIPT_LINES__[file]
-      list = File.readlines(file) rescue []
-      SCRIPT_LINES__[file] = list
-    end
-
-    if l = list[line - 1]
-      l
-    else
-      "-\n"
+    def trace(target, &block)
+      tracer = ObjectTracer.new(target, depth_offset: DEPTH_OFFSET)
+      tracer.start(&block)
     end
   end
 
-  def get_thread_no # :nodoc:
-    if no = @threads[Thread.current.object_id]
-      no
-    else
-      @threads[Thread.current.object_id] = @threads.size
-    end
-  end
-
-  def trace_func(event, file, line, id, binding, klass, *) # :nodoc:
-    return if file == __FILE__
-
-    for p in @filters
-      return unless p.call event, file, line, id, binding, klass
-    end
-
-    return unless Tracer::display_c_call? or
-      event != "c-call" && event != "c-return"
-
-    Tracer::stdout_mutex.synchronize do
-      if EVENT_SYMBOL[event]
-        stdout.printf("<%d>", $$) if Tracer::display_process_id?
-        stdout.printf("#%d:", get_thread_no) if Tracer::display_thread_id?
-        if line == 0
-          source = "?\n"
-        else
-          source = get_line(file, line)
-        end
-        stdout.printf("%s:%d:%s:%s: %s",
-               file,
-               line,
-               klass || '',
-               EVENT_SYMBOL[event],
-               source)
-      end
-    end
-
-  end
-
-  # Reference to singleton instance of Tracer
-  Single = new
-
-  ##
-  # Start tracing
-  #
-  # === Example
-  #
-  #   Tracer.on
-  #   # code to trace here
-  #   Tracer.off
-  #
-  # You can also pass a block:
-  #
-  #   Tracer.on {
-  #     # trace everything in this block
-  #   }
-
-  def Tracer.on
-    if block_given?
-      Single.on{yield}
-    else
-      Single.on
-    end
-  end
-
-  ##
-  # Disable tracing
-
-  def Tracer.off
-    Single.off
-  end
-
-  ##
-  # Register an event handler <code>p</code> which is called everytime a line
-  # in +file_name+ is executed.
-  #
-  # Example:
-  #
-  #   Tracer.set_get_line_procs("example.rb", lambda { |line|
-  #     puts "line number executed is #{line}"
-  #   })
-
-  def Tracer.set_get_line_procs(file_name, p = proc)
-    Single.set_get_line_procs(file_name, p)
-  end
-
-  ##
-  # Used to filter unwanted trace output
-  #
-  # Example which only outputs lines of code executed within the Kernel class:
-  #
-  #   Tracer.add_filter do |event, file, line, id, binding, klass, *rest|
-  #     "Kernel" == klass.to_s
-  #   end
-
-  def Tracer.add_filter(p = proc)
-    Single.add_filter(p)
-  end
+  extend Helper
 end
 
-# :stopdoc:
-SCRIPT_LINES__ = {} unless defined? SCRIPT_LINES__
-
-if $0 == __FILE__
-  # direct call
-
-  $0 = ARGV[0]
-  ARGV.shift
-  Tracer.on
-  require $0
-else
-  # call Tracer.on only if required by -r command-line option
-  count = caller.count {|bt| %r%/rubygems/core_ext/kernel_require\.rb:% !~ bt}
-  if (defined?(Gem) and count == 0) or
-     (!defined?(Gem) and count <= 1)
-    Tracer.on
-  end
-end
-# :startdoc:
+require_relative "tracer/irb"

data/tracer.gemspec

@@ -1,26 +1,43 @@
-begin
-  require_relative "lib/tracer/version"
-rescue LoadError
-  # for Ruby core repository
-  require_relative "version"
-end
+# frozen_string_literal: true
+
+require_relative "lib/tracer/version"
 
 Gem::Specification.new do |spec|
-  spec.name          = "tracer"
-  spec.version       = Tracer::VERSION
-  spec.authors       = ["Keiju ISHITSUKA"]
-  spec.email         = ["keiju@ruby-lang.org"]
+  spec.name = "tracer"
+  spec.version = Tracer::VERSION
+  spec.authors = ["Stan Lo", "Keiju ISHITSUKA"]
+  spec.email = %w[stan001212@gmail.com keiju@ruby-lang.org]
 
-  spec.summary       = %q{Outputs a source level execution trace of a Ruby program.}
-  spec.description   = %q{Outputs a source level execution trace of a Ruby program.}
-  spec.homepage      = "https://github.com/ruby/tracer"
-  spec.license       = "BSD-2-Clause"
+  spec.summary = "A Ruby tracer"
+  spec.description = "A Ruby tracer"
+  spec.homepage = "https://github.com/ruby/tracer"
+  spec.licenses = %w[Ruby BSD-2-Clause]
+  spec.required_ruby_version = ">= 2.7.0"
 
-  spec.files         = [".gitignore", ".travis.yml", "Gemfile", "LICENSE.txt", "README.md", "Rakefile", "bin/console", "bin/setup", "lib/tracer.rb", "lib/tracer/version.rb", "tracer.gemspec"]
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/ruby/tracer"
+  spec.metadata[
+    "changelog_uri"
+  ] = "https://github.com/ruby/tracer/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files =
+    Dir.chdir(__dir__) do
+      `git ls-files -z`.split("\x0")
+        .reject do |f|
+          (f == __FILE__) ||
+            f.match(
+              %r{\A(?:(?:bin|test|spec|features)/|\.(?:git|circleci)|appveyor)}
+            )
+        end
+    end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler"
-  spec.add_development_dependency "rake"
+  # Uncomment to register a new dependency of your gem
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
 end