/ 
Bot-ChatBots-0.014
River stage one • 4 direct dependents • 4 total dependents
/ Bot::ChatBots::Weak

NAME

Bot::ChatBots::Weak - Class for weak references

SYNOPSIS

use Bot::ChatBots::Weak;
my $object = Bot::ChatBots::Weak->new(
   what => $ref1,
   hey  => $ref2,
   look => 'not a reference',
);
$object->set(ahoy => $ref3);

# it's a hash reference inside
$object->{what}->frobozz; # called on $ref1 if still alive

# TO_JSON always returns undef
my $will_be_undef = $object->TO_JSON;

DESCRIPTION

This module provides a little wrapper class to keep things you want to be as weak as possible.

The constructor takes either a hash reference or key/value pairs, and will save it internally (the object is a hash reference). All references in values will be weakened via "weaken" in Scalar::Util, so that you don't have to worry about circular references.

Additionally, when some JSON encoder tries to encode this object calling "TO_JSON", it will get undef back. This comes handy if you want to e.g. defer some processing and put the whole thing in a queue, while still getting rid of things that will not make sense any more while "on the other side of the queue".

For example, while defining a hook for a Mojolicious application, you might want to save a reference to the $app or to the controller $c for usage along the local line. This puts you at risk of creating circular references and more importantly these two object will not exist any more if you e.g. defer processing in a Minion queue.

METHODS

clone

my $new_object = $object->clone;

Shallow copy of the initial $object, keeping the weak behaviour.

get

my $value = $object->get($key);

Method equivalent to $object->{$key}. Remember that the object is a hash reference, so you can do that directly!

get_multiple

my @values = $object->get_multiple(@keys);

Method equivalent to @{$object}{@keys}. Remember that the object is a hash reference, so you can do that directly!

new

my $object = Bot::ChatBots::Weak->new(%kvpairs);
my $object = Bot::ChatBots::Weak->new(\%kvpairs);

Returns a Weak object based on the provided key/value pairs in %kvpairs. Every reference in values that is stored in $object is weakened via Scalar::Util/weaken.

Returns an object that can be used as a hash reference. If you want to add/change a key's value, it's strongly suggested to use "set" below or you might lose the weakening.

set

$object->set(%kvpairs); # OR
$object->set(\%kvpairs);

Set key/value pairs according to what's in %kvpairs. Every value that is a reference is stored in a weakened way (i.e. via "weaken" in Scalar::Util).

You MUST use this method for setting values, otherwise the weak behaviour is not guaranteed (unless you do it by yourself, which is kind of weird).

Returns $object for possible chaining.

TO_JSON

my $this_is_undef = $object->TO_JSON;

Return undef. This will be called by JSON encoders when configured to do so for blessed objects; the provided values avoids freezing any value held by this object.

SEE ALSO

Bot::ChatBots.

AUTHOR

Flavio Poletti <polettix@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2016 by Flavio Poletti <polettix@cpan.org>

This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.