# 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

- .extra_includes ⇒ Array<Module, Proc>

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

## Instance Attribute Summary collapse

- #class ⇒ Object

  Returns the value of attribute class.

- #full_path ⇒ Object included from ClassMethods

  Returns the value of attribute full_path.

- #options ⇒ Object

  Returns the value of attribute options.

- #path ⇒ Object included from ClassMethods

  Returns the value of attribute path.

- #section ⇒ Object

  Returns the value of attribute section.

### Attributes included from Helpers::BaseHelper

#object, #owner, #serializer

## Class Method Summary collapse

- .find_file(basename) ⇒ String extended from ClassMethods

  Searches for a file identified by `basename` in the template’s path as well as any mixed in template paths.

- .find_nth_file(basename, index = 1) ⇒ String extended from ClassMethods

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

- .full_paths ⇒ Array<String> extended from ClassMethods

  A list of full paths.

- .include_extra(template, options) ⇒ void

  Includes the Template.extra_includes modules into the template object.

- .initialize(path, full_paths) ⇒ Object extended from ClassMethods
- .is_a?(klass) ⇒ Boolean extended from ClassMethods
- .new(*args) ⇒ Object extended from ClassMethods

  Creates a new template object to be rendered with #run.

- .reset_full_paths ⇒ Object extended from ClassMethods

  Resets cache for ClassMethods#full_paths.

- .run(*args) ⇒ Object extended from ClassMethods
- .S(*args) ⇒ Object extended from ClassMethods

  Alias for creating a Section with arguments.

- .T(*path) ⇒ Object extended from ClassMethods

  Alias for creating Engine.template.

## Instance Method Summary collapse

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

  The contents of the ERB rendered section.

- #erb_file_for(section) ⇒ Object protected
- #erb_with(content, filename = nil) ⇒ Object protected
- #file(basename, allow_inherited = false) ⇒ String

  Returns the contents of a file.

- #init ⇒ Object

  Initialization called on the template.

- #initialize(opts = TemplateOptions.new) ⇒ Object
- #inspect ⇒ Object
- #run(opts = nil, sects = sections, start_at = 0, break_first = false) {|opts| ... } ⇒ String

  Runs a template on `sects` using extra options.

- #sections(*args) ⇒ Object

  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) ⇒ Object

  Yields all subsections with any extra options.

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

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

- (`Array<String>`) —

  a list of full paths

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

- Section#initialize

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:

- YARD::Templates::Template::ClassMethods#find_file
- YARD::Templates::Template::ClassMethods#find_nth_file

    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:

- #sections

    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