# Module: YARD::Templates::Helpers::BaseHelper

Included in:
  CLI::Stats, Server::Commands::ListCommand, Server::Commands::SearchCommand, Template

Defined in:
  lib/yard/templates/helpers/base_helper.rb

## Overview

The base helper module included in all templates.

## Instance Attribute Summary collapse

- #object ⇒ Object

  Returns the value of attribute object.

- #owner ⇒ CodeObjects::Base readonly

  The object representing the current generated page.

- #serializer ⇒ Object

  Returns the value of attribute serializer.

## Managing Global Template State collapse

- #globals ⇒ OpenStruct

  An object that keeps track of global state throughout the entire template rendering process (including any sub-templates).

## Running the Verifier collapse

- #run_verifier(list) ⇒ Array<CodeObjects::Base>

  Runs a list of objects against the Verifier object passed into the template and returns the subset of verified objects.

## Escaping Text collapse

- #h(text) ⇒ Object

  Escapes text.

## 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, title = nil) ⇒ String

  Links to an object with an optional title.

- #link_url(url, title = nil, params = nil) ⇒ String

  Links to a URL.

- #linkify(*args) ⇒ Object

  Links objects or URLs.

## Formatting Object Attributes collapse

- #format_object_title(object) ⇒ String

  The page title name for a given object.

- #format_object_type(object) ⇒ String

  The human-readable formatted #type for the object.

- #format_source(value) ⇒ String

  Indents and formats source code.

- #format_types(list, brackets = true) ⇒ String

  Formats a list of return types for output and links each type.

## Instance Attribute Details

### #object ⇒ `Object`

Returns the value of attribute object.

    5
    6
    7

    # File 'lib/yard/templates/helpers/base_helper.rb', line 5

    def object
      @object
    end

### #owner ⇒ `CodeObjects::Base` (readonly)

Returns the object representing the current generated page. Might not be the current #object when inside sub-templates.

Returns:

- (`CodeObjects::Base`) —

  the object representing the current generated page. Might not be the current #object when inside sub-templates.

    9
    10
    11

    # File 'lib/yard/templates/helpers/base_helper.rb', line 9

    def owner
      @owner
    end

### #serializer ⇒ `Object`

Returns the value of attribute serializer.

    5
    6
    7

    # File 'lib/yard/templates/helpers/base_helper.rb', line 5

    def serializer
      @serializer
    end

## Instance Method Details

### #format_object_title(object) ⇒ `String`

Returns the page title name for a given object.

#### Examples:

    s = format_object_title ModuleObject.new(:root, :MyModuleName)
    s # => "Module: MyModuleName"

Parameters:

- object (`CodeObjects::Base`) —

  the object to retrieve a title for

Returns:

- (`String`) —

  the page title name for a given object

    196
    197
    198
    199
    200
    201
    202
    203

    # File 'lib/yard/templates/helpers/base_helper.rb', line 196

    def format_object_title(object)
      case object
      when YARD::CodeObjects::RootObject
        "Top Level Namespace"
      else
        format_object_type(object) + ": " + object.title
      end
    end

### #format_object_type(object) ⇒ `String`

Returns the human-readable formatted #type for the object.

#### Examples:

#####

Formatted type of an exception class

    o = ClassObject.new(:root, :MyError)
    o.superclass = P('RuntimeError')
    format_object_type(o) # => "Exception"

#####

Formatted type of a method

    o = MethodObject.new(:root, :to_s)
    format_object_type(o) # => "Method"

Parameters:

- object (`CodeObjects::Base`) —

  the object to retrieve the type for

Returns:

- (`String`) —

  the human-readable formatted #type for the object

    182
    183
    184
    185
    186
    187
    188
    189

    # File 'lib/yard/templates/helpers/base_helper.rb', line 182

    def format_object_type(object)
      case object
      when YARD::CodeObjects::ClassObject
        object.is_exception? ? "Exception" : "Class"
      else
        object.type.to_s.capitalize
      end
    end

### #format_source(value) ⇒ `String`

Indents and formats source code

Parameters:

- value (`String`) —

  the input source code

Returns:

