Class: RDoc::Markup::ToHtmlSnippet

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::ToHtmlSnippet
Defined in:	lib/rdoc/markup/to_html_snippet.rb

Overview

Outputs RDoc markup as paragraphs with inline markup only.

Constant Summary

`::RDoc::Text` - Included

MARKUP_FORMAT, TO_HTML_CHARACTERS

`ToHtml` - Inherited

LIST_TYPE_TO_HTML

Class Method Summary

.new(options, characters = 100, paragraphs = 3, markup = nil) ⇒ ToHtmlSnippet constructor

Creates a new ToHtmlSnippet formatter that will cut off the input on the next word boundary after the given number of #characters or #paragraphs of text have been encountered.

`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

#character_limit readonly

After this many characters the input will be cut off.
#mask readonly

The attribute bitmask.
#paragraph_limit readonly

After this many paragraphs the input will be cut off.
#paragraphs readonly

Count of paragraphs found.
#characters readonly Internal use only

The number of characters seen so far.

`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

`::RDoc::Text` - Included

#language

`Formatter` - Inherited

#in_tt?

Are we currently inside tt tags?

Instance Method Summary

#accept_heading(heading)

Adds heading to the output as a paragraph.
#accept_list_item_end(list_item)

Finishes consumption of list_item
#accept_list_item_start(list_item)

Prepares the visitor for consuming list_item
#accept_list_start(list)

Prepares the visitor for consuming list
#accept_paragraph(paragraph)
#accept_raw(*node)

Raw sections are untrusted and ignored.
#accept_rule(*node)

Rules are ignored.
#accept_verbatim(verbatim)

Adds verbatim to the output.
#add_paragraph

Throws :done when paragraph_limit paragraphs have been encountered.
#convert(content)

Marks up content
#convert_flow(flow)

Converts flow items flow
#gen_url(url, text)

Returns just the text of link, url is only used to determine the link type.
#handle_regexp_CROSSREF(target)

Removes escaping from the cross-references in target
#handle_regexp_HARD_BREAK(target)

target is a <br>.
#html_list_name(list_type, open_tag)

In snippets, there are no lists.
#list_item_start(list_item, list_type)

Lists are paragraphs, but notes and labels have a separator.
#off_tags(res, item)

Maintains a bitmask to allow HTML elements to be closed properly.
#on_tags(res, item)

Maintains a bitmask to allow HTML elements to be closed properly.
#start_accepting

Prepares the visitor for HTML snippet generation.
#truncate(text)

Truncates text at the end of the first word after the character_limit.

`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_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_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	These methods are used by regexp handling markup added by #add_regexp_handling.

`::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, characters = 100, paragraphs = 3, markup = nil) ⇒ `ToHtmlSnippet`

Creates a new ToHtmlSnippet formatter that will cut off the input on the next word boundary after the given number of #characters or #paragraphs of text have been encountered.

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 37


def initialize options, characters = 100, paragraphs = 3, markup = nil
  super options, markup

  @character_limit = characters
  @paragraph_limit = paragraphs

  @characters = 0
  @mask       = 0
  @paragraphs = 0

  @markup.add_regexp_handling RDoc::CrossReference::CROSSREF_REGEXP, :CROSSREF
end

Instance Attribute Details

#character_limit (readonly)

After this many characters the input will be cut off.

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 10


attr_reader :character_limit

#characters (readonly)

This method is for internal use only.

The number of characters seen so far.

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 15


attr_reader :characters # :nodoc:

#mask (readonly)

The attribute bitmask

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 20


attr_reader :mask

#paragraph_limit (readonly)

After this many paragraphs the input will be cut off.

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 25


attr_reader :paragraph_limit

#paragraphs (readonly)

Count of paragraphs found

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 30


attr_reader :paragraphs

Instance Method Details

#accept_heading(heading)

Adds heading to the output as a paragraph

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 53


def accept_heading heading
  @res << "<p>#{to_html heading.text}\n"

  add_paragraph
end

#accept_list_item_end(list_item)

Finishes consumption of list_item

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 82


def accept_list_item_end list_item
end

#accept_list_item_start(list_item)

Prepares the visitor for consuming list_item

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 88


def accept_list_item_start list_item
  @res << list_item_start(list_item, @list.last)
end

#accept_list_start(list)

Prepares the visitor for consuming list

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 95


def accept_list_start list
  @list << list.type
  @res << html_list_name(list.type, true)
  @in_list_entry.push ''
end

#accept_paragraph(paragraph)

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 69


def accept_paragraph paragraph
  para = @in_list_entry.last || "<p>"

  text = paragraph.text @hard_break

  @res << "#{para}#{to_html text}\n"

  add_paragraph
end

#accept_raw(*node)

Raw sections are untrusted and ignored

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 62


alias accept_raw ignore

#accept_rule(*node)

Rules are ignored

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 67


alias accept_rule ignore

#accept_verbatim(verbatim)

Adds verbatim to the output

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 104


