debug 1.10.0 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0abb44ebe9baa650e6fe0b811044aa50a5d3f7cf0636579ae4991193cf1467ec
-  data.tar.gz: 5decf010f8c581a30fe2543f6118541d0a34768b0d4f83451a728c47eeb6321c
+  metadata.gz: fc4d6aa4412830633b73eebc239b7b27b17f100965bf4d8b916ce3f6311dfcbb
+  data.tar.gz: 11180fe8d9c9d3c9b170b6e817a39c6020dbfa831631a8bad9dc6d69d6a6235e
 SHA512:
-  metadata.gz: 1aad7e61ccedcb91f208a6edd92e0a255d8fb9e564b3b72dafceebbd88aff37b03500b63dc2e375874d27d7ad3767f174d70d3679cb3c47f31e29270952a5999
-  data.tar.gz: 87d2cf298f30052fb0b4f91abea28d5310d7a235173ef04deb3dd27a66c1b9016add6714a2ff29a6483670a5b3245b38091d0a437ede4db61a0a0d45ecfcb773
+  metadata.gz: 0f7c076a9affef363d2a04b31484be5dd904bd750ec1a567adabbdaee0cf9a91bc162e564f504ae67711b5940aa34541300c56b81b60a6078b15296ebff2a72a
+  data.tar.gz: b912627acde3296f2e0701cf9a087d5f626181e04c994994a7ac9943ea38736734d4c2197f795573ca814fcface4c61b330f665aaa4c614f74bf1bfb85c7cb4f

data/README.md

