rdoc 2.0.0

data/lib/rdoc/ri/paths.rb

@@ -0,0 +1,102 @@
+require 'rdoc/ri'
+
+##
+# Encapsulate all the strangeness to do with finding out where to find RDoc
+# files
+#
+# We basically deal with three directories:
+#
+# 1. The 'system' documentation directory, which holds the documentation
+#    distributed with Ruby, and which is managed by the Ruby install process
+# 2. The 'site' directory, which contains site-wide documentation added
+#    locally.
+# 3. The 'user' documentation directory, stored under the user's own home
+#    directory.
+#
+# There's contention about all this, but for now:
+#
+# system:: $datadir/ri/<ver>/system/...
+# site::   $datadir/ri/<ver>/site/...
+# user::   ~/.rdoc
+
+module RDoc::RI::Paths
+
+  #:stopdoc:
+  require 'rbconfig'
+
+  DOC_DIR  = "doc/rdoc"
+
+  version = RbConfig::CONFIG['ruby_version']
+
+  base    = File.join(RbConfig::CONFIG['datadir'], "ri", version)
+  SYSDIR  = File.join(base, "system")
+  SITEDIR = File.join(base, "site")
+  homedir = ENV['HOME'] || ENV['USERPROFILE'] || ENV['HOMEPATH']
+
+  if homedir then
+    HOMEDIR = File.join(homedir, ".rdoc")
+  else
+    HOMEDIR = nil
+  end
+
+  # This is the search path for 'ri'
+  PATH = [ SYSDIR, SITEDIR, HOMEDIR ].find_all {|p| p && File.directory?(p)}
+
+  begin
+    require 'rubygems' unless defined?(Gem) and defined?(Gem::Enable) and
+                              Gem::Enable
+
+    # HACK dup'd from Gem.latest_partials and friends
+    all_paths = []
+
+    all_paths = Gem.path.map do |dir|
+      Dir[File.join(dir, 'doc', '*', 'ri')]
+    end.flatten
+
+    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]
+        end
+      end
+    end
+
+    GEMDIRS = ri_paths.map { |k,v| v.last }.sort
+    GEMDIRS.each { |dir| PATH << dir }
+  rescue LoadError
+    GEMDIRS = []
+  end
+
+  # Returns the selected documentation directories as an Array, or PATH if no
+  # overriding directories were given.
+
+  def self.path(use_system, use_site, use_home, use_gems, *extra_dirs)
+    path = raw_path(use_system, use_site, use_home, use_gems, *extra_dirs)
+    return path.select { |directory| File.directory? directory }
+  end
+
+  # Returns the selected documentation directories including nonexistent
+  # directories.  Used to print out what paths were searched if no ri was
+  # found.
+
+  def self.raw_path(use_system, use_site, use_home, use_gems, *extra_dirs)
+    return PATH unless use_system or use_site or use_home or use_gems or
+                       not extra_dirs.empty?
+
+    path = []
+    path << extra_dirs unless extra_dirs.empty?
+    path << SYSDIR if use_system
+    path << SITEDIR if use_site
+    path << HOMEDIR if use_home
+    path << GEMDIRS if use_gems
+
+    return path.flatten.compact
+  end
+
+end
+

data/lib/rdoc/ri/reader.rb

