Class: RDoc::TopLevel

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, Context, CodeObject
Instance Chain: self, Context, Comparable, CodeObject, Generator::Markup, Text
Inherits:	RDoc::Context Object RDoc::CodeObject RDoc::Context RDoc::TopLevel
Defined in:	lib/rdoc/top_level.rb, lib/rdoc/generator/markup.rb

Overview

A TopLevel context is a representation of the contents of a single file

Constant Summary

Text - Included

MARKUP_FORMAT, TO_HTML_CHARACTERS

Context - Inherited

TYPES

Class Method Summary

.new(absolute_name, relative_name = absolute_name) ⇒ TopLevel constructor

Creates a new TopLevel for the file at #absolute_name.

Context - Inherited

.new	Creates an unnamed empty context with public current visibility.

CodeObject - Inherited

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

Instance Attribute Summary

#absolute_name rw

Absolute name of this file.
#file_stat rw

This TopLevel's File::Stat struct.
#parser rw

The parser class that processed this file.
#relative_name rw

Relative name of this file.
#classes_or_modules readonly

All the classes or modules that were declared in this file.
#display? ⇒ Boolean readonly

Only a TopLevel that contains text file) will be displayed.
#text? ⇒ Boolean readonly

Is this TopLevel from a text file instead of a source code file?

Context - Inherited

