Class: Liquid::Environment

Inherits:
Object
  • Object
show all
Defined in:
lib/liquid/environment.rb

Overview

The Environment is the container for all configuration options of Liquid, such as the registered tags, filters, and the default error mode.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Environment

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Initializes a new environment instance.



76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/liquid/environment.rb', line 76

def initialize
  @tags = Tags::STANDARD_TAGS.dup
  @error_mode = :lax
  @strainer_template = Class.new(StrainerTemplate).tap do |klass|
    klass.add_filter(StandardFilters)
  end
  @exception_renderer = ->(exception) { exception }
  @file_system = BlankFileSystem.new
  @default_resource_limits = Const::EMPTY_HASH
  @strainer_template_class_cache = {}
end

Instance Attribute Details

#default_resource_limits ⇒ Object

The default resource limits that are used to limit the resources that a template can consume.



27
28
29
 
# File 'lib/liquid/environment.rb', line 27

def default_resource_limits
  @default_resource_limits
end

#error_mode ⇒ Object

The default error mode for all templates. This can be overridden on a per-template basis.



9
10
11
 
# File 'lib/liquid/environment.rb', line 9

def error_mode
  @error_mode
end

#exception_renderer ⇒ Object

The exception renderer that is used to render exceptions that are raised when rendering a template



20
21
22
 
# File 'lib/liquid/environment.rb', line 20

def exception_renderer
  @exception_renderer
end

#file_system ⇒ Object

The default file system that is used to load templates from.



23
24
25
 
# File 'lib/liquid/environment.rb', line 23

def file_system
  @file_system
end

#strainer_template ⇒ Object

The strainer template which is used to store filters that are available to use in templates.



16
17
18
 
# File 'lib/liquid/environment.rb', line 16

def strainer_template
  @strainer_template
end

#tags ⇒ Object

The tags that are available to use in the template.



12
13
14
 
# File 'lib/liquid/environment.rb', line 12

def tags
  @tags
end

Class Method Details

.build(tags: nil, file_system: nil, error_mode: nil, exception_renderer: nil) {|environment| ... } ⇒ Environment

Creates a new environment instance.

Parameters:

  • tags (Hash) (defaults to: nil) —

    The tags that are available to use in the template.

  • file_system (defaults to: nil) —

    The default file system that is used to load templates from.

  • error_mode (Symbol) (defaults to: nil) —

    The default error mode for all templates (either :strict, :warn, or :lax).

  • exception_renderer (Proc) (defaults to: nil) —

    The exception renderer that is used to render exceptions.

Yield Parameters:

  • environment (Environment) —

    The environment instance that is being built.

Returns:



42
43
44
45
46
47
48
49
50
 
# File 'lib/liquid/environment.rb', line 42

def build(tags: nil, file_system: nil, error_mode: nil, exception_renderer: nil)
  ret = new
  ret.tags = tags if tags
  ret.file_system = file_system if file_system
  ret.error_mode = error_mode if error_mode
  ret.exception_renderer = exception_renderer if exception_renderer
  yield ret if block_given?
  ret.freeze
end

.dangerously_override(environment) { ... } ⇒ Object

Sets the default environment instance for the duration of the block

Parameters:

  • environment (Environment) —

    The environment instance to use as the default for the duration of the block.

Yields:

Returns:

  • (Object) —

    The return value of the block.



65
66
67
68
69
70
71
 
# File 'lib/liquid/environment.rb', line 65

def dangerously_override(environment)
  original_default = @default
  @default = environment
  yield
ensure
  @default = original_default
end

.default ⇒ Environment

Returns the default environment instance.

Returns:



55
56
57
 
# File 'lib/liquid/environment.rb', line 55

def default
  @default ||= new
end

Instance Method Details

#create_strainer(context, filters = Const::EMPTY_ARRAY) ⇒ Liquid::Strainer

Creates a new strainer instance with the given filters, caching the result for faster lookup.

Parameters:

  • context (Liquid::Context) —

    The context that the strainer will be used in.

  • filters (Array<Module>) (defaults to: Const::EMPTY_ARRAY) —

    The filters that the strainer will have access to.

Returns:

  • (Liquid::Strainer) —

    The new strainer instance.



124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/liquid/environment.rb', line 124

def create_strainer(context, filters = Const::EMPTY_ARRAY)
  return @strainer_template.new(context) if filters.empty?

  strainer_template = @strainer_template_class_cache[filters] ||= begin
    klass = Class.new(@strainer_template)
    filters.each { |f| klass.add_filter(f) }
    klass
  end

  strainer_template.new(context)
end

#filter_method_names ⇒ Array<String>

Returns the names of all the filter methods that are available to use in the strainer template.

Returns:

  • (Array<String>) —

    The names of all the filter methods.



140
141
142
 
# File 'lib/liquid/environment.rb', line 140

def filter_method_names
  @strainer_template.filter_method_names
end

#freeze ⇒ Object 



152
153
154
155
156
157
 
# File 'lib/liquid/environment.rb', line 152

def freeze
  @tags.freeze
  # TODO: freeze the tags, currently this is not possible because of liquid-c
  # @strainer_template.freeze
  super
end

#register_filter(filter) ⇒ void

This method returns an undefined value.

Registers a new filter with the environment.

Parameters:

  • filter (Module) —

    The module that contains the filter methods.



101
102
103
104
 
# File 'lib/liquid/environment.rb', line 101

def register_filter(filter)
  @strainer_template_class_cache.clear
  @strainer_template.add_filter(filter)
end

#register_filters(filters) ⇒ self

Registers multiple filters with this environment.

Parameters:

  • filters (Array<Module>) —

    The modules that contain the filter methods.

Returns:

  • (self) 


110
111
112
113
114
 
# File 'lib/liquid/environment.rb', line 110

def register_filters(filters)
  @strainer_template_class_cache.clear
  filters.each { |f| @strainer_template.add_filter(f) }
  self
end

#register_tag(name, klass) ⇒ void

This method returns an undefined value.

Registers a new tag with the environment.

Parameters:

  • name (String) —

    The name of the tag.

  • klass (Liquid::Tag) —

    The class that implements the tag.



93
94
95
 
# File 'lib/liquid/environment.rb', line 93

def register_tag(name, klass)
  @tags[name] = klass
end

#tag_for_name(name) ⇒ Liquid::Tag

Returns the tag class for the given tag name.

Parameters:

  • name (String) —

    The name of the tag.

Returns:



148
149
150
 
# File 'lib/liquid/environment.rb', line 148

def tag_for_name(name)
  @tags[name]
end