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



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



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

#accept_document(document) ⇒ Object

Adds document to the output



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

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



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

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>



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

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



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

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.



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

def annotate(tag)
  tag
end

#convert(content) ⇒ Object

Marks up content



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

def convert content
  @markup.convert content, self
end

#convert_flow(flow) ⇒ Object

Converts flow items flow



126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/rdoc/markup/formatter.rb', line 126

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



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/rdoc/markup/formatter.rb', line 149

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



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

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



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

def ignore *node
end

#in_tt? ⇒ Boolean

Are we currently inside tt tags?

Returns:

  • (Boolean) 


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

def in_tt?
  @in_tt > 0
end

#off_tags(res, item) ⇒ Object

Turns off tags for item on res



215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/rdoc/markup/formatter.rb', line 215

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



200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/rdoc/markup/formatter.rb', line 200

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.



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
255
 
# File 'lib/rdoc/markup/formatter.rb', line 230

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) 


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

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