.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "POE::Filter::Reference 3pm"
.TH POE::Filter::Reference 3pm "2012-05-15" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
POE::Filter::Reference \- freeze and thaw arbitrary Perl data
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  #!perl
\&
\&  use YAML;
\&  use POE qw(Wheel::ReadWrite Filter::Reference);
\&
\&  POE::Session\->create(
\&    inline_states => {
\&      _start => sub {
\&        pipe(my($read, $write)) or die $!;
\&        $_[HEAP]{io} = POE::Wheel::ReadWrite\->new(
\&          InputHandle => $read,
\&          OutputHandle => $write,
\&          Filter => POE::Filter::Reference\->new(),
\&          InputEvent => "got_perl_data",
\&        );
\&
\&        $_[HEAP]{io}\->put(
\&          { key_1 => 111, key_2 => 222 }
\&        );
\&      },
\&      got_perl_data => sub {
\&        print "Got data:\en", YAML::Dump($_[ARG0]);
\&        print "Bye!\en";
\&        delete $_[HEAP]{io};
\&      }
\&    }
\&  );
\&
\&  POE::Kernel\->run();
\&  exit;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
POE::Filter::Reference allows programs to send and receive arbitrary
Perl data structures without worrying about a line protocol.  Its
\&\fIput()\fR method serializes Perl data into a byte stream suitable for
transmission.  \fIget_one()\fR parses the data structures back out of such a
stream.
.PP
By default, POE::Filter::Reference uses Storable to do its magic.  A
different serializer may be specified at construction time.
.SH "PUBLIC FILTER METHODS"
.IX Header "PUBLIC FILTER METHODS"
POE::Filter::Reference deviates from the standard POE::Filter \s-1API\s0 in
the following ways.
.SS "new [\s-1SERIALIZER\s0 [, \s-1COMPRESSION\s0 [, \s-1NO_FATALS\s0]]]"
.IX Subsection "new [SERIALIZER [, COMPRESSION [, NO_FATALS]]]"
\&\fInew()\fR creates and initializes a POE::Filter::Reference object.  It
will use Storable as its default \s-1SERIALIZER\s0 if none other is
specified.
.PP
If \s-1COMPRESSION\s0 is true, Compress::Zlib will be called upon to reduce
the size of serialized data.  It will also decompress the incoming
stream data.
.PP
If \s-1NO_FATALS\s0 is true, messages will be thawed inside a block eval.  By
default, however, \fIthaw()\fR is allowed to die normally.  If an error
occurs while \s-1NO_FATALS\s0 is in effect, POE::Filter::Reference will
return a string containing the contents of $@ at the time the eval
failed.  So when using \s-1NO_FATALS\s0, it's important to check whether
input is really a reference:
.PP
.Vb 9
\&  sub got_reference {
\&    my $message = $_[ARG0];
\&    if (ref $message) {
\&      print "Got data:\en", YAML::Dump($message);
\&    }
\&    else {
\&      warn "Input decode error: $message\en";
\&    }
\&  }
.Ve
.PP
Any class that supports \fInfreeze()\fR (or \fIfreeze()\fR) and \fIthaw()\fR may be used
as a \s-1SERIALIZER\s0.  If a \s-1SERIALIZER\s0 implements both \fInfreeze()\fR and
\&\fIfreeze()\fR, then the \*(L"network\*(R" version will be used.
.PP
\&\s-1SERIALIZER\s0 may be a class name:
.PP
.Vb 2
\&  # Use Storable explicitly, specified by package name.
\&  my $filter = POE::Filter::Reference\->new("Storable");
\&
\&  # Use YAML instead.  Compress its output, as it may be verbose.
\&  my $filter = POE::Filter::Reference\->new("YAML", 1);
.Ve
.PP
\&\s-1SERIALIZER\s0 may also be an object:
.PP
.Vb 3
\&  # Use an object.
\&  my $serializer = Data::Serializer::Something\->new();
\&  my $filter = POE::Filter::Reference\->new($serializer);
.Ve
.PP
If \s-1SERIALIZER\s0 is omitted or undef, the Reference filter will try to
use Storable, FreezeThaw, and \s-1YAML\s0 in that order.
POE::Filter::Reference will die if it cannot find one of these
serializers, but this rarely happens now that Storable and \s-1YAML\s0 are
bundled with Perl.
.PP
.Vb 3
\&  # A choose\-your\-own\-serializer adventure!
\&  # We\*(Aqll still deal with compressed data, however.
\&  my $filter = POE::Filter::Reference\->new(undef, 1);
.Ve
.PP
POE::Filter::Reference will try to compress frozen strings and
uncompress them before thawing if \s-1COMPRESSION\s0 is true.  It uses
Compress::Zlib for this.  POE::Filter::Reference doesn't need
Compress::Zlib if \s-1COMPRESSION\s0 is false.
.PP
\&\fInew()\fR will try to load any classes it needs.
.SH "SERIALIZER API"
.IX Header "SERIALIZER API"
Here's what POE::Filter::Reference expects of its serializers.
.SS "thaw \s-1SERIALIZED\s0"
.IX Subsection "thaw SERIALIZED"
\&\fIthaw()\fR is required.  It accepts two parameters: \f(CW$self\fR and a scalar
containing a \s-1SERIALIZED\s0 byte stream representing a single Perl data
structure.  It returns a reconstituted Perl data structure.
.PP
.Vb 5
\&  sub thaw {
\&    my ($self, $stream) = @_;
\&    my $reference = $self\->_deserialization_magic($stream);
\&    return $reference;
\&  }
.Ve
.SS "nfreeze \s-1REFERENCE\s0"
.IX Subsection "nfreeze REFERENCE"
Either \fInfreeze()\fR or \fIfreeze()\fR is required.  They behave identically,
except that \fInfreeze()\fR is guaranteed to be portable across networks and
between machine architectures.
.PP
These freezers accept two parameters: \f(CW$self\fR and a \s-1REFERENCE\s0 to Perl
data.  They return a serialized version of the REFERENCEd data.
.PP
.Vb 5
\&  sub nfreeze {
\&    my ($self, $reference) = @_;
\&    my $stream = $self\->_serialization_magic($reference);
\&    return $stream;
\&  }
.Ve
.SS "freeze \s-1REFERENCE\s0"
.IX Subsection "freeze REFERENCE"
\&\fIfreeze()\fR is an alternative form of \fInfreeze()\fR.  It has the same call
signature as \fInfreeze()\fR, but it doesn't guarantee that serialized data
will be portable across machine architectures.
.PP
If you must choose between implementing \fIfreeze()\fR and \fInfreeze()\fR for use
with POE::Filter::Reference, go with \fInfreeze()\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Please see POE::Filter for documentation regarding the base
interface.
.PP
The \s-1SEE\s0 \s-1ALSO\s0 section in \s-1POE\s0 contains a table of contents covering
the entire \s-1POE\s0 distribution.
.SH "BUGS"
.IX Header "BUGS"
Not so much bugs as caveats:
.PP
It's important to use identical serializers on each end of a
connection.  Even different versions of the same serializer can break
data in transit.
.PP
Most (if not all) serializers will re-bless data at the destination,
but many of them will not load the necessary classes to make those
blessings work.  Make sure the same classes and versions are available
on either end of the wire.
.SH "AUTHORS & COPYRIGHTS"
.IX Header "AUTHORS & COPYRIGHTS"
The Reference filter was contributed by Artur Bergman, with changes
by Philip Gwyn.
.PP
Please see \s-1POE\s0 for more information about authors and contributors.