Home Classes Methods

In Files

rdoc/markup/to_html_snippet.rb

Parent

RDoc::Markup::ToHtml

Methods

::new
#accept_heading
#accept_list_item_end
#accept_list_item_start
#accept_list_start
#accept_paragraph
#accept_verbatim
#add_paragraph
#convert
#convert_flow
#gen_url
#handle_special_CROSSREF
#handle_special_HARD_BREAK
#html_list_name
#list_item_start
#off_tags
#on_tags
#start_accepting
#truncate

Class/Module Index

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.

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

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

 
               # File 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 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 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 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 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 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 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.

 
               # File 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.

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

 
               # File 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 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|$)/ # TODO word-break instead of \s?

  $1
end

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please see Improve the docs, or visit Documenting-ruby.org.