PrePAN

Sign in to PrePAN

Hash::Wrap (formerly Return::Object) create lightweight on-the-fly objects from hashes

Good

Synopsis

use Hash::Wrap;

sub foo {
  wrap_hash{ a => 1 };
}

$result = foo();
print $result->a;  # prints
print $result->b;  # throws

Description

UPDATE

This module is now known as Hash::Wrap

The text below represents the original module, Return::Object. Please see the github repo for the current documentation.

DESCRIPTION

This module provides routines which encapsulate a hash as an object. The object provides methods for keys in the hash; attempting to access a non-existent key via a method will cause an exception.

The impetus for this was to encapsulate data returned from a subroutine or method (hence the name). Returning a bare hash can lead to bugs if there are typos in hash key names when accessing the hash.

It is not necessary for the hash to be fully populated when the object is created. The underlying hash may be manipulated directly, and changes will be reflected in the object's methods. To prevent this, consider using the lock routines in Hash::Util on the object after creation.

Only hash keys which are legal method names will be accessible via object methods.

Object construction and constructor customization

By default Object::Return exports a return_object constructor which, given a hashref, blesses it directly into the Return::Object::Class class.

The constructor may be customized to change which class the object is instantiated from, and how it is constructed from the data. Return::Object uses Exporter::Tiny to perform the customization. For example,

use Return::Object
  return_object => { -as => 'return_cloned_object',
                     -clone => 1 };

will create a version of return_object which clones the passed hash and is imported as return_cloned_object. To import it under the original name, return_object, leave out the -as option.

The following options are available to customize the constructor.

  • -as => subroutine name

    This is optional, and imports the customized version of return_object with the given name.

  • -class => class name

    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 Object::Return::Class.

  • -create => boolean

    If true, and -class is specified, a class with the given name will be 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

    If true, the object will store the data in a deep copy of the hash, made with "dclone" in Storeable. By default, the object uses the hash directly.

Object Classes

An object class has the following properties:

  • The class must be a subclass of Return::Object::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 'Return::Object::Base';
    
    
    sub new {
      my  ( $class, $hash ) = @_;
      return bless $hash, $class;
    }
    

    This excludes having a hash key named new.

Return::Object::Base provides an empty DESTROY method, a can method, and an AUTOLOAD method. They will mask hash keys with the same names.

BUGS AND LIMITATIONS

You can make new bug reports, and view existing ones, through the web interface at https://rt.cpan.org/Public/Dist/Display.html?Name=Return-Object.

SEE ALSO

Please see those modules/websites for more information related to this module.

AUTHOR

Diab Jerius

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

Comments

Another one for SEE ALSO: Hash::Objectify
Thanks!

I've discovered a few more; and have updated the docs in the repo
This module is more general than the use case which precipitated writing this module, so I've renamed it to Hash::Wrap. I've updated the link to the repo.

Please sign up to post a review.