Class: RDoc::TopLevel

Inherits:

Context

• Object
• CodeObject
• Context
• RDoc::TopLevel

show all

Defined in:

lib/rdoc/top_level.rb,
lib/rdoc/generator/markup.rb

Overview

Constant Summary

Constant Summary

Constants inherited from Context

Context::TYPES

Constants included from Text

RDoc::Text::TO_HTML_CHARACTERS

Instance Attribute Summary (collapse)

• - (Object) absolute_name

  Absolute name of this file.

• - (Object) classes_or_modules readonly

  All the classes or modules that were declared in this file.

• - (Object) diagram

  :nodoc:.

• - (Object) file_stat

  This TopLevel's File::Stat struct.

• - (Object) parser

  The parser that processed this file.

• - (Object) relative_name

  Relative name of this file.

Attributes inherited from Context

#aliases, #attributes, #constants, #constants_hash, #current_section, #external_aliases, #in_files, #includes, #method_list, #methods_hash, #requires, #unmatched_alias_lists, #visibility

Attributes inherited from CodeObject

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

Class Method Summary (collapse)

• + (Object) all_classes (also: classes)

  Returns all classes discovered by RDoc.

• + (Object) all_classes_and_modules

  Returns all classes and modules discovered by RDoc.

• + (Object) all_classes_hash (also: classes_hash)

  Hash of all classes known to RDoc.

• + (Object) all_files (also: files)

  All TopLevels known to RDoc.

• + (Object) all_files_hash (also: files_hash)

  Hash of all files known to RDoc.

• + (Object) all_modules (also: modules)

  Returns all modules discovered by RDoc.

• + (Object) all_modules_hash (also: modules_hash)

  Hash of all modules known to RDoc.

• + (Object) complete(min_visibility)

  Prepares the RDoc code object tree for use by a generator.

• + (Object) find_class_named(name)

  Finds the class with name in all discovered classes.

• + (Object) find_class_named_from(name, from)

  Finds the class with name starting in namespace from.

• + (Object) find_class_or_module(name)

  Finds the class or module with name.

• + (Object) find_file_named(name)

  Finds the file with name in all discovered files.

• + (Object) find_module_named(name)

  Finds the module with name in all discovered modules.

• + (Object) find_unique(all_hash)

  Finds unique classes/modules defined in all_hash, and returns them as an array.

• + (Object) fix_basic_object_inheritance

  Fixes the erroneous BasicObject in 1.9.

• + (Object) remove_nodoc(all_hash)

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

• + (Object) reset

  Empties RDoc of stored class, module and file information.

• + (Object) unique_classes

  Returns the unique classes discovered by RDoc.

• + (Object) unique_classes_and_modules

  Returns the unique classes and modules discovered by RDoc.

• + (Object) unique_modules

  Returns the unique modules discovered by RDoc.

Instance Method Summary (collapse)

• - (Object) add_alias(an_alias)

  Adds an_alias to Object instead of self.

• - (Object) add_constant(constant)

  Adds constant to Object instead of self.

• - (Object) add_include(include)

  Adds include to Object instead of self.

• - (Object) add_method(method)

  Adds method to Object instead of self.

• - (Object) add_to_classes_or_modules(mod)

  Adds class or module mod.

