voloko-sdoc 0.1.2 → 0.1.3

data/rdoc/lib/rdoc/ri/cache.rb

@@ -0,0 +1,187 @@
+require 'rdoc/ri'
+
+class RDoc::RI::ClassEntry
+
+  attr_reader :name
+  attr_reader :path_names
+
+  def initialize(path_name, name, in_class)
+    @path_names = [ path_name ]
+    @name = name
+    @in_class = in_class
+    @class_methods    = []
+    @instance_methods = []
+    @inferior_classes = []
+  end
+
+  # We found this class in more than one place, so add
+  # in the name from there.
+  def add_path(path)
+    @path_names << path
+  end
+
+  ##
+  # read in our methods and any classes and modules in our namespace. Methods
+  # are stored in files called name-c|i.yaml, where the 'name' portion is the
+  # external form of the method name and the c|i is a class|instance flag
+
+  def load_from(dir)
+    return unless File.exist? dir
+
+    Dir.foreach(dir) do |name|
+      next if name =~ /^\./
+
+      # convert from external to internal form, and
+      # extract the instance/class flag
+
+      if name =~ /^(.*?)-(c|i).yaml$/
+        external_name = $1
+        is_class_method = $2 == "c"
+        internal_name = RDoc::RI::Writer.external_to_internal(external_name)
+        list = is_class_method ? @class_methods : @instance_methods
+        path = File.join(dir, name)
+        list << RDoc::RI::MethodEntry.new(path, internal_name, is_class_method, self)
+      else
+        full_name = File.join(dir, name)
+        if File.directory?(full_name)
+          inf_class = @inferior_classes.find {|c| c.name == name }
+          if inf_class
+            inf_class.add_path(full_name)
+          else
+            inf_class = RDoc::RI::ClassEntry.new(full_name, name, self)
+            @inferior_classes << inf_class
+          end
+          inf_class.load_from(full_name)
+        end
+      end
+    end
+  end
+
+  # Return a list of any classes or modules that we contain
+  # that match a given string
+
+  def contained_modules_matching(name)
+    @inferior_classes.find_all {|c| c.name[name]}
+  end
+
+  def classes_and_modules
+    @inferior_classes
+  end
+
+  # Return an exact match to a particular name
+  def contained_class_named(name)
+    @inferior_classes.find {|c| c.name == name}
+  end
+
+  # return the list of local methods matching name
+  # We're split into two because we need distinct behavior
+  # when called from the _toplevel_
+  def methods_matching(name, is_class_method)
+    local_methods_matching(name, is_class_method)
+  end
+
+  # Find methods matching 'name' in ourselves and in
+  # any classes we contain
+  def recursively_find_methods_matching(name, is_class_method)
+    res = local_methods_matching(name, is_class_method)
+    @inferior_classes.each do |c|
+      res.concat(c.recursively_find_methods_matching(name, is_class_method))
+    end
+    res
+  end
+
+
+  # Return our full name
+  def full_name
+    res = @in_class.full_name
+    res << "::" unless res.empty?
+    res << @name
+  end
+
+  # Return a list of all out method names
+  def all_method_names
+    res = @class_methods.map {|m| m.full_name }
+    @instance_methods.each {|m| res << m.full_name}
+    res
+  end
+
+  private
+
+  # Return a list of all our methods matching a given string.
+  # Is +is_class_methods+ if 'nil', we don't care if the method
+  # is a class method or not, otherwise we only return
+  # those methods that match
+  def local_methods_matching(name, is_class_method)
+
+    list = case is_class_method
+           when nil then  @class_methods + @instance_methods
+           when true then @class_methods
+           when false then @instance_methods
+           else fail "Unknown is_class_method: #{is_class_method.inspect}"
+           end
+
+    list.find_all {|m| m.name;  m.name[name]}
+  end
+end
+
+##
+# A TopLevelEntry is like a class entry, but when asked to search for methods
+# searches all classes, not just itself
+
+class RDoc::RI::TopLevelEntry < RDoc::RI::ClassEntry
+  def methods_matching(name, is_class_method)
+    res = recursively_find_methods_matching(name, is_class_method)
+  end
+
+  def full_name
+      ""
+  end
+
+  def module_named(name)
+
+  end
+
+end
+
+class RDoc::RI::MethodEntry
+  attr_reader :name
+  attr_reader :path_name
+
+  def initialize(path_name, name, is_class_method, in_class)
+    @path_name = path_name
+    @name = name
+    @is_class_method = is_class_method
+    @in_class = in_class
+  end
+
+  def full_name
+    res = @in_class.full_name
+    unless res.empty?
+      if @is_class_method
+        res << "::"
+      else
+        res << "#"
+      end
+    end
+    res << @name
+  end
+end
+
+##
+# We represent everything known about all 'ri' files accessible to this program
+
+class RDoc::RI::Cache
+
+  attr_reader :toplevel
+
+  def initialize(dirs)
+    # At the top level we have a dummy module holding the
+    # overall namespace
+    @toplevel = RDoc::RI::TopLevelEntry.new('', '::', nil)
+
+    dirs.each do |dir|
+      @toplevel.load_from(dir)
+    end
+  end
+
+end

