rdoc 5.1.0 → 6.13.1

data/lib/rdoc/ri/driver.rb

@@ -1,23 +1,10 @@
-# frozen_string_literal: false
-require 'abbrev'
+# frozen_string_literal: true
 require 'optparse'
 
-begin
-  require 'readline'
-rescue LoadError
-end
-
-begin
-  require 'win32console'
-rescue LoadError
-end
-
-require 'rdoc'
+require_relative '../../rdoc'
 
-##
-# For RubyGems backwards compatibility
-
-require 'rdoc/ri/formatter'
+require_relative 'formatter' # For RubyGems backwards compatibility
+# TODO: Fix weird documentation with `require_relative`
 
 ##
 # The RI driver implements the command-line ri tool.
@@ -47,13 +34,25 @@ class RDoc::RI::Driver
 
   class NotFoundError < Error
 
+    def initialize(klass, suggestion_proc = nil) # :nodoc:
+      @klass = klass
+      @suggestion_proc = suggestion_proc
+    end
+
     ##
     # Name that wasn't found
 
-    alias name message
+    def name
+      @klass
+    end
 
     def message # :nodoc:
-      "Nothing known about #{super}"
+      str = "Nothing known about #{@klass}"
+      suggestions = @suggestion_proc&.call
+      if suggestions and !suggestions.empty?
+        str += "\nDid you mean?  #{suggestions.join("\n               ")}"
+      end
+      str
     end
   end
 
@@ -80,7 +79,7 @@ class RDoc::RI::Driver
     options[:interactive] = false
     options[:profile]     = false
     options[:show_all]    = false
-    options[:use_cache]   = true
+    options[:expand_refs] = true
     options[:use_stdout]  = !$stdout.tty?
     options[:width]       = 72
 
@@ -100,7 +99,7 @@ class RDoc::RI::Driver
   def self.dump data_path
     require 'pp'
 
-    open data_path, 'rb' do |io|
+    File.open data_path, 'rb' do |io|
       pp Marshal.load(io.read)
     end
   end
@@ -112,17 +111,13 @@ class RDoc::RI::Driver
     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
 
       opt.banner = <<-EOT
-Usage: #{opt.program_name} [options] [names...]
+Usage: #{opt.program_name} [options] [name ...]
 
 Where name can be:
 
@@ -132,8 +127,10 @@ Where name can be:
 
   gem_name: | gem_name:README | gem_name:History
 
-All class names may be abbreviated to their minimum unambiguous form. If a name
-is ambiguous, all valid options will be listed.
+  ruby: | ruby:NEWS | ruby:globals
+
+All class names may be abbreviated to their minimum unambiguous form.
+If a name is ambiguous, all valid options will be listed.
 
 A '.' matches either class or instance methods, while #method
 matches only instance and ::method matches only class methods.
@@ -143,6 +140,10 @@ they're contained in.  If the gem name is followed by a ':' all files in the
 gem will be shown.  The file name extension may be omitted where it is
 unambiguous.
 
+'ruby' can be used as a pseudo gem name to display files from the Ruby
+core documentation. Use 'ruby:' by itself to get a list of all available
+core documentation files.
+
 For example:
 
     #{opt.program_name} Fil
@@ -150,24 +151,25 @@ For example:
     #{opt.program_name} File.new
     #{opt.program_name} zip
     #{opt.program_name} rdoc:README
+    #{opt.program_name} ruby:comments
 
-Note that shell quoting or escaping may be required for method names containing
-punctuation:
+Note that shell quoting or escaping may be required for method names
+containing punctuation:
 
     #{opt.program_name} 'Array.[]'
     #{opt.program_name} compact\\!
 
-To see the default directories ri will search, run:
+To see the default directories #{opt.program_name} will search, run:
 
     #{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.
+Specifying the --system, --site, --home, --gems, or --doc-dir options
+will limit ri to searching only the specified directories.
 
-ri options may be set in the 'RI' environment variable.
+ri options may be set in the RI environment variable.
 
-The ri pager can be set with the 'RI_PAGER' environment variable or the
-'PAGER' environment variable.
+The ri pager can be set with the RI_PAGER environment variable
+or the PAGER environment variable.
       EOT
 
       opt.separator nil
