The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Hash-Map-0.016
River stage zero No dependents
1 ++
/ Hash::Map

NAME

Hash::Map - Manipulate hashes map like

VERSION

0.016

SYNOPSIS

    require Hash::Map;

Instead of

    %hash = (
        a => $other->{a},
        b => $other->{b},
        c => $other->{c},
        d => $other->{d},
        e => $other->{e},
        f => 'bla bla',
    );

write with map

    %hash = (
        (
            map {
                $_ => $other->{$_};
            } 'a' .. 'e'
        ),
        f => 'bla bla',
    );

or more clear readable

    %hash = Hash::Map
        ->source_ref($other)
        ->copy_keys('a' .. 'e')
        ->merge_hash(f => 'bla bla')
        ->target;

DESCRIPTION

Often in code we find lots of copy/paste code during prepare a hash or hash reference. That data we got from other structures, objects or constants.

  • We map hashes that not match exactly to the expected API.

  • Or the method names, we call, matching not exactly to the hash keys.

  • Sometimes we forgot to write scalar if we call subroutines/methods for a hash value and risk to have a value as key.

  • We use map, for, map/push to build the expected hash or hash reference.

  • Accidentally we do not destroy the data we fetch.

  • We have to write defined, ? : or do.

This Module lets you writing code without that copied noise.

The goal of this module is to write clear code with less typing around. Less typing for the user needs lots of specialized methods in this module.

The code in the SYNOPSIS is only a very simple but typical example to understand, why that module was written.

Look at your existing code for lots of similar lines of hash key/value pairs. Then this module can help you.

There is also a fuctional interface. That is wrapped around the OO inferface. Not all can be implemented functional.

For more information read the Hash::Map::Tutorial.

EXAMPLE

Inside of this Distribution is a directory named example. Run this *.pl files.

SUBROUTINES/METHODS

method new

A simple constructor without any parameters.

    my $obj = Hash::Map->new;

Typical you don't call method "new" directly.

method source, source_ref, set_source and set_source_ref

Set or get the source hash.

Method "source" can not set an empty hash, but an empty hash is the default. Otherwise use method "set_source".

    $obj = $obj->source(%source);
    $obj = $obj->source_ref($source_hashref);
    # if %source is or can be empty
    $obj = $obj->set_source(%source);
    # method exists for the sake of completeness
    $obj = $obj->set_source_ref($target_ref);

    %source         = $obj->source;
    $source_hashref = $obj->source_ref;

This methods are able to construct the object first.

    Hash::Map->source(...);
    Hash::Map->source_ref(...);
    Hash::Map->set_source(...);
    Hash::Map->set_source_ref(...);

method target, target_ref, set_target and set_target_ref

Set or get the target hash.

Method "target" can not set an empty hash, but an empty hash is the default. Otherwise use method "set_target".

    $obj = $obj->target(%target);
    $obj = $obj->target_ref($target_hashref);

    # if %target is or can be empty
    $obj = $obj->set_target(%target);
    # method exists for the sake of completeness
    $obj = $obj->set_target_ref($target_ref);

    %target         = $obj->target;
    $target_hashref = $obj->target_ref;

This methods are able to construct the object first.

    Hash::Map->target(...);
    Hash::Map->target_ref(...);
    Hash::Map->set_target(...);
    Hash::Map->set_target_ref(...);

Typical the source is set and not the target. But it makes no sense to set the source and copy then all from source.

method source_keys, target_keys, source_keys_ref, target_keys_ref

This methods get back all keys as array or array reference.

    @keys      = $obj->source_keys;
    @keys      = $obj->target_keys;
    $array_ref = $obj->source_keys_ref;
    $array_ref = $obj->target_keys_ref;

method source_values, target_values, source_values_ref, target_values_ref

This methods get back all values as array or array reference.

    @values    = $obj->source_values;
    @values    = $obj->target_values;
    $array_ref = $obj->source_values_ref;
    $array_ref = $obj->target_values_ref;

method exists_source, exists_target

This methods allows easy writing for exists.

    $boolean = $obj->exists_source($key);
    $boolean = $obj->exists_target($key);

method combine

Merge targets of other Hash::Map objects into $obj target.

    $obj = $obj->combine(@hash_map_objects);

This method is able to construct the object first.

    Hash::Map->combine(...);

Typical used for clear code to prevent the change of the source hash/hashref. It's strongly readable if source is set more than one time.

method clone_source

Using Module Clone to clone the source hash.

    $obj = $obj->clone_source;

This method exists for the sake of completeness.

method clone_target

Using Module Clone to clone the target hash.

    $obj = $obj->clone_target;

Only used after set of target hash reference to prevent manpulations backwards.

method delete_keys and delete_keys_ref

Delete keys in target hash.

    $obj = $obj->delete_keys(@keys);
    $obj = $obj->delete_keys_ref($keys_array_ref);

method copy_keys and copy_keys_ref

Copy data from source to target hash using keys.

    $obj = $obj->copy_keys(@keys);
    $obj = $obj->copy_keys_ref($keys_array_ref);

And rename all keys during copy.

    $obj = $obj->copy_keys(
        @keys,
        sub {
            my $obj = shift;
            my $key = $_;
            return "new $key";
        },
    );
    $obj = $obj->copy_keys_ref(
        $keys_array_ref,
        sub {
            my $obj = shift;
            my $key = $_;
            return "new $key";
        },
    );

The first parameter of the callback subroutine is the object itself. The current key is in $_. Return the new key.

