From: Mauricio Fernandez <mfp@...>
Date: 2006-11-15T21:10:04+09:00
Subject: [ANN] FastRI 0.2.0: full-text searching, smarter search strategies

FastRI is an alternative to the ri command-line tool. It is *much* faster, and
also allows you to offer RI lookup services over DRb. FastRI is smarter than
ri, and can find classes anywhere in the hierarchy without specifying the
"full path". FastRI can perform full-text searching. Its RubyGems support is
better than ri's, and it knows which gem a method/class definition came from.

Getting it
==========
Additional information, tarballs... at 
  http://eigenclass.org/hiki.rb?fastri

FastRI can be installed with RubyGems:
  gem install fastri
(if you get an old version/a 404 error, please allow some time after the
release until the package propagates to the RubyForge mirrors). Please read
below for an important note regarding the RubyGems packages.

Changes since version 0.1.1 (2006-11-10)
========================================
Features
--------
* fri can do full-text search (-S, --full-text); try  fri -S byte order
* fri can now determine where a method actually came from for core classes
  e.g.  fri File.inject   -> docs for Enumerable#inject
* you can specify which ports the DRb services must bind to:
    fastri-server -s 192.168.1.2:54321
    fri -s 192.168.1.2:12345
* new search methods: "anywhere" (a) and "anywhere, case-indep." (A)

Acknowledgements 
================
Tomasz Wegrzanowski
* contributed the code that allows fri to find a method in the ancestors
  for core classes

Usage
=====
There are two parts to FastRI:
* 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.

Examples
========
 $ fastri-server      (creates the index on the first run, blocks)

Later, (times measured with a cold cache):
 $ time ruby bin/fri -f plain Array#fetch
 ------------------------------------------------------------ Array#fetch
      array.fetch(index)                    -> obj
 [...]
 real    0m0.287s  (real    0m0.127s with a hot cache)
 user    0m0.048s
 sys     0m0.008s

Compare to:
 $ time ri -T -f plain Array#fetch
 ------------------------------------------------------------ Array#fetch
 [...]
 real    0m10.136s (real    ~ 1.5s with a hot cache)
 user    0m1.140s
 sys     0m0.464s

This illustrates FastRI's ability to locate classes deep in the class
hierarchy:

 $ fri Base
 ------------------------------------------------------ Multiple choices:

      ActionMailer::Base, ActionView::Base, ActionWebService::API::Base, 
      ActionWebService::Base, ActionWebService::Client::Base, 
      ActiveRecord::Base, MapReduce::ActiveRecord::Base, 
      RSS::Maker::Base, Scruffy::Components::Base, 
      Scruffy::Formatters::Base, Scruffy::Layers::Base, 
      Scruffy::Renderers::Base, Scruffy::Themes::Base

 $ fri Themes::Base
 ------------------------------------------- Class: Scruffy::Themes::Base
      Scruffy::Themes::Base
      Author: Brasten Sager

      Date:   August 14th, 2006

Compare to 
 $ ri Themes::Base      .... several seconds later ...
 Nothing known about Themes::Base

A small note about RubyGems + FastRI. 
=====================================
RubyGems adds a noticeable overhead to fri, making it run slower than if you
installed it directly from the tarball with setup.rb.

Compare the execution time when installed with RubyGems:
  $ time fri -f plain String > /dev/null

  real	0m0.385s
  user	0m0.244s
  sys	0m0.036s

to the time fri actually takes to run, without the overhead introduced by 
RubyGems:
  $ time ruby bin/fri -f plain String > /dev/null

  real	0m0.088s
  user	0m0.040s
  sys	0m0.008s

If you care about those extra 300ms (and there are situations where they will
matter, e.g. when using fri for method completion), get FastRI from the
tarballs.

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

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.

-- 
Mauricio Fernandez  -   http://eigenclass.org   -  singular Ruby