Class: RDoc::Mixin

Inherits:
CodeObject show all
Defined in:
lib/rdoc/code_object/mixin.rb

Overview

A Mixin adds features from a module into another context. RDoc::Include and RDoc::Extend are both mixins.

Direct Known Subclasses

Extend, Include

Constant Summary

Constants included from Text

Text::MARKUP_FORMAT, Text::SPACE_SEPARATED_LETTER_CLASS

Instance Attribute Summary collapse

Attributes inherited from CodeObject

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

Attributes included from Text

#language

Instance Method Summary collapse

Methods inherited from CodeObject

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

Methods included from Generator::Markup

#aref_to, #as_href, #canonical_url, #cvs_url, #description, #formatter

Methods included from Text

decode_legacy_label, expand_tabs, #flush_left, #markup, #normalize_comment, #parse, #snippet, #strip_hashes, #strip_newlines, #strip_stars, to_anchor, #wrap

Constructor Details

#initialize(name, comment) ⇒ Mixin

Creates a new Mixin for name with comment



17
18
19
20
21
22
 
# File 'lib/rdoc/code_object/mixin.rb', line 17

def initialize(name, comment)
  super()
  @name = name
  self.comment = comment
  @module = nil # cache for module if found
end

Instance Attribute Details

#name ⇒ Object

Name of included module



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

def name
  @name
end

Instance Method Details

#<=>(other) ⇒ Object

Mixins are sorted by name



27
28
29
30
31
 
# File 'lib/rdoc/code_object/mixin.rb', line 27

def <=>(other)
  return unless self.class === other

  name <=> other.name
end

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

:nodoc:



33
34
35
 
# File 'lib/rdoc/code_object/mixin.rb', line 33

def ==(other) # :nodoc:
  self.class === other and @name == other.name
end

#full_name ⇒ Object

Full name based on #module



42
43
44
45
 
# File 'lib/rdoc/code_object/mixin.rb', line 42

def full_name
  m = self.module
  ClassModule === m ? m.full_name : @name
end

#hash ⇒ Object

:nodoc:



47
48
49
 
# File 'lib/rdoc/code_object/mixin.rb', line 47

def hash # :nodoc:
  [@name, self.module].hash
end

#inspect ⇒ Object

:nodoc:



51
52
53
54
55
56
57
 
# File 'lib/rdoc/code_object/mixin.rb', line 51

def inspect # :nodoc:
  "#<%s:0x%x %s.%s %s>" % [
    self.class,
    object_id,
    parent_name, self.class.name.downcase, @name,
  ]
end

#module ⇒ Object

Attempts to locate the included module object. Returns the name if not known.

The scoping rules of Ruby to resolve the name of an included module are:

  • first look into the children of the current context;
  • if not found, look into the children of included modules, in reverse inclusion order;
  • if still not found, go up the hierarchy of names.

This method has O(n!) behavior when the module calling include is referencing nonexistent modules. Avoid calling #module until after all the files are parsed. This behavior is due to ruby's constant lookup behavior.

As of the beginning of October, 2011, no gem includes nonexistent modules.

The Ruby parser passes an already-resolved full-path name, so most of this logic only runs for the C parser, which passes the unresolved local name.



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/rdoc/code_object/mixin.rb', line 79

def module
  return @module if @module

  # search the current context
  return @name unless parent
  full_name = parent.child_name(@name)
  @module = @store.modules_hash[full_name]
  return @module if @module
  return @name if @name =~ /^::/

  # search the includes before this one, in reverse order
  searched = parent.includes.take_while { |i| i != self }.reverse
  searched.each do |i|
    inc = i.module
    next if String === inc
    full_name = inc.child_name(@name)
    @module = @store.modules_hash[full_name]
    return @module if @module
  end

  # go up the hierarchy of names
  up = parent.parent
  while up
    full_name = up.child_name(@name)
    @module = @store.modules_hash[full_name]
    return @module if @module
    up = up.parent
  end

  @name
end

#store=(store) ⇒ Object

Sets the store for this class or module and its contained code objects.



114
115
116
117
118
 
# File 'lib/rdoc/code_object/mixin.rb', line 114

def store=(store)
  super

  @file = @store.add_file @file.full_name if @file
end

#to_s ⇒ Object

:nodoc:



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

def to_s # :nodoc:
  "#{self.class.name.downcase} #@name in: #{parent}"
end