NAME

MooX::Tag::TO_HASH - Controlled translation of Moo objects into Hashes

VERSION

version 0.06

SYNOPSIS

package My::Farm;

use Moo;
with 'MooX::Tag::TO_HASH';

has cow            => ( is => 'ro', to_hash => 1 );
has duck           => ( is => 'ro', to_hash => 'goose,if_exists', );
has horse          => ( is => 'ro', to_hash => ',if_defined', );
has hen            => ( is => 'ro', to_hash => 1, );
has secret_admirer => ( is => 'ro', );

# and somewhere else...

use Data::Dumper;
my $farm = My::Farm->new(
    cow            => 'Daisy',
    duck           => 'Frank',
    secret_admirer => 'Fluffy',
);

print Dumper $farm->TO_HASH;

# resulting in

$VAR1 = {
          'goose' => 'Frank',
          'hen' => undef,
          'cow' => 'Daisy'
        };

DESCRIPTION

MooX::Tag::TO_HASH is a Moo::Role which provides a controlled method of converting your Moo based object into a hash.

Simply mark each field that should be output with the special option to_hash when declaring it:

has field => ( is => 'ro', to_hash => 1 );

and call the "TO_HASH" method on your instantiated object.

my %hash = $obj->TO_HASH;

Fields inherited from superclasses or consumed from roles which use MooX::Tag::TO_HASH are automatically handled.

If a field's value is a plain scalar, "TO_HASH" leaves it unchanged. If it is a reference, "TO_HASH" recursively walks plain array and hash references, and converts objects via their own TO_HASH method when available. You can prevent that processing with the no_recurse option.

Modifying the generated hash

[Originally, this module recommended using a method modifier to the TO_HASH method, this is no longer recommended. See discussion under "DEPRECATED BEHAVIOR" below.].

If the class provides a _modify_hashr method (or for backwards compatibility, modify_hashr), it will be called as

$self->_modify_hashr( \%hash );

and should modify the passed hash in place.

Usage

Add the to_hash option to each field which should be included in the hash. to_hash can either take a value of 1, e.g.

has field => ( is => 'ro', to_hash => 1 );

or a string which looks like one of these:

alternate_name
alternate_name,option_flag,option_flag,...
,option_flag,option_flag,...

If alternate_name is specified, that'll be the key used in the output hash.

option_flag may be one of the following:

• if_exists

  Only output the field if it was set. This uses "Moo"'s attribute predicate (one will be added to the field if it not already specified).

  It will be output if the field is set to undef.

  A synonym for this is omit_if_empty, for compatibility with MooX::TO_JSON.

• if_defined

  Only output the field if it was set and its value is defined.

• no_recurse

  Do not recursively process the field value. Objects are left as-is instead of being converted via TO_HASH, and plain array and hash references are not walked for nested objects or other nested containers.

  (Yes, this name is backwards, but eventually a separate recurse option may become available which limits the recursion depth).

METHODS

TO_HASH

%hash = $obj->TO_HASH

This method is added to the consuming class or role.

EXAMPLES

Modifying the generated hash

package My::Test::C4;

use Moo;
with 'MooX::Tag::TO_HASH';

has cow            => ( is => 'ro', to_hash => 1 );
has duck           => ( is => 'ro', to_hash => 'goose,if_exists', );
has horse          => ( is => 'ro', to_hash => ',if_defined', );
has hen            => ( is => 'ro', to_hash => 1, );
has secret_admirer => ( is => 'ro', );

# upper case the hash keys
sub modify_hashr {
    my ( $self, $hashr ) = @_;
    $hashr->{ uc $_ } = delete $hashr->{$_} for keys %$hashr;
};

# and elsewhere:
use Data::Dumper;

print Dumper(
    My::Test::C4->new(
        cow            => 'Daisy',
        hen            => 'Ruby',
        duck           => 'Donald',
        horse          => 'Ed',
        secret_admirer => 'Nemo'
    )->TO_HASH
);

# resulting in

$VAR1 = {
          'HEN' => 'Ruby',
          'COW' => 'Daisy',
          'GOOSE' => 'Donald',
          'HORSE' => 'Ed'
        };

DEPRECATED BEHAVIOR

Using method modifiers to modify the results

Previously it was suggested that the around method modifier be used to modify the resultant hash. However, if both a child and parent class consume the MooX::Tag::TO_HASH role and the parent has modified TO_HASH, the parent's modified TO_HASH will not be run; instead the original TO_HASH will. For example

package Role {
    use Moo::Role;
    sub foo { print "Role\n" }
}

package Parent {
    use Moo;
    with 'Role';
    before 'foo' => sub { print "Parent\n" };
}

package Child {
    use Moo;
    extends 'Parent';
    with 'Role';
    before 'foo' => sub { print "Child\n" };
}

Child->new->foo;

results in

Child
Role

Note it does not output Parent.

SUPPORT

Bugs

Please report any bugs or feature requests to bug-moox-tag-to_hash@rt.cpan.org or through the web interface at: https://rt.cpan.org/Public/Dist/Display.html?Name=MooX-Tag-TO_HASH

Source

Source is available at

https://codeberg.org/djerius/p5-MooX-Tag-TO_HASH

and may be cloned from

https://codeberg.org/djerius/p5-MooX-Tag-TO_HASH.git

SEE ALSO

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

• MooX::Tag::TO_JSON - the sibling class to this one.
• MooX::TO_JSON - this is similar, but doesn't handle fields inherited from super classes or consumed from roles.

AUTHOR

Diab Jerius djerius@cfa.harvard.edu

COPYRIGHT AND LICENSE

This software is Copyright (c) 2022 by Smithsonian Astrophysical Observatory.

This is free software, licensed under:

The GNU General Public License, Version 3, June 2007