POE::Filter - phpMan

NAME
    POE::Filter - protocol abstractions for POE::Wheel and standalone use

SYNOPSIS
    To use with POE::Wheel classes, pass a POE::Filter object to one of the
    "...Filter" constructor parameters:

      #!perl

      use POE qw(Filter::Line Wheel::FollowTail);

      POE::Session->create(
        inline_states => {
          _start => sub {
            $_[HEAP]{tailor} = POE::Wheel::FollowTail->new(
              Filename => "/var/log/system.log",
              InputEvent => "got_log_line",
              Filter => POE::Filter::Line->new(),
            );
          },
          got_log_line => sub {
            print "Log: $_[ARG0]\n";
          }
        }
      );

      POE::Kernel->run();
      exit;

    Standalone use without POE:

      #!perl

      use warnings;
      use strict;
      use POE::Filter::Line;

      my $filter = POE::Filter::Line->new( Literal => "\n" );

      # Prints three lines: one, two three.

      $filter->get_one_start(["one\ntwo\nthr", "ee\nfour"]);
      while (1) {
        my $line = $filter->get_one();
        last unless @$line;
        print $line->[0], "\n";
      }

      # Prints two lines: four, five.

      $filter->get_one_start(["\nfive\n"]);
      while (1) {
        my $line = $filter->get_one();
        last unless @$line;
        print $line->[0], "\n";
      }

DESCRIPTION
    POE::Filter objects plug into the wheels and define how the data will be
    serialized for writing and parsed after reading. POE::Wheel objects are
    responsible for moving data, and POE::Filter objects define how the data
    should look.

    POE::Filter objects are simple by design. They do not use POE
    internally, so they are limited to serialization and parsing. This may
    complicate implementation of certain protocols (like HTTP 1.x), but it
    allows filters to be used in stand-alone programs.

    Stand-alone use is very important. It allows application developers to
    create lightweight blocking libraries that may be used as simple clients
    for POE servers. POE::Component::IKC::ClientLite is a notable example.
    This lightweight, blocking event-passing client supports thin clients
    for gridded POE applications. The canonical use case is to inject events
    into an IKC application or grid from CGI interfaces, which require
    lightweight resource use.

    POE filters and drivers pass data in array references. This is slightly
    awkward, but it minimizes the amount of data that must be copied on
    Perl's stack.

