NAME

VERSION

SYNOPSIS

    use IO::Callback;

    my $fh = IO::Callback->new('<', sub { ... ; return $data });
    my $object = Some::Class->new_from_file($fh);

Similarly, IO::Callback allows you to wrap up a coderef as a write-only filehandle, which you can pass to a library module that expects to write its output to a filehandle.

    my $fh = IO::Callback->new('>', sub { my $data = shift ; ... });
    $object->dump_to_file($fh);

CONSTRUCTOR

EXAMPLES

Example 1

To generate a filehandle from which an infinite number of "x" characters can be read:

  my $fh = IO::Callback->new('<', sub {"xxxxxxxxxxxxxxxxxxxxxxxxxxx"});

  my $x = $fh->getc;  # $x now contains "x"
  read $fh, $x, 5;    # $x now contains "xxxxx"
    

Example 2

A filehandle from which 1000 "foo" lines can be read before EOF:

  my $count = 0;
  my $fh = IO::Callback->new('<', sub {
      return if ++$count > 1000; # EOF
      return "foo\n";
  });

  my $x = <$fh>;    # $x now contains "foo\n"
  read $fh, $x, 2;  # $x now contains "fo"
  read $fh, $x, 2;  # $x now contains "o\n"
  read $fh, $x, 20; # $x now contains "foo\nfoo\nfoo\nfoo\nfoo\n"
  my @foos = <$fh>; # @foos now contains ("foo\n") x 993
    

The example above uses a "closure" (a special kind of anonymous sub, see <http://perldoc.perl.org/perlfaq7.html#What's-a-closure?>) to allow the callback to keep track of how many lines it has returned. You don't have to use a closure if you don't want to, since "IO::Callback" will forward extra constructor arguments to the callback. This example could be re-written as:

  my $count = 0;
  my $fh = IO::Callback->new('<', \&my_callback, \$count); 

  my $x = <$fh>;    # $x now contains "foo\n"
  read $fh, $x, 2;  # $x now contains "fo"
  read $fh, $x, 2;  # $x now contains "o\n"
  read $fh, $x, 20; # $x now contains "foo\nfoo\nfoo\nfoo\nfoo\n"
  my @foos = <$fh>; # @foos now contains ("foo\n") x 993

  sub my_callback {
      my $count_ref = shift;

      return if ++$$count_ref > 1000; # EOF
      return "foo\n";
  };
    

Example 3

To generate a filehandle interface to data drawn from an SQL table:

  my $sth = $dbh->prepare("SELECT ...");
  $sth->execute;
  my $fh = IO::Callback->new('<', sub {
      my @row = $sth->fetchrow_array;
      return unless @row; # EOF
      return join(',', @row) . "\n";
  });

  # ...
    

Example 4

You want a filehandle to which data can be written, where the data is discarded but an exception is raised if the data includes the string "foo".

  my $buf = '';
  my $fh = IO::Callback->new('>', sub {
      $buf .= shift;
      die "foo written" if $buf =~ /foo/;

      if ($buf =~ /(fo?)\z/) {
          # Part way through a "foo", carry over to the next block.
          $buf = $1;
      } else {
          $buf = '';
      }
  });
    

Example 5

You have been given an object with a copy_data_out() method that takes a destination filehandle as an argument. You don't want the data written to a file though, you want it split into 1024-byte blocks and inserted into an SQL database.

  my $blocksize = 1024;
  my $sth = $dbh->prepare('INSERT ...');

  my $buf = '';
  my $fh = IO::Callback->new('>', sub {
      $buf .= shift;
      while (length $buf >= $blocksize) {
          $sth->execute(substr $buf, 0, $blocksize, '');
      }
  });

  $thing->copy_data_out($fh);

  if (length $buf) {
      # There is a remainder of < $blocksize
      $sth->execute($buf);
  }
    

Example 6

You're testing some code that reads data from a file, you want to check that it behaves as expected if it gets an IO error part way through the file.

  use IO::Callback;
  use Errno qw/EIO/;

  my $block1 = "x" x 10240;
  my $block2 = "y" x 10240;
  my @blocks = ($block1, $block2);

  my $fh = IO::Callback->new('<', sub {
      return shift @blocks if @blocks;
      $! = EIO;
      return IO::Callback::Error;
  });

  # ...
    

Example 7

You're testing some code that writes data to a file handle, you want to check that it behaves as expected if it gets a "file system full" error after it has written the first 100k of data.

  use IO::Callback;
  use Errno qw/ENOSPC/;

  my $wrote = 0;
  my $fh = IO::Callback->new('>', sub {
      $wrote += length $_[0];
      if ($wrote > 100_000) {
          $! = ENOSPC;
          return IO::Callback::Error;
      }
  });

  # ...
    

AUTHOR

BUGS AND LIMITATIONS

"Digest::MD5::addfile()"

Please report any other bugs or feature requests to "bug- at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IO::Callback>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

    perldoc IO::Callback

You can also look for information at:

• RT: CPAN's request tracker

  <http://rt.cpan.org/NoAuth/Bugs.html?Dist=IO::Callback>

• AnnoCPAN: Annotated CPAN documentation

  <http://annocpan.org/dist/IO::Callback>

• CPAN Ratings

  <http://cpanratings.perl.org/d/IO::Callback>

• Search CPAN

  <http://search.cpan.org/dist/IO::Callback>

SEE ALSO

ACKNOWLEDGEMENTS

MANITAINER

COPYRIGHT & LICENSE

Copyright 2009-2010 Dave Taylor.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.