NAME

List::Objects::WithUtils::Role::Hash - Hash manipulation methods

SYNOPSIS

  ## Via List::Objects::WithUtils::Hash ->
  use List::Objects::WithUtils 'hash';

  my $hash = hash(foo => 'bar');

  $hash->set(
    foo => 'baz',
    pie => 'tasty',
  );

  my @matches = $hash->keys->grep(sub {
    $_[0] =~ /foo/
  })->all;

  my $pie = $hash->get('pie')
    if $hash->exists('pie');

  for my $pair ( $hash->kv->all ) {
    my ($key, $val) = @$pair;
    ...
  }

  my $obj = $hash->inflate;
  my $foo = $obj->foo;

  ## As a Role ->
  use Role::Tiny::With;
  with 'List::Objects::WithUtils::Role::Hash';

DESCRIPTION

A Role::Tiny role defining methods for creating and manipulating HASH-type objects.

In addition to the methods documented below, these objects provide a TO_JSON method exporting a plain HASH-type reference for convenience when feeding JSON::Tiny or similar.

new

Constructs a new HASH-type object.

export

  my %hash = $hash->export;

Returns a raw key/value list.

clear

Clears the current hash entirely.

Returns the hash object (as of version 1.013).

copy

Creates a shallow clone of the current object.

unbless

Returns a plain /HASH reference (shallow clone).

defined

  if ( $hash->defined($key) ) { ... }

Returns boolean true if the key has a defined value.

delete

  $hash->delete( @keys );

Deletes keys from the hash.

Returns an "array_type" object containing the deleted values.

exists

  if ( $hash->exists($key) ) { ... }

Returns boolean true if the key exists.

get

  my $val  = $hash->get($key);
  my @vals = $hash->get(@keys)->all;

Retrieves a key or list of keys from the hash.

If we're taking a slice (multiple keys were specified), values are returned as an "array_type" object. (See "sliced" if you'd rather generate a new hash.)

inflate

  my $obj = hash(foo => 'bar', baz => 'quux')->inflate;
  my $baz = $obj->baz; 

Inflates a simple object providing accessors for a hash.

By default, accessors are read-only; specifying rw = 1> allows setting new values:

  my $obj = hash(foo => 'bar', baz => 'quux')->inflate(rw => 1);
  $obj->foo('frobulate');

Returns an "inflated_type" (or "inflated_rw_type") object.

The default objects provide a DEFLATE method returning a plain hash; this makes it easy to turn inflated objects back into a hash() for modification:

  my $first = hash( foo => 'bar', baz => 'quux' )->inflate;
  my $second = hash( $first->DEFLATE, frobulate => 1 )->inflate;

is_empty

Returns boolean true if the hash has no keys.

is_mutable

Returns boolean true if the hash is mutable; immutable subclasses can override to provide a negative value.

is_immutable

The opposite of "is_mutable".

keys

  my @keys = $hash->keys->all;

Returns the list of keys in the hash as an "array_type" object.

values

  my @vals = $hash->values->all;

Returns the list of values in the hash as an "array_type" object.

kv

  for my $pair ($hash->kv->all) {
    my ($key, $val) = @$pair;
  }

Returns an "array_type" object containing the key/value pairs in the HASH, each of which is a two-element ARRAY.

kv_sort

  my $kvs = hash(a => 1, b => 2, c => 3)->kv_sort;
  # $kvs = array(
  #          [ a => 1 ], 
  #          [ b => 2 ], 
  #          [ c => 3 ]
  #        )

  my $reversed = hash(a => 1, b => 2, c => 3)
    ->kv_sort(sub { $_[1] cmp $_[0] });
  # Reverse result as above

Like "kv", but sorted by key. A sort routine can be provided; $_[0] and $_[1] are equivalent to the usual sort variables $a and $b.

set

  $hash->set(
    key1 => $val,
    key2 => $other,
  )

Sets keys in the hash.

As of version 1.007, returns the current hash object. The return value of prior versions is unreliable.

sliced

  my $newhash = $hash->sliced(@keys);

Returns a new hash object built from the specified set of keys.

(See "get" if you only need the values.)

array_type

The class name of array-type objects that will be used to contain the results of methods returning a list.

Defaults to List::Objects::WithUtils::Array.

Subclasses can override array_type to produce different types of array objects; the method can also be queried to find out what kind of array object will be returned:

  my $type = $hash->array_type;

inflated_type

The class name that objects are blessed into when calling "inflate".

Defaults to List::Objects::WithUtils::Hash::Inflated.

inflated_rw_type

The class name that objects are blessed into when calling "inflate" with rw = 1>.

Defaults to List::Objects::WithUtils::Hash::Inflated::RW, a subclass of List::Objects::WithUtils::Hash::Inflated.

SEE ALSO

List::Objects::WithUtils

Data::Perl

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>

Portions of this code are derived from Data::Perl by Matthew Phillips (CPAN: MATTP), haarg et al

Licensed under the same terms as Perl.

cpanm List::Objects::WithUtils

perl -MCPAN -e shell
install List::Objects::WithUtils