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

MARSHAL_VERSION = Internal use only
# File 'lib/rdoc/top_level.rb', line 7
```
0
```

`Text` - Included

MARKUP_FORMAT, TO_HTML_CHARACTERS

`Context` - Inherited

TOMDOC_TITLES, TOMDOC_TITLES_SORT, 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.
#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.
#file_stat rw

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

The parser class that processed this file.
#parser=(val) rw
#relative_name rw

Relative name of this file.
#text? ⇒ Boolean readonly

Is this TopLevel from a text file instead of a source code file?
#diagram rw Internal use only

`Context` - Inherited

#aliases	Class/module aliases.
#attributes	All attr* methods.
#block_params	Block params to be used in the next `MethodAttr` parsed under this context.
#constants	Constants defined.
#constants_hash	Hash of registered constants.
#current_line_visibility=	Current visibility of this line.
#current_section	The current documentation section that new items will be added to.
#current_section=	Sets the current documentation section of documentation.
#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.
#ongoing_visibility=	Changes the visibility for new methods to `visibility`
#params	Params to be used in the next `MethodAttr` parsed under this context.
#remove_from_documentation?	Should we remove this context from the documentation?
#requires	Files this context requires.
#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.

`CodeObject` - Inherited

#comment	Our comment.
#comment=	Replaces our comment with `comment`, unless it is empty.
#display?	Should this `CodeObject` be displayed in output?
#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:.
#documented?	Does this object have a comment with content or is `#received_nodoc` true?
#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`.
#file	Which file this code object was defined in.
#force_documentation	Force documentation of this `CodeObject`.
#force_documentation=	Force the documentation of this object unless documentation has been turned off by :enddoc:
#full_name=	Sets the full_name overriding any computed full name.
#ignored?	Has this class been ignored?
#line	Line in `#file` where this `CodeObject` was defined.
#metadata	Hash of arbitrary metadata for this `CodeObject`.
#parent	Our parent `CodeObject`.
#parent=	Sets the parent `CodeObject`.
#received_nodoc	Did we ever receive a `:nodoc:` directive?
#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`.
#suppressed?	Has this class been suppressed?
#viewer	We are the model of the code, but we know that at some point we will be worked on by viewers.

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
#inspect Internal use only
#marshal_load(array) Internal use only

Loads this TopLevel from array.
#pretty_print(q) Internal use only
#to_s Internal use only

`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_module_by_normal_module	Adds a module by `NormalModule` instance.
#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_constant_visibility_for	Given an array `names` of constants, set the visibility of each constant to `visibility`
#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`
#display,
#each_ancestor	Iterator for ancestors for duck-typing.
#remove_invisible_in	Only called when min_visibility == `:public` or `:private`.
#sections_hash, #to_s

`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.
#initialize_visibility	Initializes state for visibility of this `CodeObject` and its children.

`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 43


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 22


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 29


attr_reader :classes_or_modules

#diagram (rw)

This method is for internal use only.

[ GitHub ]

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


attr_accessor :diagram # :nodoc:

#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 127


def display?
  text? and super
end

#file_stat (rw)

This TopLevel’s File::Stat struct

[ GitHub ]

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


attr_accessor :file_stat

#parser (rw)

The parser class that processed this file

[ GitHub ]

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


attr_reader :parser

#parser=(val) (rw)

[ GitHub ]

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


def parser=(val)
  @parser = val
  @store.update_parser_of_file(absolute_name, val) if @store
  @parser
end

#relative_name (rw)

Relative name of this file

[ GitHub ]

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


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 280


def text?
  @parser and @parser.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 64


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 73


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 82


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 91


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 100


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 110


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 117


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 149


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 68


alias eql? ==

#find_class_or_module(name)

See #find_class_or_module

[ GitHub ]

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


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 144


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 151


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 158


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 166


def hash
  @relative_name.hash
end

#http_url(prefix)

URL for this with a prefix

[ GitHub ]

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


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

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

#inspect

This method is for internal use only.

[ GitHub ]

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


def inspect # :nodoc:
  "#<%s:0x%x %p modules: %p classes: %p>" % [
    self.class, object_id,
    base_name,
    @modules.map { |n,m| m },
    @classes.map { |n,c| c }
  ]
end

#last_modified

Time this file was last modified, if known

[ GitHub ]

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


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 198


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

#marshal_load(array)

This method is for internal use only.

Loads this TopLevel from array.

[ GitHub ]

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


def marshal_load array # :nodoc:
  initialize array[1]

  @parser  = array[2]
  @comment = array[3]

  @file_stat          = nil
end

#name

Alias for #base_name.

[ GitHub ]

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


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 224


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 235


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 245


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

#pretty_print(q)

This method is for internal use only.

[ GitHub ]

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


def pretty_print q # :nodoc:
  q.group 2, "[#{self.class}: ", "]" do
    q.text "base name: #{base_name.inspect}"
    q.breakable

    items = @modules.map { |n,m| m }
    items.concat @modules.map { |n,c| c }
    q.seplist items do |mod| q.pp mod end
  end
end

#search_record

Search record used by Generator::JsonIndex

[ GitHub ]

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


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

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

#to_s

This method is for internal use only.

[ GitHub ]

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


def to_s # :nodoc:
  "file #{full_name}"
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)

#diagram (rw)

#display? ⇒ Boolean (readonly)

#file_stat (rw)

#parser (rw)

#parser=(val) (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)

#inspect

#last_modified

#marshal_dump

#marshal_load(array)

#name

#object_class

#page_name

#path

#pretty_print(q)

#search_record

#to_s

`Text` - Included

`Context` - Inherited

`Context` - Inherited

`CodeObject` - Inherited

`Context` - Inherited

`CodeObject` - Inherited

`Context` - Inherited

`CodeObject` - Inherited

`Generator::Markup` - Included

`Text` - Included

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

#display? ⇒ `Boolean` (readonly)

#text? ⇒ `Boolean` (readonly)