poe::filter::block(3pm) [debian man page]

POE::Filter::Block(3pm) 				User Contributed Perl Documentation				   POE::Filter::Block(3pm)

NAME

       POE::Filter::Block - translate data between streams and blocks

SYNOPSIS

	 #!perl

	 use warnings;
	 use strict;
	 use POE::Filter::Block;

	 my $filter = POE::Filter::Block->new( BlockSize => 8 );

	 # Prints three lines: abcdefgh, ijklmnop, qrstuvwx.
	 # Bytes "y" and "z" remain in the buffer and await completion of the
	 # next 8-byte block.

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

	 # Print one line: yz123456

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

DESCRIPTION

       POE::Filter::Block translates data between serial streams and blocks.  It can handle fixed-length and length-prepended blocks, and it may
       be extended to handle other block types.

       Fixed-length blocks are used when Block's constructor is called with a BlockSize value.	Otherwise the Block filter uses length-prepended
       blocks.

       Users who specify block sizes less than one deserve what they get.

       In variable-length mode, a LengthCodec parameter may be specified.  The LengthCodec value should be a reference to a list of two functions:
       the length encoder, and the length decoder:

	 LengthCodec => [ &encoder, &decoder ]

       The encoder takes a reference to a buffer and prepends the buffer's length to it.  The default encoder prepends the ASCII representation of
       the buffer's length and a chr(0) byte to separate the length from the actual data:

	 sub _default_encoder {
	   my $stuff = shift;
	   substr($$stuff, 0, 0) = length($$stuff) . "";
	   return;
	 }

       The corresponding decoder returns the block length after removing it and the separator from the buffer.	It returns nothing if no length
       can be determined.

	 sub _default_decoder {
	   my $stuff = shift;
	   unless ($$stuff =~ s/^(d+)//s) {
	     warn length($1), " strange bytes removed from stream"
	       if $$stuff =~ s/^(D+)//s;
	     return;
	   }
	   return $1;
	 }

       This filter holds onto incomplete blocks until they are completed.

PUBLIC FILTER METHODS

       POE::Filter::Block has no additional public methods.

SEE ALSO

       Please see POE::Filter for documentation regarding the base interface.

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

BUGS

       The put() method doesn't verify block sizes.

AUTHORS &; COPYRIGHTS
       The Block filter was contributed by Dieter Pearcey, with changes by Rocco Caputo.

       Please see POE for more information about authors and contributors.

perl v5.14.2							    2012-05-15						   POE::Filter::Block(3pm)

POE::Filter::Line(3pm)					User Contributed Perl Documentation				    POE::Filter::Line(3pm)

NAME

       POE::Filter::Line - serialize and parse terminated records (lines)

SYNOPSIS

	 #!perl

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

	 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]
";
	     }
	   }
	 );

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

DESCRIPTION

       POE::Filter::Line parses stream data into terminated records.  The default parser interprets newlines as the record terminator, and the
       default serializer appends network newlines (CR/LF, or "x0Dx0A") to outbound records.

       Record terminators are removed from the data POE::Filter::Line returns.

       POE::Filter::Line supports a number of other ways to parse lines.  Constructor parameters may specify literal newlines, regular
       expressions, or that the filter should detect newlines on its own.

PUBLIC FILTER METHODS

       POE::Filter::Line's new() method has some interesting parameters.

   new
       new() accepts a list of named parameters.

       In all cases, the data interpreted as the record terminator is stripped from the data POE::Filter::Line returns.

       "InputLiteral" may be used to parse records that are terminated by some literal string.	For example, POE::Filter::Line may be used to
       parse and emit C-style lines, which are terminated with an ASCII NUL:

	 my $c_line_filter = POE::Filter::Line->new(
	   InputLiteral => chr(0),
	   OutputLiteral => chr(0),
	 );

       "OutputLiteral" allows a filter to put() records with a different record terminator than it parses.  This can be useful in applications
       that must translate record terminators.

       "Literal" is a shorthand for the common case where the input and output literals are identical.	The previous example may be written as:

	 my $c_line_filter = POE::Filter::Line->new(
	   Literal => chr(0),
	 );

       An application can also allow POE::Filter::Line to figure out which newline to use.  This is done by specifying "InputLiteral" to be undef:

	 my $whichever_line_filter = POE::Filter::Line->new(
	   InputLiteral => undef,
	   OutputLiteral => "
",
	 );

       "InputRegexp" may be used in place of "InputLiteral" to recognize line terminators based on a regular expression.  In this example, input
       is terminated by two or more consecutive newlines.  On output, the paragraph separator is "---" on a line by itself.

	 my $paragraph_filter = POE::Filter::Line->new(
	   InputRegexp => "([x0Dx0A]{2,})",
	   OutputLiteral => "
---
",
	 );

PUBLIC FILTER METHODS

       POE::Filter::Line has no additional public methods.

SEE ALSO

       Please see POE::Filter for documentation regarding the base interface.

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

BUGS

       The default input newline parser is a regexp that has an unfortunate race condition.  First the regular expression:

	 /(x0Dx0A?|x0Ax0D?)/

       While it quickly recognizes most forms of newline, it can sometimes detect an extra blank line.	This happens when a two-byte newline
       character is broken between two reads.  Consider this situation:

	 some stream dataCR
	 LFother stream data

       The regular expression will see the first CR without its corresponding LF.  The filter will properly return "some stream data" as a line.
       When the next packet arrives, the leading "LF" will be treated as the terminator for a 0-byte line.  The filter will faithfully return this
       empty line.

       It is advised to specify literal newlines or use the autodetect feature in applications where blank lines are significant.

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

perl v5.14.2							    2012-05-15						    POE::Filter::Line(3pm)