.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 >0, 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::Handle::Prototype::Fallback 3pm"
.TH IO::Handle::Prototype::Fallback 3pm "2023-01-24" "perl v5.36.0" "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::Handle::Prototype::Fallback \- Create IO::Handle like objects using a set
of callbacks.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    my $fh = IO::Handle::Prototype::Fallback\->new(
\&        getline => sub {
\&            my $fh = shift;
\&
\&            ...
\&        },
\&    );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class provides a way to define a filehandle based on callbacks.
.PP
Fallback implementations are provided to the extent possible based on the
provided callbacks, for both writing and reading.
.SH "SPECIAL CALLBACKS"
.IX Header "SPECIAL CALLBACKS"
This class provides two additional methods on top of IO::Handle, designed to
let you implement things with a minimal amount of baggage.
.PP
The fallback methods are all best implemented using these, though these can be
implemented in terms of Perl's standard methods too.
.PP
However, to provide the most consistent semantics, it's better to do this:
.PP
.Vb 5
\&    IO::Handle::Prototype::Fallback\->new(
\&        _\|_read => sub {
\&            shift @array;
\&        },
\&    );
.Ve
.PP
Than this:
.PP
.Vb 5
\&    IO::Handle::Prototype::Fallback\->new(
\&        getline => sub {
\&            shift @array;
\&        },
\&    );
.Ve
.PP
Because the fallback implementation of \f(CW\*(C`getline\*(C'\fR implements all of the extra
crap you'd need to handle to have a fully featured implementation.
.IP "_\|_read" 4
.IX Item "__read"
Return a chunk of data of any size (could use \f(CW$/\fR or not, it depends on you,
unlike \f(CW\*(C`getline\*(C'\fR which probably \fIshould\fR respect the value of \f(CW$/\fR).
.Sp
This avoids the annoying \f(CW\*(C`substr\*(C'\fR stuff you need to do with \f(CW\*(C`read\*(C'\fR.
.ie n .IP "_\|_write $string" 4
.el .IP "_\|_write \f(CW$string\fR" 4
.IX Item "__write $string"
Write out a string.
.Sp
This is like a simplified \f(CW\*(C`print\*(C'\fR, which can disregard \f(CW$,\fR and \f(CW\*(C`$\e\*(C'\fR as well
as multiple argument forms, and does not have the extra \f(CW\*(C`substr\*(C'\fR annoyance of
\&\f(CW\*(C`write\*(C'\fR or \f(CW\*(C`syswrite\*(C'\fR.
.SH "WRAPPING"
.IX Header "WRAPPING"
If you provide a \fBsingle\fR reading related callback (\f(CW\*(C`_\|_read\*(C'\fR, \f(CW\*(C`getline\*(C'\fR or
\&\f(CW\*(C`read\*(C'\fR) then your callback will be used to implement all of the other reading
primitives using a string buffer.
.PP
These implementations handle \f(CW$/\fR in all forms (\f(CW\*(C`undef\*(C'\fR, ref to number and
string), all the funny calling conventions for \f(CW\*(C`read\*(C'\fR, etc.
.SH "FALLBACKS"
.IX Header "FALLBACKS"
Any callback that can be defined purely in terms of other callbacks in a way
will be added. For instance \f(CW\*(C`getc\*(C'\fR can be implemented in terms of \f(CW\*(C`read\*(C'\fR,
\&\f(CW\*(C`say\*(C'\fR can be implemented in terms of \f(CW\*(C`print\*(C'\fR, \f(CW\*(C`print\*(C'\fR can be implemented in
terms of \f(CW\*(C`write\*(C'\fR, \f(CW\*(C`write\*(C'\fR can be implemented in terms of \f(CW\*(C`print\*(C'\fR, etc.
.PP
None of these require special wrapping and will always be added if their
dependencies are present.
.SH "GLOB OVERLOADING"
.IX Header "GLOB OVERLOADING"
When overloaded as a glob a tied handle will be returned. This allows you to
use the handle in Perl's \s-1IO\s0 builtins. For instance:
.PP
.Vb 1
\&    my $line = <$fh>
.Ve
.PP
will not call the \f(CW\*(C`getline\*(C'\fR method natively, but the tied interface arranges
for that to happen.