Home Classes Methods

In Files

rdoc/markup/formatter.rb

Parent

Object

Methods

::gen_relative_url
::new
#accept_document
#add_special_RDOCLINK
#add_special_TIDYLINK
#add_tag
#annotate
#convert
#convert_flow
#convert_special
#convert_string
#ignore
#in_tt?
#off_tags
#on_tags
#parse_url
#tt?

Class/Module Index

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

Adds a special for links of the form rdoc-…:

 
               # File rdoc/markup/formatter.rb, line 82
def add_special_RDOCLINK
  @markup.add_special(/rdoc-[a-z]+:\S+/, :RDOCLINK)
end

add_special_TIDYLINK() click to toggle source

Adds a special for links of the form ”>word>

 
               # File rdoc/markup/formatter.rb, line 89
def add_special_TIDYLINK
  @markup.add_special(/(?:
                        \{.*?\} |   # multi-word label
                        \b[^\s{}]+? # single-word label
                       )

                       \[\S+?\]     # link target
                      /, :TIDYLINK)
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 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 rdoc/markup/formatter.rb, line 111
def annotate(tag)
  tag
end

convert(content) click to toggle source

Marks up content

 
               # File 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 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 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 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 rdoc/markup/formatter.rb, line 186
def ignore *node
end

in_tt?() click to toggle source

Are we currently inside tt tags?

 
               # File 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 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 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 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    = "http://#{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 rdoc/markup/formatter.rb, line 259
def tt? tag
  tag.bit == @tt_bit
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.