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

Macro Summary

Instance Method 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 = 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 | Nil
resolve_method(name, object) : Callable | Callable::Proc | Nil 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.


def self.new(original : Crinja) #

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


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

Creates a new environment from config.


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`.


Class Method Detail

def self.dictionary(object) : Dictionary #

Casts an object with hash-like interface to Dictionary.


def self.render(io : IO, template, variables = nil, loader = Loader::FileSystemLoader.new, config = Config.new) #

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.


def self.render(template, variables = nil, loader = Loader::FileSystemLoader.new, config = Config.new) : 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.


def self.value(value) : Value #

def self.variables(object) : Variables #

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


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.

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.

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.

Instance Method Detail

def cache : TemplateCache #

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


def cache=(cache : TemplateCache) #

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


def config : Config #

The configuration for this environment.


def context : Context #

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


def errors : Array(Exception) #

def errors=(errors : Array(Exception)) #

def evaluate(expression : AST::ExpressionNode, bindings) : Value #

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


def evaluate(expression : AST::ExpressionNode) : Value #

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.


def evaluator #

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


def filters : Crinja::Filter::Library #

Filter library for this environment.

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


def from_string(string : String) #

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


def functions : Crinja::Function::Library #

Function library for this environment.

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


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.


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.


def global_context : Context #

The global context.


def loader : Loader #

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


def loader=(loader : Loader) #

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


def logger : ::Log #

The logger for this environment.


def operators : Crinja::Operator::Library #

Operator library for this environment.

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


def policies : Hash(String, Crinja::Value) #

Policies for this environment.


def select_template(names, parent = nil, globals = nil) #

Alias for #get_template(Iterable(String)).


def stringify(object, pretty = false) #

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


def tags : Crinja::Tag::Library #

Tag library for this environment.

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


def tests : Crinja::Test::Library #

Test library for this environment.

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


def undefined(name = nil) #

Creates a new #undefined.


def with_scope(ctx : Context, &) #

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


def with_scope(bindings = nil, &) #

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