Class: RDoc::ClassModule

Inherits:
Context show all
Defined in:
lib/rdoc/class_module.rb

Overview

ClassModule is the base class for objects representing either a class or a module.

Constant Summary

MARSHAL_VERSION =

:nodoc:

0

Constants inherited from Context

RDoc::Context::TYPES

Constants included from Text

Text::TO_HTML_CHARACTERS

Instance Attribute Summary (collapse)

Attributes inherited from Context

#aliases, #attributes, #constants, #constants_hash, #current_section, #external_aliases, #in_files, #includes, #method_list, #methods_hash, #name, #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)

Instance Method Summary (collapse)

Methods inherited from Context

#<=>, #add_alias, #add_attribute, #add_class, #add_class_or_module, #add_constant, #add_include, #add_method, #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_local_symbol, #find_method, #find_method_named, #find_module_named, #find_symbol, #find_symbol_module, #fully_documented?, #http_url, #initialize_methods_etc, #instance_attributes, #instance_method_list, #methods_by_type, #methods_matching, #modules, #modules_hash, #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, #cvs_url, #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

Constructor Details

- (ClassModule) initialize(name, superclass = nil)

Creates a new ClassModule with name with optional superclass

This is a constructor for subclasses, and must never be called directly.



82
83
84
85
86
87
88
89
 
# File 'lib/rdoc/class_module.rb', line 82

def initialize(name, superclass = nil)
  @constant_aliases = []
  @diagram          = nil
  @is_alias_for     = nil
  @name             = name
  @superclass       = superclass
  super()
end

Instance Attribute Details

- (Object) constant_aliases

Constants that are aliases for this class or module



14
15
16
 
# File 'lib/rdoc/class_module.rb', line 14

def constant_aliases
  @constant_aliases
end

- (Object) diagram

:nodoc:



16
17
18
 
# File 'lib/rdoc/class_module.rb', line 16

def diagram
  @diagram
end

- (Object) is_alias_for

Class or module this constant is an alias for



21
22
23
 
# File 'lib/rdoc/class_module.rb', line 21

def is_alias_for
  @is_alias_for
end

Class Method Details

+ (Object) from_module(class_type, mod)

Return a RDoc::ClassModule of class class_type that is a copy of module module. Used to promote modules to classes.



27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/rdoc/class_module.rb', line 27

def self.from_module(class_type, mod)
  klass = class_type.new(mod.name)
  klass.comment = mod.comment
  klass.parent = mod.parent
  klass.section = mod.section
  klass.viewer = mod.viewer

  klass.attributes.concat mod.attributes
  klass.method_list.concat mod.method_list
  klass.aliases.concat mod.aliases
  klass.external_aliases.concat mod.external_aliases
  klass.constants.concat mod.constants
  klass.includes.concat mod.includes

  klass.methods_hash.update mod.methods_hash
  klass.constants_hash.update mod.constants_hash

  klass.current_section = mod.current_section
  klass.in_files.concat mod.in_files
  klass.sections.concat mod.sections
  klass.unmatched_alias_lists = mod.unmatched_alias_lists
  klass.current_section = mod.current_section
  klass.visibility = mod.visibility

  klass.classes_hash.update mod.classes_hash
  klass.modules_hash.update mod.modules_hash
  klass.metadata.update mod.metadata

  klass.document_self = mod.received_nodoc ? nil : mod.document_self
  klass.document_children = mod.document_children
  klass.force_documentation = mod.force_documentation
  klass.done_documenting = mod.done_documenting

  # update the parent of all children

  (klass.attributes +
   klass.method_list +
   klass.aliases +
   klass.external_aliases +
   klass.constants +
   klass.includes +
   klass.classes +
   klass.modules).each do |obj|
    obj.parent = klass
    obj.full_name = nil
  end

  klass
end

Instance Method Details

- (Object) ancestors

Ancestors list for this ClassModule: the list of included modules (classes will add their superclass if any).

