# 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 HtmlSyntaxHighlightHelper

YARD::Templates::Helpers::HtmlSyntaxHighlightHelper::ALREADY_HIGHLIGHTED_RE

### 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 language `type`.

- #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

#html_syntax_highlight_ruby

### Methods included from ModuleHelper

#prune_method_listing

### 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

Parameters:

- text (`String`) —

  the URL

Returns:

- (`String`) —

  the escaped URL

    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49

    # File 'lib/yard/templates/helpers/html_helper.rb', line 35

    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.

Parameters:

- object (`CodeObjects::Base`) —

  the object to get an anchor for

Returns:

- (`String`) —

  the anchor for a specific object

    357
    358
    359
    360
    361
    362
    363
    364
    365
    366
    367
    368
    369
    370

    # File 'lib/yard/templates/helpers/html_helper.rb', line 357

    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`.

Returns:

- (`String`) —

  the current character set

Since:

- 0.5.4

    584
    585
    586
    587
    588
    589
    590
    591
    592
    593
    594
    595
    596
    597
    598
    599
    600
    601
    602
    603

    # File 'lib/yard/templates/helpers/html_helper.rb', line 584

    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

Returns:

- (`String`) —

  a formatted list of objects

    468
    469
    470
    471
    472

    # File 'lib/yard/templates/helpers/html_helper.rb', line 468

    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.

Parameters:

- typelist (`Array<String>`, `FalseClass`) —

  the list of types to be formatted.

- brackets (`Boolean`) (defaults to: `true`) —

  omits the surrounding brackets if `brackets` is set to `false`.

Returns:

- (`String`) —

  the list of types formatted as [Type1, Type2, …] with the types linked to their respective descriptions.

    486
    487
    488
    489
    490
    491
    492
    493
    494

    # File 'lib/yard/templates/helpers/html_helper.rb', line 486

    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

Parameters:

- text (`String`) —

  the text to escape

Returns:

- (`String`) —

  the HTML with escaped entities

    27
    28
    29

    # File 'lib/yard/templates/helpers/html_helper.rb', line 27

    def h(text)
      CGI.escapeHTML(text.to_s)
    end

### #html_markup_asciidoc(text) ⇒ `String`

Converts Asciidoc to HTML

Parameters:

- text (`String`) —

  input Asciidoc text

Returns:

- (`String`) —

  output HTML

    119
    120
    121
    122

    # File 'lib/yard/templates/helpers/html_helper.rb', line 119

    def html_markup_asciidoc(text)
      options = {:attributes => ASCIIDOC_ATTRIBUTES}
      markup_class(:asciidoc).convert(text, options)
    end

### #html_markup_html(text) ⇒ `String`

Converts HTML to HTML

Parameters:

- text (`String`) —

  input html

Returns:

- (`String`) —

  output HTML

Since:

- 0.6.0

    178
    179
    180

    # File 'lib/yard/templates/helpers/html_helper.rb', line 178

    def html_markup_html(text)
      text
    end

### #html_markup_markdown(text) ⇒ `String`

Converts Markdown to HTML

Parameters:

- text (`String`) —

  input Markdown text

Returns:

- (`String`) —

  output HTML

Since:

- 0.6.0

    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107

    # File 'lib/yard/templates/helpers/html_helper.rb', line 82

    def html_markup_markdown(text)
      # TODO: other libraries might be more complex
      provider = markup_class(:markdown)
      case provider.to_s
      when  'RDiscount'
        provider.new(text, :autolink).to_html
      when 'RedcarpetCompat'
        provider.new(text, :autolink,
                           :fenced_code,
                           :gh_blockcode,
                           :lax_spacing,
                           :tables,
                           :with_toc_data,
                           :no_intraemphasis).to_html
      when 'Commonmarker'
        provider.to_html(text, :options => { }, :plugins => { :syntax_highlighter => nil })
      when 'CommonMarker'
        provider.render_html(text, %i[DEFAULT GITHUB_PRE_LANG], %i[autolink table])
      else
        if provider.respond_to?(:to_html)
          provider.to_html(text)
        else
          provider.new(text).to_html
        end
      end
    end

### #html_markup_none(text) ⇒ `String`

Returns the same text with no markup.

Returns:

- (`String`) —

  the same text with no markup

Since:

- 0.6.6

    170
    171
    172

    # File 'lib/yard/templates/helpers/html_helper.rb', line 170

    def html_markup_none(text)
      h(text)
    end

### #html_markup_org(text) ⇒ `String`

Converts org-mode to HTML

Parameters:

- text (`String`) —

  input org-mode text

Returns:

- (`String`) —

  output HTML

    112
    113
    114

    # File 'lib/yard/templates/helpers/html_helper.rb', line 112

    def html_markup_org(text)
      markup_class(:org).new(text).to_html
    end

### #html_markup_pre(text) ⇒ `String`

Converts plaintext to pre-formatted HTML

Parameters:

- text (`String`) —

  the input text

Returns:

- (`String`) —

  the output HTML

Since:

- 0.6.0

    156
    157
    158

    # File 'lib/yard/templates/helpers/html_helper.rb', line 156

    def html_markup_pre(text)
      "<pre>" + h(text) + "</pre>"
    end

### #html_markup_rdoc(text) ⇒ `String`

Converts RDoc formatting (SimpleMarkup) to HTML

Parameters:

- text (`String`) —

  the input RDoc formatted text

Returns:

- (`String`) —

  output HTML

Since:

- 0.6.0

    146
    147
    148
    149
    150

    # File 'lib/yard/templates/helpers/html_helper.rb', line 146

    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”.

Parameters:

- source (`String`) —

  the Ruby source

Returns:

- (`String`) —

  the highlighted HTML

Since:

- 0.7.0

    189
    190
    191

    # File 'lib/yard/templates/helpers/html_helper.rb', line 189

    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

Parameters:

- text (`String`) —

  the input text

Returns:

- (`String`) —

  the output HTML

Since:

- 0.6.0

    164
    165
    166

    # File 'lib/yard/templates/helpers/html_helper.rb', line 164

    def html_markup_text(text)
      h(text).gsub(/\r?\n/, '<br>')
    end

### #html_markup_textile(text) ⇒ `String`

Converts Textile to HTML

Parameters:

- text (`String`) —

  the input Textile text

Returns:

- (`String`) —

  output HTML

Since:

- 0.6.0

    128
    129
    130
    131
    132

    # File 'lib/yard/templates/helpers/html_helper.rb', line 128

    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)

Parameters:

- text (`String`) —

  the input textile data

Returns:

- (`String`) —

  the output HTML

Since:

- 0.6.0

    138
    139
    140

    # File 'lib/yard/templates/helpers/html_helper.rb', line 138

    def html_markup_textile_strict(text)
      markup_class(:textile).new(text).to_html
    end

### #html_syntax_highlight(source, type = nil) ⇒ `String`

Note:

To support a specific language `type`, implement the method `html_syntax_highlight_TYPE` in this class.

Syntax highlights `source` in language `type`.

Parameters:

- source (`String`) —

  the source code to highlight

- type (`Symbol`, `String`) (defaults to: `nil`) —

  the language type (:ruby, :plain, etc). Use :plain for no syntax highlighting.

Returns:

- (`String`) —

  the highlighted source

    209
    210
    211
    212
    213
    214
    215
    216
    217

    # File 'lib/yard/templates/helpers/html_helper.rb', line 209

    def html_syntax_highlight(source, type = nil)
      return "" unless source
      return h(source) unless options.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.

Returns:

- (`String`) —

  unhighlighted source

    220
    221
    222

    # File 'lib/yard/templates/helpers/html_helper.rb', line 220

    def html_syntax_highlight_plain(source)
      h(source)
    end

### #htmlify(text, markup = options.markup) ⇒ `String`

Turns text into HTML using `markup` style formatting.

Parameters:

- text (`String`) —

  the text to format

- markup (`Symbol`) (defaults to: `options.markup`) —

  examples are `:markdown`, `:textile`, `:rdoc`. To add a custom markup type, see MarkupHelper

Returns:

- (`String`) —

  the HTML

    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76

    # File 'lib/yard/templates/helpers/html_helper.rb', line 61

    def htmlify(text, markup = options.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, :ruby].include?(markup)
        html = parse_codeblocks(html)
      end
      html
    end

### #htmlify_line(*args) ⇒ `String`

Returns HTMLified text as a single line (paragraphs removed).

Returns:

- (`String`) —

  HTMLified text as a single line (paragraphs removed)

    194
    195
    196

    # File 'lib/yard/templates/helpers/html_helper.rb', line 194

    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

    306
    307
    308

    # File 'lib/yard/templates/helpers/html_helper.rb', line 306

    def insert_include(text, markup = options.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

Parameters:

- filename (`String`) —

  the filename to link to

- title (`String`) (defaults to: `nil`) —

  the title of the link

- anchor (`String`) (defaults to: `nil`) —

  optional anchor

Returns:

- (`String`) —

  the link to the file

Since:

- 0.5.5

    280
    281
    282
    283
    284
    285
    286
    287
    288
    289

    # File 'lib/yard/templates/helpers/html_helper.rb', line 280

    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

Parameters:

- file (`String`) —

  the filename to include

Returns:

- (`String`) —

  the file’s contents

Since:

- 0.7.0

    292
    293
    294
    295
    296
    297
    298

    # File 'lib/yard/templates/helpers/html_helper.rb', line 292

    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] || options.markup)
    end

### #link_include_object(obj) ⇒ `String`

Includes an object’s docstring into output.

Parameters:

- obj (`CodeObjects::Base`) —

  the object to include

Returns:

- (`String`) —

  the object’s docstring (no tags)

Since:

- 0.6.0

    301
    302
    303

    # File 'lib/yard/templates/helpers/html_helper.rb', line 301

    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

Parameters:

- obj (`CodeObjects::Base`) —

  the object to link to

- title (`String`) (defaults to: `nil`) —

  the title to use for the link

Returns:

- (`String`) —

  the linked object

    311
    312
    313
    314
    315
    316
    317
    318
    319
    320
    321
    322
    323
    324
    325
    326
    327
    328
    329
    330
    331
    332
    333
    334
    335
    336
    337
    338
    339

    # File 'lib/yard/templates/helpers/html_helper.rb', line 311

    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>"
    rescue Parser::UndocumentableError
      log.warn "The namespace of link #{obj.inspect} is a constant or invalid."
      title || obj.to_s
    end

### #link_url(url, title = nil, params = {}) ⇒ `String`

Links to a URL

Parameters:

- url (`String`) —

  the URL to link to

- title (`String`) (defaults to: `nil`) —

  the optional title to display the link as

- params (`Hash`) (defaults to: `{}`) —

  optional parameters for the link

Returns:

- (`String`) —

  the linked URL

    342
    343
    344
    345
    346
    347
    348
    349
    350
    351

    # File 'lib/yard/templates/helpers/html_helper.rb', line 342

    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`

    410

    # File 'lib/yard/templates/helpers/html_helper.rb', line 410

    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}`.

#### Examples:

#####

Linking to an instance method

    resolve_links("{MyClass#method}") # => "<a href='...'>MyClass#method</a>"

#####

Linking to a class with a title

    resolve_links("{A::B::C the C class}") # => "<a href='...'>the c class</a>"

Parameters:

- text (`String`) —

  the text to resolve links in

Returns:

- (`String`) —

  HTML with linkified references

    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
    261
    262
    263
    264
    265
    266
    267
    268
    269
    270
    271
    272
    273
    274
    275
    276
    277

    # File 'lib/yard/templates/helpers/html_helper.rb', line 235

    def resolve_links(text)
      code_tags = 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
          code_tags += (closed ? -1 : 1)
          next str
        end
        next str unless code_tags == 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`.

