Class: RDoc::Markup::Formatter

Relationships & Source Files
Namespace Children
Classes: `InlineTag`
Extension / Inclusion / Inheritance Descendants
Subclasses: ToAnsi, ToBs, ToHtml, ToHtmlCrossref, ToHtmlSnippet, ToJoinedParagraph, ToLabel, ToMarkdown, ToRdoc, ToTableOfContents, ToTest, ToTtOnly
Inherits:	Object
Defined in:	lib/rdoc/markup/formatter.rb

Overview

Base class for ::RDoc::RDoc markup formatters

Formatters are a visitor that converts an ::RDoc::Markup tree (from a comment) into some kind of output. ::RDoc::RDoc ships with formatters for converting back to rdoc, ANSI text, HTML, a Table of Contents and other formats.

If you’d like to write your own Formatter use RDoc::Markup::FormatterTestCase. If you’re writing a text-output formatter use RDoc::Markup::TextFormatterTestCase which provides extra test cases.

Class Method Summary

.gen_relative_url(path, target)

Converts a target url to one that is relative to a given path.
.new(options, markup = nil) ⇒ Formatter constructor

Creates a new Formatter.

Instance Attribute Summary

#in_tt? ⇒ Boolean readonly

Are we currently inside tt tags?

Instance Method Summary

#accept_document(document)

Adds document to the output.
#add_regexp_handling_RDOCLINK

Adds a regexp handling for links of the form rdoc-…:
#add_regexp_handling_TIDYLINK

Adds a regexp handling for links of the form <text> and <word>.
#add_tag(name, start, stop)

Add a new set of tags for an attribute.
#annotate(tag)

Allows tag to be decorated with additional information.
#convert(content)

Marks up content
#convert_flow(flow)

Converts flow items flow
#convert_regexp_handling(target)

Converts added regexp handlings.
#convert_string(string)

Converts a string to be fancier if desired.
#each_attr_tag(attr_mask, reverse = false)
#ignore(*node) (also: #accept_raw, #accept_rule, #accept_block_quote, #accept_heading, #accept_list_end, #accept_list_item_end, #accept_list_item_start, #accept_list_start, #accept_raw, #accept_rule, #accept_verbatim, #accept_table, #accept_block_quote, #accept_raw, #accept_rule, #accept_blank_line, #accept_paragraph, #accept_verbatim, #accept_list_end, #accept_list_item_start, #accept_list_item_end, #accept_list_end_bullet, #accept_list_start, #accept_table)

Use ignore in your subclass to ignore the content of a node.
#off_tags(res, item)

Turns off tags for item on res
#on_tags(res, item)

Turns on tags for item on res
#parse_url(url)

Extracts and a scheme, url and an anchor id from url and returns them.
#tt?(tag) ⇒ Boolean

Is tag a tt tag?
#tt_tag?(attr_mask, reverse = false) ⇒ Boolean

Constructor Details

.new(options, markup = nil) ⇒ `Formatter`

Creates a new Formatter

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 48


def initialize(options, markup = nil)
  @options = options

  @markup = markup || RDoc::Markup.new
  @am     = @markup.attribute_manager
  @am.add_regexp_handling(/<br>/, :HARD_BREAK)

  @attributes = @am.attributes

  @attr_tags = []

  @in_tt = 0
  @tt_bit = @attributes.bitmap_for :TT

  @hard_break = ''
  @from_path = '.'
end

Class Method Details

.gen_relative_url(path, target)

Converts a target url to one that is relative to a given path

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 24


def self.gen_relative_url(path, target)
  from        = File.dirname path
  to, to_file = File.split target

  from = from.split "/"
  to   = to.split "/"

  from.delete '.'
  to.delete '.'

  while from.size > 0 and to.size > 0 and from[0] == to[0] do
    from.shift
    to.shift
  end

  from.fill ".."
  from.concat to
  from << to_file
  File.join(*from)
end

Instance Attribute Details

#in_tt? ⇒ `Boolean` (readonly)

Are we currently inside tt tags?

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 194


def in_tt?
  @in_tt > 0
end

Instance Method Details

#accept_document(document)

Adds document to the output

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 69


def accept_document(document)
  document.parts.each do |item|
    case item
    when RDoc::Markup::Document then # HACK
      accept_document item
    else
      item.accept self
    end
  end
end

#add_regexp_handling_RDOCLINK

Adds a regexp handling for links of the form rdoc-…:

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 83


def add_regexp_handling_RDOCLINK
  @markup.add_regexp_handling(/rdoc-[a-z]:[^\s\]]/, :RDOCLINK)
end

#add_regexp_handling_TIDYLINK

Adds a regexp handling for links of the form <text> and <word>

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 91


def add_regexp_handling_TIDYLINK
  @markup.add_regexp_handling(/(?:
                                \{[^{}]*\} | # multi-word label
                                \b[^\s{}]+? # single-word label
                               )

                               \[\S+?\]     # link target
                              /x, :TIDYLINK)
end

#add_tag(name, start, stop)

Add a new set of tags for an attribute. We allow separate start and end tags for flexibility

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 105


