Templa...elocity(3pm)

💖 Templa...elocity(3pm) — the User Contributed Perl Documentation glow-up 💖

okay bestie, welcome to the manual page for Templa...elocity(3pm), aka the Template::Alloy::Velocity era. it's giving "Perl does Velocity but make it make sense." let's get into it ✨

---

🌸 NAME 🌸

Template::Alloy::Velocity — the Velocity (VTL) role. yes, that's it. that's the whole name. iconic. 💅

---

🦋 DESCRIPTION 🦋

so the Template::Alloy::Velocity role hands you both the syntax and the interface for the Velocity Templating Language (VTL). and not just that — it also pulls in a whole bunch of features from the various templating systems out there. it's lowkey a whole buffet. 🍓

if you need config deets and other parameters, go check the Template::Alloy documentation, that's where all of that lives. ✨

and if you want to actually learn the velocity language, these docs right here have more info:

http://velocity.apache.org/engine/devel/vtl-reference-guide.html
http://www.javaworld.com/javaworld/jw-12-2001/jw-1228-velocity.html?page=4

---

🎀 TODO 🎀

Add language usage and samples.

(yes that's the entire TODO section. she's short. she's honest. we respect her. 💀)

---

👑 ROLE METHODS 👑

• parse_tree_velocity — this one gets used by the parse_tree method when SYNTAX is set to 'velocity'. that's her whole job and she does it flawlessly. 💅
• merge — basically process_simple, but with the syntax set to velocity. same energy, different syntax vibe check. ✨

---

💀 UNSUPPORTED VELOCITY SPEC 💀

okay so this is the part where we keep it real: here's everything that Alloy does not do the Java Velocity way. no cap, read this part carefully bestie, it will save you so much confusion. 🫶

• the magic Java Velocity property lookups don't exist. nope, not a thing. you have to use the actual method name — Alloy is not gonna sit there and guess it for you. Java Velocity lets you type $object.Attribute and then it goes hunting for the Attribute, getAttribute, getattribute, isAttribute methods all on your behalf. in Perl Alloy? you can call $object.can('Attribute') to introspect the object yourself. do it manually, queen. 💅
• escaping of variables is consistent. the Java Velocity spec is not. read that again. the velocity spec says that "\\$email" will return "\\$email" if email is not defined, and it will return "\foo" if email is equal to "foo" — the slash behavior magically changes according to the spec, which is giving chaos honestly. in Alloy, the "\\$email" would be "\$email" if email is not defined. consistent. predictable. we love that for us. ✨
• you can set items to null (undefined) in Alloy. according to the Java Velocity reference-guide, you'd have to configure Velocity to make that happen. if you want the other behavior (the non-Alloy one), you'd need to do "#if($questionable)#set($foo=$questionable)#end". and here's the kicker: the default Velocity spec way provides no way for checking null return values. 😭
• there currently isn't a "literal" directive. the VTL reference-guide doesn't even mention #literal, but the user-guide does. in Alloy you can use this instead:

#get('#foreach($a in [1..3]) $a #end')

we'll probably add the literal support at some point — but it will still have to parse the document, so unless you are using compile_perl, you will parse literal sections multiple times. keep that in mind. 🙈

• there is no "$velocityCount". use "$loop.count" instead. periodt. 💅
• in Alloy, excess whitespace outside of the directive matters. the VTL user-guide mentions that all excess whitespace is gobbled up, but Alloy is not out here gobbling anything. Alloy supports the TT chomp operators instead — and these operators go just inside the open and close parenthesis of directives, like so:

#set(~ $a = 1 ~)

• in Alloy, division using "/" is always floating point. always. no exceptions. if you want integer division, use "div". meanwhile in Java Velocity, "/" division is integer only if both numbers are integers. different strokes, bestie. 🔥
• Perl doesn't support negative ranges. sad but true. however, arrays do have the reverse method, so you can absolutely still get where you're going:

#foreach( $bar in [-2 .. 2].reverse ) $bar #end

• in Alloy, arguments to macros are passed by value, not by name. and this is actually super easy to achieve with alloy — you just encase your arguments in single quotes and then eval the argument inside the macro. the velocity people claim this feature as a jealously guarded feature, which is a whole mood honestly. the author's first template system, "WrapEx", had the same feature — and it happened as an accident. it represents lazy software architecture and is difficult to optimize. 💀💀💀 (not the accidental feature becoming a "jealously guarded feature" i'm crying)

---

🌈 AUTHOR 🌈

Paul Seamons <paul@seamons.com> — the main character who made all of this happen. 👑

---

💜 LICENSE 💜

This module may be distributed under the same terms as Perl itself.

---

okay bestie that's the whole page! 🎀 this was written by perl v5.38.2, dated 2024-03-07, and it's part of the Templa...elocity(3pm) / User Contributed Perl Documentation situation. slay, go forth, and remember: division is always floating point. no cap. 💖✨🦋