class RDoc::TopLevel
A TopLevel context is a representation of the contents of a single file
Attributes
Absolute name of this file
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.
This TopLevel's File::Stat struct
The parser that processed this file
Relative name of this file
Public Class Methods
Returns all classes discovered by RDoc
# File lib/rdoc/top_level.rb, line 38 def self.all_classes @all_classes_hash.values end
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
Hash of all classes known to RDoc
# File lib/rdoc/top_level.rb, line 52 def self.all_classes_hash @all_classes_hash end
All TopLevels known to RDoc
# File lib/rdoc/top_level.rb, line 59 def self.all_files @all_files_hash.values end
Hash of all files known to RDoc
# File lib/rdoc/top_level.rb, line 66 def self.all_files_hash @all_files_hash end
Returns all modules discovered by RDoc
# File lib/rdoc/top_level.rb, line 73 def self.all_modules all_modules_hash.values end
Hash of all modules known to RDoc
# File lib/rdoc/top_level.rb, line 80 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 --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
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
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
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 =~ /^::/ RDoc::TopLevel.classes_hash[name] || RDoc::TopLevel.modules_hash[name] end
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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 of this file
# File lib/rdoc/top_level.rb, line 375 def base_name File.basename @absolute_name end
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 /%s/ =~ url then url % @absolute_name else url + @absolute_name end end
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
# File lib/rdoc/top_level.rb, line 395 def find_class_or_module name RDoc::TopLevel.find_class_or_module name end
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
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
Returns the relative name of this file
# File lib/rdoc/top_level.rb, line 416 def full_name @relative_name end
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
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
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
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
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 =~ /\.[^.]*$/ $` || basename end
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 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
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