{
    "content": [
        {
            "type": "text",
            "text": "# POE::Filter::Reference (perldoc)\n\n## NAME\n\nPOE::Filter::Reference - freeze and thaw arbitrary Perl data\n\n## SYNOPSIS\n\n#!perl\nuse YAML;\nuse POE qw(Wheel::ReadWrite Filter::Reference);\nPOE::Session->create(\ninlinestates => {\nstart => sub {\npipe(my($read, $write)) or die $!;\n$[HEAP]{io} = POE::Wheel::ReadWrite->new(\nInputHandle => $read,\nOutputHandle => $write,\nFilter => POE::Filter::Reference->new(),\nInputEvent => \"gotperldata\",\n);\n$[HEAP]{io}->put(\n{ key1 => 111, key2 => 222 }\n);\n},\ngotperldata => sub {\nprint \"Got data:\\n\", YAML::Dump($[ARG0]);\nprint \"Bye!\\n\";\ndelete $[HEAP]{io};\n}\n}\n);\nPOE::Kernel->run();\nexit;\n\n## DESCRIPTION\n\nPOE::Filter::Reference allows programs to send and receive arbitrary Perl data structures\nwithout worrying about a line protocol. Its put() method serializes Perl data into a byte stream\nsuitable for transmission. getone() parses the data structures back out of such a stream.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **PUBLIC FILTER METHODS** (2 subsections)\n- **SERIALIZER API** (2 subsections)\n- **SEE ALSO**\n- **BUGS**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "POE::Filter::Reference",
        "section": "",
        "mode": "perldoc",
        "summary": "POE::Filter::Reference - freeze and thaw arbitrary Perl data",
        "synopsis": "#!perl\nuse YAML;\nuse POE qw(Wheel::ReadWrite Filter::Reference);\nPOE::Session->create(\ninlinestates => {\nstart => sub {\npipe(my($read, $write)) or die $!;\n$[HEAP]{io} = POE::Wheel::ReadWrite->new(\nInputHandle => $read,\nOutputHandle => $write,\nFilter => POE::Filter::Reference->new(),\nInputEvent => \"gotperldata\",\n);\n$[HEAP]{io}->put(\n{ key1 => 111, key2 => 222 }\n);\n},\ngotperldata => sub {\nprint \"Got data:\\n\", YAML::Dump($[ARG0]);\nprint \"Bye!\\n\";\ndelete $[HEAP]{io};\n}\n}\n);\nPOE::Kernel->run();\nexit;",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 31,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 7,
                "subsections": []
            },
            {
                "name": "PUBLIC FILTER METHODS",
                "lines": 1,
                "subsections": [
                    {
                        "name": "new",
                        "lines": 49
                    },
                    {
                        "name": "new",
                        "lines": 13
                    }
                ]
            },
            {
                "name": "SERIALIZER API",
                "lines": 3,
                "subsections": [
                    {
                        "name": "thaw",
                        "lines": 23
                    },
                    {
                        "name": "freeze",
                        "lines": 5
                    }
                ]
            },
            {
                "name": "SEE ALSO",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "BUGS",
                "lines": 14,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "POE::Filter::Reference - freeze and thaw arbitrary Perl data\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "#!perl\n\nuse YAML;\nuse POE qw(Wheel::ReadWrite Filter::Reference);\n\nPOE::Session->create(\ninlinestates => {\nstart => sub {\npipe(my($read, $write)) or die $!;\n$[HEAP]{io} = POE::Wheel::ReadWrite->new(\nInputHandle => $read,\nOutputHandle => $write,\nFilter => POE::Filter::Reference->new(),\nInputEvent => \"gotperldata\",\n);\n\n$[HEAP]{io}->put(\n{ key1 => 111, key2 => 222 }\n);\n},\ngotperldata => sub {\nprint \"Got data:\\n\", YAML::Dump($[ARG0]);\nprint \"Bye!\\n\";\ndelete $[HEAP]{io};\n}\n}\n);\n\nPOE::Kernel->run();\nexit;\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "POE::Filter::Reference allows programs to send and receive arbitrary Perl data structures\nwithout worrying about a line protocol. Its put() method serializes Perl data into a byte stream\nsuitable for transmission. getone() parses the data structures back out of such a stream.\n\nBy default, POE::Filter::Reference uses Storable to do its magic. A different serializer may be\nspecified at construction time.\n",
                "subsections": []
            },
            "PUBLIC FILTER METHODS": {
                "content": "new",
                "subsections": [
                    {
                        "name": "new",
                        "content": "parameters.\n\nSerializer\nAny class that supports nfreeze() (or freeze()) and thaw() may be used as a Serializer. If a\nSerializer implements both nfreeze() and freeze(), then the \"network\" (nfreeze) version will be\nused.\n\nSerializer may be a class name:\n\n# Use Storable explicitly, specified by package name.\nmy $filter = POE::Filter::Reference->newer( Serializer=>\"Storable\" );\n\n# Use YAML instead.  Compress its output, as it may be verbose.\nmy $filter = POE::Filter::Reference->new(\"YAML\", 1);\n\nSerializer may also be an object:\n\n# Use an object.\nmy $serializer = Data::Serializer::Something->new();\nmy $filter = POE::Filter::Reference->newer( Serializer => $serializer );\n\nIf Serializer is omitted or undef, the Reference filter will try to use Storable, FreezeThaw,\nand YAML in that order. POE::Filter::Reference will die if it cannot find one of these\nserializers, but this rarely happens now that Storable and YAML are bundled with Perl.\n\nCompression\nIf Compression is true, Compress::Zlib will be called upon to reduce the size of serialized\ndata. It will also decompress the incoming stream data.\n\nMaxBuffer\n\"MaxBuffer\" sets the maximum amount of data that the filter will hold onto while trying to build\na new reference. Defaults to 512 MB.\n\nNoFatals\nIf NoFatals is true, messages will be thawed inside a block eval. By default, however, thaw() is\nallowed to die normally. If an error occurs while NoFatals is in effect, POE::Filter::Reference\nwill return a string containing the contents of $@ at the time the eval failed. So when using\nNoFatals, it's important to check whether input is really a reference:\n\nsub gotreference {\nmy $message = $[ARG0];\nif (ref $message) {\nprint \"Got data:\\n\", YAML::Dump($message);\n}\nelse {\nwarn \"Input decode error: $message\\n\";\n}\n}\n"
                    },
                    {
                        "name": "new",
                        "content": "new [SERIALIZER [, COMPRESSION [, NOFATALS]]]\nThis is the old constructor synatx. It does not conform to the normal POE::Filter constructor\nparameter syntax. Please use the new syntax instead.\n\nCalling \"new\" like this is equivalent to\n\nPOE::Filter::Reference->new( Serializer => SERIALIZER,\nCompression => COMPRESSION,\nNoFatals  => NOFATALS );\n\nPlease note that if you have a custom serializer class called \"Serializer\" you will have to\nupdate your code to the new syntax.\n"
                    }
                ]
            },
            "SERIALIZER API": {
                "content": "Here's what POE::Filter::Reference expects of its serializers.\n\nthaw SERIALIZED",
                "subsections": [
                    {
                        "name": "thaw",
                        "content": "stream representing a single Perl data structure. It returns a reconstituted Perl data\nstructure.\n\nsub thaw {\nmy ($self, $stream) = @;\nmy $reference = $self->deserializationmagic($stream);\nreturn $reference;\n}\n\nnfreeze REFERENCE\nEither nfreeze() or freeze() is required. They behave identically, except that nfreeze() is\nguaranteed to be portable across networks and between machine architectures.\n\nThese freezers accept two parameters: $self and a REFERENCE to Perl data. They return a\nserialized version of the REFERENCEd data.\n\nsub nfreeze {\nmy ($self, $reference) = @;\nmy $stream = $self->serializationmagic($reference);\nreturn $stream;\n}\n\nfreeze REFERENCE"
                    },
                    {
                        "name": "freeze",
                        "content": "it doesn't guarantee that serialized data will be portable across machine architectures.\n\nIf you must choose between implementing freeze() and nfreeze() for use with\nPOE::Filter::Reference, go with nfreeze().\n"
                    }
                ]
            },
            "SEE ALSO": {
                "content": "Please see POE::Filter for documentation regarding the base interface.\n\nThe SEE ALSO section in POE contains a table of contents covering the entire POE distribution.\n",
                "subsections": []
            },
            "BUGS": {
                "content": "Not so much bugs as caveats:\n\nIt's important to use identical serializers on each end of a connection. Even different versions\nof the same serializer can break data in transit.\n\nMost (if not all) serializers will re-bless data at the destination, but many of them will not\nload the necessary classes to make those blessings work. Make sure the same classes and versions\nare available on either end of the wire.\n\nAUTHORS & COPYRIGHTS\nThe Reference filter was contributed by Artur Bergman, with changes by Philip Gwyn.\n\nPlease see POE for more information about authors and contributors.\n",
                "subsections": []
            }
        }
    }
}