rdoc 2.0.0

data/lib/rdoc/ri/descriptions.rb

@@ -0,0 +1,150 @@
+require 'yaml'
+require 'rdoc/markup/fragments'
+require 'rdoc/ri'
+
+#--
+# Descriptions are created by RDoc (in ri_generator) and written out in
+# serialized form into the documentation tree. ri then reads these to generate
+# the documentation
+#++
+
+class RDoc::RI::NamedThing
+  attr_reader :name
+  def initialize(name)
+    @name = name
+  end
+
+  def <=>(other)
+    @name <=> other.name
+  end
+
+  def hash
+    @name.hash
+  end
+
+  def eql?(other)
+    @name.eql?(other)
+  end
+end
+
+class RDoc::RI::AliasName < RDoc::RI::NamedThing; end
+
+class RDoc::RI::Attribute < RDoc::RI::NamedThing
+  attr_reader :rw, :comment
+
+  def initialize(name, rw, comment)
+    super(name)
+    @rw = rw
+    @comment = comment
+  end
+end
+
+class RDoc::RI::Constant < RDoc::RI::NamedThing
+  attr_reader :value, :comment
+
+  def initialize(name, value, comment)
+    super(name)
+    @value = value
+    @comment = comment
+  end
+end
+
+class RDoc::RI::IncludedModule < RDoc::RI::NamedThing; end
+
+class RDoc::RI::MethodSummary < RDoc::RI::NamedThing
+  def initialize(name="")
+    super
+  end
+end
+
+class RDoc::RI::Description
+  attr_accessor :name
+  attr_accessor :full_name
+  attr_accessor :comment
+
+  def serialize
+    self.to_yaml
+  end
+
+  def self.deserialize(from)
+    YAML.load(from)
+  end
+
+  def <=>(other)
+    @name <=> other.name
+  end
+end
+
+class RDoc::RI::ModuleDescription < RDoc::RI::Description
+
+  attr_accessor :class_methods
+  attr_accessor :instance_methods
+  attr_accessor :attributes
+  attr_accessor :constants
+  attr_accessor :includes
+
+  # merge in another class desscription into this one
+  def merge_in(old)
+    merge(@class_methods, old.class_methods)
+    merge(@instance_methods, old.instance_methods)
+    merge(@attributes, old.attributes)
+    merge(@constants, old.constants)
+    merge(@includes, old.includes)
+    if @comment.nil? || @comment.empty?
+      @comment = old.comment
+    else
+      unless old.comment.nil? or old.comment.empty? then
+        @comment << RDoc::Markup::Flow::RULE.new
+        @comment.concat old.comment
+      end
+    end
+  end
+
+  def display_name
+      "Module"
+  end
+
+  # the 'ClassDescription' subclass overrides this
+  # to format up the name of a parent
+  def superclass_string
+    nil
+  end
+
+  private
+
+  def merge(into, from)
+    names = {}
+    into.each {|i| names[i.name] = i }
+    from.each {|i| names[i.name] = i }
+    into.replace(names.keys.sort.map {|n| names[n]})
+  end
+end
+
+class RDoc::RI::ClassDescription < RDoc::RI::ModuleDescription
+  attr_accessor :superclass
+
+  def display_name
+      "Class"
+  end
+
+  def superclass_string
+    if @superclass && @superclass != "Object"
+      @superclass
+    else
+      nil
+    end
+  end
+end
+
+class RDoc::RI::MethodDescription < RDoc::RI::Description
+
+  attr_accessor :is_class_method
+  attr_accessor :visibility
+  attr_accessor :block_params
+  attr_accessor :is_singleton
+  attr_accessor :aliases
+  attr_accessor :is_alias_for
+  attr_accessor :params
+
+end
+

data/lib/rdoc/ri/display.rb