#block_params	Block params to be used in the next MethodAttr parsed under this context.
#current_section	The current documentation section that new items will be added to.
#current_section=	Sets the current documentation section of documentation.
#params	Params to be used in the next MethodAttr parsed under this context.
#temporary_section	Use this section for the next method, attribute or constant added.
#unmatched_alias_lists	Hash `old_name => [aliases]`, for aliases that haven't (yet) been resolved to a method/attribute.
#visibility	Current visibility of this context.
#aliases	Class/module aliases.
#attributes	All attr* methods.
#constants	Constants defined.
#constants_hash	Hash of registered constants.
#extends	Modules this context is extended with.
#external_aliases	Aliases that could not be resolved.
#fully_documented?	Does this context and its methods and constants all have documentation?
#in_files	Files this context is found in.
#includes	Modules this context includes.
#method_list	Methods defined in this context.
#methods_hash	Hash of registered methods.
#name	Name of this class excluding namespace.
#remove_from_documentation?	Should we remove this context from the documentation?
#requires	Files this context requires.
#ongoing_visibility=	Changes the visibility for new methods to `visibility`

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) (also: #eql?)

An TopLevel is equal to another with the same relative_name.
#add_alias(an_alias)

Adds an_alias to Object instead of self.
#add_constant(constant)

Adds constant to Object instead of self.
#add_include(include)

Adds include to Object instead of self.
#add_method(method)

Adds method to Object instead of self.
#add_to_classes_or_modules(mod)

Adds class or module mod.
#base_name (also: #name)

Base name of this file.
#cvs_url

Returns a URL for this source file on some web repository.
#eql?(other)

Alias for #==.
#find_class_or_module(name)

See #find_class_or_module
#find_local_symbol(symbol)

Finds a class or module named symbol
#find_module_named(name)

Finds a module or class with #name
#full_name

Returns the relative name of this file.
#hash

An TopLevel has the same hash as another with the same relative_name.
#http_url(prefix)

URL for this with a prefix
#last_modified

Time this file was last modified, if known.
#marshal_dump

Dumps this TopLevel for use by ri.
#name

Alias for #base_name.
#object_class

Returns the NormalClass “Object”, creating it if not found.
#page_name

Base name of this file without the extension.
#path

Path to this file for use with HTML generator output.
#search_record

Search record used by Generator::JsonIndex

Context - Inherited

#<=>	Contexts are sorted by full_name.
#add	Adds an item of type `klass` with the given #name and `comment` to the context.
#add_alias	Adds `an_alias` that is automatically resolved.
#add_attribute	Adds `attribute` if not already there.
#add_class	Adds a class named `given_name` with `superclass`.
#add_class_or_module	Adds the class or module `mod` to the modules or classes Hash `self_hash`, and to `all_hash` (either `TopLevel.modules_hash` or `TopLevel.classes_hash`), unless `#done_documenting` is `true`.
#add_constant	Adds `constant` if not already there.
#add_extend	Adds extension module `ext` which should be an Extend
#add_include	Adds included module `include` which should be an Include
#add_method	Adds `method` if not already there.
#add_module	Adds a module named #name.
#add_module_alias	Adds an alias from `from` (a class or module) to #name which was defined in `file`.
#add_require	Adds `require` to this context's top level.
#add_section	Returns a section with `title`, creating it if it doesn't already exist.
#add_to	Adds `thing` to the collection `array`
#any_content	Is there any content?
#child_name	Creates the full name for a child with #name
#class_attributes	Class attributes.
#class_method_list	Class methods.
#classes	Array of classes in this context.
#classes_and_modules	All classes and modules in this namespace.
#classes_hash	Hash of classes keyed by class name.
#defined_in?	Is part of this thing was defined in `file`?
#each_attribute	Iterator for attributes.
#each_classmodule	Iterator for classes and modules.
#each_constant	Iterator for constants.
#each_extend	Iterator for extension modules.
#each_include	Iterator for included modules.
#each_method	Iterator for methods.
#each_section	Iterator for each section's contents sorted by title.
#find_attribute	Finds an attribute #name with singleton value `singleton`.
#find_attribute_named	Finds an attribute with #name in this context.
#find_class_method_named	Finds a class method with #name in this context.
#find_constant_named	Finds a constant with #name in this context.
#find_enclosing_module_named	Find a module at a higher scope.
#find_external_alias	Finds an external alias #name with singleton value `singleton`.
#find_external_alias_named	Finds an external alias with #name in this context.
#find_file_named	Finds a file with #name in this context.
#find_instance_method_named	Finds an instance method with #name in this context.
#find_local_symbol	Finds a method, constant, attribute, external alias, module or file named `symbol` in this context.
#find_method	Finds a method named #name with singleton value `singleton`.
#find_method_named	Finds a instance or module method with #name in this context.
#find_module_named	Find a module with #name using ruby's scoping rules.
#find_symbol	Look up `symbol`, first as a module, then as a local symbol.
#find_symbol_module	Look up a module named `symbol`.
#full_name	The full name for this context.
#http_url	URL for this with a `prefix`
#initialize_methods_etc	Sets the defaults for methods and so-forth.
#instance_attributes	Instance attributes.
#instance_method_list	Instance methods.
#methods_by_type	Breaks method_list into a nested hash by type (`'class'` or `'instance'`) and visibility (`:public`, `:protected`, `:private`).
#methods_matching	Yields AnyMethod and Attr entries matching the list of names in `methods`.
#modules	Array of modules in this context.
#modules_hash	Hash of modules keyed by module name.
#name_for_path	Name to use to generate the url.
#record_location	Record `top_level` as a file `self` is in.
#remove_invisible	Removes methods and attributes with a visibility less than `min_visibility`.
#resolve_aliases	Tries to resolve unmatched aliases when a method or attribute has just been added.
#section_contents	Returns Context::Section objects referenced in this context for use in a table of contents.
#sections	Sections in this context.
#set_current_section	Sets the current section to a section with `title`.
#set_visibility_for	Given an array `methods` of method names, set the visibility of each to `visibility`
#sort_sections	Sorts sections alphabetically (default) or in TomDoc fashion (none, Public, Internal, Deprecated).
#top_level	Return the `TopLevel` that owns us.
#upgrade_to_class	Upgrades NormalModule `mod` in `enclosing` to a `class_type`

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(absolute_name, relative_name = absolute_name) ⇒ `TopLevel`

Creates a new TopLevel for the file at #absolute_name. If documentation is being generated outside the source dir #relative_name is relative to the source directory.

[ GitHub ]

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


def initialize absolute_name, relative_name = absolute_name
  super()
  @name = nil
  @absolute_name = absolute_name
  @relative_name = relative_name
  @file_stat     = File.stat(absolute_name) rescue nil # HACK for testing
  @diagram       = nil
  @parser        = nil

  @classes_or_modules = []
end

Instance Attribute Details

#absolute_name (rw)

Absolute name of this file

[ GitHub ]

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


attr_accessor :absolute_name

#classes_or_modules (readonly)

All the classes or modules that were declared in this file. These are assigned to either #classes_hash or #modules_hash once we know what they really are.

[ GitHub ]

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


attr_reader :classes_or_modules

#display? ⇒ `Boolean` (readonly)

Only a TopLevel that contains text file) will be displayed. See also CodeObject#display?

[ GitHub ]

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


def display?
  text? and super
end

#file_stat (rw)

This TopLevel's File::Stat struct

[ GitHub ]

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


attr_accessor :file_stat

#parser (rw)

The parser class that processed this file

[ GitHub ]

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


attr_accessor :parser

#relative_name (rw)

Relative name of this file

[ GitHub ]

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


attr_accessor :relative_name

#text? ⇒ `Boolean` (readonly)

Is this TopLevel from a text file instead of a source code file?

[ GitHub ]

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


def text?
  @parser and @parser.ancestors.include? RDoc::Parser::Text
end

Instance Method Details

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

