NAME
POE::Component::Tie - Perl extension that sends POE events on tie method invocations.
SYNOPSIS
use POE;
use POE::Component::Tie;
my $session = POE::Session->create(
inline_states => {
_start => sub {},
STORE => \&handler,
[...] # place other handlers here you want for tie method events
}
);
my $scalar;
tie($scalar, "POE::Component::Tie", $session, $poe_kernel);
$scalar = "Test!";
$poe_kernel->run();
sub handler {
print "Got STORE event";
}
DESCRIPTION
The POE::Component::Tie package allows you to tie a scalar, array, or hash, and then have the tie methods sent as events to a POE session. Since there is no way to know the name of the variable being tied, that information is not passed back to the POE event. You will need to make a POE session and handlers for each variable you want to tie with this package. It is also worth mentioning due to this, some events that may be found in both ARRAY and HASH may pass something different back. See the documentation to know what exactly to expect back.
METHODS
List of each tie method that send events.
TIESCALAR
Sends the event TIESCALAR with no arguments.
TIEARRAY
Sends the event TIEARRAY with no arguments.
TIEHASH
Sends the event TIEHASH with no arguments.
CLEAR
Sends the event CLEAR, and also sends what was contained in the variable as ARG0
in a reference.
- EXAMPLES
-
sub handler { my $clear_ref = $_[ARG0] my %hash = %{$clear_ref}; # if was a hash my @array = @{$clear_ref}; # if was an array ... }
DELETE
Sends the event DELETE, and depending on the type of variable being tied, some arguments.
- HASH
-
From the POE event,
ARG0
will contain a hash reference with the keyskey
, andvalue
. The keykey
will be the hash key, andvalue
will be the value being deleted. - ARRAY
-
For an array, it will be the same as a hash, but instead of the hash key
key
, it will beindex
.
- EXAMPLE
-
sub handler { my $deleted = $_[ARG0]; print "The index: $deleted->{index} was deleted, the value was $deleted->{value}\n"; # array print "The key: $deleted->{key} was deleted, the value was $deleted->{value}\n"; # hash ... }
DESTROY
Not implemented.
EXISTS
Sends the event EXISTS, and depending on the type of variable being tied, some arguments.
- HASH
-
From the POE event,
ARG0
will contain a hash reference with the keyskey
, andexists
. The keykey
is the key of the hash, whileexists
is the return value ofexists
on that key. - ARRAY
-
For an array, it will be the same as a hash, but instead of the hash key
key
, it will beindex
.
- EXAMPLE
-
sub handler { my $exists = $_[ARG0]; print "$exists->{key} return value from exists is $exists->{exists}\n"; # hash print "$exists->{index} return value from exists is $exists->{exists}\n"; # array ... }
EXTEND
Sends the event EXTEND, and will send as ARG0
, the size extended.
- EXAMPLE
-
sub handler { my $size = $_[ARG0]; ... }
FETCH
Sends the event FETCH, and depending on the type of variable being tied, some arguments.
- SCALAR
-
From the POE event,
ARG0
will contain what is being fetched. - HASH
-
From the POE event,
ARG0
will contain a hash reference with the keyskey
andvalue
, which will contain the hash key and the value of that key. - ARRAY
-
From the POE event,
ARG0
will contain a hash reference with the keysindex
andvalue
, which will contain the index position and value of that position.
- EXAMPLES
-
# Scalar sub handler { my $fetched = $_[ARG0]; print "got $fetched\n"; } # Array or Hash sub handler { my $fetched = $_[ARG0]; print "Fetched: $fetched->{value}\n"; ... }
FETCHSIZE
Sends the event FETCHSIZE, and will send as ARG0
, the size of the array.
- EXAMPLE
-
sub handler { my $size = $_[ARG0]; ... }
FIRSTKEY
Sends the event FIRSTKEY, and will send as ARG0
, the first key.
- EXAMPLE
-
sub handler { my $key = $_[ARG0]; ... }
NEXTKEY
Sends the event NEXTKEY, and will send as ARG0
, the next key.
- EXAMPLE
-
sub handler { my $key = $_[ARG0]; ... }
POP
Sends the event POP, and will send as ARG0
, what was returned from pop.
- EXAMPLE
-
sub handler { my $popped = $_[ARG0]; ... }
PUSH
Sends the event PUSH, ARG0
will contain a hash reference with the keys list
, and size
. The key list
will be an array of what was pushed on, and return
will be the value returned from push
.
- EXAMPLE
-
sub handler { my $pushed = $_[ARG0]; print "Caught PUSH: List pushed: '@{$pushed->{list}}', return value: $pushed->{return}\n"; ... }
SCALAR
Not implimented yet. New in Perl 5.8.3
SHIFT
Sends the event SHIFT, and will send as ARG0
, what was returned from shift.
- EXAMPLE
-
sub handler { my $shifted = $_[ARG0]; ... }
SPLICE
Sends the event SPLICE, nothing returned, yet. TODO
- EXAMPLE
-
sub handler { print "Got splice\n"; ... }
STORE
Sends the event STORE, and depending on the type of variable being tied, some arguments.
- SCALAR
-
From the POE event,
ARG0
will what the value of the scalar used to be, whileARG1
will be the new value. - HASH
-
From the POE event,
ARG0
will contain will contain a hash reference with the keyskey
, andvalue
, which will contain the value of what the value used to be. WhileARG1
will contain a hash reference with the same structure, except its keyvalue
will contain the new value of the hash. - ARRAY
-
For an array, it will be the same as a hash, but instead of the hash key
key
, it will beindex
.
- EXAMPLES
-
# Scalar sub handler { my ($orig, $new) = @_[ARG0, ARG1]; ... } # Array or Hash sub handler { my ($orig, $new) = @_[ARG0, ARG1]; print "$orig->{value} now $new->{value}\n"; ... }
STORESIZE
Sends the event FIRSTKEY the size stored as ARG0
.
- EXAMPLE
-
sub handler { my $size = $_[ARG0]; print "Got STORESIZE of $size\n"; ... }
UNSHIFT
Sends the event UNSHIFT, ARG0
will contain a hash reference with the keys list
, and size
. The key list
will be an array of what was unshifted on, and return
will be the value returned from unshift
.
- EXAMPLE
-
sub handler { my $unshifted = $_[ARG0]; print "Caught UNSHIFT: List unshifted: '@{$unshifted->{list}}', return value: $unshifted->{return}\n"; ... }
UNTIE
Sends the event UNTIE with no arguments.
- EXAMPLE
-
sub handler { print "Got UNTIE\n"; }
EXPORT
None by default.
BUGS
SPLICE
does not pass any arguments to the SPLICE event, like it should.
If DESTROY
method sends event to POE, the following warning is issued: '(in cleanup) Can't call method "post" on an undefined value...
'. It would be nice to be able to send an event on DESTROY
.
TODO
- Add
TIEHANDLE
and it's methods. - Add
SCALAR
for hashes (5.8.3 and higher). - SPLICE needs to pass arguments.
- More tests
- Documentation, Documentation, Documentation!
VERSION
This is an alpha version release. Please use at your own risk. Bug reports, patches, or comments, please send an email to the address below.
SEE ALSO
AUTHOR
Larry Shatzer, Jr., <larrysh@cpan.org>
COPYRIGHT AND LICENSE
Copyright 2004 by Larry Shatzer, Jr.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.