Pinto::Util(3pm)

🌸 Pinto::Util 🌸

okay bestie, welcome to Pinto::Util(3pm) — yes that's the manual name, section 3pm, and yeah we're in User Contributed Perl Documentation territory. this page is the whole vibe check on Pinto's static utility functions. grab a snack. 🍓

---

✨ NAME ✨

Pinto::Util — static utility functions for Pinto 💅

---

🎀 VERSION 🎀

version 0.14 — that's the one, no cap.

---

🦋 DESCRIPTION 🦋

okay so. real talk. this is a private module for internal use only. like, there is nothing for you to see here (yet). 🙈

all the API documentation on this page? it's purely for the author's own reference. so if you're here just vibing and reading, that's iconic of you, but this is very much iykyk territory. 👑

---

💖 FUNCTIONS 💖

throw($message)

throw($exception_object)

throws a Pinto::Exception with the message you handed it. and if you hand it a reference to a Pinto::Exception object instead? it just throws that thing again. re-throw slay. 🔥

debug( $message )

debug( sub {...} )

writes your message onto STDERR, but only if the PINTO_DEBUG environment variable is true. if the argument is a subroutine, it gets invoked and its output gets written instead. always returns true. periodt. ✨

whine( $message )

literally just calls warn(), except it always appends the newline so that line numbers are suppressed. it's giving dramatic but tidy. 😭

author_dir( @base, $author )

give it an $author name and it returns the directory where that author's distributions belong — as a Path::Class::Dir. the optional @base can be a series of Path::Class:Dir or path parts (as strings). if @base is given, it gets prepended to the directory that's returned. 🫶

itis( $var, $class )

asserts whether $var is a blessed reference and an instance of $class. it's the vibe check. 🌈

parse_dist_path( $path )

parses a path like the ones you'd see in a full URI to a distribution in a CPAN repository, or the URI fragment you'd see in a CPAN index. returns the author and file name of the distribution. any subdirectories sitting between the author name and the file name get discarded. bye. 💅

isa_perl( $path_or_uri )

returns true if $path_or_uri looks like it points to a release of perl itself. this is based on some file naming patterns the author has seen in the wild. it may not be completely accurate. 🫠

mtime( $file )

returns the last modification time (in epoch seconds) for the file. the argument is required, and the file must exist or an exception will be thrown. no file, no time. 💀

md5( $file )

returns the MD-5 digest (as a hex string) for the $file. argument is required, and the file must exist or an exception will be thrown. 🧚

sha256( $file )

returns the SHA-256 digest (as a hex string) for the $file. argument is required, and the file must exist or an exception will be thrown. she's fancy. 👑

validate_property_name( $prop_name )

throws an exception if the property name is invalid. currently, property names must be alphanumeric plus any underscores or hyphens. that's the rule, bestie. 🎀

validate_stack_name( $stack_name )

throws an exception if the stack name is invalid. currently, stack names must be alphanumeric plus underscores or hyphens. same energy, different noun. ✨

current_utc_time()

returns the current time (in epoch seconds), unless the current time has been overridden by $Pinto::Globals::current_utc_time. 🕰️

current_time_offset()

returns the offset between current UTC time and the local time, in seconds — unless it's been overridden by $Pinto::Globals::current_time_offset. note that the current_time function is what's used to determine the current UTC time. 🌍

current_username()

returns the username of the current user, unless it's been overridden by $Pinto::Globals::current_username. the username can be defined through a number of environment variables. throws an exception if no username can be determined. 😤

current_author_id()

returns the author id of the current user, unless it's been overridden by $Pinto::Globals::current_author_id. the author id can be defined through environment variables. otherwise it defaults to the upper-case form of the current_username. and since PAUSE only allows letters and numbers in the author id, we remove all of those from the current_username too. 😌

is_interactive()

returns true if the process is connected to an interactive terminal (i.e. a keyboard & screen) — unless it's been overridden by $Pinto::Globals::is_interactive. 👩‍💻

interpolate($string)

performs interpolation on a literal string. the string should not include anything that looks like a variable. only metacharacters (like \n) will be interpolated correctly. 🪄

trim_text($string)

returns the string with all leading and trailing whitespace removed. fresh and clean. 🧼

title_text($string)

returns all the characters in $string before the first newline. if there's no newline, it returns the entire $string. 📝

body_text($string)

returns all the characters in $string after the first newline. if there's no newline, it returns an empty string. 🌙

truncate_text($string, $length, $elipses)

truncates the $string and appends $elipses if the $string is longer than $length characters. $elipses defaults to '...' if you don't specify it. ✂️

decamelize($string)

returns the string forced to lower case with words separated by underscores. for example, "FooBar" becomes "foo_bar". 🐪➡️🐍

indent_text($string, $n)

returns a copy of $string with each line indented by $n spaces. in other words, it puts "4n" spaces immediately after each newline in $string. the original $string is not modified. 🛋️

mksymlink($from => $to)

creates a symlink between the two files. no checks are performed to see if either path is valid or already exists. throws an exception if the operation fails or is not supported. 🔗

fr fr, read that again: no checks. she will simply try. be careful out there. 💀

is_system_prop($string)

returns true if $string is the name of a system property. ⚙️

uuid()

returns a UUID as a string. currently, the UUID is derived from random numbers. 🎲

user_palette()

returns a reference to an array containing the names of the colors pinto can use. this can be influenced by setting the PINTO_PALETTE environment variable. 🎨

is_blank($string)

returns true if the string is undefined, empty, or contains only whitespace. 🫥

is_not_blank($string)

returns true if the string contains any non-whitespace characters. 🌟

mask_uri_passwords($string)

masks the parts of the string that look like a password embedded in an http or https URI. for example, "http://joe:secret@foo.com" would return "http://joe:*password*@foo.com". 🕵️‍♀️

is_remote_repo

returns true if the argument looks like a URI to a remote repository. 🌐

(tiny note: in the original page this one is written as is_remote_repo { — stray curly brace and all. we love a typo, we're keeping the receipts. 🙈)

---

👑 AUTHOR 👑

Jeffrey Ryan Thalhammer <jeff@stratopan.com> — the icon, the legend, the whole main character. 💜

---

📜 COPYRIGHT AND LICENSE 📜

this software is copyright (c) 2015 by Jeffrey Ryan Thalhammer.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 🫶

---

and that's the whole page, bestie!! perl v5.40.1, dated 2025-04-21 — catch you on the next Pinto::Util(3pm) read. mwah. 💖✨🎀