Hash::Wrap - create lightweight on-the-fly objects from hashes
version 0.01
use Hash::Wrap; sub foo { wrap_hash { a => 1 }; } $result = foo(); print $result->a; # prints print $result->b; # throws # create two constructors, <cloned> and <copied> with different # behaviors. does not import C<wrap_hash> use Hash::Wrap { -as => 'cloned', clone => 1}, { -as => 'copied', copy => 1 };
This module provides constructors which create light-weight objects from existing hashes, allowing access to hash elements via methods (and thus avoiding typos). Attempting to access a non-existent element via a method will result in an exception.
Hash elements may be added to or deleted from the object after instantiation using the standard Perl hash operations, and changes will be reflected in the object's methods. For example,
$obj = wrap_hash( { a => 1, b => 2 ); $obj->c; # throws exception $obj->{c} = 3; $obj->c; # returns 3 delete $obj->{c}; $obj->c; # throws exception
To prevent modification of the hash, consider using the lock routines in Hash::Util on the object.
The methods act as both accessors and setters, e.g.
$obj = wrap_hash( { a => 1 } ); print $obj->a; # 1 $obj->a( 3 ); print $obj->a; # 3
Only hash keys which are legal method names will be accessible via object methods.
By default Hash::Wrap exports a wrap_hash subroutine which, given a hashref, blesses it directly into the Hash::Wrap::Class class.
Hash::Wrap
wrap_hash
The constructor may be customized to change which class the object is instantiated from, and how it is constructed from the data. For example,
use Hash::Wrap { -as => 'return_cloned_object', -clone => 1 };
will create a constructor which clones the passed hash and is imported as return_cloned_object. To import it under the original name, wrap_hash, leave out the -as option.
return_cloned_object
-as
The following options are available to customize the constructor.
This is optional, and imports the constructor with the given name. If not specified, it defaults to wrap_hash.
-class
The object will be blessed into the specified class. If the class should be created on the fly, specify the -create option. See "Object Classes" for what is expected of the object classes. This defaults to Hash::Wrap::Class.
-create
Hash::Wrap::Class
If true, and -class is specified, a class with the given name will be created.
-copy
If true, the object will store the data in a shallow copy of the hash. By default, the object uses the hash directly.
-clone
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 )
By default, the object uses the hash directly.
An object class has the following properties:
The class must be a subclass of Hash::Wrap::Base.
Hash::Wrap::Base
The class typically does not provide any methods, as they would mask a hash key of the same name.
The class need not have a constructor. If it does, it is passed a hashref which it should bless as the actual object. For example:
package My::Result; use parent 'Hash::Wrap::Base'; sub new { my ( $class, $hash ) = @_; return bless $hash, $class; }
This excludes having a hash key named new.
new
Hash::Wrap::Base provides an empty DESTROY method, a can method, and an AUTOLOAD method. They will mask hash keys with the same names.
DESTROY
can
AUTOLOAD
Here's a comparison of this module and others on CPAN.
core dependencies only
only applies object paradigm to top level hash
accessing a non-existing element via an accessor throws
can use custom package
can copy/clone existing hash. clone may be customized
As you might expect from a DCONWAY module, this does just about everything you'd like. It has a very heavy set of dependencies.
applies object paradigm recursively
accessing a non-existing element via an accessor creates it
moderate dependency chain (no XS?)
accessing a non-existing element throws
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
can()
accessing a non-existing element via an accessor returns undef
moderate dependency chain. Requires XS, tied hashes
light dependency chain. Requires XS.
accessing a non-existing element throws, but if an existing element is accessed, then deleted, accessor returns undef rather than throwing
uses source filters
light dependency chain
no documentation
You can make new bug reports, and view existing ones, through the web interface at https://rt.cpan.org/Public/Dist/Display.html?Name=Hash-Wrap.
Diab Jerius <djerius@cpan.org>
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
To install Hash::Wrap, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Hash::Wrap
CPAN shell
perl -MCPAN -e shell install Hash::Wrap
For more information on module installation, please visit the detailed CPAN module installation guide.