• - (Object) base_name (also: #name)

  Base name of this file.

• - (Object) cvs_url

  Returns a URL for this source file on some web repository.

• - (Object) find_class_or_module(name)

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

• - (Object) find_local_symbol(symbol)

  Finds a class or module named symbol.

• - (Object) find_module_named(name)

  Finds a module or class with name.

• - (Object) full_name

  Returns the relative name of this file.

• - (Object) http_url(prefix)

  URL for this with a prefix.

• - (TopLevel) initialize(file_name) constructor

  Creates a new TopLevel for file_name.

• - (Object) inspect

  :nodoc:.

• - (Object) last_modified

  Time this file was last modified, if known.

• - (Object) object_class

  Returns the NormalClass "Object", creating it if not found.

• - (Object) path

  Path to this file.

• - (Object) pretty_print(q)

  :nodoc:.

• - (Object) to_s

  :nodoc:.

Methods inherited from Context

#<=>, #add_attribute, #add_class, #add_class_or_module, #add_module, #add_module_alias, #add_require, #add_to, #any_content, #child_name, #class_attributes, #class_method_list, #classes, #classes_and_modules, #classes_hash, #defined_in?, #display, #each_attribute, #each_classmodule, #each_constant, #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, #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, #sections, #sections_hash, #set_current_section, #set_visibility_for, #top_level, #upgrade_to_class

Methods included from Generator::Markup

#aref_to, #as_href, #description, #formatter

Methods inherited from CodeObject

#documented?, #full_name=, #parent_file_name, #parent_name, #record_location, #start_doc, #stop_doc

Methods included from Text

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

284
285
286
287
288
289
290
291
292
293
294
295
296

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

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

21
22
23

# File 'lib/rdoc/top_level.rb', line 21

def absolute_name
  @absolute_name
end

28
29
30

# File 'lib/rdoc/top_level.rb', line 28

def classes_or_modules
  @classes_or_modules
end

30
31
32

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

def diagram
  @diagram
end

11
12
13

# File 'lib/rdoc/top_level.rb', line 11

def file_stat
  @file_stat
end

35
36
37

# File 'lib/rdoc/top_level.rb', line 35

def parser
  @parser
end

16
17
18

# File 'lib/rdoc/top_level.rb', line 16

def relative_name
  @relative_name
end

40
41
42

# File 'lib/rdoc/top_level.rb', line 40

def self.all_classes
  @all_classes_hash.values
end

47
48
49

# File 'lib/rdoc/top_level.rb', line 47

def self.all_classes_and_modules
  @all_classes_hash.values + @all_modules_hash.values
end

54
55
56

# File 'lib/rdoc/top_level.rb', line 54

def self.all_classes_hash
  @all_classes_hash
end

61
62
63

# File 'lib/rdoc/top_level.rb', line 61

def self.all_files
  @all_files_hash.values
end

68
69
70

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

def self.all_files_hash
  @all_files_hash
end

75
76
77

# File 'lib/rdoc/top_level.rb', line 75

def self.all_modules
  all_modules_hash.values
end

82
83
84

# File 'lib/rdoc/top_level.rb', line 82

def self.all_modules_hash
  @all_modules_hash
end

102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

# File 'lib/rdoc/top_level.rb', line 102

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 RDoc::Parser::Simple === tl.parser 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

140
141
142

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

def self.find_class_named(name)
  @all_classes_hash[name]
end

147
148
149
150
151
152
153
154
155
156
157
158
159
160

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

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

165
166
167
168

# File 'lib/rdoc/top_level.rb', line 165

def self.find_class_or_module(name)
  name = $' if name =~ /^::/
  RDoc::TopLevel.classes_hash[name] || RDoc::TopLevel.modules_hash[name]
end

173
174
175

# File 'lib/rdoc/top_level.rb', line 173

def self.find_file_named(name)
  @all_files_hash[name]
end

180
181
182

# File 'lib/rdoc/top_level.rb', line 180

def self.find_module_named(name)
  modules_hash[name]
end

191
192
193
194
195
196
197
198
199

# File 'lib/rdoc/top_level.rb', line 191

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

212
213
214
215
216
217
218
219
220

# File 'lib/rdoc/top_level.rb', line 212

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

227
228
229
230
231
232

# File 'lib/rdoc/top_level.rb', line 227

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

237
238
239
240
241

# File 'lib/rdoc/top_level.rb', line 237

def self.reset
  @all_classes_hash = {}
  @all_modules_hash = {}
  @all_files_hash   = {}
end

248
249
250

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

def self.unique_classes
  @unique_classes
end

256
257
258

# File 'lib/rdoc/top_level.rb', line 256

def self.unique_classes_and_modules
  @unique_classes + @unique_modules
end

264
265
266

# File 'lib/rdoc/top_level.rb', line 264

def self.unique_modules
  @unique_modules
end

301
302
303
304

# File 'lib/rdoc/top_level.rb', line 301

def add_alias(an_alias)
  return an_alias unless @document_self
  object_class.add_alias an_alias
end

309
310
311
312

# File 'lib/rdoc/top_level.rb', line 309

def add_constant(constant)
  return constant unless @document_self
  object_class.add_constant constant
end

317
318
319
320

# File 'lib/rdoc/top_level.rb', line 317

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

325
326
327
328

# File 'lib/rdoc/top_level.rb', line 325

def add_method(method)
  return method unless @document_self
  object_class.add_method method
end

334
335
336

# File 'lib/rdoc/top_level.rb', line 334

def add_to_classes_or_modules mod
  @classes_or_modules << mod
end

341
342
343

# File 'lib/rdoc/top_level.rb', line 341

def base_name
  File.basename @absolute_name
end

195
196
197
198
199
200
201
202
203

# File 'lib/rdoc/generator/markup.rb', line 195

def cvs_url
  url = RDoc::RDoc.current.options.webcvs

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

ones of this instance?

353
354
355

# File 'lib/rdoc/top_level.rb', line 353

def find_class_or_module name
  RDoc::TopLevel.find_class_or_module name
end

360
361
362

# File 'lib/rdoc/top_level.rb', line 360

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

367
368
369

# File 'lib/rdoc/top_level.rb', line 367

def find_module_named(name)
  find_class_or_module(name)
end

374
375
376

# File 'lib/rdoc/top_level.rb', line 374

def full_name
  @relative_name
end

381
382
383
384
385

# File 'lib/rdoc/top_level.rb', line 381

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

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

387
388
389
390
391
392
393
394

# File 'lib/rdoc/top_level.rb', line 387

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

399
400
401

# File 'lib/rdoc/top_level.rb', line 399

def last_modified
  @file_stat ? file_stat.mtime : nil
end

408
409
410
411
412
413
414

# File 'lib/rdoc/top_level.rb', line 408

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

419
420
421

# File 'lib/rdoc/top_level.rb', line 419

def path
  http_url RDoc::RDoc.current.generator.file_dir
end

423
424
425
426
427
428
429
430
431
432

# File 'lib/rdoc/top_level.rb', line 423

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

434
435
436

# File 'lib/rdoc/top_level.rb', line 434

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