Returns the included classes or modules, not the includes themselves. The returned values are either String or RDoc::NormalModule instances (see RDoc::Include#module).

The values are returned in reverse order of their inclusion, which is the order suitable for searching methods/attributes in the ancestors. The superclass, if any, comes last.



103
104
105
 
# File 'lib/rdoc/class_module.rb', line 103

def ancestors
  includes.map { |i| i.module }.reverse
end

- (Object) clear_comment

Clears the comment. Used by the ruby parser.



110
111
112
 
# File 'lib/rdoc/class_module.rb', line 110

def clear_comment
  @comment = ''
end

- (Object) comment=(comment)

Appends comment to the current comment, but separated by a rule. Works more like +=.



118
119
120
121
122
123
124
125
126
 
# File 'lib/rdoc/class_module.rb', line 118

def comment= comment
  return if comment.empty?

  comment = normalize_comment comment
  comment = "#{@comment}\n---\n#{comment}" unless
    @comment.empty?

  super
end

- (Object) complete(min_visibility)

Prepares this ClassModule for use by a generator.

See RDoc::TopLevel::complete



133
134
135
136
137
138
 
# File 'lib/rdoc/class_module.rb', line 133

def complete min_visibility
  update_aliases
  remove_nodoc_children
  update_includes
  remove_invisible min_visibility
end

- (Object) find_ancestor_local_symbol(symbol)

Looks for a symbol in the #ancestors. See Context#find_local_symbol.



143
144
145
146
147
148
149
150
151
 
# File 'lib/rdoc/class_module.rb', line 143

def find_ancestor_local_symbol symbol
  ancestors.each do |m|
    next if m.is_a?(String)
    res = m.find_local_symbol(symbol)
    return res if res
  end

  nil
end

- (Object) find_class_named(name)

Finds a class or module with name in this namespace or its descendants



156
157
158
159
160
161
162
163
164
 
# File 'lib/rdoc/class_module.rb', line 156

def find_class_named name
  return self if full_name == name
  return self if @name == name

  @classes.values.find do |klass|
    next if klass == self
    klass.find_class_named name
  end
end

- (Object) full_name

Return the fully qualified name of this class or module



169
170
171
172
173
174
175
 
# File 'lib/rdoc/class_module.rb', line 169

def full_name
  @full_name ||= if RDoc::ClassModule === @parent then
                   "#{@parent.full_name}::#{@name}"
                 else
                   @name
                 end
end

- (Object) marshal_dump

:nodoc:



177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/rdoc/class_module.rb', line 177

def marshal_dump # :nodoc:
  # TODO must store the singleton attribute
  attrs = attributes.sort.map do |attr|
    [attr.name, attr.rw]
  end

  method_types = methods_by_type.map do |type, visibilities|
    visibilities = visibilities.map do |visibility, methods|
      method_names = methods.map do |method|
        method.name
      end

      [visibility, method_names.uniq]
    end

    [type, visibilities]
  end

  [ MARSHAL_VERSION,
    @name,
    full_name,
    @superclass,
    parse(@comment),
    attrs,
    constants.map do |const|
      [const.name, parse(const.comment)]
    end,
    includes.map do |incl|
      [incl.name, parse(incl.comment)]
    end,
    method_types,
  ]
end

- (Object) marshal_load(array)

:nodoc:



211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/rdoc/class_module.rb', line 211

def marshal_load array # :nodoc:
  # TODO must restore the singleton attribute
  initialize_methods_etc
  @document_self    = true
  @done_documenting = false
  @current_section  = nil
  @parent           = nil
  @visibility       = nil

  @name       = array[1]
  @full_name  = array[2]
  @superclass = array[3]
  @comment    = array[4]

  array[5].each do |name, rw|
    add_attribute RDoc::Attr.new(nil, name, rw, nil)
  end

  array[6].each do |name, comment|
    add_constant RDoc::Constant.new(name, nil, comment)
  end

  array[7].each do |name, comment|
    add_include RDoc::Include.new(name, comment)
  end

  array[8].each do |type, visibilities|
    visibilities.each do |visibility, methods|
      @visibility = visibility

      methods.each do |name|
        method = RDoc::AnyMethod.new nil, name
        method.singleton = true if type == 'class'
        add_method method
      end
    end
  end
end

- (Object) merge(class_module)

Merges class_module into this ClassModule



253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/rdoc/class_module.rb', line 253

def merge class_module
  comment = class_module.comment

  if comment then
    document = parse @comment

    comment.parts.concat document.parts

    @comment = comment
  end

  class_module.each_attribute do |attr|
    if match = attributes.find { |a| a.name == attr.name } then
      match.rw = [match.rw, attr.rw].compact.join
    else
      add_attribute attr
    end
  end

  class_module.each_constant do |const|
    add_constant const
  end

  class_module.each_include do |incl|
    add_include incl
  end

  class_module.each_method do |meth|
    add_method meth
  end
end

- (Boolean) module?

Does this object represent a module?

Returns:

  • (Boolean) 


288
289
290
 
# File 'lib/rdoc/class_module.rb', line 288

def module?
  false
end

- (Object) name=(new_name)

Allows overriding the initial name.

Used for modules and classes that are constant aliases.



297
298
299
 
# File 'lib/rdoc/class_module.rb', line 297

def name= new_name
  @name = new_name
end

- (Object) name_for_path

Name to use to generate the url: modules and classes that are aliases for another module or class return the name of the latter.



313
314
315
 
# File 'lib/rdoc/class_module.rb', line 313

def name_for_path
  is_alias_for ? is_alias_for.full_name : full_name
end

- (Object) non_aliases

Returns the classes and modules that are not constants aliasing another class or module. For use by formatters only (caches its result).



322
323
324
 
# File 'lib/rdoc/class_module.rb', line 322

def non_aliases
  @non_aliases ||= classes_and_modules.reject { |cm| cm.is_alias_for }
end

- (Object) path

Path to this class or module



304
305
306
 
# File 'lib/rdoc/class_module.rb', line 304

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

- (Object) remove_nodoc_children

Updates the child modules or classes of class/module parent by deleting the ones that have been removed from the documentation.

parent_hash is either parent.modules_hash or parent.classes_hash and all_hash is ::all_modules_hash or ::all_classes_hash.



334
335
336
337
338
339
340
341
342
343
344
345
346
 
# File 'lib/rdoc/class_module.rb', line 334

def remove_nodoc_children
  prefix = self.full_name + '::'

  modules_hash.each_key do |name|
    full_name = prefix + name
    modules_hash.delete name unless RDoc::TopLevel.all_modules_hash[full_name]
  end

  classes_hash.each_key do |name|
    full_name = prefix + name
    classes_hash.delete name unless RDoc::TopLevel.all_classes_hash[full_name]
  end
end

- (Object) superclass

Get the superclass of this class. Attempts to retrieve the superclass object, returns the name if it is not known.



352
353
354
 
# File 'lib/rdoc/class_module.rb', line 352

def superclass
  RDoc::TopLevel.find_class_named(@superclass) || @superclass
end

- (Object) superclass=(superclass)

Set the superclass of this class to superclass

Raises:

  • (NoMethodError) 


359
360
361
362
 
# File 'lib/rdoc/class_module.rb', line 359

def superclass=(superclass)
  raise NoMethodError, "#{full_name} is a module" if module?
  @superclass = superclass
end

- (Object) to_s

:nodoc:



364
365
366
367
368
369
370
 
# File 'lib/rdoc/class_module.rb', line 364

def to_s # :nodoc:
  if is_alias_for then
    "#{self.class.name} #{self.full_name} -> #{is_alias_for}"
  else
    super
  end
end

- (Object) type

'module' or 'class'



375
376
377
 
# File 'lib/rdoc/class_module.rb', line 375

def type
  module? ? 'module' : 'class'
end

- (Object) update_aliases

Updates the child modules & classes by replacing the ones that are aliases through a constant.

The aliased module/class is replaced in the children and in RDoc::TopLevel::all_modules_hash or RDoc::TopLevel::all_classes_hash by a copy that has RDoc::ClassModule#is_alias_for set to the aliased module/class, and this copy is added to #aliases of the aliased module/class.

Formatters can use the #non_aliases method to retrieve children that are not aliases, for instance to list the namespace content, since the aliased modules are included in the constants of the class/module, that are listed separately.



394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
 
# File 'lib/rdoc/class_module.rb', line 394

def update_aliases
  constants.each do |const|
    next unless cm = const.is_alias_for
    cm_alias = cm.dup
    cm_alias.name = const.name
    cm_alias.parent = self
    cm_alias.full_name = nil  # force update for new parent
    cm_alias.aliases.clear
    cm_alias.is_alias_for = cm

    if cm.module? then
      RDoc::TopLevel.all_modules_hash[cm_alias.full_name] = cm_alias
      modules_hash[const.name] = cm_alias
    else
      RDoc::TopLevel.all_classes_hash[cm_alias.full_name] = cm_alias
      classes_hash[const.name] = cm_alias
    end

    cm.aliases << cm_alias
  end
end

- (Object) update_includes

Deletes from #includes those whose module has been removed from the documentation. -- FIXME: includes are not reliably removed, see _possible_bug test case



422
423
424
425
426
427
 
# File 'lib/rdoc/class_module.rb', line 422

def update_includes
  includes.reject! do |include|
    mod = include.module
    !(String === mod) && RDoc::TopLevel.all_modules_hash[mod.full_name].nil?
  end
end