skip to content

With Ruby's ri command, how do ri Array#sort, ri IO::readlines and ri IO.readlines differ, and why can ri know nothing about a gem?

level: juniorimportance: should knowfreq 26%

answer

  1. # instance, :: class method
  2. dot means both kinds
  3. ri with no name is interactive
  4. Nothing known about ...
  5. gem install --no-document skips ri data

basics

~20 s

ri prints installed Ruby documentation in the terminal: Array#sort names an instance method, IO::readlines a class method, and IO.readlines matches both. A gem installed with --no-document has no ri data, so ri reports Nothing known about it.

solid answer

~40 s

`ri` (Ruby information) reads the ri data that RDoc generated and prints it offline. The separator picks the method kind: `ri Array#sort` is the **instance** method, `ri IO::readlines` the **class** method, and `ri IO.readlines` shows **both** `IO::readlines` and `IO#readlines`. A bare `ri readlines` searches every class, `ri Arr` accepts a unique prefix, `ri --list` lists known classes, `ri ruby:` lists Ruby's own pages, and `ri` with no name opens an interactive prompt with completion. ri only knows what was generated: `gem install` builds ri data by default, but `--no-document` (often set in `.gemrc`) skips it, and ri then answers `Nothing known about GeoLookup`. `gem rdoc geo_lookup --ri` builds it afterwards, and `rdoc --ri` does the same for your own project.

code

bash · 5 lines
bash
ri Array#sort          # instance method
ri IO::readlines       # class method
ri IO.readlines        # both kinds
ri --list | grep Geo   # which classes ri knows
gem rdoc geo_lookup --ri

go deeper

for a junior

Recall the separators: # for an instance method, :: for a class method, a dot for both. Know that ri with no name opens an interactive prompt.

for a middle

Explain that ri reads pre-generated data from system, site, home and gem sources, and why --no-document installs leave it blind.

for a senior

Show you can recover: gem rdoc NAME --ri for an installed gem, rdoc --ri for local code, and using ri to read the exact installed version of an API offline.

for a principal

Treat terminal docs as a developer-environment choice: a team default of --no-document speeds installs but removes offline, version-exact documentation, which matters on restricted networks.

## What ri is **`ri`** (short for *Ruby information*) is the terminal documentation viewer that comes with RDoc. It does not parse source code at lookup time. It reads **ri data**: pre-generated documentation files that RDoc wrote when Ruby itself was installed, when a gem was installed, or when you ran `rdoc --ri`. Because the data is local, `ri` works offline and is fast to reach from a shell. ## Naming what you want The separator between the class and the method decides which kind of method you get: | Command | Shows | |---|---| | `ri Array` | the class `Array` | | `ri Array#sort` | the instance method `sort` | | `ri IO::readlines` | the class (singleton) method `readlines` | | `ri IO.readlines` | both `IO::readlines` and `IO#readlines` | | `ri readlines` | every `::readlines` and `#readlines` it knows | | `ri Arr` | `Array`, because the prefix is unique | | `ri ruby:` | the list of Ruby's stand-alone pages | The `#` versus `::` convention is the same one Ruby documentation uses in prose, so it is worth being precise: `File.read` in a sentence is ambiguous, `File::read` is the class method. ## Useful options - `ri --list` (or `-l`) lists the classes and modules ri knows about. - `ri --all Array` (or `-a`) shows every method's documentation for the class in one go. - `ri` with no name starts **interactive mode**: you type names at a prompt, with tab completion, and a blank line exits. - `ri -T` (a synonym for `--no-pager`) prints straight to standard output, which is what you want in scripts. - `ri --list-doc-dirs` prints the directories ri searches. - Options can also be set in the `RI` environment variable. ## Where the data comes from ri searches several sources, each of which can be switched off with a flag: 1. **system**: the documentation installed with Ruby itself (`--no-system`). 2. **site**: site-wide documentation (`--no-site`). 3. **home**: your own `~/.rdoc`, where `rdoc --ri` writes (`--no-home`). 4. **gems**: ri data inside each installed gem's documentation directory (`--no-gems`). ## Why ri says "Nothing known about" When no source has an entry, ri prints `Nothing known about <name>`, sometimes with a "Did you mean?" suggestion. The usual causes are: - **The gem was installed without documentation.** `gem install` generates ri data by default, but `-N` / `--no-document` turns that off, and many developers put `gem: --no-document` in `~/.gemrc` to speed installs up. - **The name is wrong for the kind of method.** `ri GeoLookup::Client::geocode` asks for a class method; if `geocode` is an instance method you need `#`. - **The code is your own project**, which no installer ever ran RDoc on. The fixes follow from the cause. `gem rdoc geo_lookup --ri` generates ri data for an installed gem after the fact (`--all` does every gem), and `rdoc --ri lib` builds ri data for your own code into your home directory. ## Example session ```bash $ ri IO.readlines # class and instance method $ ri GeoLookup::Client # Nothing known about GeoLookup::Client $ gem rdoc geo_lookup --ri $ ri GeoLookup::Client#geocode ``` ## Where ri fits today Most developers read documentation in a browser or an editor, so interviews rarely dwell on `ri`. It still earns a place: it works without network access, it shows exactly the version of a gem you have installed rather than whatever a website currently hosts, and its lookup syntax is the same `Class#method` / `Class::method` notation you are expected to use when talking about Ruby APIs.

  • How do you get ri documentation for the gem you are writing yourself?
    Run `rdoc --ri lib` in the project. It writes ri data into the `.rdoc` directory under your home directory, which is one of the sources ri searches by default, so `ri GeoLookup::Client#geocode` then works without installing the gem.
  • What does `ri --no-gems Array` change?
    It stops ri from reading documentation installed with gems, so only Ruby's own system, site and home sources are used. That is useful when a gem reopens a core class and adds methods you do not want mixed into the output.

saying these in an interview costs you the question

  • ri IO.readlines shows only the class method IO::readlines.
  • ri Array::sort is the correct way to look up an instance method.
  • ri downloads documentation from the internet when a gem is missing.
  • gem install never generates ri documentation unless you pass --document.
  • Nothing known about means the gem is not installed at all.