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

    351
    352
    353
    354
    355
    356
    357
    358
    359
    360
    361
    362
    363
    364

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

    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

    578
    579
    580
    581
    582
    583
    584
    585
    586
    587
    588
    589
    590
    591
    592
    593
    594
    595
    596
    597

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

    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

    462
    463
    464
    465
    466

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

    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.

    480
    481
    482
    483
    484
    485
    486
    487
    488

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

    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

    113
    114
    115
    116

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

    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

    172
    173
    174

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

    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

    # 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'
        CommonMarker.render_html(text, %i[DEFAULT GITHUB_PRE_LANG], %i[autolink table])
      else
        provider.new(text).to_html
      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

    164
    165
    166

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

    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

    106
    107
    108

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

    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

    150
    151
    152

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

    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

    140
    141
    142
    143
    144

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

    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

    183
    184
    185

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

    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

    158
    159
    160

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

    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

    122
    123
    124
    125
    126

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

    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

    132
    133
    134

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

    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

    203
    204
    205
    206
    207
    208
    209
    210
    211

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

    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

    214
    215
    216

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

    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)

    188
    189
    190

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

    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

    300
    301
    302

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

    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

    274
    275
    276
    277
    278
    279
    280
    281
    282
    283

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

    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

    286
    287
    288
    289
    290
    291
    292

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

    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

    295
    296
    297

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

    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

    305
    306
    307
    308
    309
    310
    311
    312
    313
    314
    315
    316
    317
    318
    319
    320
    321
    322
    323
    324
    325
    326
    327
    328
    329
    330
    331
    332
    333

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

    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

    336
    337
    338
    339
    340
    341
    342
    343
    344
    345

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

    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`

    404

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

    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

    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
    261
    262
    263
    264
    265
    266
    267
    268
    269
    270
    271

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

    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

    533
    534
    535
    536
    537
    538
    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

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

    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

    496
    497
    498
    499
    500
    501
    502
    503
    504
    505
    506
    507
    508
    509
    510
    511
    512
    513
    514
    515
    516
    517
    518
    519
    520
    521
    522

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

    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

    372
    373
    374
    375
    376
    377
    378
    379
    380
    381
    382
    383
    384
    385
    386
    387
    388
    389
    390
    391
    392
    393
    394
    395
    396
    397
    398
    399
    400
    401

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

    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

    411
    412
    413
    414
    415
    416
    417
    418
    419
    420
    421
    422
    423

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

    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

    438
    439
    440

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

    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.

    454
    455
    456

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

    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

    430
    431
    432

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

    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.

    446
    447
    448

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

    def url_for_main
      url_for_file("index.html")
    end