class Crinja

Overview

This class represents the core component of the Crinja template engine.

It contains the runtime environment including configuration, global variables as well as loading and rendering templates.

Instances of this class may be modified if they are not shared and if no template was loaded so far. Modifications on environments after the first template was loaded will lead to surprising effects and undefined behavior.

It also contains macros to easily define custom template features such as filters, tests and functions.

Included Modules

Defined in:

crinja.cr
environment.cr
object.cr
runtime/callable.cr:1
runtime/callable.cr:99
runtime/safe_string.cr
runtime/undefined.cr
runtime/value.cr:1
runtime/value.cr:11
visitor/html.cr
visitor/inspector.cr

Constant Summary

Log = ::Log.for(self)
UNDEFINED = Undefined.new("UNDEFINED")
VERSION = {{ (`shards version /root/project/src`).chomp.stringify }}

Constructors

Class Method Summary

Instance Method Summary

Macro Summary

Instance methods inherited from module Crinja::Resolver

call_filter(name : String, target : Value, varargs = [] of Value, kwargs = Variables.new) : Value
call_filter(name : String, target) : Value call_filter, execute_call(callable, varargs : Array(Value) = [] of Value, kwargs : Variables = Variables.new, target : Value? = nil) : Value
execute_call(callable : Callable | Callable::Proc, arguments : Arguments) : Value execute_call, resolve(name : String) : Value resolve, resolve_callable(identifier) : Value resolve_callable, resolve_callable!(identifier : Callable | Callable::Proc) : Callable | Callable::Proc
resolve_callable!(identifier : Value) : Callable | Callable::Proc resolve_callable!

Class methods inherited from module Crinja::Resolver

resolve_attribute(name, object : Value) : Value
resolve_attribute(name, value) : Value resolve_attribute, resolve_dig(name : String, object) : Value
resolve_dig(name : Value, value : Value) : Value
resolve_dig(name, object) : Value resolve_dig, resolve_getattr(name : Value, value : Value) : Value
resolve_getattr(name, value) : Value resolve_getattr, resolve_method(name, value : Value) : Callable | Callable::Proc?
resolve_method(name, object) : Callable | Callable::Proc? resolve_method, resolve_with_hash_accessor(name : Value, value : Value) : Value
resolve_with_hash_accessor(name, value : Value) : Value resolve_with_hash_accessor

Constructor Detail

def self.new(context = Context.new, config = Config.new, loader = Loader::FileSystemLoader.new, cache = TemplateCache::InMemory.new, &) #

Creates a new environment and yields self for configuration.


[View source]
def self.new(original : Crinja) #

Creates a new environment with the context and configuration from the original environment.


[View source]
def self.new(config : Config, loader = Loader::FileSystemLoader.new, cache = TemplateCache::InMemory.new) #

Creates a new environment from config.


[View source]
def self.new(context : Crinja::Context = Context.new, config : Crinja::Config = Config.new, loader : Crinja::Loader = Loader::FileSystemLoader.new, cache : Crinja::TemplateCache = TemplateCache::InMemory.new) #

Creates a new environment with default values. The context becomes both #global_context as well as current ``#context`.


[View source]

Class Method Detail

def self.dictionary(object) : Dictionary #

Casts an object with hash-like interface to Dictionary.


[View source]
def self.render(io : IO, template, variables = nil, loader = nil, config = nil) #

Render Crinja template template to an IO io.

Variables for the template can be assigned as parameter variables.

This uses default loader and config unless these are provided as optional parameters.

