Module: YARD::Templates::Template

Extended by:
ClassMethods
Includes:
ErbCache, Helpers::BaseHelper, Helpers::MethodHelper
Defined in:
lib/yard/templates/template.rb

Defined Under Namespace

Modules: ClassMethods

Class Attribute Summary (collapse)

Instance Attribute Summary (collapse)

Attributes included from Helpers::BaseHelper

#object, #owner, #serializer

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods included from Helpers::MethodHelper

#format_args, #format_block, #format_code, #format_constant, #format_lines, #format_return_types

Methods included from Helpers::BaseHelper

#format_object_title, #format_object_type, #format_source, #format_types, #globals, #h, #link_file, #link_include_file, #link_include_object, #link_object, #link_url, #linkify, #run_verifier

Methods included from ErbCache

clear!, method_for

Class Attribute Details

+ (Array<Module, Proc>) extra_includes

Extra includes are mixins that are included after a template is created. These mixins can be registered by plugins to operate on templates and override behaviour.

Note that this array can be filled with modules or proc objects. If a proc object is given, the proc will be called with the #options hash containing relevant template information like the object, format, and more. The proc should return a module or nil if there is none.

Examples:

Adding in extra mixins to include on a template

Template.extra_includes << MyHelper

Conditionally including a mixin if the format is html

Template.extra_includes << proc {|opts| MyHelper if opts.format == :html }


24
25
26
# File 'lib/yard/templates/template.rb', line 24

def extra_includes
  @extra_includes
end

Instance Attribute Details

- (Object) class

Returns the value of attribute class



6
7
8
# File 'lib/yard/templates/template.rb', line 6

def class
  @class
end

- (Object) full_path Originally defined in module ClassMethods

Returns the value of attribute full_path

- (Object) options

Returns the value of attribute options



7
8
9
# File 'lib/yard/templates/template.rb', line 7

def options
  @options
end

- (Object) path Originally defined in module ClassMethods

Returns the value of attribute path

- (Object) section

Returns the value of attribute section



6
7
8
# File 'lib/yard/templates/template.rb', line 6

def section
  @section
end

Class Method Details

+ (String) find_file(basename) Originally defined in module ClassMethods

Searches for a file identified by basename in the template's path as well as any mixed in template paths. Equivalent to calling #find_nth_file with index of 1.

See Also:

  • find_nth_file

+ (String) find_nth_file(basename, index = 1) Originally defined in module ClassMethods

Searches for the nth file (where n = index) identified by basename in the template's path and any mixed in template paths.

+ (Array<String>) full_paths Originally defined in module ClassMethods

Note:

This method caches path results. Paths should not be modified after this method is called; call #reset_full_paths to reset cache.

Returns a list of full paths

+ (void) include_extra(template, options)

This method returns an undefined value.

Includes the extra_includes modules into the template object.



37
38
39
40
41
42
43
# File 'lib/yard/templates/template.rb', line 37

def include_extra(template, options)
  extra_includes.each do |mod|
    mod = mod.call(options) if mod.is_a?(Proc)
    next unless mod.is_a?(Module)
    template.extend(mod)
  end
end

+ (Object) initialize(path, full_paths) Originally defined in module ClassMethods

+ (Boolean) is_a?(klass) Originally defined in module ClassMethods

+ (Object) new(*args) Originally defined in module ClassMethods

Creates a new template object to be rendered with YARD::Templates::Template#run

+ (Object) reset_full_paths Originally defined in module ClassMethods

Resets cache for #full_paths

+ (Object) run(*args) Originally defined in module ClassMethods

+ (Object) S(*args) Originally defined in module ClassMethods

Alias for creating a Section with arguments

See Also:

Since:

  • 0.6.0

+ (Object) T(*path) Originally defined in module ClassMethods

Instance Method Details

- (String) erb(section) { ... }

Returns the contents of the ERB rendered section

Yields:

  • calls subsections to be rendered



275
276
277
278
279
280
# File 'lib/yard/templates/template.rb', line 275

def erb(section, &block)
  method_name = ErbCache.method_for(cache_filename(section)) do
    erb_with(cache(section), cache_filename(section))
  end
  send(method_name, &block)
end

- (Object) erb_file_for(section) (protected)



338
339
340
# File 'lib/yard/templates/template.rb', line 338

def erb_file_for(section)
  "#{section}.erb"
end

- (Object) erb_with(content, filename = nil) (protected)



342
343
344
345
346
# File 'lib/yard/templates/template.rb', line 342

