class RDoc::Markup::ToHtmlSnippet

Outputs RDoc markup as paragraphs with inline markup only.

Attributes

character_limit[R]

After this many characters the input will be cut off.

mask[R]

The attribute bitmask

paragraph_limit[R]

After this many paragraphs the input will be cut off.

paragraphs[R]

Count of paragraphs found

Public Class Methods

new(options, characters = 100, paragraphs = 3, markup = nil) click to toggle source

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.

Calls superclass method RDoc::Markup::ToHtml.new

# File lib/rdoc/markup/to_html_snippet.rb, line 36
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_special RDoc::CrossReference::CROSSREF_REGEXP, :CROSSREF
end

Public Instance Methods

accept_heading(heading) click to toggle source

Adds heading to the output as a paragraph

# File lib/rdoc/markup/to_html_snippet.rb, line 52
def accept_heading heading
  @res << "<p>#{to_html heading.text}\n"

  add_paragraph
end

accept_list_item_end(list_item) click to toggle source

Finishes consumption of list_item

# File lib/rdoc/markup/to_html_snippet.rb, line 81
def accept_list_item_end list_item
end

accept_list_item_start(list_item) click to toggle source

Prepares the visitor for consuming list_item

# File lib/rdoc/markup/to_html_snippet.rb, line 87
def accept_list_item_start list_item
  @res << list_item_start(list_item, @list.last)
end

accept_list_start(list) click to toggle source

Prepares the visitor for consuming list

# File lib/rdoc/markup/to_html_snippet.rb, line 94
def accept_list_start list
  @list << list.type
  @res << html_list_name(list.type, true)
  @in_list_entry.push ''
end

accept_paragraph(paragraph) click to toggle source

# File lib/rdoc/markup/to_html_snippet.rb, line 68
def accept_paragraph paragraph
  para = @in_list_entry.last || "<p>"

  text = paragraph.text @hard_break

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

  add_paragraph
end

accept_verbatim(verbatim) click to toggle source

Adds verbatim to the output

Calls superclass method RDoc::Markup::ToHtml#accept_verbatim

# File lib/rdoc/markup/to_html_snippet.rb, line 103
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() click to toggle source

Throws :done when #paragraph_limit paragraphs have been encountered

# File lib/rdoc/markup/to_html_snippet.rb, line 194
def add_paragraph
  @paragraphs += 1

  throw :done if @paragraphs >= @paragraph_limit
end

convert(content) click to toggle source

Marks up content

Calls superclass method RDoc::Markup::Formatter#convert

# File lib/rdoc/markup/to_html_snippet.rb, line 203
def convert content
  catch :done do
    return super
  end

  end_accepting
end

convert_flow(flow) click to toggle source

Converts flow items flow

# File lib/rdoc/markup/to_html_snippet.rb, line 214
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::Special then
      text = convert_special 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) click to toggle source

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

# File lib/rdoc/markup/to_html_snippet.rb, line 167
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_special_CROSSREF(special) click to toggle source

Removes escaping from the cross-references in special

# File lib/rdoc/markup/to_html_snippet.rb, line 127
def handle_special_CROSSREF special
  special.text.sub(/\A\\/, '')
end

handle_special_HARD_BREAK(special) click to toggle source

special is a

# File lib/rdoc/markup/to_html_snippet.rb, line 134
def handle_special_HARD_BREAK special
  @characters -= 4
  '<br>'
end

html_list_name(list_type, open_tag) click to toggle source

In snippets, there are no lists

# File lib/rdoc/markup/to_html_snippet.rb, line 187
def html_list_name list_type, open_tag
  ''
end

list_item_start(list_item, list_type) click to toggle source

Lists are paragraphs, but notes and labels have a separator

# File lib/rdoc/markup/to_html_snippet.rb, line 142
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) click to toggle source

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

Calls superclass method RDoc::Markup::Formatter#off_tags

# File lib/rdoc/markup/to_html_snippet.rb, line 260
def off_tags res, item
  @mask ^= item.turn_off

  super
end

on_tags(res, item) click to toggle source

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

Calls superclass method RDoc::Markup::Formatter#on_tags

# File lib/rdoc/markup/to_html_snippet.rb, line 250
def on_tags res, item
  @mask ^= item.turn_on

  super
end

start_accepting() click to toggle source

Prepares the visitor for HTML snippet generation

Calls superclass method RDoc::Markup::ToHtml#start_accepting

# File lib/rdoc/markup/to_html_snippet.rb, line 118
def start_accepting
  super

  @characters = 0
end

truncate(text) click to toggle source

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

# File lib/rdoc/markup/to_html_snippet.rb, line 269
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