A new Crinja instance will be created for each invocation and it will parse the template. To parse the same template once and invoke it multiple times, it needs to be created directly (using Crinja#from_string or Template.new) and stored in a variable.


[View source]
def self.render(template, variables = nil, loader = nil, config = nil) : String #

Render Crinja template template to a String.

Variables for the template can be assigned as parameter variables.

This uses default loader and config unless these are provided as optional parameters.

A new Crinja instance will be created for each invocation and it will parse the template. To parse the same template once and invoke it multiple times, it needs to be created directly (using Crinja#from_string or Template.new) and stored in a variable.


[View source]
def self.value(value) : Value #

[View source]
def self.variables(object) : Variables #

Casts an object with hash-like interface to Variables, which can be used for name lookup.


[View source]

Instance Method Detail

def cache : TemplateCache #

A cache where parsed templates are stored. Defaults to TemplateCache::InMemory.


[View source]
def cache=(cache : TemplateCache) #

A cache where parsed templates are stored. Defaults to TemplateCache::InMemory.


[View source]
def config : Config #

The configuration for this environment.


[View source]
def context : Context #

The current context in which evaluation happens. It can only be changed by #with_context.


[View source]
def errors : Array(Exception) #

[View source]
def errors=(errors : Array(Exception)) #

[View source]
def evaluate(expression : AST::ExpressionNode, bindings) : Value #

Evaluates a Crinja expression with #evaluator and returns the resulting raw value.


[View source]
def evaluate(expression : AST::ExpressionNode) : Value #

[View source]
def evaluate(expression, bindings = nil) : String #

Parses and evaluates a Crinja expression with #evaluator. Returns a string which will be auto-escaped if config.autoescape? is true.


[View source]
def evaluator #

Returns an Crinja::Evaluator which allows evaluation of expressions.


[View source]
def filters : Crinja::Filter::Library #

Filter library for this environment.

See Crinja::Filter for a list of builtin filters.


[View source]
def from_string(string : String) #

Loads a template from string. This parses the given string and returns a Template object.


[View source]
def functions : Crinja::Function::Library #

Function library for this environment.

See Crinja::Function for a list of builtin functions.


[View source]
def get_template(name : String, parent = nil, globals = nil) #

Loads a template from the loader. If a loader is configured this method ask the loader for the template and returns a Template. If the parent parameter is not None, join_path() is called to get the real template name before loading.

TODO parent parameter is not implemented. The globals parameter can be used to provide template wide globals. These variables are available in the context at render time. If the template does not exist a TemplateNotFoundError is raised.


[View source]
def get_template(names : Iterable(String), parent = nil, globals = nil) #

Works like #get_template(String) but tries a number of templates before it fails. If it cannot find any of the templates, it will raise a TemplateNotFoundError.


[View source]
def global_context : Context #

The global context.


[View source]
def loader : Loader #

The loader through which #get_template loads a template. Defaults to Loader::FileSystemLoader with searchpath of the current working directory.


[View source]
def loader=(loader : Loader) #

The loader through which #get_template loads a template. Defaults to Loader::FileSystemLoader with searchpath of the current working directory.


[View source]
def logger : ::Log #

The logger for this environment.


[View source]
def operators : Crinja::Operator::Library #

Operator library for this environment.

See Crinja::Operator for a list of builtin operators.


[View source]
def policies : Hash(String, Crinja::Value) #

Policies for this environment.


[View source]
def select_template(names, parent = nil, globals = nil) #

Alias for #get_template(Iterable(String)).


[View source]
def stringify(object, pretty = false) #

Turns object into a string represenation using Crinja::Finalizer.


[View source]
def tags : Crinja::Tag::Library #

Tag library for this environment.

See Crinja::Tag for a list of builtin tags.


[View source]
def tests : Crinja::Test::Library #

Test library for this environment.

See Crinja::Test for a list of builtin tests.


[View source]
def undefined(name = nil) #

Creates a new #undefined.


[View source]
def with_scope(ctx : Context, &) #

Executes the block inside the context ctx and returns to the previous context afterwards.


[View source]
def with_scope(bindings = nil, &) #

Executes the block inside a new sub-context with optional local scoped bindings. Returns to the previous context afterwards.


[View source]

Macro Detail

macro filter(defaults = nil, name = nil, &block) #

This macro returns a Crinja::Callable proc which implements a Crinja::Filter.

defaults are set as default values in the Crinja::Arguments object, which a call to this proc receives.

If a name is provided, the created proc will automatically be registered as a default filter at Crinja::Filter::Library.

The macro takes a block which will be the main body for the proc. There, the following variables are available:

  • arguments : Crinja::Arguments - Call arguments from the caller including defaults.
  • env : Crinja - The current environment.
  • target : Crinja::Value - The value which is to be filtered. Short cut for arguments.target.

[View source]
macro function(defaults = nil, name = nil, &block) #

This macro returns a Crinja::Callable proc which implements a Crinja::Function.

defaults are set as default values in the Crinja::Arguments object, which a call to this proc receives.

If a name is provided, the created proc will automatically be registered as a default golbal function at Crinja::Function::Library.

The macro takes a block which will be the main body for the proc. There, the following variables are available:

  • arguments : Crinja::Arguments - Call arguments from the caller including defaults.
  • env : Crinja - The current environment.

[View source]
macro test(defaults = nil, name = nil, &block) #

This macro returns a Crinja::Callable proc which implements a Crinja::Test.

defaults are set as default values in the Crinja::Arguments object, which a call to this proc receives.

If a name is provided, the created proc will automatically be registered as a default test at Crinja::Test::Library.

The macro takes a block which will be the main body for the proc. There, the following variables are available:

  • arguments : Crinja::Arguments - Call arguments from the caller including defaults.
  • env : Crinja - The current environment.
  • target : Crinja::Value - The subject of the test. Short cut for arguments.target.

[View source]