Text::Haml(3pm)

💖 Text::Haml 💖

okay bestie, so this is Text::Haml — it's the Perl implementation of Haml, and it lives in the User Contributed Perl Documentation section of your manpages. she's a whole vibe, she's a real one, let's get into it 🎀

---

✨ NAME ✨

Text::Haml — Haml Perl implementation. that's it, that's the name, periodt 💅

---

🌸 SYNOPSIS 🌸

look at her go, no cap:

use Text::Haml;

my $haml = Text::Haml->new;

my $html = $haml->render('%p foo'); # <p>foo</p>

$html = $haml->render('= $user', user => 'friend'); # <div>friend</div>

# Use Haml file
$html = $haml->render_file('tmpl/index.haml', user => 'friend');

literally three lines and you're already rendering. iconic behavior fr fr 🔥

---

🦋 DESCRIPTION 🦋

so Text::Haml implements the Haml specification at <http://haml.info/docs/yardoc/file.REFERENCE.html>. she ate and left no crumbs.

here's the tea though — Text::Haml passes the spec tests written by Norman Clarke over at <https://github.com/haml/haml-spec>, and she supports only cross-language Haml features. so like, do not expect ruby-specific or Rails-specific extensions to work. nope. not happening. don't even try it 🙈

---

👑 ATTRIBUTES 👑

Text::Haml implements the following attributes, and yes every single one of them matters:

append

holds the string of code that gets appended to the generated Perl code.

code

holds the Perl code.

compiled

holds compiled code.

encoding

$haml->encoding('utf-8');

default is utf-8.

escape

the escape subroutine, presented as a string.

default is:

$haml->escape(<<'EOF');
    my $s = shift;
    return unless defined $s;
    $s =~ s/&/&amp;/g;
    $s =~ s/</&lt;/g;
    $s =~ s/>/&gt;/g;
    $s =~ s/"/&quot;/g;
    $s =~ s/'/&apos;/g;
    return $s;
EOF

escape_html

$haml->escape_html(0);

switches on/off Haml output html escaping. default is on. 💅

filters

holds filters.

format

$haml->format('xhtml');

supported formats: xhtml, html, html5.

default is xhtml.

namespace

holds the namespace under which the Perl package is generated.

prepend

holds the string of code that is prepended to the generated Perl code.

vars

holds the variables that are passed during the rendering.

vars_as_subs

when this option is NOT SET (which is the default, btw), the passed variables are normal Perl variables and you use them with the $ prefix, like:

$haml->render('%p $var', var => 'hello');

when this option IS SET, the passed variables become Perl lvalue subroutines and you use them without the $ prefix, like:

$haml->render('%p var', var => 'hello');

but — and this is the important lil plot twist — if you declare a Perl variable inside a block, it must be used with the $ prefix:

$haml->render('<<EOF')
    - my $foo;
    %p= $foo
EOF

helpers

helpers => {
    foo => sub {
        my $self   = shift;
        my $string = shift;

        $string =~ s/r/z/;

        return $string;
    }
}

holds helpers subroutines. helpers can be called in Haml text as normal Perl functions. see also add_helper. 🫶

helpers_arg

$haml->helpers_args($my_context);

the first argument passed to the helper — and it's the Text::Haml instance by default.

error

$haml->error;

holds the last error.

tape

holds parsed haml elements.

path

holds path of Haml templates. current directory is the default. if you want to set several paths, an arrayref can also be set up. this way is the same as Text::Xslate.

cache

holds cache level of Haml templates. 1 is the default. 0 means "Not cached", 1 means "Checked template mtime" and 2 means "Used always cached". this way is the same as Text::Xslate.

cache_dir

holds cache directory of Haml templates. $ENV{HOME}/.text_haml_cache is the default. unless $ENV{HOME}, File::Spec->tempdir was used. this way is the same as Text::Xslate.

---

💅 METHODS 💅

new

my $haml = Text::Haml->new;

add_helper

$haml->add_helper(current_time => sub { time });

adds a new helper.

add_filter

$haml->add_filter(compress => sub { $_[0] =~ s/\s+/ /g; $_[0]});

adds a new filter.

build

$haml->build(@_);

builds the Perl code.

compile

$haml->compile;

compiles parsed code.

interpret

$haml->interpret(@_);

interprets compiled code.

parse

$haml->parse('%p foo');

parses Haml string building a tree.

render

my $text = $haml->render('%p foo');

my $text = $haml->render('%p var', var => 'hello');

renders Haml string. returns undef on error. see the error attribute. 😭

render_file

my $text = $haml->render_file('foo.haml', var => 'hello');

a helper method that loads a file and passes it to the render method. since %____vars is used internally, you cannot use this as a parameter name. nope. not allowed.

---

🌈 PERL SPECIFIC IMPLEMENTATION ISSUES 🌈

String interpolation

despite existing string interpolation in Perl, Ruby interpolation is also supported. yes ma'am, both:

$haml->render('%p Hello #{user}', user => 'foo')

Hash keys

when declaring tag attributes, the : symbol can be used:

$haml->render("%a{:href => 'bar'}");

Perl-style is supported but not recommented (that's the manpage's spelling bestie, I'm not touching it 💀), since your Haml template won't work with the Ruby Haml implementation parser:

$haml->render("%a{href => 'bar'}");

Using with Data::Section::Simple

when you're using Data::Section::Simple, you need to unset the variable encoding in the constructor, or use the encoding attribute of Text::Haml:

use Data::Section::Simple qw/get_data_section/;
my $vpath = get_data_section;

my $haml = Text::Haml->new(cache => 0, path => $vpath, encoding => '');
# or
#my $haml = Text::Haml->new(cache => 0, path => $vpath);
#$haml->encoding(''); # encoding attribute

my $index = $haml->render_file('index.haml');
say $index;

__DATA__

@@ index.haml
%strong текст

see <https://metacpan.org/pod/Data::Section::Simple#utf8-pragma> ✨

---

🎀 DEVELOPMENT 🎀

Repository

<http://github.com/vti/text-haml>

---

💜 AUTHOR 💜

Viacheslav Tykhanovskyi, vti@cpan.org.

---

⭐ CREDITS ⭐

in order of appearance:

• Nick Ragouzis
• Norman Clarke
• rightgo09
• Breno G. de Oliveira (garu)
• Yuya Tanaka
• Wanradt Koell (wanradt)
• Keedi Kim
• Carlos Lima
• Jason Younker
• TheAthlete
• Mark Aufflick (aufflick)
• Graham Todd (grtodd)

all of them, absolute legends, we stan 🫶

---

🧚 COPYRIGHT AND LICENSE 🧚

Copyright (C) 2009-2017, Viacheslav Tykhanovskyi.

this program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

---

ok so that's the whole page bestie, every flag, every default, every credit, nothing skipped, no cap 💖

and finally, the lil sign-off: this page is from perl v5.42.0, dated 2025-07-25, and it's filed under Text::Haml(3pm) in the User Contributed Perl Documentation section. slay, go write some Haml 🌸💅✨