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 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

Public Instance Methods

accept_heading(heading) click to toggle source

Adds heading to the output as a paragraph

# File 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) click to toggle source

Finishes consumption of list_item

# File rdoc/markup/to_html_snippet.rb, line 85
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 rdoc/markup/to_html_snippet.rb, line 91
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 rdoc/markup/to_html_snippet.rb, line 98
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

Adds paragraph to the output

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

Adds verbatim to the output

Calls superclass method

# File rdoc/markup/to_html_snippet.rb, line 107
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 rdoc/markup/to_html_snippet.rb, line 198
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 rdoc/markup/to_html_snippet.rb, line 207
def convert content
  catch :done do
    return super
  end

  end_accepting
end

convert_flow(flow) click to toggle source

Converts flow items flow

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

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

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

Removes escaping from the cross-references in target

# File rdoc/markup/to_html_snippet.rb, line 131
def handle_regexp_CROSSREF target
  target.text.sub(/\A\\/, '')
end

handle_regexp_HARD_BREAK(target) click to toggle source

target is a <br>

# File rdoc/markup/to_html_snippet.rb, line 138
def handle_regexp_HARD_BREAK target
  @characters -= 4
  '<br>'
end

html_list_name(list_type, open_tag) click to toggle source

In snippets, there are no lists

# File rdoc/markup/to_html_snippet.rb, line 191
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 rdoc/markup/to_html_snippet.rb, line 146
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 rdoc/markup/to_html_snippet.rb, line 264
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 rdoc/markup/to_html_snippet.rb, line 254
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

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