rdoc 2.4.3 → 2.5

data/lib/rdoc/ri.rb

@@ -1,8 +1,18 @@
 require 'rdoc'
 
+##
+# Namespace for the ri command line tool's implementation.
+#
+# See <tt>ri --help</tt> for details.
+
 module RDoc::RI
 
+  ##
+  # Base RI error class
+
   class Error < RDoc::Error; end
 
 end
 
+require 'rdoc/ri/store'
+

data/lib/rdoc/ri/driver.rb

@@ -1,6 +1,5 @@
 require 'abbrev'
 require 'optparse'
-require 'yaml'
 
 begin
   require 'readline'
@@ -9,79 +8,59 @@ end
 
 require 'rdoc/ri'
 require 'rdoc/ri/paths'
-require 'rdoc/ri/formatter'
-require 'rdoc/ri/display'
-require 'fileutils'
 require 'rdoc/markup'
-require 'rdoc/markup/to_flow'
+require 'rdoc/markup/formatter'
+require 'rdoc/text'
+
+##
+# For RubyGems backwards compatibility
+
+require 'rdoc/ri/formatter'
+
+##
+# The RI driver implements the command-line ri tool.
+#
+# The driver supports:
+# * loading RI data from:
+#   * Ruby's standard library
+#   * RubyGems
+#   * ~/.rdoc
+#   * A user-supplied directory
+# * Paging output (uses RI_PAGER environment variable, PAGER environment
+#   variable or the less, more and pager programs)
+# * Interactive mode with tab-completion
+# * Abbreviated names (ri Zl shows Zlib documentation)
+# * Colorized output
+# * Merging output from multiple RI data sources
 
 class RDoc::RI::Driver
 
   ##
-  # This class offers both Hash and OpenStruct functionality.  We convert from
-  # the Core Hash to this before calling any of the display methods, in order
-  # to give the display methods a cleaner API for accessing the data.
+  # Base Driver error class
 
-  class OpenStructHash < Hash
+  class Error < RDoc::RI::Error; end
 
-    ##
-    # This method converts from a Hash to an OpenStructHash.
+  ##
+  # Raised when a name isn't found in the ri data stores
 
-    def self.convert(object)
-      case object
-      when Hash then
-        new_hash = new # Convert Hash -> OpenStructHash
+  class NotFoundError < Error
 
-        object.each do |key, value|
-          new_hash[key] = convert value
-        end
+    ##
+    # Name that wasn't found
 
-        new_hash
-      when Array then
-        object.map do |element|
-          convert element
-        end
-      else
-        object
-      end
-    end
-
-    def merge_enums(other)
-      other.each do |k, v|
-        if self[k] then
-          case v
-          when Array then
-            # HACK dunno
-            if String === self[k] and self[k].empty? then
-              self[k] = v
-            else
-              self[k] += v
-            end
-          when Hash then
-            self[k].update v
-          else
-            # do nothing
-          end
-        else
-          self[k] = v
-        end
-      end
-    end
+    alias name message
 
-    def method_missing method, *args
-      self[method.to_s]
+    def message # :nodoc:
+      "Nothing known about #{super}"
     end
   end
 
-  class Error < RDoc::RI::Error; end
+  attr_accessor :stores
 
-  class NotFoundError < Error
-    def message
-      "Nothing known about #{super}"
-    end
-  end
+  ##
+  # Controls the user of the pager vs $stdout
 
-  attr_accessor :homepath # :nodoc:
+  attr_accessor :use_stdout
 
   ##
   # Default options for ri
@@ -90,9 +69,9 @@ class RDoc::RI::Driver
     options = {}
     options[:use_stdout] = !$stdout.tty?
     options[:width] = 72
-    options[:formatter] = RDoc::RI::Formatter.for 'plain'
     options[:interactive] = false
     options[:use_cache] = true
+    options[:profile] = false
 
     # By default all standard paths are used.
     options[:use_system] = true
@@ -104,30 +83,33 @@ class RDoc::RI::Driver
     return options
   end
 
+  ##
+  # Dump +data_path+ using pp
+
+  def self.dump data_path
+    require 'pp'
+
+    open data_path, 'rb' do |io|
+      pp Marshal.load(io.read)
+    end
+  end
+
   ##
   # Parses +argv+ and returns a Hash of options
 
-  def self.process_args(argv)
+  def self.process_args argv
     options = default_options
 
     opts = OptionParser.new do |opt|
+      opt.accept File do |file,|
+        File.readable?(file) and not File.directory?(file) and file
+      end
+
       opt.program_name = File.basename $0
       opt.version = RDoc::VERSION
       opt.release = nil
       opt.summary_indent = ' ' * 4
 
-      directories = [
-        RDoc::RI::Paths::SYSDIR,
-        RDoc::RI::Paths::SITEDIR,
-        RDoc::RI::Paths::HOMEDIR
-      ]
-
-      if RDoc::RI::Paths::GEMDIRS then
-        Gem.path.each do |dir|
-          directories << "#{dir}/doc/*/ri"
-        end
-      end
-
       opt.banner = <<-EOT
 Usage: #{opt.program_name} [options] [names...]
 
