Steffen Winkler > Hash-Map-0.014 > Hash::Map

Download:
Hash-Map-0.014.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.014   Source  

NAME ^

Hash::Map - Manipulate hashes map like

VERSION ^

0.014

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.

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

Perl6::Export::Attrs

Scalar::Util

Try::Tiny

INCOMPATIBILITIES ^

none

BUGS AND LIMITATIONS ^

none

SEE ALSO ^

map

Data::Visitor

Hash::Map::Tutorial

AUTHOR ^

Steffen Winkler

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

LICENSE AND COPYRIGHT ^

Copyright (c) 2012, 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.

syntax highlighting: