Name

Util::H2O - Hash to Object: turns hashrefs into objects with accessors for keys

Synopsis

 use Util::H2O;
 
 my $hash = h2o { foo => "bar", x => "y" }, qw/ more keys /;
 print $hash->foo, "\n";           # accessor
 $hash->x("z");                    # change value
 $hash->more("quz");               # additional keys
 
 my $struct = { hello => { perl => "world!" } };
 h2o -recurse, $struct;            # objectify nested hashrefs as well
 print $struct->hello->perl, "\n";
 
 my $obj = h2o -meth, {            # code references become methods
     what => "beans",
     cool => sub {
         my $self = shift;
         print $self->what, "\n";
     } };
 $obj->cool;                       # prints "beans"
 
 h2o -class=>'Point',-new,-meth, { # whip up a class
         angle => sub { my $self = shift; atan2($self->y, $self->x) }
     }, qw/ x y /;
 my $one = Point->new(x=>1, y=>2);
 my $two = Point->new(x=>3, y=>4);
 printf "%.3f\n", $two->angle;     # prints 0.927

Description

This module allows you to turn hashrefs into objects, so that instead of $hash->{key} you can write $hash->key, plus you get protection from typos. In addition, options are provided that allow you to whip up really simple classes.

This module exports a single function by default.

h2o @opts, $hashref, @additional_keys

@opts

If you specify an option with a value multiple times, only the last one will take effect.

-recurse

Nested hashes are objectified as well. Note that none of the other options will be applied to the nested hashes, including @additional_keys.

-meth

Any code references present in the hash will become methods.

-class => classname

Specify the class name into which to bless the object (as opposed to the default: a generated, unique package name in Util::H2O::).

Note: If you use this option, -clean defaults to false, meaning that the package will stay in Perl's symbol table and use memory accordingly, and since this function installs the accessors in the package every time it is called, if you re-use the same package name, you will get "redefined" warnings. Therefore, if you want to create multiple objects in the same package, you should probably use -new.

-new

Generates a constructor named new in the package. The constructor works as a class and instance method, and dies if it is given any arguments that it doesn't know about. If you want more advanced features, like required arguments or other validation, you should probably switch to something like Moo instead.

-clean => bool

Whether or not to clean up the generated package when the object is destroyed. Defaults to false when -class is specified, true otherwise. If this is false, be aware that the packages will stay in Perl's symbol table and use memory accordingly.

$hashref

You must supply a plain (unblessed) hash reference here. Be aware that this function does modify the original hashref(s) by blessing it.

When -clean is true (the default, unless you use -class), the hash may not contain a key named DESTROY. When -new is used, the hash may not contain a key named new.

@additional_keys

Methods will be set up for these keys even if they do not exist in the hash.

Returns

The (now blessed) $hashref.

See Also

Inspired in part by lock_keys from Hash::Util.

Many, many other modules exist to simplify object creation in Perl. This one is mine ;-P

For real OO work, I like Moo and Type::Tiny.

Author, Copyright, and License

Copyright (c) 2020 Hauke Daempfling (haukex@zero-g.net).

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

For more information see the Perl Artistic License, which should have been distributed with your copy of Perl. Try the command perldoc perlartistic or see http://perldoc.perl.org/perlartistic.html.