use Text::Template ;

my $t = 'author: $author, title: $title' ;
	say fill_in $t, variables => { author => 'M. Twain', title => 'Niagara'} ;

The text template can be a string or a Heredoc for multi line templates. You can define your template in your code or in a separate file.

Text::Template is a thin layer over Perl6 string interpolation and EVAL, it is important to understand the security implications when using it.

The way EVAL works doesn't make it possible to use local variables, you need to pass your variables to fill_in. I will try to work around that limitation but passing variables in the call to fill_inor collecting them in a hash to pass to fill_in often looks cleaner.

• sub fill_in (Str $template, :%variables?) Accepts a template and optional variables that you want to define for the current template rendering. This may generate exceptions.

• sub fill_in(Str $template, :%variables?, :$catch_exceptions, :$no_warnings?) Accepts a template, optional variables, $catch_exceptions flag, and an optional $no_warnings flag.

if $catch_exceptions is set, fill_in will catch the exceptions and return Nil. This lets you handle the calls to fill_in with an error rather than an exception.

By Default fill_in will display the exception it has caught, you can change this behavior by passing the $no_warnings flag.

VARIABLES

Passing variables to fill_in The variables you pass through the %variables hash are local to the fill_in call. You can also pass subroutines.

my $title = 'Niagara' ;
	my $t = 'author: $author, title: $title' ;
	say fill_in $t, variables => { author => 'M. Twain', title => $title} ;

TEMPLATE FILES

Define template in file You can use IO.slurp to read your template from a file

say fill_in 'file_template'.IO.slurp, variables => { location => 'in file'} ;

Including templates

say fill_in q:to/TEMPLATE/, variables => { location => 'TOP' } ;
		# include text file, it will be included verbatim
		{ 'file_template'.IO.slurp }

# include text file and render it with the current variables
		{ fill_in 'file_template'.IO.slurp, variables => %variables }

# include text file and render it with specific variables
		{ fill_in 'file_template'.IO.slurp, variables => {location => 'in_include'} }
		TEMPLATE

%variables are the variables defined in the top call to fill_in.

EXCEPTIONS / ERRORS

Let fill_in catch the exceptions

fill_in catches exception and displays warning

say fill_in( '$non_existant', :catch_exceptions, ... ) // '' ;

fill_in catches exception, you display handle the error

say fill_in( '$non_existant', :catch_exceptions, :no_warnings, ... ) 
		// "Can't fill template @$?FILE:$?LINE" ;

catch exceptions in your code This gives you all control as you receive the exception.

try { say fill_in '$non_existant' }
	if $! {	say  "Can't fill template; exception: $! @$?FILE:$?LINE" }

EMBEDDING Perl6 CODE You can emmbed Perl6 code blocks, as in you can in any Perl6 string, the template can refer to variables, or subroutines, that are defined in the %variables parameter.

say fill_in q:to/TEMPLATE/, variables => {hash => {a => 1}, array => [4..6], private_sub => sub ( |c) {use Data::Dump::Tree ; get_dump(|c)},} ;
		\%has<a> = %hash<a>
		{ @array.map({ "array item * $_"}).join("\n") }

{ private_sub([{a => [^3]}, 123]) }
		TEMPLATE

{} vs $() {} block are scoping blocks, IE, variable declared in the block will not be visible outside the block.

say fill_in(q:to/TEMPLATE/, :catch_exceptions) // '' ;
		$( my $not_scoped = 1 ) ... $not_scoped
		{ my $scoped = 1 } ... $scoped ... will generate an exception
		TEMPLATE

CODE BLOCKS RETURNED VALUES The value returned by your code blocks is integrated in the rendering og the template. if you want to avoid that, return an empty string as the last statement of your code block; in a Heredoc, it will use a line of the template even with an empty string.

Your code block is returns a single value even if it is multiple lines long.

BUGS Submit bugs (preferably as executable tests) and, please, make suggestions.

Nadim ibn hamouda el Khemir https://github.com/nkh

This program is free software; you can redistribute it and/or modify it under the same terms as Perl6 itself.

P5 Text::Template

) ; }