NAME

Text::Nunjucks::Template - A compiled template that renders (environment.js class Template)

VERSION

version 0.001

SYNOPSIS

my $tmpl = $env->get_template('page.njk');
my $html = $tmpl->render( { title => 'Hi' } );

my $tmpl = Text::Nunjucks::Template->new( 'Hello {{ name }}', $env, 'greeting.njk' );

DESCRIPTION

A template, compiled to Perl code on first use. Obtain one from "get_template" in Text::Nunjucks::Environment, or construct it yourself.

new

Text::Nunjucks::Template->new( $src, $env, $path, $eager_compile );

Positional. $src is the template's source as a string, or a hash reference { type => 'string', obj => $source } or, for a template that is already compiled, { type => 'code', obj => \%compiled } (what Text::Nunjucks::Loader::Precompiled hands out); any other type dies. $env is the Environment whose filters, tests, globals and loaders the template uses; without one a fresh default Environment is made. $path is the name shown in error messages. With a true $eager_compile the template is compiled now, and a syntax error dies here rather than on the first render.

env

The Text::Nunjucks::Environment the template belongs to.

path

The path or name given at construction, shown in error messages.

render

my $html = $tmpl->render( \%context );
$tmpl->render( \%context, sub { my ( $err, $html ) = @_; ... } );

Renders the template. Compiles it first if needed. The return value, the death on error and the callback form are those of render of the Environment. The context is copied, so the template's set never changes the hash you passed.

A fourth positional argument exists for the compiled include of a template; it is internal and not part of the interface.

compile

$tmpl->compile;

Compiles the template if it is not compiled yet. A syntax error dies with the raw Text::Nunjucks::Lib::TemplateError, without the path and line prefix a render adds (as compile does in Nunjucks). Called by render; call it yourself to find errors early.

get_exported

$tmpl->get_exported( \%context, sub { my ( $err, $exported ) = @_; ... } );

Runs the template and passes its callback the hash of the top-level variables it exports, as import and from ... import read them. The callback is required. It gets ( $err, $exported ); on a compile error that is one argument, on a render error two, as in Nunjucks.

The macros in the hash read the template's variables through its context, which the template does not keep once it is done. This method makes it live as long as the returned hash or any function that was a value in it: every top-level function in the hash is a wrapper that holds the context (one function under two names gets one wrapper), so a macro you take out of the hash keeps working for as long as you keep it. That includes a coderef of yours which the template re-exports: it comes back as a wrapper, not as the reference you passed in.

A shallow copy of the hash holds the context only through the functions it contains. A function inside an exported array or object, taken out and called after the hash and every function that was a value in it are gone, finds the context gone and dies with template code ran after its render had ended. A returned hash that you store into data the template's context holds leaks that context. A template that failed is not kept: macros it handed out before the error find their context gone. See ADR 0021 in docs/adr/.

SUPPORT

Issues

Please report bugs and feature requests at https://github.com/Getty/p5-text-nunjucks/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.