class RDoc::Markup::ToHtmlSnippet

Outputs RDoc markup as paragraphs with inline markup only.

Attributes

After this many characters the input will be cut off.

The attribute bitmask

After this many paragraphs the input will be cut off.

Count of paragraphs found

Public Class Methods

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

Adds heading to the output as a paragraph

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

  add_paragraph
end

Finishes consumption of list_item

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

Prepares the visitor for consuming list_item

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

Prepares the visitor for consuming list

# File lib/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

Adds paragraph to the output

# File lib/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

Adds verbatim to the output

Calls superclass method
# File lib/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

Throws :done when paragraph_limit paragraphs have been encountered

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

  throw :done if @paragraphs >= @paragraph_limit
end

Marks up content

Calls superclass method RDoc::Markup::Formatter#convert
# File lib/rdoc/markup/to_html_snippet.rb, line 207
def convert content
  catch :done do
    return super
  end

  end_accepting
end

Converts flow items flow

# File lib/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

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

# File lib/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

Removes escaping from the cross-references in target

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

target is a <br>

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

In snippets, there are no lists

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

Lists are paragraphs, but notes and labels have a separator

# File lib/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

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 264
def off_tags res, item
  @mask ^= item.turn_off

  super
end

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 254
def on_tags res, item
  @mask ^= item.turn_on

  super
end

Prepares the visitor for HTML snippet generation

Calls superclass method
# File lib/rdoc/markup/to_html_snippet.rb, line 122
def start_accepting
  super

  @characters = 0
end

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

# File lib/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