{
    "mode": "perldoc",
    "parameter": "POE::Filter",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/POE%3A%3AFilter/json",
    "generated": "2026-06-12T15:40:15Z",
    "synopsis": "To use with POE::Wheel classes, pass a POE::Filter object to one of the \"...Filter\" constructor\nparameters:\n#!perl\nuse POE qw(Filter::Line Wheel::FollowTail);\nPOE::Session->create(\ninlinestates => {\nstart => sub {\n$[HEAP]{tailor} = POE::Wheel::FollowTail->new(\nFilename => \"/var/log/system.log\",\nInputEvent => \"gotlogline\",\nFilter => POE::Filter::Line->new(),\n);\n},\ngotlogline => sub {\nprint \"Log: $[ARG0]\\n\";\n}\n}\n);\nPOE::Kernel->run();\nexit;\nStandalone use without POE:\n#!perl\nuse warnings;\nuse strict;\nuse POE::Filter::Line;\nmy $filter = POE::Filter::Line->new( Literal => \"\\n\" );\n# Prints three lines: one, two three.\n$filter->getonestart([\"one\\ntwo\\nthr\", \"ee\\nfour\"]);\nwhile (1) {\nmy $line = $filter->getone();\nlast unless @$line;\nprint $line->[0], \"\\n\";\n}\n# Prints two lines: four, five.\n$filter->getonestart([\"\\nfive\\n\"]);\nwhile (1) {\nmy $line = $filter->getone();\nlast unless @$line;\nprint $line->[0], \"\\n\";\n}",
    "sections": {
        "NAME": {
            "content": "POE::Filter - protocol abstractions for POE::Wheel and standalone use\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "To use with POE::Wheel classes, pass a POE::Filter object to one of the \"...Filter\" constructor\nparameters:\n\n#!perl\n\nuse POE qw(Filter::Line Wheel::FollowTail);\n\nPOE::Session->create(\ninlinestates => {\nstart => sub {\n$[HEAP]{tailor} = POE::Wheel::FollowTail->new(\nFilename => \"/var/log/system.log\",\nInputEvent => \"gotlogline\",\nFilter => POE::Filter::Line->new(),\n);\n},\ngotlogline => sub {\nprint \"Log: $[ARG0]\\n\";\n}\n}\n);\n\nPOE::Kernel->run();\nexit;\n\nStandalone use without POE:\n\n#!perl\n\nuse warnings;\nuse strict;\nuse POE::Filter::Line;\n\nmy $filter = POE::Filter::Line->new( Literal => \"\\n\" );\n\n# Prints three lines: one, two three.\n\n$filter->getonestart([\"one\\ntwo\\nthr\", \"ee\\nfour\"]);\nwhile (1) {\nmy $line = $filter->getone();\nlast unless @$line;\nprint $line->[0], \"\\n\";\n}\n\n# Prints two lines: four, five.\n\n$filter->getonestart([\"\\nfive\\n\"]);\nwhile (1) {\nmy $line = $filter->getone();\nlast unless @$line;\nprint $line->[0], \"\\n\";\n}\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "POE::Filter objects plug into the wheels and define how the data will be serialized for writing\nand parsed after reading. POE::Wheel objects are responsible for moving data, and POE::Filter\nobjects define how the data should look.\n\nPOE::Filter objects are simple by design. They do not use POE internally, so they are limited to\nserialization and parsing. This may complicate implementation of certain protocols (like HTTP\n1.x), but it allows filters to be used in stand-alone programs.\n\nStand-alone use is very important. It allows application developers to create lightweight\nblocking libraries that may be used as simple clients for POE servers.\nPOE::Component::IKC::ClientLite is a notable example. This lightweight, blocking event-passing\nclient supports thin clients for gridded POE applications. The canonical use case is to inject\nevents into an IKC application or grid from CGI interfaces, which require lightweight resource\nuse.\n\nPOE filters and drivers pass data in array references. This is slightly awkward, but it\nminimizes the amount of data that must be copied on Perl's stack.\n",
            "subsections": []
        },
        "PUBLIC INTERFACE": {
            "content": "All POE::Filter classes must support the minimal interface, defined here. Specific filters may\nimplement and document additional methods.\n\nnew PARAMETERS",
            "subsections": [
                {
                    "name": "new",
                    "content": "subclass to the next, so please consult the documentation for your desired filter.\n\nclone"
                },
                {
                    "name": "clone",
                    "content": "one. The new filter is a near-identical copy, except that its buffers are empty.\n\nCertain components, such as POE::Component::Server::TCP, use clone(). These components accept a\nmaster or template filter at creation time, then clone() that filter for each new connection.\n\nmy $newfilter = $oldfilter->clone();\n\ngetonestart ARRAYREF"
                },
                {
                    "name": "get_one_start",
                    "content": "added to the filter's internal buffer for parsing by getone().\n\nThe \"SYNOPSIS\" shows getonestart() in use.\n\ngetone"
                },
                {
                    "name": "get_one",
                    "content": "returned as an ARRAYREF suitable for passing to another filter or a POE::Wheel object. Filters\nwill return empty ARRAYREFs if they don't have enough raw data to build a complete item.\n"
                },
                {
                    "name": "get_one",
                    "content": "buffer. This is vital for applications that may switch filters in mid-stream, as it ensures that\nthe right filter is in use at any given time.\n\nThe \"SYNOPSIS\" shows getone() in use. Note how it assumes the return is always an ARRAYREF, and\nit implicitly handles empty ones.\n\nget ARRAYREF"
                },
                {
                    "name": "get",
                    "content": "stream chunks, and it adds that data to the filter's internal buffer. It then parses as many\nfull items as possible from the buffer and returns them in another array reference. Any\nunprocessed data remains in the filter's buffer for the next call.\n\nAs with getone(), get() will return an empty array reference if the filter doesn't contain\nenough raw data to build a complete item.\n\nIn fact, get() is implemented in POE::Filter in terms of getonestart() and getone().\n\nHere's the get() form of the SYNOPSIS stand-alone example:\n\n#!perl\n\nuse warnings;\nuse strict;\nuse POE::Filter::Line;\n\nmy $filter = POE::Filter::Line->new( Literal => \"\\n\" );\n\n# Prints three lines: one, two three.\n\nmy $lines = $filter->get([\"one\\ntwo\\nthr\", \"ee\\nfour\"]);\nforeach my $line (@$lines) {\nprint \"$line\\n\";\n}\n\n# Prints two lines: four, five.\n\n$lines = $filter->get([\"\\nfive\\n\"]);\nforeach my $line (@$lines) {\nprint \"$line\\n\";\n}\n"
                },
                {
                    "name": "get",
                    "content": "it often parses streams well in advance of a wheel's events. By the time an application changes\nthe wheel's filter, it's too late: The old filter has already parsed the rest of the received\ndata.\n\nConsider a stream of letters, numbers, and periods. The periods signal when to switch filters\nfrom one that parses letters to one that parses numbers.\n\nIn our hypothetical application, letters must be handled one at a time, but numbers may be\nhandled in chunks. We'll use POE::Filter::Block with a BlockSize of 1 to parse letters, and\nPOE::FIlter::Line with a Literal terminator of \".\" to handle numbers.\n\nHere's the sample stream:\n\nabcdefg.1234567.hijklmnop.890.q\n\nWe'll start with a ReadWrite wheel configured to parse characters.\n\n$[HEAP]{wheel} = POE::Wheel::ReadWrite->new(\nFilter => POE::Filter::Block->new( BlockSize => 1 ),\nHandle => $socket,\nInputEvent => \"gotletter\",\n);\n\nThe \"gotletter\" handler will be called 8 times. One for each letter from a through g, and once\nfor the period following g. Upon receiving the period, it will switch the wheel into number\nmode.\n\nsub handleletter {\nmy $letter = $[ARG0];\nif ($letter eq \".\") {\n$[HEAP]{wheel}->setfilter(\nPOE::Filter::Line->new( Literal => \".\" )\n);\n$[HEAP]{wheel}->event( InputEvent => \"gotnumber\" );\n}\nelse {\nprint \"Got letter: $letter\\n\";\n}\n}\n\nIf the greedy get() were used, the entire input stream would have been parsed as characters in\nadvance of the first handleletter() call. The setfilter() call would have been moot, since\nthere would be no data left to be parsed.\n\nThe \"gotnumber\" handler receives contiguous runs of digits as period-terminated lines. The\ngreedy get() would cause a similar problem as above.\n\nsub handlenumbers {\nmy $numbers = $[ARG0];\nprint \"Got number(s): $numbers\\n\";\n$[HEAP]->{wheel}->setfilter(\nPOE::Filter::Block->new( BlockSize => 1 )\n);\n$[HEAP]->{wheel}->event( InputEvent => \"gotletter\" );\n}\n\nSo don't do it!\n\nput ARRAYREF"
                },
                {
                    "name": "put",
                    "content": "socket. It accepts a reference to a list of items, and it returns a reference to a list of\nmarshalled stream chunks. The number of output chunks is not necessarily related to the number\nof input items.\n\nIn stand-alone use, put()'s output may be sent directly:\n\nmy $linefilter = POE::Filter::Line->new();\nmy $lines = $linefilter->put(\\@listofthings);\nforeach my $line (@$lines) {\nprint $line;\n}\n\nThe list reference it returns may be passed directly to a driver or filter. Drivers and filters\ndeliberately share the same put() interface so that things like this are possible:\n\n$driver->put(\n$transferencodingfilter->put(\n$contentencodingfilter->put(\n\\@items\n)\n)\n);\n\n1 while $driver->flush(\\*STDOUT);\n\ngetpending"
                },
                {
                    "name": "get_pending",
                    "content": "is not cleared, however. getpending() returns a list reference if there's any data, or undef if\nthe filter was empty.\n\nPOE::Wheel objects use getpending() during filter switching. Unprocessed data is fetched from\nthe old filter with getpending() and injected into the new filter with getonestart().\n\nuse POE::Filter::Line;\nuse POE::Filter::Stream;\n\nmy $linefilter = POE::Filter::Line->new();\n$linefilter->getonestart([ \"not a complete line\" ]);\n\nmy $streamfilter = POE::Filter::Stream->new();\nmy $linebuffer = $linefilter->getpending();\n$streamfilter->getonestart($linebuffer) if $linebuffer;\n\nprint \"Stream: $\\n\" foreach (@{ $streamfilter->getone });\n\nFull items are serialized whole, so there is no corresponding \"put\" buffer or accessor.\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "The SEE ALSO section in POE contains a table of contents covering the entire POE distribution.\n\nPOE is bundled with the following filters:\n\nPOE::Filter::Block POE::Filter::Grep POE::Filter::HTTPD POE::Filter::Line POE::Filter::Map\nPOE::Filter::RecordBlock POE::Filter::Reference POE::Filter::Stackable POE::Filter::Stream\n",
            "subsections": []
        },
        "BUGS": {
            "content": "In theory, filters should be interchangeable. In practice, stream and block protocols tend to be\nincompatible.\n\nAUTHORS & COPYRIGHTS\nPlease see POE for more information about authors and contributors.\n",
            "subsections": []
        }
    },
    "summary": "POE::Filter - protocol abstractions for POE::Wheel and standalone use",
    "flags": [],
    "examples": [],
    "see_also": []
}