debug 1.0.0.beta8 → 1.1.0

data/lib/debug/tracer.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module DEBUGGER__
+  class Tracer
+    include SkipPathHelper
+    include Color
+
+    def colorize(str, color)
+      # don't colorize trace sent into a file
+      if @into
+        str
+      else
+        super
+      end
+    end
+
+    attr_reader :type
+
+    def initialize ui, pattern: nil, into: nil
+      if /\ADEBUGGER__::(([A-Z][a-z]+?)[A-Z][a-z]+)/ =~ self.class.name
+        @name = $1
+        @type = $2.downcase
+      end
+
+      setup
+
+      if pattern
+        @pattern = Regexp.compile(pattern)
+      else
+        @pattern = nil
+      end
+
+      if @into = into
+        @output = File.open(into, 'w')
+        @output.puts "PID:#{Process.pid} #{self}"
+      else
+        @output = ui
+      end
+
+      enable
+    end
+
+    def header depth
+      "DEBUGGER (trace/#{@type}) \#th:#{Thread.current.instance_variable_get(:@__thread_client_id)} \#depth:#{'%-2d'%depth}"
+    end
+
+    def enable
+      @tracer.enable
+    end
+
+    def disable
+      @tracer.disable
+    end
+
+    def description
+      nil
+    end
+
+    def to_s
+      s = "#{@name}#{description} (#{@tracer.enabled? ? 'enabled' : 'disabled'})"
+      s += " with pattern #{@pattern.inspect}" if @pattern
+      s += " into: #{@into}" if @into
+      s
+    end
+
+    def skip? tp
+      if tp.path.start_with?(__dir__) ||
+         tp.path.start_with?('<internal:') ||
+         ThreadClient.current.management? ||
+         skip_path?(tp.path) ||
+         skip_with_pattern?(tp)
+        true
+      else
+        false
+      end
+    end
+
+    def skip_with_pattern?(tp)
+      @pattern && !tp.path.match?(@pattern)
+    end
+
+    def out tp, msg = nil, depth = caller.size - 1
+      location_str = colorize("#{tp.path}:#{tp.lineno}", [:GREEN])
+      buff = "#{header(depth)}#{msg} at #{location_str}"
+
+      if false # TODO: Ractor.main?
+        ThreadClient.current.on_trace self.object_id, buff
+      else
+        @output.puts buff
+      end
+    end
+
+    def puts msg
+      @output.puts msg
+    end
+
+    def minfo tp
+      klass = tp.defined_class
+
+      if klass.singleton_class?
+        "#{tp.self}.#{tp.method_id}"
+      else
+        "#{klass}\##{tp.method_id}"
+      end
+    end
+  end
+
+  class LineTracer < Tracer
+    def setup
+      @tracer = TracePoint.new(:line){|tp|
+        next if skip?(tp)
+        # pp tp.object_id, caller(0)
+        out tp
+      }
+    end
+  end
+
+  class CallTracer < Tracer
+    def setup
+      @tracer = TracePoint.new(:a_call, :a_return){|tp|
+        next if skip?(tp)
+
+        depth = caller.size
+        sp = ' ' * depth
+
+        call_identifier_str =
+          if tp.defined_class
+            minfo(tp)
+          else
+            "block"
+          end
+
+        call_identifier_str = colorize_blue(call_identifier_str)
+
+        case tp.event
+        when :call, :c_call, :b_call
+          depth += 1 if tp.event == :c_call
+          out tp, ">#{sp}#{call_identifier_str}", depth
+        when :return, :c_return, :b_return
+          depth += 1 if tp.event == :c_return
+          return_str = colorize_magenta(DEBUGGER__.short_inspect(tp.return_value))
+          out tp, "<#{sp}#{call_identifier_str} #=> #{return_str}", depth
+        end
+      }
+    end
+
+    def skip_with_pattern?(tp)
+      super && !tp.method_id&.match?(@pattern)
+    end
+  end
+
+  class ExceptionTracer < Tracer
+    def setup
+      @tracer = TracePoint.new(:raise) do |tp|
+        next if skip?(tp)
+
+        exc = tp.raised_exception
+
+        out tp, " #{colorize_magenta(exc.inspect)}"
+      rescue Exception => e
+        p e
+      end
+    end
+
+    def skip_with_pattern?(tp)
+      super && !tp.raised_exception.inspect.match?(@pattern)
+    end
+  end
+
+  class ObjectTracer < Tracer
+    def initialize ui, obj_id, obj_inspect, **kw
+      @obj_id = obj_id
+      @obj_inspect = obj_inspect
+      super(ui, **kw)
+    end
+
+    def description
+      " for #{@obj_inspect}"
+    end
+
+    def colorized_obj_inspect
+      colorize_magenta(@obj_inspect)
+    end
+
+    def setup
+      @tracer = TracePoint.new(:a_call){|tp|
+        next if skip?(tp)
+
+        if tp.self.object_id == @obj_id
+          klass = tp.defined_class
+          method = tp.method_id
+          method_info =
+            if klass.singleton_class?
+              if tp.self.is_a?(Class)
+                ".#{method} (#{klass}.#{method})"
+              else
+                ".#{method}"
+              end
+            else
+              "##{method} (#{klass}##{method})"
+            end
+
+          out tp, " #{colorized_obj_inspect} receives #{colorize_blue(method_info)}"
+        else
+          b = tp.binding
+          method_info = colorize_blue(minfo(tp))
+
+          tp.parameters.each{|type, name|
+            next unless name
+
+            colorized_name = colorize_cyan(name)
+
+            case type
+            when :req, :opt, :key, :keyreq
+              if b.local_variable_get(name).object_id == @obj_id
+                out tp, " #{colorized_obj_inspect} is used as a parameter #{colorized_name} of #{method_info}"
+              end
+            when :rest
+              next if name == :"*"
+
+              ary = b.local_variable_get(name)
+              ary.each{|e|
+                if e.object_id == @obj_id
+                  out tp, " #{colorized_obj_inspect} is used as a parameter in #{colorized_name} of #{method_info}"
+                end
+              }
+            when :keyrest
+              next if name == :'**'
+              h = b.local_variable_get(name)
+              h.each{|k, e|
+                if e.object_id == @obj_id
+                  out tp, " #{colorized_obj_inspect} is used as a parameter in #{colorized_name} of #{method_info}"
+                end
+              }
+            end
+          }
+        end
+      }
+    end
+  end
+end
+

