class RDoc::Markup::ToHtmlSnippet

frozen_string_literal: true

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

Finishes consumption of list_item

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

Throws :done when #paragraph_limit paragraphs have been encountered

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

Removes escaping from the cross-references in target

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

target is a

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

In snippets, there are no lists

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

Lists are paragraphs, but notes and labels have a separator

# 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) 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 261
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 251
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 119
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 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