class RDoc::CrossReference

RDoc::CrossReference is a reusable way to create cross references for names.

Constants

ALL_CROSSREF_REGEXP

Version of CROSSREF_REGEXP used when --hyperlink-all is specified.

CLASS_REGEXP_STR

Regular expression to match class references

There can be a ‘\’ in front of text to suppress the cross-reference
There can be a ‘::’ in front of class names to reference from the top-level namespace.
The method can be followed by parenthesis (not recommended)

CROSSREF_REGEXP

Regular expressions matching text that should potentially have cross-reference links generated are passed to add_regexp_handling. Note that these expressions are meant to pick up text for which cross-references have been suppressed, since the suppression characters are removed by the code that is triggered.

METHOD_ARGS_REGEXP_STR

Regular expression to match method arguments.

METHOD_ARG_REGEXP_STR

Regular expression to match a single method argument.

METHOD_REGEXP_STR

Regular expression to match method references.

See CLASS_REGEXP_STR

Attributes

seen [RW]

Hash of references that have been looked-up to their replacements

Public Class Methods

new (context)

Allows cross-references to be created based on the given context (RDoc::Context).

# File lib/rdoc/cross_reference.rb, line 126
def initialize(context)
  @context = context
  @store   = context.store

  @seen = {}
end

Public Instance Methods

resolve (name)

Returns a reference to name.

If the reference is found and name is not documented nil will be returned. If name is not found nil is returned.

# File lib/rdoc/cross_reference.rb, line 197
def resolve(name)
  return @seen[name] if @seen.include? name

  ref = @context.find_symbol name

  ref = resolve_local_symbol name unless ref

  # Try a page name
  ref = @store.page name if not ref and name =~ /^[\w.\/]+$/

  ref = nil if Alias === ref # external alias, can't link to it

  ref = nil unless ref&.display?

  @seen[name] = ref

  ref
end

resolve_local_symbol (name)

Returns a method, attribute or constant reference to name if it exists in the containing context object. It returns nil otherwise.

For example, this method would decompose name = ‘A::CONSTANT’ into a container object A and a symbol ‘CONSTANT’, and it would try to find ‘CONSTANT’ in A.

# File lib/rdoc/cross_reference.rb, line 142
def resolve_local_symbol(name)
  ref = nil
  type = nil
  container = nil

  case name
  when /#{CLASS_REGEXP_STR}::([A-Z]\w*)\z/o
    symbol = $2
    container = @context.find_symbol_module($1)
  when /#{CLASS_REGEXP_STR}([.#]|::)#{METHOD_REGEXP_STR}/o
    type = $2
    if '.' == type # will find either #method or ::method
      symbol = $3
    else
      symbol = "#{type}#{$3}"
    end
    container = @context.find_symbol_module($1)
  when /^([.#]|::)#{METHOD_REGEXP_STR}/o
    type = $1
    if '.' == type
      symbol = $2
    else
      symbol = "#{type}#{$2}"
    end
    container = @context
  end

  if container
    unless TopLevel === container
      if '.' == type
        if 'new' == symbol # AnyClassName.new will be class method
          ref = container.find_local_symbol symbol
          ref = container.find_ancestor_local_symbol symbol unless ref
        else
          ref = container.find_local_symbol "::#{symbol}"
          ref = container.find_ancestor_local_symbol "::#{symbol}" unless ref
          ref = container.find_local_symbol "##{symbol}" unless ref
          ref = container.find_ancestor_local_symbol "##{symbol}" unless ref
        end
      else
        ref = container.find_local_symbol symbol
        ref = container.find_ancestor_local_symbol symbol unless ref
      end
    end
  end

  ref
end