rdoc 3.1 → 6.3.3

data/lib/rdoc/ri/formatter.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 ##
 # For RubyGems backwards compatibility
 

data/lib/rdoc/ri/paths.rb

@@ -1,7 +1,9 @@
-require 'rdoc/ri'
+# frozen_string_literal: true
+require_relative '../rdoc'
 
 ##
-# The directories where ri data lives.
+# The directories where ri data lives.  Paths can be enumerated via ::each, or
+# queried individually via ::system_dir, ::site_dir, ::home_dir and ::gem_dir.
 
 module RDoc::RI::Paths
 
@@ -10,30 +12,11 @@ module RDoc::RI::Paths
 
   version = RbConfig::CONFIG['ruby_version']
 
-  base    = if RbConfig::CONFIG.key? 'ridir' then
-              File.join RbConfig::CONFIG['ridir'], version
-            else
-              File.join RbConfig::CONFIG['datadir'], 'ri', version
-            end
+  BASE    = File.join RbConfig::CONFIG['ridir'], version
 
-  SYSDIR  = File.join base, "system"
-  SITEDIR = File.join base, "site"
-
-  homedir = begin
-              File.expand_path('~')
-            rescue ArgumentError
-            end
-
-  homedir ||= ENV['HOME'] ||
-              ENV['USERPROFILE'] || ENV['HOMEPATH'] # for 1.8 compatibility
-
-  HOMEDIR = if homedir then
-              File.join homedir, ".rdoc"
-            end
+  HOMEDIR = RDoc.home
   #:startdoc:
 
-  @gemdirs = nil
-
   ##
   # Iterates over each selected path yielding the directory and type.
   #
@@ -47,16 +30,19 @@ module RDoc::RI::Paths
   # :extra:: ri data directory from the command line.  Yielded for each
   #          entry in +extra_dirs+
 
-  def self.each system, site, home, gems, *extra_dirs # :yields: directory, type
+  def self.each system = true, site = true, home = true, gems = :latest, *extra_dirs # :yields: directory, type
+    return enum_for __method__, system, site, home, gems, *extra_dirs unless
+      block_given?
+
     extra_dirs.each do |dir|
       yield dir, :extra
     end
 
-    yield SYSDIR,  :system if system
-    yield SITEDIR, :site   if site
-    yield HOMEDIR, :home   if home and HOMEDIR
+    yield system_dir,  :system if system
+    yield site_dir,    :site   if site
+    yield home_dir,    :home   if home and HOMEDIR
 
-    gemdirs.each do |dir|
+    gemdirs(gems).each do |dir|
       yield dir, :gem
     end if gems
 
@@ -64,36 +50,70 @@ module RDoc::RI::Paths
   end
 
   ##
-  # The latest installed gems' ri directories
+  # The ri directory for the gem with +gem_name+.
 
-  def self.gemdirs
-    return @gemdirs if @gemdirs
+  def self.gem_dir name, version
+    req = Gem::Requirement.new "= #{version}"
 
-    require 'rubygems' unless defined?(Gem)
+    spec = Gem::Specification.find_by_name name, req
 
-    # HACK dup'd from Gem.latest_partials and friends
-    all_paths = []
+    File.join spec.doc_dir, 'ri'
+  end
 
-    all_paths = Gem.path.map do |dir|
-      Dir[File.join(dir, 'doc', '*', 'ri')]
-    end.flatten
+  ##
+  # The latest installed gems' ri directories.  +filter+ can be :all or
+  # :latest.
+  #
+  # A +filter+ :all includes all versions of gems and includes gems without
+  # ri documentation.
 
+  def self.gemdirs filter = :latest
     ri_paths = {}
 
