class RDoc::Markup::Formatter

Base class for RDoc markup formatters

Formatters are a visitor that converts an RDoc::Markup tree (from a comment) into some kind of output. 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.

Constants

InlineTag

Tag for inline markup containing a bit for the bitmask and the on and off triggers.

Public Class Methods

gen_relative_url(path, target) click to toggle source

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

# File lib/rdoc/markup/formatter.rb, line 23
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
new(options, markup = nil) click to toggle source

Creates a new Formatter 

# File lib/rdoc/markup/formatter.rb, line 47
def initialize options, markup = nil
 @options = options
 @markup = markup || RDoc::Markup.new
 @am = @markup.attribute_manager
 @am.add_special(/<br>/, :HARD_BREAK)
 @attributes = @am.attributes
 @attr_tags = []
 @in_tt = 0
 @tt_bit = @attributes.bitmap_for :TT
 @hard_break = ''
 @from_path = '.'
end

Public Instance Methods

accept_document(document) click to toggle source

Adds document to the output

# File lib/rdoc/markup/formatter.rb, line 68
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_tag(name, start, stop) click to toggle source

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

# File lib/rdoc/markup/formatter.rb, line 103
def add_tag(name, start, stop)
 attr = @attributes.bitmap_for name
 @attr_tags << InlineTag.new(attr, start, stop)
end
annotate(tag) click to toggle source

Allows tag to be decorated with additional information.

# File lib/rdoc/markup/formatter.rb, line 111
def annotate(tag)
 tag
end
convert(content) click to toggle source

Marks up content

# File lib/rdoc/markup/formatter.rb, line 118
def convert content
 @markup.convert content, self
end
convert_flow(flow) click to toggle source

Converts flow items flow

# File lib/rdoc/markup/formatter.rb, line 125
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::Special then
 res << convert_special(item)
 else
 raise "Unknown flow element: #{item.inspect}"
 end
 end
 res.join
end
convert_special(special) click to toggle source

Converts added specials. See RDoc::Markup#add_special 

# File lib/rdoc/markup/formatter.rb, line 148
def convert_special special
 return special.text if in_tt?
 handled = false
 @attributes.each_name_of special.type do |name|
 method_name = "handle_special_#{name}"
 if respond_to? method_name then
 special.text = send method_name, special
 handled = true
 end
 end
 unless handled then
 special_name = @attributes.as_string special.type
 raise RDoc::Error, "Unhandled special #{special_name}: #{special}"
 end
 special.text
end
convert_string(string) click to toggle source

Converts a string to be fancier if desired

# File lib/rdoc/markup/formatter.rb, line 174
def convert_string string
 string
end
ignore(*node) click to toggle source

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

##
# We don't support raw nodes in ToNoRaw
alias accept_raw ignore

# File lib/rdoc/markup/formatter.rb, line 186
def ignore *node
end
in_tt?() click to toggle source

Are we currently inside tt tags?

# File lib/rdoc/markup/formatter.rb, line 192
def in_tt?
 @in_tt > 0
end
off_tags(res, item) click to toggle source

Turns off tags for item on res

# File lib/rdoc/markup/formatter.rb, line 214
def off_tags res, item
 attr_mask = item.turn_off
 return if attr_mask.zero?
 @attr_tags.reverse_each do |tag|
 if attr_mask & tag.bit != 0 then
 @in_tt -= 1 if tt? tag
 res << annotate(tag.off)
 end
 end
end
on_tags(res, item) click to toggle source

Turns on tags for item on res

# File lib/rdoc/markup/formatter.rb, line 199
def on_tags res, item
 attr_mask = item.turn_on
 return if attr_mask.zero?
 @attr_tags.each do |tag|
 if attr_mask & tag.bit != 0 then
 res << annotate(tag.on)
 @in_tt += 1 if tt? tag
 end
 end
end
parse_url(url) click to toggle source

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

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

Is tag a tt tag?

# File lib/rdoc/markup/formatter.rb, line 259
def tt? tag
 tag.bit == @tt_bit
end