Class: RDoc::Markup::Formatter

Inherits:
Object
  • Object
show all
Defined in:
lib/rdoc/markup/formatter.rb

Overview

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.

Defined Under Namespace

Classes: InlineTag

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options, markup = nil) ⇒ Formatter

Creates a new Formatter



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# 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

Class Method Details

.gen_relative_url(path, target) ⇒ Object

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



23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# 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

Instance Method Details

#accept_document(document) ⇒ Object

Adds document to the output



68
69
70
71
72
73
74
75
76
77
 
# 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_special_RDOCLINK ⇒ Object

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



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

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

#add_special_TIDYLINK ⇒ Object

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



89
90
91
92
93
94
95
96
97
 
# File 'lib/rdoc/markup/formatter.rb', line 89

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

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

#add_tag(name, start, stop) ⇒ Object

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



103
104
105
106
 
# 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) ⇒ Object

Allows tag to be decorated with additional information.



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

def annotate(tag)
  tag
end

#convert(content) ⇒ Object

Marks up content



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

def convert content
  @markup.convert content, self
end

#convert_flow(flow) ⇒ Object

Converts flow items flow



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# 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) ⇒ Object

Converts added specials. See RDoc::Markup#add_special



148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# 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) ⇒ Object

Converts a string to be fancier if desired



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

def convert_string string
  string
end

#ignore(*node) ⇒ Object

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

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

alias accept_raw ignore



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

def ignore *node
end

#in_tt? ⇒ Boolean

Are we currently inside tt tags?

Returns:

  • (Boolean) 


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

def in_tt?
  @in_tt > 0
end

#off_tags(res, item) ⇒ Object

Turns off tags for item on res



214
215
216
217
218
219
220
221
222
223
224
 
# 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) ⇒ Object

Turns on tags for item on res



199
200
201
202
203
204
205
206
207
208
209
 
# 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) ⇒ Object

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



229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
 
# 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) ⇒ Boolean

Is tag a tt tag?

Returns:

  • (Boolean) 


259
260
261
 
# File 'lib/rdoc/markup/formatter.rb', line 259

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