Class: Asciidoctor::Converter::TemplateConverter

Inherits:
Base
  • Object
show all
Defined in:
lib/asciidoctor/converter/template.rb

Overview

will be issued.

Constant Summary collapse

DEFAULT_ENGINE_OPTIONS = 
{
  erb: { trim: 0 },
  # TODO line 466 of haml/compiler.rb sorts the attributes; file an issue to make this configurable
  # NOTE AsciiDoc syntax expects HTML/XML output to use double quotes around attribute values
  haml: { format: :xhtml, attr_wrapper: '"', escape_attrs: false, ugly: true },
  slim: { disable_escape: true, sort_attrs: false, pretty: false },
}

Constants included from DefaultFactory

DefaultFactory::PROVIDED

Instance Attribute Summary

Attributes included from Asciidoctor::Converter

#backend

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

#content_only, #skip

Methods included from Asciidoctor::Converter

derive_backend_traits

Methods included from DefaultFactory

#for, #unregister_all

Methods included from Factory

#converters, #create, create, default, #for, new

Methods included from Logging

#logger, #message_with_context

Constructor Details

#initialize(backend, template_dirs, opts = {}) ⇒ TemplateConverter

Returns a new instance of TemplateConverter.



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/asciidoctor/converter/template.rb', line 52

def initialize backend, template_dirs, opts = {}
  Helpers.require_library 'tilt' unless defined? ::Tilt.new
  @backend = backend
  @templates = {}
  @template_dirs = template_dirs
  @eruby = opts[:eruby]
  @safe = opts[:safe]
  @active_engines = {}
  @engine = opts[:template_engine]
  @engine_options = {}.tap {|accum| DEFAULT_ENGINE_OPTIONS.each {|engine, engine_opts| accum[engine] = engine_opts.merge } }
  if opts[:htmlsyntax] == 'html' # if not set, assume xml since this converter is also used for DocBook (which doesn't specify htmlsyntax)
    @engine_options[:haml][:format] = :html5
    @engine_options[:slim][:format] = :html
  end
  @engine_options[:slim][:include_dirs] = template_dirs.reverse.map {|dir| ::File.expand_path dir }
  if (overrides = opts[:template_engine_options])
    overrides.each do |engine, override_opts|
      (@engine_options[engine] ||= {}).update override_opts
    end
  end
  case opts[:template_cache]
  when true
    logger.warn 'optional gem \'concurrent-ruby\' is not available. This gem is recommended when using the default template cache.' unless defined? ::Concurrent::Map
    @caches = self.class.caches
  when ::Hash
    @caches = opts[:template_cache]
  else
    @caches = {} # the empty Hash effectively disables caching
  end
  scan
end

Class Method Details

.caches ⇒ Object 



43
44
45
 
# File 'lib/asciidoctor/converter/template.rb', line 43

def self.caches
  @caches
end

.clear_caches ⇒ Object 



47
48
49
50
 
# File 'lib/asciidoctor/converter/template.rb', line 47

def self.clear_caches
  @caches[:scans].clear if @caches[:scans]
  @caches[:templates].clear if @caches[:templates]
end

Instance Method Details

#convert(node, template_name = nil, opts = nil) ⇒ String

Convert an AbstractNode to the backend format using the named template.

Looks for a template that matches the value of the template name or, if the template name is not specified, the value of the AbstractNode#node_name property.

Parameters:

  • node —

    the AbstractNode to convert

  • template_name (defaults to: nil) —

    the String name of the template to use, or the value of the node_name property on the node if a template name is not specified. (optional, default: nil)

  • opts (defaults to: nil) —

    an optional Hash that is passed as local variables to the template. (optional, default: nil)

Returns:

  • (String) —

    Returns the String result from rendering the template



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/asciidoctor/converter/template.rb', line 97

def convert node, template_name = nil, opts = nil
  unless (template = @templates[template_name ||= node.node_name])
    raise %(Could not find a custom template to handle transform: #{template_name})
  end

  # Slim doesn't include helpers in the template's execution scope (like HAML), so do it ourselves
  node.extend ::Slim::Helpers if (defined? ::Slim::Helpers) && (::Slim::Template === template)

  # NOTE opts become locals in the template
  if template_name == 'document'
    (template.render node, opts).strip
  else
    (template.render node, opts).rstrip
  end
end

#handles?(name) ⇒ Boolean

Checks whether there is a Tilt template registered with the specified name.

Parameters:

  • name —

    the String template name

Returns:

  • (Boolean) —

    Returns a Boolean that indicates whether a Tilt template is registered for the specified template name.



119
120
121
 
# File 'lib/asciidoctor/converter/template.rb', line 119

def handles? name
  @templates.key? name
end

#register(name, template) ⇒ Object

Registers a Tilt template with this converter.

Parameters:

  • name —

    the String template name

  • template —

    the Tilt template object to register

Returns:

  • the Tilt template object



136
137
138
139
140
141
142
143
 
# File 'lib/asciidoctor/converter/template.rb', line 136

def register name, template
  @templates[name] = if (template_cache = @caches[:templates])
    template_cache[template.file] = template
  else
    template
  end
  #create_handler name, template
end

#templates ⇒ Hash

Retrieves the templates that this converter manages.

Returns:

  • (Hash) —

    Returns a Hash of Tilt template objects keyed by template name.



126
127
128
 
# File 'lib/asciidoctor/converter/template.rb', line 126

def templates
  @templates.merge
end