Class: RDoc::Mixin

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses: Extend, Include
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, CodeObject
Instance Chain: self, CodeObject, Generator::Markup, Text
Inherits:	RDoc::CodeObject Object RDoc::CodeObject RDoc::Mixin
Defined in:	lib/rdoc/mixin.rb

Overview

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

Constant Summary

Text - Included

MARKUP_FORMAT, TO_HTML_CHARACTERS

Class Method Summary

.new(name, comment) ⇒ Mixin constructor

Creates a new Mixin for #name with comment

CodeObject - Inherited

.new	Creates a new CodeObject that will document itself and its children.

Instance Attribute Summary

#name rw

Name of included module.
#store=(store) writeonly

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

CodeObject - Inherited

#comment	Our comment.
#comment=	Replaces our comment with `comment`, unless it is empty.
#document_children	Do we document our children?
#document_children=	Enables or disables documentation of this CodeObject's children unless it has been turned off by :enddoc:
#document_self	Do we document ourselves?
#document_self=	Enables or disables documentation of this CodeObject unless it has been turned off by :enddoc:.
#done_documenting	Are we done documenting (ie, did we come across a :enddoc:)?
#done_documenting=	Turns documentation on/off, and turns on/off `#document_self` and `#document_children`.
#force_documentation	Force documentation of this CodeObject.
#force_documentation=	Force the documentation of this object unless documentation has been turned off by :enddoc:
#line	Line in `#file` where this CodeObject was defined.
#offset	Offset in `#file` where this CodeObject was defined.
#parent	Our parent CodeObject.
#parent=	Sets the parent CodeObject.
#section	The section this CodeObject is in.
#section=	Set the section this CodeObject is in.
#store	The Store for this object.
#store=	Sets the `store` that contains this CodeObject.
#viewer	We are the model of the code, but we know that at some point we will be worked on by viewers.
#display?	Should this CodeObject be displayed in output?
#documented?	Does this object have a comment with content or is `#received_nodoc` true?
#file	Which file this code object was defined in.
#ignored?	Has this class been ignored?
#metadata	Hash of arbitrary metadata for this CodeObject.
#received_nodoc	Did we ever receive a `:nodoc:` directive?
#suppressed?	Has this class been suppressed?
#full_name=	Sets the full_name overriding any computed full name.

Instance Method Summary

#<=>(other)

Mixins are sorted by name.
#full_name

Full name based on #module
#module

Attempts to locate the included module object.

CodeObject - Inherited

#each_parent	Yields each parent of this CodeObject.
#file_name	File name where this CodeObject was found.
#ignore	Use this to ignore a CodeObject and all its children until found again (#record_location is called).
#options	The options instance from the store this CodeObject is attached to, or a default options instance if the CodeObject is not attached.
#parent_file_name	File name of our parent.
#parent_name	Name of our parent.
#record_location	Records the TopLevel (file) where this code object was defined.
#start_doc	Enable capture of documentation unless documentation has been turned off by :enddoc:
#stop_doc	Disable capture of documentation.
#suppress	Use this to suppress a CodeObject and all its children until the next file it is seen in or documentation is discovered.

Generator::Markup - Included

#aref_to	Generates a relative URL from this object's path to `target_path`
#as_href	Generates a relative URL from `from_path` to this object's path.
#cvs_url	Build a webcvs URL starting for the given `url` with `full_path` appended as the destination path.
#description	Handy wrapper for marking up this object's comment.
#formatter	Creates an Markup::ToHtmlCrossref formatter.

Text - Included

#expand_tabs	Expands tab characters in `text` to eight spaces.
#flush_left	Flush `text` left based on the shortest line.
#markup	Convert a string in markup format into HTML.
#normalize_comment	Strips hashes, expands tabs then flushes `text` to the left.
#parse	Normalizes `text` then builds a Markup::Document from it.
#snippet	The first `limit` characters of `text` as HTML.
#strip_hashes	Strips leading # characters from `text`
#strip_newlines	Strips leading and trailing n characters from `text`
#strip_stars	Strips /* */ style comments.
#to_html	Converts ampersand, dashes, ellipsis, quotes, copyright and registered trademark symbols in `text` to properly encoded characters.
#wrap	Wraps `txt` to `line_len`

Constructor Details

.new(name, comment) ⇒ `Mixin`

Creates a new Mixin for #name with comment

[ GitHub ]

# File 'lib/rdoc/mixin.rb', line 15


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

Instance Attribute Details

#name (rw)

Name of included module

[ GitHub ]

# File 'lib/rdoc/mixin.rb', line 10


attr_accessor :name

#store=(store) (writeonly)

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

[ GitHub ]

# File 'lib/rdoc/mixin.rb', line 109


def store= store
  super

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

Instance Method Details

#<=>(other)

Mixins are sorted by name

[ GitHub ]

# File 'lib/rdoc/mixin.rb', line 25


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

  name <=> other.name
end

#full_name

Full name based on #module

[ GitHub ]

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


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

#module

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.

[ GitHub ]

# File 'lib/rdoc/mixin.rb', line 74


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

Class: RDoc::Mixin

Overview

Constant Summary

Text - Included

Class Method Summary

CodeObject - Inherited

Instance Attribute Summary

CodeObject - Inherited

Instance Method Summary

CodeObject - Inherited

Generator::Markup - Included

Text - Included

Constructor Details

.new(name, comment) ⇒ Mixin

Instance Attribute Details

#name (rw)

#store=(store) (writeonly)

Instance Method Details

#<=>(other)

#full_name

#module

.new(name, comment) ⇒ `Mixin`