PUBLIC INTERFACE
    All POE::Filter classes must support the minimal interface, defined
    here. Specific filters may implement and document additional methods.

  new PARAMETERS
    new() creates and initializes a new filter. Constructor parameters vary
    from one POE::Filter subclass to the next, so please consult the
    documentation for your desired filter.

  clone
    clone() creates and initializes a new filter based on the constructor
    parameters of the existing one. The new filter is a near-identical copy,
    except that its buffers are empty.

    Certain components, such as POE::Component::Server::TCP, use clone().
    These components accept a master or template filter at creation time,
    then clone() that filter for each new connection.

      my $new_filter = $old_filter->clone();

  get_one_start ARRAYREF
    get_one_start() accepts an array reference containing unprocessed stream
    chunks. The chunks are added to the filter's internal buffer for parsing
    by get_one().

    The "SYNOPSIS" shows get_one_start() in use.

  get_one
    get_one() parses zero or one complete item from the filter's internal
    buffer. The data is returned as an ARRAYREF suitable for passing to
    another filter or a POE::Wheel object. Filters will return empty
    ARRAYREFs if they don't have enough raw data to build a complete item.

    get_one() is the lazy form of get(). It only parses only one item at a
    time from the filter's buffer. This is vital for applications that may
    switch filters in mid-stream, as it ensures that the right filter is in
    use at any given time.

    The "SYNOPSIS" shows get_one() in use. Note how it assumes the return is
    always an ARRAYREF, and it implicitly handles empty ones.

  get ARRAYREF
    get() is the greedy form of get_one(). It accepts an array reference
    containing unprocessed stream chunks, and it adds that data to the
    filter's internal buffer. It then parses as many full items as possible
    from the buffer and returns them in another array reference. Any
    unprocessed data remains in the filter's buffer for the next call.

    As with get_one(), get() will return an empty array reference if the
    filter doesn't contain enough raw data to build a complete item.

    In fact, get() is implemented in POE::Filter in terms of get_one_start()
    and get_one().

    Here's the get() form of the SYNOPSIS stand-alone example:

      #!perl

      use warnings;
      use strict;
      use POE::Filter::Line;

      my $filter = POE::Filter::Line->new( Literal => "\n" );

      # Prints three lines: one, two three.

      my $lines = $filter->get(["one\ntwo\nthr", "ee\nfour"]);
      foreach my $line (@$lines) {
        print "$line\n";
      }

      # Prints two lines: four, five.

      $lines = $filter->get(["\nfive\n"]);
      foreach my $line (@$lines) {
        print "$line\n";
      }

    get() should not be used with wheels that support filter switching. Its
    greedy nature means that it often parses streams well in advance of a
    wheel's events. By the time an application changes the wheel's filter,
    it's too late: The old filter has already parsed the rest of the
    received data.

    Consider a stream of letters, numbers, and periods. The periods signal
    when to switch filters from one that parses letters to one that parses
    numbers.

    In our hypothetical application, letters must be handled one at a time,
    but numbers may be handled in chunks. We'll use POE::Filter::Block with
    a BlockSize of 1 to parse letters, and POE::FIlter::Line with a Literal
    terminator of "." to handle numbers.

    Here's the sample stream:

      abcdefg.1234567.hijklmnop.890.q

    We'll start with a ReadWrite wheel configured to parse characters.

      $_[HEAP]{wheel} = POE::Wheel::ReadWrite->new(
        Filter => POE::Filter::Block->new( BlockSize => 1 ),
        Handle => $socket,
        InputEvent => "got_letter",
      );

    The "got_letter" handler will be called 8 times. One for each letter
    from a through g, and once for the period following g. Upon receiving
    the period, it will switch the wheel into number mode.

      sub handle_letter {
        my $letter = $_[ARG0];
        if ($letter eq ".") {
          $_[HEAP]{wheel}->set_filter(
            POE::Filter::Line->new( Literal => "." )
          );
          $_[HEAP]{wheel}->event( InputEvent => "got_number" );
        }
        else {
          print "Got letter: $letter\n";
        }
      }

    If the greedy get() were used, the entire input stream would have been
    parsed as characters in advance of the first handle_letter() call. The
    set_filter() call would have been moot, since there would be no data
    left to be parsed.

    The "got_number" handler receives contiguous runs of digits as
    period-terminated lines. The greedy get() would cause a similar problem
    as above.

      sub handle_numbers {
        my $numbers = $_[ARG0];
        print "Got number(s): $numbers\n";
        $_[HEAP]->{wheel}->set_filter(
          POE::Filter::Block->new( BlockSize => 1 )
        );
        $_[HEAP]->{wheel}->event( InputEvent => "got_letter" );
      }

    So don't do it!

  put ARRAYREF
    put() serializes items into a stream of octets that may be written to a
    file or sent across a socket. It accepts a reference to a list of items,
    and it returns a reference to a list of marshalled stream chunks. The
    number of output chunks is not necessarily related to the number of
    input items.

    In stand-alone use, put()'s output may be sent directly:

      my $line_filter = POE::Filter::Line->new();
      my $lines = $line_filter->put(\@list_of_things);
      foreach my $line (@$lines) {
        print $line;
      }

    The list reference it returns may be passed directly to a driver or
    filter. Drivers and filters deliberately share the same put() interface
    so that things like this are possible:

      $driver->put(
        $transfer_encoding_filter->put(
          $content_encoding_filter->put(
            \@items
          )
        )
      );

      1 while $driver->flush(\*STDOUT);

  get_pending
    get_pending() returns any data remaining in a filter's input buffer. The
    filter's input buffer is not cleared, however. get_pending() returns a
    list reference if there's any data, or undef if the filter was empty.

    POE::Wheel objects use get_pending() during filter switching.
    Unprocessed data is fetched from the old filter with get_pending() and
    injected into the new filter with get_one_start().

      use POE::Filter::Line;
      use POE::Filter::Stream;

      my $line_filter = POE::Filter::Line->new();
      $line_filter->get_one_start([ "not a complete line" ]);

      my $stream_filter = POE::Filter::Stream->new();
      my $line_buffer = $line_filter->get_pending();
      $stream_filter->get_one_start($line_buffer) if $line_buffer;

      print "Stream: $_\n" foreach (@{ $stream_filter->get_one });

    Full items are serialized whole, so there is no corresponding "put"
    buffer or accessor.

SEE ALSO
    The SEE ALSO section in POE contains a table of contents covering the
    entire POE distribution.

    POE is bundled with the following filters:

    POE::Filter::Block POE::Filter::Grep POE::Filter::HTTPD
    POE::Filter::Line POE::Filter::Map POE::Filter::RecordBlock
    POE::Filter::Reference POE::Filter::Stackable POE::Filter::Stream

BUGS
    In theory, filters should be interchangeable. In practice, stream and
    block protocols tend to be incompatible.

AUTHORS & COPYRIGHTS
    Please see POE for more information about authors and contributors.