-    all_paths.each do |dir|
-      base = File.basename File.dirname(dir)
-      if base =~ /(.*)-((\d+\.)*\d+)/ then
-        name, version = $1, $2
-        ver = Gem::Version.new version
-        if ri_paths[name].nil? or ver > ri_paths[name][0] then
-          ri_paths[name] = [ver, dir]
+    all = Gem::Specification.map do |spec|
+      [File.join(spec.doc_dir, 'ri'), spec.name, spec.version]
+    end
+
+    if filter == :all then
+      gemdirs = []
+
+      all.group_by do |_, name, _|
+        name
+      end.sort_by do |group, _|
+        group
+      end.map do |group, items|
+        items.sort_by do |_, _, version|
+          version
+        end.reverse_each do |dir,|
+          gemdirs << dir
         end
       end
+
+      return gemdirs
+    end
+
+    all.each do |dir, name, ver|
+      next unless File.exist? dir
+
+      if ri_paths[name].nil? or ver > ri_paths[name].first then
+        ri_paths[name] = [ver, name, dir]
+      end
     end
 
-    @gemdirs = ri_paths.map { |k,v| v.last }.sort
+    ri_paths.sort_by { |_, (_, name, _)| name }.map { |k, v| v.last }
   rescue LoadError
-    @gemdirs = []
+    []
+  end
+
+  ##
+  # The location of the rdoc data in the user's home directory.
+  #
+  # Like ::system, ri data in the user's home directory is rare and predates
+  # libraries distributed via RubyGems.  ri data is rarely generated into this
+  # directory.
+
+  def self.home_dir
+    HOMEDIR
   end
 
   ##
@@ -102,7 +122,7 @@ module RDoc::RI::Paths
   #
   # See also ::each
 
-  def self.path(system, site, home, gems, *extra_dirs)
+  def self.path(system = true, site = true, home = true, gems = :latest, *extra_dirs)
     path = raw_path system, site, home, gems, *extra_dirs
 
     path.select { |directory| File.directory? directory }
@@ -124,5 +144,28 @@ module RDoc::RI::Paths
     path.compact
   end
 
-end
+  ##
+  # The location of ri data installed into the site dir.
+  #
+  # Historically this was available for documentation installed by Ruby
+  # libraries predating RubyGems.  It is unlikely to contain any content for
+  # modern Ruby installations.
 
+  def self.site_dir
+    File.join BASE, 'site'
+  end
+
+  ##
+  # The location of the built-in ri data.
+  #
+  # This data is built automatically when `make` is run when Ruby is
+  # installed.  If you did not install Ruby by hand you may need to install
+  # the documentation yourself.  Please consult the documentation for your
+  # package manager or Ruby installer for details.  You can also use the
+  # rdoc-data gem to install system ri data for common versions of Ruby.
+
+  def self.system_dir
+    File.join BASE, 'system'
+  end
+
+end

data/lib/rdoc/ri/store.rb

@@ -1,265 +1,7 @@
-require 'rdoc/code_objects'
-require 'fileutils'
+# frozen_string_literal: true
+module RDoc::RI
 
