irb 1.15.1 → 1.15.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce1957978a2c18545492323b39bd054ce881cbd54aae4b2056cee739c41b17c9
-  data.tar.gz: 52d7820dbc752ec441cf7f255ef3e5c94bd9ed524c186f51c52003eb10627db2
+  metadata.gz: 7c3e1957674939d29308f3f534aa65b0a85557c1b7cd47ca6709fef260486eba
+  data.tar.gz: f60b6b8752639425dc0e8aec1443fdc88b82c9799e6c71edf4dd88945efbbd23
 SHA512:
-  metadata.gz: 35eb9995bb8dd7289360bff316d94af1df148ae36dc8bb0fc9dcfde1e78d940147a1021f93b2875c1f73f528ad3cb2198a292707d180bf4a7d510efb972e7d65
-  data.tar.gz: 6ab14019f16bb0b62ac075291067dd48c184e89e1e185ba9e57c1ac376e2115ac4da93d03aca45b21088531664da67e3deba983f43052e8bbd0511102aadff2d
+  metadata.gz: fc15c91bd69233b5cbe962cec327c918805db5553c81c4ba450836d626ab56a3745fd04ca4e185470434bd1e69fe94bab9536bf3bf4704538bbf39681b2291ac
+  data.tar.gz: 4b655b0a770eb2524757b8033e5796892dd43944ee7157dd7523f31d4fe6ffe6fed49ca281faa4990ba2c0dd014e662b1fc54445ee80ea5aa135cf097102d005

data/.rdoc_options

@@ -0,0 +1,5 @@
+page_dir: doc
+warn_missing_rdoc_ref: true
+
+autolink_excluded_words:
+- IRB