@@ -154,9 +136,9 @@ punctuation:
     #{opt.program_name} 'Array.[]'
     #{opt.program_name} compact\\!
 
-By default ri searches for documentation in the following directories:
+To see the default directories ri will search, run:
 
-    #{directories.join "\n    "}
+    #{opt.program_name} --list-doc-dirs
 
 Specifying the --system, --site, --home, --gems or --doc-dir options will
 limit ri to searching only the specified directories.
@@ -166,17 +148,60 @@ Options may also be set in the 'RI' environment variable.
 
       opt.separator nil
       opt.separator "Options:"
+
+      opt.separator nil
+
+      formatters = RDoc::Markup.constants.grep(/^To[A-Z][a-z]+$/).sort
+      formatters = formatters.sort.map do |formatter|
+        formatter.to_s.sub('To', '').downcase
+      end
+
+      opt.on("--format=NAME", "-f",
+             "Uses the selected formatter. The default",
+             "formatter is bs for paged output and ansi",
+             "otherwise. Valid formatters are:",
+             formatters.join(' '), formatters) do |value|
+        options[:formatter] = RDoc::Markup.const_get "To#{value.capitalize}"
+      end
+
+      opt.separator nil
+
+      opt.on("--no-pager", "-T",
+             "Send output directly to stdout,",
+             "rather than to a pager.") do
+        options[:use_stdout] = true
+      end
+
+      opt.separator nil
+
+      opt.on("--width=WIDTH", "-w", OptionParser::DecimalInteger,
+             "Set the width of the output.") do |value|
+        options[:width] = value
+      end
+
+      opt.separator nil
+
+      opt.on("--interactive", "-i",
+             "In interactive mode you can repeatedly",
+             "look up methods with autocomplete.") do
+        options[:interactive] = true
+      end
+
+      opt.separator nil
+
+      opt.on("--[no-]profile",
+             "Run with the ruby profiler") do |value|
+        options[:profile] = value
+      end
+
+      opt.separator nil
+      opt.separator "Data source options:"
       opt.separator nil
 
-      opt.on("--fmt=FORMAT", "--format=FORMAT", "-f",
-             RDoc::RI::Formatter::FORMATTERS.keys,
-             "Format to use when displaying output:",
-             "   #{RDoc::RI::Formatter.list}",
-             "Use 'bs' (backspace) with most pager",
-             "programs. To use ANSI, either disable the",
-             "pager or tell the pager to allow control",
-             "characters.") do |value|
-        options[:formatter] = RDoc::RI::Formatter.for value
+      opt.on("--list-doc-dirs",
+             "List the directories from which ri will",
+             "source documentation on stdout and exit.") do
+        options[:list_doc_dirs] = true
       end
 
       opt.separator nil
@@ -196,21 +221,11 @@ Options may also be set in the 'RI' environment variable.
 
       opt.separator nil
 
-      opt.on("--[no-]use-cache",
-             "Whether or not to use ri's cache.",
-             "True by default.") do |value|
-        options[:use_cache] = value
-      end
-
-      opt.separator nil
-
       opt.on("--no-standard-docs",
              "Do not include documentation from",
              "the Ruby standard library, site_lib,",
              "installed gems, or ~/.rdoc.",
-             "Equivalent to specifying",
-             "the options --no-system, --no-site, --no-gems,",
-             "and --no-home") do
+             "Use with --doc-dir") do
         options[:use_system] = false
         options[:use_site] = false
         options[:use_gems] = false
@@ -251,38 +266,12 @@ Options may also be set in the 'RI' environment variable.
       end
 
       opt.separator nil
-
-      opt.on("--list-doc-dirs",
-             "List the directories from which ri will",
-             "source documentation on stdout and exit.") do
-        options[:list_doc_dirs] = true
-      end
-
-      opt.separator nil
-
-      opt.on("--no-pager", "-T",
-             "Send output directly to stdout,",
-             "rather than to a pager.") do
-        options[:use_stdout] = true
-      end
-
-      opt.on("--interactive", "-i",
-             "This makes ri go into interactive mode.",
-             "When ri is in interactive mode it will",
-             "allow the user to disambiguate lists of",
-             "methods in case multiple methods match",
-             "against a method search string.  It also",
-             "will allow the user to enter in a method",
-             "name (with auto-completion, if readline",
-             "is supported) when viewing a class.") do
-        options[:interactive] = true
-      end
-
+      opt.separator "Debug options:"
       opt.separator nil
 
-      opt.on("--width=WIDTH", "-w", OptionParser::DecimalInteger,
-             "Set the width of the output.") do |value|
-        options[:width] = value
+      opt.on("--dump=CACHE", File,
+             "Dumps data from an ri cache or data file") do |value|
+        options[:dump_path] = value
       end
     end
 
@@ -292,7 +281,6 @@ Options may also be set in the 'RI' environment variable.
 
     options[:names] = argv
 
-    options[:formatter] ||= RDoc::RI::Formatter.for('plain')
     options[:use_stdout] ||= !$stdout.tty?
     options[:use_stdout] ||= options[:interactive]
     options[:width] ||= 72
