HTML::...:Tools(3pm)

💖 NAME 💖

HTML::Mason::Tools — it's the function library that Mason uses internally, bestie. ✨

Like, this whole page lives under the HTML::Mason::Tools(3pm) manual, in the User Contributed Perl Documentation corner of the universe, and it's your girl's guide to the little helper squad that keeps Mason running. 💅

---

🌸 DESCRIPTION 🌸

Okay so, this module is basically a backpack full of exportable functions that are meant to be used by other Mason modules. It's the support crew, not the main character. 🫶

The docs in here are primarily written for Mason core developers. iykyk.

And listen — if you're not a core dev and you still wanna roll up and use these functions? Do it at your own risk. 😭 They may change from release to release. You have been warned. Consider this your vibe check. ⚠️

---

✨ FUNCTIONS ✨

🎀 read_file

Hand it a file name, plus an optional argument that says whether or not to open the final in binary mode. It hands you back the entire contents of the file as a scalar. Whole thing. All of it. 💖

🦋 paths_eq

Given two paths, this one tells you whether they represent the same location on the filesystem. 👀

Heads up: it does not account for symlinks. So don't come for it about that. 💀

🌈 compress_path

Takes a component path and turns it into a filesystem-friendly path by escaping the characters that could otherwise be potentially meaningful. It's giving ✨path glow-up✨.

⭐ absolute_comp_path

Give it a component path and a directory path, and it returns the absolute component path — prepending the directory path if that's what's needed. 🔥

🧚 mason_canonpath

This one cleans up a component path and returns its canonical version. It's largely the same as File::Spec::Unix::canonpath, with a few additional cleanups sprinkled on top. Same energy, extra sparkle. 💅

💜 pkg_installed

Give it a module name and it returns true or false to tell you whether or not a corresponding .pm file exists. Simple. Iconic. 👑

🌸 pkg_loaded

Give it a module name and it returns true or false to tell you whether or not the module has actually been loaded into memory. Not just "does it exist", but "is it here right now". 🫶

💖 load_pkg

Give it a module name and it attempts to load it. It also takes an additional boolean parameter that says whether or not to throw an exception if the module can't be found. By default, if the module cannot be found, this function just simply returns false.

Not me — all errors generate exceptions no matter what. Every single time. No exceptions to the exceptions. 😤

If the module is loaded successfully, this function returns true. Slay. ✨

🎀 taint_is_on

Returns a boolean value indicating whether taint mode is on or not. On or off, that's the whole tea. 🍓

🌈 coerce_to_array

Give it a scalar, which may be a reference, and this function attempts to return an array. If that can't be done, it throws an HTML::Mason::Exception::Params exception. 🚨

This function is called from the generated component code as part of a component's argument handling. So it's lowkey doing important work. 💅

⭐ coerce_to_hash

Same deal, different container: give it a scalar, which may be a reference, and it attempts to return a hash. If that can't be done, it throws an HTML::Mason::Exception::Params exception. 🚨

This function is also called from the generated component code as part of a component's argument handling. Twin behavior, twin icon energy. 👯

🧚 checksum

Computes a simple checksum of a string. Used for Compiler::object_id. That's it, that's the function. Short, sweet, essential. 💖

---

And that's the whole page, bestie — no cap. 🎀 This gem came to you as perl v5.38.2, dated 2024-03-05, under the HTML::...:Tools(3pm) banner. Go forth and use these functions at your own risk, mwah. 💅✨