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

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Included In: `::YARD::CLI::Stats`, `::YARD::Server::Commands::ListCommand`, `::YARD::Server::Commands::SearchCommand`, `::YARD::Templates::Template`
Defined in:	lib/yard/templates/helpers/base_helper.rb

Overview

The base helper module included in all templates.

Managing Global Template State

#globals ⇒ OpenStruct

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

Running the Verifier

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

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

Escaping Text

#h(text)

Escapes text.

Linking Objects and URLs

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

Links objects or URLs.

Formatting Object Attributes

#format_object_title(object) ⇒ String
#format_object_type(object) ⇒ String
#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 (rw)

[ GitHub ]

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


attr_accessor :object, :serializer

#owner ⇒ CodeObjects::Base (readonly)

Returns:

(CodeObjects::Base) —
the object representing the current generated page. Might not be the current #object when inside sub-templates.

[ GitHub ]

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


attr_reader :owner

#serializer (rw)

[ GitHub ]

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


attr_accessor :object, :serializer

Instance Method Details

#format_object_title(object) ⇒ String

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

[ GitHub ]

# 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

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

[ GitHub ]

# 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

[ GitHub ]

# 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

[ GitHub ]

# 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

[ GitHub ]

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


def globals; options.globals end

#h(text)

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.

[ GitHub ]

# 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

[ GitHub ]

# 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

[ GitHub ]

# 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

[ GitHub ]

# 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

[ GitHub ]

# 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

[ GitHub ]

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

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')

[ GitHub ]

# 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 ::YARD::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.

[ GitHub ]

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


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