Parameters:

- meth (`CodeObjects::MethodObject`) —

  the method object to list the signature of

- link (`Boolean`) (defaults to: `true`) —

  whether to link the method signature to the details view

- show_extras (`Boolean`) (defaults to: `true`) —

  whether to show extra meta-data (visibility, attribute info)

- full_attr_name (`Boolean`) (defaults to: `true`) —

  whether to show the full attribute name (“name=” instead of “name”)

Returns:

- (`String`) —

  the formatted method signature

    539
    540
    541
    542
    543
    544
    545
    546
    547
    548
    549
    550
    551
    552
    553
    554
    555
    556
    557
    558
    559
    560
    561
    562
    563
    564
    565
    566
    567
    568
    569
    570
    571
    572
    573

    # File 'lib/yard/templates/helpers/html_helper.rb', line 539

    def signature(meth, link = true, show_extras = true, full_attr_name = true)
      meth = convert_method_to_overload(meth)

      type = signature_types(meth, link)
      type = "&#x21d2; #{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.

Parameters:

- meth (`CodeObjects::MethodObject`) —

  the method object

- link (`Boolean`) (defaults to: `true`) —

  whether to link the types

Returns:

- (`String`) —

  the signature types

Since:

- 0.5.3

    502
    503
    504
    505
    506
    507
    508
    509
    510
    511
    512
    513
    514
    515
    516
    517
    518
    519
    520
    521
    522
    523
    524
    525
    526
    527
    528

    # File 'lib/yard/templates/helpers/html_helper.rb', line 502

    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 = options.default_return || ""
      if meth.tag(:return) && meth.tag(:return).types
        types = meth.tags(: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'] && options.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.

Parameters:

- obj (`String`, `CodeObjects::Base`) —

  the object (or object path) to link to

- anchor (`String`) (defaults to: `nil`) —

  the anchor to link to

- relative (`Boolean`) (defaults to: `true`) —

  use a relative or absolute link

Returns:

- (`String`) —

  the URL location of the object

    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
    405
    406
    407

    # File 'lib/yard/templates/helpers/html_helper.rb', line 378

    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

Parameters:

- filename (`String`, `CodeObjects::ExtraFileObject`) —

  the filename to link to

- anchor (`String`) (defaults to: `nil`) —

  optional anchor

Returns:

- (`String`) —

  the URL pointing to the file

    417
    418
    419
    420
    421
    422
    423
    424
    425
    426
    427
    428
    429

    # File 'lib/yard/templates/helpers/html_helper.rb', line 417

    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 == options.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

Returns:

- (`String`) —

  the URL pointing to the frames page

Since:

- 0.8.0

    444
    445
    446

    # File 'lib/yard/templates/helpers/html_helper.rb', line 444

    def url_for_frameset
      url_for_file("frames.html")
    end

### #url_for_index ⇒ `String`

Returns the URL for the alphabetic index page

Returns:

- (`String`) —

  the URL pointing to the first main page the user should see.

    460
    461
    462

    # File 'lib/yard/templates/helpers/html_helper.rb', line 460

    def url_for_index
      url_for_file("_index.html")
    end

### #url_for_list(type) ⇒ `String`

Returns the URL for a list type

Parameters:

- type (`String`, `Symbol`) —

  the list type to generate a URL for

Returns:

- (`String`) —

  the URL pointing to the list

Since:

- 0.8.0

    436
    437
    438

    # File 'lib/yard/templates/helpers/html_helper.rb', line 436

    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)

Returns:

- (`String`) —

  the URL pointing to the first main page the user should see.

    452
    453
    454

    # File 'lib/yard/templates/helpers/html_helper.rb', line 452

    def url_for_main
      url_for_file("index.html")
    end