class RDoc::CrossReference - rdoc-4.2.0 Documentation

# 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

  1. There can be a '\' in front of text to suppress the cross-reference

  2. There can be a '::' in front of class names to reference from the top-level namespace.

  3. 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_special. 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_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) click to toggle source

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

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

      @seen = {}
    end

### Public Instance Methods

resolve(name, text) click to toggle source

Returns a reference to `name`.

If the reference is found and `name` is not documented `text` will be returned. If `name` is escaped `name` is returned. If `name` is not found `text` is returned.

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

      if /#{CLASS_REGEXP_STR}([.#]|::)#{METHOD_REGEXP_STR}/o =~ name then
        type = $2
        type = '' if type == '.'  # will find either #method or ::method
        method = "#{type}#{$3}"
        container = @context.find_symbol_module($1)
      elsif /^([.#]|::)#{METHOD_REGEXP_STR}/o =~ name then
        type = $1
        type = '' if type == '.'
        method = "#{type}#{$2}"
        container = @context
      else
        container = nil
      end

      if container then
        ref = container.find_local_symbol method

        unless ref || RDoc::TopLevel === container then
          ref = container.find_ancestor_local_symbol method
        end
      end

      ref = case name
            when /^\(#{CLASS_REGEXP_STR})$/o then
              @context.find_symbol $1
            else
              @context.find_symbol name
            end unless ref

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

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

      out = if name == '\' then
              name
            elsif name =~ /^\/ then
              # we remove the \ only in front of what we know:
              # other backslashes are treated later, only outside of <tt>
              ref ? $' : name
            elsif ref then
              if ref.display? then
                ref
              else
                text
              end
            else
              text
            end

      @seen[name] = out

      out
    end