def accept_verbatim verbatim
  throw :done if @characters >= @character_limit
  input = verbatim.text.rstrip

  text = truncate input
  text << ' ...' unless text == input

  super RDoc::Markup::Verbatim.new text

  add_paragraph
end

#add_paragraph

Throws :done when paragraph_limit paragraphs have been encountered

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 195


def add_paragraph
  @paragraphs += 1

  throw :done if @paragraphs >= @paragraph_limit
end

#convert(content)

Marks up content

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 204


def convert content
  catch :done do
    return super
  end

  end_accepting
end

#convert_flow(flow)

Converts flow items flow

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 215


def convert_flow flow
  throw :done if @characters >= @character_limit

  res = []
  @mask = 0

  flow.each do |item|
    case item
    when RDoc::Markup::AttrChanger then
      off_tags res, item
      on_tags  res, item
    when String then
      text = convert_string item
      res << truncate(text)
    when RDoc::Markup::RegexpHandling then
      text = convert_regexp_handling item
      res << truncate(text)
    else
      raise "Unknown flow element: #{item.inspect}"
    end

    if @characters >= @character_limit then
      off_tags res, RDoc::Markup::AttrChanger.new(0, @mask)
      break
    end
  end

  res << ' ...' if @characters >= @character_limit

  res.join
end

#gen_url(url, text)

Returns just the text of link, url is only used to determine the link type.

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 168


def gen_url url, text
  if url =~ /^rdoc-label:([^:]*)(?::(.*))?/ then
    type = "link"
  elsif url =~ /([A-Za-z]+):(.*)/ then
    type = $1
  else
    type = "http"
  end

  if (type == "http" or type == "https" or type == "link") and
     url =~ /\.(gif|png|jpg|jpeg|bmp)$/ then
    ''
  else
    text.sub(%r%^#{type}:/*%, '')
  end
end

#handle_regexp_CROSSREF(target)

Removes escaping from the cross-references in target

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 128


def handle_regexp_CROSSREF target
  target.text.sub(/\A\\/, '')
end

#handle_regexp_HARD_BREAK(target)

target is a <br>

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 135


def handle_regexp_HARD_BREAK target
  @characters -= 4
  '<br>'
end

#html_list_name(list_type, open_tag)

In snippets, there are no lists

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 188


def html_list_name list_type, open_tag
  ''
end

#list_item_start(list_item, list_type)

Lists are paragraphs, but notes and labels have a separator

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 143


def list_item_start list_item, list_type
  throw :done if @characters >= @character_limit

  case list_type
  when :BULLET, :LALPHA, :NUMBER, :UALPHA then
    "<p>"
  when :LABEL, :NOTE then
    labels = Array(list_item.label).map do |label|
      to_html label
    end.join ', '

    labels << " &mdash; " unless labels.empty?

    start = "<p>#{labels}"
    @characters += 1 # try to include the label
    start
  else
    raise RDoc::Error, "Invalid list type: #{list_type.inspect}"
  end
end

#off_tags(res, item)

Maintains a bitmask to allow HTML elements to be closed properly. See Formatter.

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 261


def off_tags res, item
  @mask ^= item.turn_off

  super
end

#on_tags(res, item)

Maintains a bitmask to allow HTML elements to be closed properly. See Formatter.

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 251


def on_tags res, item
  @mask ^= item.turn_on

  super
end

#start_accepting

Prepares the visitor for HTML snippet generation

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 119


def start_accepting
  super

  @characters = 0
end

#truncate(text)

Truncates text at the end of the first word after the character_limit.

[ GitHub ]

# File 'lib/rdoc/markup/to_html_snippet.rb', line 270


def truncate text
  length = text.length
  characters = @characters
  @characters += length

  return text if @characters < @character_limit

  remaining = @character_limit - characters

  text =~ /\A(.{#{remaining},}?)(\s|$)/m # TODO word-break instead of \s?

  $1
end

Class: RDoc::Markup::ToHtmlSnippet

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, characters = 100, paragraphs = 3, markup = nil) ⇒ ToHtmlSnippet

Instance Attribute Details

#character_limit (readonly)

#characters (readonly)

#mask (readonly)

#paragraph_limit (readonly)

#paragraphs (readonly)

Instance Method Details

#accept_heading(heading)

#accept_list_item_end(list_item)

#accept_list_item_start(list_item)

#accept_list_start(list)

#accept_paragraph(paragraph)

#accept_raw(*node)

#accept_rule(*node)

#accept_verbatim(verbatim)

#add_paragraph

#convert(content)

#convert_flow(flow)

#gen_url(url, text)

#handle_regexp_CROSSREF(target)

#handle_regexp_HARD_BREAK(target)

#html_list_name(list_type, open_tag)

#list_item_start(list_item, list_type)

#off_tags(res, item)

#on_tags(res, item)

#start_accepting

#truncate(text)

`::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, characters = 100, paragraphs = 3, markup = nil) ⇒ `ToHtmlSnippet`