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

Managing Global Template State collapse

Running the Verifier collapse

Escaping Text collapse

Linking Objects and URLs collapse

Formatting Object Attributes collapse

Instance Attribute Details

#objectObject

Returns the value of attribute object


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

def object
  @object
end

#ownerCodeObjects::Base (readonly)


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

def owner
  @owner
end

#serializerObject

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"

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"

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


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"

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

#globalsOpenStruct

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

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

Links to an extra 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

Include a file as a docstring in output

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

Includes an object's docstring into output.

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

Links to an object with an optional title


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

Links to a 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.


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