Skip to content

Latest commit

 

History

History
821 lines (606 loc) · 23.3 KB

RI.md

File metadata and controls

821 lines (606 loc) · 23.3 KB
Raw

#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):

$ 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):

$ 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://docs.ruby-lang.org/en/master/IRB.html] session, you already have immediate access to ri: just type 'help' or '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}[rdoc-ref:RI.md@Static+Mode].

  • 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:

    $ 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}[rdoc-ref:RI.md@Interactive+Mode].

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):

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

  • Interactive mode (already in ri): just type the name; examples (output omitted):

    $ 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 are example names for class and module documents (see {details and examples}[rdoc-ref:RI.md@Class+and+Module+Documents]):

Name Shows
'File' Document for Ruby class File.
'File::Stat' Document for Ruby nested class File::Stat.
'Enumerable' Document for Ruby module Enumerable.
'Arr' Document for Ruby class Array (unique initial characters).
'Nokogiri::HTML4::Document' Document for gem class Nokogiri::HTML4::Document.
'Nokogiri' Document for gem module Nokogiri.

If {option \--all}[rdoc-ref:RI.md@-all-2C+-a] is in effect, documents for the methods in the named class or module are included in the display.

Names for Method Documents

These are example names for method documents (see {details and examples}[rdoc-ref:RI.md@Method+Documents]):

Name Shows
'IO::readlines' Document for Ruby class method IO::readlines.
'IO#readlines' Document for Ruby instance method IO::readlines.
'IO.readlines' Documents for Ruby instance method IO::readlines and class method IO::readlines.
'::readlines' Documents for all class methods ::readlines.
'#readlines' Documents for all instance methods #readlines.
'.readlines', 'readlines' Documents for class methods ::readlines and instance methods #readlines.
'Nokogiri::HTML4::Document::parse' Document for gem class method Nokogiri::HTML4::Document::parse.
'Nokogiri::HTML4::Document#fragment' Document for gem instance method Nokogiri::HTML4::Document#fragment.

Names for Page Documents

These are example names for page documents (see {details and examples}[rdoc-ref:RI.md@Page+Documents]):

Name Shows
'ruby:syntax/assignment.rdoc' Document for Ruby page assignment.
'ruby:syntax/assignment' Same document, if no other syntax/assignment.*.
'ruby:assignment' Same document, if no other /assignment..
'nokogiri:README.md' Document for page README.md.

Names for Lists

These are example names for lists (see {details and examples}[rdoc-ref:RI.md@ri+Lists]):

Name Shows
'ruby:' List of Ruby pages.
'nokogiri:' List of Nokogiri pages.

There are more lists available; see {option \--list}[rdoc-ref:RI.md@-list-2C+-l].

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:

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):

$ 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):

    $ 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):

    $ 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):

    $ 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 Documents

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

See also:

  • {Pager}[rdoc-ref:RI.md@Pager].
  • {Links in ri Output}[rdoc-ref:RI.md@Links+in+ri+Output].

Class and Module Documents

The document for a class or module shows:

  • The class or module name, along with its parent class if any.

  • Where it's defined (Ruby core or gem).

  • When each exists:

    • The names of its included modules.
    • The text of its embedded documentation.
    • Its constants.
    • Its class methods.
    • Its instance methods.

Examples:

  • Ruby class Array:

    $ ri Array | head
= Array < Object

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

(from ruby core)
------------------------------------------------------------------------
An Array is an ordered, integer-indexed collection of objects, called
elements.  Any object may be an Array element.

  • Gem module Nokogiri:

    $ ri Nokogiri | head
= Nokogiri

(from gem nokogiri-1.16.2-x86_64-linux)
------------------------------------------------------------------------

Nokogiri parses and searches XML/HTML very quickly, and also has
correctly implemented CSS3 selector support as well as XPath 1.0
support.

Parsing a document returns either a Nokogiri::XML::Document, or a

The document typically includes certain headings, which may be useful for searching:

$ ri IO | grep "^= "
= IO < Object
= Includes:
= Constants:
= Class methods:
= Instance methods:

Method Documents

The document for a method includes:

  • The source of the method: '(from ruby core)' or '(from gem _gem_)'.
  • The calling sequence(s) for the method.
  • The text of its embedded documentation (if it exists).

Examples:

$ ri IO#read | head
= IO#read

(from ruby core)
------------------------------------------------------------------------
ios.read([length [, outbuf]])    -> string, outbuf, or nil

------------------------------------------------------------------------

Reads length bytes from the I/O stream.
$ ri Nokogiri::parse | head
= Nokogiri::parse

(from gem nokogiri-1.16.2-x86_64-linux)
------------------------------------------------------------------------
  parse(string, url = nil, encoding = nil, options = nil) { |doc| ... }

------------------------------------------------------------------------

Parse an HTML or XML document.  string contains the document.

The output for a name that cites methods includes the document for each found implementation; the number of such implementations depends on the name:

  • Within a class:

    Each of these commands shows documents for methods in Ruby class IO (output omitted):

    $ ri IO::readlines # Class method ::readlines.
$ ri IO#readlines  # Instance method #readlines.
$ ri IO.readlines  # Both of above.

  • In all classes:

    Each of these commands shows documents for methods in all classes (output omitted):

    $ ri ::readlines   # Class method ::readlines.