An TopLevel is equal to another with the same relative_name

[ GitHub ]

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


def == other
  self.class === other and @relative_name == other.relative_name
end

#add_alias(an_alias)

Adds an_alias to Object instead of self.

[ GitHub ]

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


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

#add_constant(constant)

Adds constant to Object instead of self.

[ GitHub ]

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


def add_constant constant
  object_class.record_location self
  return constant unless @document_self
  object_class.add_constant constant
end

#add_include(include)

Adds include to Object instead of self.

[ GitHub ]

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


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

#add_method(method)

Adds method to Object instead of self.

[ GitHub ]

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


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

#add_to_classes_or_modules(mod)

Adds class or module mod. Used in the building phase by the Ruby parser.

[ GitHub ]

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


def add_to_classes_or_modules mod
  @classes_or_modules << mod
end

#base_name Also known as: #name

Base name of this file

[ GitHub ]

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


def base_name
  File.basename @relative_name
end

#cvs_url

Returns a URL for this source file on some web repository. Use the -W command line option to set.

[ GitHub ]

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


def cvs_url
  url = @store.rdoc.options.webcvs

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

#eql?(other)

Alias for #==.

[ GitHub ]

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


alias eql? ==

#find_class_or_module(name)

See #find_class_or_module

[ GitHub ]

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


def find_class_or_module name
  @store.find_class_or_module name
end

#find_local_symbol(symbol)

Finds a class or module named symbol

[ GitHub ]

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


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

#find_module_named(name)

Finds a module or class with #name

[ GitHub ]

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


def find_module_named(name)
  find_class_or_module(name)
end

#full_name

Returns the relative name of this file

[ GitHub ]

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


def full_name
  @relative_name
end

#hash

An TopLevel has the same hash as another with the same relative_name

[ GitHub ]

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


def hash
  @relative_name.hash
end

#http_url(prefix)

URL for this with a prefix

[ GitHub ]

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


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

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

#last_modified

Time this file was last modified, if known

[ GitHub ]

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


def last_modified
  @file_stat ? file_stat.mtime : nil
end

#marshal_dump

Dumps this TopLevel for use by ri. See also #marshal_load

[ GitHub ]

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


def marshal_dump
  [
    MARSHAL_VERSION,
    @relative_name,
    @parser,
    parse(@comment),
  ]
end

#name

Alias for #base_name.

[ GitHub ]

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


alias name base_name

#object_class

Returns the NormalClass “Object”, creating it if not found.

Records self as a location in “Object”.

[ GitHub ]

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


def object_class
  @object_class ||= begin
    oc = @store.find_class_named('Object') || add_class(RDoc::NormalClass, 'Object')
    oc.record_location self
    oc
  end
end

#page_name

Base name of this file without the extension

[ GitHub ]

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


def page_name
  basename = File.basename @relative_name
  basename =~ /\.(rb|rdoc|txt|md)$/i

  $` || basename
end

#path

Path to this file for use with HTML generator output.

[ GitHub ]

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


def path
  http_url @store.rdoc.generator.file_dir
end

#search_record

Search record used by Generator::JsonIndex

[ GitHub ]

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


def search_record
  return unless @parser < RDoc::Parser::Text

  [
    page_name,
    '',
    page_name,
    '',
    path,
    '',
    snippet(@comment),
  ]
end

Class: RDoc::TopLevel

Overview

Constant Summary

Text - Included

Context - Inherited

Class Method Summary

Context - Inherited

CodeObject - Inherited

Instance Attribute Summary

Context - Inherited

CodeObject - Inherited

Instance Method Summary

Context - Inherited

CodeObject - Inherited

Generator::Markup - Included

Text - Included

Constructor Details

.new(absolute_name, relative_name = absolute_name) ⇒ TopLevel

Instance Attribute Details

#absolute_name (rw)

#classes_or_modules (readonly)

#display? ⇒ Boolean (readonly)

#file_stat (rw)

#parser (rw)

#relative_name (rw)

#text? ⇒ Boolean (readonly)

Instance Method Details

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

#add_alias(an_alias)

#add_constant(constant)

#add_include(include)

#add_method(method)

#add_to_classes_or_modules(mod)

#base_name Also known as: #name

#cvs_url

#eql?(other)

#find_class_or_module(name)

#find_local_symbol(symbol)

#find_module_named(name)

#full_name

#hash

#http_url(prefix)

#last_modified

#marshal_dump

#name

#object_class

#page_name

#path

#search_record

.new(absolute_name, relative_name = absolute_name) ⇒ `TopLevel`

#display? ⇒ `Boolean` (readonly)

#text? ⇒ `Boolean` (readonly)