@@ -199,15 +201,15 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
       opt.separator nil
 
       opt.on("--[no-]pager",
-             "Send output directly to stdout,",
-             "rather than to a pager.") do |use_pager|
+             "Send output to a pager,",
+             "rather than directly to stdout.") do |use_pager|
         options[:use_stdout] = !use_pager
       end
 
       opt.separator nil
 
       opt.on("-T",
-             "Synonym for --no-pager") do
+             "Synonym for --no-pager.") do
         options[:use_stdout] = true
       end
 
@@ -220,7 +222,7 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
 
       opt.separator nil
 
-      opt.on("--server [PORT]", Integer,
+      opt.on("--server[=PORT]", Integer,
              "Run RDoc server on the given port.",
              "The default port is 8214.") do |port|
         options[:server] = port || 8214
@@ -235,13 +237,35 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
       formatters -= %w[html label test] # remove useless output formats
 
       opt.on("--format=NAME", "-f",
-             "Uses the selected formatter. The default",
+             "Use the selected formatter.  The default",
              "formatter is bs for paged output and ansi",
-             "otherwise. Valid formatters are:",
-             formatters.join(' '), formatters) do |value|
+             "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-]expand-refs", "Expand rdoc-refs at the end of output") do |value|
+        options[:expand_refs] = value
+      end
+
+      opt.separator nil
+
+      opt.on("--help", "-h",
+             "Show help and exit.") do
+        puts opts
+        exit
+      end
+
+      opt.separator nil
+
+      opt.on("--version", "-v",
+             "Output version information and exit.") do
+        puts "#{opts.program_name} #{opts.version}"
+        exit
+      end
+
       opt.separator nil
       opt.separator "Data source options:"
       opt.separator nil
@@ -273,7 +297,7 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
              "Do not include documentation from",
              "the Ruby standard library, site_lib,",
              "installed gems, or ~/.rdoc.",
-             "Use with --doc-dir") do
+             "Use with --doc-dir.") do
         options[:use_system] = false
         options[:use_site] = false
         options[:use_gems] = false
@@ -283,8 +307,8 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
       opt.separator nil
 
       opt.on("--[no-]system",
-             "Include documentation from Ruby's standard",
-             "library.  Defaults to true.") do |value|
+             "Include documentation from Ruby's",
+             "standard library.  Defaults to true.") do |value|
         options[:use_system] = value
       end
 
@@ -318,19 +342,27 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
       opt.separator nil
 
       opt.on("--[no-]profile",
-             "Run with the ruby profiler") do |value|
+             "Run with the ruby profiler.") do |value|
         options[:profile] = value
       end
 
       opt.separator nil
 
-      opt.on("--dump=CACHE", File,
-             "Dumps data from an ri cache or data file") do |value|
-        options[:dump_path] = value
+      opt.on("--dump=CACHE",
+             "Dump data from an ri cache or data file.") do |value|
+        unless File.readable?(value)
+          abort "#{value.inspect} is not readable"
+        end
+
+        if File.directory?(value)
+          abort "#{value.inspect} is a directory"
+        end
+
+        options[:dump_path] = File.new(value)
       end
     end
 
-    argv = ENV['RI'].to_s.split.concat argv
+    argv = ENV['RI'].to_s.split(' ').concat argv
 
     opts.parse! argv
 
@@ -388,7 +420,7 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
                          *options[:extra_doc_dirs]) do |path, type|
       @doc_dirs << path
 
-      store = RDoc::RI::Store.new path, type
+      store = RDoc::RI::Store.new(RDoc::Options.new, path: path, type: type)
       store.load_cache
       @stores << store
     end
@@ -399,9 +431,8 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
     @server      = options[:server]
     @use_stdout  = options[:use_stdout]
     @show_all    = options[:show_all]
-
-    # pager process for jruby
-    @jruby_pager_process = nil
+    @width       = options[:width]
+    @expand_refs = options[:expand_refs]
   end
 
   ##
@@ -487,7 +518,7 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
     with.each do |incl|
       out << RDoc::Markup::Paragraph.new(incl.name)
       out << RDoc::Markup::BlankLine.new
-      out << incl.comment
+      out << incl.comment.parse
     end
 
     unless wout.empty? then
@@ -511,7 +542,7 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
 
     if include.comment then
       out << RDoc::Markup::BlankLine.new
-      out << include.comment
+      out << include.comment.parse
     end
   end
 
@@ -526,11 +557,8 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
   # Looks up the method +name+ and adds it to +out+
 
   def add_method out, name