def erb_with(content, filename = nil)
  erb = ERB.new(content, nil, options.format == :text ? '<>' : nil)
  erb.filename = filename if filename
  erb
end

- (String) file(basename, allow_inherited = false)

Returns the contents of a file. If allow_inherited is set to true, use {{{__super__}}} inside the file contents to insert the contents of the file from an inherited template. For instance, if templates/b inherits from templates/a and file “test.css” exists in both directories, both file contents can be retrieved by having templates/b/test.css look like:

{{{__super__}}}
...
body { css styles here }
p.class { other styles }


302
303
304
305
306
307
308
309
310
311
312
313
# File 'lib/yard/templates/template.rb', line 302

def file(basename, allow_inherited = false)
  file = self.class.find_file(basename)
  raise ArgumentError, "no file for '#{basename}' in #{self.class.path}" unless file

  data = IO.read(file)
  if allow_inherited
    superfile = self.class.find_nth_file(basename, 2)
    data.gsub!('{{{__super__}}}', superfile ? IO.read(superfile) : "")
  end

  data
end

- (Object) init

Initialization called on the template. Override this in a 'setup.rb' file in the template's path to implement a template

Examples:

A default set of sections

def init
  sections :section1, :section2, [:subsection1, :etc]
end

See Also:



229
230
# File 'lib/yard/templates/template.rb', line 229

def init
end

- (Object) initialize(opts = TemplateOptions.new)



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

def initialize(opts = TemplateOptions.new)
  opts_class = opts.class
  opts_class = TemplateOptions if opts_class == Hash
  @cache, @cache_filename = {}, {}
  @sections, @options = [], opts_class.new
  add_options(opts)
  Template.include_extra(self, options)
  init
end

- (Object) inspect



332
333
334
# File 'lib/yard/templates/template.rb', line 332

def inspect
  "Template(#{self.class.path}) [section=#{section.name}]"
end

- (String) run(opts = nil, sects = sections, start_at = 0, break_first = false) {|opts| ... }

Runs a template on sects using extra options. This method should not be called directly. Instead, call the class method YARD::Templates::Template::ClassMethods#run

Yields:

  • (opts)

    calls for the subsections to be rendered

Yield Parameters:

  • opts (Hash)

    any extra options to yield



242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
# File 'lib/yard/templates/template.rb', line 242

def run(opts = nil, sects = sections, start_at = 0, break_first = false, &block)
  out = ""
  return out if sects.nil?
  sects = sects[start_at..-1] if start_at > 0
  sects = Section.new(nil, sects) unless sects.is_a?(Section)
  add_options(opts) do
    sects.each do |s|
      self.section = s
      subsection_index = 0
      value = render_section(section) do |*args|
        value = with_section do
          run(args.first, section, subsection_index, true, &block)
        end
        subsection_index += 1
        value
      end
      out << (value || "")
      break if break_first
    end
  end
  out
end

- (Object) sections(*args)

Sets the sections (and subsections) to be rendered for the template

Examples:

Sets a set of erb sections

sections :a, :b, :c # searches for a.erb, b.erb, c.erb

Sets a set of method and erb sections

sections :a, :b, :c # a is a method, the rest are erb files

Sections with subsections

sections :header, [:name, :children]
# the above will call header.erb and only renders the subsections
# if they are yielded by the template (see #yieldall)


216
217
218
219
# File 'lib/yard/templates/template.rb', line 216

def sections(*args)
  @sections = Section.new(nil, *args) if args.size > 0
  @sections
end

- (String) superb(section = section, &block)

Calls the ERB file from the last inherited template with #section.erb



320
321
322
323
324
325
# File 'lib/yard/templates/template.rb', line 320

def superb(section = section, &block)
  filename = self.class.find_nth_file(erb_file_for(section), 2)
  return "" unless filename
  method_name = ErbCache.method_for(filename) { erb_with(IO.read(filename), filename) }
  send(method_name, &block)
end

- (Template) T(*path)

Loads a template specified by path. If :template or :format is specified in the #options hash, they are prepended and appended to the path respectively.



194
195
196
197
198
# File 'lib/yard/templates/template.rb', line 194

def T(*path)
  path.unshift(options.template) if options.template
  path.push(options.format) if options.format
  self.class.T(*path)
end

- (Object) yieldall(opts = nil, &block)

Yields all subsections with any extra options



268
269
270
# File 'lib/yard/templates/template.rb', line 268

def yieldall(opts = nil, &block)
  with_section { run(opts, section, &block) }
end