FastRI: faster, smarter RI docs for Ruby, DRb-enabled

Overview

FastRI is an alternative to the "ri" documentation browser for Ruby. FastRI can operate in standalone mode (without using a DRb server, see below), so it can now fully replace ri for most intents and purposes.

Why prefer it over ri? FastRI

• actually works
• is *much* faster than ri
• can perform fast full-text searching over all your rdoc documentation
• is smarter than ri, and can find classes anywhere in the hierarchy without specifying the "full path"
• can be told to use different search strategies (completion, nested namespaces, etc.)
• supports RubyGems much better than ri, and knows which gem a method/class came from
• can serve RI documentation over DRb

You can find more information about what makes FastRI faster than ri here, and about its 200 LoC full-text search engine here.

Getting it

FastRI can be installed with RubyGems:

 gem install fastri

If you try this shortly after a release and you get an old version/a 404 error, please allow some time until the packages propagate to RubyForge's mirrors.

FastRI is available in tarball format. The fri executable will run much faster if you install FastRI from a tarball, since RubyGems introduces a noticeable overhead.

The latest tarball is fastri-0.3.1.tar.gz

You can also get it from http://eigenclass.org/static/fastri if RubyForge happens to be down.

Just run

 setup.rb

to install.

Usage

Starting from 0.3.0, fri can be used in either local mode (--local, -L) or remote mode (using a fastri-server, -R, --remote). By default, fri will run in remote mode. There's a new executable named qri that defaults to local mode (it behaves otherwise identically to fri).

Remote mode is slightly faster (typically about 150ms) , since the documentation index is kept in memory and needs not be read from disk.

Local mode

$ qri Array
 ----------------------------------------------------------- Class: Array
      Arrays are ordered, integer-indexed collections of any object.
      Array indexing starts at 0, as in C or Java. A negative index is
...

$ qri compact
 ---------------------------------------------------------- Array#compact
      array.compact     ->  an_array
 ------------------------------------------------------------------------
      Returns a copy of self with all nil elements removed.

Remote mode

There are two parts to using FastRI in remote mode:

• the server: fastri-server
• the client: fri

FastRI uses a Rinda Ring to allow servers to be discovered automatically without needing to indicate the DRb URIs manually. It can work across machines if you make sure the ring server is bound to the correct interface, and the ACL permissions are correct.

Quickstart

First of all, the DRb server must be launched with

$ fastri-server             (blocks)

Later,

$ fri String
---------------------------------------------------------- Class: String
     A String object holds and manipulates an arbitrary sequence of
     bytes, typically representing characters. String objects may be
     created using String::new or as literals.
...

Read on for more information, including how to make FastRI work across machines.

More about fastri-server

For local usage, just

 $ fastri-server

will do. The DRb service will bind to 127.0.0.1, and only connections from 127.0.0.1 will be allowed. If you want to allow fri to be used from other machines, you have to specify which interface to bind to, and allow incoming connections from the desired hosts. For example, if your network is 192.168.1.0, and your IP is 192.168.1.2, you can do

 $ fastri-server -a 192.168.1.0/24 -s 192.168.1.2
 FastRI 0.0.1 listening on druby://192.168.1.2:41217
 ACL:
 deny  all
 allow localhost
 allow 192.168.1.0/24

Further options are documented in

 $ fastri-server -h

More about fri

Running fri with no options (or -h/--help) will explain the command-line options. If you are using fri locally (i.e. on the same server as fastri-server), just use it as follows:

 $ fri Array
 ------------------------------------------------------- Class: Array
 Arrays are ordered, integer-indexed collections of any object.
 ...

If you're on a different machine, you'll probably have to specify which address the DRb service should be attached to. You can either specify it with -s ADDRESS (or --bind ADDRESS), or set the FASTRI_ADDR environment variable. For example, if you're on 192.168.1.101, both

 export FASTRI_ADDR="192.168.1.101"
 fri Array

and

 fri -s 192.168.1.101 Array

will work. Note that FASTRI_ADDR is the *local* address: the server will be discovered automatically. (The reason why the local address must be specified is that it will be given to the ring server, which must be able to establish a reverse connection through the local DRb service.)

Feedback

Bug reports, patches, comments... are appreciated. You can contact the author via <mfp@acm.org>. Please add "fastri" to the subject in order to bypass the spam filters.

License

FastRI is licensed under the same terms as Ruby. See LICENSE.