-    filtered   = lookup_method name
-
-    method_out = method_document name, filtered
-
-    out.concat method_out.parts
+    filtered = lookup_method name
+    method_document out, name, filtered
   end
 
   ##
@@ -582,11 +610,11 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
 
       stores = classes[current]
 
-      break unless stores and not stores.empty?
+      next unless stores and not stores.empty?
 
-      klasses = stores.map do |store|
-        store.ancestors[current]
-      end.flatten.uniq
+      klasses = stores.flat_map do |store|
+        store.ancestors[current] || []
+      end.uniq
 
       klasses = klasses - seen
 
@@ -622,18 +650,19 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
 
     add_also_in out, also_in
 
+    expand_rdoc_refs_at_the_bottom(out)
     out
   end
 
   ##
   # Adds the class +comment+ to +out+.
 
-  def class_document_comment out, comment # :nodoc:
-    unless comment.empty? then
+  def class_document_comment out, document # :nodoc:
+    unless document.empty? then
       out << RDoc::Markup::Rule.new(1)
 
-      if comment.merged? then
-        parts = comment.parts
+      if document.merged? then
+        parts = document.parts
         parts = parts.zip [RDoc::Markup::BlankLine.new] * parts.length
         parts.flatten!
         parts.pop
@@ -658,7 +687,7 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
     constants = klass.constants.sort_by { |constant| constant.name }
 
     list.items.concat constants.map { |constant|
-      parts = constant.comment.parts if constant.comment
+      parts = constant.comment.parse.parts
       parts << RDoc::Markup::Paragraph.new('[not documented]') if
         parts.empty?
 
@@ -725,7 +754,7 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
     complete_klass  name, klass, selector, method, completions
     complete_method name, klass, selector,         completions
 
-    completions.sort.uniq
+    completions.uniq.select {|s| s.start_with? name }.sort
   end
 
   def complete_klass name, klass, selector, method, completions # :nodoc:
@@ -760,7 +789,15 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
         completions << "#{klass}#{selector}"
       end
 
-      completions.concat methods
+      methods.each do |klass_sel_method|
+        match = klass_sel_method.match(/^(.+)(#|\.|::)([^#.:]+)$/)
+        # match[2] is `::` for class method and `#` for instance method.
+        # To be consistent with old completion that completes `['Foo#i', 'Foo::c']` for `Foo.`,
+        # `.` should be a wildcard for both `#` and `::` here.
+        if match && match[2] == selector || selector == '.'
+          completions << match[1] + selector + match[3]
+        end
+      end
     end
   end
 
@@ -769,7 +806,9 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
 
   def display document
     page do |io|
-      text = document.accept formatter(io)
+      f = formatter(io)
+      f.width = @width if @width and f.respond_to?(:width)
+      text = document.accept f
 
       io.write text
     end
@@ -799,6 +838,8 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
 
     add_method out, name
 
+    expand_rdoc_refs_at_the_bottom(out)
+
     display out
   end
 
@@ -873,7 +914,7 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
 
     page = store.load_page page_name
 
-    display page.comment
+    display page.comment.parse
   end
 
   ##
@@ -902,13 +943,38 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
     display out
   end
 
+  def check_did_you_mean # :nodoc:
+    if defined? DidYouMean::SpellChecker
+      true
+    else
+      begin
+        require 'did_you_mean'
+        if defined? DidYouMean::SpellChecker
+          true
+        else
+          false
+        end
+      rescue LoadError
+        false
+      end
+    end
+  end
+
   ##
   # Expands abbreviated klass +klass+ into a fully-qualified class.  "Zl::Da"
   # will be expanded to Zlib::DataError.
 
   def expand_class klass
-    ary = classes.keys.grep(Regexp.new("\\A#{klass.gsub(/(?=::|\z)/, '[^:]*')}\\z"))
-    raise NotFoundError, klass if ary.length != 1 && ary.first != klass
+    class_names = classes.keys
+    ary = class_names.grep(Regexp.new("\\A#{klass.gsub(/(?=::|\z)/, '[^:]*')}\\z"))
+    if ary.length != 1 && ary.first != klass
+      if check_did_you_mean
+        suggestion_proc = -> { DidYouMean::SpellChecker.new(dictionary: class_names).correct(klass) }
+        raise NotFoundError.new(klass, suggestion_proc)
+      else
+        raise NotFoundError, klass
+      end
+    end
     ary.first
   end
 
@@ -990,36 +1056,6 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
     self
   end
 
-  ##
-  # Finds the given +pager+ for jruby.  Returns an IO if +pager+ was found.
-  #
-  # Returns false if +pager+ does not exist.
-  #
-  # Returns nil if the jruby JVM doesn't support ProcessBuilder redirection
-  # (1.6 and older).
-
-  def find_pager_jruby pager
-    require 'java'
-    require 'shellwords'
-
-    return nil unless java.lang.ProcessBuilder.constants.include? :Redirect
-
-    pager = Shellwords.split pager
-
-    pb = java.lang.ProcessBuilder.new(*pager)
-    pb = pb.redirect_output java.lang.ProcessBuilder::Redirect::INHERIT
-
-    @jruby_pager_process = pb.start
-
-    input = @jruby_pager_process.output_stream
-
-    io = input.to_io
-    io.sync = true
-    io
-  rescue java.io.IOException
-    false
-  end
-
   ##
   # Finds a store that matches +name+ which can be the name of a gem, "ruby",
   # "home" or "site".
@@ -1059,6 +1095,10 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
   def interactive
     puts "\nEnter the method name you want to look up."
 
+    begin
+      require 'readline'
+    rescue LoadError
+    end
     if defined? Readline then
       Readline.completion_proc = method :complete
       puts "You can use tab to autocomplete."
@@ -1068,7 +1108,7 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
 
     loop do
       name = if defined? Readline then
-               Readline.readline ">> "
+               Readline.readline ">> ", true
              else
                print ">> "
                $stdin.gets
@@ -1087,17 +1127,6 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
     exit
   end
 
-  ##
-  # Is +file+ in ENV['PATH']?
-
-  def in_path? file
-    return true if file =~ %r%\A/% and File.exist? file
-
-    ENV['PATH'].split(File::PATH_SEPARATOR).any? do |path|
-      File.exist? File.join(path, file)
-    end
-  end
-
   ##
   # Lists classes known to ri starting with +names+.  If +names+ is empty all
   # known classes are shown.
@@ -1174,7 +1203,7 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
   # +cache+ indicate if it is a class or instance method.
 
   def load_method store, cache, klass, type, name
-    methods = store.send(cache)[klass]
+    methods = store.public_send(cache)[klass]
 
     return unless methods
 
@@ -1186,7 +1215,8 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
 
     store.load_method klass, "#{type}#{method}"
   rescue RDoc::Store::MissingFileError => e
-    comment = RDoc::Comment.new("missing documentation at #{e.file}").parse
+    comment = RDoc::Comment.new("missing documentation at #{e.file}")
+    comment.parse
 
     method = RDoc::AnyMethod.new nil, name
     method.comment = comment
@@ -1220,7 +1250,21 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
   def lookup_method name
     found = load_methods_matching name
 
-    raise NotFoundError, name if found.empty?
+    if found.empty?
+      if check_did_you_mean
+        methods = []
+        _, _, method_name = parse_name name
+        find_methods name do |store, klass, ancestor, types, method|
+          methods.push(*store.class_methods[klass]) if [:class, :both].include? types
+          methods.push(*store.instance_methods[klass]) if [:instance, :both].include? types
+        end
+        methods = methods.uniq
+        suggestion_proc = -> { DidYouMean::SpellChecker.new(dictionary: methods).correct(method_name) }
+        raise NotFoundError.new(name, suggestion_proc)
+      else
+        raise NotFoundError, name
+      end
+    end
 
     filter_methods found, name
   end
@@ -1228,9 +1272,7 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
   ##
   # Builds a RDoc::Markup::Document from +found+, +klasses+ and +includes+
 
-  def method_document name, filtered
-    out = RDoc::Markup::Document.new
-
+  def method_document out, name, filtered
     out << RDoc::Markup::Heading.new(1, name)
     out << RDoc::Markup::BlankLine.new
 
@@ -1278,7 +1320,6 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
         yield pager
       ensure
         pager.close
-        @jruby_pager_process.wait_for if @jruby_pager_process
       end
     else
       yield $stdout
@@ -1335,13 +1376,13 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
   # documentable items the class is added to +also_in+ instead.
 
   def render_class out, store, klass, also_in # :nodoc:
-    comment = klass.comment
+    document = klass.comment.parse
     # TODO the store's cache should always return an empty Array
     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
+    if document.empty? and
        instance_methods.empty? and class_methods.empty? then
       also_in << store
       return
@@ -1349,7 +1390,7 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
 
     add_from out, store
 
-    class_document_comment out, comment
+    class_document_comment out, document
 
     if class_methods or instance_methods or not klass.constants.empty? then
       out << RDoc::Markup::Rule.new(1)
@@ -1375,7 +1416,13 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
 
     render_method_arguments out, method.arglists
     render_method_superclass out, method
-    render_method_comment out, method
+    if method.is_alias_for
+      al = method.is_alias_for
+      alias_for = store.load_method al.parent_name, "#{al.name_prefix}#{al.name}"
+      render_method_comment out, method, alias_for
+    else
+      render_method_comment out, method
+    end
   end
 
   def render_method_arguments out, arglists # :nodoc:
@@ -1387,10 +1434,22 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
     out << RDoc::Markup::Rule.new(1)
   end
 
-  def render_method_comment out, method # :nodoc:
-    out << RDoc::Markup::BlankLine.new
-    out << method.comment
-    out << RDoc::Markup::BlankLine.new
+  def render_method_comment out, method, alias_for = nil# :nodoc:
+    if alias_for
+      unless method.comment.nil? or method.comment.empty?
+        out << RDoc::Markup::BlankLine.new
+        out << method.comment.parse
+      end
+      out << RDoc::Markup::BlankLine.new
+      out << RDoc::Markup::Paragraph.new("(This method is an alias for #{alias_for.full_name}.)")
+      out << RDoc::Markup::BlankLine.new
+      out << alias_for.comment.parse
+      out << RDoc::Markup::BlankLine.new
+    else
+      out << RDoc::Markup::BlankLine.new
+      out << method.comment.parse
+      out << RDoc::Markup::BlankLine.new
+    end
   end
 
   def render_method_superclass out, method # :nodoc:
@@ -1428,27 +1487,14 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
   def setup_pager
     return if @use_stdout
 
-    jruby = RUBY_ENGINE == 'jruby'
-
     pagers = [ENV['RI_PAGER'], ENV['PAGER'], 'pager', 'less', 'more']
 
+    require 'shellwords'
     pagers.compact.uniq.each do |pager|
-      next unless pager
-
-      pager_cmd = pager.split.first
-
-      next unless in_path? pager_cmd
-
-      if jruby then
-        case io = find_pager_jruby(pager)
-        when nil   then break
-        when false then next
-        else            io
-        end
-      else
-        io = IO.popen(pager, 'w') rescue next
-      end
+      pager = Shellwords.split(pager)
+      next if pager.empty?
 
+      io = IO.popen(pager, 'w') rescue next
       next if $? and $?.pid == io.pid and $?.exited? # pager didn't work
 
       @paging = true
@@ -1465,7 +1511,11 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
   # Starts a WEBrick server for ri.
 
   def start_server
-    require 'webrick'
+    begin
+      require 'webrick'
+    rescue LoadError
+      abort "webrick is not found. You may need to `gem install webrick` to install webrick."
+    end
 
     server = WEBrick::HTTPServer.new :Port => @server
 
@@ -1479,4 +1529,38 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
     server.start
   end
 
+  RDOC_REFS_REGEXP = /\[rdoc-ref:([\w.]+)(@.*)?\]/
+
+  def expand_rdoc_refs_at_the_bottom(out)
+    return unless @expand_refs
+
+    extracted_rdoc_refs = []
+
+    out.each do |part|
+      content = if part.respond_to?(:text)
+        part.text
+      else
+        next
+      end
+
+      rdoc_refs = content.scan(RDOC_REFS_REGEXP).uniq.map do |file_name, _anchor|
+        file_name
+      end
+
+      extracted_rdoc_refs.concat(rdoc_refs)
+    end
+
+    found_pages = extracted_rdoc_refs.map do |ref|
+      begin
+        @stores.first.load_page(ref)
+      rescue RDoc::Store::MissingFileError
+      end
+    end.compact
+
+    found_pages.each do |page|
+      out << RDoc::Markup::Heading.new(4, "Expanded from #{page.full_name}")
+      out << RDoc::Markup::BlankLine.new
+      out << page.comment.parse
+    end
+  end
 end