Class: Liquid2::Template

Inherits:
Object
  • Object
show all
Defined in:
lib/liquid2/template.rb

Overview

A compiled template bound to a Liquid environment and ready to be rendered.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(env, source, ast, name: "", path: nil, up_to_date: nil, globals: nil, overlay: nil) ⇒ Template

Returns a new instance of Template.

Parameters:

  • env (Environment)
  • source (String)
  • ast (Array[Node | String])
  • name (String) (defaults to: "") —

    The template's name.

  • path (String?) (defaults to: nil) —

    The path or other qualifying data to name.

  • globals (_Namespace) (defaults to: nil) —

    Global template variables.

  • overlay (_Namespace) (defaults to: nil) —

    Additional template variables. Could be from front matter or other meta data store, for example.



16
17
18
19
20
21
22
23
24
25
26
 
# File 'lib/liquid2/template.rb', line 16

def initialize(env, source, ast, name: "", path: nil, up_to_date: nil, globals: nil,
               overlay: nil)
  @env = env
  @source = source
  @ast = ast
  @name = name
  @path = path
  @globals = globals || {} # steep:ignore UnannotatedEmptyCollection
  @overlay = overlay || {} # steep:ignore UnannotatedEmptyCollection
  @up_to_date = up_to_date
end

Instance Attribute Details

#ast ⇒ Object (readonly)

Returns the value of attribute ast.



6
7
8
 
# File 'lib/liquid2/template.rb', line 6

def ast
  @ast
end

#env ⇒ Object (readonly)

Returns the value of attribute env.



6
7
8
 
# File 'lib/liquid2/template.rb', line 6

def env
  @env
end

#globals ⇒ Object (readonly)

Returns the value of attribute globals.



6
7
8
 
# File 'lib/liquid2/template.rb', line 6

def globals
  @globals
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



6
7
8
 
# File 'lib/liquid2/template.rb', line 6

def name
  @name
end

#overlay ⇒ Object (readonly)

Returns the value of attribute overlay.



6
7
8
 
# File 'lib/liquid2/template.rb', line 6

def overlay
  @overlay
end

#path ⇒ Object (readonly)

Returns the value of attribute path.



6
7
8
 
# File 'lib/liquid2/template.rb', line 6

def path
  @path
end

#source ⇒ Object (readonly)

Returns the value of attribute source.



6
7
8
 
# File 'lib/liquid2/template.rb', line 6

def source
  @source
end

#up_to_date ⇒ Object (readonly)

Returns the value of attribute up_to_date.



6
7
8
 
# File 'lib/liquid2/template.rb', line 6

def up_to_date
  @up_to_date
end

Instance Method Details

#analyze(include_partials: false) ⇒ Liquid2::StaticAnalysis::Result

Statically analyze this template and report variable, tag and filter usage.

Parameters:

  • include_partials (bool) (defaults to: false)

Returns:



92
93
94
 
# File 'lib/liquid2/template.rb', line 92

def analyze(include_partials: false)
  Liquid2::StaticAnalysis.analyze(self, include_partials: include_partials)
end

#comments ⇒ Array[BlockComment | InlineComment | Comment]

Return an array of comment nodes found in this template.

Comment nodes have token and text attributes. Use template.comments.map(&:text) to get an array of comment strings. Each comment string includes leading and trailing whitespace.

Note that this method does not try to load included or render templates when looking. for comment nodes.

Returns:



106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/liquid2/template.rb', line 106

def comments
  context = RenderContext.new(self)
  nodes = [] # : Array[BlockComment | InlineComment | Comment]

  # @type var visit: ^(Node) -> void
  visit = lambda do |node|
    if node.is_a?(BlockComment) || node.is_a?(InlineComment) || node.is_a?(Comment)
      nodes << node
    end

    node.children(context, include_partials: false).each do |child|
      visit.call(child) if child.is_a?(Node)
    end
  end

  @ast.each { |node| visit.call(node) if node.is_a?(Node) }

  nodes
end

#docs ⇒ Array[DocTag]

Return an array of {% doc %} nodes found in this template.

Each instance of Liquid2::DocTag has a token and text attribute. Use Template#docs.map(&:text) to get an array of doc strings.

Returns:



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/liquid2/template.rb', line 132

def docs
  context = RenderContext.new(self)
  nodes = [] # : Array[DocTag]

  # @type var visit: ^(Node) -> void
  visit = lambda do |node|
    nodes << node if node.is_a?(DocTag)

    node.children(context, include_partials: false).each do |child|
      visit.call(child) if child.is_a?(Node)
    end
  end

  @ast.each { |node| visit.call(node) if node.is_a?(Node) }

  nodes
end

#filter_names(include_partials: false) ⇒ Array[String]

Return the names of all filters used in this template.

Parameters:

  • include_partials (bool) (defaults to: false)

Returns:

  • (Array[String]) 


218
219
220
 
# File 'lib/liquid2/template.rb', line 218

def filter_names(include_partials: false)
  analyze(include_partials: include_partials).filters.keys
end

#full_name ⇒ Object

Return this template's path joined with its name, or just name if path is not available.



31
32
33
 
# File 'lib/liquid2/template.rb', line 31

def full_name
  @name + @path.to_s
end

#global_variable_paths(include_partials: false) ⇒ Array[String]

Return an array of global variables used in this template, including path segments.

Parameters:

  • include_partials (bool) (defaults to: false)

Returns:

  • (Array[String]) 


204
205
206
 
# File 'lib/liquid2/template.rb', line 204

