Class: RDoc::Markup::Formatter
- Inherits:
-
Object
- Object
- RDoc::Markup::Formatter
- Defined in:
- lib/rdoc/markup/formatter.rb
Overview
frozen_string_literal: false
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.
Direct Known Subclasses
ToHtml, ToJoinedParagraph, ToLabel, ToRdoc, ToTableOfContents, ToTest, ToTtOnly
Defined Under Namespace
Classes: InlineTag
Class Method Summary collapse
-
.gen_relative_url(path, target) ⇒ Object
Converts a target url to one that is relative to a given path.
Instance Method Summary collapse
-
#accept_document(document) ⇒ Object
Adds
document
to the output. -
#add_special_RDOCLINK ⇒ Object
Adds a special for links of the form rdoc-…:.
- #add_special_TIDYLINK ⇒ Object
-
#add_tag(name, start, stop) ⇒ Object
Add a new set of tags for an attribute.
-
#annotate(tag) ⇒ Object
Allows
tag
to be decorated with additional information. -
#convert(content) ⇒ Object
Marks up
content
. -
#convert_flow(flow) ⇒ Object
Converts flow items
flow
. -
#convert_special(special) ⇒ Object
Converts added specials.
-
#convert_string(string) ⇒ Object
Converts a string to be fancier if desired.
-
#ignore(*node) ⇒ Object
Use ignore in your subclass to ignore the content of a node.
-
#in_tt? ⇒ Boolean
Are we currently inside tt tags?.
-
#initialize(options, markup = nil) ⇒ Formatter
constructor
Creates a new Formatter.
-
#off_tags(res, item) ⇒ Object
Turns off tags for
item
onres
. -
#on_tags(res, item) ⇒ Object
Turns on tags for
item
onres
. -
#parse_url(url) ⇒ Object
Extracts and a scheme, url and an anchor id from
url
and returns them. -
#tt?(tag) ⇒ Boolean
Is
tag
a tt tag?.
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 , markup = nil @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
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 res, item 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?
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 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 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?
260 261 262 |
# File 'lib/rdoc/markup/formatter.rb', line 260 def tt? tag tag.bit == @tt_bit end |