From 02d875f7174fd25769ca0575f25205cd01f9b373 Mon Sep 17 00:00:00 2001 From: Stan Lo Date: Sun, 22 Dec 2024 14:27:50 +0000 Subject: [PATCH] Restructure IRB's documentation Currently, part of the documentation lives in `lib/irb.rb` as RDoc comments, and the rest lives in `README.md`. The RDoc comments are not for viewing on GitHub, while README.md is. So this means users need to read part of the documentation on https://ruby.github.io/irb/, and the rest on GitHub. This is not a great user experience. This commit restructures the documentation so all major documentation is in `doc/index.md` that will become the main documentation for IRB on https://ruby.github.io/irb/. This solves a 2 main problems: 1. Users can read IRB documentation all in one place, on https://ruby.github.io/irb/. 2. It makes updating the documentation easier, especially the content that currently lives in `lib/irb.rb`. --- .document | 8 - .gitignore | 1 + .rdoc_options | 2 + Rakefile | 8 +- doc/.document | 1 + doc/COMMAND_LINE_OPTIONS.md | 69 ++ .../COMPARED_WITH_PRY.md | 0 .../indexes.md => CONFIGURATION_ENTRIES.md} | 74 +- EXTEND_IRB.md => doc/EXTEND_IRB.md | 0 doc/index.md | 863 ++++++++++++++++++ doc/{irb => }/irb-tools.rd.ja | 0 doc/{irb => }/irb.rd.ja | 0 lib/.document | 3 + lib/irb.rb | 852 ----------------- 14 files changed, 944 insertions(+), 937 deletions(-) delete mode 100644 .document create mode 100644 .rdoc_options create mode 100644 doc/.document create mode 100644 doc/COMMAND_LINE_OPTIONS.md rename COMPARED_WITH_PRY.md => doc/COMPARED_WITH_PRY.md (100%) rename doc/{irb/indexes.md => CONFIGURATION_ENTRIES.md} (56%) rename EXTEND_IRB.md => doc/EXTEND_IRB.md (100%) create mode 100644 doc/index.md rename doc/{irb => }/irb-tools.rd.ja (100%) rename doc/{irb => }/irb.rd.ja (100%) create mode 100644 lib/.document diff --git a/.document b/.document deleted file mode 100644 index 39cee3186..000000000 --- a/.document +++ /dev/null @@ -1,8 +0,0 @@ -LICENSE.txt -README.md -EXTEND_IRB.md -COMPARED_WITH_PRY.md -doc/irb/indexes.md -lib/irb.rb -lib/irb/context.rb -lib/irb/command/base.rb diff --git a/.gitignore b/.gitignore index be35d6352..f217e5a10 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,4 @@ /tmp/ /docs/ Gemfile.lock +_site/ diff --git a/.rdoc_options b/.rdoc_options new file mode 100644 index 000000000..81831200d --- /dev/null +++ b/.rdoc_options @@ -0,0 +1,2 @@ +page_dir: doc +warn_missing_rdoc_ref: true diff --git a/Rakefile b/Rakefile index aaf5a936a..67bb439bd 100644 --- a/Rakefile +++ b/Rakefile @@ -45,8 +45,8 @@ end task :default => :test RDoc::Task.new do |rdoc| - rdoc.title = "IRB" - rdoc.rdoc_dir = "docs" - rdoc.main = "README.md" - rdoc.options.push("--copy-files", "LICENSE.txt") + rdoc.title = "IRB Documentation" + rdoc.main = "index.md" + rdoc.rdoc_dir = "_site" + rdoc.options.push("lib") end diff --git a/doc/.document b/doc/.document new file mode 100644 index 000000000..dd449725e --- /dev/null +++ b/doc/.document @@ -0,0 +1 @@ +*.md diff --git a/doc/COMMAND_LINE_OPTIONS.md b/doc/COMMAND_LINE_OPTIONS.md new file mode 100644 index 000000000..babbdece7 --- /dev/null +++ b/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. diff --git a/COMPARED_WITH_PRY.md b/doc/COMPARED_WITH_PRY.md similarity index 100% rename from COMPARED_WITH_PRY.md rename to doc/COMPARED_WITH_PRY.md diff --git a/doc/irb/indexes.md b/doc/CONFIGURATION_ENTRIES.md similarity index 56% rename from doc/irb/indexes.md rename to doc/CONFIGURATION_ENTRIES.md index d6dc5c160..6f4b8af70 100644 --- a/doc/irb/indexes.md +++ b/doc/CONFIGURATION_ENTRIES.md @@ -1,76 +1,4 @@ -## Indexes - -### 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. - -### Index of \IRB.conf Entries +# \IRB.conf Entries These are the keys for hash \IRB.conf entries, with links to explanatory text; for each entry that is pre-defined, the initial value is given: diff --git a/EXTEND_IRB.md b/doc/EXTEND_IRB.md similarity index 100% rename from EXTEND_IRB.md rename to doc/EXTEND_IRB.md diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 000000000..f49eb30ea --- /dev/null +++ b/doc/index.md @@ -0,0 +1,863 @@ +# \IRB + +[![Gem Version](https://badge.fury.io/rb/irb.svg)](https://badge.fury.io/rb/irb) +[![build](https://github.com/ruby/irb/actions/workflows/test.yml/badge.svg)](https://github.com/ruby/irb/actions/workflows/test.yml) + +## Overview + +\IRB stands for "Interactive Ruby" and is a tool to interactively execute Ruby expressions read from the standard input. The `irb` command from your shell will start the interpreter. + +\IRB provides a shell-like interface that supports user interaction with the Ruby interpreter. It operates as a *read-eval-print loop* ([REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)) that: + +- **Reads** each character as you type. You can modify the \IRB context to change the way input works. See [Input](#label-Input). +- **Evaluates** the code each time it has read a syntactically complete passage. +- **Prints** after evaluating. You can modify the \IRB context to change the way output works. See [Output](#label-Output). + +## Installation + +> **Note** +> +> \IRB is a default gem of Ruby, so you shouldn't need to install it separately. However, if you're using Ruby 2.6 or later and want to upgrade/install a specific version of \IRB, follow these steps. + +To install it with `bundler`, add this line to your application's Gemfile: + +```ruby +gem 'irb' +``` + +Then execute: + +```console +$ bundle +``` + +Or install it directly with: + +```console +$ gem install irb +``` + +## Usage + +> **Note** +> +> We're working hard to match Pry's variety of powerful features in \IRB. Track our progress or find contribution ideas in [COMPARED_WITH_PRY.md](./COMPARED_WITH_PRY.md). + +### Starting \IRB + +You can start a fresh \IRB session by typing `irb` in your terminal. In the session, you can evaluate Ruby expressions or prototype small Ruby scripts. Input is executed when it is syntactically complete. + +```console +$ irb +irb(main):001> 1 + 2 +=> 3 +irb(main):002* class Foo +irb(main):003* def foo +irb(main):004* puts 1 +irb(main):005* end +irb(main):006> end +=> :foo +irb(main):007> Foo.new.foo +1 +=> nil +``` + +### The `binding.irb` Breakpoint + +If you use Ruby 2.5 or later versions, you can use `binding.irb` in your program as breakpoints. Once `binding.irb` is evaluated, a new \IRB session starts with the surrounding context: + +```console +$ ruby test.rb + +From: test.rb @ line 2 : + + 1: def greet(word) + => 2: binding.irb + 3: puts "Hello #{word}" + 4: end + 5: + 6: greet("World") + +irb(main):001> word +=> "World" +irb(main):002> exit +Hello World +``` + +## Startup + +At startup, \IRB: + +1. Interprets (as Ruby code) the content of the [configuration file](#label-Configuration) (if given). +2. Constructs the initial session context from [hash IRB.conf](#label-Hash+IRB.conf) and from default values; the hash content may have been affected by [command-line options](#command-line-options), and by direct assignments in the configuration file. +3. Assigns the context to variable `conf`. +4. Assigns command-line arguments to variable `ARGV`. +5. Prints the prompt. +6. Puts the content of the [initialization script](#label-Initialization+script) onto the \IRB shell, just as if it were user-typed commands. + +## Command Line + +On the command line, all options precede all arguments; the first item that is not recognized as an option is treated as an argument, as are all items that follow. + +### Command-Line Options + +Many command-line options affect entries in hash `IRB.conf`, which in turn affect the initial configuration of the \IRB session. + +Details of the options are described in relevant subsections below. A cursory list of \IRB command-line options may be seen in the [help message](https://raw.githubusercontent.com/ruby/irb/master/lib/irb/lc/help-message), which is also displayed if you use command-line option `--help`. + +If you are interested in a specific option, consult the [index](rdoc-ref:COMMAND_LINE_OPTIONS.md). + +### Command-Line Arguments + +Command-line arguments are passed to \IRB in array `ARGV`: + +```console +$ irb --noscript Foo Bar Baz +irb(main):001> ARGV +=> ["Foo", "Bar", "Baz"] +irb(main):002> exit +$ +``` + +Command-line option `--` causes everything that follows to be treated as arguments, even those that look like options: + +```console +$ irb --noscript -- --noscript -- Foo Bar Baz +irb(main):001> ARGV +=> ["--noscript", "--", "Foo", "Bar", "Baz"] +irb(main):002> exit +$ +``` + +## Commands + +The following commands are available in \IRB. Use the `help` command to see the list of available commands. + +```txt +Help + help List all available commands. Use `help ` to get information about a specific command. + +IRB + context Displays current configuration. + exit Exit the current irb session. + exit! Exit the current process. + irb_load Load a Ruby file. + irb_require Require a Ruby file. + source Loads a given file in the current session. + irb_info Show information about IRB. + history Shows the input history. `-g [query]` or `-G [query]` allows you to filter the output. + disable_irb Disable binding.irb. + +Workspace + cwws Show the current workspace. + chws Change the current workspace to an object. + workspaces Show workspaces. + pushws Push an object to the workspace stack. + popws Pop a workspace from the workspace stack. + cd Move into the given object or leave the current context. + +Multi-irb (DEPRECATED) + irb Start a child IRB. + jobs List of current sessions. + fg Switches to the session of the given number. + kill Kills the session with the given number. + +Debugging + debug Start the debugger of debug.gem. + break Start the debugger of debug.gem and run its `break` command. + catch Start the debugger of debug.gem and run its `catch` command. + next Start the debugger of debug.gem and run its `next` command. + delete Start the debugger of debug.gem and run its `delete` command. + step Start the debugger of debug.gem and run its `step` command. + continue Start the debugger of debug.gem and run its `continue` command. + finish Start the debugger of debug.gem and run its `finish` command. + backtrace Start the debugger of debug.gem and run its `backtrace` command. + info Start the debugger of debug.gem and run its `info` command. + +Misc + edit Open a file or source location. + measure `measure` enables the mode to measure processing time. `measure :off` disables it. + +Context + show_doc Look up documentation with RI. + ls Show methods, constants, and variables. + show_source Show the source code of a given method, class/module, or constant. + whereami Show the source code around binding.irb again. + +Helper methods + conf Returns the current IRB context. + +Aliases + $ Alias for `show_source` + @ Alias for `whereami` +``` + +## Debugging with \IRB + +### Getting Started + +- In `binding.irb`, use the `debug` command to start an `irb:rdbg` session with access to all `debug.gem` commands. +- Use the `RUBY_DEBUG_IRB_CONSOLE=1` environment variable to make `debug.gem` use \IRB as the debugging console. + +### Details + +Starting from version 1.8.0, \IRB offers a powerful integration with `debug.gem`, providing a debugging experience similar to `pry-byebug`. + +After hitting a `binding.irb` breakpoint, you can activate the debugger with the `debug` command. Alternatively, if the `debug` method is already defined in the current scope, you can call `irb_debug`. + +```console +From: test.rb @ line 3 : + + 1: + 2: def greet(word) + => 3: binding.irb + 4: puts "Hello #{word}" + 5: end + 6: + 7: greet("World") + +irb(main):001> debug +irb:rdbg(main):002> +``` + +Once activated, the prompt's header changes from `irb` to `irb:rdbg`, enabling you to use any of `debug.gem`'s [commands](https://github.com/ruby/debug#debug-command-on-the-debug-console): + +```console +irb:rdbg(main):002> info # use info command to see available variables +%self = main +_ = nil +word = "World" +irb:rdbg(main):003> next # use next command to move to the next line +[1, 7] in test.rb + 1| + 2| def greet(word) + 3| binding.irb +=> 4| puts "Hello #{word}" + 5| end + 6| + 7| greet("World") +=>#0 Object#greet(word="World") at test.rb:4 + #1
at test.rb:7 +irb:rdbg(main):004> +``` + +Simultaneously, you maintain access to \IRB's commands, such as `show_source`: + +```console +irb:rdbg(main):004> show_source greet + +From: test.rb:2 + +def greet(word) + binding.irb + puts "Hello #{word}" +end +``` + +### More about `debug.gem` + +`debug.gem` offers many advanced debugging features that simple REPLs can't provide, including: + +- Step-debugging +- Frame navigation +- Setting breakpoints with commands +- Thread control +- ...and many more + +To learn about these features, refer to `debug.gem`'s [commands list](https://github.com/ruby/debug#debug-command-on-the-debug-console). + +In the `irb:rdbg` session, the `help` command also displays all commands from `debug.gem`. + +### Advantages Over `debug.gem`'s Console + +This integration offers several benefits over `debug.gem`'s native console: + +1. Access to handy \IRB commands like `show_source` or `show_doc`. +2. Support for multi-line input. +3. Symbol shortcuts such as `@` (`whereami`) and `$` (`show_source`). +4. Autocompletion. +5. Customizable prompt. + +However, there are some limitations to be aware of: + +1. `binding.irb` doesn't support `pre` and `do` arguments like [`binding.break`](https://github.com/ruby/debug#bindingbreak-method). +2. As \IRB [doesn't currently support remote-connection](https://github.com/ruby/irb/issues/672), it can't be used with `debug.gem`'s remote debugging feature. +3. Access to the previous return value via the underscore `_` is not supported. + +## Type Based Completion + +\IRB's default completion `\IRB::RegexpCompletor` uses Regexp. \IRB offers an experimental completion `\IRB::TypeCompletor` that uses type analysis. + +### How to Enable \IRB::TypeCompletor + +Install [ruby/repl_type_completor](https://github.com/ruby/repl_type_completor/) with: + +```console +$ gem install repl_type_completor +``` + +Or add these lines to your project's Gemfile. + +```ruby +gem 'irb' +gem 'repl_type_completor', group: [:development, :test] +``` + +Now you can use type-based completion by: + +- Running \IRB with the `--type-completor` option + + ```console + $ irb --type-completor + ``` + +- Or writing this line to \IRB's rc-file (e.g., `~/.irbrc`) + + ```ruby + IRB.conf[:COMPLETOR] = :type # default is :regexp + ``` + +- Or setting the environment variable `IRB_COMPLETOR` + + ```ruby + ENV['IRB_COMPLETOR'] = 'type' + IRB.start + ``` + +To check if it's enabled, type `irb_info` into \IRB and see the `Completion` section. + +```console +irb(main):001> irb_info +... +# Enabled +Completion: Autocomplete, ReplTypeCompletor: 0.1.0, Prism: 0.18.0, RBS: 3.3.0 +# Not enabled +Completion: Autocomplete, RegexpCompletor +... +``` + +If you have a `sig/` directory or `rbs_collection.lock.yaml` in the current directory, \IRB will load it. + +### Advantage over Default \IRB::RegexpCompletor + +\IRB::TypeCompletor can autocomplete chained methods, block parameters, and more if type information is available. These are some examples \IRB::RegexpCompletor cannot complete. + +```console +irb(main):001> 'Ruby'.upcase.chars.s # Array methods (sample, select, shift, size) +``` + +```console +irb(main):001> 10.times.map(&:to_s).each do |s| +irb(main):002> s.up # String methods (upcase, upcase!, upto) +``` + +```console +irb(main):001> class User < ApplicationRecord +irb(main):002> def foo +irb(main):003> sa # save, save! +``` + +As a trade-off, completion calculation takes more time than \IRB::RegexpCompletor. + +### Difference between Steep's Completion + +Compared with Steep, \IRB::TypeCompletor has some differences and limitations. +```ruby +[0, 'a'].sample. +# Steep completes the intersection of Integer methods and String methods +# IRB::TypeCompletor completes both Integer and String methods +``` + +Some features like type narrowing are not implemented. +```ruby +def f(arg = [0, 'a'].sample) + if arg.is_a?(String) + arg. # Completes both Integer and String methods +``` + +Unlike other static type checkers, \IRB::TypeCompletor uses runtime information to provide better completion. + +```console +irb(main):001> a = [1] +=> [1] +irb(main):002> a.first. # Completes Integer methods +``` + +## Input + +This section describes the features that allow you to change the way \IRB input works; see also [Output](#output). + +### Input Command History + +By default, \IRB stores a history of up to 1000 input commands in a file named `.irb_history`. The history file will be in the same directory as the [configuration file](#label-Configuration+File) if one is found, or in `~/` otherwise. + +A new \IRB session creates the history file if it does not exist and appends to the file if it does exist. + +You can change the filepath by adding to your configuration file: +`IRB.conf[:HISTORY_FILE] = *filepath*`, where *filepath* is a string filepath. + +During the session, method `conf.history_file` returns the filepath, and method `conf.history_file = *new_filepath*` copies the history to the file at *new_filepath*, which becomes the history file for the session. + +You can change the number of commands saved by adding to your configuration file: `IRB.conf[:SAVE_HISTORY] = *n*`, where *n* is one of: + +- Positive integer: the number of commands to be saved. +- Negative integer: all commands are to be saved. +- Zero or `nil`: no commands are to be saved. + +During the session, you can use methods `conf.save_history` or `conf.save_history=` to retrieve or change the count. + +### Command Aliases + +By default, \IRB defines several command aliases: + +```console +irb(main):001> conf.command_aliases +=> {:"$"=>:show_source, :"@"=>:whereami} +``` + +You can change the initial aliases in the configuration file with: + +```ruby +IRB.conf[:COMMAND_ALIASES] = {foo: :show_source, bar: :whereami} +``` + +You can replace the current aliases at any time with configuration method `conf.command_aliases=`; because `conf.command_aliases` is a hash, you can modify it. + +### End-of-File + +By default, `IRB.conf[:IGNORE_EOF]` is `false`, which means that typing the end-of-file character `Ctrl-D` causes the session to exit. + +You can reverse that behavior by adding `IRB.conf[:IGNORE_EOF] = true` to the configuration file. + +During the session, method `conf.ignore_eof?` returns the setting, and method `conf.ignore_eof = *boolean*` sets it. + +### SIGINT + +By default, `IRB.conf[:IGNORE_SIGINT]` is `true`, which means that typing the interrupt character `Ctrl-C` causes the session to exit. + +You can reverse that behavior by adding `IRB.conf[:IGNORE_SIGING] = false` to the configuration file. + +During the session, method `conf.ignore_siging?` returns the setting, and method `conf.ignore_sigint = *boolean*` sets it. + +### Automatic Completion + +By default, \IRB enables [automatic completion](https://en.wikipedia.org/wiki/Autocomplete#In_command-line_interpreter): + +You can disable it by either of these: + +- Adding `IRB.conf[:USE_AUTOCOMPLETE] = false` to the configuration file. +- Giving command-line option `--noautocomplete` (`--autocomplete` is the default). + +Method `conf.use_autocomplete?` returns `true` if automatic completion is enabled, `false` otherwise. + +The setting may not be changed during the session. + +### Automatic Indentation + +By default, \IRB automatically indents lines of code to show structure (e.g., it indents the contents of a block). + +The current setting is returned by the configuration method `conf.auto_indent_mode`. + +The default initial setting is `true`: + +```console +irb(main):001> conf.auto_indent_mode +=> true +irb(main):002* Dir.entries('.').select do |entry| +irb(main):003* entry.start_with?('R') +irb(main):004> end +=> ["README.md", "Rakefile"] +``` + +You can change the initial setting in the configuration file with: + +```ruby +IRB.conf[:AUTO_INDENT] = false +``` + +Note that the *current* setting *may not* be changed in the \IRB session. + +### Input Method + +The \IRB input method determines how command input is read; by default, the input method for a session is \IRB::RelineInputMethod unless the TERM environment variable is 'dumb', in which case the most simplistic input method is used. + +You can set the input method by: + +- Adding to the configuration file: + + - `IRB.conf[:USE_SINGLELINE] = true` or `IRB.conf[:USE_MULTILINE] = false` sets the input method to \IRB::ReadlineInputMethod. + - `IRB.conf[:USE_SINGLELINE] = false` or `IRB.conf[:USE_MULTILINE] = true` sets the input method to \IRB::RelineInputMethod. + +- Giving command-line options: + + - `--singleline` or `--nomultiline` sets the input method to \IRB::ReadlineInputMethod. + - `--nosingleline` or `--multiline` sets the input method to \IRB::RelineInputMethod. + - `--nosingleline` together with `--nomultiline` sets the input to \IRB::StdioInputMethod. + +Method `conf.use_multiline?` and its synonym `conf.use_reline` return: + +- `true` if option `--multiline` was given. +- `false` if option `--nomultiline` was given. +- `nil` if neither was given. + +Method `conf.use_singleline?` and its synonym `conf.use_readline` return: + +- `true` if option `--singleline` was given. +- `false` if option `--nosingleline` was given. +- `nil` if neither was given. + +## Output + +This section describes the features that allow you to change the way \IRB output works; see also [Input](#label-Input). + +### Return-Value Printing (Echoing) + +By default, \IRB prints (echoes) the values returned by all input commands. + +You can change the initial behavior and suppress all echoing by: + +- Adding to the configuration file: `IRB.conf[:ECHO] = false`. (The default value for this entry is `nil`, which means the same as `true`.) +- Giving command-line option `--noecho`. (The default is `--echo`.) + +During the session, you can change the current setting with configuration method `conf.echo=` (set to `true` or `false`). + +As stated above, by default \IRB prints the values returned by all input commands; but \IRB offers special treatment for values returned by assignment statements, which may be: + +- Printed with truncation (to fit on a single line of output), which is the default; an ellipsis (`...` is suffixed, to indicate the truncation): + + ```console + irb(main):001> x = 'abc' * 100 + > "abcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabc..." + ``` + +- Printed in full (regardless of the length). +- Suppressed (not printed at all). + +You can change the initial behavior by: + +- Adding to the configuration file: `IRB.conf[:ECHO_ON_ASSIGNMENT] = false`. (The default value for this entry is `nil`, which means the same as `:truncate`.) +- Giving command-line option `--noecho-on-assignment` or `--echo-on-assignment`. (The default is `--truncate-echo-on-assignment`.) + +During the session, you can change the current setting with configuration method `conf.echo_on_assignment=` (set to `true`, `false`, or `:truncate`). + +By default, \IRB formats returned values by calling method `inspect`. + +You can change the initial behavior by: + +- Adding to the configuration file: `IRB.conf[:INSPECT_MODE] = false`. (The default value for this entry is `true`.) +- Giving command-line option `--noinspect`. (The default is `--inspect`.) + +During the session, you can change the setting using method `conf.inspect_mode=`. + +### Multiline Output + +By default, \IRB prefixes a newline to a multiline response. + +You can change the initial default value by adding to the configuration file: + +```ruby +IRB.conf[:NEWLINE_BEFORE_MULTILINE_OUTPUT] = false +``` + +During a session, you can retrieve or set the value using methods `conf.newline_before_multiline_output?` and `conf.newline_before_multiline_output=`. + +Examples: + +```console +irb(main):001> conf.inspect_mode = false +=> false +irb(main):002> "foo\nbar" +=> +foo +bar +irb(main):003> conf.newline_before_multiline_output = false +=> false +irb(main):004> "foo\nbar" +=> foo +bar +``` + +### Evaluation History + +By default, \IRB saves no history of evaluations (returned values), and the related methods `conf.eval_history`, `_`, and `__` are undefined. + +You can turn on that history and set the maximum number of evaluations to be stored: + +- In the configuration file: add `IRB.conf[:EVAL_HISTORY] = *n*`. (Examples below assume that we've added `IRB.conf[:EVAL_HISTORY] = 5`.) +- In the session (at any time): `conf.eval_history = *n*`. + +If `n` is zero, all evaluation history is stored. + +Doing either of the above: + +- Sets the maximum size of the evaluation history; defines method `conf.eval_history`, which returns the maximum size `n` of the evaluation history: + + ```console + irb(main):001> conf.eval_history = 5 + => 5 + irb(main):002> conf.eval_history + => 5 + ``` + +- Defines variable `_`, which contains the most recent evaluation, or `nil` if none; same as method `conf.last_value`: + + ```console + irb(main):003> _ + => 5 + irb(main):004> :foo + => :foo + irb(main):005> :bar + => :bar + irb(main):006> _ + => :bar + irb(main):007> _ + => :bar + ``` + +- Defines variable `__`: + + - `__` unadorned: contains all evaluation history: + + ```console + irb(main):008> :foo + => :foo + irb(main):009> :bar + => :bar + irb(main):010> :baz + => :baz + irb(main):011> :bat + => :bat + irb(main):012> :bam + => :bam + irb(main):013> __ + => + 9 :bar + 10 :baz + 11 :bat + 12 :bam + 13 ...self-history... + ``` + + Note that when the evaluation is multiline, it is displayed differently. + + - `__[m]`: + + - Positive `m`: contains the evaluation for the given line number, or `nil` if that line number is not in the evaluation history: + + ```console + irb(main):015> __[12] + => :bam + irb(main):016> __[1] + => nil + ``` + + - Negative `m`: contains the `mth`-from-end evaluation, or `nil` if that evaluation is not in the evaluation history: + + ```console + irb(main):017> __[-3] + => :bam + irb(main):018> __[-13] + => nil + ``` + + - Zero `m`: contains `nil`: + + ```console + irb(main):019> __[0] + => nil + ``` + +## Configuration + +### Environment Variables + +- `NO_COLOR`: Assigning a value to it disables \IRB's colorization. +- `IRB_USE_AUTOCOMPLETE`: Setting it to `false` disables \IRB's autocompletion. +- `IRB_COMPLETOR`: Configures \IRB's auto-completion behavior, allowing settings for either `regexp` or `type`. +- `VISUAL`: Its value is used to open files by the `edit` command. +- `EDITOR`: Its value is used to open files by the `edit` command if `VISUAL` is unset. +- `IRBRC`: The file specified is evaluated as \IRB's rc-file. +- `XDG_CONFIG_HOME`: If set and `IRBRC` is unset, the file `$XDG_CONFIG_HOME/irb/irbrc` is evaluated as \IRB's rc-file. +- `RI_PAGER`: The command specified is used as a pager. +- `PAGER`: The command specified is used as a pager if `RI_PAGER` is unset. +- `IRB_LANG`, `LC_MESSAGES`, `LC_ALL`, `LANG`: The first of these that is set is used as the locale value. + +### Configuration File + +You can initialize \IRB via a *configuration file*. + +If command-line option `-f` is given, no configuration file is looked for. + +Otherwise, \IRB reads and interprets a configuration file if one is available. + +The configuration file can contain any Ruby code and can include user code that: + +- Can be debugged in \IRB. +- Configures \IRB itself. +- Requires or loads files. + +The path to the configuration file is the first found among: + +- The value of variable `$IRBRC`, if defined. +- The value of variable `$XDG_CONFIG_HOME/irb/irbrc`, if defined. +- File `$HOME/.irbrc`, if it exists. +- File `$HOME/.config/irb/irbrc`, if it exists. +- File `.irbrc` in the current directory, if it exists. +- File `irb.rc` in the current directory, if it exists. +- File `_irbrc` in the current directory, if it exists. +- File `$irbrc` in the current directory, if it exists. + +If the search fails, there is no configuration file. + +If the search succeeds, the configuration file is read as Ruby code and can contain any Ruby programming you like. + +Method `conf.rc?` returns `true` if a configuration file was read, `false` otherwise. Hash entry `IRB.conf[:RC]` also contains that value. + +### 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`. + +Details of the entries' meanings are described in relevant subsections below. + +If you are interested in a specific entry, consult the [index](rdoc-ref:CONFIGURATION_ENTRIES.md). + +### 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. + +### Initialization Script + +By default, the first command-line argument (after any options) is the path to a Ruby initialization script. + +\IRB reads the initialization script and puts its content onto the \IRB shell, just as if it were user-typed commands. + +Command-line option `--noscript` causes the first command-line argument to be treated as an ordinary argument (instead of an initialization script); `--script` is the default. + +## 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`: + +## Encodings + +Command-line option `-E *ex*[:*in*]` sets initial external (ex) and internal (in) encodings. + +Command-line option `-U` sets both to UTF-8. + +## Extending \IRB + +\IRB `v1.13.0` and later versions allow users/libraries to extend its functionality through official APIs. + +For more information, visit [EXTEND_IRB.md](rdoc-ref:EXTEND_IRB.md). + +## License + +The gem is available as open source under the terms of the [2-Clause BSD License](https://opensource.org/licenses/BSD-2-Clause). diff --git a/doc/irb/irb-tools.rd.ja b/doc/irb-tools.rd.ja similarity index 100% rename from doc/irb/irb-tools.rd.ja rename to doc/irb-tools.rd.ja diff --git a/doc/irb/irb.rd.ja b/doc/irb.rd.ja similarity index 100% rename from doc/irb/irb.rd.ja rename to doc/irb.rd.ja diff --git a/lib/.document b/lib/.document new file mode 100644 index 000000000..85f1b2217 --- /dev/null +++ b/lib/.document @@ -0,0 +1,3 @@ +irb.rb +irb/context.rb +irb/command/base.rb diff --git a/lib/irb.rb b/lib/irb.rb index 3aff5deff..169985773 100644 --- a/lib/irb.rb +++ b/lib/irb.rb @@ -24,858 +24,6 @@ require_relative "irb/debug" require_relative "irb/pager" -# ## IRB -# -# Module IRB ("Interactive Ruby") provides a shell-like interface that supports -# user interaction with the Ruby interpreter. -# -# It operates as a *read-eval-print loop* -# ([REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)) -# that: -# -# * ***Reads*** each character as you type. You can modify the IRB context to -# change the way input works. See [Input](rdoc-ref:IRB@Input). -# * ***Evaluates*** the code each time it has read a syntactically complete -# passage. -# * ***Prints*** after evaluating. You can modify the IRB context to change -# the way output works. See [Output](rdoc-ref:IRB@Output). -# -# -# Example: -# -# $ irb -# irb(main):001> File.basename(Dir.pwd) -# => "irb" -# irb(main):002> Dir.entries('.').size -# => 25 -# irb(main):003* Dir.entries('.').select do |entry| -# irb(main):004* entry.start_with?('R') -# irb(main):005> end -# => ["README.md", "Rakefile"] -# -# The typed input may also include [\IRB-specific -# commands](rdoc-ref:IRB@IRB-Specific+Commands). -# -# As seen above, you can start IRB by using the shell command `irb`. -# -# You can stop an IRB session by typing command `exit`: -# -# irb(main):006> exit -# $ -# -# At that point, IRB calls any hooks found in array `IRB.conf[:AT_EXIT]`, then -# exits. -# -# ## Startup -# -# At startup, IRB: -# -# 1. Interprets (as Ruby code) the content of the [configuration -# file](rdoc-ref:IRB@Configuration+File) (if given). -# 2. Constructs the initial session context from [hash -# IRB.conf](rdoc-ref:IRB@Hash+IRB.conf) and from default values; the hash -# content may have been affected by [command-line -# options](rdoc-ref:IRB@Command-Line+Options), and by direct assignments in -# the configuration file. -# 3. Assigns the context to variable `conf`. -# 4. Assigns command-line arguments to variable `ARGV`. -# 5. Prints the [prompt](rdoc-ref:IRB@Prompt+and+Return+Formats). -# 6. Puts the content of the [initialization -# script](rdoc-ref:IRB@Initialization+Script) onto the IRB shell, just as if -# it were user-typed commands. -# -# -# ### The Command Line -# -# On the command line, all options precede all arguments; the first item that is -# not recognized as an option is treated as an argument, as are all items that -# follow. -# -# #### Command-Line Options -# -# Many command-line options affect entries in hash `IRB.conf`, which in turn -# affect the initial configuration of the IRB session. -# -# Details of the options are described in the relevant subsections below. -# -# A cursory list of the IRB command-line options may be seen in the [help -# message](https://raw.githubusercontent.com/ruby/irb/master/lib/irb/lc/help-message), -# which is also displayed if you use command-line option `--help`. -# -# If you are interested in a specific option, consult the -# [index](rdoc-ref:doc/irb/indexes.md@Index+of+Command-Line+Options). -# -# #### Command-Line Arguments -# -# Command-line arguments are passed to IRB in array `ARGV`: -# -# $ irb --noscript Foo Bar Baz -# irb(main):001> ARGV -# => ["Foo", "Bar", "Baz"] -# irb(main):002> exit -# $ -# -# Command-line option `--` causes everything that follows to be treated as -# arguments, even those that look like options: -# -# $ irb --noscript -- --noscript -- Foo Bar Baz -# irb(main):001> ARGV -# => ["--noscript", "--", "Foo", "Bar", "Baz"] -# irb(main):002> exit -# $ -# -# ### Configuration File -# -# You can initialize IRB via a *configuration file*. -# -# If command-line option `-f` is given, no configuration file is looked for. -# -# Otherwise, IRB reads and interprets a configuration file if one is available. -# -# The configuration file can contain any Ruby code, and can usefully include -# user code that: -# -# * Can then be debugged in IRB. -# * Configures IRB itself. -# * Requires or loads files. -# -# -# The path to the configuration file is the first found among: -# -# * The value of variable `$IRBRC`, if defined. -# * The value of variable `$XDG_CONFIG_HOME/irb/irbrc`, if defined. -# * File `$HOME/.irbrc`, if it exists. -# * File `$HOME/.config/irb/irbrc`, if it exists. -# * File `.irbrc` in the current directory, if it exists. -# * File `irb.rc` in the current directory, if it exists. -# * File `_irbrc` in the current directory, if it exists. -# * File `$irbrc` in the current directory, if it exists. -# -# -# If the search fails, there is no configuration file. -# -# If the search succeeds, the configuration file is read as Ruby code, and so -# can contain any Ruby programming you like. -# -# Method `conf.rc?` returns `true` if a configuration file was read, `false` -# otherwise. Hash entry `IRB.conf[:RC]` also contains that value. -# -# ### 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`. -# -# Details of the entries' meanings are described in the relevant subsections -# below. -# -# If you are interested in a specific entry, consult the -# [index](rdoc-ref:doc/irb/indexes.md@Index+of+IRB.conf+Entries). -# -# ### 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. -# -# -# ### Initialization Script -# -# By default, the first command-line argument (after any options) is the path to -# a Ruby initialization script. -# -# IRB reads the initialization script and puts its content onto the IRB shell, -# just as if it were user-typed commands. -# -# Command-line option `--noscript` causes the first command-line argument to be -# treated as an ordinary argument (instead of an initialization script); -# `--script` is the default. -# -# ## Input -# -# This section describes the features that allow you to change the way IRB input -# works; see also [Input and Output](rdoc-ref:IRB@Input+and+Output). -# -# ### Input Command History -# -# By default, IRB stores a history of up to 1000 input commands in a file named -# `.irb_history`. The history file will be in the same directory as the -# [configuration file](rdoc-ref:IRB@Configuration+File) if one is found, or in -# `~/` otherwise. -# -# A new IRB session creates the history file if it does not exist, and appends -# to the file if it does exist. -# -# You can change the filepath by adding to your configuration file: -# `IRB.conf[:HISTORY_FILE] = *filepath*`, where *filepath* is a string filepath. -# -# During the session, method `conf.history_file` returns the filepath, and -# method `conf.history_file = *new_filepath*` copies the history to the file at -# *new_filepath*, which becomes the history file for the session. -# -# You can change the number of commands saved by adding to your configuration -# file: `IRB.conf[:SAVE_HISTORY] = *n*`, where *n* is one of: -# -# * Positive integer: the number of commands to be saved. -# * Negative integer: all commands are to be saved. -# * Zero or `nil`: no commands are to be saved. -# -# -# During the session, you can use methods `conf.save_history` or -# `conf.save_history=` to retrieve or change the count. -# -# ### Command Aliases -# -# By default, IRB defines several command aliases: -# -# irb(main):001> conf.command_aliases -# => {:"$"=>:show_source, :"@"=>:whereami} -# -# You can change the initial aliases in the configuration file with: -# -# IRB.conf[:COMMAND_ALIASES] = {foo: :show_source, bar: :whereami} -# -# You can replace the current aliases at any time with configuration method -# `conf.command_aliases=`; Because `conf.command_aliases` is a hash, you can -# modify it. -# -# ### End-of-File -# -# By default, `IRB.conf[:IGNORE_EOF]` is `false`, which means that typing the -# end-of-file character `Ctrl-D` causes the session to exit. -# -# You can reverse that behavior by adding `IRB.conf[:IGNORE_EOF] = true` to the -# configuration file. -# -# During the session, method `conf.ignore_eof?` returns the setting, and method -# `conf.ignore_eof = *boolean*` sets it. -# -# ### SIGINT -# -# By default, `IRB.conf[:IGNORE_SIGINT]` is `true`, which means that typing the -# interrupt character `Ctrl-C` causes the session to exit. -# -# You can reverse that behavior by adding `IRB.conf[:IGNORE_SIGING] = false` to -# the configuration file. -# -# During the session, method `conf.ignore_siging?` returns the setting, and -# method `conf.ignore_sigint = *boolean*` sets it. -# -# ### Automatic Completion -# -# By default, IRB enables [automatic -# completion](https://en.wikipedia.org/wiki/Autocomplete#In_command-line_interpr -# eters): -# -# You can disable it by either of these: -# -# * Adding `IRB.conf[:USE_AUTOCOMPLETE] = false` to the configuration file. -# * Giving command-line option `--noautocomplete` (`--autocomplete` is the -# default). -# -# -# Method `conf.use_autocomplete?` returns `true` if automatic completion is -# enabled, `false` otherwise. -# -# The setting may not be changed during the session. -# -# ### Automatic Indentation -# -# By default, IRB automatically indents lines of code to show structure (e.g., -# it indent the contents of a block). -# -# The current setting is returned by the configuration method -# `conf.auto_indent_mode`. -# -# The default initial setting is `true`: -# -# irb(main):001> conf.auto_indent_mode -# => true -# irb(main):002* Dir.entries('.').select do |entry| -# irb(main):003* entry.start_with?('R') -# irb(main):004> end -# => ["README.md", "Rakefile"] -# -# You can change the initial setting in the configuration file with: -# -# IRB.conf[:AUTO_INDENT] = false -# -# Note that the *current* setting *may not* be changed in the IRB session. -# -# ### Input Method -# -# The IRB input method determines how command input is to be read; by default, -# the input method for a session is IRB::RelineInputMethod. Unless the -# value of the TERM environment variable is 'dumb', in which case the -# most simplistic input method is used. -# -# You can set the input method by: -# -# * Adding to the configuration file: -# -# * `IRB.conf[:USE_SINGLELINE] = true` or `IRB.conf[:USE_MULTILINE]= -# false` sets the input method to IRB::ReadlineInputMethod. -# * `IRB.conf[:USE_SINGLELINE] = false` or `IRB.conf[:USE_MULTILINE] = -# true` sets the input method to IRB::RelineInputMethod. -# -# -# * Giving command-line options: -# -# * `--singleline` or `--nomultiline` sets the input method to -# IRB::ReadlineInputMethod. -# * `--nosingleline` or `--multiline` sets the input method to -# IRB::RelineInputMethod. -# * `--nosingleline` together with `--nomultiline` sets the -# input to IRB::StdioInputMethod. -# -# -# Method `conf.use_multiline?` and its synonym `conf.use_reline` return: -# -# * `true` if option `--multiline` was given. -# * `false` if option `--nomultiline` was given. -# * `nil` if neither was given. -# -# -# Method `conf.use_singleline?` and its synonym `conf.use_readline` return: -# -# * `true` if option `--singleline` was given. -# * `false` if option `--nosingleline` was given. -# * `nil` if neither was given. -# -# -# ## Output -# -# This section describes the features that allow you to change the way IRB -# output works; see also [Input and Output](rdoc-ref:IRB@Input+and+Output). -# -# ### Return-Value Printing (Echoing) -# -# By default, IRB prints (echoes) the values returned by all input commands. -# -# You can change the initial behavior and suppress all echoing by: -# -# * Adding to the configuration file: `IRB.conf[:ECHO] = false`. (The default -# value for this entry is `nil`, which means the same as `true`.) -# * Giving command-line option `--noecho`. (The default is `--echo`.) -# -# -# During the session, you can change the current setting with configuration -# method `conf.echo=` (set to `true` or `false`). -# -# As stated above, by default IRB prints the values returned by all input -# commands; but IRB offers special treatment for values returned by assignment -# statements, which may be: -# -# * Printed with truncation (to fit on a single line of output), which is the -# default; an ellipsis (`...` is suffixed, to indicate the truncation): -# -# irb(main):001> x = 'abc' * 100 -# -# -# > "abcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabc... -# -# * Printed in full (regardless of the length). -# * Suppressed (not printed at all) -# -# -# You can change the initial behavior by: -# -# * Adding to the configuration file: `IRB.conf[:ECHO_ON_ASSIGNMENT] = false`. -# (The default value for this entry is `niL`, which means the same as -# `:truncate`.) -# * Giving command-line option `--noecho-on-assignment` or -# `--echo-on-assignment`. (The default is `--truncate-echo-on-assignment`.) -# -# -# During the session, you can change the current setting with configuration -# method `conf.echo_on_assignment=` (set to `true`, `false`, or `:truncate`). -# -# By default, IRB formats returned values by calling method `inspect`. -# -# You can change the initial behavior by: -# -# * Adding to the configuration file: `IRB.conf[:INSPECT_MODE] = false`. (The -# default value for this entry is `true`.) -# * Giving command-line option `--noinspect`. (The default is `--inspect`.) -# -# -# During the session, you can change the setting using method -# `conf.inspect_mode=`. -# -# ### Multiline Output -# -# By default, IRB prefixes a newline to a multiline response. -# -# You can change the initial default value by adding to the configuration file: -# -# IRB.conf[:NEWLINE_BEFORE_MULTILINE_OUTPUT] = false -# -# During a session, you can retrieve or set the value using methods -# `conf.newline_before_multiline_output?` and -# `conf.newline_before_multiline_output=`. -# -# Examples: -# -# irb(main):001> conf.inspect_mode = false -# => false -# irb(main):002> "foo\nbar" -# => -# foo -# bar -# irb(main):003> conf.newline_before_multiline_output = false -# => false -# irb(main):004> "foo\nbar" -# => foo -# bar -# -# ### Evaluation History -# -# By default, IRB saves no history of evaluations (returned values), and the -# related methods `conf.eval_history`, `_`, and `__` are undefined. -# -# You can turn on that history, and set the maximum number of evaluations to be -# stored: -# -# * In the configuration file: add `IRB.conf[:EVAL_HISTORY] = *n*`. (Examples -# below assume that we've added `IRB.conf[:EVAL_HISTORY] = 5`.) -# * In the session (at any time): `conf.eval_history = *n*`. -# -# -# If `n` is zero, all evaluation history is stored. -# -# Doing either of the above: -# -# * Sets the maximum size of the evaluation history; defines method -# `conf.eval_history`, which returns the maximum size `n` of the evaluation -# history: -# -# irb(main):001> conf.eval_history = 5 -# => 5 -# irb(main):002> conf.eval_history -# => 5 -# -# * Defines variable `_`, which contains the most recent evaluation, or `nil` -# if none; same as method `conf.last_value`: -# -# irb(main):003> _ -# => 5 -# irb(main):004> :foo -# => :foo -# irb(main):005> :bar -# => :bar -# irb(main):006> _ -# => :bar -# irb(main):007> _ -# => :bar -# -# * Defines variable `__`: -# -# * `__` unadorned: contains all evaluation history: -# -# irb(main):008> :foo -# => :foo -# irb(main):009> :bar -# => :bar -# irb(main):010> :baz -# => :baz -# irb(main):011> :bat -# => :bat -# irb(main):012> :bam -# => :bam -# irb(main):013> __ -# => -# 9 :bar -# 10 :baz -# 11 :bat -# 12 :bam -# irb(main):014> __ -# => -# 10 :baz -# 11 :bat -# 12 :bam -# 13 ...self-history... -# -# Note that when the evaluation is multiline, it is displayed -# differently. -# -# * `__[`*m*`]`: -# -# * Positive *m*: contains the evaluation for the given line number, -# or `nil` if that line number is not in the evaluation history: -# -# irb(main):015> __[12] -# => :bam -# irb(main):016> __[1] -# => nil -# -# * Negative *m*: contains the `mth`-from-end evaluation, or `nil` if -# that evaluation is not in the evaluation history: -# -# irb(main):017> __[-3] -# => :bam -# irb(main):018> __[-13] -# => nil -# -# * Zero *m*: contains `nil`: -# -# irb(main):019> __[0] -# => nil -# -# -# -# -# ### Prompt and Return Formats -# -# By default, IRB uses the prompt and return value formats defined in its -# `:DEFAULT` prompt mode. -# -# #### The Default Prompt and Return Format -# -# The default prompt and return values look like this: -# -# irb(main):001> 1 + 1 -# => 2 -# irb(main):002> 2 + 2 -# => 4 -# -# The prompt includes: -# -# * The name of the running program (`irb`); see [IRB -# Name](rdoc-ref:IRB@IRB+Name). -# * The name of the current session (`main`); See [IRB -# Sessions](rdoc-ref:IRB@IRB+Sessions). -# * A 3-digit line number (1-based). -# -# -# The default prompt actually defines three formats: -# -# * One for most situations (as above): -# -# irb(main):003> Dir -# => Dir -# -# * One for when the typed command is a statement continuation (adds trailing -# asterisk): -# -# irb(main):004* Dir. -# -# * One for when the typed command is a string continuation (adds trailing -# single-quote): -# -# irb(main):005' Dir.entries('. -# -# -# You can see the prompt change as you type the characters in the following: -# -# irb(main):001* Dir.entries('.').select do |entry| -# irb(main):002* entry.start_with?('R') -# irb(main):003> end -# => ["README.md", "Rakefile"] -# -# #### Pre-Defined Prompts -# -# IRB has several pre-defined prompts, stored in hash `IRB.conf[:PROMPT]`: -# -# irb(main):001> IRB.conf[:PROMPT].keys -# => [:NULL, :DEFAULT, :CLASSIC, :SIMPLE, :INF_RUBY, :XMP] -# -# To see the full data for these, type `IRB.conf[:PROMPT]`. -# -# Most of these prompt definitions include specifiers that represent values like -# the IRB name, session name, and line number; see [Prompt -# Specifiers](rdoc-ref:IRB@Prompt+Specifiers). -# -# You can change the initial prompt and return format by: -# -# * Adding to the configuration file: `IRB.conf[:PROMPT] = *mode*` where -# *mode* is the symbol name of a prompt mode. -# * Giving a command-line option: -# -# * `--prompt *mode*`: sets the prompt mode to *mode*. where *mode* is the -# symbol name of a prompt mode. -# * `--simple-prompt` or `--sample-book-mode`: sets the prompt mode to -# `:SIMPLE`. -# * `--inf-ruby-mode`: sets the prompt mode to `:INF_RUBY` and suppresses -# both `--multiline` and `--singleline`. -# * `--noprompt`: suppresses prompting; does not affect echoing. -# -# -# -# You can retrieve or set the current prompt mode with methods -# -# `conf.prompt_mode` and `conf.prompt_mode=`. -# -# If you're interested in prompts and return formats other than the defaults, -# you might experiment by trying some of the others. -# -# #### Custom Prompts -# -# You can also define custom prompts and return formats, which may be done -# either in an IRB session or in the configuration file. -# -# A prompt in IRB actually defines three prompts, as seen above. For simple -# custom data, we'll make all three the same: -# -# irb(main):001* IRB.conf[:PROMPT][:MY_PROMPT] = { -# irb(main):002* PROMPT_I: ': ', -# irb(main):003* PROMPT_C: ': ', -# irb(main):004* PROMPT_S: ': ', -# irb(main):005* RETURN: '=> ' -# irb(main):006> } -# => {:PROMPT_I=>": ", :PROMPT_C=>": ", :PROMPT_S=>": ", :RETURN=>"=> "} -# -# If you define the custom prompt in the configuration file, you can also make -# it the current prompt by adding: -# -# IRB.conf[:PROMPT_MODE] = :MY_PROMPT -# -# Regardless of where it's defined, you can make it the current prompt in a -# session: -# -# conf.prompt_mode = :MY_PROMPT -# -# You can view or modify the current prompt data with various configuration -# methods: -# -# * `conf.prompt_mode`, `conf.prompt_mode=`. -# * `conf.prompt_c`, `conf.c=`. -# * `conf.prompt_i`, `conf.i=`. -# * `conf.prompt_s`, `conf.s=`. -# * `conf.return_format`, `return_format=`. -# -# -# #### Prompt Specifiers -# -# A prompt's definition can include specifiers for which certain values are -# substituted: -# -# * `%N`: the name of the running program. -# * `%m`: the value of `self.to_s`. -# * `%M`: the value of `self.inspect`. -# * `%l`: an indication of the type of string; one of `"`, `'`, `/`, `]`. -# * `%NNi`: Indentation level. NN is a 2-digit number that specifies the number -# of digits of the indentation level (03 will result in 001). -# * `%NNn`: Line number. NN is a 2-digit number that specifies the number -# of digits of the line number (03 will result in 001). -# * `%%`: Literal `%`. -# -# -# ### Verbosity -# -# By default, IRB verbosity is disabled, which means that output is smaller -# rather than larger. -# -# You can enable verbosity by: -# -# * Adding to the configuration file: `IRB.conf[:VERBOSE] = true` (the default -# is `nil`). -# * Giving command-line options `--verbose` (the default is `--noverbose`). -# -# -# During a session, you can retrieve or set verbosity with methods -# `conf.verbose` and `conf.verbose=`. -# -# ### Help -# -# Command-line option `--version` causes IRB to print its help text and exit. -# -# ### Version -# -# Command-line option `--version` causes IRB to print its version text and exit. -# -# ## Input and Output -# -# ### Color Highlighting -# -# By default, IRB color highlighting is enabled, and is used for both: -# -# * Input: As you type, IRB reads the typed characters and highlights elements -# that it recognizes; it also highlights errors such as mismatched -# parentheses. -# * Output: IRB highlights syntactical elements. -# -# -# You can disable color highlighting by: -# -# * Adding to the configuration file: `IRB.conf[:USE_COLORIZE] = false` (the -# default value is `true`). -# * Giving command-line option `--nocolorize` -# -# -# ## Debugging -# -# Command-line option `-d` sets variables `$VERBOSE` and `$DEBUG` to `true`; -# these have no effect on IRB output. -# -# ### Warnings -# -# Command-line option `-w` suppresses warnings. -# -# Command-line option `-W[*level*]` sets warning level; -# -# * 0=silence -# * 1=medium -# * 2=verbose -# -# ## Other Features -# -# ### 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): -# -# irb(main):001> conf.load_modules -# => [] -# -# You can set the default initial value via: -# -# * Command-line option `-r` -# -# $ irb -r csv -r json -# irb(main):001> conf.load_modules -# => ["csv", "json"] -# -# * Hash entry `IRB.conf[:LOAD_MODULES] = *array*`: -# -# 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): -# -# irb(main):001> conf.extra_doc_dirs -# => [] -# -# You can set the default initial value via: -# -# * Command-line option `--extra_doc_dir` -# -# $ 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*`: -# -# 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'`: -# -# irb(main):001> conf.irb_name -# => "irb" -# -# You can set the default initial value via hash entry `IRB.conf[:IRB_NAME] = -# *string*`: -# -# IRB.conf[:IRB_NAME] = 'foo' -# -# ### Application Name -# -# You can specify an application name for the IRB session. -# -# The default initial value is `'irb'`: -# -# irb(main):001> conf.ap_name -# => "irb" -# -# You can set the default initial value via hash entry `IRB.conf[:AP_NAME] = -# *string*`: -# -# 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: -# -# IRB.conf[:IRB_RC] = proc {|conf| puts conf.class } -# -# Each time the configuration is changed, that proc is called with argument -# `conf`: -# -# ### Encodings -# -# Command-line option `-E *ex*[:*in*]` sets initial external (ex) and internal -# (in) encodings. -# -# Command-line option `-U` sets both to UTF-8. -# -# ### Commands -# -# Please use the `help` command to see the list of available commands. -# -# ### IRB Sessions -# -# IRB has a special feature, that allows you to manage many sessions at once. -# -# You can create new sessions with Irb.irb, and get a list of current sessions -# with the `jobs` command in the prompt. -# -# #### Configuration -# -# The command line options, or IRB.conf, specify the default behavior of -# Irb.irb. -# -# On the other hand, each conf in IRB@Command-Line+Options is used to -# individually configure IRB.irb. -# -# If a proc is set for `IRB.conf[:IRB_RC]`, its will be invoked after execution -# of that proc with the context of the current session as its argument. Each -# session can be configured using this mechanism. -# -# #### Session variables -# -# There are a few variables in every Irb session that can come in handy: -# -# `_` -# : The value command executed, as a local variable -# `__` -# : The history of evaluated commands. Available only if -# `IRB.conf[:EVAL_HISTORY]` is not `nil` (which is the default). See also -# IRB::Context#eval_history= and IRB::History. -# `__[line_no]` -# : Returns the evaluation value at the given line number, `line_no`. If -# `line_no` is a negative, the return value `line_no` many lines before the -# most recent return value. -# -# -# ## Restrictions -# -# Ruby code typed into IRB behaves the same as Ruby code in a file, except that: -# -# * Because IRB evaluates input immediately after it is syntactically -# complete, some results may be slightly different. -# * Forking may not be well behaved. -# module IRB # An exception raised by IRB.irb_abort