Module: YARD::Templates::Template

Relationships & Source Files
Namespace Children
Modules: `ClassMethods`
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `ClassMethods`
Instance Chain: self, `Helpers::MethodHelper`, `Helpers::BaseHelper`, `ErbCache`
Defined in:	lib/yard/templates/template.rb

Class Attribute Summary

.extra_includes ⇒ Array<Module, Proc> rw

Extra includes are mixins that are included after a template is created.

Class Method Summary

.include_extra(template, options) ⇒ void

Includes the .extra_includes modules into the template object.
.included(klass) Internal use only Internal use only

`ClassMethods` - Extended

find_file	Searches for a file identified by `basename` in the template's path as well as any mixed in template paths.
find_nth_file	Searches for the nth file (where n = `index`) identified by basename in the template's path and any mixed in template paths.
full_paths, initialize, is_a?,
new	Creates a new template object to be rendered with #run
reset_full_paths	Resets cache for `#full_paths`
run,
S	Alias for creating a `Section` with arguments.
T	Alias for creating Engine.template.
include_inherited, include_parent, load_setup_rb

`Helpers::BaseHelper` - Included

#object, #owner, #serializer

Instance Method Summary

#erb(section) { ... } ⇒ String
#file(basename, allow_inherited = false) ⇒ String

Returns the contents of a file.
#init

Initialization called on the template.
#initialize(opts = TemplateOptions.new)
#inspect
#run(opts = nil, sects = sections, start_at = 0, break_first = false) {|opts| ... } ⇒ String

Runs a template on sects using extra options.
#sections(*args)

Sets the sections (and subsections) to be rendered for the template.
#superb(sect = section, &block) ⇒ String

Calls the ERB file from the last inherited template with #section.erb.
T(*path) ⇒ Template

Loads a template specified by path.
#yieldall(opts = nil, &block)

Yields all subsections with any extra options.
#add_options(opts = nil) private
#cache(section) private
#cache_filename(section) private
#render_section(section, &block) private
#set_ivars private
#with_section private

`Helpers::MethodHelper` - Included

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

`Helpers::BaseHelper` - Included

#format_object_title, #format_object_type,
#format_source	Indents and formats source code.
#format_types	Formats a list of return types for output and links each type.
#globals	An object that keeps track of global state throughout the entire template rendering process (including any sub-templates).
#h	Escapes text.
#link_file	Links to an extra file.
#link_include_file	Include a file as a docstring in output.
#link_include_object	Includes an object's docstring into output.
#link_object	Links to an object with an optional title.
#link_url	Links to a URL.
#linkify	Links objects or URLs.
#run_verifier	Runs a list of objects against the `::YARD::Verifier` object passed into the template and returns the subset of verified objects.

Class Attribute Details

.extra_includes ⇒ Array<Module, `Proc`> (rw)

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

[ GitHub ]

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


attr_accessor :extra_includes

Class Method Details

.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

[ GitHub ]

# 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

.included(klass)

This method is for internal use only.

[ GitHub ]

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


def included(klass)
  klass.extend(ClassMethods)
end

Instance Attribute Details

#class (rw)

[ GitHub ]

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


attr_accessor :class, :section

#options (rw)

[ GitHub ]

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


attr_reader :options

#options=(value) (rw)

[ GitHub ]

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


def options=(value)
  @options = value
  set_ivars
end

#section (rw)

[ GitHub ]

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


attr_accessor :class, :section

Instance Method Details

#add_options(opts = nil) (private)

[ GitHub ]

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


def add_options(opts = nil)
  return(yield) if opts.nil? && block_given?
  cur_opts = options if block_given?

  self.options = options.merge(opts)

  if block_given?
    value = yield
    self.options = cur_opts
    value
  end
end

#cache(section) (private)

Raises:

(ArgumentError)

[ GitHub ]

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


def cache(section)
  content = @cache[section.to_sym]
  return content if content

  file = cache_filename(section)
  @cache_filename[section.to_sym] = file
  raise ArgumentError, "no template for section '#{section}' in #{self.class.path}" unless file
  @cache[section.to_sym] = IO.read(file)
end

#cache_filename(section) (private)

[ GitHub ]

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


def cache_filename(section)
  @cache_filename[section.to_sym] ||=
    self.class.find_file(erb_file_for(section))
end

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

Parameters:

section (String, Symbol) —
the section name

Yields:

calls subsections to be rendered

Returns:

(String) —
the contents of the ERB rendered section

[ GitHub ]

# 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

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

#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

#initialize(opts = TemplateOptions.new)

[ GitHub ]

# 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

[ GitHub ]

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


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

#render_section(section, &block) (private)

[ GitHub ]

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


def render_section(section, &block)
  section = section.name if section.is_a?(Section)
  case section
  when Section, String, Symbol
    if respond_to?(section)
      send(section, &block)
    else
      erb(section, &block)
    end
  when Module, Template
    section.run(options, &block) if section.is_a?(Template)
  end || ""
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 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

[ GitHub ]

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

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 ClassMethods#run called on them. Any subsections can be yielded to using yield or #yieldall

[ GitHub ]

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


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

#set_ivars (private)

[ GitHub ]

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


def set_ivars
  options.each do |k, v|
    instance_variable_set("@#{k}", v)
  end
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.

[ GitHub ]

# 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

[ GitHub ]

# 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

#with_section (private)

[ GitHub ]

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


def with_section
  sect = section
  value = yield
  self.section = sect
  value
end

#yieldall(opts = nil, &block)

Yields all subsections with any extra options

Parameters:

opts (Hash) (defaults to: nil) —
extra options to be applied to subsections

[ GitHub ]

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


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

Module: YARD::Templates::Template

Class Attribute Summary

ClassMethods - Extended

Class Method Summary

ClassMethods - Extended

Instance Attribute Summary

Helpers::BaseHelper - Included

Instance Method Summary

Helpers::MethodHelper - Included

Helpers::BaseHelper - Included

Class Attribute Details

.extra_includes ⇒ Array<Module, Proc> (rw)

Class Method Details

.include_extra(template, options) ⇒ void

.included(klass)

Instance Attribute Details

#class (rw)

#options (rw)

#options=(value) (rw)

#section (rw)

Instance Method Details

#add_options(opts = nil) (private)

#cache(section) (private)

#cache_filename(section) (private)

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

#file(basename, allow_inherited = false) ⇒ String

#init

#initialize(opts = TemplateOptions.new)

#inspect

#render_section(section, &block) (private)

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

#sections(*args)

#set_ivars (private)

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

T(*path) ⇒ Template

#with_section (private)

#yieldall(opts = nil, &block)

`ClassMethods` - Extended

`ClassMethods` - Extended

`Helpers::BaseHelper` - Included

`Helpers::MethodHelper` - Included

`Helpers::BaseHelper` - Included

.extra_includes ⇒ Array<Module, `Proc`> (rw)

.include_extra(template, options) ⇒ `void`

T(*path) ⇒ `Template`