@@ -0,0 +1,106 @@
+require 'rdoc/ri'
+require 'rdoc/ri/descriptions'
+require 'rdoc/ri/writer'
+require 'rdoc/markup/to_flow'
+
+class RDoc::RI::Reader
+
+  def initialize(ri_cache)
+    @cache = ri_cache
+  end
+
+  def top_level_namespace
+    [ @cache.toplevel ]
+  end
+
+  def lookup_namespace_in(target, namespaces)
+    result = []
+    for n in namespaces
+      result.concat(n.contained_modules_matching(target))
+    end
+    result
+  end
+
+  def find_class_by_name(full_name)
+    names = full_name.split(/::/)
+    ns = @cache.toplevel
+    for name in names
+      ns = ns.contained_class_named(name)
+      return nil if ns.nil?
+    end
+    get_class(ns)
+  end
+
+  def find_methods(name, is_class_method, namespaces)
+    result = []
+    namespaces.each do |ns|
+      result.concat ns.methods_matching(name, is_class_method)
+    end
+    result
+  end
+
+  ##
+  # Return the MethodDescription for a given MethodEntry by deserializing the
+  # YAML
+
+  def get_method(method_entry)
+    path = method_entry.path_name
+    File.open(path) { |f| RI::Description.deserialize(f) }
+  end
+
+  ##
+  # Return a class description
+
+  def get_class(class_entry)
+    result = nil
+    for path in class_entry.path_names
+      path = RiWriter.class_desc_path(path, class_entry)
+      desc = File.open(path) {|f| RI::Description.deserialize(f) }
+      if result
+        result.merge_in(desc)
+      else
+        result = desc
+      end
+    end
+    result
+  end
+
+  ##
+  # Return the names of all classes and modules
+
+  def full_class_names
+    res = []
+    find_classes_in(res, @cache.toplevel)
+  end
+
+  ##
+  # Return a list of all classes, modules, and methods
+
+  def all_names
+    res = []
+    find_names_in(res, @cache.toplevel)
+  end
+
+  private
+
+  def find_classes_in(res, klass)
+    classes = klass.classes_and_modules
+    for c in classes
+      res << c.full_name
+      find_classes_in(res, c)
+    end
+    res
+  end
+
+  def find_names_in(res, klass)
+    classes = klass.classes_and_modules
+    for c in classes
+      res << c.full_name
+      res.concat c.all_method_names
+      find_names_in(res, c)
+    end
+    res
+  end
+
+end
+

data/lib/rdoc/ri/util.rb

