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
-
.urlencode(text) ⇒ String
Escapes a URL.
-
#h(text) ⇒ String
Escapes HTML entities.
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_org(text) ⇒ String
Converts org-mode to HTML.
-
#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.
- #mtime(_file) ⇒ Object
-
#url_for(obj, anchor = nil, relative = true) ⇒ String
(also: #mtime_url)
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 ModuleHelper
Methods included from MarkupHelper
clear_markup_cache, #load_markup_provider, #markup_class, #markup_file_contents, #markup_for_file, #markup_provider
Class Method Details
.urlencode(text) ⇒ String
Escapes a URL
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 31 def urlencode(text) text = text.dup enc = nil if text.respond_to?(:force_encoding) enc = text.encoding text = text.force_encoding('binary') end text = text.gsub(/%[a-z0-9]{2}|#{URLMATCH}/i) do $&.size > 1 ? $& : "%" + $&.ord.to_s(16).upcase end.tr(' ', '+') text = text.force_encoding(enc) if enc text end |
Instance Method Details
#anchor_for(object) ⇒ String
Returns the anchor for a specific object.
337 338 339 340 341 342 343 344 345 346 347 348 349 350 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 337 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
.
564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 564 def charset has_encoding = defined?(::Encoding) if defined?(@file) && @file && has_encoding lang = @file.contents.encoding.to_s else return 'utf-8' unless has_encoding || ENV['LANG'] lang = if has_encoding ::Encoding.default_external.name.downcase else ENV['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
448 449 450 451 452 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 448 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.
466 467 468 469 470 471 472 473 474 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 466 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
23 24 25 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 23 def h(text) CGI.escapeHTML(text.to_s) end |
#html_markup_asciidoc(text) ⇒ String
Converts Asciidoc to HTML
102 103 104 105 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 102 def html_markup_asciidoc(text) = {:attributes => ASCIIDOC_ATTRIBUTES} markup_class(:asciidoc).render(text, ) end |
#html_markup_html(text) ⇒ String
Converts HTML to HTML
161 162 163 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 161 def html_markup_html(text) text end |
#html_markup_markdown(text) ⇒ String
Converts Markdown to HTML
78 79 80 81 82 83 84 85 86 87 88 89 90 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 78 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.
153 154 155 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 153 def html_markup_none(text) h(text) end |
#html_markup_org(text) ⇒ String
Converts org-mode to HTML
95 96 97 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 95 def html_markup_org(text) markup_class(:org).new(text).to_html end |
#html_markup_pre(text) ⇒ String
Converts plaintext to pre-formatted HTML
139 140 141 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 139 def html_markup_pre(text) "<pre>" + h(text) + "</pre>" end |
#html_markup_rdoc(text) ⇒ String
Converts RDoc formatting (SimpleMarkup) to HTML
129 130 131 132 133 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 129 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”.
172 173 174 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 172 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
147 148 149 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 147 def html_markup_text(text) h(text).gsub(/\r?\n/, '<br/>') end |
#html_markup_textile(text) ⇒ String
Converts Textile to HTML
111 112 113 114 115 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 111 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)
121 122 123 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 121 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
.
192 193 194 195 196 197 198 199 200 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 192 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.
203 204 205 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 203 def html_syntax_highlight_plain(source) h(source) end |
#htmlify(text, markup = options.markup) ⇒ String
Turns text into HTML using markup
style formatting.
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 57 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).dup 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).
177 178 179 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 177 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
289 290 291 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 289 def insert_include(text, markup = .markup) htmlify(text, markup).gsub(%r{\A\s*<p>|</p>\s*\Z}, '') end |
#link_file(filename, title = nil, anchor = nil) ⇒ String
Links to an extra file
263 264 265 266 267 268 269 270 271 272 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 263 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
275 276 277 278 279 280 281 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 275 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.
284 285 286 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 284 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
294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 294 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
322 323 324 325 326 327 328 329 330 331 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 322 def link_url(url, title = nil, params = {}) title ||= url title = title.gsub(/[\r\n]/, ' ') params = SymbolHash.new(false).update( :href => url, :title => h(title) ).update(params) params[:target] ||= '_parent' if url =~ %r{^(\w+)://} "<a #{tag_attrs(params)}>#{title}</a>".gsub(/[\r\n]/, ' ') end |
#mtime(_file) ⇒ Object
390 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 390 def mtime(_file) nil 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}.
218 219 220 221 222 223 224 225 226 227 228 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 255 256 257 258 259 260 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 218 def resolve_links(text) = 0 text.gsub(%r{<(/)?(pre|code|tt)|(\\|!)?\{(?!\})(\S+?)(?:\s([^\}]*?\S))?\}(?=[\W<]|.+</|$)}m) do |str| closed = $1 tag = $2 escape = $3 name = $4 title = $5 match = $& 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 =~ %r{href=["'](.+?)["'].*>.*</a>\s*(.*)\Z} name = $1 title = $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 = (defined?(@file) && @file ? @file.filename : object.file) || '(unknown)' line = (defined?(@file) && @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 ? ":" : ".") + "\n\t" + (match[1] ? '...' : '') + match[2].delete("\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
.
519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 519 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 rw = meth.attr_info if rw 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.
482 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 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 482 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 Also known as: mtime_url
Returns the URL for an object.
358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 358 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
397 398 399 400 401 402 403 404 405 406 407 408 409 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 397 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) path = filename == .readme ? 'index.html' : serializer.serialized_path(filename) link = File.relative_path(from, path) link += (anchor ? '#' + urlencode(anchor) : '') link end |
#url_for_frameset ⇒ String
Returns the URL for the frameset page
424 425 426 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 424 def url_for_frameset url_for_file("frames.html") end |
#url_for_index ⇒ String
Returns the URL for the alphabetic index page
440 441 442 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 440 def url_for_index url_for_file("_index.html") end |
#url_for_list(type) ⇒ String
Returns the URL for a list type
416 417 418 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 416 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)
432 433 434 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 432 def url_for_main url_for_file("index.html") end |