data/rdoc/lib/rdoc/ri/descriptions.rb

@@ -0,0 +1,156 @@
+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 :class_method_extensions
+  attr_accessor :instance_methods
+  attr_accessor :instance_method_extensions
+  attr_accessor :attributes
+  attr_accessor :constants
+  attr_accessor :includes
+
+  # merge in another class description 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
+        if @comment.nil? or @comment.empty? then
+          @comment = old.comment
+        else
+          @comment << RDoc::Markup::Flow::RULE.new
+          @comment.concat old.comment
+        end
+      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
+  attr_accessor :source_path
+
+end
+

data/rdoc/lib/rdoc/ri/display.rb

@@ -0,0 +1,340 @@
+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
+
+  attr_reader :formatter
+
+  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)
+    page do
+      superclass = klass.superclass
+
+      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|
+          incs << inc.name
+        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|
+          @formatter.wrap "#{constant.name} = #{constant.value}"
+          if constant.comment then
+            @formatter.indent do
+              @formatter.display_flow constant.comment
+            end
+          else
+            @formatter.break_to_newline
+          end
+        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})"
+            @formatter.break_to_newline
+          end
+        end
+      end
+
+      return display_class_method_list(klass)
+    end
+  end
+
+  ##
+  # Given a Hash mapping a class' methods to method types (returned by
+  # display_class_method_list), this method allows the user to choose one of
+  # the methods.
+
+  def get_class_method_choice(method_map)
+  end
+
+  ##
+  # Display methods on +klass+.  Returns a hash mapping method name to method
+  # contents
+
+  def display_class_method_list(klass)
+    method_map = {}
+
+    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.nil? or data.empty? then
+        @formatter.blankline
+
+        heading = data_type.to_s.split('_').join(' ').capitalize << ':'
+        @formatter.display_heading heading, 2, ''
+
+        method_names = []
+        data.each do |item|
+          method_names << item.name
+
+          if(data_type == :class_methods ||
+             data_type == :class_method_extensions) then
+            method_map["::#{item.name}"] = :class
+            method_map[item.name] = :class
+          else
+            #
+            # Since we iterate over instance methods after class methods,
+            # an instance method always will overwrite the unqualified
+            # class method entry for a class method of the same name.
+            #
+            method_map["##{item.name}"] = :instance
+            method_map[item.name] = :instance
+          end
+        end
+        method_names.sort!
+
+        @formatter.wrap method_names.join(', ')
+      end
+    end
+
+    method_map
+  end
+  private :display_class_method_list
+
+  ##
+  # 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
+
+      methods.each do |method|
+        @formatter.raw_print_line "#{method.full_name} [#{method.source_path}]\n"
+      end
+    end
+  end
+
+  ##
+  # Display a list of +methods+ and allow the user to select one of them.
+
+  def display_method_list_choice(methods)
+    page do
+      @formatter.wrap "More than one method matched your request.  Please choose one of the possible matches."
+      @formatter.blankline
+
+      methods.each_with_index do |method, index|
+        @formatter.raw_print_line "%3d %s [%s]\n" % [index + 1, method.full_name, method.source_path]
+      end
+
+      @formatter.raw_print_line ">> "
+
+      choice = $stdin.gets.strip!
+
+      if(choice == '')
+        return
+      end
+
+      choice = choice.to_i
+
+      if ((choice == 0) || (choice > methods.size)) then
+        @formatter.raw_print_line "Invalid choice!\n"
+      else
+        method = methods[choice - 1]
+        display_method_info(method)
+      end
+    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
+
+    @formatter.blankline
+    @formatter.wrap("From #{method.source_path}")
+  end
+
+  ##
+  # List the classes in +classes+.
+
+  def list_known_classes(classes)
+    if classes.empty? then
+      warn_no_database
+    else
+      page do
+        @formatter.draw_line "Known classes and modules"
+        @formatter.blankline
+
+        classes.sort.each do |klass|
+          @formatter.wrap klass
+        end
+      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