123456789_123456789_123456789_123456789_123456789_

Class: RDoc::Mixin

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses:
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, CodeObject
Instance Chain:
Inherits: RDoc::CodeObject
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

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

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