123456789_123456789_123456789_123456789_123456789_

Class: RDoc::TopLevel

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
Instance Chain:
self, Context, Comparable, CodeObject, Generator::Markup, Text
Inherits: RDoc::Context
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, SPACE_SEPARATED_LETTER_CLASS, TO_HTML_CHARACTERS

Context - Inherited

TOMDOC_TITLES, TOMDOC_TITLES_SORT, TYPES

Class Method Summary

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

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.

Text - Included

#language

The language for this text.

Instance Method Summary

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.

#instance_methods

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 130

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)

Sets the parser for this toplevel context, also the store.

[ GitHub ]

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

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 283

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 67

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 76

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 85

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 94

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 103

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 113

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 120

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 71

alias eql? ==

#find_class_or_module(name)

See #find_class_or_module

[ GitHub ]

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

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 147

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 154

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 161

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 169

def hash
  @relative_name.hash
end

#http_url(prefix)

URL for this with a prefix

[ GitHub ]

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

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 182

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 194

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 201

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 213

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

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

  @file_stat          = nil
end

#name

[ GitHub ]

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

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 227

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 238

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 248

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 252

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 266

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 287

def to_s # :nodoc:
  "file #{full_name}"
end