/ 
Array-Join-0.003
/ Array::Join::OO

NAME

Array::Join::OO - SQL-like joins over two arrays of hashrefs

SYNOPSIS

use Array::Join::OO;

my $join = Array::Join::OO->new(
    \@left,
    \@right,
    {
        on   => [
            sub { $_[0]{id} },
            sub { $_[0]{id} },
        ],
        type  => 'inner',   # inner | left | right | outer
        merge => 'LEFT_PRECEDENT',
    }
);

my @rows = $join->join;

DESCRIPTION

Array::Join::OO performs SQL-style joins over two Perl arrays. Each array element is typically a hashref. Join keys are produced by user-supplied callbacks.

The module supports inner, left, right, and outer joins and multiple merge strategies for combining matching rows.

Multiple rows per key are supported; all matching combinations are returned (Cartesian product).

CONSTRUCTOR

new( \@array_a, \@array_b, \%options )

Creates a join object.

Exactly two array references must be provided.

The options hash must contain an on key with exactly two code references, one per array.

Options

  • on => [ sub {...}, sub {...} ]

    Required. Two callbacks that extract a join key from items in the left and right arrays respectively.

  • type => 'inner' | 'left' | 'right' | 'outer'

    Join type. Defaults to inner.

  • merge => STR | ARRAY | CODE

    Controls how matching rows are combined.

    See "MERGE STRATEGIES".

  • as => ...

    Alias for merge.

METHODS

join

my @rows = $join->join;

Executes the join and returns a list of merged rows.

For non-inner joins, missing rows are represented as empty hashrefs.

keys

my $keys = $join->keys;

Returns a sorted arrayref of join keys used by the join.

lookups

my $lookups = $join->lookups;

Returns a deep clone of the internal lookup tables. This data is read-only.

MERGE STRATEGIES

The merge option controls how matching rows are combined.

CODE reference

merge => sub {
    my ($left, $right, $opts) = @_;
    ...
}

Receives cloned copies of both rows and must return a single value.

ARRAY reference

merge => [ 'left', 'right' ]

All keys in each hash are renamed with the given prefixes (e.g. left.id, right.id) before merging.

Hash::Merge behaviors

merge => 'LEFT_PRECEDENT'
merge => 'RIGHT_PRECEDENT'
merge => 'STORAGE_PRECEDENT'

Passed directly to Hash::Merge. If the string ends in _PRECEDENT, the behavior is applied explicitly.

Default

If merge is false or omitted, each result row is returned as:

[ $left_hashref, $right_hashref ]

JOIN SEMANTICS

  • inner

    Only keys present in both arrays.

  • left

    All keys from the left array; missing right rows become empty hashes.

  • right

    All keys from the right array; missing left rows become empty hashes.

  • outer

    All keys from both arrays.

If multiple rows share the same key on either side, all combinations are returned.

ERRORS

The constructor throws exceptions if:

  • The wrong number of arrays is provided

  • The on option is missing or invalid

  • An unknown join type is specified

AUTHOR

Simone Cesano <scesano@cpan.org>

This software is copyright (c) 2025 by Simone Cesano.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.