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

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



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

def owner
  @owner
end

#serializer ⇒ Object

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

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

Returns:

  • (String) —

    the page title name for a given object



193
194
195
196
197
198
199
200
 
# File 'lib/yard/templates/helpers/base_helper.rb', line 193

def format_object_title(object)
  case object
  when YARD::CodeObjects::RootObject
    "Top Level Namespace"
  else
    format_object_type(object) + ": " + object.path
  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:

Returns:

  • (String) —

    the human-readable formatted #type for the object



179
180
181
182
183
184
185
186
 
# File 'lib/yard/templates/helpers/base_helper.rb', line 179

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



206
207
208
209
210
 
# File 'lib/yard/templates/helpers/base_helper.rb', line 206

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



165
166
167
 
# File 'lib/yard/templates/helpers/base_helper.rb', line 165

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



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

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.



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

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



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

def link_file(filename, title = nil, anchor = nil)
  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



110
111
112
 
# File 'lib/yard/templates/helpers/base_helper.rb', line 110

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

#link_include_object(object) ⇒ String

Includes an object’s docstring into output.

Parameters:

Returns:

  • (String) —

    the object’s docstring (no tags)

Since:

  • 0.6.0



102
103
104
 
# File 'lib/yard/templates/helpers/base_helper.rb', line 102

def link_include_object(object)
  object.docstring
end

#link_object(object, title = nil) ⇒ String

Links to an object with an optional title

Parameters:

  • object (CodeObjects::Base) —

    the object to link to

  • title (String) (defaults to: nil) —

    the title to use for the link

Returns:

  • (String) —

    the linked object



119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/yard/templates/helpers/base_helper.rb', line 119

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

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



138
139
140
 
# File 'lib/yard/templates/helpers/base_helper.rb', line 138

def link_url(url, title = nil, params = nil)
  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')


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
91
92
93
94
95
96
 
# File 'lib/yard/templates/helpers/base_helper.rb', line 54

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

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

Returns:

  • (Array<CodeObjects::Base>) —

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



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

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