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

- (Object) object

Returns the value of attribute object



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

def object
  @object
end

- (Object) serializer

Returns the value of attribute serializer



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

def serializer
  @serializer
end

Instance Method Details

- (String) format_object_title(object)

Returns the page title name for a given object

Examples:

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


187
188
189
190
191
192
193
194
# File 'lib/yard/templates/helpers/base_helper.rb', line 187

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

- (String) format_object_type(object)

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"


173
174
175
176
177
178
179
180
# File 'lib/yard/templates/helpers/base_helper.rb', line 173

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

- (String) format_source(value)

Indents and formats source code



200
201
202
203
204
# File 'lib/yard/templates/helpers/base_helper.rb', line 200

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

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

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"


159
160
161
# File 'lib/yard/templates/helpers/base_helper.rb', line 159

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

- (OpenStruct) globals

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

Since:

  • 0.6.0



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

def globals; options[:__globals] end

- (Object) 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.



31
32
33
# File 'lib/yard/templates/helpers/base_helper.rb', line 31

def h(text)
  text
end

Links to an extra file

Since:

  • 0.5.5



143
144
145
146
# File 'lib/yard/templates/helpers/base_helper.rb', line 143

def link_file(filename, title = nil, anchor = nil)
  return filename.filename if CodeObjects::ExtraFileObject === filename
  filename
end

Include a file as a docstring in output

Since:

  • 0.7.0



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

def link_include_file(file)
  File.read(file)
end

Includes an object's docstring into output.

Since:

  • 0.6.0



96
97
98
# File 'lib/yard/templates/helpers/base_helper.rb', line 96

def link_include_object(object)
  object.docstring
end

Links to an object with an optional title



113
114
115
116
117
118
119
120
121
122
123
124
# File 'lib/yard/templates/helpers/base_helper.rb', line 113

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

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

Links to a URL



132
133
134
# File 'lib/yard/templates/helpers/base_helper.rb', line 132

def link_url(url, title = nil, params = nil)
  url
end

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


48
49
50
51
52
53
54
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
# File 'lib/yard/templates/helpers/base_helper.rb', line 48

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
      if obj = YARD::Registry.resolve(object.namespace, path)
        link_include_object(obj)
      else
        log.warn "Cannot find object at `#{path}' for inclusion"
        ""
      end
    when /^render:(\S+)/
      path = $1
      if obj = YARD::Registry.resolve(object, path)
        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

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

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



23
24
25
# File 'lib/yard/templates/helpers/base_helper.rb', line 23

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