123456789_123456789_123456789_123456789_123456789_

Class: RDoc::MethodAttr

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

Overview

Abstract class representing either a method or an attribute.

Constant Summary

Text - Included

MARKUP_FORMAT, TO_HTML_CHARACTERS

Class Attribute Summary

Class Method Summary

CodeObject - Inherited

.new

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

Instance Attribute Summary

  • #aliases readonly

    Array of other names for this method/attribute.

  • #arglists readonly

    The call_seq or the param_seq with method name, if there is no call_seq.

  • #block_params rw

    Parameters yielded by the called block.

  • #block_params=(value) rw

    Attempts to sanitize the content passed by the Ruby parser: remove outer parentheses, etc.

  • #call_seq rw

    Different ways to call this method.

  • #documented? ⇒ Boolean readonly

    A method/attribute is documented if any of the following is true: - it was marked with :nodoc:; - it has a comment; - it is an alias for a documented method; - it has a #see method that is documented.

  • #is_alias_for rw

    The method/attribute we're aliasing.

  • #name rw

    Name of this method/attribute.

  • #param_seq readonly

    Pretty parameter list for this method.

  • #params rw

    Parameters for this method.

  • #singleton rw

    Is this a singleton method/attribute?

  • #store=(store) writeonly

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

  • #text readonly

    Source file token stream.

  • #visibility rw

    public, protected, private.

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

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(text, name) ⇒ MethodAttr

Creates a new MethodAttr from token stream #text and method or attribute name #name.

Usually this is called by super from a subclass.

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 78

def initialize text, name
  super()

  @text = text
  @name = name

  @aliases      = []
  @is_alias_for = nil
  @parent_name  = nil
  @singleton    = nil
  @visibility   = :public
  @see = false

  @arglists     = nil
  @block_params = nil
  @call_seq     = nil
  @param_seq    = nil
  @params       = nil
end

Class Attribute Details

.add_line_numbers (rw)

Allows controlling whether #markup_code adds line numbers to the source code.

[ GitHub ]

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

attr_accessor :add_line_numbers

Instance Attribute Details

#aliases (readonly)

Array of other names for this method/attribute

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 32

attr_reader :aliases

#arglists (readonly)

The call_seq or the param_seq with method name, if there is no call_seq.

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 64

attr_reader :arglists

#block_params (rw)

Parameters yielded by the called block

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 49

attr_reader :block_params

#block_params=(value) (rw)

Attempts to sanitize the content passed by the Ruby parser: remove outer parentheses, etc.

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 233