def global_variable_paths(include_partials: false)
  analyze(include_partials: include_partials).globals.values.flatten.map(&:to_s).uniq
end

#global_variable_segments(include_partials: false) ⇒ Array[Array[String | Integer | Segment]]

Return an array of global variables used in this template, each as an array of segments.

Parameters:

  • include_partials (bool) (defaults to: false)

Returns:

  • (Array[Array[String | Integer | Segment]]) 


211
212
213
 
# File 'lib/liquid2/template.rb', line 211

def global_variable_segments(include_partials: false)
  analyze(include_partials: include_partials).globals.values.flatten.map(&:segments).uniq
end

#global_variables(include_partials: false) ⇒ Array[String]

Return an array of global variables used in this template, without path segments.

Parameters:

  • include_partials (bool) (defaults to: false)

Returns:

  • (Array[String]) 


197
198
199
 
# File 'lib/liquid2/template.rb', line 197

def global_variables(include_partials: false)
  analyze(include_partials: include_partials).globals.keys
end

#macros(include_partials: false) ⇒ Array[MacroTag], Array[CallTag]

Return arrays of {% macro %} and {% call %} tags found in this template.

Parameters:

  • include_partials (bool) (defaults to: false)

Returns:



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/liquid2/template.rb', line 153

def macros(include_partials: false)
  context = RenderContext.new(self)
  macro_nodes = [] # : Array[MacroTag]
  call_nodes = [] # : Array[CallTag]

  # @type var visit: ^(Node) -> void
  visit = lambda do |node|
    macro_nodes << node if node.is_a?(MacroTag)
    call_nodes << node if node.is_a?(CallTag)

    node.children(context, include_partials: include_partials).each do |child|
      visit.call(child) if child.is_a?(Node)
    end
  end

  @ast.each { |node| visit.call(node) if node.is_a?(Node) }

  [macro_nodes, call_nodes]
end

#make_globals(namespace) ⇒ Object

Merge template globals with another namespace.



79
80
81
 
# File 'lib/liquid2/template.rb', line 79

def make_globals(namespace)
  @globals.merge(@overlay, namespace || {})
end

#render(globals = nil) ⇒ String

Render this template with data from globals added to the render context.

Parameters:

  • globals (Hash[::String, untyped]) (defaults to: nil)

Returns:

  • (String) 


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

def render(globals = nil)
  buf = +""
  context = RenderContext.new(self, globals: make_globals(globals))
  render_with_context(context, buf)
  buf
end

#render_with_context(context, buffer, partial: false, block_scope: false, namespace: nil) ⇒ Object 



45
46
47
48
49
50
51
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
 
# File 'lib/liquid2/template.rb', line 45

def render_with_context(context, buffer, partial: false, block_scope: false, namespace: nil)
  context.extend(namespace || {}) do
    index = 0
    while (node = @ast[index])
      index += 1
      case node
      when String
        buffer << node
      else
        node.render_with_disabled_tag_check(context, buffer)
      end

      context.raise_for_output_limit(buffer.bytesize)

      next unless (interrupt = context.interrupts.pop)

      break if interrupt == :stop_render

      if !partial || block_scope
        raise LiquidSyntaxError.new("unexpected #{interrupt}",
                                    node.token) # steep:ignore
      end

      context.interrupts << interrupt
      break
    end
  end
rescue LiquidError => e
  e.source = context.template.source unless e.source
  e.template_name = @name unless e.template_name || @name.empty?
  raise
end

#tag_names(include_partials: false) ⇒ Array[String]

Return the names of all tags used in this template.

Parameters:

  • include_partials (bool) (defaults to: false)

Returns:

  • (Array[String]) 


225
226
227
 
# File 'lib/liquid2/template.rb', line 225

def tag_names(include_partials: false)
  analyze(include_partials: include_partials).tags.keys
end

#to_s ⇒ Object 



28
 
# File 'lib/liquid2/template.rb', line 28

def to_s = @ast.to_s

#up_to_date? ⇒ Boolean

Return false if this template is stale and needs to be loaded again. nil is returned if an up_to_date proc is not available.

Returns:

  • (Boolean) 


85
86
87
 
# File 'lib/liquid2/template.rb', line 85

def up_to_date?
  @up_to_date&.call
end

#variable_paths(include_partials: false) ⇒ Array[String]

Return an array of variables used in this template, including path segments.

Parameters:

  • include_partials (bool) (defaults to: false)

Returns:

  • (Array[String]) 


183
184
185
 
# File 'lib/liquid2/template.rb', line 183

def variable_paths(include_partials: false)
  analyze(include_partials: include_partials).variables.values.flatten.map(&:to_s).uniq
end

#variable_segments(include_partials: false) ⇒ Array[Array[String | Integer | Segment]]

Return an array of variables used in this template, each as an array of segments.

Parameters:

  • include_partials (bool) (defaults to: false)

Returns:

  • (Array[Array[String | Integer | Segment]]) 


190
191
192
 
# File 'lib/liquid2/template.rb', line 190

def variable_segments(include_partials: false)
  analyze(include_partials: include_partials).variables.values.flatten.map(&:segments).uniq
end

#variables(include_partials: false) ⇒ Array[String]

Return an array of variables used in this template, without path segments.

Parameters:

  • include_partials (bool) (defaults to: false)

Returns:

  • (Array[String]) 


176
177
178
 
# File 'lib/liquid2/template.rb', line 176

def variables(include_partials: false)
  analyze(include_partials: include_partials).variables.keys
end