23s2s

✏️ Editing: RI.md

# `ri`: Ruby Information

`ri` (ruby information) is the Ruby command-line utility
that gives fast and easy on-line access to Ruby documentation.

`ri` can show documentation for Ruby itself and for its installed gems:

- A **class** or **module**:
  text associated with the class or module definition
  in a source file (`.rb` or `.c`).
- One or more **methods**:
  text associated with method definitions
  in source files (`.rb` and `.c`).
- A **page**:
  text from a stand-alone documentation file
  (`.rdoc` or  `.md`, or sometimes other).

Examples (output omitted):

```sh
$ ri Hash             # Document for class Hash.
$ ri Array#sort       # Document for instance method sort in class Array.
$ ri read             # Documents for methods ::read and #read in all classes and modules.
$ ri ruby:dig_methods # Document for page dig_methods.
```

`ri` can also show lists of:

- **classes** and **modules**:
  full or partial list.
- **pages**:
  for Ruby or for an installed gem.

Examples (output omitted):

```sh
$ ri --list # List of classes and modules.
$ ri ruby:  # List of Ruby pages.
```

## Why `ri`?

Using `ri` may have advantages over using
the [Ruby online documentation](https://docs.ruby-lang.org/en/master):

- The `ri` documentation is always available, even when you do not have internet access
  (think: airplane mode).
- If you are working in a terminal window, typing `ri _whatever_` (or just `ri`)
  may be faster than navigating to a browser window and searching for documentation.
- If you are working in an
  [irb $interactive Ruby$](https://ruby.github.io/irb/index.html)
  session, you _already_ have immediate access to `ri`:
  just type `'show_doc'`.

## Modes

There are two `ri` modes:

- Static mode:
 In general, `ri` responds in its static mode
 if a _name_ is given;
 it shows results and exits (as in the examples above).
 See [Static Mode][1].
- Interactive mode:
 In general, `ri` enters its interactive mode
 if no _name_ is given;
 in interactive mode, `ri` shows results and waits for another command:

```sh
    $ ri
    Enter the method name you want to look up.
    You can use tab to autocomplete.
    Enter a blank line to exit.
    >>
    ```

See [Interactive Mode][2].

## Names

In both modes, static and interactive,
`ri` responds to an input _name_ that specifies what is to be displayed:
a document, multiple documents, or other information:

- Static mode (in the shell): type `'ri _name_'`;
  examples (output omitted):

```sh
    $ ri File
    $ ri IO#readlines
    $ ri ruby:
    ```

- Interactive mode (already in `ri`): just type the _name_;
  examples (output omitted):

```sh
    $ ri
    Enter the method name you want to look up.
    You can use tab to autocomplete.
    Enter a blank line to exit.
    >> File
    >> IO#readlines
    >> ruby:
    ```

### Names for Class and Module Documents

These example `ri` commands cite names for class and module documents
(see [details and examples][3]):

| Command | Shows |
|------------------------------|------------------------------------------------------------|
| ri File | Document for Ruby class File. |
| ri File::Stat | Document for Ruby nested class File::Stat. |
| ri Enumerable | Document for Ruby module Enumerable. |
| ri Arr | Document for Ruby class Array (unique initial characters). |
| ri Nokogiri::HTML4::Document | Document for gem class Nokogiri::HTML4::Document. |
| ri Nokogiri | Document for gem module Nokogiri. |

If [option \\--all][4]
is in effect, documents for the methods in the named class or module
are included in the display.

### Names for Method Documents

These example `ri` commands cite names for method documents
(see [details and examples][5]):

| Command | Shows |
|--------------------------------------|----------------------------------------------------------------------------------|
| ri IO::readlines | Document for Ruby class method IO::readlines. |
| ri IO#readlines | Document for Ruby instance method IO::readlines. |
| ri IO.readlines | Documents for Ruby instance method IO::readlines and class method IO::readlines. |
| ri ::readlines | Documents for all class methods ::readlines. |
| ri #readlines | Documents for all instance methods #readlines. |
| ri .readlines, ri readlines | Documents for class methods ::readlines and instance methods #readlines. |
| ri Nokogiri::HTML4::Document::parse | Document for gem class method Nokogiri::HTML4::Document::parse. |
| ri Nokogiri::HTML4::Document#fragment | Document for gem instance method Nokogiri::HTML4::Document#fragment. |

### Names for Page Documents

These example `ri` commands cite names for page documents
(see [details and examples][6]):

| Command | Shows |
|--------------------------------|--------------------------------------------------|
| ri ruby:syntax/assignment.rdoc | Document for Ruby page assignment. |
| ri ruby:syntax/assignment | Same document, if no other syntax/assignment.*. |
| ri ruby:assignment | Same document, if no other */assignment.*. |
| ri nokogiri:README.md | Document for page README.md. |

### Names for Lists

These example `ri` commands cite names for lists
(see [details and examples][7]):

| Command | Shows |
|---------------|-------------------------|
| ri ruby: | List of Ruby pages. |
| ri nokogiri: | List of Nokogiri pages. |

There are more lists available;
see [option \\--list][8].

## Pro Tips

### `ri` at the Ready

If you are a frequent `ri` user,
you can save time by keeping open a dedicated command window
with either of:

- A running [interactive ri][2] session.
- A running [irb session][9];
  type `'show_doc'` to enter `ri`, newline to exit.

When you switch to that window, `ri` is ready to respond quickly,
without the performance overhead of re-reading `ri` sources.

### Output Filters

The `pager` value actually need not be simply the path to an executable;
it's actually a full-fledged command line,
and so may include not only the executable path,
but also whatever options and arguments that executable accepts.

You can, for example, set the pager value to `'grep . | less'`,
which will exclude blank lines (thus saving screen space)
before piping the result to `less`;
example (output omitted):

```sh
$ RI_PAGER="grep . | less" ri Array
```

See the documentation for your chosen pager programs
(e.g, type `'grep --help'`, `'less --help'`).

### Links  in `ri` Output

#### Implicit Link

When you see:

- `'IO::readlines'`, `'IO#readlines'`, `'IO.readlines'`:
  use that same text as the _name_ in an `ri` command.

Examples (output omitted):

```sh
    $ ri IO::readlines
    $ ri IO#readlines
    $ ri IO.readlines
    ```

- `'#read'`, `'::read'`, `'.read'`:
  you're likely already in the `ri` document for a class or module,
  or for a method in a class or module;
  use that same text with the name of the class or module (such as `'File'`)
  as the _name_ in an `ri` command.

Examples (output omitted):

```sh
    $ ri File::read
    $ ri File#read
    $ ri File.read
    ```

#### Explicit Link

When you see:

- `'{Dig Methods}[rdoc-ref:doc/dig_methods.rdoc]'`:
   use the trailing part of the `'[rdoc-ref:doc/'` in an `ri` command
   for a Ruby document.

Example (output omitted):

```sh
    $ ri ruby:dig_methods.rdoc
    ```

- `'{Table (information)}[https://en.wikipedia.org/wiki/Table_(information)]'`:
  go to the given URL in your browser.

## About the Examples

- `ri` output can be large;
  to save space, an example may pipe it to one of these:

- [head](https://www.man7.org/linux/man-pages/man1/head.1.html): leading lines only.
    - [tail](https://www.man7.org/linux/man-pages/man1/tail.1.html): trailing lines only.
    - [wc -l](https://www.man7.org/linux/man-pages/man1/wc.1.html): line count only.
    - [grep](https://www.man7.org/linux/man-pages/man1/grep.1.html): selected lines only.

- An example that involves a gem assumes that gems `nokogiri` and `minitest` are installed.

## `ri` Documents

This section outlines what you can expect to find
in the `ri` document for a class, module, method, or page.

See also [Output Filters][19].

## Options

Options may be given on the `ri` command line;
those should be whitespace-separated, and must precede the given _name_, if any.

Options may also be specified in environment variable `RI`;
those should also be whitespace-separated.

An option specified in environment variable `RI`
may be overridden by an option on the `ri` command line:

```sh
$ RI="--all" ri Array | wc -l
4224
$ RI="--all" ri --no-all Array | wc -l
390
```

### Source Directories Options

#### Options `--doc-dir=DIRPATH`, `-d DIRPATH`

Option `--doc-dir=DIRPATH` (aliased as `-d`) adds the given directory path
to the beginning of the array of `ri` source directory paths:

```sh
$ ri --doc-dir=/tmp --list-doc-dirs | head -1
/tmp
```

#### Options `--gems`, `--no-gems`

Option `--gems` (the default) specifies that documents from installed gems
may be included;
option `--no-gems` may be used to exclude them:

```sh
$ ri --list | wc -l
1417
$ ri --list --no-gems| wc -l
1262
```

#### Options `--home`, `--no-home`

Option `--home` (the default) specifies that `ri` is to include source directory
in `~/.rdoc` if it exists;
option `--no-home` may be used to exclude them.

#### Options `--list-doc-dirs`, `--no-list-doc-dirs`

Option `--list-doc-dirs` specifies that a list of the `ri` source directories
is to be displayed;
default is `--no-list-doc-dirs`.

#### Option `--no-standard`

Option `--no-standard` specifies that documents from the standard libraries
are not to be included;
default is to include documents from the standard libraries.

#### Options `--site`, `--no-site`

Option `--site` (the default) specifies that documents from the site libraries
may be included;
option `--no-site` may be used to exclude them.

#### Options `--system`, `--no-system`

Option `--system` (the default) specifies that documents from the system libraries
may be included;
option `--no-system` may be used to exclude them.

### Mode Options

#### Options `--interactive`, `-i`, `--no-interactive`

Option `--interactive` (aliased as `-i`)
specifies that `ri` is to enter interactive mode (ignoring the _name_ if given);
the option is the default when no _name_ is given;
option `--no-interactive` (the default)
specifies that `ri` is not to enter interactive mode,
regardless of whether _name_ is given.

### Information Options

#### Options `--help`, `-h`

Option `--help` (aliased as `-h`) specifies that `ri` is to show
its help text and exit.

#### Options `--version`, `-v`

Option `--version` (aliased as `-v`) specifies that `ri` is to show its version and exit.

### Debugging Options

#### Options `--dump=FILEPATH`, `--no-dump`

Option `--dump=FILEPATH` specifies that `ri` is to dump the content
of the `.ri` file at the given file path;
option`--no-dump` (the default) specifies that `ri` is not to dump content.

The file path may point to any `.ri` file,
but typically would point to one named `cache.ri`:

```sh
$ ri --dump=/usr/share/ri/3.0.0/system/cache.ri | wc -l
14487
$ ri --dump=/usr/share/ri/3.0.0/system/cache.ri | head
{:ancestors=>
  {"Array"=>["Enumerable", "Object"],
   "RubyVM"=>["Object"],
   "RubyVM::AbstractSyntaxTree::Node"=>["Object"],
   "Object"=>["BasicObject", "Kernel"],
   "Integer"=>["Numeric"],
   "Module"=>["Object"],
   "Class"=>["Module"],
   "Complex"=>["Numeric"],
   "NilClass"=>["Object"],
```

#### Options `--profile`, `--no-profile`

Option `--profile` specifies that the program is to be run with the Ruby profiler;
option `no-profile` (the default) specifies that the program is not to be run
with the Ruby profiler.

### Output Options

#### Options `--format=FORMAT`, `-f FORMAT`

Option `--format=FORMAT` (aliased as `-f`) specifies the formatter for the output,
which must be `ansi`, `bs`, `markdown`, or `rdoc`;
the default is `bs` for paged output, `ansi` otherwise.

#### Options `--pager`, `--no-pager`

Option `--pager` (the default) specifies that the output is to be piped
to a pager;
option `--no-pager` specifies that the output is not to be piped.

#### Options `--width=NUMBER`, `-w NUMBER`

Option `--width` (aliased as `-w`) specifies that the lengths of the displayed lines
should be restricted to the given _NUMBER_ of characters;
this is to be accomplished by line-wrapping, not truncation.
The default width is `80`:

```sh
$ ri --width=40 Array | head
= Array < Object

----------------------------------------
= Includes:
Enumerable (from ruby core)

(from ruby core)
----------------------------------------
An Array is an ordered, integer-indexed
collection of objects, called
```

### List Options

#### Options `--list`, `-l`, `--no-list`

Option `--list` (aliased as `-l`) specifies that all class and module names
whose initial characters match the given _name_ are to be displayed:
whose initial characters match the given _name_ are to be displayed:

```sh
$ ri --list Ar | head
ArgumentError
Array
```

If no _name_ is given, all class and module names are displayed.

Option `--no-list` (the default) specifies that a list of class and module names
is not to be displayed.

### Methods Options (for Class or Module)

#### Options `--all`, `-a`, `--no-all`

Option `--all` (aliased as `-a`) specifies that when _name_ identifies a class or module,
the documents for all its methods are included;
option `--no-all` (the default) specifies that the method documents are not to be included:

```shell
$ ri Array | wc -l
390
$ ri --all Array | wc -l
4224
```

### Server Option

#### Option `--server=NUMBER`

Option `--server` specifies that the \RDoc server is to be run on the port
given as _NUMBER_;
the default port is `8214`.

## Generating `ri` Source Files

`ri` by default reads data from directories installed by Ruby and gems.

You can create your own `ri` source files.
This command creates `ri` source files in local directory `my_ri`,
from Ruby source files in local directory `my_sources`:

```sh
$ rdoc --op my_ri --format=ri my_sources
```

Those files may then be considered for any `ri` command
by specifying option `--doc-dir=my_ri`;
see [option \\--doc-dir][20].

[1]: rdoc-ref:RI.md@Static+Mode
[2]: rdoc-ref:RI.md@Interactive+Mode
[3]: rdoc-ref:RI.md@Class+and+Module+Documents
[4]: rdoc-ref:RI.md@Options+--all-2C+-a-2C+--no-all
[5]: rdoc-ref:RI.md@Method+Documents
[6]: rdoc-ref:RI.md@Page+Documents
[7]: rdoc-ref:RI.md@ri+Lists
[8]: rdoc-ref:RI.md@Options+--list-2C+-l-2C+--no-list
[9]: https://docs.ruby-lang.org/en/master/IRB.html
[10]: rdoc-ref:RI.md@Pager
[11]: rdoc-ref:RI.md@Links+in+ri+Output
[12]: rdoc-ref:RI.md@Options+--list-doc-dirs-2C+--no-list-doc-dirs
[13]: rdoc-ref:RI.md@Options+--help-2C+-h
[14]: rdoc-ref:RI.md@Options+--version-2C+-v
[15]: rdoc-ref:RI.md@Options+--dump-3DFILEPATH-2C+--no-dump
[16]: rdoc-ref:RI.md@ri+Information
[17]: rdoc-ref:RI.md@Options
[18]: rdoc-ref:RI.md@ri+at+the+Ready
[19]: rdoc-ref:RI.md@Output+Filters
[20]: rdoc-ref:RI.md@Options+--doc-dir-3DDIRPATH-2C+-d+DIRPATH

Sid Gifari From Gifari Industries - BD Cyber Security Team