# Module: YARD::Templates::Engine

Defined in:
  lib/yard/templates/engine.rb

## Overview

This module manages all creation, handling and rendering of Template objects.

- To create a template object at a path, use Engine.template.

- To render a template, call Engine.render.

- To register a template path in the lookup paths, call Engine.register_template_path.

## Class Attribute Summary collapse

- .template_paths ⇒ Array<String>

  The list of registered template paths.

## Class Method Summary collapse

- .generate(objects, options = {}) ⇒ void

  Passes a set of objects to the `:fulldoc` template for full documentation generation.

- .register_template_path(path) ⇒ void

  Registers a new template path in Engine.template_paths.

- .render(options = {}) ⇒ String

  Renders a template on a code object using a set of default (overridable) options.

- .template(*path) ⇒ Template

  Creates a template module representing the path.

- .template!(path, full_paths = nil) ⇒ Template

  Forces creation of a template at `path` within a `full_path`.

- .with_serializer(object, serializer) { ... } ⇒ Object

  Serializes the results of a block with a `serializer` object.

## Class Attribute Details

### .template_paths ⇒ `Array<String>`

Returns the list of registered template paths.

Returns:

- (`Array<String>`) —

  the list of registered template paths

    14
    15
    16

    # File 'lib/yard/templates/engine.rb', line 14

    def template_paths
      @template_paths
    end

## Class Method Details

### .generate(objects, options = {}) ⇒ `void`

This method returns an undefined value.

Passes a set of objects to the `:fulldoc` template for full documentation generation. This is called by CLI::Yardoc to most commonly perform HTML documentation generation.

Parameters:

- objects (`Array<CodeObjects::Base>`) —

  a list of CodeObjects::Base objects to pass to the template

- options (`Hash`) (defaults to: `{}`) —

  (see render)

    100
    101
    102
    103
    104
    105

    # File 'lib/yard/templates/engine.rb', line 100

    def generate(objects, options = {})
      options = set_default_options(options)
      options.objects = objects
      options.object = Registry.root
      template(options.template, :fulldoc, options.format).run(options)
    end

### .register_template_path(path) ⇒ `void`

This method returns an undefined value.

Registers a new template path in template_paths

Parameters:

- path (`String`) —

  a new template path

    20
    21
    22

    # File 'lib/yard/templates/engine.rb', line 20

    def register_template_path(path)
      template_paths.push(path) unless template_paths.include?(path)
    end

### .render(options = {}) ⇒ `String`

Renders a template on a code object using a set of default (overridable) options. Either the `:object` or `:type` keys must be provided.

If a `:serializer` key is provided and `:serialize` is not set to false, the rendered contents will be serialized through the Serializers::Base object. See with_serializer.

#### Examples:

#####

Renders an object with html formatting

    Engine.render(:format => :html, :object => obj)

#####

Renders without an object

    Engine.render(:type => :fulldoc, :otheropts => somevalue)

Parameters:

- options (`Hash`) (defaults to: `{}`) —

  the options hash

Options Hash (`options`):

- :format (`Symbol`) — default: `:text` —

  the default format

- :type (`Symbol`) — default: `nil` —

  the :object’s type.

- :template (`Symbol`) — default: `:default` —

  the default template

Returns:

- (`String`) —

  the rendered template

    81
    82
    83
    84
    85
    86
    87
    88
    89
    90

    # File 'lib/yard/templates/engine.rb', line 81

    def render(options = {})
      options = set_default_options(options)
      mod = template(options.template, options.type, options.format)

      if options.serializer && options.serialize != false
        with_serializer(options.object, options.serializer) { mod.run(options) }
      else
        mod.run(options)
      end
    end

### .template(*path) ⇒ `Template`

Creates a template module representing the path. Searches on disk for the first directory named `path` (joined by ‘/’) within the template paths and builds a template module for. All other matching directories in other template paths will be included in the generated module as mixins (for overriding).

Parameters:

- path (`Array<String, Symbol>`) —

  a list of path components

Returns:

- (`Template`) —

  the module representing the template

Raises:

- (`ArgumentError`) —

  if the path does not exist within one of the template_paths on disk.

    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45

    # File 'lib/yard/templates/engine.rb', line 34

    def template(*path)
      from_template = nil
      from_template = path.shift if path.first.is_a?(Template)
      path = path.join('/')
      full_paths = find_template_paths(from_template, path)

      path = File.cleanpath(path).gsub('../', '')
      raise ArgumentError, "No such template for #{path}" if full_paths.empty?
      mod = template!(path, full_paths)

      mod
    end

### .template!(path, full_paths = nil) ⇒ `Template`

Forces creation of a template at `path` within a `full_path`.

Parameters:

- path (`String`) —

  the path name of the template

- full_paths (`Array<String>`) (defaults to: `nil`) —

  the full path on disk of the template

Returns:

- (`Template`) —

  the template module representing the `path`

    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62

    # File 'lib/yard/templates/engine.rb', line 52

    def template!(path, full_paths = nil)
      full_paths ||= [path]
      full_paths = [full_paths] unless full_paths.is_a?(Array)
      name = template_module_name(full_paths.first)
      begin; return const_get(name); rescue NameError; nil end

      mod = const_set(name, Module.new)
      mod.send(:include, Template)
      mod.send(:initialize, path, full_paths)
      mod
    end

### .with_serializer(object, serializer) { ... } ⇒ `Object`

Serializes the results of a block with a `serializer` object.

Parameters:

- object (`CodeObjects::Base`) —

  the code object to serialize

- serializer (`Serializers::Base`) —

  the serializer object

Yields:

- a block whose result will be serialize

Yield Returns:

- (`String`) —

  the contents to serialize

See Also:

- Serializers::Base

    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129

    # File 'lib/yard/templates/engine.rb', line 114

    def with_serializer(object, serializer)
      output = nil
      filename = serializer.serialized_path(object)
      if serializer.respond_to?(:basepath)
        filename = File.join(serializer.basepath, filename)
      end
      log.capture("Generating #{filename}", nil) do
        serializer.before_serialize if serializer
        output = yield
        if serializer
          serializer.serialize(object, output)
          serializer.after_serialize(output)
        end
      end
      output
    end