# class RDoc::TopLevel

A TopLevel context is a representation of the contents of a single file

### Attributes

absolute_name[RW]

Absolute name of this file

classes_or_modules[R]

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.

file_stat[RW]

This TopLevel’s File::Stat struct

parser[RW]

The parser that processed this file

relative_name[RW]

Relative name of this file

### Public Class Methods

all_classes() click to toggle source

Returns all classes discovered by RDoc

    # File lib/rdoc/top_level.rb, line 38
    def self.all_classes
      @all_classes_hash.values
    end

Also aliased as: classes
all_classes_and_modules() click to toggle source

Returns all classes and modules discovered by RDoc

    # File lib/rdoc/top_level.rb, line 45
    def self.all_classes_and_modules
      @all_classes_hash.values + @all_modules_hash.values
    end

all_classes_hash() click to toggle source

Hash of all classes known to RDoc

    # File lib/rdoc/top_level.rb, line 52
    def self.all_classes_hash
      @all_classes_hash
    end

Also aliased as: classes_hash
all_files() click to toggle source

All TopLevels known to RDoc

    # File lib/rdoc/top_level.rb, line 59
    def self.all_files
      @all_files_hash.values
    end

Also aliased as: files
all_files_hash() click to toggle source

Hash of all files known to RDoc

    # File lib/rdoc/top_level.rb, line 66
    def self.all_files_hash
      @all_files_hash
    end

Also aliased as: files_hash
all_modules() click to toggle source

Returns all modules discovered by RDoc

    # File lib/rdoc/top_level.rb, line 73
    def self.all_modules
      all_modules_hash.values
    end

Also aliased as: modules
all_modules_hash() click to toggle source

Hash of all modules known to RDoc

    # File lib/rdoc/top_level.rb, line 80
    def self.all_modules_hash
      @all_modules_hash
    end

Also aliased as: modules_hash
classes() click to toggle source
Alias for: all_classes
classes_hash() click to toggle source
Alias for: all_classes_hash
complete(min_visibility) click to toggle source

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 `--visibility` option.

See also RDoc::Context#remove_from_documentation?

    # File lib/rdoc/top_level.rb, line 100
    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

files() click to toggle source
Alias for: all_files
files_hash() click to toggle source
Alias for: all_files_hash
find_class_named(name) click to toggle source

Finds the class with `name` in all discovered classes

    # File lib/rdoc/top_level.rb, line 138
    def self.find_class_named(name)
      @all_classes_hash[name]
    end

find_class_named_from(name, from) click to toggle source

Finds the class with `name` starting in namespace `from`

    # File lib/rdoc/top_level.rb, line 145
    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

find_class_or_module(name) click to toggle source

Finds the class or module with `name`

    # File lib/rdoc/top_level.rb, line 163
    def self.find_class_or_module(name)
      name = $' if name =~ %r^::/
      RDoc::TopLevel.classes_hash[name] || RDoc::TopLevel.modules_hash[name]
    end

find_file_named(name) click to toggle source

Finds the file with `name` in all discovered files

    # File lib/rdoc/top_level.rb, line 171
    def self.find_file_named(name)
      @all_files_hash[name]
    end

find_module_named(name) click to toggle source

Finds the module with `name` in all discovered modules

    # File lib/rdoc/top_level.rb, line 178
    def self.find_module_named(name)
      modules_hash[name]
    end

find_unique(all_hash) click to toggle source

Finds unique classes/modules defined in `all_hash`, and returns them as an array. Performs the alias updates in `all_hash`: see ::complete.

    # File lib/rdoc/top_level.rb, line 189
    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

fix_basic_object_inheritance() click to toggle source

Fixes the erroneous `BasicObject < Object` 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.

    # File lib/rdoc/top_level.rb, line 210
    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

modules() click to toggle source
Alias for: all_modules
modules_hash() click to toggle source
Alias for: all_modules_hash
new(file_name) click to toggle source

Creates a new RDoc::TopLevel with `file_name` only if one with the same name does not exist in all_files.

    # File lib/rdoc/top_level.rb, line 224
    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

new(file_name) click to toggle source

Creates a new TopLevel for `file_name`

    # File lib/rdoc/top_level.rb, line 305
    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

page(name) click to toggle source

Returns the RDoc::TopLevel that has the given `name`

    # File lib/rdoc/top_level.rb, line 237
    def self.page name
      @all_files_hash.each_value.find do |file|
        file.text? and file.page_name == name
      end
    end

remove_nodoc(all_hash) click to toggle source

Removes from `all_hash` the contexts that are nodoc or have no content.

See RDoc::Context#remove_from_documentation?

    # File lib/rdoc/top_level.rb, line 248
    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

reset() click to toggle source

Empties RDoc of stored class, module and file information

    # File lib/rdoc/top_level.rb, line 258
    def self.reset
      @all_classes_hash = {}
      @all_modules_hash = {}
      @all_files_hash   = {}
    end

unique_classes() click to toggle source

Returns the unique classes discovered by RDoc.

::complete must have been called prior to using this method.

    # File lib/rdoc/top_level.rb, line 269
    def self.unique_classes
      @unique_classes
    end

unique_classes_and_modules() click to toggle source

