2017-11-27 13:45:24 +03:00
|
|
|
# frozen_string_literal: true
|
2010-04-01 11:45:16 +04:00
|
|
|
##
|
|
|
|
# A TopLevel context is a representation of the contents of a single file
|
|
|
|
|
|
|
|
class RDoc::TopLevel < RDoc::Context
|
|
|
|
|
2012-11-27 08:28:14 +04:00
|
|
|
MARSHAL_VERSION = 0 # :nodoc:
|
|
|
|
|
2010-04-01 11:45:16 +04:00
|
|
|
##
|
|
|
|
# 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
|
|
|
|
|
2010-12-20 06:22:49 +03:00
|
|
|
##
|
|
|
|
# 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:
|
2010-04-01 11:45:16 +04:00
|
|
|
|
|
|
|
##
|
2013-09-19 03:33:36 +04:00
|
|
|
# The parser class that processed this file
|
2010-04-01 11:45:16 +04:00
|
|
|
|
2018-10-17 09:28:20 +03:00
|
|
|
attr_reader :parser
|
2010-04-01 11:45:16 +04:00
|
|
|
|
|
|
|
##
|
2012-11-27 12:54:03 +04:00
|
|
|
# Creates a new TopLevel for the file at +absolute_name+. If documentation
|
|
|
|
# is being generated outside the source dir +relative_name+ is relative to
|
|
|
|
# the source directory.
|
2010-04-01 11:45:16 +04:00
|
|
|
|
2012-11-27 12:54:03 +04:00
|
|
|
def initialize absolute_name, relative_name = absolute_name
|
2010-04-01 11:45:16 +04:00
|
|
|
super()
|
|
|
|
@name = nil
|
2012-11-27 12:54:03 +04:00
|
|
|
@absolute_name = absolute_name
|
|
|
|
@relative_name = relative_name
|
|
|
|
@file_stat = File.stat(absolute_name) rescue nil # HACK for testing
|
2010-04-01 11:45:16 +04:00
|
|
|
@diagram = nil
|
|
|
|
@parser = nil
|
|
|
|
|
2010-12-20 06:22:49 +03:00
|
|
|
@classes_or_modules = []
|
2010-04-01 11:45:16 +04:00
|
|
|
end
|
|
|
|
|
2018-10-17 09:28:20 +03:00
|
|
|
def parser=(val)
|
|
|
|
@parser = val
|
|
|
|
@store.update_parser_of_file(absolute_name, val) if @store
|
|
|
|
@parser
|
|
|
|
end
|
|
|
|
|
2011-06-16 08:59:24 +04:00
|
|
|
##
|
2012-11-27 12:54:03 +04:00
|
|
|
# An RDoc::TopLevel is equal to another with the same relative_name
|
2011-06-16 08:59:24 +04:00
|
|
|
|
|
|
|
def == other
|
2012-11-27 12:54:03 +04:00
|
|
|
self.class === other and @relative_name == other.relative_name
|
2011-06-16 08:59:24 +04:00
|
|
|
end
|
|
|
|
|
|
|
|
alias eql? ==
|
|
|
|
|
2010-04-01 11:45:16 +04:00
|
|
|
##
|
2010-12-20 06:22:49 +03:00
|
|
|
# Adds +an_alias+ to +Object+ instead of +self+.
|
|
|
|
|
|
|
|
def add_alias(an_alias)
|
2011-06-30 01:17:31 +04:00
|
|
|
object_class.record_location self
|
2010-12-20 06:22:49 +03:00
|
|
|
return an_alias unless @document_self
|
|
|
|
object_class.add_alias an_alias
|
|
|
|
end
|
|
|
|
|
|
|
|
##
|
|
|
|
# Adds +constant+ to +Object+ instead of +self+.
|
|
|
|
|
2012-11-27 08:28:14 +04:00
|
|
|
def add_constant constant
|
2011-06-30 01:17:31 +04:00
|
|
|
object_class.record_location self
|
2010-12-20 06:22:49 +03:00
|
|
|
return constant unless @document_self
|
|
|
|
object_class.add_constant constant
|
|
|
|
end
|
|
|
|
|
|
|
|
##
|
|
|
|
# Adds +include+ to +Object+ instead of +self+.
|
|
|
|
|
|
|
|
def add_include(include)
|
2011-06-30 01:17:31 +04:00
|
|
|
object_class.record_location self
|
2010-12-20 06:22:49 +03:00
|
|
|
return include unless @document_self
|
|
|
|
object_class.add_include include
|
|
|
|
end
|
|
|
|
|
|
|
|
##
|
|
|
|
# Adds +method+ to +Object+ instead of +self+.
|
2010-04-01 11:45:16 +04:00
|
|
|
|
|
|
|
def add_method(method)
|
2011-06-30 01:17:31 +04:00
|
|
|
object_class.record_location self
|
2010-12-20 06:22:49 +03:00
|
|
|
return method unless @document_self
|
|
|
|
object_class.add_method method
|
|
|
|
end
|
|
|
|
|
|
|
|
##
|
|
|
|
# Adds class or module +mod+. Used in the building phase
|
2013-07-19 06:26:08 +04:00
|
|
|
# by the Ruby parser.
|
2010-04-01 11:45:16 +04:00
|
|
|
|
2010-12-20 06:22:49 +03:00
|
|
|
def add_to_classes_or_modules mod
|
|
|
|
@classes_or_modules << mod
|
2010-04-01 11:45:16 +04:00
|
|
|
end
|
|
|
|
|
|
|
|
##
|
|
|
|
# Base name of this file
|
|
|
|
|
|
|
|
def base_name
|
2012-11-27 12:54:03 +04:00
|
|
|
File.basename @relative_name
|
2010-04-01 11:45:16 +04:00
|
|
|
end
|
|
|
|
|
2010-12-20 06:22:49 +03:00
|
|
|
alias name base_name
|
|
|
|
|
2012-11-27 08:28:14 +04:00
|
|
|
##
|
|
|
|
# Only a TopLevel that contains text file) will be displayed. See also
|
|
|
|
# RDoc::CodeObject#display?
|
|
|
|
|
|
|
|
def display?
|
|
|
|
text? and super
|
|
|
|
end
|
|
|
|
|
2010-04-01 11:45:16 +04:00
|
|
|
##
|
2010-12-20 06:22:49 +03:00
|
|
|
# See RDoc::TopLevel::find_class_or_module
|
|
|
|
#--
|
|
|
|
# TODO Why do we search through all classes/modules found, not just the
|
|
|
|
# ones of this instance?
|
2010-04-01 11:45:16 +04:00
|
|
|
|
|
|
|
def find_class_or_module name
|
2012-11-27 08:28:14 +04:00
|
|
|
@store.find_class_or_module name
|
2010-04-01 11:45:16 +04:00
|
|
|
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)
|
2010-12-20 06:22:49 +03:00
|
|
|
find_class_or_module(name)
|
2010-04-01 11:45:16 +04:00
|
|
|
end
|
|
|
|
|
|
|
|
##
|
2010-12-20 06:22:49 +03:00
|
|
|
# Returns the relative name of this file
|
2010-04-01 11:45:16 +04:00
|
|
|
|
|
|
|
def full_name
|
|
|
|
@relative_name
|
|
|
|
end
|
|
|
|
|
2011-06-16 08:59:24 +04:00
|
|
|
##
|
|
|
|
# An RDoc::TopLevel has the same hash as another with the same
|
2012-11-27 12:54:03 +04:00
|
|
|
# relative_name
|
2011-06-16 08:59:24 +04:00
|
|
|
|
|
|
|
def hash
|
2012-11-27 12:54:03 +04:00
|
|
|
@relative_name.hash
|
2011-06-16 08:59:24 +04:00
|
|
|
end
|
|
|
|
|
2010-04-01 11:45:16 +04:00
|
|
|
##
|
|
|
|
# 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
|
|
|
|
|
|
|
|
##
|
2010-12-20 06:22:49 +03:00
|
|
|
# Time this file was last modified, if known
|
2010-04-01 11:45:16 +04:00
|
|
|
|
|
|
|
def last_modified
|
2010-12-20 06:22:49 +03:00
|
|
|
@file_stat ? file_stat.mtime : nil
|
2010-04-01 11:45:16 +04:00
|
|
|
end
|
|
|
|
|
2012-11-27 08:28:14 +04:00
|
|
|
##
|
|
|
|
# Dumps this TopLevel for use by ri. See also #marshal_load
|
2013-01-23 05:02:24 +04:00
|
|
|
|
2012-11-27 08:28:14 +04:00
|
|
|
def marshal_dump
|
|
|
|
[
|
|
|
|
MARSHAL_VERSION,
|
2012-11-27 12:54:03 +04:00
|
|
|
@relative_name,
|
2012-11-27 08:28:14 +04:00
|
|
|
@parser,
|
|
|
|
parse(@comment),
|
|
|
|
]
|
|
|
|
end
|
|
|
|
|
|
|
|
##
|
|
|
|
# Loads this TopLevel from +array+.
|
|
|
|
|
|
|
|
def marshal_load array # :nodoc:
|
|
|
|
initialize array[1]
|
|
|
|
|
|
|
|
@parser = array[2]
|
|
|
|
@comment = array[3]
|
|
|
|
|
|
|
|
@file_stat = nil
|
|
|
|
end
|
|
|
|
|
2010-04-01 11:45:16 +04:00
|
|
|
##
|
2010-12-20 06:22:49 +03:00
|
|
|
# Returns the NormalClass "Object", creating it if not found.
|
|
|
|
#
|
|
|
|
# Records +self+ as a location in "Object".
|
|
|
|
|
|
|
|
def object_class
|
|
|
|
@object_class ||= begin
|
2012-11-27 08:28:14 +04:00
|
|
|
oc = @store.find_class_named('Object') || add_class(RDoc::NormalClass, 'Object')
|
2010-12-20 06:22:49 +03:00
|
|
|
oc.record_location self
|
|
|
|
oc
|
|
|
|
end
|
|
|
|
end
|
2010-04-01 11:45:16 +04:00
|
|
|
|
|
|
|
##
|
2012-11-27 08:28:14 +04:00
|
|
|
# Base name of this file without the extension
|
|
|
|
|
|
|
|
def page_name
|
2012-11-27 12:54:03 +04:00
|
|
|
basename = File.basename @relative_name
|
2013-01-15 02:43:21 +04:00
|
|
|
basename =~ /\.(rb|rdoc|txt|md)$/i
|
2012-11-27 08:28:14 +04:00
|
|
|
|
|
|
|
$` || basename
|
|
|
|
end
|
|
|
|
|
|
|
|
##
|
|
|
|
# Path to this file for use with HTML generator output.
|
2010-04-01 11:45:16 +04:00
|
|
|
|
|
|
|
def path
|
2012-11-27 08:28:14 +04:00
|
|
|
http_url @store.rdoc.generator.file_dir
|
2010-04-01 11:45:16 +04:00
|
|
|
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 }
|
2012-11-27 08:28:14 +04:00
|
|
|
items.concat @modules.map { |n,c| c }
|
2010-04-01 11:45:16 +04:00
|
|
|
q.seplist items do |mod| q.pp mod end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
2012-11-27 08:28:14 +04:00
|
|
|
##
|
|
|
|
# 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?
|
2018-10-17 09:28:20 +03:00
|
|
|
@parser and @parser.include? RDoc::Parser::Text
|
2012-11-27 08:28:14 +04:00
|
|
|
end
|
|
|
|
|
2010-12-20 06:22:49 +03:00
|
|
|
def to_s # :nodoc:
|
|
|
|
"file #{full_name}"
|
|
|
|
end
|
|
|
|
|
2010-04-01 11:45:16 +04:00
|
|
|
end
|
|
|
|
|