NAME
HATX - A fluent interface for Hash and Array Transformations
SYNOPSIS
use HATX qw/hatx/;
# Multiple versions of journal.html and projmgmt.html
my $files = [
'journal-v1.0.tar.gz 1201',
'journal-v1.1.tar.gz 1999',
'journal-v1.2.tar.gz 3100',
'projmgmt-v0.1.tar.gz 250',
'projmgmt-v0.2.tar.gz 350'
];
# Declare a helper object
my $max = { journal => '0.0', projmgmt => '0.0' };
# hatx($obj) clones $obj; no clobbering
my $h = hatx($files)
# Internal object becomes equivalent to:
# [ 'journal-v1.0.tar.gz 1201',
# 'journal-v1.1.tar.gz 1999',
# 'journal-v1.2.tar.gz 3100',
# 'projmgmt-v0.1.tar.gz 250',
# 'projmgmt-v0.2.tar.gz 350' ]
# Extract components: file, version, bytes
->map(sub {
$_[0] =~ /(journal|projmgmt)-v(.+).tar.gz\s+(\d+)/;
return [$1, $2, $3]; # e.g. ['journal', '1.0', 1201]
})
# Internal object becomes equivalent to:
# [ ['journal', '1.0', 1201]
# ['journal', '1.1', 1999]
# ['journal', '1.2', 3100]
# ['projmgmt', '0.1', 250]
# ['projmgmt', '0.2', 350] ]
# Accumulate file count and file sizes
->apply(sub {
my ($v, $res) = @_;
$res->{count}++;
$res->{bytes} += $v->[2];
}, my $stats = { count => 0, bytes => 0 })
# Internal object unchanged
# The $stats variable becomes { count => 5, bytes => 6900 }
# Determine the max version of each file, store into $max
->apply(sub {
my ($v, $res) = @_;
my ($file, $ver, $size) = @$v;
if ($ver gt $res->{$file}) { $res->{$file} = $ver }
}, $max)
# Internal object unchanged
# $max variable becomes { journal => '1.2', projmgmt => '0.2' }
# Keep only the max version
->grep(sub {
my ($v, $res) = @_;
my ($file, $ver, $size) = @$v;
return $ver eq $res->{$file};
}, $max)
# Internal object reduced to:
# [ ['journal', '1.2', 3100]
# ['projmgmt', '0.2', 350] ]
;
METHODS
hatx( $objref )
DESCRIPTION
Clone the given $objref to create a 'hatx' object instance. The
'hatx' object has an internal structure which is:
One of: hashref | arrayref | undef
This internal structure shall be called 'haref' in the rest of this
document.
ARGUMENTS
$objref - Reference to either a hash or an array
RETURNS
An instance of the HATX object.
to_obj()
DESCRIPTION
Converts the internal haref and returns it.
ARGUMENTS
None.
RETURNS
One of: hashref | arrayref | undef
map( $fn, [,@args] )
DESCRIPTION
Apply the given function, $fn, to each element of the internal
haref, replacing the entire haref.
ARGUMENTS
$fn - A user-provided function with a suitable signature.
If internal haref is a hashref, $fn should have signature:
$fn->($hkey_s, $hval_s [,@args]) returning ($hkey_t, $hval_t)
WHERE
$hkey_s Key of source hashref pair
$hval_s Value of source hashref pair
@args Optional user variables
$hkey_t Key of target hashref pair
$hval_t Value of target hashref pair
If the internal haref is an arrayref, $fn should have the signature:
$fn->($val_s [,@args]) returning ($val_t)
WHERE
$val_s An element of the source arrayref
@args Optional user variables
$val_t An element of the target arrayref
@args - Optional arguments that are passed to $fn
RETURNS
The hatx object with the target haref.
grep( $fn [,@args] )
DESCRIPTION
Retain only elements of the haref where $fn returns true.
ARGUMENTS
$fn - A user-provided function with a suitable signature.
If internal haref is a hashref, $fn should have signature:
$fn->($hkey_s, $hval_s [,@args]) returning ($hkey_t, $hval_t)
WHERE
$hkey_s Key of source hashref pair
$hval_s Value of source hashref pair
@args Optional user variables
$hkey_t Key of target hashref pair
$hval_t Value of target hashref pair
If the internal haref is an arrayref, $fn should have the signature:
$fn->($val_s [,@args]) returning ($val_t)
WHERE
$val_s An element of the source arrayref
@args Optional user variables
$val_t An element of the target arrayref
@args - Optional arguments that are passed to $fn
RETURNS
The hatx object with elements containing only 'grepped' elements.
sort( $fn )
DESCRIPTION
Sorts contents of arrayref. Hashrefs are unmodified.
ARGUMENTS
$fn - A function reference with prototype ($$) i.e. taking two
arguments. See https://perldoc.perl.org/functions/sort.
Examples of $fn:
sub ($$) { $_[1] cmp $_[0] } # Sort descending alphabetically
sub ($$) { $_[0] <=> $_[1] } # Sort ascending numerically
sub ($$) { $_[1] <=> $_[0] } # Sort descending numerically
RETURNS
The sorted hatx object.
to_href( $fn [,@args] )
DESCRIPTION
Convert internal arrayref to hashref using the given function, $fn,
fn and optionally additional arguments, @args, as needed.
ARGUMENTS
$fn - A user-provided function reference with signature:
$fn->($val [,@args]) returning ($hkey, $hval)
WHERE
$val An element of the source arrayref
@args Optional user variables
$hkey Key of target hashref pair
$hval Value of target hashref pair
@args - Optional arguments that are passed to $fn
RETURNS
The hatx object where the internal structure is a hashref.
to_aref( $fn [,@args] )
DESCRIPTION
Convert internal hashref to arrayref using the given function, $fn
and optionally additional arguments, @args, as needed.
ARGUMENTS
$fn - A user-provided function reference with signature:
$fn->($hkey, $hval [,@args]) returning ($val)
WHERE
$hkey Key of source hashref pair
$hval Value of source hashref pair
@args Optional user variables
$val An element of the target arrayref
@args - Optional arguments that are passed to $fn
RETURNS
The hatx object where the internal structure is a hashref.
apply( $fn [,@args] )
DESCRIPTION
Apply the given function, $fn to each item in the haref. The haref
is unchanged. Typically used to find aggregate values e.g. max/min or
totals which are then stored into @args.
ARGUMENTS
$fn - A user-provided function with a suitable signature.
If internal haref is a hashref, $fn should have signature:
$fn->($hkey_s, $hval_s [,@args]) with no return values
WHERE
$hkey_s Key of source hashref pair
$hval_s Value of source hashref pair
@args Optional user variables
If the internal haref is an arrayref, $fn should have the signature:
$fn->($val_s [,@args]) with no return values
WHERE
$val_s An element of the source arrayref
@args Optional user variables
@args - Optional arguments that are passed to $fn
RETURNS
The same hatx object.
AUTHOR
Hoe Kit CHEW <hoekit@gmail.com>
COPYRIGHT
Copyright 2024- Hoe Kit CHEW
LICENSE
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.