view release on metacpan or  search on metacpan

lib/Bot/ChatBots/Weak.pod  view on Meta::CPAN

=pod

=encoding utf8

=head1 NAME

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

=head1 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;


=head1 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 L<Scalar::Util/weaken>, so that you don't have
to worry about circular references.

Additionally, when some JSON encoder tries to encode this object calling
L</TO_JSON>, it will get C<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 L<Mojolicious> application, you
might want to save a reference to the C<$app> or to the controller C<$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 L<Minion> queue.

=head1 METHODS


=head2 B<< clone >>

   my $new_object = $object->clone;

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

=head2 B<< get >>

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

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

=head2 B<< get_multiple >>

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

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

=head2 B<< new >>

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

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

Returns an object that can be used as a hash reference. If you want to