Module: YARD::Templates::Helpers::HtmlHelper
- Includes:
- HtmlSyntaxHighlightHelper, MarkupHelper
- Defined in:
- lib/yard/templates/helpers/html_helper.rb
Overview
The helper module for HTML templates.
Constant Summary
Constants included from MarkupHelper
MarkupHelper::MARKUP_EXTENSIONS, MarkupHelper::MARKUP_FILE_SHEBANG, MarkupHelper::MARKUP_PROVIDERS
Escaping Template Data collapse
-
#h(text) ⇒ String
Escapes HTML entities.
-
#urlencode(text) ⇒ String
Escapes a URL.
Converting Markup to HTML collapse
-
#html_markup_asciidoc(text) ⇒ String
Converts Asciidoc to HTML.
-
#html_markup_html(text) ⇒ String
Converts HTML to HTML.
-
#html_markup_markdown(text) ⇒ String
Converts Markdown to HTML.
-
#html_markup_none(text) ⇒ String
The same text with no markup.
-
#html_markup_pre(text) ⇒ String
Converts plaintext to pre-formatted HTML.
-
#html_markup_rdoc(text) ⇒ String
Converts RDoc formatting (SimpleMarkup) to HTML.
-
#html_markup_ruby(source) ⇒ String
Highlights Ruby source.
-
#html_markup_text(text) ⇒ String
Converts plaintext to regular HTML.
-
#html_markup_textile(text) ⇒ String
Converts Textile to HTML.
-
#html_markup_textile_strict(text) ⇒ String
Converts plaintext to strict Textile (hard breaks).
-
#htmlify(text, markup = options.markup) ⇒ String
Turns text into HTML using
markup
style formatting. -
#htmlify_line(*args) ⇒ String
HTMLified text as a single line (paragraphs removed).
Syntax Highlighting Source Code collapse
-
#html_syntax_highlight(source, type = nil) ⇒ String
Syntax highlights
source
in languagetype
. -
#html_syntax_highlight_plain(source) ⇒ String
Unhighlighted source.
Linking Objects and URLs collapse
-
#insert_include(text, markup = options.markup) ⇒ Object
Inserts an include link while respecting inlining.
-
#link_file(filename, title = nil, anchor = nil) ⇒ String
Links to an extra file.
-
#link_include_file(file) ⇒ String
Include a file as a docstring in output.
-
#link_include_object(obj) ⇒ String
Includes an object’s docstring into output.
-
#link_object(obj, title = nil, anchor = nil, relative = true) ⇒ String
Links to an object with an optional title.
-
#link_url(url, title = nil, params = {}) ⇒ String
Links to a URL.
-
#resolve_links(text) ⇒ String
Resolves any text in the form of {Name} to the object specified by Name.
URL Helpers collapse
-
#anchor_for(object) ⇒ String
The anchor for a specific object.
-
#url_for(obj, anchor = nil, relative = true) ⇒ String
Returns the URL for an object.
-
#url_for_file(filename, anchor = nil) ⇒ String
Returns the URL for a specific file.
-
#url_for_frameset ⇒ String
Returns the URL for the frameset page.
-
#url_for_index ⇒ String
Returns the URL for the alphabetic index page.
-
#url_for_list(type) ⇒ String
Returns the URL for a list type.
-
#url_for_main ⇒ String
Returns the URL for the main page (README or alphabetic index).
Formatting Objects and Attributes collapse
-
#format_object_name_list(objects) ⇒ String
Formats a list of objects and links them.
-
#format_types(typelist, brackets = true) ⇒ String
Formats a list of types from a tag.
-
#signature(meth, link = true, show_extras = true, full_attr_name = true) ⇒ String
Formats the signature of method
meth
. -
#signature_types(meth, link = true) ⇒ String
Get the return types for a method signature.
Getting the Character Encoding collapse
-
#charset ⇒ String
Returns the current character set.
Methods included from HtmlSyntaxHighlightHelper
Methods included from MarkupHelper
clear_markup_cache, #load_markup_provider, #markup_class, #markup_file_contents, #markup_for_file, #markup_provider
Instance Method Details
#anchor_for(object) ⇒ String
Returns the anchor for a specific object.
302 303 304 305 306 307 308 309 310 311 312 313 314 315 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 302 def anchor_for(object) case object when CodeObjects::MethodObject "#{object.name}-#{object.scope}_#{object.type}" when CodeObjects::ClassVariableObject "#{object.name.to_s.gsub('@@', '')}-#{object.type}" when CodeObjects::Base "#{object.name}-#{object.type}" when CodeObjects::Proxy object.path else object.to_s end end |
#charset ⇒ String
Returns the current character set. The default value can be overridden by setting the LANG
environment variable or by overriding this method. In Ruby 1.9 you can also modify this value by setting Encoding.default_external
.
527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 527 def charset has_encoding = defined?(::Encoding) if @file && has_encoding lang = @file.contents.encoding.to_s else return 'utf-8' unless has_encoding || lang = ENV['LANG'] if has_encoding lang = ::Encoding.default_external.name.downcase else lang = lang.downcase.split('.').last end end case lang when "ascii-8bit", "us-ascii", "ascii-7bit"; 'iso-8859-1' when "utf8"; 'utf-8' else; lang end end |
#format_object_name_list(objects) ⇒ String
Formats a list of objects and links them
412 413 414 415 416 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 412 def format_object_name_list(objects) objects.sort_by {|o| o.name.to_s.downcase }.map do |o| "<span class='name'>" + linkify(o, o.name) + "</span>" end.join(", ") end |
#format_types(typelist, brackets = true) ⇒ String
Formats a list of types from a tag.
430 431 432 433 434 435 436 437 438 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 430 def format_types(typelist, brackets = true) return unless typelist.is_a?(Array) list = typelist.map do |type| type = type.gsub(/([<>])/) { h($1) } type = type.gsub(/([\w:]+)/) { $1 == "lt" || $1 == "gt" ? $1 : linkify($1, $1) } "<tt>" + type + "</tt>" end list.empty? ? "" : (brackets ? "(#{list.join(", ")})" : list.join(", ")) end |
#h(text) ⇒ String
Escapes HTML entities
16 17 18 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 16 def h(text) CGI.escapeHTML(text.to_s) end |
#html_markup_asciidoc(text) ⇒ String
Converts Asciidoc to HTML
74 75 76 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 74 def html_markup_asciidoc(text) markup_class(:asciidoc).render(text) end |
#html_markup_html(text) ⇒ String
Converts HTML to HTML
132 133 134 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 132 def html_markup_html(text) text end |
#html_markup_markdown(text) ⇒ String
Converts Markdown to HTML
57 58 59 60 61 62 63 64 65 66 67 68 69 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 57 def html_markup_markdown(text) # TODO: other libraries might be more complex provider = markup_class(:markdown) if provider.to_s == 'RDiscount' provider.new(text, :autolink).to_html elsif provider.to_s == 'RedcarpetCompat' provider.new(text, :no_intraemphasis, :gh_blockcode, :fenced_code, :autolink, :tables, :lax_spacing).to_html else provider.new(text).to_html end end |
#html_markup_none(text) ⇒ String
Returns the same text with no markup.
124 125 126 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 124 def html_markup_none(text) h(text) end |
#html_markup_pre(text) ⇒ String
Converts plaintext to pre-formatted HTML
110 111 112 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 110 def html_markup_pre(text) "<pre>" + h(text) + "</pre>" end |
#html_markup_rdoc(text) ⇒ String
Converts RDoc formatting (SimpleMarkup) to HTML
100 101 102 103 104 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 100 def html_markup_rdoc(text) doc = markup_class(:rdoc).new(text) doc.from_path = url_for(object) if doc.respond_to?(:from_path=) doc.to_html end |
#html_markup_ruby(source) ⇒ String
Highlights Ruby source. Similar to #html_syntax_highlight, but this method is meant to be called from #htmlify when markup is set to “ruby”.
143 144 145 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 143 def html_markup_ruby(source) '<pre class="code ruby">' + html_syntax_highlight(source, :ruby) + '</pre>' end |
#html_markup_text(text) ⇒ String
Converts plaintext to regular HTML
118 119 120 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 118 def html_markup_text(text) h(text).gsub(/\r?\n/, '<br/>') end |
#html_markup_textile(text) ⇒ String
Converts Textile to HTML
82 83 84 85 86 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 82 def html_markup_textile(text) doc = markup_class(:textile).new(text) doc.hard_breaks = false if doc.respond_to?(:hard_breaks=) doc.to_html end |
#html_markup_textile_strict(text) ⇒ String
Converts plaintext to strict Textile (hard breaks)
92 93 94 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 92 def html_markup_textile_strict(text) markup_class(:textile).new(text).to_html end |
#html_syntax_highlight(source, type = nil) ⇒ String
To support a specific language type
, implement the method html_syntax_highlight_TYPE
in this class.
Syntax highlights source
in language type
.
163 164 165 166 167 168 169 170 171 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 163 def html_syntax_highlight(source, type = nil) return "" unless source return h(source) unless .highlight new_type, source = parse_lang_for_codeblock(source) type ||= new_type || :ruby meth = "html_syntax_highlight_#{type}" respond_to?(meth) ? send(meth, source) : h(source) end |
#html_syntax_highlight_plain(source) ⇒ String
Returns unhighlighted source.
174 175 176 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 174 def html_syntax_highlight_plain(source) h(source) end |
#htmlify(text, markup = options.markup) ⇒ String
Turns text into HTML using markup
style formatting.
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 36 def htmlify(text, markup = .markup) markup_meth = "html_markup_#{markup}" return text unless respond_to?(markup_meth) return "" unless text return text unless markup html = send(markup_meth, text) if html.respond_to?(:encode) html = html.force_encoding(text.encoding) # for libs that mess with encoding html = html.encode(:invalid => :replace, :replace => '?') end html = resolve_links(html) unless [:text, :none, :pre].include?(markup) html = parse_codeblocks(html) end html end |
#htmlify_line(*args) ⇒ String
Returns HTMLified text as a single line (paragraphs removed).
148 149 150 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 148 def htmlify_line(*args) "<div class='inline'>" + htmlify(*args) + "</div>" end |
#insert_include(text, markup = options.markup) ⇒ Object
Inserts an include link while respecting inlining
254 255 256 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 254 def insert_include(text, markup = .markup) htmlify(text, markup).gsub(/\A\s*<p>|<\/p>\s*\Z/, '') end |
#link_file(filename, title = nil, anchor = nil) ⇒ String
Links to an extra file
228 229 230 231 232 233 234 235 236 237 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 228 def link_file(filename, title = nil, anchor = nil) if CodeObjects::ExtraFileObject === filename file = filename else contents = File.file?(filename) ? nil : '' file = CodeObjects::ExtraFileObject.new(filename, contents) end return title || file.title unless serializer link_url(url_for_file(file, anchor), title || file.title) end |
#link_include_file(file) ⇒ String
Include a file as a docstring in output
240 241 242 243 244 245 246 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 240 def link_include_file(file) unless file.is_a?(CodeObjects::ExtraFileObject) file = CodeObjects::ExtraFileObject.new(file) end file.attributes[:markup] ||= markup_for_file('', file.filename) insert_include(file.contents, file.attributes[:markup] || .markup) end |
#link_include_object(obj) ⇒ String
Includes an object’s docstring into output.
249 250 251 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 249 def link_include_object(obj) insert_include(obj.docstring) end |
#link_object(obj, title = nil, anchor = nil, relative = true) ⇒ String
Links to an object with an optional title
259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 259 def link_object(obj, title = nil, anchor = nil, relative = true) return title if obj.nil? obj = Registry.resolve(object, obj, true, true) if obj.is_a?(String) if title title = title.to_s elsif object.is_a?(CodeObjects::Base) # Check if we're linking to a class method in the current # object. If we are, create a title in the format of # "CurrentClass.method_name" if obj.is_a?(CodeObjects::MethodObject) && obj.scope == :class && obj.parent == object title = h([object.name, obj.sep, obj.name].join) elsif obj.title != obj.path title = h(obj.title) else title = h(object.relative_path(obj)) end else title = h(obj.title) end return title unless serializer return title if obj.is_a?(CodeObjects::Proxy) link = url_for(obj, anchor, relative) link = link ? link_url(link, title, :title => h("#{obj.title} (#{obj.type})")) : title "<span class='object_link'>" + link + "</span>" end |
#link_url(url, title = nil, params = {}) ⇒ String
Links to a URL
287 288 289 290 291 292 293 294 295 296 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 287 def link_url(url, title = nil, params = {}) title ||= url title.gsub!(/[\r\n]/, ' ') params = SymbolHash.new(false).update( :href => url, :title => h(title) ).update(params) params[:target] ||= '_parent' if url =~ /^(\w+):\/\// "<a #{tag_attrs(params)}>#{title}</a>".gsub(/[\r\n]/, ' ') end |
#resolve_links(text) ⇒ String
Resolves any text in the form of {Name} to the object specified by Name. Also supports link titles in the form {Name title}.
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 189 def resolve_links(text) = 0 text.gsub(/<(\/)?(pre|code|tt)|(\\|!)?\{(?!\})(\S+?)(?:\s([^\}]*?\S))?\}(?=[\W<]|.+<\/|$)/m) do |str| closed, tag, escape, name, title, match = $1, $2, $3, $4, $5, $& if tag += (closed ? -1 : 1) next str end next str unless == 0 next(match[1..-1]) if escape next(match) if name[0,1] == '|' if name == '<a' && title =~ /href=["'](.+?)["'].*>.*<\/a>\s*(.*)\Z/ name, title = $1, $2 title = nil if title.empty? end name = CGI.unescapeHTML(name) if object.is_a?(String) object else link = linkify(name, title) if (link == name || link == title) && (name+' '+link !~ /\A<a\s.*>/) match = /(.+)?(\{#{Regexp.quote name}(?:\s.*?)?\})(.+)?/.match(text) file = (@file ? @file.filename : object.file) || '(unknown)' line = (@file ? 1 : (object.docstring.line_range ? object.docstring.line_range.first : 1)) + (match ? $`.count("\n") : 0) log.warn "In file `#{file}':#{line}: Cannot resolve link to #{name} from text" + (match ? ":" : ".") log.warn((match[1] ? '...' : '') + match[2].gsub("\n","") + (match[3] ? '...' : '')) if match end link end end end |
#signature(meth, link = true, show_extras = true, full_attr_name = true) ⇒ String
Formats the signature of method meth
.
483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 483 def signature(meth, link = true, show_extras = true, full_attr_name = true) meth = convert_method_to_overload(meth) type = signature_types(meth, link) type = "⇒ #{type}" if type && !type.empty? scope = meth.scope == :class ? "." : "#" name = full_attr_name ? meth.name : meth.name.to_s.gsub(/^(\w+)=$/, '\1') blk = format_block(meth) args = !full_attr_name && meth.writer? ? "" : format_args(meth) extras = [] extras_text = '' if show_extras if rw = meth.attr_info attname = [rw[:read] ? 'read' : nil, rw[:write] ? 'write' : nil].compact attname = attname.size == 1 ? attname.join('') + 'only' : nil extras << attname if attname end extras << meth.visibility if meth.visibility != :public extras_text = ' <span class="extras">(' + extras.join(", ") + ')</span>' unless extras.empty? end title = "%s<strong>%s</strong>%s %s %s" % [scope, h(name), args, blk, type] if link if meth.is_a?(YARD::CodeObjects::MethodObject) link_title = "#{h meth.name(true)} (#{meth.scope} #{meth.type})" else link_title = "#{h name} (#{meth.type})" end obj = meth.respond_to?(:object) ? meth.object : meth url = url_for(object, obj) link_url(url, title, :title => link_title) + extras_text else title + extras_text end end |
#signature_types(meth, link = true) ⇒ String
Get the return types for a method signature.
446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 446 def signature_types(meth, link = true) meth = convert_method_to_overload(meth) if meth.respond_to?(:object) && !meth.has_tag?(:return) meth = meth.object end type = .default_return || "" if meth.tag(:return) && meth.tag(:return).types types = meth.(:return).map {|t| t.types ? t.types : [] }.flatten.uniq first = link ? h(types.first) : format_types([types.first], false) if types.size == 2 && types.last == 'nil' type = first + '<sup>?</sup>' elsif types.size == 2 && types.last =~ /^(Array)?<#{Regexp.quote types.first}>$/ type = first + '<sup>+</sup>' elsif types.size > 2 type = [first, '...'].join(', ') elsif types == ['void'] && .hide_void_return type = "" else type = link ? h(types.join(", ")) : format_types(types, false) end elsif !type.empty? type = link ? h(type) : format_types([type], false) end type = "#{type} " unless type.empty? type end |
#url_for(obj, anchor = nil, relative = true) ⇒ String
Returns the URL for an object.
323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 323 def url_for(obj, anchor = nil, relative = true) link = nil return link unless serializer return link if obj.is_a?(CodeObjects::Base) && run_verifier([obj]).empty? if obj.is_a?(CodeObjects::Base) && !obj.is_a?(CodeObjects::NamespaceObject) # If the obj is not a namespace obj make it the anchor. anchor, obj = obj, obj.namespace end objpath = serializer.serialized_path(obj) return link unless objpath relative = false if object == Registry.root if relative fromobj = object if object.is_a?(CodeObjects::Base) && !object.is_a?(CodeObjects::NamespaceObject) fromobj = owner end from = serializer.serialized_path(fromobj) link = File.relative_path(from, objpath) else link = objpath end link + (anchor ? '#' + urlencode(anchor_for(anchor)) : '') end |
#url_for_file(filename, anchor = nil) ⇒ String
Returns the URL for a specific file
358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 358 def url_for_file(filename, anchor = nil) return '' unless serializer fromobj = object if CodeObjects::Base === fromobj && !fromobj.is_a?(CodeObjects::NamespaceObject) fromobj = fromobj.namespace end from = serializer.serialized_path(fromobj) if filename == .readme path = 'index.html' else path = serializer.serialized_path(filename) end link = File.relative_path(from, path) link += (anchor ? '#' + urlencode(anchor) : '') link end |
#url_for_frameset ⇒ String
Returns the URL for the frameset page
388 389 390 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 388 def url_for_frameset url_for_file("frames.html") end |
#url_for_index ⇒ String
Returns the URL for the alphabetic index page
404 405 406 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 404 def url_for_index url_for_file("_index.html") end |
#url_for_list(type) ⇒ String
Returns the URL for a list type
380 381 382 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 380 def url_for_list(type) url_for_file("#{type}_list.html") end |
#url_for_main ⇒ String
Returns the URL for the main page (README or alphabetic index)
396 397 398 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 396 def url_for_main url_for_file("index.html") end |
#urlencode(text) ⇒ String
Escapes a URL
24 25 26 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 24 def urlencode(text) CGI.escape(text.to_s) end |