- (`String`) —

  formatted source code

    209
    210
    211
    212
    213

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

    def format_source(value)
      sp = value.split("\n").last[/^(\s+)/, 1]
      num = sp ? sp.size : 0
      value.gsub(/^\s{#{num}}/, '')
    end

### #format_types(list, brackets = true) ⇒ `String`

Formats a list of return types for output and links each type.

#### Examples:

#####

Formatting types

    format_types(['String', 'Array']) #=> "(String, Array)"

#####

Formatting types without surrounding brackets

    format_types(['String', 'Array'], false) #=> "String, Array"

Parameters:

- list (`Array<String>`) —

  a list of types

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

  whether to surround the types in brackets

Returns:

- (`String`) —

  the formatted list of Ruby types

    168
    169
    170

    # File 'lib/yard/templates/helpers/base_helper.rb', line 168

    def format_types(list, brackets = true)
      list.nil? || list.empty? ? "" : (brackets ? "(#{list.join(", ")})" : list.join(", "))
    end

### #globals ⇒ `OpenStruct`

An object that keeps track of global state throughout the entire template rendering process (including any sub-templates).

Returns:

- (`OpenStruct`) —

  a struct object that stores state

Since:

- 0.6.0

    20

    # File 'lib/yard/templates/helpers/base_helper.rb', line 20

    def globals; options.globals end

### #h(text) ⇒ `Object`

Escapes text. This is used a lot by the HtmlHelper and there should be some helper to “clean up” text for whatever, this is it.

    38
    39
    40

    # File 'lib/yard/templates/helpers/base_helper.rb', line 38

    def h(text)
      text
    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

    152
    153
    154
    155

    # File 'lib/yard/templates/helpers/base_helper.rb', line 152

    def link_file(filename, title = nil, anchor = nil) # rubocop:disable Lint/UnusedMethodArgument
      return filename.filename if CodeObjects::ExtraFileObject === filename
      filename
    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

    113
    114
    115

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

    def link_include_file(file)
      File.read(file)
    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

    105
    106
    107

    # File 'lib/yard/templates/helpers/base_helper.rb', line 105

    def link_include_object(obj)
      obj.docstring
    end

### #link_object(obj, title = nil) ⇒ `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

    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133

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

    def link_object(obj, title = nil)
      return title if title

      case obj
      when YARD::CodeObjects::Base, YARD::CodeObjects::Proxy
        obj.title
      when String, Symbol
        P(obj).title
      else
        obj
      end
    end

### #link_url(url, title = nil, params = nil) ⇒ `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: `nil`) —

  optional parameters for the link

Returns:

- (`String`) —

  the linked URL

    141
    142
    143

    # File 'lib/yard/templates/helpers/base_helper.rb', line 141

    def link_url(url, title = nil, params = nil) # rubocop:disable Lint/UnusedMethodArgument
      url
    end

### #linkify(*args) ⇒ `Object`

Links objects or URLs. This method will delegate to the correct `link_` method depending on the arguments passed in.

#### Examples:

#####

Linking a URL

    linkify('http://example.com')

#####

Including docstring contents of an object

    linkify('include:YARD::Docstring')

#####

Linking to an extra file

    linkify('file:README')

#####

Linking an object by path

    linkify('YARD::Docstring')

    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99

    # File 'lib/yard/templates/helpers/base_helper.rb', line 55

    def linkify(*args)
      if args.first.is_a?(String)
        case args.first
        when %r{://}, /^mailto:/
          link_url(args[0], args[1], {:target => '_parent'}.merge(args[2] || {}))
        when /^include:file:(\S+)/
          file = $1
          relpath = File.relative_path(Dir.pwd, File.expand_path(file))
          if relpath =~ /^\.\./
            log.warn "Cannot include file from path `#{file}'"
            ""
          elsif File.file?(file)
            link_include_file(file)
          else
            log.warn "Cannot find file at `#{file}' for inclusion"
            ""
          end
        when /^include:(\S+)/
          path = $1
          obj = YARD::Registry.resolve(object.namespace, path)
          if obj
            link_include_object(obj)
          else
            log.warn "Cannot find object at `#{path}' for inclusion"
            ""
          end
        when /^render:(\S+)/
          path = $1
          obj = YARD::Registry.resolve(object, path)
          if obj
            opts = options.dup
            opts.delete(:serializer)
            obj.format(opts)
          else
            ''
          end
        when /^file:(\S+?)(?:#(\S+))?$/
          link_file($1, args[1] ? args[1] : nil, $2)
        else
          link_object(*args)
        end
      else
        link_object(*args)
      end
    end

### #run_verifier(list) ⇒ `Array<CodeObjects::Base>`

Runs a list of objects against the Verifier object passed into the template and returns the subset of verified objects.

Parameters:

- list (`Array<CodeObjects::Base>`) —

  a list of code objects

Returns:

- (`Array<CodeObjects::Base>`) —

  a list of code objects that match the verifier. If no verifier is supplied, all objects are returned.

    30
    31
    32

    # File 'lib/yard/templates/helpers/base_helper.rb', line 30

    def run_verifier(list)
      options.verifier ? options.verifier.run(list) : list
    end