$ ri \#readlines   # Instance method #readlines.
$ ri .readlines    # Both of above.

    For these all-classes commands, the output is organized into sections, one for each found method (output filtered to show sections):

    $ ri ::readlines | grep "= Implementation"
=== Implementation from CSV
=== Implementation from IO
    $ ri \#readlines | grep "= Implementation"
=== Implementation from ARGF
=== Implementation from CSV
=== Implementation from IO
=== Implementation from Kernel
=== Implementation from Buffering
=== Implementation from Pathname
=== Implementation from StringIO
=== Implementation from GzipReader
    $ ri .readlines | grep "= Implementation"
=== Implementation from ARGF
=== Implementation from CSV
=== Implementation from CSV
=== Implementation from IO
=== Implementation from IO
=== Implementation from Kernel
=== Implementation from Buffering
=== Implementation from Pathname
=== Implementation from StringIO
=== Implementation from GzipReader

Page Documents

The document for a Ruby page is the text from the .rdoc or .md source for that page:

$ ri ruby:dig_methods | head
= Dig Methods

Ruby's dig methods are useful for accessing nested data structures.

Consider this data:
  item = {
    id: "0001",
    type: "donut",
    name: "Cake",
    ppu: 0.55,

The document for a gem page is whatever the gem has generated for the page:

$ ri nokogiri:README | head
<div><img src="https://nokogiri.org/images/nokogiri-serif-black.png" align="right"/></div>= Nokoii
Nokogiri (鋸) makes it easy and painless to work with XML and HTML from
Ruby. It provides a sensible, easy-to-understand API for
{reading}[https://nokogiri.org/tutorials/parsing_an_html_xml_document.ht
ml], writing,
{modifying}[https://nokogiri.org/tutorials/modifying_an_html_xml_documen
t.html], and
{querying}[https://nokogiri.org/tutorials/searching_a_xml_html_document.
html] documents. It is fast and standards-compliant by relying on native
parsers like libxml2, libgumbo, and xerces.

ri Lists

The list of Ruby pages is available via name 'ruby:':

$ ri ruby: | head
= Pages in ruby core

CONTRIBUTING.md
COPYING
COPYING.ja
LEGAL
NEWS-1.8.7
NEWS-1.9.1
NEWS-1.9.2
NEWS-1.9.3
$ ri ruby: | tail
syntax/control_expressions.rdoc
syntax/exceptions.rdoc
syntax/literals.rdoc
syntax/methods.rdoc
syntax/miscellaneous.rdoc
syntax/modules_and_classes.rdoc
syntax/pattern_matching.rdoc
syntax/precedence.rdoc
syntax/refinements.rdoc
win32/README.win32

The list of gem pages is available via name '_gem_name_':

$ ri nokogiri: | head
= Pages in gem nokogiri-1.16.2-x86_64-linux

README.md
lib/nokogiri/css/tokenizer.rex

See also:

  • {Option \--list}[rdoc-ref:RI.md@-list-2C+-l]: lists classes and modules.
  • {Option \--list-doc-dirs}[rdoc-ref:RI.md@-list-doc-dirs]: lists ri source directories.

ri Information

With certain options, an ri command may display information other than documents or lists:

  • {Option \--help or -h}[rdoc-ref:RI.md@-help-2C+-h]: Shows ri help text.
  • {option \--version or -v}[rdoc-ref:RI.md@-version-2C+-v]: Shows ri version.
  • {Option \--dump=FILEPATH}[rdoc-ref:RI.md@-dump-3DFILEPATH]: Shows dump of ri cache file at the given filepath.

Static Mode

In static mode, ri shows a response and exits.

In general, ri responds in static mode if the command gives a name:

$ ri Array | head
= Array < Object

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

(from ruby core)
------------------------------------------------------------------------
An Array is an ordered, integer-indexed collection of objects, called
elements.  Any object may be an Array element.

ri also responds in static mode when certain options are given, even when no name is given; see {ri Information}[rdoc-ref:RI.md@ri+Information].

Interactive Mode

In general, ri responds to a command in interactive mode if the command has no arguments:

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

A command in interactive mode are similar to one in static mode, except that it:

  • Omits command word ri; you just type the name.
  • Omits options; in interactive mode the only options in effect are those taken from environment variable RI. See {Options}[rdoc-ref:RI.md@Options].
  • Supports tab auto-completion for the names of a classes, modules, and methods; when, for example, you type "Arr\t" (here "\t represents the tab character), ri "completes" the text as 'Array '.

See also {ri at the Ready}[rdoc-ref:RI.md@ri+at+the+Ready].

Pager

Because ri output is often large, ri by default pipes it to a pager, which is the program whose name is the first-found among:

  • The value of ENV['RI_PAGER'].
  • The value of ENV['PAGER'].
  • 'pager'.
  • 'less'.
  • 'more'.

If none is found, the output goes directly to $stdout, with no pager.

If you set environment variable RI_PAGER or PAGER, its value should be the name of an executable program that will accept the ri output (such as 'pager', 'less', or 'more').

See also {Output Filters}[rdoc-ref:RI.md@Output+Filters].

\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:

$ 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:

$ 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:

$ 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:

$ 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:

$ 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:

$ 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:

$ 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:

$ 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}[rdoc-ref:RI.md@-doc-dir-3DDIRPATH-2C+-d+DIRPATH].