The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Module-Generic-v0.15.0
River stage two • 15 direct dependents • 19 total dependents
2 ++
/ Module::Generic::Hash

NAME

Module::Generic::Hash - Hash Manipulation Object Class

SYNOPSIS

    my $h = Module::Generic::Hash->new({
        first_name => 'John',
        last_name => 'Doe',
        age => 30,
        email => 'john.doe@example.com',
    });

    # or

    my $h = Module::Generic::Hash->new({
        first_name => 'John',
        last_name => 'Doe',
        age => 30,
        email => 'john.doe@example.com',
    }, { debug => 2 });

    my $keys = $h->keys # Module::Generic::Array returned
    $h->keys->length # e.g. 10
    $keys->pop # See Module::Generic::Array
    print( $h->as_string, "\n" );
    # or
    print( "$h\n" );
    # Produces:
    {
    "age" => 30,
    "email" => "john.doe\@example.com",
    "first_name" => "John",
    "last_name" => "Doe"
    }

    $h->json({ pretty => 1 });
    # Produces
    {
    "age" : 30,
    "email" : "john.doe@example.com",
    "first_name" : "John",
    "last_name" : "Doe"
    }
    # Or
    $h->json
    # Produces
    {"age":30,"email":"john.doe@example.com","first_name":"John","last_name":"Doe"}
    # Adding a key and value as usual:
    $h->{role} = 'customer';
    $h->defined( 'role' ) # True
    $h->delete( 'role' ) # Removes and returns 'customer'
    $h->each(sub
    {
        my( $k, $v ) = @_;
        print( "Key $k has value '$v'\n" );
    });
    exists( $h->{age} );
    # same as
    $h->exists( 'age' );
    # Same as $h->foreach(sub{ #.. });
    $h->for(sub{
        my( $k, $v ) = @_;
        print( "Key $k has value '$v'\n" );
    });
    $h->length # Returns a Module::Generic::Number
    my $hash2 =
    {
        address =>
        {
        line1 => '1-2-3 Kudan-minami, Chiyoda-ku',
        line2 => 'Big bld 7F',
        postal_code => '123-4567',
        city => 'Tokyo',
        country => 'jp',
        },
        last_name => 'Smith',
    };
    my $h2 = Module::Generic::Hash->new( $hash2 );
    $h->merge( $hash2 );
    # same as $h->merge( $h2 );
    $h > $h2 # True
    $h gt $h2 # True
    $h >= $h2 # True
    $h2 < $h # True
    $h2 lt $h # True
    $h2 <= $h # True
    3 < $h # True

    # Merge $hash2 into $h, but without overwriting existing entries
    $h->merge( $hash2, { overwrite => 0 });
    # Otherwise, bluntly overwriting existing entries, if any
    $h->merge( $hash2 );

    # Same copy
    my $h3 = $h->clone;

    my $vals = $h->values; # Returns a Module::Generic::Array
    # Must return an empty list to prevent the entry from being added to the result, as per perlfunc documentation, see map
    my $vals = $h->values(sub{
        ref( $_[0] ) ? () : $_[0];
    }, { sort => 1 });

VERSION

    v1.0.0

DESCRIPTION

The purpos of this class/package is to provide a lightweight object-oriented approach to hash manipulation.

This uses perl core functions only and Clone for cloning. This module's methods act as a wrapper to them.

The object is overloaded, so it returns the hash representation, as dumped by Data::Dumper when used as a string.

    print( "I have a nice $hash\n" );

Would produce something like:

    I have a nice {
    "age" => 30,
    "email" => "john.doe\@example.com",
    "first_name" => "John",
    "last_name" => "Doe"
    }

Because the object is overloaded, you can use the variable with comparison perl operators, such as :

    $h > 3 # True
    $h <= 3 # False
    # etc...

You can also compare two hashes reliably, such as :

    $h1 eq $h2 # True

But if you use ==, it will compare the hash size, i.e. the number of keys

    $h1 == $h2

Which could be true if both hashes have the same number of keys (==), but may not be true if they are not the same (eq)

Otherwise, the hash can be accessed like a regular hash. For example :

    print( "Customer is $h->{first_name} $h->{last_name}\n" );

METHODS

new

Provided with a hash reference, some optional parameters and this returns a new object.

Possible optional parameters are:

debug

Provided with an integer and this actives or deactivates debugging messages. Nothing meaningful happens below 3

as_string

Return a string version of the hash as produced by Data::Dumper

    print( "$h\n" );
    # or
    print( $h->as_string, "\n" );

    # Produces
    {
    "age" => 30,
    "email" => "john.doe\@example.com",
    "first_name" => "John",
    "last_name" => "Doe"
    }

chomp

Performs a "chomp" in perlfunc on the entire hash values and returns the current object it was called with.