def add_tag(name, start, stop)
  attr = @attributes.bitmap_for name
  @attr_tags << InlineTag.new(attr, start, stop)
end

#annotate(tag)

Allows tag to be decorated with additional information.

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 113


def annotate(tag)
  tag
end

#convert(content)

Marks up content

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 120


def convert(content)
  @markup.convert content, self
end

#convert_flow(flow)

Converts flow items flow

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 127


def convert_flow(flow)
  res = []

  flow.each do |item|
    case item
    when String then
      res << convert_string(item)
    when RDoc::Markup::AttrChanger then
      off_tags res, item
      on_tags res, item
    when RDoc::Markup::RegexpHandling then
      res << convert_regexp_handling(item)
    else
      raise "Unknown flow element: #{item.inspect}"
    end
  end

  res.join
end

#convert_regexp_handling(target)

Converts added regexp handlings. See RDoc::Markup#add_regexp_handling

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 150


def convert_regexp_handling(target)
  return target.text if in_tt?

  handled = false

  @attributes.each_name_of target.type do |name|
    method_name = "handle_regexp_#{name}"

    if respond_to? method_name then
      target.text = public_send method_name, target
      handled = true
    end
  end

  unless handled then
    target_name = @attributes.as_string target.type

    raise RDoc::Error, "Unhandled regexp handling #{target_name}: #{target}"
  end

  target.text
end

#convert_string(string)

Converts a string to be fancier if desired

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 176


def convert_string(string)
  string
end

#each_attr_tag(attr_mask, reverse = false)

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 225


def each_attr_tag(attr_mask, reverse = false)
  return if attr_mask.zero?

  @attr_tags.public_send(reverse ? :reverse_each : :each) do |tag|
    if attr_mask & tag.bit != 0 then
      yield tag
    end
  end
end

#ignore(*node) Also known as: #accept_raw, #accept_rule, #accept_block_quote, #accept_heading, #accept_list_end, #accept_list_item_end, #accept_list_item_start, #accept_list_start, #accept_raw, #accept_rule, #accept_verbatim, #accept_table, #accept_block_quote, #accept_raw, #accept_rule, #accept_blank_line, #accept_paragraph, #accept_verbatim, #accept_list_end, #accept_list_item_start, #accept_list_item_end, #accept_list_end_bullet, #accept_list_start, #accept_table

Use ignore in your subclass to ignore the content of a node.

##
# We don't support raw nodes in ToNoRaw

alias accept_raw ignore

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 188


def ignore *node
end

#off_tags(res, item)

Turns off tags for item on res

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 218


def off_tags(res, item)
  each_attr_tag(item.turn_off, true) do |tag|
    @in_tt -= 1 if tt? tag
    res << annotate(tag.off)
  end
end

#on_tags(res, item)

Turns on tags for item on res

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 208


def on_tags(res, item)
  each_attr_tag(item.turn_on) do |tag|
    res << annotate(tag.on)
    @in_tt += 1 if tt? tag
  end
end

#parse_url(url)

Extracts and a scheme, url and an anchor id from url and returns them.

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 238


def parse_url(url)
  case url
  when /^rdoc-label:([^:]*)(?::(.*))?/ then
    scheme = 'link'
    path   = "##{$1}"
    id     = " id=\"#{$2}\"" if $2
  when /([A-Za-z]+):(.*)/ then
    scheme = $1.downcase
    path   = $2
  when /^#/ then
  else
    scheme = 'http'
    path   = url
    url    = url
  end

  if scheme == 'link' then
    url = if path[0, 1] == '#' then # is this meaningful?
            path
          else
            self.class.gen_relative_url @from_path, path
          end
  end

  [scheme, url, id]
end

#tt?(tag) ⇒ `Boolean`

Is tag a tt tag?

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 268


def tt?(tag)
  tag.bit == @tt_bit
end

#tt_tag?(attr_mask, reverse = false) ⇒ `Boolean`

[ GitHub ]

# File 'lib/rdoc/markup/formatter.rb', line 198


def tt_tag?(attr_mask, reverse = false)
  each_attr_tag(attr_mask, reverse) do |tag|
    return true if tt? tag
  end
  false
end

Class: RDoc::Markup::Formatter

Overview

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(options, markup = nil) ⇒ Formatter

Class Method Details

.gen_relative_url(path, target)

Instance Attribute Details

#in_tt? ⇒ Boolean (readonly)

Instance Method Details

#accept_document(document)

#add_regexp_handling_RDOCLINK

#add_regexp_handling_TIDYLINK

#add_tag(name, start, stop)

#annotate(tag)

#convert(content)

#convert_flow(flow)

#convert_regexp_handling(target)

#convert_string(string)

#each_attr_tag(attr_mask, reverse = false)

#off_tags(res, item)

#on_tags(res, item)

#parse_url(url)

#tt?(tag) ⇒ Boolean

#tt_tag?(attr_mask, reverse = false) ⇒ Boolean

.new(options, markup = nil) ⇒ `Formatter`

#in_tt? ⇒ `Boolean` (readonly)

#tt?(tag) ⇒ `Boolean`

#tt_tag?(attr_mask, reverse = false) ⇒ `Boolean`