--- name: "Pinto::Util" section: "3pm" platform: "linux" package: "pinto" version: "0.14000-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Pinto::Util" --- # Pinto::Util(3pm) Static utility functions for Pinto ## NAME Pinto::Util - Static utility functions for Pinto ## VERSION version 0.14 ## DESCRIPTION This is a private module for internal use only. There is nothing for you to see here (yet). All API documentation is purely for my own reference. ## FUNCTIONS ### throw($message) ### throw($exception\_object) Throws a Pinto::Exception with the given message. If given a reference to a Pinto::Exception object, then it just throws it again. ### debug( $message ) ### debug( sub {...} ) Writes the message on STDERR if the `"PINTO_DEBUG"` environment variable is true. If the argument is a subroutine, it will be invoked and its output will be written instead. Always returns true. ### whine( $message ) Just calls **warn()**, but always appends the newline so that line numbers are suppressed. ### author\_dir( @base, $author ) Given the name of an `$author`, returns the directory where the distributions for that author 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 will be prepended to the directory that is returned. ### itis( $var, $class ) Asserts whether var is a blessed reference and is an instance of the `$class`. ### parse\_dist\_path( $path ) Parses a path like the ones you would see in a full URI to a distribution in a CPAN repository, or the URI fragment you would see in a CPAN index. Returns the author and file name of the distribution. Subdirectories between the author name and the file name are discarded. ### isa\_perl( $path\_or\_uri ) Return true if `$path_or_uri` appears to point to a release of perl itself. This is based on some file naming patterns that I've 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. ### md5( $file ) Returns the `"MD-5"` digest (as a hex string) for the `$file`. The argument is required and the file must exist on an exception will be thrown. ### sha256( $file ) Returns the `"SHA-256"` digest (as a hex string) for the `$file`. The argument is required and the file must exist on an exception will be thrown. ### 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. ### validate\_stack\_name( $stack\_name ) Throws an exception if the stack name is invalid. Currently, stack names must be alphanumeric plus underscores or hyphens. ### 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 overridden by `$Pinto::Globals::current_time_offset`. The `"current_time"` function is used to determine the current UTC time. ### current\_username() Returns the username of the current user unless it has 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 has 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, then 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 has 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. ### title\_text($string) Returns all the characters in `$string` before the first newline. If there is no newline, returns the entire `$string`. ### body\_text($string) Returns all the characters in `$string` after the first newline. If there is no newline, 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 not specified. ### decamelize($string) Returns the string forced to lower case and 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. ### 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 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 ## AUTHOR Jeffrey Ryan Thalhammer \ ## 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.