@@ -309,308 +297,438 @@ Options may also be set in the 'RI' environment variable.
   ##
   # Runs the ri command line executable using +argv+
 
-  def self.run(argv = ARGV)
+  def self.run argv = ARGV
     options = process_args argv
+
+    if options[:dump_path] then
+      dump options[:dump_path]
+      return
+    end
+
     ri = new options
     ri.run
   end
 
-  def initialize(initial_options={})
+  ##
+  # Creates a new driver using +initial_options+ from ::process_args
+
+  def initialize initial_options = {}
+    @paging = false
+    @classes = nil
+
     options = self.class.default_options.update(initial_options)
 
+    @formatter_klass = options[:formatter]
+
+    require 'profile' if options[:profile]
+
     @names = options[:names]
-    @class_cache_name = 'classes'
 
-    @doc_dirs = RDoc::RI::Paths.path(options[:use_system],
-                                     options[:use_site],
-                                     options[:use_home],
-                                     options[:use_gems],
-                                     options[:extra_doc_dirs])
+    @doc_dirs = []
+    @stores   = []
 
-    @homepath = RDoc::RI::Paths.raw_path(false, false, true, false).first
-    @homepath = @homepath.sub(/\.rdoc/, '.ri')
-    @sys_dir = RDoc::RI::Paths.raw_path(true, false, false, false).first
-    @list_doc_dirs = options[:list_doc_dirs]
+    RDoc::RI::Paths.each(options[:use_system], options[:use_site],
+                                   options[:use_home], options[:use_gems],
+                                   *options[:extra_doc_dirs]) do |path, type|
+      @doc_dirs << path
 
-    FileUtils.mkdir_p cache_file_path unless File.directory? cache_file_path
-    @cache_doc_dirs_path = File.join cache_file_path, ".doc_dirs"
+      store = RDoc::RI::Store.new path, type
+      store.load_cache
+      @stores << store
+    end
 
-    @use_cache = options[:use_cache]
-    @class_cache = nil
+    @list_doc_dirs = options[:list_doc_dirs]
 
     @interactive = options[:interactive]
-    @display = RDoc::RI::DefaultDisplay.new(options[:formatter],
-                                            options[:width],
-                                            options[:use_stdout])
+    @use_stdout  = options[:use_stdout]
   end
 
   ##
-  # Cache of classes ri knows about
+  # Adds paths for undocumented classes +also_in+ to +out+
 
-  def class_cache
-    return @class_cache if @class_cache
+  def add_also_in out, also_in
+    return if also_in.empty?
 
-    # Get the documentation directories used to make the cache in order to see
-    # whether the cache is valid for the current ri instantiation.
-    if(File.readable?(@cache_doc_dirs_path))
-      cache_doc_dirs = IO.read(@cache_doc_dirs_path).split("\n")
-    else
-      cache_doc_dirs = []
-    end
-
-    newest = map_dirs('created.rid') do |f|
-      File.mtime f if test ?f, f
-    end.max
-
-    # An up to date cache file must have been created more recently than
-    # the last modification of any of the documentation directories.  It also
-    # must have been created with the same documentation directories
-    # as those from which ri currently is sourcing documentation.
-    up_to_date = (File.exist?(class_cache_file_path) and
-                  newest and newest < File.mtime(class_cache_file_path) and
-                  (cache_doc_dirs == @doc_dirs))
-
-    if up_to_date and @use_cache then
-      open class_cache_file_path, 'rb' do |fp|
-        begin
-          @class_cache = Marshal.load fp.read
-        rescue
-          #
-          # This shouldn't be necessary, since the up_to_date logic above
-          # should force the cache to be recreated when a new version of
-          # rdoc is installed.  This seems like a worthwhile enhancement
-          # to ri's robustness, however.
-          #
-          $stderr.puts "Error reading the class cache; recreating the class cache!"
-          @class_cache = create_class_cache
-        end
-      end
-    else
-      @class_cache = create_class_cache
+    out << RDoc::Markup::Rule.new(1)
+    out << RDoc::Markup::Paragraph.new("Also found in:")
+
+    paths = RDoc::Markup::Verbatim.new
+    also_in.each do |store|
+      paths.parts.push '  ', store.friendly_path, "\n"
     end
+    out << paths
+  end
 
-    @class_cache
+  ##
+  # Adds a class header to +out+ for class +name+ which is described in
+  # +classes+.
+
+  def add_class out, name, classes
+    heading = if classes.all? { |klass| klass.module? } then
+                name
+              else
+                superclass = classes.map do |klass|
+                  klass.superclass unless klass.module?
+                end.compact.shift || 'Object'
+
+                "#{name} < #{superclass}"
+              end
+
+    out << RDoc::Markup::Heading.new(1, heading)
+    out << RDoc::Markup::BlankLine.new
   end
 
   ##
-  # Creates the class cache if it is empty
+  # Adds "(from ...)" to +out+ for +store+
 
-  def create_class_cache
-    class_cache = OpenStructHash.new
+  def add_from out, store
+    out << RDoc::Markup::Paragraph.new("(from #{store.friendly_path})")
+  end
 
