Class: RDoc::TopLevel

Inherits:
Context show all
Defined in:
lib/rdoc/code_object/top_level.rb,
lib/rdoc/generator/markup.rb

Overview

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

Constant Summary collapse

MARSHAL_VERSION =

:nodoc:

0

Constants inherited from Context

Context::TOMDOC_TITLES, Context::TOMDOC_TITLES_SORT, Context::TYPES

Constants included from Text

RDoc::Text::MARKUP_FORMAT, RDoc::Text::SPACE_SEPARATED_LETTER_CLASS, RDoc::Text::TO_HTML_CHARACTERS

Instance Attribute Summary collapse

Attributes inherited from Context

#aliases, #attributes, #block_params, #constants, #constants_hash, #current_line_visibility, #current_section, #extends, #external_aliases, #in_files, #includes, #method_list, #methods_hash, #params, #requires, #temporary_section, #unmatched_alias_lists, #visibility

Attributes inherited from CodeObject

#comment, #document_children, #document_self, #done_documenting, #file, #force_documentation, #line, #metadata, #mixin_from, #parent, #received_nodoc, #section, #store, #viewer

Attributes included from Text

#language

Instance Method Summary collapse

Methods inherited from Context

#<=>, #add, #add_attribute, #add_class, #add_class_or_module, #add_extend, #add_module, #add_module_alias, #add_module_by_normal_module, #add_require, #add_section, #add_to, #any_content, #child_name, #class_attributes, #class_method_list, #classes, #classes_and_modules, #classes_hash, #defined_in?, #display, #each_ancestor, #each_attribute, #each_classmodule, #each_constant, #each_extend, #each_include, #each_method, #each_section, #find_attribute, #find_attribute_named, #find_class_method_named, #find_constant_named, #find_enclosing_module_named, #find_external_alias, #find_external_alias_named, #find_file_named, #find_instance_method_named, #find_method, #find_method_named, #find_symbol, #find_symbol_module, #fully_documented?, #initialize_methods_etc, #instance_attributes, #instance_method_list, #instance_methods, #methods_by_type, #methods_matching, #modules, #modules_hash, #name_for_path, #ongoing_visibility=, #record_location, #remove_from_documentation?, #remove_invisible, #remove_invisible_in, #resolve_aliases, #section_contents, #sections, #sections_hash, #set_constant_visibility_for, #set_current_section, #set_visibility_for, #sort_sections, #top_level, #upgrade_to_class

Methods inherited from CodeObject

#documented?, #each_parent, #file_name, #full_name=, #ignore, #ignored?, #initialize_visibility, #options, #parent_file_name, #parent_name, #record_location, #start_doc, #stop_doc, #suppress, #suppressed?

Methods included from Generator::Markup

#aref_to, #as_href, #description, #formatter

Methods included from Text

encode_fallback, #expand_tabs, #flush_left, #markup, #normalize_comment, #parse, #snippet, #strip_hashes, #strip_newlines, #strip_stars, #to_html, #wrap

Constructor Details

#initialize(absolute_name, relative_name = absolute_name) ⇒ TopLevel

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.



43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/rdoc/code_object/top_level.rb', line 43

def initialize absolute_name, relative_name = absolute_name
  super()
  @name = nil
  @absolute_name = absolute_name
  @relative_name = relative_name
  @file_stat     = File.stat(absolute_name) rescue nil # HACK for testing
  @diagram       = nil
  @parser        = nil

  @classes_or_modules = []
end

Instance Attribute Details

#absolute_name ⇒ Object

Absolute name of this file



22
23
24
 
# File 'lib/rdoc/code_object/top_level.rb', line 22

def absolute_name
  @absolute_name
end

#classes_or_modules ⇒ Object (readonly)

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.



29
30
31
 
# File 'lib/rdoc/code_object/top_level.rb', line 29

def classes_or_modules
  @classes_or_modules
end

#diagram ⇒ Object

:nodoc:



31
32
33
 
# File 'lib/rdoc/code_object/top_level.rb', line 31

def diagram
  @diagram
end

#file_stat ⇒ Object

This TopLevel’s File::Stat struct



12
13
14
 
# File 'lib/rdoc/code_object/top_level.rb', line 12

def file_stat
  @file_stat
end

#parser ⇒ Object

The parser class that processed this file



36
37
38
 
# File 'lib/rdoc/code_object/top_level.rb', line 36

def parser
  @parser
end

#relative_name ⇒ Object

Relative name of this file



17
18
19
 
# File 'lib/rdoc/code_object/top_level.rb', line 17

def relative_name
  @relative_name
end

Instance Method Details

#==(other) ⇒ Object Also known as: eql?

An RDoc::TopLevel is equal to another with the same relative_name



67
68
69
 
# File 'lib/rdoc/code_object/top_level.rb', line 67

def == other
  self.class === other and @relative_name == other.relative_name
end

#add_alias(an_alias) ⇒ Object

Adds an_alias to Object instead of self.



76
77
78
79
80
 
# File 'lib/rdoc/code_object/top_level.rb', line 76

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) ⇒ Object

Adds constant to Object instead of self.



85
86
87
88
89
 
# File 'lib/rdoc/code_object/top_level.rb', line 85

def add_constant constant
  object_class.record_location self
  return constant unless @document_self
  object_class.add_constant constant
end

#add_include(include) ⇒ Object

Adds include to Object instead of self.



94
95
96
97
98
 
# File 'lib/rdoc/code_object/top_level.rb', line 94