data/lib/debug/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DEBUGGER__
-  VERSION = "1.0.0.beta8"
+  VERSION = "1.1.0"
 end

data/misc/README.md.erb

@@ -8,7 +8,7 @@ This debug.rb is replacement of traditional lib/debug.rb standard library which
 New debug.rb has several advantages:
 
 * Fast: No performance penalty on non-stepping mode and non-breakpoints.
-* Remote debugging: Support remote debugging natively.
+* [Remote debugging](#remote-debugging): Support remote debugging natively.
   * UNIX domain socket
   * TCP/IP
   * VSCode/DAP integration ([VSCode rdbg Ruby Debugger - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg))
@@ -20,11 +20,12 @@ New debug.rb has several advantages:
   * Support threads (almost done) and ractors (TODO).
   * Support suspending and entering to the console debugging with `Ctrl-C` at most of timing.
   * Show parameters on backtrace command.
+  * Support recording & reply debugging.
 
 # Installation
 
 ```
-$ gem install debug --pre
+$ gem install debug
 ```
 
 or specify `-Ipath/to/debug/lib` in `RUBYOPT` or each ruby command-line option, especially for debug this gem development.
@@ -32,7 +33,7 @@ or specify `-Ipath/to/debug/lib` in `RUBYOPT` or each ruby command-line option,
 If you use Bundler, write the following line to your Gemfile.
 
 ```
-gem "debug", ">= 1.0.0.beta"
+gem "debug", ">= 1.0.0"
 ```
 
 # HOW TO USE
@@ -43,25 +44,27 @@ To use a debugger, roughly you will do the following steps:
 2. Run a program with the debugger.
 3. At the breakpoint, enter the debugger console.
 4. Use debug commands.
-    * Query the prgram status (e.g. `p lvar` to see the local variable `lvar`).
-    * Control program flow (e.g. move to the another line with `step`, to the next line with `next`).
-    * Set another breakpoints (e.g. `catch Exception` to set the breakpoints when `Exception` is raiesd).
-    * Change the configuration (e.g. `config set no_color true` to disable coloring).
+    * [Evaluate Ruby expressions](#evaluate) (e.g. `p lvar` to see the local variable `lvar`).
+    * [Query the program status](#information) (e.g. `info` to see information about the current frame).
+    * [Control program flow](#control-flow) (e.g. move to the another line with `step`, to the next line with `next`).
+    * [Set another breakpoint](#breakpoint) (e.g. `catch Exception` to set a breakpoint that'll be triggered when `Exception` is raised).
+    * [Activate tracing in your program](#trace) (e.g. `trace call` to trace method calls).
+    * [Change the configuration](#configuration-1) (e.g. `config set no_color true` to disable coloring).
     * Continue the program (`c` or `continue`) and goto 3.
 
 ## Invoke with the debugger
 
 There are several options for (1) and (2). Please choose your favorite way.
 
-### Modify source code as `binding.pry` and `binding.irb`
+### Modify source code with [`binding.break`](#bindingbreak-method) (similar to `binding.pry` or `binding.irb`)
 
-If you can modify the source code, you can use the debugger by adding `require 'debug'` line at the top of your program and putting `binding.break` method (`binding.b` for short) into lines where you want to stop as breakpoints like `binding.pry` and `binding.irb`.
-After that, you run the program as usuall and you will enter the debug console at breakpoints you inserted.
+If you can modify the source code, you can use the debugger by adding `require 'debug'` line at the top of your program and putting [`binding.break`](#bindingbreak-method) method (`binding.b` for short) into lines where you want to stop as breakpoints like `binding.pry` and `binding.irb`.
+After that, you run the program as usual and you will enter the debug console at breakpoints you inserted.
 
-The following example shows the demonstration of `binding.break`.
+The following example shows the demonstration of [`binding.break`](#bindingbreak-method).
 
 ```shell
-$ cat target.rb                        # Sample prgram
+$ cat target.rb                        # Sample program
 require 'debug'
 
 a = 1
@@ -120,13 +123,13 @@ d => 4
 [1, 2, 3, 4]
 ```
 
-### Invoke the prorgam from the debugger as a traditional debuggers
+### Invoke the program from the debugger as a traditional debuggers
 
 If you don't want to modify the source code, you can set breakpoints with a debug command `break` (`b` for short).
 Using `rdbg` command to launch the program without any modifications, you can run the program with the debugger.
 
 ```shell
-$ cat target.rb                        # Sample prgram
+$ cat target.rb                        # Sample program
 a = 1
 b = 2
 c = 3
@@ -241,16 +244,16 @@ NOTE: If you want to use bundler (`bundle` command), you need to write `gem debu
 
 ### Using VSCode
 
-Like other langauges, you can use this debugger on the VSCode.
+Like other languages, you can use this debugger on the VSCode.
 
-1. Install [VSCode rdbg Ruby Debugger - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg) 
+1. Install [VSCode rdbg Ruby Debugger - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg)
 2. Open `.rb` file (e.g. `target.rb`)
 3. Register breakpoints with "Toggle breakpoint" in Run menu (or type F9 key)
 4. Choose "Start debugging" in "Run" menu (or type F5 key)
 5. You will see a dialog "Debug command line" and you can choose your favorite command line your want to run.
-6. Chosed command line is invoked with `rdbg -c` and VSCode shows the details at breakponts.
+6. Chosen command line is invoked with `rdbg -c` and VSCode shows the details at breakpoints.
 
-Plase refer [Debugging in Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging) for operations on VSCode.
+Please refer [Debugging in Visual Studio Code](https://code.visualstudio.com/docs/editor/debugging) for operations on VSCode.
 
 You can configure the extension in `.vscode/launch.json`.
 Please see the extension page for more details.
@@ -265,7 +268,7 @@ You can use this debugger as a remote debugger. For example, it will help the fo
   * Your application uses pipe for STDIN or STDOUT.
 * Your application is running as a daemon and you want to query the running status (checking a backtrace and so on).
 
-You can run your application as a remote debuggee and the remote debugger console can attach to the debugee anytime.
+You can run your application as a remote debuggee and the remote debugger console can attach to the debuggee anytime.
 
 ### Invoke as a remote debuggee
 
@@ -279,10 +282,10 @@ You can run a script with `rdbg --open target.rb` command and run a `target.rb`
 $ exe/rdbg --open target.rb
 DEBUGGER: Session start (pid: 7773)
 DEBUGGER: Debugger can attach via UNIX domain socket (/home/ko1/.ruby-debug-sock/ruby-debug-ko1-7773)
-DEBUGGER: wait for debuger connection...
+DEBUGGER: wait for debugger connection...
 ```
 
-By deafult, `rdbg --open` uses UNIX domain socket and generates path name automatically (`/home/ko1/.ruby-debug-sock/ruby-debug-ko1-7773` in this case).
+By default, `rdbg --open` uses UNIX domain socket and generates path name automatically (`/home/ko1/.ruby-debug-sock/ruby-debug-ko1-7773` in this case).
 
 You can connect to the debuggee with `rdbg --attach` command (`rdbg -A` for short).
 
@@ -309,7 +312,7 @@ NOTE: If you use `quit` command, only remote console exits and the debuggee prog
 
 If you want to use TCP/IP for the remote debugging, you need to specify the port and host with `--port` like `rdbg --open --port 12345` and it binds to `localhost:12345`.
 
-To connect to the debugeee, you need to specify the port.
+To connect to the debuggee, you need to specify the port.
 
 ```shell
 $ rdbg --attach 12345
@@ -324,7 +327,7 @@ If you can modify the program, you can open debugging port by adding `require 'd
 
 If you don't want to stop the program at the beginning, you can also use `require 'debug/open_nonstop'`.
 Using `debug/open_nonstop` is useful if you want to open a backdoor to the application.
-However, it is also danger because it can become antoher vulnerability.
+However, it is also danger because it can become another vulnerability.
 Please use it carefully.
 
 By default, UNIX domain socket is used for the debugging port. To use TCP/IP, you can set the `RUBY_DEBUG_PORT` environment variable.
@@ -336,14 +339,14 @@ $ RUBY_DEBUG_PORT=12345 ruby target.rb
 ## Configuration
 
 You can configure the debugger's behavior with debug commands and environment variables.
-When the debug session is started, initial scripts are loaded so you can put your favorite configurations in the intial scripts.
+When the debug session is started, initial scripts are loaded so you can put your favorite configurations in the initial scripts.
 
 ### Configuration list
 
 You can configure debugger's behavior with environment variables and `config` command. Each configuration has environment variable and the name which can be specified by `config` command.
 
 ```
-# configulation example
+# configuration example
 config set log_level INFO
 config set no_color true
 ```
@@ -355,7 +358,7 @@ config set no_color true
 
 ### Initial scripts
 
-If there is `~/.rdbgrc`, the file is loaded as an initial scripts which contains debug commands) when the debug session is started. 
+If there is `~/.rdbgrc`, the file is loaded as an initial script (which contains debug commands) when the debug session is started.
 
 * `RUBY_DEBUG_INIT_SCRIPT` environment variable can specify the initial script file.
 * You can specify the initial script with `rdbg -x initial_script` (like gdb's `-x` option).
@@ -369,7 +372,12 @@ If there are `~/.rdbgrc.rb` is available, it is also loaded as a ruby script at
 
 On the debug console, you can use the following debug commands.
 
-* `Enter` repeats the last command (useful when repeating `step`s).
+There are additional features:
+
+* `<expr>` without debug command is almost same as `pp <expr>`.
+  * If the input line `<expr>` does *NOT* start with any debug command, the line `<expr>` will be evaluated as a Ruby expression and the result will be printed with `pp` method. So that the input `foo.bar` is same as `pp foo.bar`.
+  * If `<expr>` is recognized as a debug command, of course it is not evaluated as a Ruby expression, but is executed as debug command. For example, you can not evaluate such single letter local variables `i`, `b`, `n`, `c` because they are single letter debug commands. Use `p i` instead.
+* `Enter` without any input repeats the last command (useful when repeating `step`s).
 * `Ctrl-D` is equal to `quit` command.
 * [debug command compare sheet - Google Sheets](https://docs.google.com/spreadsheets/d/1TlmmUDsvwK4sSIyoMv-io52BUUz__R5wpu-ComXlsw0/edit?usp=sharing)
 
@@ -395,7 +403,7 @@ You can start debugging without `rdbg` command by requiring the following librar
 You need to require one of them at the very beginning of the application.
 Using `ruby -r` (for example `ruby -r debug/start target.rb`) is another way to invoke with debugger.
 
-NOTE: Until Ruby 3.0, there is old `lib/debug.rb` standard library. So that if this gem is not installed, or if `Gemfile` missed to list this gem and `bunde exec` is used, you will see the following output:
+NOTE: Until Ruby 3.0, there is old `lib/debug.rb` standard library. So that if this gem is not installed, or if `Gemfile` missed to list this gem and `bundle exec` is used, you will see the following output:
 
 ```shell
 $ ruby -r debug -e0
@@ -411,7 +419,7 @@ Emacs support available.
 
 #### Start by method
 
-After loading `debug/session`, you can start debug session with the following methods. They are convinient if you want to specifies debug configrations in your program.
+After loading `debug/session`, you can start debug session with the following methods. They are convenient if you want to specify debug configurations in your program.
 
 * `DEBUGGER__.start(**kw)`: start debug session with local console.
 * `DEBUGGER__.open(**kw)`: open debug port with configuration (without configurations open with UNIX domain socket)
@@ -436,15 +444,15 @@ If `do: 'command'` is specified, the debugger suspends the program and run the `
 It is useful if you only want to call a debug command and don't want to stop there.
 
 ```
-def initialzie
+def initialize
   @a = 1
   binding.b do: 'watch @a'
 end
 ```
 
-On this case, register a watch breakpont for `@a` and continue to run.
+On this case, register a watch breakpoint for `@a` and continue to run.
 
-If `pre: 'command'` is specified, the debuger suspends the program and run the `command` as a debug command, and keep suspend.
+If `pre: 'command'` is specified, the debugger suspends the program and run the `command` as a debug command, and keep suspend.
 It is useful if you have operations before suspend.
 
 ```
@@ -454,7 +462,7 @@ def foo
 end
 ```
 
-On this case, you can see the result of `bar()` everytime when you stops there.
+On this case, you can see the result of `bar()` every time you stop there.
 
 ## rdbg command help