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_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_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 HTML.
-
#html_markup_textile(text) ⇒ String
Converts Textile to HTML.
-
#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
-
#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, otitle = 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.
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.
269 270 271 272 273 274 275 276 277 278 279 280 281 282 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 269 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
.
457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 457 def charset if @file && RUBY19 lang = @file.contents.encoding.to_s else return 'utf-8' unless RUBY19 || lang = ENV['LANG'] if RUBY19 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
344 345 346 347 348 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 344 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.
362 363 364 365 366 367 368 369 370 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 362 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_html(text) ⇒ String
Converts HTML to HTML
107 108 109 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 107 def html_markup_html(text) text end |
#html_markup_markdown(text) ⇒ String
Converts Markdown to HTML
59 60 61 62 63 64 65 66 67 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 59 def html_markup_markdown(text) # TODO: other libraries might be more complex provider = markup_class(:markdown) if provider.to_s == 'RDiscount' markup_class(:markdown).new(text, :autolink).to_html else markup_class(:markdown).new(text).to_html end end |
#html_markup_none(text) ⇒ String
Returns the same text with no markup.
99 100 101 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 99 def html_markup_none(text) h(text).gsub(/(?:\r?\n){2}/, '<br/>') end |
#html_markup_rdoc(text) ⇒ String
Converts RDoc formatting (SimpleMarkup) to HTML
83 84 85 86 87 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 83 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”.
118 119 120 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 118 def html_markup_ruby(source) '<pre class="code">' + html_syntax_highlight(source, :ruby) + '</pre>' end |
#html_markup_text(text) ⇒ String
Converts plaintext to HTML
93 94 95 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 93 def html_markup_text(text) "<pre>" + text + "</pre>" end |
#html_markup_textile(text) ⇒ String
Converts Textile to HTML
73 74 75 76 77 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 73 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_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
.
138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 138 def html_syntax_highlight(source, type = nil) return "" unless source return h(source) if [:no_highlight] type ||= object.source_type || :ruby # handle !!!LANG prefix to send to html_syntax_highlight_LANG if source =~ /\A(?:[ \t]*\r?\n)?[ \t]*!!!([\w.+-]+)[ \t]*\r?\n/ type, source = $1, $' source = $' end meth = "html_syntax_highlight_#{type}" respond_to?(meth) ? send(meth, source) : h(source) end |
#html_syntax_highlight_plain(source) ⇒ String
Returns unhighlighted source.
155 156 157 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 155 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 52 53 |
# 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) html = html.gsub(/<pre>(?:\s*<code>)?(.+?)(?:<\/code>\s*)?<\/pre>/m) do str = $1 str = html_syntax_highlight(CGI.unescapeHTML(str)) unless [:no_highlight] %Q{<pre class="code">#{str}</pre>} end unless markup == :text html end |
#htmlify_line(*args) ⇒ String
Returns HTMLified text as a single line (paragraphs removed).
123 124 125 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 123 def htmlify_line(*args) "<div class='inline'>" + htmlify(*args) + "</div>" end |
#link_file(filename, title = nil, anchor = nil) ⇒ String
Links to an extra file
207 208 209 210 211 212 213 214 215 216 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 207 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
219 220 221 222 223 224 225 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 219 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) htmlify(file.contents, file.attributes[:markup] || [:markup]) end |
#link_include_object(obj) ⇒ String
Includes an object’s docstring into output.
228 229 230 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 228 def link_include_object(obj) htmlify(obj.docstring) end |
#link_object(obj, otitle = nil, anchor = nil, relative = true) ⇒ String
Links to an object with an optional title
233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 233 def link_object(obj, otitle = nil, anchor = nil, relative = true) return otitle if obj.nil? obj = Registry.resolve(object, obj, true, true) if obj.is_a?(String) if !otitle && obj.root? title = "Top Level Namespace" elsif otitle title = otitle.to_s elsif object.is_a?(CodeObjects::Base) title = h(object.relative_path(obj)) else title = h(obj.to_s) 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 => "#{obj.path} (#{obj.type})") : title "<span class='object_link'>" + link + "</span>" end |
#link_url(url, title = nil, params = {}) ⇒ String
Links to a URL
254 255 256 257 258 259 260 261 262 263 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 254 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}.
170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 170 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 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
.
415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 415 def signature(meth, link = true, show_extras = true, full_attr_name = true) meth = convert_method_to_overload(meth) type = signature_types(meth, link) 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 %s<strong>%s</strong>%s %s" % [scope, type, h(name), args, blk] 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 link_url(url_for(obj), 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.
378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 378 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.
290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 290 def url_for(obj, anchor = nil, relative = true) link = nil return link unless serializer 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 if relative fromobj = object if object.is_a?(CodeObjects::Base) && !object.is_a?(CodeObjects::NamespaceObject) fromobj = fromobj.namespace 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
323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 323 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 |
#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 |