added Filter::Block and Dieter's FollowTail patches; finishing touche…

…s for 0.1009

Changes

@@ -11,25 +11,50 @@ subversions are available from <http://www.newts.org/~troc/poe.html>.
   make dist on it!  0.0910 is ``v0_0910''!  For example:
 
   cvs tag -Rc v0_11   .
-  cvs tag -Rc v0_1005 .
+  cvs tag -Rc v0_1009 .
 ]
 
 ,----- To Do -----
 |
 | Before 0.11
 |
-| Test $kernel->fork() or replace it entirely.
+| Wheel::FollowTail test.
+| Filter::Block test.
+| Fix $kernel->fork() or take it out entirely.
 |
 | After 0.11
 |
+| Filter::HTTPD test.
+| Filter::Reference test.
+| Filter::Stream test.
+| Wheel::ListenAccept test.
+|
+| Add new newlines to Filter::Line.
+| Add variable-length capability to Filter::Block.
+|
 | Split the samples out into a separate distribution.
 | Revise the POE web pages.
 |
 `-----------------
 
 
-0.1009 2000.??.??
------------------
+0.1009 2000.06.17 (!!!)
+-----------------------
+
+(!!!) Documented that $kernel->fork() was broken in 0.1006.
+
+Dieter Pearcey sent in a patch to FollowTail that lets programs
+specify how far to seek back into a file before tailing it.  When
+SeekBack is used, everything up to the current end of file is
+returned.  These changes look okay, but they are not yet tested.
+samples/followtail.perl still works, which is encouraging.
+
+Dieter Pearcey also submitted Filter::Block, a fixed-length block
+filter.  This filter is not yet tested.
+
+Windows compatibility seems to have gone all to heck in this version.
+I'm not sure why, either, since I didn't do anything specific to
+Windows but enhance its support.
 
 Tweaked POE::Preprocessor to do something approaching right things
 when debugging or tracing are turned on.
@@ -38,8 +63,8 @@ Optimized away a function in lib/TestSetup.pm.
 
 Added t/13_wheels_udp.t and a corresponding MANIFEST entry.
 
-Jonathan Feinber graciously loaned a Windows NT shell for testing
-and development, opening whole new worlds of pain to me.  :)
+Jonathan Feinber graciously loaned a Windows NT shell for testing and
+development, opening whole new worlds of pain to me.  :)
 
 Tweaked the Win32 FIONBIO ioctls for non-blocking filehandles in
 POE::Kernel and POE::Wheel::SocketFactory.
@@ -127,6 +152,8 @@ wouldn't apply and I sort of redid the code as I spliced it into the
 the Kernel.  I'll know when Philip tests it whether I've broken his
 algorithm.)
 
+(!!!) $kernel->fork() was broken during the SIGCHLD revision.
+
 Tweaked postbacks.  Older Perl versions were not doing the right
 things with \@_ in POE::Session's postback() method.  Replaced it
 with [ @_ ] instead.

MANIFEST

@@ -12,6 +12,7 @@ POE/Curator.pm
 POE/Driver.pm
 POE/Driver/SysRW.pm
 POE/Filter.pm
+POE/Filter/Block.pm
 POE/Filter/HTTPD.pm
 POE/Filter/Line.pm
 POE/Filter/Reference.pm

lib/POE.pm

@@ -297,6 +297,13 @@ Filters next:
 
 =item *
 
+POE::Filter::Block
+
+This filter parses input as fixed-length blocks.  The output side
+merely passes data through unscathed.
+
+=item *
+
 POE::Filter::HTTPD
 
 This filter parses input as HTTP requests, translating them into
@@ -987,6 +994,14 @@ testing and feedback, some of which is visible in the Changes file.
 
 =item *
 
+Dieter Pearcey is <dieter@bullfrog.perlhacker.org>.  He goes by
+several Japanese nicknames.
+
+Dieter patched Wheel::FollowTail to be more useful and has contributed
+the basic Filter::Block, along with documentation!
+
+=item *
+
 Robert Seifer
 
 Robert Seifer is <e-mail unknown>.  He rotates IRC nicknames

lib/POE/Filter/Block.pm

@@ -0,0 +1,99 @@
+# $Id$
+
+package POE::Filter::Block;
+
+use strict;
+
+#------------------------------------------------------------------------------
+
+sub new {
+  my $type = shift;
+
+  my $self = { blocksize      => abs(shift) || 512,
+               framing_buffer => ''
+             };
+
+  bless $self, $type;
+  $self;
+}
+
+#------------------------------------------------------------------------------
+
+sub get {
+  my ($self, $stream) = @_;
+
+  $self->{framing_buffer} .= join '', @{$stream};
+
+  my @blocks;
+  while (length $self->{framing_buffer} >= $self->{blocksize}) {
+    push @blocks, substr($self->{framing_buffer}, 0, $self->{blocksize}, "");
+  }
+
+  \@blocks;
+}
+
+#------------------------------------------------------------------------------
+
+sub put {
+  my ($self, $blocks) = @_;
+  my @raw = join '', @{$blocks};
+  \@raw;
+}
+
+#------------------------------------------------------------------------------
+
+sub get_pending {
+  my $self = shift;
+  return unless $self->{framing_buffer};
+  [ $self->{framing_buffer ];
+}
+
+###############################################################################
+1;
+
+__END__
+
+=head1 NAME
+
+POE::Filter::Block - POE Block Protocol Abstraction
+
+=head1 SYNOPSIS
+
+  $filter = new POE::Filter::Block(1024);
+  $arrayref_of_blocks =
+    $filter->get($arrayref_of_raw_chunks_from_driver);
+  $arrayref_of_streamable_chunks_for_driver =
+    $filter->put($arrayref_of_blocks);
+  $arrayref_of_streamable_chunks_for_driver =
+    $filter->put($single_block);
+  $arrayref_of_leftovers =
+    $filter->get_pending();
+
+=head1 DESCRIPTION
+
+The Block filter translates streams to and from blocks of bytes of a
+specified size.  If the size is not specified, 512 is used as default;
+if the given size is negative, the absolute value is used instead.
+Anyway, people trying to use negative blocksizes should be soundly
+spanked.
+
+Extra bytes are buffered until more bytes arrive to complete a block.
+
+=head1 PUBLIC FILTER METHODS
+
+Please see POE::Filter.
+
+=head1 SEE ALSO
+
+POE::Filter; POE::Filter::HTTPD; POE::Filter::Reference;
+POE::Filter::Stream; POE::Filter::Line
+
+=head1 BUGS
+
+None known.
+
+=head1 AUTHORS & COPYRIGHTS
+
+Please see the POE manpage.
+
+=cut

lib/POE/Filter/Line.pm

@@ -71,6 +71,8 @@ POE::Filter::Line - POE Line Protocol Abstraction
     $filter->put($arrayref_of_lines);
   $arrayref_of_streamable_chunks_for_driver =
     $filter->put($single_line);
+  $arrayref_of_leftovers =
+    $filter->get_pending();
 
 =head1 DESCRIPTION
 

lib/POE/Wheel/FollowTail.pm

@@ -33,6 +33,13 @@ sub new {
                         : 1
                       );
 
+  my $seek_back = ( (exists $params{'SeekBack'})
+                    ? $params{'SeekBack'}
+                    : 4096
+                  );
+  $seek_back = 0 if $seek_back < 0;
+
+
   my $self = bless { handle      => $handle,
                      driver      => $driver,
                      filter      => $filter,
@@ -46,10 +53,13 @@ sub new {
   # Try to position the file pointer before the end of the file.  This
   # is so we can "tail -f" an existing file.
 
-  eval { seek($handle, -4096, SEEK_END); };
-                                        # discard partial input chunks
-  while (defined(my $raw_input = $driver->get($handle))) {
-    $filter->get($raw_input);
+  eval { seek($handle, -$seek_back, SEEK_END); };
+
+  # Discard partial input chunks unless a SeekBack was specified.
+  unless (exists $params{SeekBack}) {
+    while (defined(my $raw_input = $driver->get($handle))) {
+      $filter->get($raw_input);
+    }
   }
                                         # nudge the wheel into action
   $poe_kernel->select($handle, $self->{state_read});
@@ -89,7 +99,7 @@ sub _define_states {
 
         while (defined(my $raw_input = $driver->get($hdl))) {
           foreach my $cooked_input (@{$filter->get($raw_input)}) {
-            $k->call($ses, $$event_input, $cooked_input)
+            $k->call($ses, $$event_input, $cooked_input);
           }
         }
 
@@ -219,6 +229,16 @@ before checking again.
 
 =item *
 
+SeekBack
+
+SeekBack is the number of bytes to seek back from the current end of
+file before reading.  By default, this is 4096, and data read up to
+the end of file is not returned.  (This is used to frame lines before
+returning actual data.)  If SeekBack is specified, then existing data
+up until EOF is returned, and then the wheel begins following tail.
+
+=item *
+
 InputState
 
 The InputState event is identical to POE::Wheel::ReadWrite's

tests/09_wheels_unix.t

@@ -12,7 +12,7 @@ use Socket;
 sub POE::Kernel::ASSERT_DEFAULT () { 1 }
 use POE qw( Wheel::SocketFactory
             Wheel::ReadWrite
-            Filter::Line Filter::Stream
+            Filter::Line
             Driver::SysRW
           );
 

tests/10_wheels_tcp.t

@@ -12,7 +12,7 @@ use Socket;
 sub POE::Kernel::ASSERT_DEFAULT () { 1 }
 use POE qw( Component::Server::TCP
             Wheel::ReadWrite
-            Filter::Line Filter::Stream
+            Filter::Line
             Driver::SysRW
           );