-    if(@use_cache)
-      # Dump the documentation directories to a file in the cache, so that
-      # we only will use the cache for future instantiations with identical
-      # documentation directories.
-      File.open @cache_doc_dirs_path, "wb" do |fp|
-        fp << @doc_dirs.join("\n")
-      end
-    end
+  ##
+  # Adds +includes+ to +out+
 
-    classes = map_dirs('**/cdesc*.yaml') { |f| Dir[f] }
-    warn "Updating ri class cache with #{classes.size} classes..."
-    populate_class_cache class_cache, classes
+  def add_includes out, includes
+    return if includes.empty?
 
-    write_cache class_cache, class_cache_file_path
+    out << RDoc::Markup::Rule.new(1)
+    out << RDoc::Markup::Heading.new(1, "Includes:")
 
-    class_cache
-  end
+    includes.each do |modules, store|
+      if modules.length == 1 then
+        include = modules.first
+        name = include.name
+        path = store.friendly_path
+        out << RDoc::Markup::Paragraph.new("#{name} (from #{path})")
 
-  ##
-  # Populates +class_cache+ with +classes+, adding +extension+ data for found
-  # methods when asked
+        if include.comment then
+          out << RDoc::Markup::BlankLine.new
+          out << include.comment
+        end
+      else
+        out << RDoc::Markup::Paragraph.new("(from #{store.friendly_path})")
 
-  def populate_class_cache(class_cache, classes, extension = false)
-    classes.each do |cdesc|
-      desc = read_yaml cdesc
-      klassname = desc["full_name"]
+        wout, with = modules.partition { |incl| incl.comment.empty? }
 
-      unless class_cache.has_key? klassname then
-        desc["display_name"] = "Class"
-        desc["sources"] = [cdesc]
-        desc["instance_method_extensions"] = []
-        desc["class_method_extensions"] = []
-        class_cache[klassname] = desc
-      else
-        klass = class_cache[klassname]
+        out << RDoc::Markup::BlankLine.new unless with.empty?
 
-        if extension then
-          desc["instance_method_extensions"] = desc.delete "instance_methods"
-          desc["class_method_extensions"] = desc.delete "class_methods"
+        with.each do |incl|
+          out << RDoc::Markup::Paragraph.new(incl.name)
+          out << RDoc::Markup::BlankLine.new
+          out << incl.comment
         end
 
-        klass.merge_enums desc
-        klass["sources"] << cdesc
+        unless wout.empty? then
+          verb = RDoc::Markup::Verbatim.new
+
+          wout.each do |incl|
+            verb.push '  ', incl.name, "\n"
+          end
+
+          out << verb
+        end
       end
     end
   end
 
   ##
-  # Path to the class_cache
+  # Adds a list of +methods+ to +out+ with a heading of +name+
 
-  def class_cache_file_path
-    File.join cache_file_path, @class_cache_name
+  def add_method_list out, methods, name
+    return unless methods
+
+    out << RDoc::Markup::Heading.new(1, "#{name}:")
+    out << RDoc::Markup::BlankLine.new
+
+    out.push(*methods.map do |method|
+      RDoc::Markup::Verbatim.new '  ', method
+    end)
+
+    out << RDoc::Markup::BlankLine.new
   end
 
   ##
-  # Path to the cache file for +klassname+
+  # Returns ancestor classes of +klass+
+
+  def ancestors_of klass
+    ancestors = []
+
+    unexamined = [klass]
+    seen = []
+
+    loop do
+      break if unexamined.empty?
+      current = unexamined.shift
+      seen << current
+
+      stores = classes[current]
+
+      break unless stores and not stores.empty?
+
+      klasses = stores.map do |store|
+        store.ancestors[current]
+      end.flatten.uniq
 
-  def cache_file_for(klassname)
-    File.join cache_file_path, klassname.gsub(/:+/, "-")
+      klasses = klasses - seen
+
+      ancestors.push(*klasses)
+      unexamined.push(*klasses)
+    end
+
+    ancestors.reverse
   end
 
   ##
-  # Directory where cache files live
+  # For RubyGems backwards compatibility
 
-  def cache_file_path
-    File.join @homepath, 'cache'
+  def class_cache # :nodoc:
   end
 
   ##
-  # Displays the module, class or method +name+.  For methods, locates the
-  # method in the ancestors list if it isn't in the named module.
+  # Hash mapping a known class or module to the stores it can be loaded from
 
-  def display_name(name)
-    if class_cache.key? name then
-      method_map = display_class name
-    elsif name =~ /::|\#|\./ then
-      method = nil
-      klass, = parse_name name
+  def classes
+    return @classes if @classes
 
-      klass = expand_klass klass unless class_cache.key? klass
+    @classes = {}
 
-      orig_klass = klass
-      orig_name = name
+    @stores.each do |store|
+      store.cache[:modules].each do |mod|
+        # using default block causes searched-for modules to be added
+        @classes[mod] ||= []
+        @classes[mod] << store
+      end
+    end
 
-      loop do
-        method = lookup_method name, klass
+    @classes
+  end
 
-        break if method
+  ##
+  # Completes +name+ based on the caches.  For Readline
 
