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.