@@ -0,0 +1,274 @@
+require 'rdoc/ri'
+
+##
+# This is a kind of 'flag' module. If you want to write your own 'ri' display
+# module (perhaps because you're writing an IDE), you write a class which
+# implements the various 'display' methods in RDoc::RI::DefaultDisplay, and
+# include the RDoc::RI::Display module in that class.
+#
+# To access your class from the command line, you can do
+#
+#    ruby -r <your source file>  ../ri ....
+
+module RDoc::RI::Display
+
+  @@display_class = nil
+
+  def self.append_features(display_class)
+    @@display_class = display_class
+  end
+
+  def self.new(*args)
+    @@display_class.new(*args)
+  end
+
+end
+
+##
+# A paging display module. Uses the RDoc::RI::Formatter class to do the actual
+# presentation.
+
+class RDoc::RI::DefaultDisplay
+
+  include RDoc::RI::Display
+
+  def initialize(formatter, width, use_stdout, output = $stdout)
+    @use_stdout = use_stdout
+    @formatter = formatter.new output, width, "     "
+  end
+
+  ##
+  # Display information about +klass+.  Fetches additional information from
+  # +ri_reader+ as necessary.
+
+  def display_class_info(klass, ri_reader)
+    page do
+      superclass = klass.superclass_string
+
+      if superclass
+        superclass = " < " + superclass
+      else
+        superclass = ""
+      end
+
+      @formatter.draw_line(klass.display_name + ": " +
+                           klass.full_name + superclass)
+
+      display_flow(klass.comment)
+      @formatter.draw_line
+
+      unless klass.includes.empty?
+        @formatter.blankline
+        @formatter.display_heading("Includes:", 2, "")
+        incs = []
+        klass.includes.each do |inc|
+          inc_desc = ri_reader.find_class_by_name(inc.name)
+          if inc_desc
+            str = inc.name + "("
+            str << inc_desc.instance_methods.map{|m| m.name}.join(", ")
+            str << ")"
+            incs << str
+          else
+            incs << inc.name
+          end
+      end
+        @formatter.wrap(incs.sort.join(', '))
+      end
+
+      unless klass.constants.empty?
+        @formatter.blankline
+        @formatter.display_heading("Constants:", 2, "")
+
+        constants = klass.constants.sort_by { |constant| constant.name }
+
+        constants.each do |constant|
+          if constant.comment then
+            @formatter.wrap "#{constant.name}:"
+
+            @formatter.indent do
+              @formatter.display_flow constant.comment
+            end
+          else
+            @formatter.wrap constant.name
+          end
+        end
+      end
+
+      class_data = [
+        :class_methods,
+        :class_method_extensions,
+        :instance_methods,
+        :instance_method_extensions,
+      ]
+
+      class_data.each do |data_type|
+        data = klass.send data_type
+
+        unless data.empty? then
+          @formatter.blankline
+
+          heading = data_type.to_s.split('_').join(' ').capitalize << ':'
+          @formatter.display_heading heading, 2, ''
+
+          data = data.map { |item| item.name }.sort.join ', '
+          @formatter.wrap data
+        end
+      end
+
+      unless klass.attributes.empty? then
+        @formatter.blankline
+
+        @formatter.display_heading 'Attributes:', 2, ''
+
+        attributes = klass.attributes.sort_by { |attribute| attribute.name }
+
+        attributes.each do |attribute|
+          if attribute.comment then
+            @formatter.wrap "#{attribute.name} (#{attribute.rw}):"
+            @formatter.indent do
+              @formatter.display_flow attribute.comment
+            end
+          else
+            @formatter.wrap "#{attribute.name} (#{attribute.rw})"
+          end
+        end
+      end
+    end
+  end
+
+  ##
+  # Display an Array of RDoc::Markup::Flow objects, +flow+.
+
+  def display_flow(flow)
+    if flow and not flow.empty? then
+      @formatter.display_flow flow
+    else
+      @formatter.wrap '[no description]'
+    end
+  end
+
+  ##
+  # Display information about +method+.
+
+  def display_method_info(method)
+    page do
+      @formatter.draw_line(method.full_name)
+      display_params(method)
+
+      @formatter.draw_line
+      display_flow(method.comment)
+
+      if method.aliases and not method.aliases.empty? then
+        @formatter.blankline
+        aka = "(also known as #{method.aliases.map { |a| a.name }.join(', ')})"
+        @formatter.wrap aka
+      end
+    end
+  end
+
+  ##
+  # Display the list of +methods+.
+
+  def display_method_list(methods)
+    page do
+      @formatter.wrap "More than one method matched your request.  You can refine your search by asking for information on one of:"
+
+      @formatter.blankline
+
+      @formatter.wrap methods.map { |m| m.full_name }.join(", ")
+    end
+  end
+
+  ##
+  # Display the params for +method+.
+
+  def display_params(method)
+    params = method.params
+
+    if params[0,1] == "(" then
+      if method.is_singleton
+        params = method.full_name + params
+      else
+        params = method.name + params
+      end
+    end
+
+    params.split(/\n/).each do |param|
+      @formatter.wrap param
+      @formatter.break_to_newline
+    end
+
+    if method.source_path then
+      @formatter.blankline
+      @formatter.wrap("Extension from #{method.source_path}")
+    end
+  end
+
+  ##
+  # List the classes in +classes+.
+
+  def list_known_classes(classes)
+    if classes.empty?
+      warn_no_database
+    else
+      page do
+        @formatter.draw_line "Known classes and modules"
+        @formatter.blankline
+
+        @formatter.wrap classes.sort.join(', ')
+      end
+    end
+  end
+
+  ##
+  # Paginates output through a pager program.
+
+  def page
+    if pager = setup_pager then
+      begin
+        orig_output = @formatter.output
+        @formatter.output = pager
+        yield
+      ensure
+        @formatter.output = orig_output
+        pager.close
+      end
+    else
+      yield
+    end
+  rescue Errno::EPIPE
+  end
+
+  ##
+  # Sets up a pager program to pass output through.
+
+  def setup_pager
+    unless @use_stdout then
+      for pager in [ ENV['PAGER'], "less", "more", 'pager' ].compact.uniq
+        return IO.popen(pager, "w") rescue nil
+      end
+      @use_stdout = true
+      nil
+    end
+  end
+
+  ##
+  # Displays a message that describes how to build RI data.
+
+  def warn_no_database
+    output = @formatter.output
+
+    output.puts "No ri data found"
+    output.puts
+    output.puts "If you've installed Ruby yourself, you need to generate documentation using:"
+    output.puts
+    output.puts "  make install-doc"
+    output.puts
+    output.puts "from the same place you ran `make` to build ruby."
+    output.puts
+    output.puts "If you installed Ruby from a packaging system, then you may need to"
+    output.puts "install an additional package, or ask the packager to enable ri generation."
+  end
+
+end
+