def block_params=(value)
  # 'yield.to_s' or 'assert yield, msg'
  return @block_params = '' if value =~ /^[\.,]/

  # remove trailing 'if/unless ...'
  return @block_params = '' if value =~ /^(if|unless)\s/

  value = $1.strip if value =~ /^(.+)\s(if|unless)\s/

  # outer parentheses
  value = $1 if value =~ /^\s*\((.*)\)\s*$/
  value = value.strip

  # proc/lambda
  return @block_params = $1 if value =~ /^(proc|lambda)(\s*\{|\sdo)/

  # surrounding ... or [...]
  value = $1.strip if value =~ /^\(.*)\$/
  value = $1.strip if value =~ /^\[(.*)\]$/

  return @block_params = '' if value.empty?

  # global variable
  return @block_params = 'str' if value =~ /^\$[&0-9]$/

  # wipe out array/hash indices
  value.gsub!(/(\w)\[[^\[]+\]/, '\1')

  # remove @ from class/instance variables
  value.gsub!(/@@?([a-z0-9_]+)/, '\1')

  # method calls => method name
  value.gsub!(/([A-Z:a-z0-9_])\.([a-z0-9_])(\s*\(\s*[a-z0-9_.,\s]*\s*\)\s*)?/) do
    case $2
    when 'to_s'      then $1
    when 'const_get' then 'const'
    when 'new' then
      $1.split('::').last.  # ClassName => class_name
        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
        gsub(/([a-z\d])([A-Z])/,'\1_\2').
        downcase
    else
      $2
    end
  end

  # class prefixes
  value.gsub!(/[A-Za-z0-9_:]+::/, '')

  # simple expressions
  value = $1 if value =~ /^([a-z0-9_])\s*[-*\/]/

  @block_params = value.strip
end

#call_seq (rw)

Different ways to call this method

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 59

attr_accessor :call_seq

#documented?Boolean (readonly)

A method/attribute is documented if any of the following is true:

  • it was marked with :nodoc:;

  • it has a comment;

  • it is an alias for a documented method;

  • it has a #see method that is documented.

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 132

def documented?
  super or
    (is_alias_for and is_alias_for.documented?) or
    (see and see.documented?)
end

#is_alias_for (rw)

The method/attribute we're aliasing

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 37

attr_accessor :is_alias_for

#name (rw)

Name of this method/attribute.

[ GitHub ]

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

attr_accessor :name

#param_seq (readonly)

Pretty parameter list for this method

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 69

attr_reader :param_seq

#params (rw)

Parameters for this method

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 54

attr_accessor :params

#singleton (rw)

Is this a singleton method/attribute?

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 22

attr_accessor :singleton

#store=(store) (writeonly)

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

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 160

def store= store
  super

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

#text (readonly)

Source file token stream

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 27

attr_reader :text

#visibility (rw)

public, protected, private

[ GitHub ]

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

attr_accessor :visibility

Instance Method Details

#<=>(other)

Order by #singleton then #name

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 113

def <=>(other)
  return unless other.respond_to?(:singleton) &&
                other.respond_to?(:name)

  [     @singleton ? 0 : 1,       name] <=>
  [other.singleton ? 0 : 1, other.name]
end

#==(other)

This method is for internal use only.
[ GitHub ]

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

def == other # :nodoc:
  equal?(other) or self.class == other.class and full_name == other.full_name
end

#add_alias(an_alias, context)

Abstract method. Contexts in their building phase call this to register a new alias for this known method/attribute.

  • creates a new AnyMethod/Attribute named an_alias.new_name;

  • adds self as an alias for the new method or attribute

  • adds the method or attribute to #aliases

  • adds the method or attribute to context.

Raises:

  • (NotImplementedError)
[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 209

def add_alias(an_alias, context)
  raise NotImplementedError
end

#add_line_numbers(src)

Prepend src with line numbers. Relies on the first line of a source code listing having:

# File xxxxx, line dddd

If it has this comment then line numbers are added to src and the , line dddd portion of the comment is removed.

[ GitHub ]

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

def add_line_numbers(src)
  return unless src.sub!(/\A(.*)(, line (\d+))/, '\1')
  first = $3.to_i - 1
  last  = first + src.count("\n")
  size = last.to_s.length

  line = first
  src.gsub!(/^/) do
    res = if line == first then
            " " * (size + 1)
          else
            "<span class=\"line-num\">%2$*1$d</span> " % [size, line]
          end

    line += 1
    res
  end
end

#aref

HTML fragment reference for this method

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 216

def aref
  type = singleton ? 'c' : 'i'
  # % characters are not allowed in html names => dash instead
  "#{aref_prefix}-#{type}-#{html_name}"
end

#aref_prefix

Prefix for #aref, defined by subclasses.

Raises:

  • (NotImplementedError)
[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 225

def aref_prefix
  raise NotImplementedError
end

#find_method_or_attribute(name)

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 178

def find_method_or_attribute name # :nodoc:
  return nil unless parent.respond_to? :ancestors

  searched = parent.ancestors
  kernel = @store.modules_hash['Kernel']

  searched << kernel if kernel &&
    parent != kernel && !searched.include?(kernel)

  searched.each do |ancestor|
    next if String === ancestor
    next if parent == ancestor

    other = ancestor.find_method_named('#' + name) ||
            ancestor.find_attribute_named(name)

    return other if other
  end

  nil
end

#find_see

This method is for internal use only.
[ GitHub ]

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

def find_see # :nodoc:
  return nil if singleton || is_alias_for

  # look for the method
  other = find_method_or_attribute name
  return other if other

  # if it is a setter, look for a getter
  return nil unless name =~ /[a-z_]=$/i   # avoid == or ===
  return find_method_or_attribute name[0..-2]
end

#full_name

Full method/attribute name including namespace

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 300

def full_name
  @full_name ||= "#{parent_name}#{pretty_name}"
end

#html_name

HTML id-friendly method/attribute name

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 291

def html_name
  require 'cgi'

  CGI.escape(@name.gsub('-', '-2D')).gsub('%','-').sub(/^-/, '')
end

#initialize_copy(other)

This method is for internal use only.

Resets cached data for the object so it can be rebuilt by accessor methods

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 101

def initialize_copy other # :nodoc:
  @full_name = nil
end

#initialize_visibility

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 105

def initialize_visibility # :nodoc:
  super
  @see = nil
end

#inspect

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 304

def inspect # :nodoc:
  alias_for = @is_alias_for ? " (alias for #{@is_alias_for.name})" : nil
  visibility = self.visibility
  visibility = "forced #{visibility}" if force_documentation
  "#<%s:0x%x %s (%s)%s>" % [
    self.class, object_id,
    full_name,
    visibility,
    alias_for,
  ]
end

#markup_code

Turns the method's token stream into HTML.

Prepends line numbers if .add_line_numbers is true.

[ GitHub ]

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

def markup_code
  return '' unless @token_stream

  src = RDoc::TokenStream.to_html @token_stream

  # dedent the source
  indent = src.length
  lines = src.lines.to_a
  lines.shift if src =~ /\A.*#\ *File/i # remove '# File' comment
  lines.each do |line|
    if line =~ /^ *(?=\S)/
      n = $&.length
      indent = n if n < indent
      break if n == 0
    end
  end
  src.gsub!(/^#{' ' * indent}/, '') if indent > 0

  add_line_numbers(src) if RDoc::MethodAttr.add_line_numbers

  src
end

#name_prefix

'::' for a class method/attribute, '#' for an instance method.

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 319

def name_prefix
  @singleton ? '::' : '#'
end

#output_name(context)

Name for output to HTML. For class methods the full name with a “.” is used like SomeClass.method_name. For instance methods the class name is used if context does not match the parent.

This is to help prevent people from using

to call class methods.

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 330

def output_name context
  return "#{name_prefix}#{@name}" if context == parent

  "#{parent_name}#{@singleton ? '.' : '#'}#{@name}"
end

#parent_name

Name of our parent with special handling for un-marshaled methods

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 360

def parent_name
  @parent_name || super
end

#path

Path to this method for use with HTML generator output.

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 353

def path
  "#{@parent.path}##{aref}"
end

#pretty_name

Method/attribute name with class/instance indicator

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 339

def pretty_name
  "#{name_prefix}#{@name}"
end

#pretty_print(q)

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 364

def pretty_print q # :nodoc:
  alias_for =
    if @is_alias_for.respond_to? :name then
      "alias for #{@is_alias_for.name}"
    elsif Array === @is_alias_for then
      "alias for #{@is_alias_for.last}"
    end

  q.group 2, "[#{self.class.name} #{full_name} #{visibility}", "]" do
    if alias_for then
      q.breakable
      q.text alias_for
    end

    if text then
      q.breakable
      q.text "text:"
      q.breakable
      q.pp @text
    end

    unless comment.empty? then
      q.breakable
      q.text "comment:"
      q.breakable
      q.pp @comment
    end
  end
end

#search_record

Used by Generator::JsonIndex to create a record for the search engine.

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 398

def search_record
  [
    @name,
    full_name,
    @name,
    @parent.full_name,
    path,
    params,
    snippet(@comment),
  ]
end

#see

A method/attribute to look at, in particular if this method/attribute has no documentation.

It can be a method/attribute of the superclass or of an included module, including the Kernel module, which is always appended to the included modules.

Returns nil if there is no such method/attribute. The #is_alias_for method/attribute, if any, is not included.

Templates may generate a “see also …” if this method/attribute has documentation, and “see …” if it does not.

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 152

def see
  @see = find_see if @see == false
  @see
end

#to_s

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 410

def to_s # :nodoc:
  if @is_alias_for
    "#{self.class.name}: #{full_name} -> #{is_alias_for}"
  else
    "#{self.class.name}: #{full_name}"
  end
end

#type

Type of method/attribute (class or instance)

[ GitHub ]

  
# File 'lib/rdoc/method_attr.rb', line 346

def type
  singleton ? 'class' : 'instance'
end