voloko-sdoc 0.1.2 → 0.1.3

data/rdoc/lib/rdoc/ri/paths.rb

@@ -0,0 +1,93 @@
+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
+
+  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
+  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)
+    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/rdoc/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| RDoc::RI::Description.deserialize(f) }
+  end
+
+  ##
+  # Return a class description
+
+  def get_class(class_entry)
+    result = nil
+    for path in class_entry.path_names
+      path = RDoc::RI::Writer.class_desc_path(path, class_entry)
+      desc = File.open(path) {|f| RDoc::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/rdoc/lib/rdoc/ri/util.rb

@@ -0,0 +1,79 @@
+require 'rdoc/ri'
+
+##
+# 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/rdoc/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/rdoc/lib/rdoc/ri.rb

@@ -0,0 +1,8 @@
+require 'rdoc'
+
+module RDoc::RI
+
+  class Error < RDoc::Error; end
+
+end
+

data/rdoc/lib/rdoc/single_class.rb

@@ -0,0 +1,8 @@
+require 'rdoc/class_module'
+
+##
+# A singleton class
+
+class RDoc::SingleClass < RDoc::ClassModule
+end
+

data/rdoc/lib/rdoc/stats.rb

@@ -0,0 +1,178 @@
+require 'rdoc'
+require 'thread'
+
+##
+# Simple stats collector
+
+class RDoc::Stats
+
+  attr_reader :num_classes
+  attr_reader :num_files
+  attr_reader :num_methods
+  attr_reader :num_modules
+  attr_reader :total_files
+
+  def initialize(total_files, verbosity = 1)
+    @lock = Mutex.new
+    
+    @num_classes = 0
+    @num_files   = 0
+    @num_methods = 0
+    @num_modules = 0
+    @total_files = total_files
+
+    @start = Time.now
+
+    @display = case verbosity
+               when 0 then Quiet.new
+               when 1 then Normal.new(total_files)
+               else        Verbose.new
+               end
+  end
+  
+  def begin_adding(number_of_workers)
+    @display.begin_adding(number_of_workers)
+  end
+
+  def add_alias(as)
+    @lock.synchronize do
+      @display.print_alias as
+      @num_methods += 1
+    end
+  end
+
+  def add_class(klass)
+    @lock.synchronize do
+      @display.print_class klass
+      @num_classes += 1
+    end
+  end
+
+  def add_file(file)
+    @lock.synchronize do
+      @display.print_file @num_files, file
+      @num_files += 1
+    end
+  end
+
+  def add_method(method)
+    @lock.synchronize do
+      @display.print_method method
+      @num_methods += 1
+    end
+  end
+
+  def add_module(mod)
+    @lock.synchronize do
+      @display.print_module mod
+      @num_modules += 1
+    end
+  end
+  
+  def done_adding
+    @lock.synchronize do
+      @display.done_adding
+    end
+  end
+
+  def print
+    puts "Files:   #@num_files"
+    puts "Classes: #@num_classes"
+    puts "Modules: #@num_modules"
+    puts "Methods: #@num_methods"
+    puts "Elapsed: " + sprintf("%0.1fs", Time.now - @start)
+  end
+
+  class Quiet
+    def begin_adding(*) end
+    def print_alias(*) end
+    def print_class(*) end
+    def print_file(*) end
+    def print_method(*) end
+    def print_module(*) end
+    def done_adding(*) end
+  end
+  
+  class Normal
+    def initialize(total_files)
+      @total_files = total_files
+    end
+    
+    def begin_adding(number_of_workers)
+      puts "Parsing sources with #{number_of_workers} thread(s)..."
+    end
+    
+    def print_file(files_so_far, filename)
+      progress_bar = sprintf("%3d%% [%2d/%2d]  ",
+                             100 * (files_so_far + 1) / @total_files,
+                             files_so_far + 1,
+                             @total_files)
+      
+      if $stdout.tty?
+        # Print a progress bar, but make sure it fits on a single line. Filename
+        # will be truncated if necessary.
+        terminal_width = (ENV['COLUMNS'] || 80).to_i
+        max_filename_size = terminal_width - progress_bar.size
+        if filename.size > max_filename_size
+          # Turn "some_long_filename.rb" to "...ong_filename.rb"
+          filename = filename[(filename.size - max_filename_size) .. -1]
+          filename[0..2] = "..."
+        end
+        
+        # Pad the line with whitespaces so that leftover output from the
+        # previous line doesn't show up.
+        line = "#{progress_bar}#{filename}"
+        padding = terminal_width - line.size
+        if padding > 0
+          line << (" " * padding)
+        end
+        
+        $stdout.print("#{line}\r")
+        $stdout.flush
+      else
+        puts "#{progress_bar} #{filename}"
+      end
+    end
+    
+    def done_adding
+      puts "\n"
+    end
+
+    def print_alias(*) end
+    def print_class(*) end
+    def print_method(*) end
+    def print_module(*) end
+  end
+
+  class Verbose
+    def begin_adding(number_of_workers)
+      puts "Parsing sources with #{number_of_workers} thread(s)..."
+    end
+    
+    def print_alias(as)
+      puts "\t\talias #{as.new_name} #{as.old_name}"
+    end
+
+    def print_class(klass)
+      puts "\tclass #{klass.full_name}"
+    end
+
+    def print_file(files_so_far, file)
+      puts file
+    end
+
+    def print_method(method)
+      puts "\t\t#{method.singleton ? '::' : '#'}#{method.name}"
+    end
+
+    def print_module(mod)
+      puts "\tmodule #{mod.full_name}"
+    end
+    
+    def done_adding
+    end
+  end
+
+end
+
+