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_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
28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 28 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.
326 327 328 329 330 331 332 333 334 335 336 337 338 339 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 326 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
.
553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 553 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
437 438 439 440 441 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 437 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.
455 456 457 458 459 460 461 462 463 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 455 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
20 21 22 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 20 def h(text) CGI.escapeHTML(text.to_s) end |
#html_markup_asciidoc(text) ⇒ String
Converts Asciidoc to HTML
92 93 94 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 92 def html_markup_asciidoc(text) markup_class(:asciidoc).render(text) end |
#html_markup_html(text) ⇒ String
Converts HTML to HTML
150 151 152 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 150 def html_markup_html(text) text end |
#html_markup_markdown(text) ⇒ String
Converts Markdown to HTML
75 76 77 78 79 80 81 82 83 84 85 86 87 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 75 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.
142 143 144 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 142 def html_markup_none(text) h(text) end |
#html_markup_pre(text) ⇒ String
Converts plaintext to pre-formatted HTML
128 129 130 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 128 def html_markup_pre(text) "<pre>" + h(text) + "</pre>" end |
#html_markup_rdoc(text) ⇒ String
Converts RDoc formatting (SimpleMarkup) to HTML
118 119 120 121 122 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 118 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”.
161 162 163 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 161 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
136 137 138 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 136 def html_markup_text(text) h(text).gsub(/\r?\n/, '<br/>') end |
#html_markup_textile(text) ⇒ String
Converts Textile to HTML
100 101 102 103 104 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 100 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)
110 111 112 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 110 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
.
181 182 183 184 185 186 187 188 189 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 181 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.
192 193 194 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 192 def html_syntax_highlight_plain(source) h(source) end |
#htmlify(text, markup = options.markup) ⇒ String
Turns text into HTML using markup
style formatting.
54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 54 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).
166 167 168 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 166 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
278 279 280 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 278 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
252 253 254 255 256 257 258 259 260 261 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 252 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
264 265 266 267 268 269 270 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 264 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.
273 274 275 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 273 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
283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 283 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
311 312 313 314 315 316 317 318 319 320 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 311 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
379 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 379 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}.
207 208 209 210 211 212 213 214 215 216 217 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 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 207 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
.
508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 508 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.
471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 471 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.
347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 347 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
386 387 388 389 390 391 392 393 394 395 396 397 398 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 386 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
413 414 415 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 413 def url_for_frameset url_for_file("frames.html") end |
#url_for_index ⇒ String
Returns the URL for the alphabetic index page
429 430 431 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 429 def url_for_index url_for_file("_index.html") end |
#url_for_list(type) ⇒ String
Returns the URL for a list type
405 406 407 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 405 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)
421 422 423 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 421 def url_for_main url_for_file("index.html") end |