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_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) ⇒ 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_regexp_handling_RDOCLINK ⇒ Object

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



83
84
85
 
# 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 ⇒ Object

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



91
92
93
94
95
96
97
98
99
 
# 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) ⇒ Object

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



105
106
107
108
 
# 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) ⇒ Object

Allows tag to be decorated with additional information.



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

def annotate(tag)
  tag
end

#convert(content) ⇒ Object

Marks up content



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

def convert content
  @markup.convert content, self
end

#convert_flow(flow) ⇒ Object

Converts flow items flow



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

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



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

Converts a string to be fancier if desired



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

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



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

def ignore *node
end

#in_tt? ⇒ Boolean

Are we currently inside tt tags?

Returns:

  • (Boolean) 


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

def in_tt?
  @in_tt > 0
end

#off_tags(res, item) ⇒ Object

Turns off tags for item on res



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

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



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

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.



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

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) 


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

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