Arch::Util(3pm)

💖 Arch::Util — the perl side of the arch universe 💖

okay bestie, welcome to Arch::Util(3pm), aka User Contributed Perl Documentation's cutest little toolbox 🧰✨ this is a set of helper functions for GNU Arch related projects in Perl, and it's giving "the plumbing underneath everything" energy. no cap.

---

🌸 NAME 🌸

Arch::Util — arch utility functions 🦋

---

✨ SYNOPSIS ✨

use Arch::Util qw(run_tla load_file save_file setup_config_dir);

my $abrowse_output = run_tla('abrowse --summary --date --creator');
my ($full_version) = run_tla('tree-version');
my @full_revisions = run_tla('logs', '-r', '-f');

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);

like, look at her go 😭 she's literally just loading a config, regexing it, saving it back. main character behavior fr fr.

---

🎀 DESCRIPTION 🎀

A set of helper functions suitable for GNU Arch related projects in Perl.

Higher (object oriented) levels of the Arch/Perl library make use of these helper functions. so basically this is the lowkey backbone that the fancy OO layers lean on. iconic of her honestly 💅

---

👑 FUNCTIONS 👑

The following functions are available:

• run_tla
• run_cmd
• run_pipe_from
• load_file
• save_file
• copy_dir
• remove_dir
• setup_config_dir
• standardize_date
• date2daysago
• date2age
• parse_creator_email
• adjacent_revision

⚠️ heads up bestie: The system functions die on errors. like, they will not sugarcoat it, they will just die. periodt. 💀

---

🦋 is_tla_functional

Verify whether the system has a working arch backend installed (and possibly configured by environment variables, like TLA or ARCH_BACKEND), needed for this perl library to function.

aka: vibe check the backend first before you do anything else, otherwise nothing works and you'll be sad 🙈

🌈 run_tla subcommand_with_args

🌈 run_tla subcommand arg ...

Run the given tla subcommand with optional arguments. Return the tla output in the scalar context, and a list of chomp-ed lines in the list context.

scalar context = one big string. list context = cute little array of lines with the newlines already chomped off ✂️ obsessed.

🌟 run_cmd shell_command_with_args

🌟 run_cmd shell_command arg ...

Run the given shell command (like wc or awk) with optional arguments. Return the command output in the scalar context, and a list of chomp-ed lines in the list context.

run_tla is implemented using run_cmd. iykyk 🫶

🍓 run_pipe_from shell_command_with_args

🍓 run_pipe_from shell_command arg ...

Run the given shell command (like ls or tar) with optional arguments in the separate process. Return the pipe (file handle) that may be used to read the command output from.

separate process!! she's independent!! ✨ and run_cmd is implemented using run_pipe_from, so it's turtles all the way down 🐢

💜 load_file file_name

💜 load_file file_name scalar_ref

💜 load_file file_name array_ref

Load the given file_name. Return the file content if the returning value is expected. As a side effect, may modify the scalar_ref or array_ref if given, in the last case all file lines are split and chomp-ed.

so like, three modes: just give her the file and take the return value, or hand her a scalar_ref, or hand her an array_ref and she'll split + chomp every line for you. so thoughtful 😭💖

🌸 save_file file_name content

Save the given content in the given file_name. The content may be either scalar, scalar ref, or array ref (see load_file).

she's flexible like that 💅 see load_file above, same energy, opposite direction.

🧚 copy_dir dir1 dir2

Copy dir1 to dir2 recursivelly, preserving as many attributes as possible.

preserving attributes!! she cares about the details bestie 🎀

💀 remove_dir dir ..

Remove dir (or dirs) recusivelly. Please be careful.

🚨 PLEASE BE CAREFUL. not me writing that in the actual docs but genuinely — this one deletes recursively and it does not ask twice. like, please. 🙏

⭐ setup_config_dir

⭐ setup_config_dir dir

⭐ setup_config_dir dir subdir ...

Create (if needed) the configuration dir that defaults to either $ARCH_MAGIC_DIR or ~/.arch-magic or /tmp/.arch-magic if $HOME is unset.

If one or more consecutive subdir given, repeat the same procedure for the sub-directory (including creating and diagnostics if needed).

Return a name of the existing directory (including sub-directories if any).

so it creates the dir if it's not there yet, and if you pass a subdir (or a whole lil chain of them) she'll do the same thing for each one, with diagnostics and everything ✨ and then she hands you back the name of the directory that actually exists, sub-directories included. slay.

🫶 standardize_date default_unix_date_string

Try to convert the given date string to "yyyy-mm-dd HH:MM:SS TMZ". If failed, the original string is returned.

no drama, no exception, no crash — if the conversion flops she just gives you back what you gave her 🙈

💅 date2daysago date_string

Convert a date string to time difference to now in full days.

In list content, return (num_days_ago, unix_time, timezone_str).

three values in list context, bestie — count them 👑

🦋 date2age date_string

Like date2daysago, but return a human readable string, like "5 days" or "-6 weeks" or "7 months" or "3 years".

human readable!! that's the whole point, no one wants a raw number when they could have "3 years" 😌

🎀 parse_creator_email my_id

Try to parse the arch my-id of the patch creator. Return a list of his/her name and email.

name AND email, in a list, from one my-id. detective work honestly 🔍

🌈 adjacent_revision full_revision offset

Given the full_revision and positive or negative offset, try to guess the full name of the adjacent revision.

positive or negative, she handles both directions, she's just guessing though — try to guess, that's what the docs say, don't come for her 👑✨

---

🐛 BUGS 🐛

Awaiting for your reports.

literally sitting there with a lil notepad like "tell me everything 💖" — so if you find one, report it!

---

👯 AUTHORS 👯

Mikhael Goikhman (migo@homemail.com--Perl-GPL/arch-perl--devel).

---

🌟 SEE ALSO 🌟

For more information, see tla, Arch.

---

and that's the whole page bestie 🫶 written by the perl gang, perl v5.20.2, dated 2010-03-08 — vintage but still serving 💅✨ bye ily, go read your config files responsibly 🎀