.\" 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 "Arch::Util 3pm"
.TH Arch::Util 3pm "2022-06-08" "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"
Arch::Util \- Arch utility functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Arch::Util qw(run_tla load_file save_file setup_config_dir);
\&
\&    my $abrowse_output = run_tla(\*(Aqabrowse \-\-summary \-\-date \-\-creator\*(Aq);
\&    my ($full_version) = run_tla(\*(Aqtree\-version\*(Aq);
\&    my @full_revisions = run_tla(\*(Aqlogs\*(Aq, \*(Aq\-r\*(Aq, \*(Aq\-f\*(Aq);
\&
\&    my $cfg_dir = setup_config_dir(undef, "archipelago");
\&    my $content = load_file("$cfg_dir/versions.cfg");
\&    $content =~ s/^last_version = .*/last_version = $full_version/m;
\&    save_file("$cfg_dir/versions.cfg", $content);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A set of helper functions suitable for \s-1GNU\s0 Arch related projects in Perl.
.PP
Higher (object oriented) levels of Arch/Perl library make use of these
helper functions.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
The following functions are available:
.PP
\&\fBrun_tla\fR,
\&\fBrun_cmd\fR,
\&\fBrun_pipe_from\fR,
\&\fBload_file\fR,
\&\fBsave_file\fR,
\&\fBcopy_dir\fR,
\&\fBremove_dir\fR,
\&\fBsetup_config_dir\fR,
\&\fBstandardize_date\fR,
\&\fBdate2daysago\fR,
\&\fBdate2age\fR,
\&\fBparse_creator_email\fR,
\&\fBadjacent_revision\fR.
.PP
The system functions die on errors.
.IP "\fBis_tla_functional\fR" 4
.IX Item "is_tla_functional"
Verify whether the system has a working arch backend installed (and
possibly configured by environment variables, like \s-1TLA\s0 or \s-1ARCH_BACKEND\s0),
needed for this perl library to function.
.IP "\fBrun_tla\fR \fIsubcommand_with_args\fR" 4
.IX Item "run_tla subcommand_with_args"
.PD 0
.IP "\fBrun_tla\fR \fIsubcommand\fR arg ..." 4
.IX Item "run_tla subcommand arg ..."
.PD
Run the given \fItla\fR subcommand with optional arguments. Return the tla
output in the scalar context, and a list of \fBchomp\fR\-ed lines in the list
context.
.IP "\fBrun_cmd\fR \fIshell_command_with_args\fR" 4
.IX Item "run_cmd shell_command_with_args"
.PD 0
.IP "\fBrun_cmd\fR \fIshell_command\fR \fIarg\fR ..." 4
.IX Item "run_cmd shell_command arg ..."
.PD
Run the given shell command (like \fIwc\fR or \fIawk\fR) with optional arguments.
Return the command output in the scalar context, and a list of \fBchomp\fR\-ed
lines in the list context.
.Sp
\&\fBrun_tla\fR is implemented using \fBrun_cmd\fR.
.IP "\fBrun_pipe_from\fR \fIshell_command_with_args\fR" 4
.IX Item "run_pipe_from shell_command_with_args"
.PD 0
.IP "\fBrun_pipe_from\fR \fIshell_command\fR \fIarg\fR ..." 4
.IX Item "run_pipe_from shell_command arg ..."
.PD
Run the given shell command (like \fIls\fR or \fItar\fR) with optional arguments
in the separate process. Return the pipe (file handle) that may be used to
read the command output from.
.Sp
\&\fBrun_cmd\fR is implemented using \fBrun_pipe_from\fR.
.IP "\fBload_file\fR \fIfile_name\fR" 4
.IX Item "load_file file_name"
.PD 0
.IP "\fBload_file\fR \fIfile_name\fR \fIscalar_ref\fR" 4
.IX Item "load_file file_name scalar_ref"
.IP "\fBload_file\fR \fIfile_name\fR \fIarray_ref\fR" 4
.IX Item "load_file file_name array_ref"
.PD
Load the given \fIfile_name\fR. Return the file content if the returning value
is expected. As a side effect, may modify the \fIscalar_ref\fR or \fIarray_ref\fR
if given, in the last case all file lines are split and \fBchomp\fR\-ed.
.IP "\fBsave_file\fR \fIfile_name\fR \fIcontent\fR" 4
.IX Item "save_file file_name content"
Save the given \fIcontent\fR in the given \fIfile_name\fR. The \fIcontent\fR may be
either scalar, scalar ref, or array ref (see \fBload_file\fR).
.IP "\fBcopy_dir\fR \fIdir1\fR \fIdir2\fR" 4
.IX Item "copy_dir dir1 dir2"
Copy \fIdir1\fR to \fIdir2\fR recursivelly, preserving as many attributes as
possible.
.IP "\fBremove_dir\fR \fIdir\fR .." 4
.IX Item "remove_dir dir .."
Remove \fIdir\fR (or dirs) recusivelly. Please be careful.
.IP "\fBsetup_config_dir\fR" 4
.IX Item "setup_config_dir"
.PD 0
.IP "\fBsetup_config_dir\fR \fIdir\fR" 4
.IX Item "setup_config_dir dir"
.IP "\fBsetup_config_dir\fR \fIdir\fR \fIsubdir\fR ..." 4
.IX Item "setup_config_dir dir subdir ..."
.PD
Create (if needed) the configuration \fIdir\fR that defaults to either
\&\f(CW$ARCH_MAGIC_DIR\fR or \fI~/.arch\-magic\fR or \fI/tmp/.arch\-magic\fR if \f(CW$HOME\fR is
unset.
.Sp
If one or more consecutive \fIsubdir\fR given, repeat the same procedure
for the sub-directory (including creating and diagnostics if needed).
.Sp
Return a name of the existing directory (including sub-directories if any).
.IP "\fBstandardize_date\fR \fIdefault_unix_date_string\fR" 4
.IX Item "standardize_date default_unix_date_string"
Try to convert the given date string to \*(L"yyyy-mm-dd \s-1HH:MM:SS TMZ\*(R".\s0
If failed, the original string is returned.
.IP "\fBdate2daysago\fR \fIdate_string\fR" 4
.IX Item "date2daysago date_string"
Convert a date string to time difference to now in full days.
.Sp
In list content, return (num_days_ago, unix_time, timezone_str).
.IP "\fBdate2age\fR \fIdate_string\fR" 4
.IX Item "date2age date_string"
Like \fBdate2daysago\fR, but return a human readable string, like \*(L"5 days\*(R"
or \*(L"\-6 weeks\*(R" or \*(L"7 months\*(R" or \*(L"3 years\*(R".
.IP "\fBparse_creator_email\fR \fImy_id\fR" 4
.IX Item "parse_creator_email my_id"
Try to parse the \fIarch\fR \fBmy-id\fR of the patch creator. Return a list of
his/her name and email.
.IP "\fBadjacent_revision\fR \fIfull_revision\fR \fIoffset\fR" 4
.IX Item "adjacent_revision full_revision offset"
Given the \fIfull_revision\fR and positive or negative offset, try to guess the
full name of the adjacent revision.
.SH "BUGS"
.IX Header "BUGS"
Awaiting for your reports.
.SH "AUTHORS"
.IX Header "AUTHORS"
Mikhael Goikhman (migo@homemail.com\*(--Perl\-GPL/arch\-perl\*(--devel).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For more information, see tla, Arch.