.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IO::Callback 3pm"
.TH IO::Callback 3pm "2015-06-10" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IO::Callback \- Emulate file interface for a code reference
.SH "VERSION"
.IX Header "VERSION"
Version 1.12
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\f(CW\*(C`IO::Callback\*(C'\fR provides an easy way to produce a phoney read-only filehandle that calls back to your own code when it needs data to satisfy a read. This is useful if you want to use a library module that expects to read data from a filehandle, but you want the data to come from some other source and you don't want to read it all into memory and use IO::String.
.PP
.Vb 1
\&    use IO::Callback;
\&
\&    my $fh = IO::Callback\->new(\*(Aq<\*(Aq, sub { ... ; return $data });
\&    my $object = Some::Class\->new_from_file($fh);
.Ve
.PP
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.
.PP
.Vb 2
\&    my $fh = IO::Callback\->new(\*(Aq>\*(Aq, sub { my $data = shift ; ... });
\&    $object\->dump_to_file($fh);
.Ve
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .SS """new ( MODE, CODEREF [,ARG ...] )"""
.el .SS "\f(CWnew ( MODE, CODEREF [,ARG ...] )\fP"
.IX Subsection "new ( MODE, CODEREF [,ARG ...] )"
Returns a filehandle object encapsulating the coderef.
.PP
\&\s-1MODE\s0 must be either \f(CW\*(C`<\*(C'\fR for a read-only filehandle or \f(CW\*(C`>\*(C'\fR for a write-only filehandle.
.PP
For a read-only filehandle, the callback coderef will be invoked in a scalar context each time more data is required to satisfy a read. It must return some more input data (at least one byte) as a string. If there is no more data to be read, then the callback should return either \f(CW\*(C`undef\*(C'\fR or the empty string. If \s-1ARG\s0 values were supplied to the constructor, then they will be passed to the callback each time it is invoked.
.PP
For a write-only filehandle, the callback will be invoked each time there is data to be written. The first argument will be the data as a string, which will always be at least one byte long. If \s-1ARG\s0 values were supplied to the constructor, then they will be passed as additional arguments to the callback. When the filehandle is closed, the callback will be invoked once with the empty string as its first argument.
.PP
To simulate a non-fatal error on the file, the callback should set \f(CW$!\fR and return the special value \f(CW\*(C`IO::Callback::Error\*(C'\fR. See examples 6 and 7 below.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.IP "Example 1" 4
.IX Item "Example 1"
To generate a filehandle from which an infinite number of \f(CW\*(C`x\*(C'\fR characters can be read:
.Sp
.Vb 1
\&  my $fh = IO::Callback\->new(\*(Aq<\*(Aq, sub {"xxxxxxxxxxxxxxxxxxxxxxxxxxx"});
\&
\&  my $x = $fh\->getc;  # $x now contains "x"
\&  read $fh, $x, 5;    # $x now contains "xxxxx"
.Ve
.IP "Example 2" 4
.IX Item "Example 2"
A filehandle from which 1000 \f(CW\*(C`foo\*(C'\fR lines can be read before \s-1EOF:\s0
.Sp
.Vb 5
\&  my $count = 0;
\&  my $fh = IO::Callback\->new(\*(Aq<\*(Aq, sub {
\&      return if ++$count > 1000; # EOF
\&      return "foo\en";
\&  });
\&
\&  my $x = <$fh>;    # $x now contains "foo\en"
\&  read $fh, $x, 2;  # $x now contains "fo"
\&  read $fh, $x, 2;  # $x now contains "o\en"
\&  read $fh, $x, 20; # $x now contains "foo\enfoo\enfoo\enfoo\enfoo\en"
\&  my @foos = <$fh>; # @foos now contains ("foo\en") x 993
.Ve
.Sp
The example above uses a \f(CW\*(C`closure\*(C'\fR (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 \f(CW\*(C`IO::Callback\*(C'\fR will forward extra constructor arguments to the callback. This example could be re-written as:
.Sp
.Vb 2
\&  my $count = 0;
\&  my $fh = IO::Callback\->new(\*(Aq<\*(Aq, \e&my_callback, \e$count); 
\&
\&  my $x = <$fh>;    # $x now contains "foo\en"
\&  read $fh, $x, 2;  # $x now contains "fo"
\&  read $fh, $x, 2;  # $x now contains "o\en"
\&  read $fh, $x, 20; # $x now contains "foo\enfoo\enfoo\enfoo\enfoo\en"
\&  my @foos = <$fh>; # @foos now contains ("foo\en") x 993
\&
\&  sub my_callback {
\&      my $count_ref = shift;
\&
\&      return if ++$$count_ref > 1000; # EOF
\&      return "foo\en";
\&  };
.Ve
.IP "Example 3" 4
.IX Item "Example 3"
To generate a filehandle interface to data drawn from an \s-1SQL\s0 table:
.Sp
.Vb 7
\&  my $sth = $dbh\->prepare("SELECT ...");
\&  $sth\->execute;
\&  my $fh = IO::Callback\->new(\*(Aq<\*(Aq, sub {
\&      my @row = $sth\->fetchrow_array;
\&      return unless @row; # EOF
\&      return join(\*(Aq,\*(Aq, @row) . "\en";
\&  });
\&
\&  # ...
.Ve
.IP "Example 4" 4
.IX Item "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 \f(CW\*(C`foo\*(C'\fR.
.Sp
.Vb 4
\&  my $buf = \*(Aq\*(Aq;
\&  my $fh = IO::Callback\->new(\*(Aq>\*(Aq, sub {
\&      $buf .= shift;
\&      die "foo written" if $buf =~ /foo/;
\&
\&      if ($buf =~ /(fo?)\ez/) {
\&          # Part way through a "foo", carry over to the next block.
\&          $buf = $1;
\&      } else {
\&          $buf = \*(Aq\*(Aq;
\&      }
\&  });
.Ve
.IP "Example 5" 4
.IX Item "Example 5"
You have been given an object with a \fIcopy_data_out()\fR 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 \s-1SQL\s0 database.
.Sp
.Vb 2
\&  my $blocksize = 1024;
\&  my $sth = $dbh\->prepare(\*(AqINSERT ...\*(Aq);
\&
\&  my $buf = \*(Aq\*(Aq;
\&  my $fh = IO::Callback\->new(\*(Aq>\*(Aq, sub {
\&      $buf .= shift;
\&      while (length $buf >= $blocksize) {
\&          $sth\->execute(substr $buf, 0, $blocksize, \*(Aq\*(Aq);
\&      }
\&  });
\&
\&  $thing\->copy_data_out($fh);
\&
\&  if (length $buf) {
\&      # There is a remainder of < $blocksize
\&      $sth\->execute($buf);
\&  }
.Ve
.IP "Example 6" 4
.IX Item "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 \s-1IO\s0 error part way through the file.
.Sp
.Vb 2
\&  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(\*(Aq<\*(Aq, sub {
\&      return shift @blocks if @blocks;
\&      $! = EIO;
\&      return IO::Callback::Error;
\&  });
\&
\&  # ...
.Ve
.IP "Example 7" 4
.IX Item "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 \f(CW\*(C`file system full\*(C'\fR error after it has written the first 100k of data.
.Sp
.Vb 2
\&  use IO::Callback;
\&  use Errno qw/ENOSPC/;
\&
\&  my $wrote = 0;
\&  my $fh = IO::Callback\->new(\*(Aq>\*(Aq, sub {
\&      $wrote += length $_[0];
\&      if ($wrote > 100_000) {
\&          $! = ENOSPC;
\&          return IO::Callback::Error;
\&      }
\&  });
\&
\&  # ...
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Taylor, \f(CW\*(C`<dave.taylor.cpan at gmail.com>\*(C'\fR
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
Fails to inter-operate with some library modules that read or write filehandles from within \s-1XS\s0 code. I am aware of the following specific cases, please let me know if you run into any others:
.ie n .IP """Digest::MD5::addfile()""" 4
.el .IP "\f(CWDigest::MD5::addfile()\fR" 4
.IX Item "Digest::MD5::addfile()"
.PP
Please report any other bugs or feature requests to \f(CW\*(C`bug\- at rt.cpan.org\*(C'\fR, 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.
.SH "SUPPORT"
.IX Header "SUPPORT"
You can find documentation for this module with the perldoc command.
.PP
.Vb 1
\&    perldoc IO::Callback
.Ve
.PP
You can also look for information at:
.IP "\(bu" 4
\&\s-1RT: CPAN\s0's request tracker
.Sp
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=IO::Callback>
.IP "\(bu" 4
AnnoCPAN: Annotated \s-1CPAN\s0 documentation
.Sp
<http://annocpan.org/dist/IO::Callback>
.IP "\(bu" 4
\&\s-1CPAN\s0 Ratings
.Sp
<http://cpanratings.perl.org/d/IO::Callback>
.IP "\(bu" 4
Search \s-1CPAN\s0
.Sp
<http://search.cpan.org/dist/IO::Callback>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
IO::String, IO::Stringy, \*(L"open\*(R" in perlfunc
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Adapted from code in IO::String by Gisle Aas.
.SH "MANITAINER"
.IX Header "MANITAINER"
This module is currently being maintained by Toby Inkster (\s-1TOBYINK\s0)
for bug fixes. No substantial changes or new features are planned.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 1998\-2005 Gisle Aas.
.PP
Copyright 2009\-2010 Dave Taylor.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.