← Back
Editing: RI.md
# `ri`: Ruby Information `ri` (<b>r</b>uby <b>i</b>nformation) 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: - <i>Static mode</i>: 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]. - <i>Interactive mode</i>: 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. | <br> 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. | <br> ### 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. | <br> ### 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. | <br> 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: - [Pager][10]. - [Links in ri Output][11]. ### 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`: ```sh $ 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`: ```sh $ 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: ```sh $ 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: ```sh $ 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. ``` ```sh $ 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): ```sh $ 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): ```sh $ 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): ```sh $ ri ::readlines | grep "= Implementation" === Implementation from CSV === Implementation from IO ``` ```sh $ 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 ``` ```sh $ 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: ```sh $ 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: ```sh $ ri minitest:README | head = minitest/{test,spec,mock,benchmark} home: https://github.com/minitest/minitest bugs: https://github.com/minitest/minitest/issues rdoc: https://docs.seattlerb.org/minitest ``` ## `ri` Lists The list of Ruby pages is available via _name_ `'ruby:'`: ```sh $ 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 ``` ```sh $ 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_'`: ```sh $ ri nokogiri: | head = Pages in gem nokogiri-1.16.2-x86_64-linux README.md lib/nokogiri/css/tokenizer.rex ``` See also: - [Option \\--list][8]: lists classes and modules. - [Option \\--list-doc-dirs][12]: lists `ri` source directories. ## `ri` Information With certain options, an `ri` command may display information other than documents or lists: - [Option \\--help or -h][13]: Shows `ri` help text. - [option \\--version or -v][14]: Shows `ri` version. - [Option \\--dump=FILEPATH][15]: 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_: ```sh $ 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][16]. ## Interactive Mode In general, `ri` responds to a command in interactive mode if the command has no arguments: ```sh $ 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][17]. - Supports tab auto-completion for the name of a class, module, or method; 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][18]. ## 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][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
Save File
Cancel