NAME

Data::Focus::Lens::HashArray::Index - a lens to focus on element(s) of hash/array

SYNOPSIS

    use Data::Focus qw(focus);
    use Data::Focus::Lens::HashArray::Index;
    
    sub lens { Data::Focus::Lens::HashArray::Index->new(index => $_[0]) }
    
    my $target = {
        foo => "bar",
        hoge => [ "a", "b", "c" ]
    };
    
    focus($target)->get(lens("foo"));                ## => "bar"
    focus($target)->get(lens("hoge"));               ## => ["a", "b", "c"]
    focus($target)->get(lens("hoge"), lens(1));      ## => "b"
    
    focus($target)->list(lens("hoge"), lens([0, 2])) ## => ("a", "c")

DESCRIPTION

This is an implementation of Data::Focus::Lens, which focuses on one or more elements in a hash or array.

Conceptually, this lens does the same as hash/array subscripts and slices.

    $hash->{index}
    @{$hash}{"index1", "index2", "index3"}
    $array->[4]
    @{$array}[3,4,5]

This lens never autovivifies when reading, while it DOES autovivify when writing.

Detailed behaviors of this lens are described below for each target type.

HASH target

If the target is a hash-ref, this lens behaves as its subscript or slice.

Duplicate keys in a slice are allowed. If different values are set to those keys, only the last one takes effect.

It returns undef for non-existent keys. You can set values to them.

ARRAY target

If the target is an array-ref, this lens behaves as its subscript and slice. The indices are cast to integers.

Positive out-of-range indices are allowed. get() and list() return undef for those indices. When set, it extends the array.

Negative indices are allowed. They create focal points from the end of the array, e.g., index of -1 means the last element in the array.

Negative out-of-range indices are read-only. They always return undef. If you try to set values, it croaks.

Duplicate indices in a slice are allowed. If different values are set to those indices, only the last one takes effect.

undef target

When reading, it always returns undef.

When writing, it autovivifies an array-ref if and only if the indices are all non-negative integers. Otherwise, it autovivifies a hash-ref.

blessed target

By default, the lens creates no focal point for a blessed target. This means get() returns undef and set() does nothing.

If allow_blessed option is set to true and the target is made of a hash-ref or array-ref, the lens creates focal points as if the target were a regular hash-ref or array-ref.

other targets

For other types of targets such as scalar-refs, the lens creates no focal point. This means get() returns undef and set() does nothing.

CLASS METHODS

$lens = Data::Focus::Lens::HashArray::Index->new(%args)

The constructor. Fields in %args are:

index => STR or ARRAYREF_OF_THEM (mandatory)

Index to focus. When you specify an array-ref, the $lens behaves like slice.

immutable => BOOL (optional, default: false)

If set to true, the target hash/array is treated as immutable. This means every updating operation using the $lens creates a new hash/array in a copy-on-write fashion.

allow_blessed => BOOL (optional, default: false)

If set to true, the lens makes focal points for blessed targets if they are made of hash-refs or array-refs.

You should not set this option together with immutable option, bacause in this case you get a plain (unblessed) hash-ref/array-ref from set() method. This is confusing.

OBJECT METHODS

apply_lens

See Data::Focus::Lens.

AUTHOR

Toshio Ito, <toshioito at cpan.org>

cpanm Data::Focus

perl -MCPAN -e shell
install Data::Focus