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.
263 264 265 266 267 268 269 270 271 272 273 274 275 276 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 263 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
.
447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 447 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' else; lang end end |
#format_object_name_list(objects) ⇒ String
Formats a list of objects and links them
338 339 340 341 342 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 338 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.
356 357 358 359 360 361 362 363 364 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 356 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
201 202 203 204 205 206 207 208 209 210 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 201 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
213 214 215 216 217 218 219 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 213 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.
222 223 224 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 222 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
227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 227 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
248 249 250 251 252 253 254 255 256 257 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 248 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 |
# 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 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
.
406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 406 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 link_url(url_for(meth), 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.
372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 372 def signature_types(meth, link = true) meth = convert_method_to_overload(meth) 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.
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 309 310 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 284 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
317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 |
# File 'lib/yard/templates/helpers/html_helper.rb', line 317 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 |