Class: RDoc::Markup::ToHtmlCrossref

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `ToHtml`, `Formatter`
Instance Chain: self, `ToHtml`, `::RDoc::Text`, `Formatter`
Inherits:	RDoc::Markup::ToHtml Object RDoc::Markup::Formatter RDoc::Markup::ToHtml RDoc::Markup::ToHtmlCrossref
Defined in:	lib/rdoc/markup/to_html_crossref.rb

Overview

Subclass of the 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

ALL_CROSSREF_REGEXP = Internal use only
# File 'lib/rdoc/markup/to_html_crossref.rb', line 10
```
RDoc::CrossReference::ALL_CROSSREF_REGEXP
```
CLASS_REGEXP_STR = Internal use only
# File 'lib/rdoc/markup/to_html_crossref.rb', line 11
```
RDoc::CrossReference::CLASS_REGEXP_STR
```
CROSSREF_REGEXP = Internal use only
# File 'lib/rdoc/markup/to_html_crossref.rb', line 12
```
RDoc::CrossReference::CROSSREF_REGEXP
```
METHOD_REGEXP_STR = Internal use only
# File 'lib/rdoc/markup/to_html_crossref.rb', line 13
```
RDoc::CrossReference::METHOD_REGEXP_STR
```

`::RDoc::Text` - Included

MARKUP_FORMAT, SPACE_SEPARATED_LETTER_CLASS, TO_HTML_CHARACTERS

`ToHtml` - Inherited

LIST_TYPE_TO_HTML, URL_CHARACTERS_REGEXP_STR

Class Method Summary

.new(options, from_path, context, markup = nil) ⇒ ToHtmlCrossref constructor

Creates a new crossref resolver that generates links relative to #context which lives at from_path in the generated files.

`ToHtml` - Inherited

.new	Creates a new formatter that will output HTML.

`Formatter` - Inherited

.gen_relative_url	Converts a target url to one that is relative to a given path.
.new	Creates a new `Formatter`.

Instance Attribute Summary

#context rw

::RDoc::CodeObject for generating references.
#show_hash rw

Should we show ‘#’ characters on method references?

`ToHtml` - Inherited

#code_object	The `::RDoc::CodeObject` HTML is being generated for.
#from_path	Path to this document for relative links.
#in_list_entry, #list, #res

`Formatter` - Inherited

#in_tt?

Are we currently inside tt tags?

Instance Method Summary

#cross_reference(name, text = nil, code = true)

Creates a link to the reference name if the name exists.
#gen_url(url, text)

Generates links for rdoc-ref: scheme URLs and allows ToHtml to handle other schemes.
#handle_regexp_CROSSREF(target)

We’re invoked when any text matches the CROSSREF pattern.
#handle_regexp_HYPERLINK(target)

Handles rdoc-ref: scheme links and allows ToHtml to handle other schemes.
#handle_regexp_RDOCLINK(target)

target is an rdoc-schemed link that will be converted into a hyperlink.
#link(name, text, code = true)

Creates an HTML link to name with the given text.
#init_link_notation_regexp_handlings Internal use only

`ToHtml` - Inherited

#accept_blank_line	Adds `blank_line` to the output.
#accept_block_quote	Adds `block_quote` to the output.
#accept_heading	Adds `heading` to the output.
#accept_list_end	Finishes consumption of `list`
#accept_list_item_end	Finishes consumption of `list_item`
#accept_list_item_start	Prepares the visitor for consuming `list_item`
#accept_list_start	Prepares the visitor for consuming `list`
#accept_paragraph	Adds `paragraph` to the output.
#accept_raw	Adds `raw` to the output.
#accept_rule	Adds `rule` to the output.
#accept_table	Adds `table` to the output.
#accept_verbatim	Adds `verbatim` to the output.
#convert_string	CGI-escapes `text`
#end_accepting	Returns the generated output.
#gen_url	Generate a link to `url` with content `text`.
#handle_regexp_HARD_BREAK	`target` is a `<br>`.
#handle_regexp_HYPERLINK	`target` is a potential link.
#handle_regexp_RDOCLINK	`target` is an rdoc-schemed link that will be converted into a hyperlink.
#handle_regexp_TIDYLINK	This `target` is a link where the label is different from the URL `label[url]` or `{url long label}`.
#html_list_name	Determines the HTML list element for `list_type` and `open_tag`
#init_link_notation_regexp_handlings	Adds regexp handlings about link notations.
#init_regexp_handlings	Adds regexp handlings.
#init_tags	Maps attributes to HTML tags.
#list_end_for	Returns the HTML end-tag for `list_type`
#list_item_start	Returns the HTML tag for `list_type`, possible using a label from `list_item`
#parseable?	Returns true if text is valid ruby syntax.
#start_accepting	Prepares the visitor for HTML generation.
#to_html	Converts `item` to HTML using Text#to_html
#handle_RDOCLINK