-##
-# A set of ri data.
-#
-# The store manages reading and writing ri data for a project (gem, path,
-# etc.) and maintains a cache of methods, classes and ancestors in the
-# store.
-
-class RDoc::RI::Store
-
-  ##
-  # If true this Store will not write any files
-
-  attr_accessor :dry_run
-
-  ##
-  # Path this store reads or writes
-
-  attr_accessor :path
-
-  ##
-  # Type of ri datastore this was loaded from.  See RDoc::RI::Driver,
-  # RDoc::RI::Paths.
-
-  attr_accessor :type
-
-  ##
-  # The contents of the Store
-
-  attr_reader :cache
-
-  ##
-  # Creates a new Store of +type+ that will load or save to +path+
-
-  def initialize path, type = nil
-    @dry_run = false
-    @type    = type
-    @path    = path
-
-    @cache = {
-      :class_methods    => {},
-      :instance_methods => {},
-      :attributes       => {},
-      :modules          => [],
-      :ancestors        => {},
-    }
-  end
-
-  ##
-  # Ancestors cache accessor.  Maps a klass name to an Array of its ancestors
-  # in this store.  If Foo in this store inherits from Object, Kernel won't be
-  # listed (it will be included from ruby's ri store).
-
-  def ancestors
-    @cache[:ancestors]
-  end
-
-  ##
-  # Attributes cache accessor.  Maps a class to an Array of its attributes.
-
-  def attributes
-    @cache[:attributes]
-  end
-
-  ##
-  # Path to the cache file
-
-  def cache_path
-    File.join @path, 'cache.ri'
-  end
-
-  ##
-  # Path to the ri data for +klass_name+
-
-  def class_file klass_name
-    name = klass_name.split('::').last
-    File.join class_path(klass_name), "cdesc-#{name}.ri"
-  end
-
-  ##
-  # Class methods cache accessor.  Maps a class to an Array of its class
-  # methods (not full name).
-
-  def class_methods
-    @cache[:class_methods]
-  end
-
-  ##
-  # Path where data for +klass_name+ will be stored (methods or class data)
-
-  def class_path klass_name
-    File.join @path, *klass_name.split('::')
-  end
-
-  ##
-  # Friendly rendition of #path
-
-  def friendly_path
-    case type
-    when :gem    then
-      sep = Regexp.union(*['/', File::ALT_SEPARATOR].compact)
-      @path =~ /#{sep}doc#{sep}(.*?)#{sep}ri$/
-      "gem #{$1}"
-    when :home   then '~/.ri'
-    when :site   then 'ruby site'
-    when :system then 'ruby core'
-    else @path
-    end
-  end
-
-  def inspect # :nodoc:
-    "#<%s:0x%x %s %p>" % [self.class, object_id, @path, modules.sort]
-  end
-
-  ##
-  # Instance methods cache accessor.  Maps a class to an Array of its
-  # instance methods (not full name).
-
-  def instance_methods
-    @cache[:instance_methods]
-  end
-
-  ##
-  # Loads cache file for this store
-
-  def load_cache
-    open cache_path, 'rb' do |io|
-      @cache = Marshal.load io.read
-    end
-  rescue Errno::ENOENT
-  end
-
-  ##
-  # Loads ri data for +klass_name+
-
-  def load_class klass_name
-    open class_file(klass_name), 'rb' do |io|
-      Marshal.load io.read
-    end
-  end
-
-  ##
-  # Loads ri data for +method_name+ in +klass_name+
-
-  def load_method klass_name, method_name
-    open method_file(klass_name, method_name), 'rb' do |io|
-      Marshal.load io.read
-    end
-  end
-
-  ##
-  # Path to the ri data for +method_name+ in +klass_name+
-
-  def method_file klass_name, method_name
-    method_name = method_name.split('::').last
-    method_name =~ /#(.*)/
-    method_type = $1 ? 'i' : 'c'
-    method_name = $1 if $1
-
-    method_name = if ''.respond_to? :ord then
-                    method_name.gsub(/\W/) { "%%%02x" % $&[0].ord }
-                  else
-                    method_name.gsub(/\W/) { "%%%02x" % $&[0] }
-                  end
-
-    File.join class_path(klass_name), "#{method_name}-#{method_type}.ri"
-  end
-
-  ##
-  # Modules cache accessor.  An Array of all the modules (and classes) in the
-  # store.
-
-  def modules
-    @cache[:modules]
-  end
-
-  ##
-  # Writes the cache file for this store
-
-  def save_cache
-    # HACK mongrel-1.1.5 documents its files twice
-    @cache[:ancestors].       each do |_, m| m.uniq!; m.sort! end
-    @cache[:attributes].      each do |_, m| m.uniq!; m.sort! end
-    @cache[:class_methods].   each do |_, m| m.uniq!; m.sort! end
-    @cache[:instance_methods].each do |_, m| m.uniq!; m.sort! end
-    @cache[:modules].uniq!; @cache[:modules].sort!
-
-    return if @dry_run
-
-    open cache_path, 'wb' do |io|
-      Marshal.dump @cache, io
-    end
-  end
-
-  ##
-  # Writes the ri data for +klass+
-
-  def save_class klass
-    FileUtils.mkdir_p class_path(klass.full_name) unless @dry_run
-
-    @cache[:modules] << klass.full_name
-
-    path = class_file klass.full_name
-
-    begin
-      disk_klass = nil
-
-      open path, 'rb' do |io|
-        disk_klass = Marshal.load io.read
-      end
-
-      klass.merge disk_klass
-    rescue Errno::ENOENT
-    end
-
-    # BasicObject has no ancestors
-    ancestors = klass.ancestors.compact.map do |ancestor|
-      # HACK for classes we don't know about (class X < RuntimeError)
-      String === ancestor ? ancestor : ancestor.full_name
-    end
-
-    @cache[:ancestors][klass.full_name] ||= []
-    @cache[:ancestors][klass.full_name].push(*ancestors)
-
-    attributes = klass.attributes.map do |attribute|
-      "#{attribute.definition} #{attribute.name}"
-    end
-
-    unless attributes.empty? then
-      @cache[:attributes][klass.full_name] ||= []
-      @cache[:attributes][klass.full_name].push(*attributes)
-    end
-
-    return if @dry_run
-
-    open path, 'wb' do |io|
-      Marshal.dump klass, io
-    end
-  end
-
-  ##
-  # Writes the ri data for +method+ on +klass+
-
-  def save_method klass, method
-    FileUtils.mkdir_p class_path(klass.full_name) unless @dry_run
-
-    cache = if method.singleton then
-              @cache[:class_methods]
-            else
-              @cache[:instance_methods]
-            end
-    cache[klass.full_name] ||= []
-    cache[klass.full_name] << method.name
-
-    return if @dry_run
-
-    open method_file(klass.full_name, method.full_name), 'wb' do |io|
-      Marshal.dump method, io
-    end
-  end
+  Store = RDoc::Store # :nodoc:
 
 end
 

