NAME
Text::Nunjucks::Loader - 1:1 port of Nunjucks src/loader.js -- the base Loader (resolve/isRelative)
VERSION
version 0.001
DESCRIPTION
The base class of every template loader, a port of Nunjucks src/loader.js. A loader finds the source of a template by name for an Text::Nunjucks::Environment. Text::Nunjucks::Loader::FileSystem and Text::Nunjucks::Loader::Precompiled extend it, and so does a loader of your own. It does the resolve / is_relative work for relative template names and takes the on / emit event methods from Text::Nunjucks::EmitterObj.
Writing a loader
Extend this class and provide get_source:
package My::Loader;
use Moo;
extends 'Text::Nunjucks::Loader';
sub get_source {
my ( $self, $name ) = @_;
return unless exists $self->templates->{$name};
return { src => $self->templates->{$name}, path => $name, noCache => 0 };
}
has templates => ( is => 'ro', default => sub { {} } );
my $env = Text::Nunjucks::Environment->new( My::Loader->new( templates => { 'hi.njk' => 'Hi {{ who }}' } ) );
get_source($name) returns a hash reference, or undef (or an empty return) when the loader does not have the template, so the next loader is asked. The hash has these keys:
- src
-
The template source as a string. A hash reference
{ type => 'code', obj => \%compiled }is a precompiled template, see Text::Nunjucks::Loader::Precompiled. - path
-
The template's path or name, shown in error messages.
- noCache
-
True to keep the Environment from caching the template, so the next lookup asks the loader again. The key keeps its JavaScript spelling because the Environment reads it by that name.
A loader that finds its templates asynchronously defines async to return a true value; its get_source then receives a callback as the second argument and calls it, instead of returning:
sub async { 1 }
sub get_source {
my ( $self, $name, $cb ) = @_;
$cb->( undef, { src => $src, path => $path } ); # found
$cb->( undef, undef ); # not found, next loader
$cb->($err); # failed
}
The callbacks run synchronously unless the loader defers them (ADR 0003). An asynchronous loader serves render and render_string with a callback, and get_template with a callback.
A loader announces what it did with emit: $self->emit( load => $name, $source ) after a template was read, $self->emit( update => $name, $fullname ) when one changed on its own. The Environment listens to both.
cache
Hash reference of the compiled templates the loader holds. The Environment sets it to a fresh hash when it takes the loader over and replaces it on invalidate_cache.
async
Returns false. A loader that is asynchronous overrides it to return true, see above.
resolve
my $name = $loader->resolve( $from, $to );
Resolves the relative template name $to against the template $from, as Node's path.resolve( path.dirname($from), $to ): purely on the strings (a .. removes the directory before it, the file system is not asked), and against the current working directory when $from is itself relative. The result is the name the loader's get_source receives and its cache key (ADR 0018).
is_relative
my $bool = $loader->is_relative($filename);
True (1) when the name starts with ./ or ../, otherwise 0.
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.