data/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing to IRB
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/ruby/irb](https://github.com/ruby/irb).
+
+## Set up the environment
+
+1. Fork the project to your GitHub account.
+2. Clone the fork with `git clone git@github.com:[your_username]/irb.git`.
+3. Run `bundle install`.
+4. Run `bundle exec rake` to make sure tests pass locally.
+
+## Run integration tests
+
+If your changes affect component rendering, such as the autocompletion's dialog/dropdown, you may need to run IRB's integration tests, known as `yamatanooroti`.
+
+Before running these tests, ensure that you have `libvterm` installed. If you're using Homebrew, you can install it by running:
+
+```bash
+brew install libvterm
+```
+
+After installing `libvterm`, you can run the integration tests using the following commands:
+
+```bash
+WITH_VTERM=1 bundle install
+WITH_VTERM=1 bundle exec rake test test_yamatanooroti
+```
+
+## Update documentation
+
+IRB's documentation is generated by [RDoc](https://ruby.github.io/rdoc/) and published to [ruby.github.io/irb](https://ruby.github.io/irb/). Most of the documentation source lives under the `doc/` directory.
+
+Run the following command to generate the documentation site locally.
+
+```bash
+bundle exec rake rdoc
+bundle exec rake rerdoc # to force regeneration
+```
+
+Follow the output message to open the documentation site in your browser.
+
+> [!Note]
+>
+> Please ensure that the changes are rendered correctly on the documentation site.
+> RDoc's Markdown support is limited, so the rendered result on GitHub might differ from what’s rendered on [https://ruby.github.io/irb](https://ruby.github.io/irb).
+
+We welcome any improvements to the documentation, including:
+
+- Fixing typos and grammatical errors.
+- Adding missing documentation for features.
+- Adding missing documentation for configuration options.
+- Adding demo images/gifs for features.

data/EXTEND_IRB.md

@@ -0,0 +1,3 @@
+# Extend IRB
+
+This page has been moved to the [IRB Extension Guide](https://ruby.github.io/irb/EXTEND_IRB_md.html).

data/Gemfile

@@ -25,5 +25,7 @@ gem "debug", github: "ruby/debug", platforms: [:mri, :mswin]
 gem "rdoc", ">= 6.11.0"
 
 if RUBY_VERSION >= "3.0.0" && !is_truffleruby
+  # TODO: Remove this after rbs is released with tsort in its dependencies
+  gem "rbs", github: "ruby/rbs" if RUBY_VERSION >= "3.2"
   gem "repl_type_completor"
 end

data/doc/COMMAND_LINE_OPTIONS.md

@@ -0,0 +1,69 @@
+# Index of Command-Line Options
+
+These are the IRB command-line options, with links to explanatory text:
+
+- `-d`: Set `$DEBUG` and {$VERBOSE}[rdoc-ref:IRB@Verbosity]
+  to `true`.
+- `-E _ex_[:_in_]`: Set initial external (ex) and internal (in)
+  {encodings}[rdoc-ref:IRB@Encodings] (same as `ruby -E`).
+- `-f`: Don't initialize from {configuration file}[rdoc-ref:IRB@Configuration+File].
+- `-I _dirpath_`: Specify {$LOAD_PATH directory}[rdoc-ref:IRB@Load+Modules]
+  (same as `ruby -I`).
+- `-r _load-module_`: Require {load-module}[rdoc-ref:IRB@Load+Modules]
+  (same as `ruby -r`).
+- `-U`: Set external and internal {encodings}[rdoc-ref:IRB@Encodings] to UTF-8.
+- `-w`: Suppress {warnings}[rdoc-ref:IRB@Warnings] (same as `ruby -w`).
+- `-W[_level_]`: Set {warning level}[rdoc-ref:IRB@Warnings];
+  0=silence, 1=medium, 2=verbose (same as `ruby -W`).
+- `--autocomplete`: Use {auto-completion}[rdoc-ref:IRB@Automatic+Completion].
+- `--back-trace-limit _n_`: Set a {backtrace limit}[rdoc-ref:IRB@Tracer];
+  display at most the top `n` and bottom `n` entries.
+- `--colorize`: Use {color-highlighting}[rdoc-ref:IRB@Color+Highlighting]
+  for input and output.
+- `--context-mode _n_`: Select method to create Binding object
+  for new {workspace}[rdoc-ref:IRB@Commands]; `n` in range `0..4`.
+- `--echo`: Print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  return values.
+- `--extra-doc-dir _dirpath_`:
+  Add a {documentation directory}[rdoc-ref:IRB@RI+Documentation+Directories]
+  for the documentation dialog.
+- `--inf-ruby-mode`: Set prompt mode to {:INF_RUBY}[rdoc-ref:IRB@Pre-Defined+Prompts]
+  (appropriate for `inf-ruby-mode` on Emacs);
+  suppresses --multiline and --singleline.
+- `--inspect`: Use method `inspect` for printing ({echoing}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  return values.
+- `--multiline`: Use the multiline editor as the {input method}[rdoc-ref:IRB@Input+Method].
+- `--noautocomplete`: Don't use {auto-completion}[rdoc-ref:IRB@Automatic+Completion].
+- `--nocolorize`: Don't use {color-highlighting}[rdoc-ref:IRB@Color+Highlighting]
+  for input and output.
+- `--noecho`: Don't print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  return values.
+- `--noecho-on-assignment`: Don't print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  result on assignment.
+- `--noinspect`: Don't se method `inspect` for printing ({echoing}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  return values.
+- `--nomultiline`: Don't use the multiline editor as the {input method}[rdoc-ref:IRB@Input+Method].
+- `--noprompt`: Don't print {prompts}[rdoc-ref:IRB@Prompt+and+Return+Formats].
+- `--noscript`:  Treat the first command-line argument as a normal
+  {command-line argument}[rdoc-ref:IRB@Initialization+Script],
+  and include it in `ARGV`.
+- `--nosingleline`: Don't use the singleline editor as the {input method}[rdoc-ref:IRB@Input+Method].
+- `--noverbose`: Don't print {verbose}[rdoc-ref:IRB@Verbosity] details.
+- `--prompt _mode_`, `--prompt-mode _mode_`:
+  Set {prompt and return formats}[rdoc-ref:IRB@Prompt+and+Return+Formats];
+  `mode` may be a {pre-defined prompt}[rdoc-ref:IRB@Pre-Defined+Prompts]
+  or the name of a {custom prompt}[rdoc-ref:IRB@Custom+Prompts].
+- `--script`: Treat the first command-line argument as the path to an
+  {initialization script}[rdoc-ref:IRB@Initialization+Script],
+  and omit it from `ARGV`.
+- `--simple-prompt`, `--sample-book-mode`:
+  Set prompt mode to {:SIMPLE}[rdoc-ref:IRB@Pre-Defined+Prompts].
+- `--singleline`: Use the singleline editor as the {input method}[rdoc-ref:IRB@Input+Method].
+- `--tracer`: Use {Tracer}[rdoc-ref:IRB@Tracer] to print a stack trace for each input command.
+- `--truncate-echo-on-assignment`: Print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  truncated result on assignment.
+- `--verbose`Print {verbose}[rdoc-ref:IRB@Verbosity] details.
+- `-v`, `--version`: Print the {IRB version}[rdoc-ref:IRB@Version].
+- `-h`, `--help`: Print the {IRB help text}[rdoc-ref:IRB@Help].
+- `--`: Separate options from {arguments}[rdoc-ref:IRB@Command-Line+Arguments]
+  on the command-line.

data/doc/COMPARED_WITH_PRY.md

@@ -0,0 +1,22 @@
+# Comparison with Pry
+
+👋 IRB is on a mission to match feature parity with Pry. This document is here to help us track the similarities and differences between the two.
+
+Feel free to chip in and update this table - we appreciate your help!
+
+| Feature                   | Pry                                                                                                                  | IRB                                                                                                                                                    | Note                                                                                           |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
+| Supported Rubies          | `>= 2.0`                                                                                                             | `>= 2.7`                                                                                                                                               |                                                                                                |
+| Source code browsing      | `show-source`                                                                                                        | `show_source`                                                                                                                                          | IRB's `show_source` can't display C source. See [#664](https://github.com/ruby/irb/issues/664) |
+| Document browsing         | `ri`                                                                                                                 | `show_doc`                                                                                                                                             |                                                                                                |
+| Live help system          | `help` or `command_name --help`                                                                                      | `help`                                                                                                                                                 | IRB doesn't support detailed descriptions for individual commands yet                          |
+| Open methods in editors   | `edit`                                                                                                               | `edit`                                                                                                                                                 |                                                                                                |
+| Syntax highlighting       | Yes                                                                                                                  | Yes                                                                                                                                                    |                                                                                                |
+| Command shell integration | Yes                                                                                                                  | No                                                                                                                                                     | Currently, there's no plan to support such features in IRB                                     |
+| Navigation                | - `cd object` to enter `object` <br/> - `cd ..` to leave the current object <br/> - `nesting` to list nesting levels | - `pushws object` <br/> - `popws` <br/> - `workspaces` <br /> - `cd object`/`cd ..` (since [1.14.0](https://github.com/ruby/irb/releases/tag/v1.14.0)) | We plan to refine IRB's commands in the future                                                 |
+| Runtime invocation        | `binding.pry`                                                                                                        | `binding.irb`                                                                                                                                          |                                                                                                |
+| Command system            | Yes                                                                                                                  | No                                                                                                                                                     | Planned in #513 and #588                                                                       |
+| Input history             | [Comprehensive support](https://github.com/pry/pry/wiki/History)                                                     | Supports retrieving previous input and the `history` command                                                                                           | The history command doesn't support as many flags yet, but contributions are welcome.          |
+| Pager support             | Command output and return value                                                                                      | Command output and return value                                                                                                                        |                                                                                                |
+| Debugger integration      | With `byebug` through [pry-byebug](https://github.com/deivid-rodriguez/pry-byebug) gem                               | Supports [`irb:rdbg`](https://github.com/ruby/irb#debugging-with-irb) sessions                                                                         |                                                                                                |
+| Rails console             | Through [`pry-rails`](https://github.com/pry/pry-rails) gem                                                          | Rails' default                                                                                                                                         | Rails console with IRB doesn't have commands like `show-routes` or `show-models`               |

data/doc/Configurations.md

@@ -0,0 +1,275 @@
+# Configure IRB
+
+## Configuration Sources
+
+IRB configurations can be set through multiple sources, each with its own precedence:
+
+1. **Command-Line Options**: When some options are specified when starting IRB, they can override default settings.
+2. **Configuration File**: If present, IRB reads a configuration file containing Ruby code to set configurations.
+3. **Environment Variables**: Certain environment variables influence IRB's behavior.
+4. **Hash `IRB.conf`**: This hash holds the current configuration settings, which can be modified during a session.
+
+### Configuration File Path Resolution
+
+IRB searches for a configuration file in the following order:
+
+1. `$IRBRC`
+2. `$XDG_CONFIG_HOME/irb/irbrc`
+3. `$HOME/.irbrc`
+4. `$HOME/.config/irb/irbrc`
+5. `.irbrc` in the current directory
+6. `irb.rc` in the current directory
+7. `_irbrc` in the current directory
+8. `$irbrc` in the current directory
+
+If the `-f` command-line option is used, no configuration file is loaded.
+
+Method `conf.rc?` returns `true` if a configuration file was read, `false` otherwise. Hash entry `IRB.conf[:RC]` also contains that value.
+
+## Environment Variables
+
+- `NO_COLOR`: Disables IRB's colorization.
+- `IRB_USE_AUTOCOMPLETE`: Setting to `false` disables autocompletion.
+- `IRB_COMPLETOR`: Configures auto-completion behavior (`regexp` or `type`).
+- `IRB_COPY_COMMAND`: Overrides the default program used to interface with the system clipboard.
+- `VISUAL` / `EDITOR`: Specifies the editor for the `edit` command.
+- `IRBRC`: Specifies the rc-file for configuration.
+- `XDG_CONFIG_HOME`: Used to locate the rc-file if `IRBRC` is unset.
+- `RI_PAGER` / `PAGER`: Specifies the pager for documentation.
+- `IRB_LANG`, `LC_MESSAGES`, `LC_ALL`, `LANG`: Determines the locale.
+
+## Hash `IRB.conf`
+
+The initial entries in hash `IRB.conf` are determined by:
+
+- Default values.
+- Command-line options, which may override defaults.
+- Direct assignments in the configuration file.
+
+You can see the hash by typing `IRB.conf`. Below are the primary entries:
+
+- `:AP_NAME`: IRB {application name}[rdoc-ref:IRB@Application+Name];
+  initial value: `'irb'`.
+- `:AT_EXIT`: Array of hooks to call
+  {at exit}[rdoc-ref:IRB@IRB];
+  initial value: `[]`.
+- `:AUTO_INDENT`: Whether {automatic indentation}[rdoc-ref:IRB@Automatic+Indentation]
+  is enabled; initial value: `true`.
+- `:BACK_TRACE_LIMIT`: Sets the {back trace limit}[rdoc-ref:IRB@Tracer];
+  initial value: `16`.
+- `:COMMAND_ALIASES`: Defines input {command aliases}[rdoc-ref:IRB@Command+Aliases];
+  initial value:
+
+        {
+          "$": :show_source,
+          "@": :whereami,
+        }
+
+- `:CONTEXT_MODE`: Sets the {context mode}[rdoc-ref:IRB@Context+Mode],
+  the type of binding to be used when evaluating statements;
+  initial value: `4`.
+- `:ECHO`: Whether to print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  return values;
+  initial value: `nil`, which would set `conf.echo` to `true`.
+- `:ECHO_ON_ASSIGNMENT`: Whether to print ({echo}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29])
+  return values on assignment;
+  initial value: `nil`, which would set `conf.echo_on_assignment` to `:truncate`.
+- `:EVAL_HISTORY`: How much {evaluation history}[rdoc-ref:IRB@Evaluation+History]
+  is to be stored; initial value: `nil`.
+- `:EXTRA_DOC_DIRS`: Array of
+  {RI documentation directories}[rdoc-ref:IRB@RI+Documentation+Directories]
+  to be parsed for the documentation dialog;
+  initial value: `[]`.
+- `:IGNORE_EOF`: Whether to ignore {end-of-file}[rdoc-ref:IRB@End-of-File];
+  initial value: `false`.
+- `:IGNORE_SIGINT`: Whether to ignore {SIGINT}[rdoc-ref:IRB@SIGINT];
+  initial value: `true`.
+- `:INSPECT_MODE`: Whether to use method `inspect` for printing
+  ({echoing}[rdoc-ref:IRB@Return-Value+Printing+-28Echoing-29]) return values;
+  initial value: `true`.
+- `:IRB_LIB_PATH`: The path to the {IRB library directory}[rdoc-ref:IRB@IRB+Library+Directory]; initial value:
+
+      - `"<i>RUBY_DIR</i>/lib/ruby/gems/<i>RUBY_VER_NUM</i>/gems/irb-<i>IRB_VER_NUM</i>/lib/irb"`,
+
+    where:
+
+      - <i>RUBY_DIR</i> is the Ruby installation dirpath.
+      - <i>RUBY_VER_NUM</i> is the Ruby version number.
+      - <i>IRB_VER_NUM</i> is the IRB version number.
+
+- `:IRB_NAME`: {IRB name}[rdoc-ref:IRB@IRB+Name];
+  initial value: `'irb'`.
+- `:IRB_RC`: {Configuration monitor}[rdoc-ref:IRB@Configuration+Monitor];
+  initial value: `nil`.
+- `:LC_MESSAGES`: {Locale}[rdoc-ref:IRB@Locale];
+  initial value: IRB::Locale object.
+- `:LOAD_MODULES`: deprecated.
+- `:MAIN_CONTEXT`: The {context}[rdoc-ref:IRB@Session+Context] for the main IRB session;
+  initial value: IRB::Context object.
+- `:MEASURE`: Whether to
+  {measure performance}[rdoc-ref:IRB@Performance+Measurement];
+  initial value: `false`.
+- `:MEASURE_CALLBACKS`: Callback methods for
+  {performance measurement}[rdoc-ref:IRB@Performance+Measurement];
+  initial value: `[]`.
+- `:MEASURE_PROC`: Procs for
+  {performance measurement}[rdoc-ref:IRB@Performance+Measurement];
+  initial value:
+
+        {
+          :TIME=>#<Proc:0x0000556e271c6598 /var/lib/gems/3.0.0/gems/irb-1.8.3/lib/irb/init.rb:106>,
+          :STACKPROF=>#<Proc:0x0000556e271c6548 /var/lib/gems/3.0.0/gems/irb-1.8.3/lib/irb/init.rb:116>
+        }
+
+- `:PROMPT`: Hash of {defined prompts}[rdoc-ref:IRB@Prompt+and+Return+Formats];
+  initial value:
+
+        {
+          :NULL=>{:PROMPT_I=>nil, :PROMPT_S=>nil, :PROMPT_C=>nil, :RETURN=>"%s\n"},
+          :DEFAULT=>{:PROMPT_I=>"%N(%m):%03n> ", :PROMPT_S=>"%N(%m):%03n%l ", :PROMPT_C=>"%N(%m):%03n* ", :RETURN=>"=> %s\n"},
+          :CLASSIC=>{:PROMPT_I=>"%N(%m):%03n:%i> ", :PROMPT_S=>"%N(%m):%03n:%i%l ", :PROMPT_C=>"%N(%m):%03n:%i* ", :RETURN=>"%s\n"},
+          :SIMPLE=>{:PROMPT_I=>">> ", :PROMPT_S=>"%l> ", :PROMPT_C=>"?> ", :RETURN=>"=> %s\n"},
+          :INF_RUBY=>{:PROMPT_I=>"%N(%m):%03n> ", :PROMPT_S=>nil, :PROMPT_C=>nil, :RETURN=>"%s\n", :AUTO_INDENT=>true},
+          :XMP=>{:PROMPT_I=>nil, :PROMPT_S=>nil, :PROMPT_C=>nil, :RETURN=>"    ==>%s\n"}
+        }
+
+- `:PROMPT_MODE`: Name of {current prompt}[rdoc-ref:IRB@Prompt+and+Return+Formats];
+  initial value: `:DEFAULT`.
+- `:RC`: Whether a {configuration file}[rdoc-ref:IRB@Configuration+File]
+  was found and interpreted;
+  initial value: `true` if a configuration file was found, `false` otherwise.
+- `:SAVE_HISTORY`: Number of commands to save in
+  {input command history}[rdoc-ref:IRB@Input+Command+History];
+  initial value: `1000`.
+- `:SINGLE_IRB`: Whether command-line option `--single-irb` was given;
+  initial value: `true` if the option was given, `false` otherwise.
+  See {Single-IRB Mode}[rdoc-ref:IRB@Single-IRB+Mode].
+- `:USE_AUTOCOMPLETE`: Whether to use
+  {automatic completion}[rdoc-ref:IRB@Automatic+Completion];
+  initial value: `true`.
+- `:USE_COLORIZE`: Whether to use
+  {color highlighting}[rdoc-ref:IRB@Color+Highlighting];
+  initial value: `true`.
+- `:USE_LOADER`: Whether to use the
+  {IRB loader}[rdoc-ref:IRB@IRB+Loader] for `require` and `load`;
+  initial value: `false`.
+- `:USE_TRACER`: Whether to use the
+  {IRB tracer}[rdoc-ref:IRB@Tracer];
+  initial value: `false`.
+- `:USE_PAGER`: Controls whether pager is enabled.
+  initial value: `true`.
+- `:VERBOSE`: Whether to print {verbose output}[rdoc-ref:IRB@Verbosity];
+  initial value: `nil`.
+- `:__MAIN__`: The main IRB object;
+  initial value: `main`.
+
+## Notes on Initialization Precedence
+
+- Any conflict between an entry in hash `IRB.conf` and a command-line option is resolved in favor of the hash entry.
+- Hash `IRB.conf` affects the context only once, when the configuration file is interpreted; any subsequent changes to it do not affect the context and are therefore essentially meaningless.
+
+## Load Modules
+
+You can specify the names of modules that are to be required at startup.
+
+Array `conf.load_modules` determines the modules (if any) that are to be required during session startup. The array is used only during session startup, so the initial value is the only one that counts.
+
+The default initial value is `[]` (load no modules):
+
+```console
+irb(main):001> conf.load_modules
+=> []
+```
+
+You can set the default initial value via:
+
+- Command-line option `-r`
+
+    ```console
+    $ irb -r csv -r json
+    irb(main):001> conf.load_modules
+    => ["csv", "json"]
+    ```
+
+- Hash entry `IRB.conf[:LOAD_MODULES] = *array*`:
+
+    ```ruby
+    IRB.conf[:LOAD_MODULES] = %w[csv json]
+    ```
+
+Note that the configuration file entry overrides the command-line options.
+
+## RI Documentation Directories
+
+You can specify the paths to RI documentation directories that are to be loaded (in addition to the default directories) at startup; see details about RI by typing `ri --help`.
+
+Array `conf.extra_doc_dirs` determines the directories (if any) that are to be loaded during session startup. The array is used only during session startup, so the initial value is the only one that counts.
+
+The default initial value is `[]` (load no extra documentation):
+
+```console
+irb(main):001> conf.extra_doc_dirs
+=> []
+```
+
+You can set the default initial value via:
+
+- Command-line option `--extra_doc_dir`
+
+    ```console
+    $ irb --extra-doc-dir your_doc_dir --extra-doc-dir my_doc_dir
+    irb(main):001> conf.extra_doc_dirs
+    => ["your_doc_dir", "my_doc_dir"]
+    ```
+
+- Hash entry `IRB.conf[:EXTRA_DOC_DIRS] = *array*`:
+
+    ```ruby
+    IRB.conf[:EXTRA_DOC_DIRS] = %w[your_doc_dir my_doc_dir]
+    ```
+
+Note that the configuration file entry overrides the command-line options.
+
+## IRB Name
+
+You can specify a name for IRB.
+
+The default initial value is `'irb'`:
+
+```console
+irb(main):001> conf.irb_name
+=> "irb"
+```
+
+You can set the default initial value via hash entry `IRB.conf[:IRB_NAME] = *string*`:
+
+```ruby
+IRB.conf[:IRB_NAME] = 'foo'
+```
+
+## Application Name
+
+You can specify an application name for the IRB session.
+
+The default initial value is `'irb'`:
+
+```console
+irb(main):001> conf.ap_name
+=> "irb"
+```
+
+You can set the default initial value via hash entry `IRB.conf[:AP_NAME] = *string*`:
+
+```ruby
+IRB.conf[:AP_NAME] = 'my_ap_name'
+```
+
+## Configuration Monitor
+
+You can monitor changes to the configuration by assigning a proc to `IRB.conf[:IRB_RC]` in the configuration file:
+
+```console
+IRB.conf[:IRB_RC] = proc {|conf| puts conf.class }
+```
+
+Each time the configuration is changed, that proc is called with argument `conf`:

data/doc/EXTEND_IRB.md

@@ -0,0 +1,122 @@
+# Extend IRB
+
+From v1.13.0, IRB provides official APIs to extend its functionality. This feature allows libraries to
+customize and enhance their users' IRB sessions by adding new commands and helper methods tailored for
+the libraries.
+
+## Helper Methods vs. Commands
+
+- Use a helper method if the operation is meant to return a Ruby object that interacts with the application.
+  - For example, an `admin_user` helper method that returns `User.where(admin: true).first`, which can then be used like `login_as(admin_user)`.
+- Use a command if the operation fits one of the following:
+  - A utility operation that performs non-Ruby related tasks, such as IRB's `edit` command.
+  - Displays information, like the `show_source` command.
+  - If the operation requires non-Ruby syntax arguments, like `ls -g pattern`.
+
+If you don't know what to pick, go with commands first. Commands are generally safer as they can handle a wider variety of inputs and use cases.
+
+## Commands
+
+Commands are designed to complete certain tasks or display information for the user, similar to shell commands.
+Therefore, they are designed to accept a variety of inputs, including those that are not valid Ruby code, such
+as `my_cmd Foo#bar` or `my_cmd --flag foo`.
+
+### Example
+
+```rb
+require "irb/command"
+
+class Greet < IRB::Command::Base
+  category "Greeting"
+  description "Greets the user"
+  help_message <<~HELP
+    Greets the user with the given name.
+
+    Usage: greet <name>
+  HELP
+
+  # Any input after the command name will be passed as a single string.
+  # If nothing is added after the command, an empty string will be passed.
+  def execute(arg)
+    puts "Hello! #{arg}"
+  end
+end
+
+IRB::Command.register(:greet, Greet)
+```
+
+As long as the above code is loaded before the IRB session is started, such as in a loaded library or a user's `.irbrc` file, `greet` will be accessible to the user.
+
+```txt
+irb(main):001> greet
+Hello!
+=> nil
+irb(main):002> greet Stan
+Hello! Stan
+=> nil
+```
+
+And because the `Greet` command introduces a new category, `Greeting`, a new help message category will be created:
+
+```txt
+Help
+  help           List all available commands. Use `help <command>` to get information about a specific command.
+
+Greeting
+  greet          Greets the user
+
+IRB
+  context        Displays current configuration.
+  ...
+```
+
+If the optional `help_message` attribute is specified, `help greet` will also display it:
+
+```txt
+irb(main):001> help greet
+Greets the user with the given name.
+
+Usage: greet <name>
+```
+
+## Helper methods
+
+Helper methods are designed to be used as Ruby methods, such as `my_helper(arg, kwarg: val).foo`.
+
+The main use case of helper methods is to provide shortcuts for users, providing quick and easy access to
+frequently used operations or components within the IRB session. For example, a helper method might simplify
+the process of fetching and displaying specific configuration settings or data structures that would otherwise
+require multiple steps to access.
+
+### Example
+
+```rb
+# This only loads the minimum components required to define and register a helper method.
+# It does not load the entire IRB, nor does it initialize it.
+require "irb/helper_method"
+
+class MyHelper < IRB::HelperMethod::Base
+  description "This is a test helper"
+
+  def execute(arg, kwarg:)
+    "arg: #{arg}, kwarg: #{kwarg}"
+  end
+end
+
+IRB::HelperMethod.register(:my_helper, MyHelper)
+```
+
+As long as the above code is loaded before the IRB session is started, such as in a loaded library or a user's `.irbrc` file, `my_helper` will be accessible to the user.
+
+```txt
+irb(main):001> my_helper("foo", kwarg: "bar").upcase
+=> "ARG: FOO, KWARG: BAR"
+```
+
+The registered helper methods will also be listed in the help message's `Helper methods` section:
+
+```txt
+Helper methods
+  conf           Returns the current context.
+  my_helper      This is a test helper
+```