NAME
Hash::Wrap - create on-the-fly objects from hashes
VERSION
version 1.03
SYNOPSIS
use Hash::Wrap;
my $result = wrap_hash( { a => 1 } );
print $result->a; # prints
print $result->b; # throws
# import two constructors, <cloned> and <copied> with different behaviors.
use Hash::Wrap
{ -as => 'cloned', clone => 1},
{ -as => 'copied', copy => 1 };
my $cloned = cloned( { a => 1 } );
print $cloned->a;
my $copied = copied( { a => 1 } );
print $copied->a;
# don't pollute your namespace
my $wrap;
use Hash::Wrap { -as => \$wrap};
my $obj = $wrap->( { a => 1 } );
# apply constructors to hashes two levels deep into the hash
use Hash::Wrap { -recurse => 2 };
# apply constructors to hashes at any level
use Hash::Wrap { -recurse => -1 };
DESCRIPTION
Hash::Wrap creates objects from hashes, providing accessors for hash elements. The objects are hashes, and may be modified using the standard Perl hash operations and the object's accessors will behave accordingly.
Why use this class? Sometimes a hash is created on the fly and it's too much of a hassle to build a class to encapsulate it.
sub foo () { ... ; return { a => 1 }; }
With Hash::Wrap
:
use Hash::Wrap;
sub foo () { ... ; return wrap_hash( { a => 1 ); }
my $obj = foo ();
print $obj->a;
Elements can be added or removed to the object and accessors will track them. The object may be made immutable, or may have a restricted set of attributes.
There are many similar modules on CPAN (see "SEE ALSO" for comparisons).
What sets Hash::Wrap apart is that it's possible to customize object construction and accessor behavior:
It's possible to use the passed hash directly, or make shallow or deep copies of it.
Accessors can be customized so that accessing a non-existent element can throw an exception or return the undefined value.
On recent enough versions of Perl, accessors can be lvalues, e.g.
$obj->existing_key = $value;
USAGE
Simple Usage
use
'ing Hash::Wrap without options imports a subroutine called wrap_hash which takes a hash, blesses it into a wrapper class and returns the hash:
use Hash::Wrap;
my $h = wrap_hash { a => 1 };
print $h->a, "\n"; # prints 1
[API change @ v1.0] The passed hash must be a plain hash (i.e. not an object or blessed hash). To pass an object, you must specify a custom clone subroutine returning a plain hashref via the "-clone" option.
The wrapper class has no constructor method, so the only way to create an object is via the wrap_hash subroutine. (See "WRAPPER CLASSES" for more about wrapper classes) If wrap_hash is called without arguments, it will create a hash for you.
Advanced Usage
wrap_hash is an awful name for the constructor subroutine
So rename it:
use Hash::Wrap { -as => "a_much_better_name_for_wrap_hash" };
$obj = a_much_better_name_for_wrap_hash( { a => 1 } );
The Wrapper Class name matters
If the class name matters, but it'll never be instantiated except via the imported constructor subroutine:
use Hash::Wrap { -class => 'My::Class' };
my $h = wrap_hash { a => 1 };
print $h->a, "\n"; # prints 1
$h->isa( 'My::Class' ); # returns true
or, if you want it to reflect the current package, try this:
package Foo;
use Hash::Wrap { -class => '-target', -as => 'wrapit' };
my $h = wrapit { a => 1 };
$h->isa( 'Foo::wrapit' ); # returns true
Again, the wrapper class has no constructor method, so the only way to create an object is via the generated subroutine.
The Wrapper Class needs its own class constructor method
To generate a wrapper class which can be instantiated via its own constructor method:
use Hash::Wrap { -class => 'My::Class', -new => 1 };
The default wrap_hash constructor subroutine is still exported, so
$h = My::Class->new( { a => 1 } );
and
$h = wrap_hash( { a => 1 } );
do the same thing.
To give the constructor method a different name:
use Hash::Wrap { -class => 'My::Class', -new => '_my_new' };
To prevent the constructor subroutine from being imported:
use Hash::Wrap { -as => undef, -class => 'My::Class', -new => 1 };
A stand alone Wrapper Class
To create a stand alone wrapper class,
package My::Class;
use Hash::Wrap { -base => 1 };
1;
And later...
use My::Class;
$obj = My::Class->new( \%hash );
It's possible to modify the constructor and accessors:
package My::Class;
use Hash::Wrap { -base => 1, -new => 'new_from_hash', -undef => 1 };
1;
Recursive wrapping
Hash::Wrap can automatically wrap nested hashes using the "-recurse" option.
Using the original hash
The "-recurse" option allows mapping nested hashes onto chained methods, e.g.
use Hash::Wrap { -recurse => -1, -as => 'recwrap' };
my %hash = ( a => { b => { c => 'd' } } );
my $wrap = recwrap(\%hash);
$wrap->a->b->c eq 'd'; # true
Along the way, %hash, $hash{a}, $hash{b}, $hash{c} are all blessed into wrapping classes.
Copying the original hash
If "-copy" is also specified, then the relationship between the nested hashes in the original hash and those hashes retrieved by wrapper methods depends upon what level in the structure has been wrapped. For example,
use Hash::Wrap { -recurse => -1, -copy => 1, -as => 'copyrecwrap' };
use Scalar::Util 'refaddr';
my %hash = ( a => { b => { c => 'd' } } );
my $wrap = copyrecwrap(\%hash);
refaddr( $wrap ) != refaddr( \%hash );
Because the $wrap->a
method hasn't been called, then the $hash{a} structure has yet to be wrapped, so, using $wrap
as a hash,
refaddr( $wrap->{a} ) == refaddr( $hash{a} );
However,
# invoking $wrap->a wraps a copy of $hash{a} because of the -copy
# attribute
refaddr( $wrap->a ) != refaddr( $hash{a} );
# so $wrap->{a} is no longer the same as $hash{a}:
refaddr( $wrap->{a} ) != refaddr( $hash{a} );
refaddr( $wrap->{a} ) == refaddr( $wrap->a );
Importing into an alternative package
Normally the constructor is installed into the package importing Hash::Wrap
. The -into
option can change that:
package This::Package;
use Hash::Wrap { -into => 'Other::Package' };
will install Other::Package::wrap_hash.
OPTIONS
Hash::Wrap works at import time. To modify its behavior pass it options when it is use
'd:
use Hash::Wrap { %options1 }, { %options2 }, ... ;
Multiple options hashes may be passed; each hash specifies options for a separate constructor or class.
For example,
use Hash::Wrap
{ -as => 'cloned', clone => 1},
{ -as => 'copied', copy => 1 };
creates two constructors, cloned
and copied
with different behaviors.
Constructor
-as
=> subroutine name ||undef
|| scalar ref ||-return
-
(This defaults to the string
wrap_hash
)If the argument is
a string (but not the string
-return
)Import the constructor subroutine with the given name.
undefined
Do not import the constructor. This is usually only used with the "-new" option.
a scalar ref
Do not import the constructor. Store a reference to the constructor into the scalar.
The string
-return
.Do not import the constructor. The constructor subroutine(s) will be returned from
Hash::Import
'simport
method. This is a fairly esoteric way of doing things:require Hash::Wrap; ( $copy, $clone ) = Hash::Wrap->import( { -as => '-return', copy => 1 }, { -as => '-return', clone => 1 } );
A list is always returned, even if only one constructor is created.
-copy
=> boolean-
If true, the object will store the data in a shallow copy of the hash. By default, the object uses the hash directly.
-clone
=> boolean | coderef-
Store the data in a deep copy of the hash. if true, "dclone" in Storable is used. If a coderef, it will be called as
$clone = $coderef->( $hash )
$coderef
must return a plain hashref.By default, the object uses the hash directly.
-immutable
=> boolean-
The object's attributes and values are locked and may not be altered. Note that this locks the underlying hash.
-lockkeys
=> boolean | arrayref-
If the value is true, the object's attributes are restricted to the existing keys in the hash. If it is an array reference, it specifies which attributes are allowed, in addition to existing attributes. The attribute's values are not locked. Note that this locks the underlying hash.
-into
=> package name-
The name of the package in which to install the constructor. By default it's that of the caller.
Accessors
-undef
=> boolean-
Normally an attempt to use an accessor for an non-existent key will result in an exception. This option causes the accessor to return
undef
instead. It does not create an element in the hash for the key. -lvalue
=> flag-
If non-zero, the accessors will be lvalue routines, e.g. they can change the underlying hash value by assigning to them:
$obj->attr = 3;
The hash entry must already exist or this will throw an exception.
lvalue subroutines are only available on Perl version 5.16 and later.
If
-lvalue = 1
this option will silently be ignored on earlier versions of Perl.If
-lvalue = -1
this option will cause an exception on earlier versions of Perl. -recurse
=> integer level-
Normally only the top level hash is wrapped in a class. This option specifies how many levels deep into the hash hashes should be wrapped. For example, if
%h = ( l => 0, a => { l => 1, b => { l => 2, c => { l => 3 } } } }; use Hash::Wrap { -recurse => 0 }; $h->l # => 0 $h->a->l # => ERROR use Hash::Wrap { -recurse => 1 }; $h->l # => 0 $h->a->l # => 1 $h->a->b->l # => ERROR use Hash::Wrap { -recurse => 2 }; $h->l # => 0 $h->a->l # => 1 $h->a->b->l # => 2 $h->a->b->c->l # => ERROR
For infinite recursion, set
-recurse
to-1
.Constructors built for deeper hash levels will not heed the
-as_scalar_ref
,-class
,-base
, or-as
attributes.
Class
-base
=> boolean-
If true, the enclosing package is converted into a proxy wrapper class. This should not be used in conjunction with
-class
. See "A stand alone Wrapper Class". -class
=> class name-
A class with the given name will be created and new objects will be blessed into the specified class by the constructor subroutine. The new class will not have a constructor method.
If class name is the string
-target
(or, deprecated,-caller
), then the class name is set to the fully qualified name of the constructor, e.g.package Foo; use Hash::Wrap { -class => '-target', -as => 'wrap_it' };
results in a class name of
Foo::wrap_it
.If not specified, the class name will be constructed based upon the options. Do not rely upon this name to determine if an object is wrapped by Hash::Wrap.
-new
=> boolean | Perl Identifier-
Add a class constructor method.
If
-new
is a true boolean value, the method will be callednew
. Otherwise-new
specifies the name of the method.
Extra Class Methods
-defined
=> boolean | Perl Identifier-
Add a method which returns true if the passed hash key is defined or does not exist. If
-defined
is a true boolean value, the method will be calleddefined
. Otherwise it specifies the name of the method. For example,use Hash::Wrap { -defined => 1 }; $obj = wrap_hash( { a => 1, b => undef } ); $obj->defined( 'a' ); # TRUE $obj->defined( 'b' ); # FALSE $obj->defined( 'c' ); # FALSE
or
use Hash::Wrap { -defined => 'is_defined' }; $obj = wrap_hash( { a => 1 } ); $obj->is_defined( 'a' );
-exists
=> boolean | Perl Identifier-
Add a method which returns true if the passed hash key exists. If
-exists
is a boolean, the method will be calledexists
. Otherwise it specifies the name of the method. For example,use Hash::Wrap { -exists => 1 }; $obj = wrap_hash( { a => 1 } ); $obj->exists( 'a' );
or
use Hash::Wrap { -exists => 'is_present' }; $obj = wrap_hash( { a => 1 } ); $obj->is_present( 'a' );
-predicate
=> boolean-
This adds the more traditionally named predicate methods, such as
has_foo
for attributefoo
. Note that this option makes any elements which begin withhas_
unavailable via the generated accessors. -methods
=> { method name => code reference, ... }-
Install the passed code references into the class with the specified names. These override any attributes in the hash. For example,
use Hash::Wrap { -methods => { a => sub { 'b' } } }; $obj = wrap_hash( { a => 'a' } ); $obj->a; # returns 'b'
WRAPPER CLASSES
A wrapper class has the following characteristics.
It has the methods
DESTROY
,AUTOLOAD
andcan
.It will have other methods if the
-undef
and-exists
options are specified. It may have other methods if it is a stand alone class.It will have a constructor if either of
-base
or-new
is specified.
Wrapper Class Limitations
Wrapper classes have
DESTROY
,can
method, andAUTOLOAD
methods, which will mask hash keys with the same names.Classes which are generated without the
-base
or-new
options do not have a class constructor method, e.gClass->new()
will not return a new object. The only way to instantiate them is via the constructor subroutine generated via Hash::Wrap. This allows the underlying hash to have anew
attribute which would otherwise be masked by the constructor.
LIMITATIONS
Lvalue accessors
Lvalue accessors are available only on Perl 5.16 and later.
Accessors for deleted hash elements
Accessors for deleted elements are not removed. The class's can
method will return undef
for them, but they are still available in the class's stash.
Wrapping immutable structures
Locked (e.g. immutable) hashes cannot be blessed into a class. This will cause Hash::Wrap to fail if it is asked to work directly (without cloning or copying) on a locked hash or recursive wrapping is specified and the hash contains nested locked hashes.
To create an immutable Hash::Wrap object from an immutable hash, use the "-copy" and "-immutable" attributes. The "-copy" attribute performs a shallow copy of the hash which is then locked by "-immutable". The default "-clone" option will not work, as it will clone the immutability of the input hash.
Adding the "-recurse" option will properly create an immutable wrapped object when used on locked hashes. It does not suffer the issue described in "Eventual immutability in nested structures" in "Bugs".
Cloning with recursion
Cloning by default uses "dclone" in Storable, which performs a deep clone of the passed hash. In recursive mode, the clone operation is performed at every wrapping of a nested hash, causing some data to be repeatedly cloned. This does not create a memory leak, but it is inefficient. Consider using "-copy" instead of "-clone" with "-recurse".
BUGS
Eventual immutability in nested structures
Immutability is added to mutable nested structures as they are traversed via method calls. This means that the hash underlying the wrapper object is not fully immutable until all nested hashes have been visited via methods.
For example,
use Hash::Wrap { -immutable => 1, -recurse => -1, -as 'immutable' };
my $wrap = immutable( { a => { b => 2 } } );
$wrap->{a} = 11; # expected fail: IMMUTABLE
$wrap->{a}{b} = 22; # unexpected success: NOT IMMUTABLE
$wrap->a;
$wrap->{a}{b} = 33; # expected fail: IMMUTABLE; $wrap->{a} is now locked
EXAMPLES
Existing keys are not compatible with method names
If a hash key contains characters that aren't legal in method names, there's no way to access that hash entry. One way around this is to use a custom clone subroutine which modifies the keys so they are legal method names. The user can directly insert a non-method-name key into the Hash::Wrap
object after it is created, and those still have a key that's not available via a method, but there's no cure for that.
SEE ALSO
Here's a comparison of this module and others on CPAN.
- Hash::Wrap (this module)
-
core dependencies only
object tracks additions and deletions of entries in the hash
optionally applies object paradigm recursively
accessors may be lvalue subroutines
accessing a non-existing element via an accessor throws by default, but can optionally return
undef
can use custom package
can copy/clone existing hash. clone may be customized
can add additional methods to the hash object's class
optionally stores the constructor in a scalar
optionally provides per-attribute predicate methods (e.g.
has_foo
)optionally provides methods to check an attribute existence or whether its value is defined
can create immutable objects
- Object::Result
-
As you might expect from a DCONWAY module, this does just about everything you'd like. It has a very heavy set of dependencies.
- Hash::AsObject
-
core dependencies only
applies object paradigm recursively
accessing a non-existing element via an accessor creates it
- Data::AsObject
-
moderate dependency chain (no XS?)
applies object paradigm recursively
accessing a non-existing element throws
- Class::Hash
-
core dependencies only
only applies object paradigm to top level hash
can add generic accessor, mutator, and element management methods
accessing a non-existing element via an accessor creates it (not documented, but code implies it)
can()
doesn't work
- Hash::Inflator
-
core dependencies only
accessing a non-existing element via an accessor returns undef
applies object paradigm recursively
- Hash::AutoHash
-
moderate dependency chain. Requires XS, tied hashes
applies object paradigm recursively
accessing a non-existing element via an accessor creates it
- Hash::Objectify
-
light dependency chain. Requires XS.
only applies object paradigm to top level hash
accessing a non-existing element throws, but if an existing element is accessed, then deleted, accessor returns undef rather than throwing
can use custom package
- Data::OpenStruct::Deep
-
uses source filters
applies object paradigm recursively
- Object::AutoAccessor
-
light dependency chain
applies object paradigm recursively
accessing a non-existing element via an accessor creates it
- Data::Object::Autowrap
-
core dependencies only
no documentation
- Object::Accessor
-
core dependencies only
only applies object paradigm to top level hash
accessors may be lvalue subroutines
accessing a non-existing element via an accessor returns
undef
by default, but can optionally throw. Changing behavior is done globally, so all objects are affected.accessors must be explicitly added.
accessors may have aliases
values may be validated
invoking an accessor may trigger a callback
- Object::Adhoc
-
minimal non-core dependencies (Exporter::Shiny)
uses Class::XSAccessor if available
only applies object paradigm to top level hash
provides separate getter and predicate methods, but only for existing keys in hash.
hash keys are locked.
operates directly on hash.
- Util::H2O
-
has a cool name
core dependencies only
locks hash by default
optionally recurses into the hash
does not track changes to hash
can destroy class
can add methods
can use custom package
SUPPORT
Bugs
Please report any bugs or feature requests to bug-hash-wrap@rt.cpan.org or through the web interface at: https://rt.cpan.org/Public/Dist/Display.html?Name=Hash-Wrap
Source
Source is available at
https://gitlab.com/djerius/hash-wrap
and may be cloned from
https://gitlab.com/djerius/hash-wrap.git
AUTHOR
Diab Jerius <djerius@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2017 by Smithsonian Astrophysical Observatory.
This is free software, licensed under:
The GNU General Public License, Version 3, June 2007