-        ancestor = lookup_ancestor klass, orig_klass
+  def complete name
+    klasses = classes.keys
+    completions = []
 
-        break unless ancestor
+    klass, selector, method = parse_name name
 
-        name = name.sub klass, ancestor
-        klass = ancestor
-      end
+    # may need to include Foo when given Foo::
+    klass_name = method ? name : klass
 
-      raise NotFoundError, orig_name unless method
+    if name !~ /#|\./ then
+      completions.push(*klasses.grep(/^#{klass_name}/))
+    elsif selector then
+      completions << klass if classes.key? klass
+    elsif classes.key? klass_name then
+      completions << klass_name
+    end
 
-      display_method method
-    else
-      methods = select_methods(/#{name}/)
+    if completions.include? klass and name =~ /#|\.|::/ then
+      methods = list_methods_matching name
 
-      if methods.size == 0
-        raise NotFoundError, name
-      elsif methods.size == 1
-        display_method methods[0]
-      else
-        @display.display_method_list methods
+      if not methods.empty? then
+        # remove Foo if given Foo:: and a method was found
+        completions.delete klass
+      elsif selector then
+        # replace Foo with Foo:: as given
+        completions.delete klass
+        completions << "#{klass}#{selector}" 
       end
+
+      completions.push(*methods)
     end
+
+    completions.sort
   end
 
   ##
-  # Displays info for class or module +name+
+  # Converts +document+ to text and writes it to the pager
 
-  def display_class(name)
-    klass = class_cache[name]
-    @display.display_class_info klass
+  def display document
+    page do |io|
+      text = document.accept formatter
+
+      io.write text
+    end
   end
 
   ##
-  # Displays info for method +method+
+  # Outputs formatted RI data for class +name+.  Groups undocumented classes
+
+  def display_class name
+    return if name =~ /#|\./
+
+    klasses = []
+    includes = []
+
+    found = @stores.map do |store|
+      begin
+        klass = store.load_class name
+        klasses  << klass
+        includes << [klass.includes, store] if klass.includes
+        [store, klass]
+      rescue Errno::ENOENT
+      end
+    end.compact
 
-  def display_method(method)
-    @display.display_method_info method
+    return if found.empty?
+
+    also_in = []
+
+    includes.reject! do |modules,| modules.empty? end
+
+    out = RDoc::Markup::Document.new
+
+    add_class out, name, klasses
+
+    add_includes out, includes
+
+    found.each do |store, klass|
+      comment = klass.comment
+      class_methods    = store.class_methods[klass.full_name]
+      instance_methods = store.instance_methods[klass.full_name]
+      attributes       = store.attributes[klass.full_name]
+
+      if comment.empty? and !(instance_methods or class_methods) then
+        also_in << store
+        next
+      end
+
+      add_from out, store
+
+      unless comment.empty? then
+        out << RDoc::Markup::Rule.new(1)
+        out << comment
+      end
+
+      if class_methods or instance_methods or not klass.constants.empty? then
+        out << RDoc::Markup::Rule.new
+      end
+
+      unless klass.constants.empty? then
+        out << RDoc::Markup::Heading.new(1, "Constants:")
+        out << RDoc::Markup::BlankLine.new
+        list = RDoc::Markup::List.new :NOTE
+
+        constants = klass.constants.sort_by { |constant| constant.name }
+
+        list.push(*constants.map do |constant|
+          parts = constant.comment.parts if constant.comment
+          parts << RDoc::Markup::Paragraph.new('[not documented]') if
+            parts.empty?
+
+          RDoc::Markup::ListItem.new(constant.name, *parts)
+        end)
+
+        out << list
+      end
+
+      add_method_list out, class_methods,    'Class methods'
+      add_method_list out, instance_methods, 'Instance methods'
+      add_method_list out, attributes,       'Attributes'
+
+      out << RDoc::Markup::BlankLine.new
+    end
+
+    add_also_in out, also_in
+
+    display out
   end
 
   ##
-  # Runs ri interactively using Readline if it is available.
+  # Outputs formatted RI data for method +name+
 
-  def interactive
-    formatter = @display.formatter
+  def display_method name
+    found = load_methods_matching name
 
-    if defined? Readline then
-      # prepare abbreviations for tab completion
-      klasses = class_cache.keys
+    raise NotFoundError, name if found.empty?
 
-      Readline.completion_proc = proc do |name|
-        case name
-        when /(#|\.|::)([^A-Z]|$)/ then
-          methods = []
-          method_type = $1 == '.' ? '#|::' : $1
+    out = RDoc::Markup::Document.new
 
-          klass, method = if $2.empty? then
-                            [$`, '']
-                          else
-                            parse_name name
-                          end
+    out << RDoc::Markup::Heading.new(1, name)
+    out << RDoc::Markup::BlankLine.new
 
-          cache = load_cache_for klass
+    found.each do |store, methods|
+      methods.each do |method|
+        out << RDoc::Markup::Paragraph.new("(from #{store.friendly_path})")
 
-          methods += cache.keys.select do |method_name|
-            method_name =~ /^#{klass}#{method_type}#{method}/
-          end
-
-          # TODO ancestor lookup
+        unless name =~ /^#{Regexp.escape method.parent_name}/ then
+          out << RDoc::Markup::Heading.new(3, "Implementation from #{method.parent_name}")
+        end
+        out << RDoc::Markup::Rule.new(1)
 
-          if method_type == '::' and method.empty? then
-            methods += klasses.grep(/^#{klass}::/)
-          end
+        if method.call_seq then
+          call_seq = method.call_seq.chomp.split "\n"
+          call_seq = call_seq.map { |line| ['  ', line, "\n"] }
+          out << RDoc::Markup::Verbatim.new(*call_seq.flatten)
+        end
 
-          methods
-        when /^[A-Z]\w*/ then
-          klasses.grep(/^#{name}/)
-        else
-          []
+        if method.block_params then
+          out << RDoc::Markup::BlankLine.new if method.call_seq
+          params = "yields: #{method.block_params}"
+          out << RDoc::Markup::Verbatim.new('  ', params, "\n")
         end
+
+        out << RDoc::Markup::Rule.new(1) if
+          method.call_seq or method.block_params
+
+        out << RDoc::Markup::BlankLine.new
+        out << method.comment
+        out << RDoc::Markup::BlankLine.new
       end
     end
 
-    formatter.raw_print_line "\nEnter the method name you want to look up.\n"
+    display out
+  end
 
-    if defined? Readline then
-      formatter.raw_print_line "You can use tab to autocomplete.\n"
-    end
+  ##
+  # Outputs formatted RI data for the class or method +name+.
+  #
+  # Returns true if +name+ was found, false if it was not an alternative could
+  # be guessed, raises an error if +name+ couldn't be guessed.
 
-    formatter.raw_print_line "Enter a blank line to exit.\n\n"
+  def display_name name
+    return true if display_class name
 
-    loop do
-      name = if defined? Readline then
-               Readline.readline ">> "
-             else
-               formatter.raw_print_line ">> "
-               $stdin.gets
-             end
+    display_method name if name =~ /::|#|\./
 
-      return if name.nil? or name.empty?
+    true
+  rescue NotFoundError
+    matches = list_methods_matching name if name =~ /::|#|\./
+    matches = classes.keys.grep(/^#{name}/) if matches.empty?
 
-      name = name.strip
+    raise if matches.empty?
 
-      begin
-        display_name name
-      rescue NotFoundError => e
-        formatter.raw_print_line "#{e.message}\n"
-      end
+    page do |io|
+      io.puts "#{name} not found, maybe you meant:"
+      io.puts
+      io.puts matches.join("\n")
     end
 
-  rescue Interrupt
-    exit
+    false
   end
 
   ##
-  # Expands abbreviated klass +klass+ into a fully-qualified klass.  "Zl::Da"
+  # Displays each name in +name+
+
+  def display_names names
+    names.each do |name|
+      name = expand_name name
+
+      display_name name
+    end
+  end
+  ##
+  # Expands abbreviated klass +klass+ into a fully-qualified class.  "Zl::Da"
   # will be expanded to Zlib::DataError.
 
-  def expand_klass(klass)
+  def expand_class klass
     klass.split('::').inject '' do |expanded, klass_part|
       expanded << '::' unless expanded.empty?
       short = expanded << klass_part
 
-      subset = class_cache.keys.select do |klass_name|
-        klass =~ /^#{expanded}[^:]*$/
+      subset = classes.keys.select do |klass_name|
+        klass_name =~ /^#{expanded}[^:]*$/
       end
 
       abbrevs = Abbrev.abbrev subset
@@ -624,152 +742,277 @@ Options may also be set in the 'RI' environment variable.
   end
 
   ##
-  # Loads the cache for +klassname+
+  # Expands the class portion of +name+ into a fully-qualified class.  See
+  # #expand_class.
 
-  def load_cache_for(klassname)
-    path = cache_file_for klassname
+  def expand_name name
+    klass, selector, method = parse_name name
 
-    cache = nil
+    return [selector, method].join if klass.empty?
 
-    if File.exist? path and
-       File.mtime(path) >= File.mtime(class_cache_file_path) and
-       @use_cache then
-      open path, 'rb' do |fp|
-        begin
-          cache = Marshal.load fp.read
-        rescue
-          #
-          # The cache somehow is bad.  Recreate the cache.
-          #
-          $stderr.puts "Error reading the cache for #{klassname}; recreating the cache!"
-          cache = create_cache_for klassname, path
-        end
-      end
+    "#{expand_class klass}#{selector}#{method}"
+  end
+
+  ##
+  # Yields items matching +name+ including the store they were found in, the
+  # class being searched for, the class they were found in (an ancestor) the
+  # types of methods to look up (from #method_type), and the method name being
+  # searched for
+
+  def find_methods name
+    klass, selector, method = parse_name name
+
+    types = method_type selector
+
+    klasses = nil
+    ambiguous = klass.empty?
+
+    if ambiguous then
+      klasses = classes.keys
     else
-      cache = create_cache_for klassname, path
+      klasses = ancestors_of klass
+      klasses.unshift klass
+    end
+
+    methods = []
+
+    klasses.each do |ancestor|
+      ancestors = classes[ancestor]
+
+      next unless ancestors
+
+      klass = ancestor if ambiguous
+
+      ancestors.each do |store|
+        methods << [store, klass, ancestor, types, method]
+      end
+    end
+
+    methods = methods.sort_by do |_, k, a, _, m|
+      [k, a, m].compact
     end
 
-    cache
+    methods.each do |item|
+      yield(*item)
+    end
+
+    self
   end
 
   ##
-  # Writes a cache file for +klassname+ to +path+
+  # Creates a new RDoc::Markup::Formatter.  If a formatter is given with -f,
+  # use it.  If we're outputting to a pager, use bs, otherwise ansi.
+
+  def formatter
+    if @formatter_klass then
+      @formatter_klass.new
+    elsif paging? then
+      RDoc::Markup::ToBs.new
+    else
+      RDoc::Markup::ToAnsi.new
+    end
+  end
 
-  def create_cache_for(klassname, path)
-    klass = class_cache[klassname]
-    return nil unless klass
+  ##
+  # Runs ri interactively using Readline if it is available.
 
-    method_files = klass["sources"]
-    cache = OpenStructHash.new
+  def interactive
+    puts "\nEnter the method name you want to look up."
 
-    method_files.each do |f|
-      system_file = f.index(@sys_dir) == 0
-      Dir[File.join(File.dirname(f), "*")].each do |yaml|
-        next unless yaml =~ /yaml$/
-        next if yaml =~ /cdesc-[^\/]+yaml$/
+    if defined? Readline then
+      Readline.completion_proc = method :complete
+      puts "You can use tab to autocomplete."
+    end
 
-        method = read_yaml yaml
+    puts "Enter a blank line to exit.\n\n"
 
-        if system_file then
-          method["source_path"] = "Ruby #{RDoc::RI::Paths::VERSION}"
-        else
-          gem = Gem.path.any? do |gem_path|
-            pattern = File.join Regexp.escape(gem_path), 'doc', '(.*?)', ''
+    loop do
+      name = if defined? Readline then
+               Readline.readline ">> "
+             else
+               print ">> "
+               $stdin.gets
+             end
 
-            f =~ /^#{pattern}/
-          end
+      return if name.nil? or name.empty?
 
-          method["source_path"] = if gem then
-                                    "gem #{$1}"
-                                  else
-                                    f
-                                  end
-        end
+      name = expand_name name.strip
 
-        name = method["full_name"]
-        cache[name] = method
+      begin
+        display_name name
+      rescue NotFoundError => e
+        puts e.message
       end
     end
 
-    write_cache cache, path
+  rescue Interrupt
+    exit
   end
 
   ##
-  # Finds the next ancestor of +orig_klass+ after +klass+.
+  # Lists classes known to ri
+
+  def list_known_classes
+    classes = []
 
-  def lookup_ancestor(klass, orig_klass)
-    # This is a bit hacky, but ri will go into an infinite loop otherwise,
-    # since Object has an Object ancestor for some reason.  Depending on the
-    # documentation state, I've seen Kernel as an ancestor of Object and not
-    # as an ancestor of Object.
-    if orig_klass == "Object" && (klass == "Kernel" || klass == "Object") then
-      return nil
+    stores.each do |store|
+      classes << store.modules
     end
 
-    cache = class_cache[orig_klass]
+    classes = classes.flatten.uniq.sort
 
-    return nil unless cache
+    page do |io|
+      if paging? or io.tty? then
+        io.puts "Classes and Modules known to ri:"
+        io.puts
+      end
+
+      io.puts classes.join("\n")
+    end
+  end
+
+  ##
+  # Returns an Array of methods matching +name+
+
+  def list_methods_matching name
+    found = []
+
+    find_methods name do |store, klass, ancestor, types, method|
+      if types == :instance or types == :both then
+        methods = store.instance_methods[ancestor]
+
+        if methods then
+          matches = methods.grep(/^#{method}/)
+
+          matches = matches.map do |match|
+            "#{klass}##{match}"
+          end
+
+          found.push(*matches)
+        end
+      end
+
+      if types == :class or types == :both then
+        methods = store.class_methods[ancestor]
 
-    ancestors = [orig_klass]
-    ancestors.push(*cache.includes.map { |inc| inc['name'] })
-    ancestors << cache.superclass
+        next unless methods
+        matches = methods.grep(/^#{method}/)
 
-    ancestor_index = ancestors.index klass
+        matches = matches.map do |match|
+          "#{klass}::#{match}"
+        end
 
-    if ancestor_index
-      ancestor = ancestors[ancestors.index(klass) + 1]
-      return ancestor if ancestor
+        found.push(*matches)
+      end
     end
 
-    lookup_ancestor klass, cache.superclass
+    found.uniq
   end
 
   ##
-  # Finds the method
+  # Loads RI data for method +name+ on +klass+ from +store+.  +type+ and
+  # +cache+ indicate if it is a class or instance method.
+
+  def load_method store, cache, klass, type, name
+    methods = store.send(cache)[klass]
+
+    return unless methods
+
+    method = methods.find do |method_name|
+      method_name == name
+    end
 
-  def lookup_method(name, klass)
-    cache = load_cache_for klass
-    return nil unless cache
+    return unless method
 
-    method = cache[name.gsub('.', '#')]
-    method = cache[name.gsub('.', '::')] unless method
-    method
+    store.load_method klass, "#{type}#{method}"
   end
 
-  def map_dirs(file_name)
-    @doc_dirs.map { |dir| yield File.join(dir, file_name) }.flatten.compact
+  ##
+  # Returns an Array of RI data for methods matching +name+
+
+  def load_methods_matching name
+    found = []
+
+    find_methods name do |store, klass, ancestor, types, method|
+      methods = []
+
+      methods << load_method(store, :class_methods, ancestor, '::',  method) if
+        types == :class or types == :both
+
+      methods << load_method(store, :instance_methods, ancestor, '#',  method) if
+        types == :instance or types == :both
+
+      found << [store, methods.compact]
+    end
+
+    found.reject do |path, methods| methods.empty? end
   end
 
   ##
-  # Extract the class and method name parts from +name+ like Foo::Bar#baz
+  # Returns the type of method (:both, :instance, :class) for +selector+
 
-  def parse_name(name)
-    parts = name.split(/(::|\#|\.)/)
+  def method_type selector
+    case selector
+    when '.', nil then :both
+    when '#'      then :instance
+    else               :class
+    end
+  end
 
-    if parts[-2] != '::' or parts.last !~ /^[A-Z]/ then
-      meth = parts.pop
-      parts.pop
+  ##
+  # Paginates output through a pager program.
+
+  def page
+    if pager = setup_pager then
+      begin
+        yield pager
+      ensure
+        pager.close
+      end
+    else
+      yield $stdout
     end
+  rescue Errno::EPIPE
+  ensure
+    @paging = false
+  end
 
-    klass = parts.join
+  ##
+  # Are we using a pager?
 
-    [klass, meth]
+  def paging?
+    @paging
   end
 
   ##
-  # Reads ri YAML data from +path+, converting RDoc 1.x classes to RDoc 2.x
-  # classes
+  # Extract the class, selector and method name parts from +name+ like
+  # Foo::Bar#baz.
+  #
+  # NOTE: Given Foo::Bar, Bar is considered a class even though it may be a
+  #       method
+
+  def parse_name(name)
+    parts = name.split(/(::|#|\.)/)
 
-  def read_yaml(path)
-    data = File.read path
+    if parts.length == 1 then
+      if parts.first =~ /^[a-z]/ then
+        type = '.'
+        meth = parts.pop
+      else
+        type = nil
+        meth = nil
+      end
+    elsif parts.length == 2 or parts.last =~ /::|#|\./ then
+      type = parts.pop
+      meth = nil
+    elsif parts[-2] != '::' or parts.last !~ /^[A-Z]/ then
+      meth = parts.pop
+      type = parts.pop
+    end
 
-    # Necessary to be backward-compatible with documentation generated
-    # by earliar RDoc versions.
-    data = data.gsub(/ \!ruby\/(object|struct):(RDoc::RI|RI).*/, '')
-    data = data.gsub(/ \!ruby\/(object|struct):SM::(\S+)/,
-                     ' !ruby/\1:RDoc::Markup::\2')
+    klass = parts.join
 
-    OpenStructHash.convert YAML.load(data)
+    [klass, type, meth]
   end
 
   ##
@@ -781,47 +1024,34 @@ Options may also be set in the 'RI' environment variable.
     elsif @interactive then
       interactive
     elsif @names.empty? then
-      @display.list_known_classes class_cache.keys.sort
+      list_known_classes
     else
-      @names.each do |name|
-        display_name name
-      end
+      display_names @names
     end
   rescue NotFoundError => e
     abort e.message
   end
 
   ##
-  # Selects methods matching +pattern+ from all modules
+  # Sets up a pager program to pass output through.  Tries the RI_PAGER and
+  # PAGER environment variables followed by pager, less then more.
 
-  def select_methods(pattern)
-    methods = []
-    class_cache.keys.sort.each do |klass|
-      class_cache[klass]["instance_methods"].map{|h|h["name"]}.grep(pattern) do |name|
-        method = load_cache_for(klass)[klass+'#'+name]
-        methods << method if method
-      end
-      class_cache[klass]["class_methods"].map{|h|h["name"]}.grep(pattern) do |name|
-        method = load_cache_for(klass)[klass+'::'+name]
-        methods << method if method
-      end
-    end
-    methods
-  end
+  def setup_pager
+    return if @use_stdout
 
-  ##
-  # Writes +cache+ to +path+
+    pagers = [ENV['RI_PAGER'], ENV['PAGER'], 'pager', 'less', 'more']
 
-  def write_cache(cache, path)
-    if @use_cache then
-      File.open path, "wb" do |cache_file|
-        Marshal.dump cache, cache_file
-      end
+    pagers.compact.uniq.each do |pager|
+      io = IO.popen(pager, "w") rescue next
+
+      @paging = true
+
+      return io
     end
 
-    cache
-  rescue Errno::EISDIR # HACK toplevel, replace with main
-    cache
+    @use_stdout = true
+
+    nil
   end
 
 end