@@ -16,38 +16,38 @@ New debug.rb has several advantages:
      | Frontend    | [Console](https://github.com/ruby/debug#invoke-as-a-remote-debuggee) | [VSCode](https://github.com/ruby/debug#vscode-integration)                                  | [Chrome DevTool](#chrome-devtool-integration) |
      | ----------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------- |
      | Connection  | UDS, TCP/IP                                                          | UDS, TCP/IP                                                                                 | TCP/IP                                        |
-     | Requirement | No                                                                   | [vscode-rdbg](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg) | Chrome                                        |
+     | Requirement | None                                                                 | [vscode-rdbg](https://marketplace.visualstudio.com/items?itemName=KoichiSasada.vscode-rdbg) | Chrome                                        |
 
 * Extensible: application can introduce debugging support in several ways:
   * By `rdbg` command
   * By loading libraries with `-r` command line option
   * By calling Ruby's method explicitly
 * Misc
-  * Support threads (almost done) and ractors (TODO).
-  * Support suspending and entering to the console debugging with `Ctrl-C` at most of timing.
+  * Support threads (almost done) and Ractors (TODO).
+  * Support suspending and entering the debug console with `Ctrl-C` at most of timing.
   * Show parameters on backtrace command.
-  * Support recording & replay debugging.
+  * Support recording and replay debugging.
 
 # Installation
 
-```
+```console
 $ gem install debug
 ```
 
-or specify `-Ipath/to/debug/lib` in `RUBYOPT` or each ruby command-line option, especially for debug this gem development.
+Alternatively, specify `-Ipath/to/debug/lib` in `RUBYOPT`, or as a Ruby command-line option
+This is especially useful for debugging this gem during development.
 
-If you use Bundler, write the following line to your Gemfile.
+If using Bundler, add the following to your Gemfile:
 
-```
+```ruby
 gem "debug", ">= 1.0.0"
 ```
 
-(The version constraint is important; `debug < 1.0.0` is an older,
-abandoned gem that is completely different from this product.)
+(The version constraint is important; `debug < 1.0.0` is an older, abandoned gem that is completely different from this product.)
 
 # HOW TO USE
 
-To use a debugger, roughly you will do the following steps:
+To use the debugger, you will do roughly the following steps:
 
 1. Set breakpoints.
 2. Run a program with the debugger.
@@ -63,22 +63,23 @@ To use a debugger, roughly you will do the following steps:
 
 ## Invoke with the debugger
 
-There are several options for (1) and (2). Please choose your favorite way.
+There are several ways to invoke the debugger, depending on your needs, preferences, and the environment.
 
 ### 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'` at the top of your program and putting [`binding.break`](#bindingbreak-method) method into lines where you want to stop as breakpoints like `binding.pry` and `binding.irb`.
+If you can modify the source code, you can use the debugger by adding `require 'debug'` at the top of your program and putting [`binding.break`](#bindingbreak-method) method into lines where you want to stop as breakpoints.
+This is similar to how `binding.pry` and `binding.irb` work.
 
-You can also use its 2 aliases in the same way:
+`binding.break` has two aliases which do the same thing:
 
 - `binding.b`
 - `debugger`
 
 After that, 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`](#bindingbreak-method).
+The following is an example of the [`binding.break`](#bindingbreak-method) method.
 
-```shell
+```console
 $ cat target.rb                        # Sample program
 require 'debug'
 
@@ -140,10 +141,11 @@ d => 4
 
 ### 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 (or `bundle exec rdbg`) to launch the program without any modifications, you can run the program with the debugger.
+If you don't want to modify the source code, you can use the `rdbg` command (or `bundle exec rdbg`) to run the program with the debugger.
+This is similar to how you'd launch a program with `ruby program.rb`.
+Then you can set breakpoints with the debug command `break` (`b` for short).
 
-```shell
+```console
 $ cat target.rb                        # Sample program
 a = 1
 b = 2
@@ -166,9 +168,11 @@ DEBUGGER: Session start (pid: 7656)
 (rdbg)
 ```
 
-`rdbg` command suspends the program at the beginning of the given script (`target.rb` in this case) and you can use debug commands. `(rdbg)` is prompt. Let's set breakpoints on line 3 and line 5 with `break` command (`b` for short).
+The `rdbg` command suspends the program at the beginning of the given script (`target.rb` in this case) and you can use debug commands to control execution from there.
+`(rdbg)` is the console prompt.
+Let's set breakpoints on line 3 and line 5 with `break` command (`b` for short).
 
-```shell
+```console
 (rdbg) break 3                         # set breakpoint at line 3
 #0  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
 
@@ -180,9 +184,10 @@ DEBUGGER: Session start (pid: 7656)
 #1  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:5 (line)
 ```
 
-You can see that two breakpoints are registered. Let's continue the program by using the `continue` command.
+You can see that two breakpoints are registered.
+Let's continue the program by using the `continue` command.
 
-```shell
+```console
 (rdbg) continue
 [1, 7] in target.rb
       1| a = 1
@@ -199,11 +204,11 @@ Stop by #0  BP - Line  /mnt/c/ko1/src/rb/ruby-debug/target.rb:3 (line)
 (rdbg)
 ```
 
-You can see that we can stop at line 3.
-Let's see the local variables with the `info` command, and continue.
-You can also confirm that the program will suspend at line 5 and you can use the `info` command again.
+You can see that we stopped at line 3.
+Let's see the local variables with the `info` command, and continue execution with the `continue`.
+The program will then suspend at line 5 and you can use the `info` command again.
 
-```shell
+```console
 (rdbg) info
 =>#0    <main> at target.rb:3
 %self => main
@@ -237,25 +242,28 @@ d => 4
 [1, 2, 3, 4]
 ```
 
-By the way, using `rdbg` command you can suspend your application with `C-c` (SIGINT) and enter the debug console.
+NOTE: When using `rdbg` you can suspend your application with `C-c` (SIGINT) and enter the debug console.
 It will help if you want to know what the program is doing.
 
 ### Use `rdbg` with commands written in Ruby
 
-If you want to run a command written in Ruby like `rake`, `rails`, `bundle`, `rspec`, and so on, you can use `rdbg -c` option.
+If you want to run an executable written in Ruby like `rake`, `rails`, `bundle`, `rspec`, and so on, you can use `rdbg -c` option.
 
-* Without the `-c` option, `rdbg <name>` means that `<name>` is a Ruby script and invokes it like `ruby <name>` with the debugger.
-* With the `-c` option, `rdbg -c <name>` means that `<name>` is a command in `PATH` and simply invokes it with the debugger.
+* Without the `-c` option, `rdbg <name>` means that `<name>` is a Ruby script and it is invoked like `ruby <name>` with the debugger.
+* With the `-c` option, `rdbg -c <name>` means that `<name>` is an executable in `PATH` and simply invokes it with the debugger.
 
 Examples:
+
 * `rdbg -c -- rails server`
 * `rdbg -c -- bundle exec ruby foo.rb`
 * `rdbg -c -- bundle exec rake test`
 * `rdbg -c -- ruby target.rb` is the same as `rdbg target.rb`
 
-NOTE: `--` is needed to separate the command line options for `rdbg` and the invoking command. For example, `rdbg -c rake -T` is recognized like `rdbg -c -T -- rake`. It should be `rdbg -c -- rake -T`.
+NOTE: `--` is needed to separate the command line options for `rdbg` from the executable being invoked, and its options.
+For example, `rdbg -c rake -T` would be parsed as `rdbg -c -T -- rake`, which is incorrect.
+It should be `rdbg -c -- rake -T`.
 
-NOTE: If you want to use bundler (`bundle` command), you need to write `gem debug` line in your `Gemfile`.
+NOTE: If you want to use Bundler (`bundle` executable), you need to add `gem 'debug'` to your `Gemfile`.
 
 ### Using VSCode
 
@@ -275,12 +283,13 @@ Please see the extension page for more details.
 
 ## Remote debugging
 
-You can use this debugger as a remote debugger. For example, it will help in the following situations:
+You can use this debugger as a remote debugger.
+For example, it will help in the following situations:
 
 * Your application does not run on TTY, and it is hard to use `binding.pry` or `binding.irb`.
   * Your application is running on a Docker container, and there is no TTY.
   * Your application is running as a daemon.
-  * Your application uses pipe for STDIN or STDOUT.
+  * 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 debuggee anytime.
@@ -296,10 +305,11 @@ There are multiple ways to run your program as a debuggee:
 
 #### `rdbg --open` (or `rdbg -O` for short)
 
-You can run a script with `rdbg --open target.rb` command and run a `target.rb` as a debuggee program. It also opens the network port and suspends at the beginning of `target.rb`.
+Launch a script with `rdbg --open target.rb` to run `target.rb` as a debuggee program.
+It also opens the network port and suspends at the beginning of `target.rb`.
 
-```shell
-$ exe/rdbg --open target.rb
+```console
+$ 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 debugger connection...
@@ -309,7 +319,7 @@ By default, `rdbg --open` uses UNIX domain socket and generates the path name au
 
 You can connect to the debuggee with `rdbg --attach` command (`rdbg -A` for short).
 
-```shell
+```console
 $ rdbg -A
 [1, 7] in target.rb
 =>    1| a = 1
@@ -324,37 +334,41 @@ $ rdbg -A
 (rdbg:remote)
 ```
 
-If there are no other opening ports on the default directory, `rdbg --attach` command chooses the only one opening UNIX domain socket and connects to it. If there are more files, you need to specify the file.
+If there are no other files in the default directory, `rdbg --attach` will automatically connect to the UNIX domain socket listed.
+If there are multiple files, you need to specify which to use.
 
-When `rdbg --attach` connects to the debuggee, you can use any debug commands (set breakpoints, continue the program, and so on) like the local debug console. When a debuggee program exits, the remote console will also terminate.
+When `rdbg --attach` connects to the debuggee, you can use any debug commands (set breakpoints, continue the program, and so on) like the local debug console.
+When a debuggee program exits, the remote console will also terminate.
 
-NOTE: If you use the `quit` command, only the remote console exits and the debuggee program continues to run (and you can connect it again). If you want to exit the debuggee program, use `kill` command.
+NOTE: If you use the `quit` command, only the remote console exits and the debuggee program continues to run (and you can connect it again).
+If you want to exit the debuggee program, use `kill` command.
 
-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`. You can add an optional `--port_range` option to try multiple ports in a reliable way. For example, `rdbg --open --port 12345 --port_range 10` will try to bind to 12345, 12346, 12347, ... until it finds an available port.
-
-```shell
+If you want to use TCP/IP for remote debugging, you need to specify the port and host with `--port` like `rdbg --open --port 12345` and it binds to `localhost:12345`.
+You can add an optional `--port_range` to try multiple ports in a reliable way.
+For example, `rdbg --open --port 12345 --port_range 10` will try to bind to 12345, 12346, 12347,… until it finds an available port.
 
 To connect to the debuggee, you need to specify the port.
 
-```shell
+```console
 $ rdbg --attach 12345
 ```
 
 If you want to choose the host to bind, you can use `--host` option.
-Note that all messages communicated between the debugger and the debuggee are *NOT* encrypted so please use remote debugging carefully.
+Messages communicated between the debugger and the debuggee are *NOT* encrypted so please use remote debugging carefully.
 
 #### `require 'debug/open'` in a program
 
-If you can modify the program, you can open the debugging port by adding `require 'debug/open'` line in the program.
+If you can modify the program, you can open the debugging port by adding `require 'debug/open'` in the program.
 
 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 dangerous 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.
+By default, UNIX domain socket is used for the debugging port.
+To use TCP/IP, you can set the `RUBY_DEBUG_PORT` environment variable.
 
-```shell
+```console
 $ RUBY_DEBUG_PORT=12345 ruby target.rb
 ```
 
@@ -366,9 +380,7 @@ You can attach with external debugger frontend with VSCode and Chrome.
 $ rdbg --open=[frontend] target.rb
 ```
 
-will open a debug port and `[frontend]` can attach to the port.
-
-Also `open` command allows opening the debug port.
+This will open a debug port and the `[frontend]` can attach to the port.
 
 #### VSCode integration
 
@@ -376,9 +388,9 @@ Also `open` command allows opening the debug port.
 
 If you don't run a debuggee Ruby process on VSCode, you can attach it to VSCode later with the following steps.
 
-`rdbg --open=vscode` opens the debug port and tries to invoke the VSCode (`code` command).
+`rdbg --open=vscode` opens the debug port and tries to invoke the VSCode (`code` executable).
 
-```
+```console
 $ rdbg --open=vscode target.rb
 DEBUGGER: Debugger can attach via UNIX domain socket (/tmp/ruby-debug-sock-1000/ruby-debug-ko1-27706)
 DEBUGGER: wait for debugger connection...
@@ -386,11 +398,11 @@ Launching: code /tmp/ruby-debug-vscode-20211014-27706-gd7e85/ /tmp/ruby-debug-vs
 DEBUGGER: Connected.
 ```
 
-And it tries to invoke the new VSCode window and VSCode starts attaching to the debuggee Ruby program automatically.
+It tries to invoke the new VSCode window and VSCode will attach to the debuggee Ruby program automatically.
 
-You can also use `open vscode` command in REPL.
+You can also use `open vscode` in a REPL.
 
-```
+```console
 $ rdbg target.rb
 [1, 8] in target.rb
      1|
@@ -409,9 +421,9 @@ Launching: code /tmp/ruby-debug-vscode-20211014-28337-kg9dm/ /tmp/ruby-debug-vsc
 DEBUGGER: Connected.
 ```
 
-If the machine which runs the Ruby process doesn't have a `code` command, the following message will be shown:
+If the machine which runs the Ruby process doesn't have a `code` executable on `$PATH`, the following message will be shown:
 
-```
+```console
 (rdbg) open vscode
 DEBUGGER: wait for debugger connection...
 DEBUGGER: Debugger can attach via UNIX domain socket (/tmp/ruby-debug-sock-1000/ruby-debug-ko1-455)
@@ -427,15 +439,13 @@ If your application is running on a SSH remote host, please try:
 
 ```
 
-and try to use the proposed commands.
-
 Note that you can attach with `rdbg --attach` and continue REPL debugging.
 
 #### Chrome DevTool integration
 
-With `rdbg --open=chrome` command will show the following message.
+Using `rdbg --open=chrome` will show the following message:
 
-```
+```console
 $ rdbg target.rb --open=chrome
 DEBUGGER: Debugger can attach via TCP/IP (127.0.0.1:43633)
 DEBUGGER: With Chrome browser, type the following URL in the address-bar:
@@ -445,20 +455,25 @@ DEBUGGER: With Chrome browser, type the following URL in the address-bar:
 DEBUGGER: wait for debugger connection...
 ```
 
-Type `devtools://devtools/bundled/inspector.html?v8only=true&panel=sources&ws=127.0.0.1:57231/b32a55cd-2eb5-4c5c-87d8-b3dfc59d80ef` in the address bar on Chrome browser, and you can continue the debugging with chrome browser.
+Type the following in the address bar on Chrome browser, and you can continue the debugging with chrome browser:
+
+```txt
+devtools://devtools/bundled/inspector.html?v8only=true&panel=sources&ws=127.0.0.1:57231/b32a55cd-2eb5-4c5c-87d8-b3dfc59d80ef`
+```
 
-Also `open chrome` command works like `open vscode`.
+Similar to VSCode, you can use `open chrome` to open the debugger in Chrome.
 
-For more information about how to use Chrome debugging, you might want to read [here](https://developer.chrome.com/docs/devtools/).
+For more information about how to use Chrome debugging, [see the devtools docs](https://developer.chrome.com/docs/devtools/).
 
 ## 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 initial scripts.
+When the debug session is started, some [initialization scripts](#initial-scripts) (e.g., `~/.rdbgrc`) are loaded, allowing you to configure the debugger's behavior to your needs and preferences.
 
 ### Configuration list
 
-You can configure the debugger's behavior with environment variables and `config` command. Each configuration has an environment variable and a name which can be specified by `config` command.
+You can configure the debugger's behavior with environment variables and `config` command.
+Each configuration has an environment variable and a name which can be specified by `config` command.
 
 ```
 # configuration example
@@ -471,6 +486,7 @@ config set no_color true
 * UI
   * `RUBY_DEBUG_LOG_LEVEL` (`log_level`): Log level same as Logger (default: WARN)
   * `RUBY_DEBUG_SHOW_SRC_LINES` (`show_src_lines`): Show n lines source code on breakpoint (default: 10)
+  * `RUBY_DEBUG_SHOW_SRC_LINES_FRAME` (`show_src_lines_frame`): Show n lines source code on frame operations (default: 1)
   * `RUBY_DEBUG_SHOW_EVALEDSRC` (`show_evaledsrc`): Show actually evaluated source (default: false)
   * `RUBY_DEBUG_SHOW_FRAMES` (`show_frames`): Show n frames on breakpoint (default: 2)
   * `RUBY_DEBUG_USE_SHORT_PATH` (`use_short_path`): Show shorten PATH (like $(Gem)/foo.rb) (default: false)
@@ -479,6 +495,7 @@ config set no_color true
   * `RUBY_DEBUG_NO_RELINE` (`no_reline`): Do not use Reline library (default: false)
   * `RUBY_DEBUG_NO_HINT` (`no_hint`): Do not show the hint on the REPL (default: false)
   * `RUBY_DEBUG_NO_LINENO` (`no_lineno`): Do not show line numbers (default: false)
+  * `RUBY_DEBUG_NO_REPEAT` (`no_repeat`): Do not repeat last line when empty line (default: false)
   * `RUBY_DEBUG_IRB_CONSOLE` (`irb_console`): Use IRB as the console (default: false)
 
 * CONTROL
@@ -495,7 +512,7 @@ config set no_color true
   * `RUBY_DEBUG_INIT_SCRIPT` (`init_script`): debug command script path loaded at first stop
   * `RUBY_DEBUG_COMMANDS` (`commands`): debug commands invoked at first stop. Commands should be separated by `;;`
   * `RUBY_DEBUG_NO_RC` (`no_rc`): ignore loading ~/.rdbgrc(.rb) (default: false)
-  * `RUBY_DEBUG_HISTORY_FILE` (`history_file`): history file (default: ~/.rdbg_history)
+  * `RUBY_DEBUG_HISTORY_FILE` (`history_file`): history file (default: ${XDG_STATE_HOME-~/.local/state}/rdbg/history)
   * `RUBY_DEBUG_SAVE_HISTORY` (`save_history`): maximum save history lines (default: 10000)
 
 * REMOTE
@@ -524,7 +541,7 @@ There are other environment variables:
 
 ### Initial scripts
 
-If there is `~/.rdbgrc`, the file is loaded as an initial script (which contains debug commands) when the debug session is started.
+If there is a `~/.rdbgrc` file it is loaded as an initialization 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).
@@ -532,7 +549,7 @@ If there is `~/.rdbgrc`, the file is loaded as an initial script (which contains
 Initial scripts are useful to write your favorite configurations.
 For example, you can set breakpoints with `break file:123` in `~/.rdbgrc`.
 
-If there are `~/.rdbgrc.rb` is available, it is also loaded as a ruby script at same timing.
+If there is a `~/.rdbgrc.rb` file it is also loaded as a Ruby script when the debug session is started.
 
 ## Debug command on the debug console
 
@@ -541,16 +558,19 @@ On the debug console, you can use the following debug commands.
 There are additional features:
 
 * `<expr>` without debug command is almost the 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 the 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.
-  * So the author (Koichi Sasada) recommends using `p`, `pp` or `eval` command to evaluate the Ruby expression every time.
+  * 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 the 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.
+  * For consistency, the author (Koichi Sasada) recommends using the `p`, `pp`, or `eval` command to evaluate the Ruby expression every time.
 * `Enter` without any input repeats the last command (useful when repeating `step`s) for some commands.
 * `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)
 
-You can use the following debug commands. Each command should be written in 1 line.
-The `[...]` notation means this part can be eliminated. For example, `s[tep]` means `s` or `step` is a valid command. `ste` is not valid.
-The `<...>` notation means the argument.
+You can use the following debug commands.
+Each command should be written in 1 line.
+The `[…]` notation means this part can be eliminated. For example, `s[tep]` means `s` or `step` is a valid command. `ste` is not valid.
+The `<…>` notation means the argument.
 
 ### Control flow
 
@@ -800,7 +820,7 @@ To switch to the IRB console, simply use the `irb` command in the debug console.
 
 Once activated, you'll notice the prompt changes to:
 
-```txt
+```console
 irb:rdbg(main):001>
 ```
 
@@ -827,9 +847,12 @@ 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 `bundle exec` is used, you will see the following output:
+NOTE: Until Ruby 3.0, there is old `lib/debug.rb` in the standard library.
+`lib/debug.rb` was not maintained well in recent years, and the purpose of this library is to rewrite old `lib/debug.rb` with recent techniques.
+
+So, if this gem is not installed, or if the `Gemfile` doesn't include this gem and `bundle exec` is used, you will see the following output:
 
-```shell
+```console
 $ ruby -r debug -e0
 .../2.7.3/lib/ruby/2.7.0/x86_64-linux/continuation.so: warning: callcc is obsolete; use Fiber instead
 Debug.rb
@@ -839,16 +862,15 @@ Emacs support available.
 (rdb:1)
 ```
 
-`lib/debug.rb` was not maintained well in recent years, and the purpose of this library is to rewrite old `lib/debug.rb` with recent techniques.
-
 #### Start by method
 
-After loading `debug/session`, you can start a debug session with the following methods. They are convenient if you want to specify debug configurations in your program.
+After loading `debug/session`, you can start a 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)
-* `DEBUGGER__.open_unix(**kw)`: open debug port with UNIX domain socket
-* `DEBUGGER__.open_tcp(**kw)`: open debug port with TCP/IP
+* `DEBUGGER__.open(**kw)`: open debug port with configuration (without configurations open with UNIX domain socket).
+* `DEBUGGER__.open_unix(**kw)`: open debug port with UNIX domain socket.
+* `DEBUGGER__.open_tcp(**kw)`: open debug port with TCP/IP.
 
 For example:
 
@@ -862,24 +884,28 @@ DEBUGGER__.start(no_color: true,    # disable colorize
 
 ### `binding.break` method
 
-`binding.break` (or `binding.b`) set breakpoints at the written line. It also has several keywords.
+`binding.break` (or `binding.b`) sets a breakpoint at that line.
+It also has several keywords.
 
 If `do: 'command'` is specified, the debugger suspends the program, runs the `command` as a debug command, and continues the program.
 It is useful if you only want to call a debug command and don't want to stop there.
+For example:
 
-```
+```ruby
 def initialize
   @a = 1
   binding.b do: 'info \n watch @a'
 end
 ```
 
-In this case, execute the `info` command then register a watch breakpoint for `@a` and continue to run. You can also use `;;` instead of `\n` to separate your commands.
+In this case, execute the `info` command, then register a watch breakpoint for `@a` and continue to run.
+You can also use `;;` instead of `\n` to separate your commands.
 
 If `pre: 'command'` is specified, the debugger suspends the program and runs the `command` as a debug command, and keeps suspended.
 It is useful if you have operations before suspend.
+For example:
 
-```
+```ruby
 def foo
   binding.b pre: 'p bar()'
   ...
@@ -890,7 +916,7 @@ In this case, you can see the result of `bar()` every time you stop there.
 
 ## rdbg command help
 
-```
+```console
 exe/rdbg [options] -- [debuggee options]
 
 Debug console mode:
@@ -959,7 +985,7 @@ NOTE
 
 # Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/debug.
+Bug reports and pull requests are welcome on GitHub at [https://github.com/ruby/debug]().
 This debugger is not mature so your feedback will help us.
 
 Please also check the [contributing guideline](/CONTRIBUTING.md).

data/lib/debug/config.rb

@@ -12,50 +12,52 @@ module DEBUGGER__
 
   CONFIG_SET = {
     # UI setting
-    log_level:      ['RUBY_DEBUG_LOG_LEVEL',      "UI: Log level same as Logger",               :loglevel, "WARN"],
-    show_src_lines: ['RUBY_DEBUG_SHOW_SRC_LINES', "UI: Show n lines source code on breakpoint", :int, "10"],
-    show_evaledsrc: ['RUBY_DEBUG_SHOW_EVALEDSRC', "UI: Show actually evaluated source",         :bool, "false"],
-    show_frames:    ['RUBY_DEBUG_SHOW_FRAMES',    "UI: Show n frames on breakpoint",            :int, "2"],
-    use_short_path: ['RUBY_DEBUG_USE_SHORT_PATH', "UI: Show shorten PATH (like $(Gem)/foo.rb)", :bool, "false"],
-    no_color:       ['RUBY_DEBUG_NO_COLOR',       "UI: Do not use colorize",                    :bool, "false"],
-    no_sigint_hook: ['RUBY_DEBUG_NO_SIGINT_HOOK', "UI: Do not suspend on SIGINT",               :bool, "false"],
-    no_reline:      ['RUBY_DEBUG_NO_RELINE',      "UI: Do not use Reline library",              :bool, "false"],
-    no_hint:        ['RUBY_DEBUG_NO_HINT',        "UI: Do not show the hint on the REPL",       :bool, "false"],
-    no_lineno:      ['RUBY_DEBUG_NO_LINENO',      "UI: Do not show line numbers",               :bool, "false"],
-    irb_console:    ["RUBY_DEBUG_IRB_CONSOLE",    "UI: Use IRB as the console",                 :bool, "false"],
+    log_level:           ['RUBY_DEBUG_LOG_LEVEL',      "UI: Log level same as Logger",               :loglevel, "WARN"],
+    show_src_lines:      ['RUBY_DEBUG_SHOW_SRC_LINES', "UI: Show n lines source code on breakpoint", :int, "10"],
+    show_src_lines_frame:['RUBY_DEBUG_SHOW_SRC_LINES_FRAME', "UI: Show n lines source code on frame operations", :int, "1"],
+    show_evaledsrc:      ['RUBY_DEBUG_SHOW_EVALEDSRC', "UI: Show actually evaluated source",         :bool, "false"],
+    show_frames:         ['RUBY_DEBUG_SHOW_FRAMES',    "UI: Show n frames on breakpoint",            :int, "2"],
+    use_short_path:      ['RUBY_DEBUG_USE_SHORT_PATH', "UI: Show shorten PATH (like $(Gem)/foo.rb)", :bool, "false"],
+    no_color:            ['RUBY_DEBUG_NO_COLOR',       "UI: Do not use colorize",                    :bool, "false"],
+    no_sigint_hook:      ['RUBY_DEBUG_NO_SIGINT_HOOK', "UI: Do not suspend on SIGINT",               :bool, "false"],
+    no_reline:           ['RUBY_DEBUG_NO_RELINE',      "UI: Do not use Reline library",              :bool, "false"],
+    no_hint:             ['RUBY_DEBUG_NO_HINT',        "UI: Do not show the hint on the REPL",       :bool, "false"],
+    no_lineno:           ['RUBY_DEBUG_NO_LINENO',      "UI: Do not show line numbers",               :bool, "false"],
+    no_repeat:           ['RUBY_DEBUG_NO_REPEAT',      "UI: Do not repeat last line when empty line",:bool, "false"],
+    irb_console:         ["RUBY_DEBUG_IRB_CONSOLE",    "UI: Use IRB as the console",                 :bool, "false"],
 
     # control setting
-    skip_path:      ['RUBY_DEBUG_SKIP_PATH',      "CONTROL: Skip showing/entering frames for given paths", :path],
-    skip_nosrc:     ['RUBY_DEBUG_SKIP_NOSRC',     "CONTROL: Skip on no source code lines",              :bool, "false"],
-    keep_alloc_site:['RUBY_DEBUG_KEEP_ALLOC_SITE',"CONTROL: Keep allocation site and p, pp shows it",   :bool, "false"],
-    postmortem:     ['RUBY_DEBUG_POSTMORTEM',     "CONTROL: Enable postmortem debug",                   :bool, "false"],
-    fork_mode:      ['RUBY_DEBUG_FORK_MODE',      "CONTROL: Control which process activates a debugger after fork (both/parent/child)", :forkmode, "both"],
-    sigdump_sig:    ['RUBY_DEBUG_SIGDUMP_SIG',    "CONTROL: Sigdump signal", :bool, "false"],
+    skip_path:           ['RUBY_DEBUG_SKIP_PATH',      "CONTROL: Skip showing/entering frames for given paths", :path],
+    skip_nosrc:          ['RUBY_DEBUG_SKIP_NOSRC',     "CONTROL: Skip on no source code lines",              :bool, "false"],
+    keep_alloc_site:     ['RUBY_DEBUG_KEEP_ALLOC_SITE',"CONTROL: Keep allocation site and p, pp shows it",   :bool, "false"],
+    postmortem:          ['RUBY_DEBUG_POSTMORTEM',     "CONTROL: Enable postmortem debug",                   :bool, "false"],
+    fork_mode:           ['RUBY_DEBUG_FORK_MODE',      "CONTROL: Control which process activates a debugger after fork (both/parent/child)", :forkmode, "both"],
+    sigdump_sig:         ['RUBY_DEBUG_SIGDUMP_SIG',    "CONTROL: Sigdump signal", :bool, "false"],
 
     # boot setting
-    nonstop:        ['RUBY_DEBUG_NONSTOP',     "BOOT: Nonstop mode",                                                :bool, "false"],
-    stop_at_load:   ['RUBY_DEBUG_STOP_AT_LOAD',"BOOT: Stop at just loading location",                               :bool, "false"],
-    init_script:    ['RUBY_DEBUG_INIT_SCRIPT', "BOOT: debug command script path loaded at first stop"],
-    commands:       ['RUBY_DEBUG_COMMANDS',    "BOOT: debug commands invoked at first stop. Commands should be separated by `;;`"],
-    no_rc:          ['RUBY_DEBUG_NO_RC',       "BOOT: ignore loading ~/.rdbgrc(.rb)",                               :bool, "false"],
-    history_file:   ['RUBY_DEBUG_HISTORY_FILE',"BOOT: history file",               :string, "~/.rdbg_history"],
-    save_history:   ['RUBY_DEBUG_SAVE_HISTORY',"BOOT: maximum save history lines", :int, "10000"],
+    nonstop:             ['RUBY_DEBUG_NONSTOP',     "BOOT: Nonstop mode",                                                :bool, "false"],
+    stop_at_load:        ['RUBY_DEBUG_STOP_AT_LOAD',"BOOT: Stop at just loading location",                               :bool, "false"],
+    init_script:         ['RUBY_DEBUG_INIT_SCRIPT', "BOOT: debug command script path loaded at first stop"],
+    commands:            ['RUBY_DEBUG_COMMANDS',    "BOOT: debug commands invoked at first stop. Commands should be separated by `;;`"],
+    no_rc:               ['RUBY_DEBUG_NO_RC',       "BOOT: ignore loading ~/.rdbgrc(.rb)",                               :bool, "false"],
+    history_file:        ['RUBY_DEBUG_HISTORY_FILE',"BOOT: history file (default: ${XDG_STATE_HOME-~/.local/state}/rdbg/history)",        :string, nil],
+    save_history:        ['RUBY_DEBUG_SAVE_HISTORY',"BOOT: maximum save history lines", :int, "10000"],
 
     # remote setting
-    open:           ['RUBY_DEBUG_OPEN',         "REMOTE: Open remote port (same as `rdbg --open` option)"],
-    port:           ['RUBY_DEBUG_PORT',         "REMOTE: TCP/IP remote debugging: port"],
-    port_range:     ['RUBY_DEBUG_PORT_RANGE',   "REMOTE: TCP/IP remote debugging: length of port range"],
-    host:           ['RUBY_DEBUG_HOST',         "REMOTE: TCP/IP remote debugging: host", :string, "127.0.0.1"],
-    sock_path:      ['RUBY_DEBUG_SOCK_PATH',    "REMOTE: UNIX Domain Socket remote debugging: socket path"],
-    sock_dir:       ['RUBY_DEBUG_SOCK_DIR',     "REMOTE: UNIX Domain Socket remote debugging: socket directory"],
-    local_fs_map:   ['RUBY_DEBUG_LOCAL_FS_MAP', "REMOTE: Specify local fs map", :path_map],
-    skip_bp:        ['RUBY_DEBUG_SKIP_BP',      "REMOTE: Skip breakpoints if no clients are attached", :bool, 'false'],
-    cookie:         ['RUBY_DEBUG_COOKIE',       "REMOTE: Cookie for negotiation"],
-    session_name:   ['RUBY_DEBUG_SESSION_NAME', "REMOTE: Session name for differentiating multiple sessions"],
-    chrome_path:    ['RUBY_DEBUG_CHROME_PATH',  "REMOTE: Platform dependent path of Chrome (For more information, See [here](https://github.com/ruby/debug/pull/334/files#diff-5fc3d0a901379a95bc111b86cf0090b03f857edfd0b99a0c1537e26735698453R55-R64))"],
+    open:                ['RUBY_DEBUG_OPEN',         "REMOTE: Open remote port (same as `rdbg --open` option)"],
+    port:                ['RUBY_DEBUG_PORT',         "REMOTE: TCP/IP remote debugging: port"],
+    port_range:          ['RUBY_DEBUG_PORT_RANGE',   "REMOTE: TCP/IP remote debugging: length of port range"],
+    host:                ['RUBY_DEBUG_HOST',         "REMOTE: TCP/IP remote debugging: host", :string, "127.0.0.1"],
+    sock_path:           ['RUBY_DEBUG_SOCK_PATH',    "REMOTE: UNIX Domain Socket remote debugging: socket path"],
+    sock_dir:            ['RUBY_DEBUG_SOCK_DIR',     "REMOTE: UNIX Domain Socket remote debugging: socket directory"],
+    local_fs_map:        ['RUBY_DEBUG_LOCAL_FS_MAP', "REMOTE: Specify local fs map", :path_map],
+    skip_bp:             ['RUBY_DEBUG_SKIP_BP',      "REMOTE: Skip breakpoints if no clients are attached", :bool, 'false'],
+    cookie:              ['RUBY_DEBUG_COOKIE',       "REMOTE: Cookie for negotiation"],
+    session_name:        ['RUBY_DEBUG_SESSION_NAME', "REMOTE: Session name for differentiating multiple sessions"],
+    chrome_path:         ['RUBY_DEBUG_CHROME_PATH',  "REMOTE: Platform dependent path of Chrome (For more information, See [here](https://github.com/ruby/debug/pull/334/files#diff-5fc3d0a901379a95bc111b86cf0090b03f857edfd0b99a0c1537e26735698453R55-R64))"],
 
     # obsolete
-    parent_on_fork: ['RUBY_DEBUG_PARENT_ON_FORK', "OBSOLETE: Keep debugging parent process on fork",     :bool, "false"],
+    parent_on_fork:      ['RUBY_DEBUG_PARENT_ON_FORK', "OBSOLETE: Keep debugging parent process on fork",     :bool, "false"],
   }.freeze
 
   CONFIG_MAP = CONFIG_SET.map{|k, (ev, _)| [k, ev]}.to_h.freeze