data/lib/rdoc/ri/task.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+begin
+  gem 'rdoc'
+rescue Gem::LoadError
+end unless defined?(RDoc)
+
+require_relative '../task'
+
+##
+# RDoc::RI::Task creates ri data in <code>./.rdoc</code> for your project.
+#
+# It contains the following tasks:
+#
+# [ri]
+#   Build ri data
+#
+# [clobber_ri]
+#   Delete ri data files.  This target is automatically added to the main
+#   clobber target.
+#
+# [reri]
+#   Rebuild the ri data from scratch even if they are not out of date.
+#
+# Simple example:
+#
+#   require 'rdoc/ri/task'
+#
+#   RDoc::RI::Task.new do |ri|
+#     ri.main = 'README.rdoc'
+#     ri.rdoc_files.include 'README.rdoc', 'lib/**/*.rb'
+#   end
+#
+# For further configuration details see RDoc::Task.
+
+class RDoc::RI::Task < RDoc::Task
+
+  DEFAULT_NAMES = { # :nodoc:
+    :clobber_rdoc => :clobber_ri,
+    :rdoc         => :ri,
+    :rerdoc       => :reri,
+  }
+
+  ##
+  # Create an ri task with the given name. See RDoc::Task for documentation on
+  # setting names.
+
+  def initialize name = DEFAULT_NAMES # :yield: self
+    super
+  end
+
+  def clobber_task_description # :nodoc:
+    "Remove RI data files"
+  end
+
+  ##
+  # Sets default task values
+
+  def defaults
+    super
+
+    @rdoc_dir = '.rdoc'
+  end
+
+  def rdoc_task_description # :nodoc:
+    'Build RI data files'
+  end
+
+  def rerdoc_task_description # :nodoc:
+    'Rebuild RI data files'
+  end
+end

data/lib/rdoc/ri.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'rdoc'
 
 ##
@@ -12,7 +13,9 @@ module RDoc::RI
 
   class Error < RDoc::Error; end
 
-end
+  autoload :Driver, 'rdoc/ri/driver'
+  autoload :Paths,  'rdoc/ri/paths'
+  autoload :Store,  'rdoc/ri/store'
 
-require 'rdoc/ri/store'
+end