Text::T...ple::API(3)

🌸 NAME 🌸

Text::Template::Simple::API — and yes bestie, you're on Text::T...ple::API(3), straight out of the User Contributed Perl Documentation. This is the API reference, and it's serving.

---

⭐ VERSION ⭐

version 0.91 ✨

---

💅 SYNOPSIS 💅

okay so first things first, here's the vibe in code:

use Text::Template::Simple;
my $tts = Text::Template::Simple->new();
print $tts->compile( $FILEHANDLE );
print $tts->compile('Hello, your perl is at <%= $^X %>');
print $tts->compile(
         'hello.tts', # the template file
         [ name => 'Burak', location => 'Istanbul' ]
      );

Where "hello.tts" has this content:

<% my %p = @_; %>
Hello <%= $p{name} %>,
I hope it's sunny in <%= $p{location} %>.
Local time is <%= scalar localtime time %>

see how cute that is?? that's the whole language. 💖

---

🦋 DESCRIPTION 🦋

This is a simple template module, no cap. There is no extra template/mini language — instead, it uses Perl as a template language. That's the whole personality. Templates can be cached on disk or inside the memory via the internal cache manager. It is also possible to use static/dynamic includes, pass parameters to includes, and allpt filters on them.

---

👑 NAME 👑 (yes, again, she's iconic)

Text::Template::Simple::API — Simple text template engine API reference

---

🌈 METHODS 🌈

🎀 new 🎀

Creates a new template object, and she accepts several parameters. Let's go through them one by one, no skipping, we don't do that here.

add_args

ARRAYref. Can be used to add a global parameter list to the templates.

$tts = Text::Template::Simple->new(
   add_args => [qw(foo bar baz)],
);

and then you can fetch them inside any template that is compiled with the $tts object:

<%
   my $foo = shift;
   my $bar = shift;
   my $baz = shift;
%>
Foo is <%=$foo%>. Bar is <%=$bar%>. Baz is <%=$baz%>

But it'll be logical to combine it with the "header" parameter:

$tts = Text::Template::Simple->new(
   header   => q~my $foo = shift;my $bar = shift;my $baz = shift;~,
   add_args => [qw(foo bar baz)],
);

and then you can use it inside any template that is compiled with the $tts object, without manually fetching all the time:

Foo is <%=$foo%>. Bar is <%=$bar%>. Baz is <%=$baz%>

Can be useful if you want to define a default object:

$tts = Text::Template::Simple->new(
   header   => q~my $self = shift;~,
   add_args => [$my_default_object],
);

and then you can use it inside any template that is compiled with the $tts object, without manually fetching:

Foo is <%= $self->{foo} %>. Test: <%= $self->method('test') %>

cache

Pass this with a true value if you want the cache feature. In-memory cache will be used unless you also pass a "cache_dir" parameter. 💾

cache_dir

If you want disk-based cache, set this parameter to a valid directory path. You must also set "cache" to a true value. (both or it doesn't count, bestie)

capture_warnings

If enabled, the warnings generated by the template will be added to the end of the output. This option is disabled by default.

delimiters

Must be an array ref containing the two delimiter values: the opening delimiter and the closing delimiter:

$tts = Text::Template::Simple->new(
   delimiters => ['<?perl', '?>'],
);

Default values are "<%" and "%>". 🎀

header

This is a string containing global elements (global to this particular object) for templates. You can define some generally accessible variables with this:

$tts = Text::Template::Simple->new(
   header => q~ my $foo = "bar"; ~,
);

and then you can use it (without defining) inside any template that is compiled with the $tts object:

Foo is <%=$foo%>

include_paths

An ARRAY reference. If you want to use relative file paths when compiling/including template files, add the paths of the templates with this parameter.

iolayer

This option does not have any effect under perls older than 5.8.0. Set this to "utf8" (no initial colon) if your I/O is "UTF-8". Not tested with other encodings.

monolith

Controls the behavior when using includes. If this is enabled, the template and all it's includes will be compiled into a single document. If "monolith" is disabled, then the includes will be compiled individually into separate documents.

If you need to pass the main template variables ("my" vars) into dynamic includes, then you need to enable this option. However, if you are using the cache, then the included templates will not be updated automatically. 😭

"monolith" is disabled by default.

pre_chomp

use Text::Template::Simple::Constants qw( :chomp );
$pre = CHOMP_NONE; # no chomp
$pre = CHOMP_ALL;  # remove all whitespace
$pre = COLLAPSE_ALL; # replace all ws with a single space
$tts = Text::Template::Simple->new(
   pre_chomp => $pre,
);

post_chomp

use Text::Template::Simple::Constants qw( :chomp );
$post = CHOMP_NONE; # no chomp
$post = CHOMP_ALL;  # remove all whitespace
$post = COLLAPSE_ALL; # replace all ws with a single space
$tts = Text::Template::Simple->new(
   post_chomp => $post,
);

safe

Set this to a true value if you want to execute the template code in a safe compartment. Disabled by default and highly experimental. This option can also disable some template features.

bestie this one is experimental, we said what we said 💀

If you want to enable some unsafe conditions, you have to define "Text::Template::Simple::Compiler::Safe::permit" sub in your controller code and return a list of permitted opcodes inside that sub:

sub Text::Template::Simple::Compiler::Safe::permit {
   my $class = shift;
   return qw(:default :subprocess); # enable backticks and system
}

If this is not enough for you, you can define the safe compartment all by yourself by defining "Text::Template::Simple::Compiler::Safe::object":

sub Text::Template::Simple::Compiler::Safe::object {
   require Safe;
   my $safe = Safe->new('Text::Template::Simple::Dummy');
   $safe->permit(':browse');
   return $safe;
}

":default", "require" and "caller" are enabled opcodes, unless you define your own. You have to disable "strict" option to disable "require" opcode. Disabling "caller" will also make your "require"/"use" calls die in perl 5.9.5 and later.

See Safe and especially Opcode for opcode lists and other details.

stack

This option enables caller stack tracing for templates. The generated list is sent to "warn". So, it is possible to capture this data with a signal handler. See Text::Template::Simple::Caller for available options.

It is also possible to send the output to the template output buffer, if you append ":buffer" to the type of the "stack" option:

$tts = Text::Template::Simple->new(
   stack => 'string:buffer',
);

"html_comment" is the same as "string" except that it also includes HTML comment markers. "text_table" needs the optional module "Text::Table".

This option is also available to all templates as a function named "stack" for individual stack dumping. See Text::Template::Simple::Dummy for more information.

strict

If has a true value, the template will be compiled under strict. Enabled by default.

taint_mode

You need to run your template controller with the "-T" flag enabled. Then you can set various taint mode options.

use Text::Template::Simple::Constants qw(:taint);
my $tmode = TAINT_CHECK_FH_READ;
my $restrict = Text::Template::Simple->new( taint_mode => $tmode );

With the ":taint" key, you'll get access to these constants (bitwise flags):

TAINT_CHECK_NORMAL    * Default
TAINT_CHECK_WINDOWS   Some tests are disabled under Windows OS. Enable them
TAINT_CHECK_FH_READ   FH must only be readable by the current user

To have a more strict taint test:

$tmode = TAINT_CHECK_FH_READ | TAINT_CHECK_WINDOWS;

However, note that this'll cause failures unless file mode is 600. And it will cause failures on Windows. 🙈

verbose_errors

If enabled, you'll get both the parsed structure and a tidied version of it in the error messages. Disabled by default.

warn_ids

If enabled, the module will warn you about compile steps using template ids. You must both enable this and the cache. If cache is disabled, no warnings will be generated.

---

🌟 compile DATA [, FILL_IN_PARAM, OPTIONS] 🌟

Compiles the template you have passed and manages template cache, if you've enabled cache feature. Then it returns the compiled template. Accepts three different types of data as the first parameter; a reference to a filehandle ("GLOB"), a string, or a file path (path to the template file).

First parameter (DATA)

The first parameter can take four different values; a filehandle, a string, a file path, or explicit type definition via an ARRAY reference. Distinguishing filehandles are easy, since they'll be passed as a reference (but see the bareword issue below). So, the only problem is distinguishing strings and file paths. "compile" first checks if the string length is equal or less than 255 characters and then tests if a file with this name exists. If all these tests fail, the string will be treated as the template text.

File paths

You can pass a file path as the first parameter:

$text = $tts->compile('/my/templates/test.tts');

Strings

You can pass a string as the first parameter:

$text = $tts->compile(q~
<%for my $i (0..10) {%>
   counting <%=$i%>...
<%}%>
~);

Filehandles

"GLOB"s must be passed as a reference. If you are using bareword filehandles, be sure to pass it's reference or it'll be treated as a file path and your code will probably "die":

open MYHANDLE, '/path/to/foo.tts' or die "Error: $!";
$text = $tts->compile(\*MYHANDLE); # RIGHT.
$text = $tts->compile( *MYHANDLE); # WRONG. Recognized as a file path
$text = $tts->compile(  MYHANDLE); # WRONG. Ditto. Dies under strict

or use the standard "IO::File" module:

use IO::File;
my $fh = IO::File->new;
$fh->open('/path/to/foo.tts', 'r') or die "Error: $!";
$text = $tts->compile($fh);

or you can use lexicals inside "open" if you don't care about compatibility with older perl:

open my $fh, '/path/to/foo.tts' or die "Error: $!";
$text = $tts->compile($fh);

Filehandles will not be closed. 🫶

Explicit Types

Pass an arrayref containing the type and the parameter to disable guessing and forcing the type:

$text = $tts->compile( [ FILE   => '/path/to/my.tts'] );
$text = $tts->compile( [ GLOB   => \*MYHANDLE] );
$text = $tts->compile( [ STRING => 'I am running under <%= $] %>'] );

Type can be one of these: "FILE", "GLOB", "STRING".

FILL_IN_PARAM

An arrayref. Everything inside this will be accessible from the usual @_ array inside templates.

OPTIONS

A hashref. Several template specific options can be set with this parameter.

id

...and that's where part one of this page runs out — more is coming, bestie, don't go anywhere. 💜

This one controls the cache id generation. Lowkey a slay if you wanna pass in your own template id, fr fr. But if it's false, or you set it to "AUTO", then the internal mechanisms take over and generate the template keys for you. 💅

---

🗝️ map_keys ✨

Enabling this changes how the compiler behaves. Flip it on and you can build templates like this:

This is "<%foo%>", that is "<%bar%>" and the other is "<%baz%>"

Like, only the key names get used instead of full perl constructs. And see how <% is used instead of <%=? That's the vibe. map_keys also disables the usage of perl constructs entirely — only bare words are allowed, and you don't have to fetch parameters via @_ inside the template. Iconic, honestly. Here's an example:

$text = $tts->compile(
         q~This is "<%foo%>", that is "<%bar%>"
           and the other is "<%baz%>"~,
         [
            foo => "blah 1",
            bar => "blah 2",
            baz => "blah 3",
         ],
         {
            map_keys => 1
         },
);

Can be good (and simple) for compiling i18n texts. 🦋 But if you don't use map_keys, that same code above must be written as:

$text = $tts->compile(
         q~<%my(%l) = @_%>This is "<%=$l{foo}%>", that is "<%=$l{bar}%>"
           and the other is "<%=$l{baz}%>"~,
         [
            foo => "blah 1",
            bar => "blah 2",
            baz => "blah 3",
         ],
);

And if map_keys is set to 'init', then the uninitialized values get initialized to an empty string. But beware — 'init' may cloak template errors. It'll silence uninitialized warnings, but it can also make it harder to detect template errors. 😭

If map_keys is set to 'check', then the compiler will check for the key's existence and check if it is defined or not. 👑

🕵️ chkmt 🕵️

If you're using file templates (i.e.: not FH or not string) and you set this to a true value, the modification time of templates will be checked and compared for template change. Basically a vibe check on your files. 🌸

📦 cache 💖

Returns the Text::Template::Simple::Cache object.

🗂️ io 🗂️

Returns the Text::Template::Simple::IO object.

🔌 connector 🔌

Returns the class name of the supplied connector.

🏷️ class_id 🏷️

Returns a class identifier.

---

🧬 CLASS METHODS 🧬

These are all global (i.e.: not local to any particular object). No gatekeeping, they belong to everybody. 🫶

🔍 DEBUG 🔍

Used to enable/disable debugging. Debug information is generated as warnings:

Text::Template::Simple->DEBUG(1); # enable
Text::Template::Simple->DEBUG(0); # disable
Text::Template::Simple->DEBUG(2); # more verbose

DEBUG is disabled by default. ✨

🔐 DIGEST 🔐

Returns the digester object:

$digester = Text::Template::Simple->DIGEST;
print $digester->add($data)->hexdigest;

---

🗄️ CACHE MANAGER ✨

The cache manager has two working modes. It can use disk files or memory for the storage. Memory based cache is far more faster than disk cache. Periodt.

The template text is first parsed and compiled into an anonymous perl sub source. Then a unique key is generated from your source data (you can by-pass the key generation phase if you supply your own id parameter, iykyk).

If in-memory cache is used, the perl source will be compiled into an anonymous sub inside the in-memory cache hash, and this compiled version will be used instead of continiously parsing/compiling the same template. 🔁

If disk cache is used, a template file with the ".tts.cache" extension will be generated on the disk.

Using cache is recommended under persistent environments like mod_perl and PerlEx. 👑

In-memory cache can use two or three times more space than disk-cache, but it is far more faster than disk cache. Disk cache can also be slower than no-cache for small templates, since there is a little overhead when generating unique keys with the DIGESTER and also there will be a disk I/O. There is a modification time check option for disk based templates (see compile). 🫡

---

🧪 DIGESTER 🧪

Cache keys are generated with one of these modules:

Digest::SHA
Digest::SHA1
Digest::SHA2
Digest::SHA::PurePerl
Digest::MD5
MD5
Digest::Perl::MD5

The SHA algorithm seems to be more reliable for key generation, but md5 is widely available and Digest::MD5 is in CORE. So like, SHA is the main character energy pick, md5 is the one that's always in the group chat. 💅

---

🎁 FUNCTIONS 🎁

🫶 tts [ NEW_ARGS, ] COMPILE_ARGS 🫶

This function is a wrapper around the Text::Template::Simple object. It creates it's own temporary object behind the scenes and can be used for quick Perl one-liners for example. Using this function other than testing is not recommended. 🙈

NEW_ARGS is optional and must be a hashref containing the parameters to new. COMPILE_ARGS is a list and everything it contains will be passed to the compile method.

It is possible to import this function to your namespace:

use Text::Template::Simple qw( tts );
print tts("<%= scalar localtime time %>");
print tts( { strict => 1 }, "<%= scalar localtime time %>");

---

⚠️ CAVEATS ⚠️

Taint checking on filehandles have limited tests under Windows. Since file permission is always 0666, g-o read & g-o write tests are disabled under Windows and g-o read taint checking is also disabled by default on all platforms. However, it is possible to force to enable those. See taint_mode for more information.

Heads up bestie: the monolith option can not be used with interpolated includes. You'll need to use the SHARE commad instead to explicitly share variables with includes. Don't fight it, that's just the rules. 💀

---

👀 SEE ALSO 👀

Text::Template::Simple.

---

✍️ AUTHOR ✍️

Burak Gursoy <burak@cpan.org>

---

⚖️ COPYRIGHT AND LICENSE ⚖️

This software is copyright (c) 2004 by Burak Gursoy.

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

---

And that's a wrap, bestie! 💖✨ This page dropped as perl v5.42.0, dated 2025-07-25, and you just read Text::T...ple::API(3) from the User Contributed Perl Documentation. Go forth and template responsibly. 🎀🦋💅