Templat...::Simple(3)

📦
version 0.31 · 2 versions
, in fedora 43

✨ Templat...::Simple ✨ (the Template::Toolkit::Simple man page, bestie 💖)

okay so this is the User Contributed Perl Documentation page for Template::Toolkit::Simple and honestly? it's giving "Template Toolkit but make it not annoying". buckle up 🎀

🌸 NAME 🌸

Template::Toolkit::Simple — A Simple Interface to Template Toolkit

✨ SYNOPSIS ✨

use Template::Toolkit::Simple;

print tt
    ->path(['./', 'template/'])
    ->data('values.yaml')
    ->post_chomp
    ->render('foo.tt');

or, if you're a terminal girlie, from the command line:

tt-render --path=./:template/ --data=values.yaml --post-chomp foo.tt

💅 DESCRIPTION 💅

okay so real talk: Template Toolkit is the best Perl template framework. periodt. the only problem — and it's lowkey a big one — is that using it for simple stuff is a little bit cumbersome. 🙈 and also there's no good utility for using it from the command line. tragic.

so this module is a simple wrapper around Template Toolkit. it exports a function called tt which returns a new Template::Toolkit::Simple object. the object supports method calls for setting all the Template Toolkit options. all of them. we don't gatekeep. 👑

this module also installs a program called tt-render which you can use from the command line to render templates with all the power of the Perl object. every single object method becomes a command line argument in the command line version. iconic behaviour tbh.

🖥️ COMMAND LINE USAGE 🖥️

this command renders the named file and prints the output to STDOUT. if an error occurs, it's printed to STDERR. no cap.

tt-render [template-options] file-name

🛤️ TEMPLATE PATH 🛤️

when you're using Template::Toolkit::Simple or tt-render, the most common parameters you'll reach for are the main template file name and the directory of supporting templates. and as a lil convenience, you can specify these together. cute, right? 🎀

this:

tt->render('foo//bar/baz.tt');
> tt-render foo//bar/baz.tt  # command line version

is the same as:

tt->include_path('foo/')->render('bar/baz.tt');
> tt-render --include_path=foo/ bar/baz.tt  # command line version

just use a double slash to separate the path from the template. and this is extra handy on the command line, because (at least in Bash) tab completion still works after you specify the '//'. slay 💅

🎁 EXPORTED SUBROUTINES 🎁

  • tt — simply returns a new Template::Toolkit::Simple object. this is Simple sugar for:
Template::Toolkit::Simple->new();

it takes no parameters. zero. none. it's just vibes.

🌈 METHODS 🌈

this section describes the methods that are not option-setting methods. those ones are described below, bestie, don't worry.

  • new() — return a new Template::Toolkit::Simple object. takes no parameters.
  • render($template, $data); — this is the method that actually renders the template. it's similar to the Template Toolkit process method, except that it actually returns the template result as a string. and it returns undef if an error occurs. 😭

the $data field is optional and can be set with the data method.

if you need more control, see the process command below:

  • process($template, $data, $output, %options); — this command is simply a proxy to the Template Toolkit process command. all the parameters you give it are passed to the real process command and the result is returned. see Template for more information. 👀
  • output($filepath) — specify a filepath to print the template result to.
  • error() — this method is a proxy to the Template Toolkit error method. it returns the error message if there was an error.

👑 OPTION METHODS 👑

all of the Template Toolkit options are available as methods to Template::Toolkit::Simple objects, and also as command line options to the tt- render command.

for example, the POST_CHOMP options is available in the following ways:

tt->post_chomp      # turn POST_CHOMP on
tt->post_chomp(1)   # turn POST_CHOMP on
tt->post_chomp(0)   # turn POST_CHOMP off

--post_chomp        # turn POST_CHOMP on
--post-chomp        # same. use - instead of _
--post_chomp=1      # turn POST_CHOMP on
--post_chomp=0      # turn POST_CHOMP off

if the method functionality is not explained below, please refer to Template. iykyk 💜

  • config($file_name || $hash) — if you have a common set of Template Toolkit options stored in a file, you can use this method to read and parse the file, and set the appropriate options.

the currently supported file formats are YAML, JSON and XML. the format is determined by the file extension, so use the appropriate one. note that XML::Simple is used to parse XML files and JSON::XS is used to parse JSON files.

  • data($file_name || $hash) — most templates use a hash object of data to access values while rendering. you can specify this data in a file or with a hash reference.

the currently supported file formats are YAML, JSON and XML. the format is determined by the file extension, so use the appropriate one. note the XML::Simple is used to parse XML files.

  • include_path($template_directories) — default is undef

this method allows you to specify the directories that are searched to find templates. you can specify this as a string containing a single directory, an array ref of strings containing directory names, or as a string containing multiple directories separated by ':'. so many options, we love flexibility 🦋

  • path() — default is undef

this is a shorter name for include_path. it does the exact same thing. literally the same.

  • start_tag() — default is '[%'
  • end_tag() — default is '%]'
  • tag_style() — default is 'template'
  • pre_chomp() — default is 0
  • post_chomp() — default is 0
  • trim() — default is 0
  • interpolate() — default is 0
  • anycase() — default is 0
  • delimiter() — default is ':'
  • absolute() — default is 0
  • relative() — default is 0
  • strict() — default is 0
  • default() — default is undef
  • blocks() — default is undef
  • auto_reset() — default is 1
  • recursion() — default is 0
  • eval_perl() — default is 0
  • pre_process() — default is undef
  • post_process() — default is undef
  • process_template() — default is undef

this is a proxy to the Template Toolkit PROCESS option. the process method is used to actually process a template.

  • error_template() — default is undef

this is a proxy to the Template Toolkit ERROR option. the error() method returns the error message on a failure.

  • debug() — default is 0
  • cache_size() — default is undef
  • compile_ext() — default is undef
  • compile_dir() — default is undef
  • encoding() — default is 'utf8'

💖 AUTHOR 💖

Ingy döt Net <ingy@cpan.org>

Copyright 2008-2014. Ingy döt Net.

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

See <http://www.perl.com/perl/misc/Artistic.html>

and that's the whole page, bestie!! 🫶 this doc was served up by perl v5.42.0 on 2025-07-25, and it's page 3 of the Templat...::Simple manual. go render something cute ✨🌸

📦 where this page comes from