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

.extra_includes ⇒ Array<Module, Proc>

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 }

Returns:

  • (Array<Module, Proc>) —

    a list of modules to be automatically included into any new template module



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

def extra_includes
  @extra_includes
end

Instance Attribute Details

#class ⇒ Object

Returns the value of attribute class.



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

def class
  @class
end

#full_path ⇒ Object Originally defined in module ClassMethods

Returns the value of attribute full_path.

#options ⇒ Object

Returns the value of attribute options.



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

def options
  @options
end

#path ⇒ Object Originally defined in module ClassMethods

Returns the value of attribute path.

#section ⇒ Object

Returns the value of attribute section.



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

def section
  @section
end

Class Method Details

.find_file(basename) ⇒ String 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.

Parameters:

  • basename (String) —

    the filename to search for

Returns:

  • (String) —

    the full path of a file on disk with filename basename in one of the template’s paths.

See Also:

.find_nth_file(basename, index = 1) ⇒ String 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.

Parameters:

  • basename (String) —

    the filename to search for

  • index (Fixnum) (defaults to: 1) —

    the nth existing file to return

Returns:

  • (String) —

    the full path of the nth file on disk with filename basename in one of the template paths

.full_paths ⇒ Array<String> 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.

Returns:

.include_extra(template, options) ⇒ void

This method returns an undefined value.

Includes the extra_includes modules into the template object.

Parameters:

  • template (Template) —

    the template object to mixin the extra includes.

  • options (SymbolHash) —

    the options hash containing all template information



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

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

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

.is_a?(klass) ⇒ Boolean Originally defined in module ClassMethods

Returns:

  • (Boolean)

.new(*args) ⇒ Object Originally defined in module ClassMethods

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

.reset_full_paths ⇒ Object Originally defined in module ClassMethods

Resets cache for #full_paths

.run(*args) ⇒ Object Originally defined in module ClassMethods

.S(*args) ⇒ Object Originally defined in module ClassMethods

Alias for creating a Section with arguments

See Also:

Since:

  • 0.6.0

.T(*path) ⇒ Object Originally defined in module ClassMethods

Alias for creating Engine.template.

Instance Method Details

#erb(section) { ... } ⇒ String

Returns the contents of the ERB rendered section.

Parameters:

  • section (String, Symbol) —

    the section name

Yields:

  • calls subsections to be rendered

Returns:

  • (String) —

    the contents of the ERB rendered section



285
286
287
288
289
290
 
# File 'lib/yard/templates/template.rb', line 285

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

#erb_file_for(section) ⇒ Object (protected) 



348
349
350
 
# File 'lib/yard/templates/template.rb', line 348

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

#erb_with(content, filename = nil) ⇒ Object (protected) 



352
353
354
355
356
357
358
359
360
 
# File 'lib/yard/templates/template.rb', line 352

def erb_with(content, filename = nil)
  erb = if ERB.instance_method(:initialize).parameters.assoc(:key) # Ruby 2.6+
          ERB.new(content, :trim_mode => options.format == :text ? '<>' : nil)
        else
          ERB.new(content, nil, options.format == :text ? '<>' : nil)
        end
  erb.filename = filename if filename
  erb
end

#file(basename, allow_inherited = false) ⇒ String

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 }

Parameters:

  • basename (String) —

    the name of the file

  • allow_inherited (Boolean) (defaults to: false) —

    whether inherited templates can be inserted with {{{__super__}}}

Returns:

  • (String) —

    the contents of a file identified by basename. All template paths (including any mixed in templates) are searched for the file

Raises:

  • (ArgumentError)

See Also:



312
313
314
315
316
317
318
319
320
321
322
323
 
# File 'lib/yard/templates/template.rb', line 312

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

#init ⇒ Object

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:



239
240
 
# File 'lib/yard/templates/template.rb', line 239

def init
end

#initialize(opts = TemplateOptions.new) ⇒ Object 



186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/yard/templates/template.rb', line 186

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

#inspect ⇒ Object 



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

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

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

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

Parameters:

  • opts (Hash, nil) (defaults to: nil) —

    any extra options to apply to sections

  • sects (Section, Array) (defaults to: sections) —

    a section list of sections to render

  • start_at (Fixnum) (defaults to: 0) —

    the index in the section list to start from

  • break_first (Boolean) (defaults to: false) —

    if true, renders only the first section

Yields:

  • (opts) —

    calls for the subsections to be rendered

Yield Parameters:

  • opts (Hash) —

    any extra options to yield

Returns:

  • (String) —

    the rendered sections joined together



252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/yard/templates/template.rb', line 252

def run(opts = nil, sects = sections, start_at = 0, break_first = false, &block)
  out = String.new("")
  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

#sections(*args) ⇒ Object

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)

Parameters:

  • args (Array<Symbol, String, Template, Array>) —

    the sections to use to render the template. For symbols and strings, the section will be executed as a method (if one exists), or rendered from the file “name.erb” where name is the section name. For templates, they will have YARD::Templates::Template::ClassMethods#run called on them. Any subsections can be yielded to using yield or #yieldall



226
227
228
229
 
# File 'lib/yard/templates/template.rb', line 226

def sections(*args)
  @sections = Section.new(nil, *args) unless args.empty?
  @sections
end

#superb(sect = section, &block) ⇒ String

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

Parameters:

  • sect (Symbol, String) (defaults to: section) —

    if provided, uses a specific section name

Returns:

  • (String) —

    the rendered ERB file in any of the inherited template paths.



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

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

#T(*path) ⇒ Template

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.

Parameters:

  • path (Array<String, Symbol>) —

    the path of the template

Returns:

  • (Template) —

    the loaded template module



204
205
206
207
208
 
# File 'lib/yard/templates/template.rb', line 204

def T(*path) # rubocop:disable Style/MethodName
  path.unshift(options.template) if options.template
  path.push(options.format) if options.format
  self.class.T(*path)
end

#yieldall(opts = nil, &block) ⇒ Object

Yields all subsections with any extra options

Parameters:

  • opts (Hash) (defaults to: nil) —

    extra options to be applied to subsections



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

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