Returns the unique classes and modules discovered by RDoc. ::complete must have been called prior to using this method.

    # File lib/rdoc/top_level.rb, line 277
    def self.unique_classes_and_modules
      @unique_classes + @unique_modules
    end

unique_modules() click to toggle source

Returns the unique modules discovered by RDoc. ::complete must have been called prior to using this method.

    # File lib/rdoc/top_level.rb, line 285
    def self.unique_modules
      @unique_modules
    end

### Public Instance Methods

==(other) click to toggle source

An RDoc::TopLevel is equal to another with the same #absolute_name

    # File lib/rdoc/top_level.rb, line 322
    def == other
      self.class === other and @absolute_name == other.absolute_name
    end

Also aliased as: eql?
add_alias(an_alias) click to toggle source

Adds `an_alias` to `Object` instead of `self`.

    # File lib/rdoc/top_level.rb, line 331
    def add_alias(an_alias)
      object_class.record_location self
      return an_alias unless @document_self
      object_class.add_alias an_alias
    end

add_constant(constant) click to toggle source

Adds `constant` to `Object` instead of `self`.

    # File lib/rdoc/top_level.rb, line 340
    def add_constant constant
      object_class.record_location self
      return constant unless @document_self
      object_class.add_constant constant
    end

add_include(include) click to toggle source

Adds `include` to `Object` instead of `self`.

    # File lib/rdoc/top_level.rb, line 349
    def add_include(include)
      object_class.record_location self
      return include unless @document_self
      object_class.add_include include
    end

add_method(method) click to toggle source

Adds `method` to `Object` instead of `self`.

    # File lib/rdoc/top_level.rb, line 358
    def add_method(method)
      object_class.record_location self
      return method unless @document_self
      object_class.add_method method
    end

add_to_classes_or_modules(mod) click to toggle source

Adds class or module `mod`. Used in the building phase by the ruby parser.

    # File lib/rdoc/top_level.rb, line 368
    def add_to_classes_or_modules mod
      @classes_or_modules << mod
    end

base_name() click to toggle source

Base name of this file

    # File lib/rdoc/top_level.rb, line 375
    def base_name
      File.basename @absolute_name
    end

Also aliased as: name
cvs_url() click to toggle source

Returns a URL for this source file on some web repository. Use the -W command line option to set.

    # File lib/rdoc/generator/markup.rb, line 160
    def cvs_url
      url = RDoc::RDoc.current.options.webcvs

      if %r%s/ =~ url then
        url % @absolute_name
      else
        url + @absolute_name
      end
    end

display?() click to toggle source

Only a TopLevel that contains text file) will be displayed. See also RDoc::CodeObject#display?

    # File lib/rdoc/top_level.rb, line 385
    def display?
      text? and super
    end

eql?(other) click to toggle source
Alias for: ==
find_class_or_module(name) click to toggle source

See ::find_class_or_module

    # File lib/rdoc/top_level.rb, line 395
    def find_class_or_module name
      RDoc::TopLevel.find_class_or_module name
    end

find_local_symbol(symbol) click to toggle source

Finds a class or module named `symbol`

    # File lib/rdoc/top_level.rb, line 402
    def find_local_symbol(symbol)
      find_class_or_module(symbol) || super
    end

find_module_named(name) click to toggle source

Finds a module or class with `name`

    # File lib/rdoc/top_level.rb, line 409
    def find_module_named(name)
      find_class_or_module(name)
    end

full_name() click to toggle source

Returns the relative name of this file

    # File lib/rdoc/top_level.rb, line 416
    def full_name
      @relative_name
    end

hash() click to toggle source

An RDoc::TopLevel has the same hash as another with the same #absolute_name

    # File lib/rdoc/top_level.rb, line 424
    def hash
      @absolute_name.hash
    end

http_url(prefix) click to toggle source

URL for this with a `prefix`

    # File lib/rdoc/top_level.rb, line 431
    def http_url(prefix)
      path = [prefix, @relative_name.tr('.', '_')]

      File.join(*path.compact) + '.html'
    end

last_modified() click to toggle source

Time this file was last modified, if known

    # File lib/rdoc/top_level.rb, line 449
    def last_modified
      @file_stat ? file_stat.mtime : nil
    end

name() click to toggle source
Alias for: base_name
object_class() click to toggle source

Returns the NormalClass “Object”, creating it if not found.

Records `self` as a location in “Object”.

    # File lib/rdoc/top_level.rb, line 458
    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

page_name() click to toggle source

Base name of this file without the extension

    # File lib/rdoc/top_level.rb, line 469
    def page_name
      basename = File.basename @absolute_name
      basename =~ %r\.[^.]*$/

      $` || basename
    end

path() click to toggle source

Path to this file

    # File lib/rdoc/top_level.rb, line 479
    def path
      http_url RDoc::RDoc.current.generator.file_dir
    end

search_record() click to toggle source

Search record used by RDoc::Generator::JsonIndex

    # File lib/rdoc/top_level.rb, line 497
    def search_record
      return unless @parser < RDoc::Parser::Text

      [
        page_name,
        '',
        page_name,
        '',
        path,
        '',
        snippet(@comment),
      ]
    end

text?() click to toggle source

Is this TopLevel from a text file instead of a source code file?

    # File lib/rdoc/top_level.rb, line 514
    def text?
      @parser and @parser.ancestors.include? RDoc::Parser::Text
    end