Sympa::Template(3Sympa)

💖 NAME 💖

Sympa::Template — the template parser, bestie. This is the manual page for sympa 6.2.80, and it's literally the glow-up machine for your text files. 💅

🌸 SYNOPSIS 🌸

use Sympa::Template;

$template = Sympa::Template->new;
$template->parse($data, $tpl_file, \$output);

🦋 DESCRIPTION 🦋

Okay so this is the whole vibe. Sympa::Template is the parser that makes templates happen. Let's break it down, no cap.

👑 Methods 👑

new ( $that, [ property defaults ] )

Constructor. Creates a new Sympa::Template instance. It's giving "fresh start" energy.

Parameters:

• $that — Context. Site, Robot or List. Basically where you're at.
• property defaults — Pairs to specify property defaults. Periodt.

parse ( $data, $tpl, $output, [ has_header => 1 ] )

Instance method. Parses template and outputs result. The main character move.

Parameters:

• $data — A HASH ref containing the data. All the tea.
• $tpl — A string that contains the file name. Or, scalarref or arrayref that contains the template. Flexible, we love to see it.
• $output — A file descriptor or a reference to scalar for the output. Where the magic lands.
• has_header => 0|1 — If 1 is set, prepended header fields are assumed, i.e. one newline will be inserted at beginning of output. Lowkey important.
• is_not_template => 0|1 — This option was obsoleted. RIP boo, you had your moment. 💀

Returns:

On success, returns 1 and clears {last_error} property. Otherwise returns undef and sets {last_error} property. So if it's not slaying, check last_error.

💅 Properties 💅

Instance of Sympa::Template may have following attributes. These are the vibes it carries.

• {allow_absolute} — If set, absolute paths in INCLUDE directive are allowed. Letting it be free.
• {include_path} — Reference to array containing additional template search paths. Extra spots to look.
• {last_error} — Read only. Error occurred at the last execution of parse, or undef. The receipts.
• {subdir}, {lang}, {lang_only} — TBD. Not me leaving you on read, it's literally TBD.

🎀 Filters 🎀

These custom filters are defined by Sympa::Template. See Template::Manual::Filters about usage of filters. Okay so there are SO many, let's go.

canonic_email

Canonicalize e-mail address. Making it all neat and proper.

This filter was added by Sympa 6.2.17.

decode_utf8

No longer used. She's retired, respect her legacy. 🫶

encode_utf8

No longer used. Same energy.

escape_cstr

Applies C-style escaping of a string (not enclosed by quotes). Getting all escape-y.

This filter was added on Sympa 6.2.37b.1.

escape_quote

Escape quotation marks. The O.G. way.

Deprecated. Use escape_cstr. Like, please upgrade bestie.

escape_url

Escapes URL. Putting it in a safe little bubble.

This was OBSOLETED. Use mailtourl instead. The glow-up.

escape_xml

OBSOLETED. Use xml in Template::Manual::Filters. Moving on.

helploc ( parameters )

l ( parameters )

loc ( parameters )

Translates text using catalog. Placeholders (%1, %2, ...) are replaced by parameters. i18n girlies rise.

locdt ( argument )

Generates formatted (i18n'ized) date/time. Giving timezone realness.

• Filtered text — strftime() style format string. Your format, your rules.
• argument — A string representing date/time: "YYYY/MM", "YYYY/MM/DD", "YYYY/MM/DD/HH/MM" or "YYYY/MM/DD/HH/MM/SS". Pick your level of detail.

mailbox ( email, [ comment ] )

Generates mailbox string appropriately encoded to suit for addresses in header fields. Making email headers fashion.

• Filtered text — Display name, if any. The name tag.
• email — E-mail address. The @.
• comment — Comment, if any. Extra notes.

This filter was introduced on Sympa 6.2.42.

mailto ( email, [ {key => val, ...}, [ nodecode ] ] )

Generates HTML fragment linking to mailto: URL, i.e. <a href="mailto:email">filtered text</a>. Clickable cuteness.

• Filtered text — Content of linking element. If it does not contain nonspaces, e-mail address will be used. So if it's empty, email takes over.
• email — E-mail address(es) to be linked. Who we're linking.
• {key => val, ...} — Optional query. Extra params.
• nodecode — If true, assumes arguments are not encoded as HTML entities. By default entities are decoded at first. This option does not affect filtered text. Setting boundaries.

Note: This filter was introduced by Sympa 6.2.14.

mailtourl ( [ {key = val, ...} ] )

Generates mailto: URL. Just the URL, no fluff.

• Filtered text — E-mail address(es). Note that any characters must not be encoded as HTML entities. Keep it raw.
• {key = val, ...} — Optional query. Note that any characters must not be encoded as HTML entities. Same rule.

Note: This filter was introduced by Sympa 6.2.14.

obfuscate ( mode )

Obfuscates email addresses in the HTML text according to mode. Keeping it lowkey.

• Filtered text — HTML document or fragment. The thing being hidden.
• mode — Obfuscation mode. "at" or "javascript". Invalid mode will be silently ignored. No drama, just ignore.

Note: This filter was introduced by Sympa 6.2.14.

optdesc ( type, withval )

Generates i18n'ed description of list parameter value. Translating the deets.

As of Sympa 6.2.17, if it is called by the web templates (in web_tt2 subdirectories), special characters in result will be encoded. Glow-up.

• Filtered text — Parameter value. What we're describing.
• type — Type of list parameter value: Special types (See field_type in Sympa::ListDef) or others (default). Categorize it.
• withval — If parameter value is added to the description. False by default. Optional flex.

permalink_id

Calculate permalink ID from message ID. Forever linking.

Note: This filter was introduced by Sympa 6.2.71b.

qencode

Encode string by MIME header encoding. Despite its name, appropriate encoding scheme ("Q" or "B") will be chosen. The name is a red herring, it's smart.

unescape

No longer used. Ghosted. 👻

url_abs ( ... )

Same as url_rel but gives absolute URI. Full address energy.

Note: This filter was introduced by Sympa 6.2.15.

url_rel ( [ paths, [ query, [ fragment ] ] ] )

Gives relative URI for specified action. The short version.

If it is called by the web templates (in web_tt2 subdirectories), HTML entities in the arguments will be decoded and special characters in resulting URL will be encoded. Web template magic.

• Filtered text — Name of action. What's happening.
• paths — Array. Additional path components. Extra path bits.
• query — Hash. Optional query. Params.
• fragment — Scalar. Optional fragment. The # part.

Note: This filter was introduced by Sympa 6.2.15.

wrap ( init, subs, cols )

Generates folded text. Making it fit.

• init — Indentation (or its length) of each paragraph if any. First line indent.
• subs — Indentation (or its length) of other lines if any. Other lines indent.
• cols — Line width, defaults to 78. How wide.

Note:

Calls of helploc, loc and locdt in template files are extracted during packaging process and are added to translation catalog. So they're special, iykyk.

🌈 Plugins 🌈

Plugins may be placed under LIBDIR/Sympa/Template/Plugin. See <https://www.sympa.community/manual/customize/template-plugins.html> about usage of plugins. Get into it.

👀 SEE ALSO 👀

Template::Manual. That's the one.

📜 HISTORY 📜

• Sympa 4.2b.3 adopted template engine based on Template Toolkit. The origin story.
• Plugin feature was added on Sympa 6.2. The upgrade.
• tt2 module was renamed to Sympa::Template on Sympa 6.2. The rebrand, we love a rebrand.

---

This manual page was brought to you by sympa 6.2.80, dated 2026-10-19. Stay slaying, bestie. 💖✨