horseman 0.0.2 → 0.0.3

data/vendor/ruby/1.9.1/gems/rdoc-3.12/lib/rdoc/top_level.rb

@@ -0,0 +1,523 @@
+##
+# A TopLevel context is a representation of the contents of a single file
+
+class RDoc::TopLevel < RDoc::Context
+
+  ##
+  # This TopLevel's File::Stat struct
+
+  attr_accessor :file_stat
+
+  ##
+  # Relative name of this file
+
+  attr_accessor :relative_name
+
+  ##
+  # Absolute name of this file
+
+  attr_accessor :absolute_name
+
+  ##
+  # All the classes or modules that were declared in
+  # this file. These are assigned to either +#classes_hash+
+  # or +#modules_hash+ once we know what they really are.
+
+  attr_reader :classes_or_modules
+
+  attr_accessor :diagram # :nodoc:
+
+  ##
+  # The parser that processed this file
+
+  attr_accessor :parser
+
+  ##
+  # Returns all classes discovered by RDoc
+
+  def self.all_classes
+    @all_classes_hash.values
+  end
+
+  ##
+  # Returns all classes and modules discovered by RDoc
+
+  def self.all_classes_and_modules
+    @all_classes_hash.values + @all_modules_hash.values
+  end
+
+  ##
+  # Hash of all classes known to RDoc
+
+  def self.all_classes_hash
+    @all_classes_hash
+  end
+
+  ##
+  # All TopLevels known to RDoc
+
+  def self.all_files
+    @all_files_hash.values
+  end
+
+  ##
+  # Hash of all files known to RDoc
+
+  def self.all_files_hash
+    @all_files_hash
+  end
+
+  ##
+  # Returns all modules discovered by RDoc
+
+  def self.all_modules
+    all_modules_hash.values
+  end
+
+  ##
+  # Hash of all modules known to RDoc
+
+  def self.all_modules_hash
+    @all_modules_hash
+  end
+
+  ##
+  # Prepares the RDoc code object tree for use by a generator.
+  #
+  # It finds unique classes/modules defined, and replaces classes/modules that
+  # are aliases for another one by a copy with RDoc::ClassModule#is_alias_for
+  # set.
+  #
+  # It updates the RDoc::ClassModule#constant_aliases attribute of "real"
+  # classes or modules.
+  #
+  # It also completely removes the classes and modules that should be removed
+  # from the documentation and the methods that have a visibility below
+  # +min_visibility+, which is the <tt>--visibility</tt> option.
+  #
+  # See also RDoc::Context#remove_from_documentation?
+
+  def self.complete min_visibility
+    fix_basic_object_inheritance
+
+    # cache included modules before they are removed from the documentation
+    all_classes_and_modules.each { |cm| cm.ancestors }
+
+    remove_nodoc @all_classes_hash
+    remove_nodoc @all_modules_hash
+
+    @unique_classes = find_unique @all_classes_hash
+    @unique_modules = find_unique @all_modules_hash
+
+    unique_classes_and_modules.each do |cm|
+      cm.complete min_visibility
+    end
+
+    @all_files_hash.each_key do |file_name|
+      tl = @all_files_hash[file_name]
+
+      unless tl.text? then
+        tl.modules_hash.clear
+        tl.classes_hash.clear
+
+        tl.classes_or_modules.each do |cm|
+          name = cm.full_name
+          if cm.type == 'class' then
+            tl.classes_hash[name] = cm if @all_classes_hash[name]
+          else
+            tl.modules_hash[name] = cm if @all_modules_hash[name]
+          end
+        end
+      end
+    end
+  end
+
+  ##
+  # Finds the class with +name+ in all discovered classes
+
+  def self.find_class_named(name)
+    @all_classes_hash[name]
+  end
+
+  ##
+  # Finds the class with +name+ starting in namespace +from+
+
+  def self.find_class_named_from name, from
+    from = find_class_named from unless RDoc::Context === from
+
+    until RDoc::TopLevel === from do
+      return nil unless from
+
+      klass = from.find_class_named name
+      return klass if klass
+
+      from = from.parent
+    end
+
+    find_class_named name
+  end
+
+  ##
+  # Finds the class or module with +name+
+
+  def self.find_class_or_module(name)
+    name = $' if name =~ /^::/
+    RDoc::TopLevel.classes_hash[name] || RDoc::TopLevel.modules_hash[name]
+  end
+
+  ##
+  # Finds the file with +name+ in all discovered files
+
+  def self.find_file_named(name)
+    @all_files_hash[name]
+  end
+
+  ##
+  # Finds the module with +name+ in all discovered modules
+
+  def self.find_module_named(name)
+    modules_hash[name]
+  end
+
+  ##
+  # Finds unique classes/modules defined in +all_hash+,
+  # and returns them as an array. Performs the alias
+  # updates in +all_hash+: see ::complete.
+  #--
+  # TODO  aliases should be registered by Context#add_module_alias
+
+  def self.find_unique(all_hash)
+    unique = []
+
+    all_hash.each_pair do |full_name, cm|
+      unique << cm if full_name == cm.full_name
+    end
+
+    unique
+  end
+
+  ##
+  # Fixes the erroneous <tt>BasicObject < Object</tt> in 1.9.
+  #
+  # Because we assumed all classes without a stated superclass
+  # inherit from Object, we have the above wrong inheritance.
+  #
+  # We fix BasicObject right away if we are running in a Ruby
+  # version >= 1.9. If not, we may be documenting 1.9 source
+  # while running under 1.8: we search the files of BasicObject
+  # for "object.c", and fix the inheritance if we find it.
+
+  def self.fix_basic_object_inheritance
+    basic = all_classes_hash['BasicObject']
+    return unless basic
+    if RUBY_VERSION >= '1.9'
+      basic.superclass = nil
+    elsif basic.in_files.any? { |f| File.basename(f.full_name) == 'object.c' }
+      basic.superclass = nil
+    end
+  end
+
+  ##
+  # Creates a new RDoc::TopLevel with +file_name+ only if one with the same
+  # name does not exist in all_files.
+
+  def self.new file_name
+    if top_level = @all_files_hash[file_name] then
+      top_level
+    else
+      top_level = super
+      @all_files_hash[file_name] = top_level
+      top_level
+    end
+  end
+
+  ##
+  # Returns the RDoc::TopLevel that has the given +name+
+
+  def self.page name
+    @all_files_hash.each_value.find do |file|
+      file.text? and file.page_name == name
+    end
+  end
+
+  ##
+  # Removes from +all_hash+ the contexts that are nodoc or have no content.
+  #
+  # See RDoc::Context#remove_from_documentation?
+
+  def self.remove_nodoc(all_hash)
+    all_hash.keys.each do |name|
+      context = all_hash[name]
+      all_hash.delete(name) if context.remove_from_documentation?
+    end
+  end
+
+  ##
+  # Empties RDoc of stored class, module and file information
+
+  def self.reset
+    @all_classes_hash = {}
+    @all_modules_hash = {}
+    @all_files_hash   = {}
+  end
+
+  ##
+  # Returns the unique classes discovered by RDoc.
+  #
+  # ::complete must have been called prior to using this method.
+
+  def self.unique_classes
+    @unique_classes
+  end
+
+  ##
+  # Returns the unique classes and modules discovered by RDoc.
+  # ::complete must have been called prior to using this method.
+
+  def self.unique_classes_and_modules
+    @unique_classes + @unique_modules
+  end
+
+  ##
+  # Returns the unique modules discovered by RDoc.
+  # ::complete must have been called prior to using this method.
+
+  def self.unique_modules
+    @unique_modules
+  end
+
+  class << self
+    alias classes      all_classes
+    alias classes_hash all_classes_hash
+
+    alias files        all_files
+    alias files_hash   all_files_hash
+
+    alias modules      all_modules
+    alias modules_hash all_modules_hash
+  end
+
+  reset
+
+  ##
+  # Creates a new TopLevel for +file_name+
+
+  def initialize(file_name)
+    super()
+    @name = nil
+    @relative_name = file_name
+    @absolute_name = file_name
+    @file_stat     = File.stat(file_name) rescue nil # HACK for testing
+    @diagram       = nil
+    @parser        = nil
+
+    @classes_or_modules = []
+
+    RDoc::TopLevel.files_hash[file_name] = self
+  end
+
+  ##
+  # An RDoc::TopLevel is equal to another with the same absolute_name
+
+  def == other
+    self.class === other and @absolute_name == other.absolute_name
+  end
+
+  alias eql? ==
+
+  ##
+  # Adds +an_alias+ to +Object+ instead of +self+.
+
+  def add_alias(an_alias)
+    object_class.record_location self
+    return an_alias unless @document_self
+    object_class.add_alias an_alias
+  end
+
+  ##
+  # Adds +constant+ to +Object+ instead of +self+.
+
+  def add_constant constant
+    object_class.record_location self
+    return constant unless @document_self
+    object_class.add_constant constant
+  end
+
+  ##
+  # Adds +include+ to +Object+ instead of +self+.
+
+  def add_include(include)
+    object_class.record_location self
+    return include unless @document_self
+    object_class.add_include include
+  end
+
+  ##
+  # Adds +method+ to +Object+ instead of +self+.
+
+  def add_method(method)
+    object_class.record_location self
+    return method unless @document_self
+    object_class.add_method method
+  end
+
+  ##
+  # Adds class or module +mod+. Used in the building phase
+  # by the ruby parser.
+
+  def add_to_classes_or_modules mod
+    @classes_or_modules << mod
+  end
+
+  ##
+  # Base name of this file
+
+  def base_name
+    File.basename @absolute_name
+  end
+
+  alias name base_name
+
+  ##
+  # Only a TopLevel that contains text file) will be displayed.  See also
+  # RDoc::CodeObject#display?
+
+  def display?
+    text? and super
+  end
+
+  ##
+  # See RDoc::TopLevel::find_class_or_module
+  #--
+  # TODO Why do we search through all classes/modules found, not just the
+  #       ones of this instance?
+
+  def find_class_or_module name
+    RDoc::TopLevel.find_class_or_module name
+  end
+
+  ##
+  # Finds a class or module named +symbol+
+
+  def find_local_symbol(symbol)
+    find_class_or_module(symbol) || super
+  end
+
+  ##
+  # Finds a module or class with +name+
+
+  def find_module_named(name)
+    find_class_or_module(name)
+  end
+
+  ##
+  # Returns the relative name of this file
+
+  def full_name
+    @relative_name
+  end
+
+  ##
+  # An RDoc::TopLevel has the same hash as another with the same
+  # absolute_name
+
+  def hash
+    @absolute_name.hash
+  end
+
+  ##
+  # URL for this with a +prefix+
+
+  def http_url(prefix)
+    path = [prefix, @relative_name.tr('.', '_')]
+
+    File.join(*path.compact) + '.html'
+  end
+
+  def inspect # :nodoc:
+    "#<%s:0x%x %p modules: %p classes: %p>" % [
+      self.class, object_id,
+      base_name,
+      @modules.map { |n,m| m },
+      @classes.map { |n,c| c }
+    ]
+  end
+
+  ##
+  # Time this file was last modified, if known
+
+  def last_modified
+    @file_stat ? file_stat.mtime : nil
+  end
+
+  ##
+  # Returns the NormalClass "Object", creating it if not found.
+  #
+  # Records +self+ as a location in "Object".
+
+  def object_class
+    @object_class ||= begin
+      oc = self.class.find_class_named('Object') || add_class(RDoc::NormalClass, 'Object')
+      oc.record_location self
+      oc
+    end
+  end
+
+  ##
+  # Base name of this file without the extension
+
+  def page_name
+    basename = File.basename @absolute_name
+    basename =~ /\.[^.]*$/
+
+    $` || basename
+  end
+
+  ##
+  # Path to this file
+
+  def path
+    http_url RDoc::RDoc.current.generator.file_dir
+  end
+
+  def pretty_print q # :nodoc:
+    q.group 2, "[#{self.class}: ", "]" do
+      q.text "base name: #{base_name.inspect}"
+      q.breakable
+
+      items = @modules.map { |n,m| m }
+      items.push(*@modules.map { |n,c| c })
+      q.seplist items do |mod| q.pp mod end
+    end
+  end
+
+  ##
+  # Search record used by RDoc::Generator::JsonIndex
+
+  def search_record
+    return unless @parser < RDoc::Parser::Text
+
+    [
+      page_name,
+      '',
+      page_name,
+      '',
+      path,
+      '',
+      snippet(@comment),
+    ]
+  end
+
+  ##
+  # Is this TopLevel from a text file instead of a source code file?
+
+  def text?
+    @parser and @parser.ancestors.include? RDoc::Parser::Text
+  end
+
+  def to_s # :nodoc:
+    "file #{full_name}"
+  end
+
+end
+