From cf0c2adcd13cb2eca476ce95f80ac3a69e16d00a Mon Sep 17 00:00:00 2001 From: Stan Lo Date: Sat, 28 Dec 2024 18:54:00 +0000 Subject: [PATCH 1/2] Use the documentation site as the source of truth 1. Remove detailed content from README.md and point links to the documentation site. 2. Remove the content of EXTEND_IRB.md and point links to the documentation site. --- EXTEND_IRB.md | 121 +-------------------- README.md | 291 +++----------------------------------------------- 2 files changed, 13 insertions(+), 399 deletions(-) diff --git a/EXTEND_IRB.md b/EXTEND_IRB.md index 684b0b7b1..9cd27aa29 100644 --- a/EXTEND_IRB.md +++ b/EXTEND_IRB.md @@ -1,122 +1,3 @@ # 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 - 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 ` 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 -``` - -## 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 -``` +This page has been moved to the [IRB Extension Guide](https://ruby.github.io/irb/EXTEND_IRB_md.html). diff --git a/README.md b/README.md index 7186bc41a..b469eb715 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,14 @@ # IRB [![Gem Version](https://badge.fury.io/rb/irb.svg)](https://badge.fury.io/rb/irb) +[![Static Badge](https://img.shields.io/badge/RDoc-flat?style=flat&label=documentation&link=https%3A%2F%2Fruby.github.io%2Firb%2F)](https://ruby.github.io/irb/) [![build](https://github.com/ruby/irb/actions/workflows/test.yml/badge.svg)](https://github.com/ruby/irb/actions/workflows/test.yml) + 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. -- [Installation](#installation) -- [Usage](#usage) - - [The `irb` Executable](#the-irb-executable) - - [The `binding.irb` Breakpoint](#the-bindingirb-breakpoint) -- [Commands](#commands) -- [Debugging with IRB](#debugging-with-irb) - - [More about `debug.gem`](#more-about-debuggem) - - [Advantages Over `debug.gem`'s Console](#advantages-over-debuggems-console) -- [Type Based Completion](#type-based-completion) - - [How to Enable IRB::TypeCompletor](#how-to-enable-irbtypecompletor) - - [Advantage over Default IRB::RegexpCompletor](#advantage-over-default-irbregexpcompletor) - - [Difference between Steep's Completion](#difference-between-steeps-completion) -- [Configuration](#configuration) - - [Environment Variables](#environment-variables) -- [Documentation](#documentation) -- [Extending IRB](#extending-irb) -- [Development](#development) -- [Contributing](#contributing) -- [Releasing](#releasing) -- [License](#license) - ## Installation > [!Note] @@ -58,7 +39,7 @@ $ gem install irb > [!Note] > -> We're working hard to match Pry's variety of powerful features in IRB, and you can track our progress or find contribution ideas in [this document](https://github.com/ruby/irb/blob/master/COMPARED_WITH_PRY.md). +> We're working hard to match Pry's variety of powerful features in IRB, and you can track our progress or find contribution ideas in [this document](https://ruby.github.io/irb/COMPARED_WITH_PRY_md.html). ### The `irb` Executable @@ -105,276 +86,28 @@ irb(main):002:0> exit Hello World ``` -## Commands - -The following commands are available on IRB. You can get the same output from the `help` command. - -```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 a `irb:rdbg` session with access to all `debug.gem` commands. -- Use `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 boasts a powerful integration with `debug.gem`, providing a debugging experience akin to `pry-byebug`. - -After hitting a `binding.irb` breakpoint, you can activate the debugger with the `debug` command. Alternatively, if the `debug` method happens to already be defined in the current scope, you can call `irb_debug`. - -```shell -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): - -```shell -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`: - -```shell -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, please 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 will also display 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 also 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 has another 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: -``` -$ 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 -``` -$ 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. -``` -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 `sig/` directory or `rbs_collection.lock.yaml` in 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. - -```ruby -irb(main):001> 'Ruby'.upcase.chars.s # Array methods (sample, select, shift, size) -``` - -```ruby -irb(main):001> 10.times.map(&:to_s).each do |s| -irb(main):002> s.up # String methods (upcase, upcase!, upto) -``` +### Debugging -```ruby -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. +You can use IRB as a debugging console with `debug.gem` with these options: -### Difference between Steep's Completion +- 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. -Compared with Steep, IRB::TypeCompletor has some difference and limitations. -```ruby -[0, 'a'].sample. -# Steep completes intersection of Integer methods and String methods -# IRB::TypeCompletor completes both Integer and String methods -``` +To learn more about debugging with IRB, see [Debugging with IRB](https://ruby.github.io/irb/#label-Debugging+with+IRB). -Some features like type narrowing is not implemented. -```ruby -def f(arg = [0, 'a'].sample) - if arg.is_a?(String) - arg. # Completes both Integer and String methods -``` +## Documentation -Unlike other static type checker, IRB::TypeCompletor uses runtime information to provide better completion. -```ruby -irb(main):001> a = [1] -=> [1] -irb(main):002> a.first. # Completes Integer methods -``` +https://ruby.github.io/irb/ provides a comprehensive guide to IRB's features and usage. ## 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 would be used to open files by the `edit` command. -- `EDITOR`: Its value would be used to open files by the `edit` command if `VISUAL` is unset. -- `IRBRC`: The file specified would be evaluated as IRB's rc-file. -- `XDG_CONFIG_HOME`: If it is set and `IRBRC` is unset, the file `$XDG_CONFIG_HOME/irb/irbrc` would be evaluated as IRB's rc-file. -- `RI_PAGER`: The command specified would be used as a pager. -- `PAGER`: The command specified would be used as a pager if `RI_PAGER` is unset. -- `IRB_LANG`, `LC_MESSAGES`, `LC_ALL`, `LANG`: The first of these that is set would be used as the locale value. - -## Documentation - -https://ruby.github.io/irb/ +See the [Configuration page](https://ruby.github.io/irb/Configurations_md.html) in the documentation. ## Extending IRB IRB `v1.13.0` and later versions allows users/libraries to extend its functionality through official APIs. -For more information, please visit [EXTEND_IRB.md](./EXTEND_IRB.md). +For more information, please visit the [IRB Extension Guide](https://ruby.github.io/irb/EXTEND_IRB_md.html). ## Development From 7720346f170e313a344c1c2ff7dc72c91f6a15f5 Mon Sep 17 00:00:00 2001 From: Stan Lo Date: Sat, 28 Dec 2024 19:01:00 +0000 Subject: [PATCH 2/2] Use GitHub pages as Rubygems' documentation target --- irb.gemspec | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/irb.gemspec b/irb.gemspec index d3d481d08..6bb257c8c 100644 --- a/irb.gemspec +++ b/irb.gemspec @@ -18,7 +18,7 @@ Gem::Specification.new do |spec| spec.metadata["homepage_uri"] = spec.homepage spec.metadata["source_code_uri"] = spec.homepage - spec.metadata["documentation_uri"] = spec.homepage + spec.metadata["documentation_uri"] = "https://ruby.github.io/irb/" spec.metadata["changelog_uri"] = "#{spec.homepage}/releases" spec.files = [