`::RDoc::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 `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`

`Formatter` - Inherited

#accept_document	Adds `document` to the output.
#add_regexp_handling_RDOCLINK	Adds a regexp handling for links of the form rdoc-…:
#add_regexp_handling_TIDYLINK	Adds a regexp handling for links of the form `<text>` and <word>.
#add_tag	Add a new set of tags for an attribute.
#annotate	Allows `tag` to be decorated with additional information.
#convert	Marks up `content`
#convert_flow	Converts flow items `flow`
#convert_regexp_handling	Converts added regexp handlings.
#convert_string	Converts a string to be fancier if desired.
#ignore	Use ignore in your subclass to ignore the content of a node.
#off_tags	Turns off tags for `item` on `res`
#on_tags	Turns on tags for `item` on `res`
#parse_url	Extracts and a scheme, url and an anchor id from `url` and returns them.
#tt?	Is `tag` a tt tag?

Constructor Details

.new(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)

[ GitHub ]

# File 'lib/rdoc/markup/to_html_crossref.rb', line 32


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

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

Instance Attribute Details

#context (rw)

::RDoc::CodeObject for generating references

[ GitHub ]

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


attr_accessor :context

#show_hash (rw)

Should we show ‘#’ characters on method references?

[ GitHub ]

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


attr_accessor :show_hash

Instance Method Details

#cross_reference(name, text = nil, code = true)

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.

[ GitHub ]

# File 'lib/rdoc/markup/to_html_crossref.rb', line 61


def cross_reference name, text = nil, code = true
  lookup = name

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

  if !(name.end_with?('+@', '-@')) and name =~ /(.*[^#:])?@/
    text ||= [CGI.unescape($'), (" at <code>#{$1}</code>" if $~.begin(1))].join("")
    code = false
  else
    text ||= name
  end

  link lookup, text, code
end

#gen_url(url, text)

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

[ GitHub ]

# File 'lib/rdoc/markup/to_html_crossref.rb', line 131


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

  name = $'
  cross_reference name, text, name == text
end

#handle_regexp_CROSSREF(target)

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 ::RDoc::Markup first.

[ GitHub ]

# File 'lib/rdoc/markup/to_html_crossref.rb', line 83


def handle_regexp_CROSSREF(target)
  name = target.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_regexp_HYPERLINK(target)

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

[ GitHub ]

# File 'lib/rdoc/markup/to_html_crossref.rb', line 102


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

  super
end

#handle_regexp_RDOCLINK(target)

target 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

[ GitHub ]

# File 'lib/rdoc/markup/to_html_crossref.rb', line 116


def handle_regexp_RDOCLINK target
  url = target.text

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

#init_link_notation_regexp_handlings

This method is for internal use only.

[ GitHub ]

# File 'lib/rdoc/markup/to_html_crossref.rb', line 46


def init_link_notation_regexp_handlings
  add_regexp_handling_RDOCLINK

  # The crossref must be linked before tidylink because Klass.method[:sym]
  # will be processed as a tidylink first and will be broken.
  crossref_re = @options.hyperlink_all ? ALL_CROSSREF_REGEXP : CROSSREF_REGEXP
  @markup.add_regexp_handling crossref_re, :CROSSREF

  add_regexp_handling_TIDYLINK
end

#link(name, text, code = true)

Creates an HTML link to name with the given text.

[ GitHub ]

# File 'lib/rdoc/markup/to_html_crossref.rb', line 141


def link name, text, code = true
  if !(name.end_with?('+@', '-@')) and name =~ /(.*[^#:])?@/
    name = $1
    label = $'
  end

  ref = @cross_reference.resolve name, text if name

  case ref
  when String then
    ref
  else
    path = ref ? ref.as_href(@from_path) : +""

    if code and RDoc::CodeObject === ref and !(RDoc::TopLevel === ref)
      text = "<code>#{CGI.escapeHTML text}</code>"
    end

    if label
      if path =~ /#/
        path << "-label-#{label}"
      elsif ref&.sections&.any? { |section| label == section.title }
        path << "##{label}"
      elsif ref.respond_to?(:aref)
        path << "##{ref.aref}-label-#{label}"
      else
        path << "#label-#{label}"
      end
    end

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

Class: RDoc::Markup::ToHtmlCrossref

Overview

Constant Summary

::RDoc::Text - Included

ToHtml - Inherited

Class Method Summary

ToHtml - Inherited

Formatter - Inherited

Instance Attribute Summary

ToHtml - Inherited

::RDoc::Text - Included

Formatter - Inherited

Instance Method Summary

ToHtml - Inherited

::RDoc::Text - Included

Formatter - Inherited

Constructor Details

.new(options, from_path, context, markup = nil) ⇒ ToHtmlCrossref

Instance Attribute Details

#context (rw)

#show_hash (rw)

Instance Method Details

#cross_reference(name, text = nil, code = true)

#gen_url(url, text)

#handle_regexp_CROSSREF(target)

#handle_regexp_HYPERLINK(target)

#handle_regexp_RDOCLINK(target)

#init_link_notation_regexp_handlings

#link(name, text, code = true)

`::RDoc::Text` - Included

`ToHtml` - Inherited

`ToHtml` - Inherited

`Formatter` - Inherited

`ToHtml` - Inherited

`::RDoc::Text` - Included

`Formatter` - Inherited

`ToHtml` - Inherited

`::RDoc::Text` - Included

`Formatter` - Inherited

.new(options, from_path, context, markup = nil) ⇒ `ToHtmlCrossref`