Qyoting from perlfunc: "If variable is a hash, it chomps the hash's values, but not its keys".

clone

Produce a deep clone of the hash and return a new object. This uses "clone" in Clone to achieve that.

debug

Sets or gets the debug level

defined

Provided with a hash key and this returns true if there is a value defined for this key. See "defined" in perlfunc

delete

Provided with a hash key and this remove the hash entry and return the previous value, exactly as "delete" in perlfunc does.

dump

Returns a string representation of the hash. This uses Data::Dumper to produce the result.

each

Provided with with a reference to a subroutine, this will do a loop using "each" in perlfunc and this will call the code, passing it the hash key and its value.

If the code returns false, it will exit the "while" in perlfunc loop.

To exit the loop, return undef(), for example:

    $a->each(sub
    {
        my( $k, $v ) = @_;
        return if( $key eq $not_this_one );
        print( "ok, this one\n" );
    });

exists

Given a hash key, this will return true or false depending if the hash key exists. This uses "exists" in perlfunc.

for

This is simply an alias for "foreach"

foreach

Same as "foreach" in perlfunc, given a reference to a subroutine, and this will execute foreach and call the code providing it as arguments the hash key and value. For convenience, $_ is also available and represent the 2nd argument, i.e. the value.

To exit the loop, return undef(), for example:

    $a->foreach(sub
    {
        my( $k, $v ) = @_;
        return if( $key eq $not_this_one );
        print( "ok, this one\n" );
    });

get

Provided with an hash key and this will return whatever value was set.

    $a->get( 'last_name' ); # Return 'Doe' maybe?

See "set" for the opposite method, i.e. setting a key value.

json

This returns a JSON representation of the hash. You can provided optionally an hash reference of parameters. Currently, only one parameter is supported: pretty, which will make the json result more human readable. With it enabled, you would get something like this :

    {
    "age" : 30,
    "email" : "john.doe@example.com",
    "first_name" : "John",
    "last_name" : "Doe"
    }

Otherwise, you would get a more terse result, such as :

    {"age":30,"email":"john.doe@example.com","first_name":"John","last_name":"Doe"}

keys

Returns the hash keys as a Module::Generic::Array object.

Also note that if you have a multi-level hash, this will return only the first level keys, just like "keys" in perlfunc would do.

    printf( "%d hash keys found\n", $h->keys->length );

And even, chaining through different objects :

    if( $h->keys->length->is_positive )
    {
        # Do something
    }

This returns the keys as an Module::Generic::Array object, then returns the size of the array as a Module::Generic::Number object.

length

This returns the number of keys in the hash, as a Module::Generic::Number object.

map

Provided with a code reference and this calls "map" in perlfunc and pass the code reference the hash key and its value.

It returns a regular list, i.e. not an object, just like perl's "map" in perlfunc would do.

map_array

Does the same as "map" above, except it returns a new array as a Module::Generic::Array object.

map_hash

Does the same as "map" above, except it returns a new Module::Generic::Hash object.

For this to work properly, the code reference needs to return a key-value pair.

merge

Provided with an hash reference and an optional hash of parameters and this will mergge the given hash with hash in our object. It does so recursively and prevents looping by using "refaddr" in Scalar::Util.

Currently the only parameter possible is overwrite. By default this is set to a true value, and you can provide this argument to specifically indicates you do not want the hash key value to be overwriten.

reset

This simply empty the hash. See also "undef" for the same result.

set

Provided with a key and a value, and this adds it to the hash, possibly overwriting any previous entry.

See "get" for the opposite method, i.e. to get the key value.

undef

This simply empty the hash. See also "reset" for the same result.

values

This returns the values of the hash as a Module::Generic::Array, but please note that jsut like the "values" in perlfunc, it only provides the first level values.

If an optional reference to a subroutine is provided, the code will be called for each value as its sole argument, and the subroutine can decide what to do with it, possibly altering the value and discarding it by returning the value, possibly altered, or an empty list to indicte this entry shoul be discarded. For example :

    my $vals = $h->values(sub{
        ref( $_[0] ) ? () : $_[0];
    });

This will make sure to get all values, except the ones that are reference (perlref)

To return entries with uppercase first :

    my $vals = $h->values(sub{
        join( ' ', map( ucfirst( lc( $_ ) ), split( /[[:blank:]]+/, $_[0] ) ) );
    });

And if one of the value were JohN DOE, this would result in John Doe

If the parameter sort is provided, then it will sort the array before returning the values and before executing the reference of the subroutine on each entry.

SEE ALSO

Module::Generic::Scalar, Module::Generic::Array, Module::Generic::Boolean, Module::Generic::Number, Module::Generic::Dynamic

Math::BigInt

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

Copyright (c) 2000-2020 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.