def add_include(include)
  object_class.record_location self
  return include unless @document_self
  object_class.add_include include
end

#add_method(method) ⇒ Object

Adds method to Object instead of self.



103
104
105
106
107
 
# File 'lib/rdoc/code_object/top_level.rb', line 103

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) ⇒ Object

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



113
114
115
 
# File 'lib/rdoc/code_object/top_level.rb', line 113

def add_to_classes_or_modules mod
  @classes_or_modules << mod
end

#base_name ⇒ Object Also known as: name

Base name of this file



120
121
122
 
# File 'lib/rdoc/code_object/top_level.rb', line 120

def base_name
  File.basename @relative_name
end

#cvs_url ⇒ Object

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



149
150
151
152
153
154
155
156
157
 
# File 'lib/rdoc/generator/markup.rb', line 149

def cvs_url
  url = @store.rdoc.options.webcvs

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

#display? ⇒ Boolean

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

Returns:

  • (Boolean) 


130
131
132
 
# File 'lib/rdoc/code_object/top_level.rb', line 130

def display?
  text? and super
end

#find_class_or_module(name) ⇒ Object

See RDoc::TopLevel::find_class_or_module – TODO Why do we search through all classes/modules found, not just the

ones of this instance?



140
141
142
 
# File 'lib/rdoc/code_object/top_level.rb', line 140

def find_class_or_module name
  @store.find_class_or_module name
end

#find_local_symbol(symbol) ⇒ Object

Finds a class or module named symbol



147
148
149
 
# File 'lib/rdoc/code_object/top_level.rb', line 147

def find_local_symbol(symbol)
  find_class_or_module(symbol) || super
end

#find_module_named(name) ⇒ Object

Finds a module or class with name



154
155
156
 
# File 'lib/rdoc/code_object/top_level.rb', line 154

def find_module_named(name)
  find_class_or_module(name)
end

#full_name ⇒ Object

Returns the relative name of this file



161
162
163
 
# File 'lib/rdoc/code_object/top_level.rb', line 161

def full_name
  @relative_name
end

#hash ⇒ Object

An RDoc::TopLevel has the same hash as another with the same relative_name



169
170
171
 
# File 'lib/rdoc/code_object/top_level.rb', line 169

def hash
  @relative_name.hash
end

#http_url(prefix) ⇒ Object

URL for this with a prefix



176
177
178
179
180
 
# File 'lib/rdoc/code_object/top_level.rb', line 176

def http_url(prefix)
  path = [prefix, @relative_name.tr('.', '_')]

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

#inspect ⇒ Object

:nodoc:



182
183
184
185
186
187
188
189
 
# File 'lib/rdoc/code_object/top_level.rb', line 182

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

#last_modified ⇒ Object

Time this file was last modified, if known



194
195
196
 
# File 'lib/rdoc/code_object/top_level.rb', line 194

def last_modified
  @file_stat ? file_stat.mtime : nil
end

#marshal_dump ⇒ Object

Dumps this TopLevel for use by ri. See also #marshal_load



201
202
203
204
205
206
207
208
 
# File 'lib/rdoc/code_object/top_level.rb', line 201

def marshal_dump
  [
    MARSHAL_VERSION,
    @relative_name,
    @parser,
    parse(@comment),
  ]
end

#marshal_load(array) ⇒ Object

Loads this TopLevel from array.



213
214
215
216
217
218
219
220
 
# File 'lib/rdoc/code_object/top_level.rb', line 213

def marshal_load array # :nodoc:
  initialize array[1]

  @parser  = array[2]
  @comment = array[3]

  @file_stat          = nil
end

#object_class ⇒ Object

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

Records self as a location in “Object”.



227
228
229
230
231
232
233
 
# File 'lib/rdoc/code_object/top_level.rb', line 227

def object_class
  @object_class ||= begin
    oc = @store.find_class_named('Object') || add_class(RDoc::NormalClass, 'Object')
    oc.record_location self
    oc
  end
end

#page_name ⇒ Object

Base name of this file without the extension



238
239
240
241
242
243
 
# File 'lib/rdoc/code_object/top_level.rb', line 238

def page_name
  basename = File.basename @relative_name
  basename =~ /\.(rb|rdoc|txt|md)$/i

  $` || basename
end

#path ⇒ Object

Path to this file for use with HTML generator output.



248
249
250
 
# File 'lib/rdoc/code_object/top_level.rb', line 248

def path
  http_url @store.rdoc.generator.file_dir
end

#pretty_print(q) ⇒ Object

:nodoc:



252
253
254
255
256
257
258
259
260
261
 
# File 'lib/rdoc/code_object/top_level.rb', line 252

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.concat @modules.map { |n, c| c }
    q.seplist items do |mod| q.pp mod end
  end
end

#search_record ⇒ Object

Search record used by RDoc::Generator::JsonIndex



266
267
268
269
270
271
272
273
274
275
276
277
278
 
# File 'lib/rdoc/code_object/top_level.rb', line 266

def search_record
  return unless @parser < RDoc::Parser::Text

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

#text? ⇒ Boolean

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

Returns:

  • (Boolean) 


283
284
285
 
# File 'lib/rdoc/code_object/top_level.rb', line 283

def text?
  @parser and @parser.include? RDoc::Parser::Text
end

#to_s ⇒ Object

:nodoc:



287
288
289
 
# File 'lib/rdoc/code_object/top_level.rb', line 287

def to_s # :nodoc:
  "file #{full_name}"
end