Class: RDoc::Markup::ToHtmlCrossref

Inherits:
ToHtml show all
Defined in:
lib/rdoc/markup/to_html_crossref.rb

Overview

Subclass of the RDoc::Markup::ToHtml class that supports looking up method names, classes, etc to create links. RDoc::CrossReference is used to generate those links based on the current context.

Constant Summary collapse

ALL_CROSSREF_REGEXP =

:stopdoc:

RDoc::CrossReference::ALL_CROSSREF_REGEXP
CLASS_REGEXP_STR = 
RDoc::CrossReference::CLASS_REGEXP_STR
CROSSREF_REGEXP = 
RDoc::CrossReference::CROSSREF_REGEXP
METHOD_REGEXP_STR = 
RDoc::CrossReference::METHOD_REGEXP_STR

Constants inherited from ToHtml

RDoc::Markup::ToHtml::LIST_TYPE_TO_HTML

Constants included from Text

Text::MARKUP_FORMAT, Text::TO_HTML_CHARACTERS

Instance Attribute Summary collapse

Attributes inherited from ToHtml

#code_object, #from_path, #in_list_entry, #list, #res

Instance Method Summary collapse

Methods inherited from ToHtml

#accept_blank_line, #accept_block_quote, #accept_heading, #accept_list_end, #accept_list_item_end, #accept_list_item_start, #accept_list_start, #accept_paragraph, #accept_raw, #accept_rule, #accept_verbatim, #convert_string, #end_accepting, #handle_RDOCLINK, #handle_special_HARD_BREAK, #handle_special_TIDYLINK, #html_list_name, #init_tags, #list_end_for, #list_item_start, #parseable?, #start_accepting, #to_html

Methods included from Text

encode_fallback, #expand_tabs, #flush_left, #markup, #normalize_comment, #parse, #snippet, #strip_hashes, #strip_newlines, #strip_stars, #to_html, #wrap

Methods inherited from Formatter

#accept_document, #add_special_RDOCLINK, #add_special_TIDYLINK, #add_tag, #annotate, #convert, #convert_flow, #convert_special, #convert_string, gen_relative_url, #ignore, #in_tt?, #off_tags, #on_tags, #parse_url, #tt?

Constructor Details

#initialize(options, from_path, context, markup = nil) ⇒ ToHtmlCrossref

Creates a new crossref resolver that generates links relative to context which lives at from_path in the generated files. ‘#’ characters on references are removed unless show_hash is true. Only method names preceded by ‘#’ or ‘::’ are linked, unless hyperlink_all is true.

Raises:

  • (ArgumentError) 


31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/rdoc/markup/to_html_crossref.rb', line 31

def initialize(options, from_path, context, markup = nil)
  raise ArgumentError, 'from_path cannot be nil' if from_path.nil?

  super options, markup

  @context       = context
  @from_path     = from_path
  @hyperlink_all = @options.hyperlink_all
  @show_hash     = @options.show_hash

  crossref_re = @hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP
  @markup.add_special crossref_re, :CROSSREF

  @cross_reference = RDoc::CrossReference.new @context
end

Instance Attribute Details

#context ⇒ Object

RDoc::CodeObject for generating references



18
19
20
 
# File 'lib/rdoc/markup/to_html_crossref.rb', line 18

def context
  @context
end

#show_hash ⇒ Object

Should we show ‘#’ characters on method references?



23
24
25
 
# File 'lib/rdoc/markup/to_html_crossref.rb', line 23

def show_hash
  @show_hash
end

Instance Method Details

#cross_reference(name, text = nil) ⇒ Object

Creates a link to the reference name if the name exists. If text is given it is used as the link text, otherwise name is used.



51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/rdoc/markup/to_html_crossref.rb', line 51

def cross_reference name, text = nil
  lookup = name

  name = name[1..-1] unless @show_hash if name[0, 1] == '#'

  name = "#{CGI.unescape $'} at #{$1}" if name =~ /(.*[^#:])@/

  text = name unless text

  link lookup, text
end

#gen_url(url, text) ⇒ Object

Generates links for rdoc-ref: scheme URLs and allows RDoc::Markup::ToHtml to handle other schemes.



118
119
120
121
122
 
# File 'lib/rdoc/markup/to_html_crossref.rb', line 118

def gen_url url, text
  return super unless url =~ /\Ardoc-ref:/

  cross_reference $', text
end

#handle_special_CROSSREF(special) ⇒ Object

We’re invoked when any text matches the CROSSREF pattern. If we find the corresponding reference, generate a link. If the name we’re looking for contains no punctuation, we look for it up the module/class chain. For example, ToHtml is found, even without the RDoc::Markup:: prefix, because we look for it in module Markup first.



70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/rdoc/markup/to_html_crossref.rb', line 70

def handle_special_CROSSREF(special)
  name = special.text

  return name if name =~ /@[\w-]+\.[\w-]/ # labels that look like emails

  unless @hyperlink_all then
    # This ensures that words entirely consisting of lowercase letters will
    # not have cross-references generated (to suppress lots of erroneous
    # cross-references to "new" in text, for instance)
    return name if name =~ /\A[a-z]*\z/
  end

  cross_reference name
end

#handle_special_HYPERLINK(special) ⇒ Object

Handles rdoc-ref: scheme links and allows RDoc::Markup::ToHtml to handle other schemes.



89
90
91
92
93
 
# File 'lib/rdoc/markup/to_html_crossref.rb', line 89

def handle_special_HYPERLINK special
  return cross_reference $' if special.text =~ /\Ardoc-ref:/

  super
end

#handle_special_RDOCLINK(special) ⇒ Object

special is an rdoc-schemed link that will be converted into a hyperlink. For the rdoc-ref scheme the cross-reference will be looked up and the given name will be used.

All other contents are handled by the superclass



103
104
105
106
107
108
109
110
111
112
 
# File 'lib/rdoc/markup/to_html_crossref.rb', line 103

def handle_special_RDOCLINK special
  url = special.text

  case url
  when /\Ardoc-ref:/ then
    cross_reference $'
  else
    super
  end
end

#link(name, text) ⇒ Object

Creates an HTML link to name with the given text.



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/rdoc/markup/to_html_crossref.rb', line 127

def link name, text
  original_name = name

  if name =~ /(.*[^#:])@/ then
    name = $1
    label = $'
  end

  ref = @cross_reference.resolve name, text

  text = ref.output_name @context if
    RDoc::MethodAttr === ref and text == original_name

  case ref
  when String then
    ref
  else
    path = ref.as_href @from_path

    if path =~ /#/ then
      path << "-label-#{label}"
    elsif ref.sections and
          ref.sections.any? { |section| label == section.title } then
      path << "##{label}"
    else
      path << "#label-#{label}"
    end if label

    "<a href=\"#{path}\">#{text}</a>"
  end
end