data/lib/rdoc/ri/driver.rb

@@ -0,0 +1,452 @@
+require 'optparse'
+require 'yaml'
+
+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'
+
+class RDoc::RI::Driver
+
+  def self.process_args(argv)
+    options = {}
+    options[:use_stdout] = !$stdout.tty?
+    options[:width] = 72
+    options[:formatter] = RDoc::RI::Formatter.for 'plain'
+    options[:list_classes] = false
+    options[:list_names] = false
+
+    # By default all paths are used.  If any of these are true, only those
+    # directories are used.
+    use_system = false
+    use_site = false
+    use_home = false
+    use_gems = false
+    doc_dirs = []
+
+    opts = OptionParser.new do |opt|
+      opt.program_name = File.basename $0
+      opt.version = RDoc::VERSION
+      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...]
+
+Where name can be:
+
+  Class | Class::method | Class#method | Class.method | method
+
+All class names may be abbreviated to their minimum unambiguous form. If a name
+is ambiguous, all valid options will be listed.
+
+The form '.' method matches either class or instance methods, while #method
+matches only instance and ::method matches only class methods.
+
+For example:
+
+    #{opt.program_name} Fil
+    #{opt.program_name} File
+    #{opt.program_name} File.new
+    #{opt.program_name} zip
+
+Note that shell quoting may be required for method names containing
+punctuation:
+
+    #{opt.program_name} 'Array.[]'
+    #{opt.program_name} compact\\!
+
+By default ri searches for documentation in the following directories:
+
+    #{directories.join "\n    "}
+
+Specifying the --system, --site, --home, --gems or --doc-dir options will
+limit ri to searching only the specified directories.
+
+Options may also be set in the 'RI' environment variable.
+      EOT
+
+      opt.separator nil
+      opt.separator "Options:"
+      opt.separator nil
+
+      opt.on("--classes", "-c",
+             "Display the names of classes and modules we",
+             "know about.") do |value|
+        options[:list_classes] = value
+      end
+
+      opt.separator nil
+
+      opt.on("--doc-dir=DIRNAME", "-d", Array,
+             "List of directories to search for",
+             "documentation. If not specified, we search",
+             "the standard rdoc/ri directories. May be",
+             "repeated.") do |value|
+        value.each do |dir|
+          unless File.directory? dir then
+            raise OptionParser::InvalidArgument, "#{dir} is not a directory"
+          end
+        end
+
+        doc_dirs.concat value
+      end
+
+      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
+      end
+
+      opt.separator nil
+
+      unless RDoc::RI::Paths::GEMDIRS.empty? then
+        opt.on("--[no-]gems",
+               "Include documentation from RubyGems.") do |value|
+          use_gems = value
+        end
+      end
+
+      opt.separator nil
+
+      opt.on("--[no-]home",
+             "Include documentation stored in ~/.rdoc.") do |value|
+        use_home = value
+      end
+
+      opt.separator nil
+
+      opt.on("--[no-]list-names", "-l",
+             "List all the names known to RDoc, one per",
+             "line.") do |value|
+        options[:list_names] = value
+      end
+
+      opt.separator nil
+
+      opt.on("--no-pager", "-T",
+             "Send output directly to stdout.") do |value|
+        options[:use_stdout] = !value
+      end
+
+      opt.separator nil
+
+      opt.on("--[no-]site",
+             "Include documentation from libraries",
+             "installed in site_lib.") do |value|
+        use_site = value
+      end
+
+      opt.separator nil
+
+      opt.on("--[no-]system",
+             "Include documentation from Ruby's standard",
+             "library.") do |value|
+        use_system = value
+      end
+
+      opt.separator nil
+
+      opt.on("--width=WIDTH", "-w", OptionParser::DecimalInteger,
+             "Set the width of the output.") do |value|
+        options[:width] = value
+      end
+    end
+
+    argv = ENV['RI'].to_s.split.concat argv
+
+    opts.parse! argv
+
+    options[:names] = argv
+
+    options[:path] = RDoc::RI::Paths.path(use_system, use_site, use_home,
+                                          use_gems, *doc_dirs)
+    options[:raw_path] = RDoc::RI::Paths.raw_path(use_system, use_site,
+                                                  use_home, use_gems, *doc_dirs)
+
+    options
+
+  rescue OptionParser::InvalidArgument, OptionParser::InvalidOption => e
+    puts opts
+    puts
+    puts e
+    exit 1
+  end
+
+  def self.run(argv = ARGV)
+    options = process_args argv
+    ri = new options
+    ri.run
+  end
+
+  def initialize(options={})
+    options[:formatter] ||= RDoc::RI::Formatter.for('plain')
+    options[:use_stdout] ||= !$stdout.tty?
+    options[:width] ||= 72
+    @names = options[:names]
+
+    @class_cache_name = 'classes'
+    @all_dirs = RDoc::RI::Paths.path(true, true, true, true)
+    @homepath = RDoc::RI::Paths.raw_path(false, false, true, false).first
+    @homepath = @homepath.sub(/\.rdoc/, '.ri')
+    @sys_dirs = RDoc::RI::Paths.raw_path(true, false, false, false)
+
+    FileUtils.mkdir_p cache_file_path unless File.directory? cache_file_path
+
+    @class_cache = nil
+
+    @display = RDoc::RI::DefaultDisplay.new(options[:formatter],
+                                            options[:width],
+                                            options[:use_stdout])
+  end
+
+  def class_cache
+    return @class_cache if @class_cache
+
+    newest = map_dirs('created.rid', :all) do |f|
+      File.mtime f if test ?f, f
+    end.max
+
+    up_to_date = (File.exist?(class_cache_file_path) and
+                  newest and newest < File.mtime(class_cache_file_path))
+
+    @class_cache = if up_to_date then
+                     load_cache_for @class_cache_name
+                   else
+                     class_cache = {}
+
+                     classes = map_dirs('**/cdesc*.yaml', :sys) { |f| Dir[f] }
+                     populate_class_cache class_cache, classes
+
+                     classes = map_dirs('**/cdesc*.yaml') { |f| Dir[f] }
+                     warn "Updating class cache with #{classes.size} classes..."
+
+                     populate_class_cache class_cache, classes, true
+                     write_cache class_cache, class_cache_file_path
+                   end
+  end
+
+  def class_cache_file_path
+    File.join cache_file_path, @class_cache_name
+  end
+
+  def cache_file_for(klassname)
+    File.join cache_file_path, klassname.gsub(/:+/, "-")
+  end
+
+  def cache_file_path
+    File.join @homepath, 'cache'
+  end
+
+  def display_class(name)
+    klass = class_cache[name]
+    @display.display_class_info klass, class_cache
+  end
+
+  def load_cache_for(klassname)
+    path = cache_file_for klassname
+
+    if File.exist? path and
+       File.mtime(path) >= File.mtime(class_cache_file_path) then
+      File.open path, 'rb' do |fp|
+        Marshal.load fp.read
+      end
+    else
+      class_cache = nil
+
+      File.open class_cache_file_path, 'rb' do |fp|
+        class_cache = Marshal.load fp.read
+      end
+
+      klass = class_cache[klassname]
+      return nil unless klass
+
+      method_files = klass["sources"]
+      cache = {}
+
+      sys_dir = @sys_dirs.first
+      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$/
+          method = read_yaml yaml
+          name = method["full_name"]
+          ext_path = f
+          ext_path = "gem #{$1}" if f =~ %r%gems/[\d.]+/doc/([^/]+)%
+          method["source_path"] = ext_path unless system_file
+          cache[name] = method
+        end
+      end
+
+      write_cache cache, path
+    end
+  end
+
+  def map_dirs(file_name, system=false)
+    dirs = if system == :all then
+             @all_dirs
+           else
+             if system then
+               @sys_dirs
+             else
+               @all_dirs - @sys_dirs
+             end
+           end
+
+    dirs.map { |dir| yield File.join(dir, file_name) }.flatten.compact
+  end
+
+  def populate_class_cache(class_cache, classes, extension = false)
+    classes.each do |cdesc|
+      desc = read_yaml cdesc
+      klassname = desc["full_name"]
+
+      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]
+
+        if extension then
+          desc["instance_method_extensions"] = desc.delete "instance_methods"
+          desc["class_method_extensions"] = desc.delete "class_methods"
+        end
+
+        klass.merge_enums desc
+        klass["sources"] << cdesc
+      end
+    end
+  end
+
+  def read_yaml(path)
+    data = File.read path
+    data = data.gsub(/ \!ruby\/(object|struct):(RDoc::RI|RI).*/, '')
+    data = data.gsub(/ \!ruby\/(object|struct):SM::(\S+)/,
+                     ' !ruby/\1:RDoc::Markup::\2')
+    YAML.load data
+  end
+
+  def get_info_for(arg)
+    @names = [arg]
+    run
+  end
+
+  def run
+    if @names.empty? then
+      @display.list_known_classes class_cache.keys.sort
+    else
+      @names.each do |name|
+        case name
+        when /::|\#|\./ then
+          if class_cache.key? name then
+            display_class name
+          else
+            meth = nil
+
+            parts = name.split(/::|\#|\./)
+            meth = parts.pop unless parts.last =~ /^[A-Z]/
+            klass = parts.join '::'
+
+            cache = load_cache_for klass
+            # HACK Does not support F.n
+            abort "Nothing known about #{name}" unless cache
+            method = cache[name.gsub(/\./, '#')]
+            abort "Nothing known about #{name}" unless method
+            @display.display_method_info method
+          end
+        else
+          if class_cache.key? name then
+            display_class name
+          else
+            methods = select_methods(/^#{name}/)
+            if methods.size == 0
+              abort "Nothing known about #{name}"
+            elsif methods.size == 1
+              @display.display_method_info methods.first
+            else
+              @display.display_method_list methods
+            end
+          end
+        end
+      end
+    end
+  end
+
+  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 write_cache(cache, path)
+    File.open path, "wb" do |cache_file|
+      Marshal.dump cache, cache_file
+    end
+
+    cache
+  end
+
+end
+
+class Hash # HACK don't add stuff to Hash.
+  def method_missing method, *args
+    self[method.to_s]
+  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].merge! v
+        else
+          # do nothing
+        end
+      else
+        self[k] = v
+      end
+    end
+  end
+end
+