.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Pinto::Util 3pm"
.TH Pinto::Util 3pm "2022-10-16" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Pinto::Util \- Static utility functions for Pinto
.SH "VERSION"
.IX Header "VERSION"
version 0.14
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a private module for internal use only.  There is nothing for
you to see here (yet).  All \s-1API\s0 documentation is purely for my own
reference.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "throw($message)"
.IX Subsection "throw($message)"
.SS "throw($exception_object)"
.IX Subsection "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.
.ie n .SS "debug( $message )"
.el .SS "debug( \f(CW$message\fP )"
.IX Subsection "debug( $message )"
.SS "debug( sub {...} )"
.IX Subsection "debug( sub {...} )"
Writes the message on \s-1STDERR\s0 if the \f(CW\*(C`PINTO_DEBUG\*(C'\fR environment variable is true.
If the argument is a subroutine, it will be invoked and its output will be
written instead.  Always returns true.
.ie n .SS "whine( $message )"
.el .SS "whine( \f(CW$message\fP )"
.IX Subsection "whine( $message )"
Just calls \fBwarn()\fR, but always appends the newline so that line numbers are
suppressed.
.ie n .SS "author_dir( @base, $author )"
.el .SS "author_dir( \f(CW@base\fP, \f(CW$author\fP )"
.IX Subsection "author_dir( @base, $author )"
Given the name of an \f(CW$author\fR, returns the directory where the
distributions for that author belong (as a Path::Class::Dir).  The
optional \f(CW@base\fR can be a series of Path::Class:Dir or path parts
(as strings).  If \f(CW@base\fR is given, it will be prepended to the
directory that is returned.
.ie n .SS "itis( $var, $class )"
.el .SS "itis( \f(CW$var\fP, \f(CW$class\fP )"
.IX Subsection "itis( $var, $class )"
Asserts whether var is a blessed reference and is an instance of the
\&\f(CW$class\fR.
.ie n .SS "parse_dist_path( $path )"
.el .SS "parse_dist_path( \f(CW$path\fP )"
.IX Subsection "parse_dist_path( $path )"
Parses a path like the ones you would see in a full \s-1URI\s0 to a
distribution in a \s-1CPAN\s0 repository, or the \s-1URI\s0 fragment you would see
in a \s-1CPAN\s0 index.  Returns the author and file name of the
distribution.  Subdirectories between the author name and the file
name are discarded.
.ie n .SS "isa_perl( $path_or_uri )"
.el .SS "isa_perl( \f(CW$path_or_uri\fP )"
.IX Subsection "isa_perl( $path_or_uri )"
Return true if \f(CW$path_or_uri\fR 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.
.ie n .SS "mtime( $file )"
.el .SS "mtime( \f(CW$file\fP )"
.IX Subsection "mtime( $file )"
Returns the last modification time (in epoch seconds) for the \f(CW\*(C`file\*(C'\fR.
The argument is required and the file must exist or an exception will
be thrown.
.ie n .SS "md5( $file )"
.el .SS "md5( \f(CW$file\fP )"
.IX Subsection "md5( $file )"
Returns the \f(CW\*(C`MD\-5\*(C'\fR digest (as a hex string) for the \f(CW$file\fR.  The
argument is required and the file must exist on an exception will be
thrown.
.ie n .SS "sha256( $file )"
.el .SS "sha256( \f(CW$file\fP )"
.IX Subsection "sha256( $file )"
Returns the \f(CW\*(C`SHA\-256\*(C'\fR digest (as a hex string) for the \f(CW$file\fR.  The
argument is required and the file must exist on an exception will be
thrown.
.ie n .SS "validate_property_name( $prop_name )"
.el .SS "validate_property_name( \f(CW$prop_name\fP )"
.IX Subsection "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.
.ie n .SS "validate_stack_name( $stack_name )"
.el .SS "validate_stack_name( \f(CW$stack_name\fP )"
.IX Subsection "validate_stack_name( $stack_name )"
Throws an exception if the stack name is invalid.  Currently, stack
names must be alphanumeric plus underscores or hyphens.
.SS "\fBcurrent_utc_time()\fP"
.IX Subsection "current_utc_time()"
Returns the current time (in epoch seconds) unless the current time has been
overridden by \f(CW$Pinto::Globals::current_utc_time\fR.
.SS "\fBcurrent_time_offset()\fP"
.IX Subsection "current_time_offset()"
Returns the offset between current \s-1UTC\s0 time and the local time in
seconds, unless overridden by \f(CW$Pinto::Globals::current_time_offset\fR.
The \f(CW\*(C`current_time\*(C'\fR function is used to determine the current \s-1UTC\s0
time.
.SS "\fBcurrent_username()\fP"
.IX Subsection "current_username()"
Returns the username of the current user unless it has been overridden by
\&\f(CW$Pinto::Globals::current_username\fR.  The username can be defined through
a number of environment variables.  Throws an exception if no username
can be determined.
.SS "\fBcurrent_author_id()\fP"
.IX Subsection "current_author_id()"
Returns the author id of the current user unless it has been overridden by
\&\f(CW$Pinto::Globals::current_author_id\fR.  The author id can be defined through
environment variables.  Otherwise it defaults to the upper-case form of the
\&\f(CW\*(C`current_username\*(C'\fR.  And since \s-1PAUSE\s0 only allows letters and numbers in the
author id, then we remove all of those from the \f(CW\*(C`current_username\*(C'\fR too.
.SS "\fBis_interactive()\fP"
.IX Subsection "is_interactive()"
Returns true if the process is connected to an interactive terminal
(i.e.  a keyboard & screen) unless it has been overridden by
\&\f(CW$Pinto::Globals::is_interactive\fR.
.SS "interpolate($string)"
.IX Subsection "interpolate($string)"
Performs interpolation on a literal string.  The string should not
include anything that looks like a variable.  Only metacharacters
(like \en) will be interpolated correctly.
.SS "trim_text($string)"
.IX Subsection "trim_text($string)"
Returns the string with all leading and trailing whitespace removed.
.SS "title_text($string)"
.IX Subsection "title_text($string)"
Returns all the characters in \f(CW$string\fR before the first newline.  If
there is no newline, returns the entire \f(CW$string\fR.
.SS "body_text($string)"
.IX Subsection "body_text($string)"
Returns all the characters in \f(CW$string\fR after the first newline.  If
there is no newline, returns an empty string.
.ie n .SS "truncate_text($string, $length, $elipses)"
.el .SS "truncate_text($string, \f(CW$length\fP, \f(CW$elipses\fP)"
.IX Subsection "truncate_text($string, $length, $elipses)"
Truncates the \f(CW$string\fR and appends \f(CW$elipses\fR if the \f(CW$string\fR is
longer than \f(CW$length\fR characters.  \f(CW$elipses\fR defaults to '...' if
not specified.
.SS "decamelize($string)"
.IX Subsection "decamelize($string)"
Returns the string forced to lower case and words separated by underscores.
For example \f(CW\*(C`FooBar\*(C'\fR becomes \f(CW\*(C`foo_bar\*(C'\fR.
.ie n .SS "indent_text($string, $n)"
.el .SS "indent_text($string, \f(CW$n\fP)"
.IX Subsection "indent_text($string, $n)"
Returns a copy of \f(CW$string\fR with each line indented by \f(CW$n\fR spaces.
In other words, it puts \f(CW\*(C`4n\*(C'\fR spaces immediately after each newline
in \f(CW$string\fR.  The original \f(CW$string\fR is not modified.
.ie n .SS "mksymlink($from => $to)"
.el .SS "mksymlink($from => \f(CW$to\fP)"
.IX Subsection "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.
.SS "is_system_prop($string)"
.IX Subsection "is_system_prop($string)"
Returns true if \f(CW$string\fR is the name of a system property.
.SS "\fBuuid()\fP"
.IX Subsection "uuid()"
Returns a \s-1UUID\s0 as a string.  Currently, the \s-1UUID\s0 is derived from
random numbers.
.SS "\fBuser_palette()\fP"
.IX Subsection "user_palette()"
Returns a reference to an array containing the names of the colors pinto
can use.  This can be influenced by setting the \f(CW\*(C`PINTO_PALETTE\*(C'\fR environment
variable.
.SS "is_blank($string)"
.IX Subsection "is_blank($string)"
Returns true if the string is undefined, empty, or contains only whitespace.
.SS "is_not_blank($string)"
.IX Subsection "is_not_blank($string)"
Returns true if the string contains any non-whitespace characters.
.SS "mask_uri_passwords($string)"
.IX Subsection "mask_uri_passwords($string)"
Masks the parts the string that look like a password embedded in an http or
https \s-1URI.\s0 For example, \f(CW\*(C`http://joe:secret@foo.com\*(C'\fR would return
\&\f(CW\*(C`http://joe:*password*@foo.com\*(C'\fR
.SS "is_remote_repo {"
.IX Subsection "is_remote_repo {"
Returns true if the argument looks like a \s-1URI\s0 to a remote repository
.SH "AUTHOR"
.IX Header "AUTHOR"
Jeffrey Ryan Thalhammer <jeff@stratopan.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2015 by Jeffrey Ryan Thalhammer.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.