@@ -0,0 +1,81 @@
+require 'rdoc/ri'
+
+class RDoc::RI::Error < RuntimeError; end
+
+##
+# Break argument into its constituent class or module names, an
+# optional method type, and a method name
+
+class RDoc::RI::NameDescriptor
+
+  attr_reader :class_names
+  attr_reader :method_name
+
+  ##
+  # true and false have the obvious meaning. nil means we don't care
+
+  attr_reader :is_class_method
+
+  ##
+  # +arg+ may be
+  #
+  # 1. A class or module name (optionally qualified with other class or module
+  #    names (Kernel, File::Stat etc)
+  # 2. A method name
+  # 3. A method name qualified by a optionally fully qualified class or module
+  #    name
+  #
+  # We're fairly casual about delimiters: folks can say Kernel::puts,
+  # Kernel.puts, or Kernel\#puts for example. There's one exception: if you
+  # say IO::read, we look for a class method, but if you say IO.read, we look
+  # for an instance method
+
+  def initialize(arg)
+    @class_names = []
+    separator = nil
+
+    tokens = arg.split(/(\.|::|#)/)
+
+    # Skip leading '::', '#' or '.', but remember it might
+    # be a method name qualifier
+    separator = tokens.shift if tokens[0] =~ /^(\.|::|#)/
+
+    # Skip leading '::', but remember we potentially have an inst
+
+    # leading stuff must be class names
+
+    while tokens[0] =~ /^[A-Z]/
+      @class_names << tokens.shift
+      unless tokens.empty?
+        separator = tokens.shift
+        break unless separator == "::"
+      end
+    end
+
+    # Now must have a single token, the method name, or an empty array
+    unless tokens.empty?
+      @method_name = tokens.shift
+      # We may now have a trailing !, ?, or = to roll into
+      # the method name
+      if !tokens.empty? && tokens[0] =~ /^[!?=]$/
+        @method_name << tokens.shift
+      end
+
+      if @method_name =~ /::|\.|#/ or !tokens.empty?
+        raise RDoc::RI::Error.new("Bad argument: #{arg}") 
+      end
+      if separator && separator != '.'
+        @is_class_method = separator == "::"
+      end
+    end
+  end
+
+  # Return the full class name (with '::' between the components) or "" if
+  # there's no class name
+
+  def full_class_name
+    @class_names.join("::")
+  end
+
+end
+

data/lib/rdoc/ri/writer.rb

@@ -0,0 +1,68 @@
+require 'fileutils'
+require 'rdoc/ri'
+
+class RDoc::RI::Writer
+
+  def self.class_desc_path(dir, class_desc)
+    File.join(dir, "cdesc-" + class_desc.name + ".yaml")
+  end
+
+  ##
+  # Convert a name from internal form (containing punctuation) to an external
+  # form (where punctuation is replaced by %xx)
+
+  def self.internal_to_external(name)
+    if ''.respond_to? :ord then
+      name.gsub(/\W/) { "%%%02x" % $&[0].ord }
+    else
+      name.gsub(/\W/) { "%%%02x" % $&[0] }
+    end
+  end
+
+  ##
+  # And the reverse operation
+
+  def self.external_to_internal(name)
+    name.gsub(/%([0-9a-f]{2,2})/) { $1.to_i(16).chr }
+  end
+
+  def initialize(base_dir)
+    @base_dir = base_dir
+  end
+
+  def remove_class(class_desc)
+    FileUtils.rm_rf(path_to_dir(class_desc.full_name))
+  end
+
+  def add_class(class_desc)
+    dir = path_to_dir(class_desc.full_name)
+    FileUtils.mkdir_p(dir)
+    class_file_name = self.class.class_desc_path(dir, class_desc)
+    File.open(class_file_name, "w") do |f|
+      f.write(class_desc.serialize)
+    end
+  end
+
+  def add_method(class_desc, method_desc)
+    dir = path_to_dir(class_desc.full_name)
+    file_name = self.class.internal_to_external(method_desc.name)
+    meth_file_name = File.join(dir, file_name)
+    if method_desc.is_singleton
+      meth_file_name += "-c.yaml"
+    else
+      meth_file_name += "-i.yaml"
+    end
+
+    File.open(meth_file_name, "w") do |f|
+      f.write(method_desc.serialize)
+    end
+  end
+
+  private
+
+  def path_to_dir(class_name)
+    File.join(@base_dir, *class_name.split('::'))
+  end
+
+end
+

data/lib/rdoc/stats.rb

@@ -0,0 +1,25 @@
+require 'rdoc'
+
+##
+# Simple stats collector
+
+class RDoc::Stats
+
+  attr_accessor :num_files, :num_classes, :num_modules, :num_methods
+
+  def initialize
+    @num_files = @num_classes = @num_modules = @num_methods = 0
+    @start = Time.now
+  end
+
+  def print
+    puts "Files:   #@num_files"
+    puts "Classes: #@num_classes"
+    puts "Modules: #@num_modules"
+    puts "Methods: #@num_methods"
+    puts "Elapsed: " + sprintf("%0.3fs", Time.now - @start)
+  end
+
+end
+
+

data/lib/rdoc/template.rb

@@ -0,0 +1,64 @@
+require 'erb'
+
+module RDoc; end
+
+##
+# An ERb wrapper that allows nesting of one ERb template inside another.
+#
+# This TemplatePage operates similarly to RDoc 1.x's TemplatePage, but uses
+# ERb instead of a custom template language.
+#
+# Converting from a RDoc 1.x template to an RDoc 2.x template is fairly easy.
+#
+# * %blah% becomes <%= values["blah"] %>
+# * !INCLUDE! becomes <%= template_include %>
+# * HREF:aref:name becomes <%= href values["aref"], values["name"] %>
+# * IF:blah becomes <% if values["blah"] then %>
+# * IFNOT:blah becomes <% unless values["blah"] then %>
+# * ENDIF:blah becomes <% end %>
+# * START:blah becomes <% values["blah"].each do |blah| %>
+# * END:blah becomes <% end %>
+#
+# To make nested loops easier to convert, start by converting START statements
+# to:
+#
+#   <% values["blah"].each do |blah| $stderr.puts blah.keys %>
+#
+# So you can see what is being used inside which loop.
+
+class RDoc::TemplatePage
+
+  ##
+  # Create a new TemplatePage that will use +templates+.
+
+  def initialize(*templates)
+    @templates = templates
+  end
+
+  ##
+  # Returns "<a href=\"#{ref}\">#{name}</a>"
+
+  def href(ref, name)
+    if ref then
+      "<a href=\"#{ref}\">#{name}</a>"
+    else
+      name
+    end
+  end
+
+  ##
+  # Process the template using +values+, writing the result to +io+.
+
+  def write_html_on(io, values)
+    b = binding
+    template_include = ""
+
+    @templates.reverse_each do |template|
+      template_include = ERB.new(template).result b
+    end
+
+    io.write template_include
+  end
+
+end
+