Replaces code like this:

    %target = (
        a => $source->{a},
        b => $source->{b},
        ...
    );
    %target = (
        p_a => $source->{a},
        p_b => $source->{b},
        ...
    );

method map_keys and map_keys_ref

Copy data from source hash (key is key of map) to target hash (key is value of map).

    $obj = $obj->map_keys(%map);
    $obj = $obj->map_keys_ref($map_hashref);

Replaces code like this:

    %target = (
        a => $source->{z},
        b => $source->{y},
        ...
    );

method merge_hash and merge_hashref

Merge the given hash into the target hash.

    $obj = $obj->merge_hash(%hash);
    $obj = $obj->merge_hashref($hashref);

Replaces code like this:

    %target = (
        %hash,
        ...
    );

method modify and modify_ref

Modify the target hash inplace by given key and code for that.

The first parameter of the callback subroutine is the object itself. The old value of the target hash is in $_; Return the new value.

    $obj = $obj->modify(
        key1 => $code_ref1,
        ...
    );
    $obj = $obj->modify_ref({
        key1 => $code_ref1,
        ...
    });

Typical the combinated methods are used: "copy_modify", "copy_modify_ref", "copy_modify_identical", "copy_modify_identical_ref", "map_modify", "map_modify_ref", "map_modify_identical" and "map_modify_identical_ref".

method copy_modify and copy_modify_ref

This is a combination of method "copy_keys" and "modify".

The first parameter of the callback subroutine is the object itself. The old value of the target hash is in $_; Return the new value.

    $obj = $obj->copy_modify(
        key1 => $code_ref1,
        ...
    );
    $obj = $obj->copy_modify_ref({
        key1 => $code_ref1,
        ...
    });

It is not possible to rename all keys during copy. Use method "map_modify" or "map_modify_ref" instead.

This method exists for the sake of completeness.

method copy_modify_identical and copy_modify_identical_ref

This is another combination of method "copy_keys" and "modify". All values are modified using a common code reference.

The 1st parameter of the callback subroutine is the object itself. The 2nd parameter is the key. The old value of the target hash is in $_; Return the new value.

    $obj = $obj->copy_modify_identical(
        @keys,
        $code_ref,
    );
    $obj = $obj->copy_modify_identical_ref(
        $keys_array_ref,
        $code_ref,
    );

It is not possible to rename all keys during copy. Use method "map_modify_identical" or "map_modify_identical" instead.

Replaces code like this:

    %target = (
        a => $foo->bar('a'),
        b => $foo->bar('b'),
        ...
    );
    %target = (
        a => $foo->a,
        b => $foo->b,
        ...
    );

method map_modify and map_modify_ref

This is a combination of method "map_keys" and "modify".

The first parameter of the callback subroutine is the object itself. The old value of the target hash is in $_; Return the new value.

    $obj = $obj->map_modify(
        source_key1 => target_key1 => $code_ref1,
        ...
    );
    $obj = $obj->map_modify_ref([
        source_key1 => target_key1 => $code_ref1,
        ...
    ]);

This method exists for the sake of completeness.

method map_modify_identical and map_modify_identical_ref

This is a combination of method "map_keys" and "modify".

The 1st parameter of the callback subroutine is the object itself. The 2nd parameter is the source key and the 3rd parameter is the target key. The old value of the target hash is in $_; Return the new value.

    $obj = $obj->map_modify_identical(
        source_key1 => target_key1,
        ...
        $code_ref,
    );
    $obj = $obj->map_modify_identical_ref(
        {
            source_key1 => target_key1,
            ...
        },
        $code_ref,
    );

Replaces code like this:

    %target = (
        a => $foo->bar('z'),
        b => $foo->bar('y'),
        ...
    );
    %target = (
        a => $foo->z,
        b => $foo->y,
        ...
    );

method each_source, each_target, source_iterator, target_iterator

This methods allows to work with iterations.

    while ( my ($key, $value) = $self->each_source ) {
        ...
    }

    while ( my ($key, $value) = $self->each_target ) {
        ...
    }

    my $iterator_code = $self->source_iterator;
    while ( my ($key, $value) = $iterator_code->() ) {
        ...
    }

    my $iterator_code = $self->target_iterator;
    while ( my ($key, $value) = $iterator_code->() ) {
        ...
    }

subroutine hash_map

This subroutine is for the fuctional interface only.

    %target_hash = hash_map(
        \%source_hash,
        # The following references are sorted anyway.
        # Running in order like written.
        [ qw(key1 key2) ],               # copy_keys from source to target hash
        [ qw(key3 key4), $code_ref ],    # copy_keys, code_ref to rename keys
        {
            source_key1 => 'target_key', # map_keys from source to target hash
            source_key2 => $code_ref,    # modify values in target hash
        },
    );

subroutine hashref_map

Similar, only the subroutine name and the return value has chenged.

    $target_hashref = hashref_map(
        $source_hashref,
        ...
    );

DIAGNOSTICS

nothing

CONFIGURATION AND ENVIRONMENT

nothing

DEPENDENCIES

Carp

Clone

Scalar::Util

Try::Tiny

parent

Exporter::Tiny

INCOMPATIBILITIES

none

BUGS AND LIMITATIONS

none

SEE ALSO

map

Data::Visitor

Hash::Map::Tutorial

AUTHOR

Steffen Winkler

inspired by: Andreas Specht <ACID at cpan.org>

LICENSE AND COPYRIGHT

Copyright (c) 2012 - 2016, Steffen Winkler <steffenw at cpan.org>. All rights reserved.

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