Add built local::lib

[catagits/Gitalist.git] / local-lib5 / man / man3 / Test::Builder::IO::Scalar.3pm

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" 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 "Test::Builder::IO::Scalar 3"
.TH Test::Builder::IO::Scalar 3 "2009-09-02" "perl v5.8.7" "User Contributed Perl Documentation"
.SH "NAME"
Test::Builder::IO::Scalar \- A copy of IO::Scalar for Test::Builder
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a copy of IO::Scalar which ships with Test::Builder to
support scalar references as filehandles on Perl 5.6.  Newer
versions of Perl simply use \f(CW\*(C`<open()\*(C'\fR>'s built in support.
.PP
Test::Builder can not have dependencies on other modules without
careful consideration, so its simply been copied into the distribution.
.SH "COPYRIGHT and LICENSE"
.IX Header "COPYRIGHT and LICENSE"
This file came from the \*(L"IO\-stringy\*(R" Perl5 toolkit.
.PP
Copyright (c) 1996 by Eryq.  All rights reserved.
Copyright (c) 1999,2001 by ZeeGee Software Inc.  All rights reserved.
.PP
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.Sh "Construction"
.IX Subsection "Construction"
.IP "new [\s-1ARGS\s0...]" 4
.IX Item "new [ARGS...]"
\&\fIClass method.\fR
Return a new, unattached scalar handle.
If any arguments are given, they're sent to \fIopen()\fR.
.IP "open [\s-1SCALARREF\s0]" 4
.IX Item "open [SCALARREF]"
\&\fIInstance method.\fR
Open the scalar handle on a new scalar, pointed to by \s-1SCALARREF\s0.
If no \s-1SCALARREF\s0 is given, a \*(L"private\*(R" scalar is created to hold
the file data.
.Sp
Returns the self object on success, undefined on error.
.IP "opened" 4
.IX Item "opened"
\&\fIInstance method.\fR
Is the scalar handle opened on something?
.IP "close" 4
.IX Item "close"
\&\fIInstance method.\fR
Disassociate the scalar handle from its underlying scalar.
Done automatically on destroy.
.Sh "Input and output"
.IX Subsection "Input and output"
.IP "flush" 4
.IX Item "flush"
\&\fIInstance method.\fR
No\-op, provided for \s-1OO\s0 compatibility.
.IP "getc" 4
.IX Item "getc"
\&\fIInstance method.\fR
Return the next character, or undef if none remain.
.IP "getline" 4
.IX Item "getline"
\&\fIInstance method.\fR
Return the next line, or undef on end of string.
Can safely be called in an array context.
Currently, lines are delimited by \*(L"\en\*(R".
.IP "getlines" 4
.IX Item "getlines"
\&\fIInstance method.\fR
Get all remaining lines.
It will \fIcroak()\fR if accidentally called in a scalar context.
.IP "print \s-1ARGS\s0..." 4
.IX Item "print ARGS..."
\&\fIInstance method.\fR
Print \s-1ARGS\s0 to the underlying scalar.
.Sp
\&\fBWarning:\fR this continues to always cause a seek to the end
of the string, but if you perform \fIseek()\fRs and \fItell()\fRs, it is
still safer to explicitly seek-to-end before subsequent \fIprint()\fRs.
.IP "read \s-1BUF\s0, \s-1NBYTES\s0, [\s-1OFFSET\s0]" 4
.IX Item "read BUF, NBYTES, [OFFSET]"
\&\fIInstance method.\fR
Read some bytes from the scalar.
Returns the number of bytes actually read, 0 on end\-of\-file, undef on error.
.IP "write \s-1BUF\s0, \s-1NBYTES\s0, [\s-1OFFSET\s0]" 4
.IX Item "write BUF, NBYTES, [OFFSET]"
\&\fIInstance method.\fR
Write some bytes to the scalar.
.IP "sysread \s-1BUF\s0, \s-1LEN\s0, [\s-1OFFSET\s0]" 4
.IX Item "sysread BUF, LEN, [OFFSET]"
\&\fIInstance method.\fR
Read some bytes from the scalar.
Returns the number of bytes actually read, 0 on end\-of\-file, undef on error.
.IP "syswrite \s-1BUF\s0, \s-1NBYTES\s0, [\s-1OFFSET\s0]" 4
.IX Item "syswrite BUF, NBYTES, [OFFSET]"
\&\fIInstance method.\fR
Write some bytes to the scalar.
.Sh "Seeking/telling and other attributes"
.IX Subsection "Seeking/telling and other attributes"
.IP "autoflush" 4
.IX Item "autoflush"
\&\fIInstance method.\fR
No\-op, provided for \s-1OO\s0 compatibility.
.IP "binmode" 4
.IX Item "binmode"
\&\fIInstance method.\fR
No\-op, provided for \s-1OO\s0 compatibility.
.IP "clearerr" 4
.IX Item "clearerr"
\&\fIInstance method.\fR  Clear the error and \s-1EOF\s0 flags.  A no\-op.
.IP "eof" 4
.IX Item "eof"
\&\fIInstance method.\fR  Are we at end of file?
.IP "seek \s-1OFFSET\s0, \s-1WHENCE\s0" 4
.IX Item "seek OFFSET, WHENCE"
\&\fIInstance method.\fR  Seek to a given position in the stream.
.IP "sysseek \s-1OFFSET\s0, \s-1WHENCE\s0" 4
.IX Item "sysseek OFFSET, WHENCE"
\&\fIInstance method.\fR Identical to \f(CW\*(C`seek OFFSET, WHENCE\*(C'\fR, \fIq.v.\fR
.IP "tell" 4
.IX Item "tell"
\&\fIInstance method.\fR
Return the current position in the stream, as a numeric offset.
.IP "use_RS [\s-1YESNO\s0]" 4
.IX Item "use_RS [YESNO]"
\&\fIInstance method.\fR
\&\fBDeprecated and ignored.\fR
Obey the curent setting of $/, like IO::Handle does?
Default is false in 1.x, but cold-welded true in 2.x and later.
.IP "setpos \s-1POS\s0" 4
.IX Item "setpos POS"
\&\fIInstance method.\fR
Set the current position, using the opaque value returned by \f(CW\*(C`getpos()\*(C'\fR.
.IP "getpos" 4
.IX Item "getpos"
\&\fIInstance method.\fR
Return the current position in the string, as an opaque object.
.IP "sref" 4
.IX Item "sref"
\&\fIInstance method.\fR
Return a reference to the underlying scalar.
.SH "WARNINGS"
.IX Header "WARNINGS"
Perl's \s-1TIEHANDLE\s0 spec was incomplete prior to 5.005_57;
it was missing support for \f(CW\*(C`seek()\*(C'\fR, \f(CW\*(C`tell()\*(C'\fR, and \f(CW\*(C`eof()\*(C'\fR.
Attempting to use these functions with an IO::Scalar will not work
prior to 5.005_57. IO::Scalar will not have the relevant methods
invoked; and even worse, this kind of bug can lie dormant for a while.
If you turn warnings on (via \f(CW$^W\fR or \f(CW\*(C`perl \-w\*(C'\fR),
and you see something like this...
.PP
.Vb 1
\&    attempt to seek on unopened filehandle
.Ve
.PP
\&...then you are probably trying to use one of these functions
on an IO::Scalar with an old Perl.  The remedy is to simply
use the \s-1OO\s0 version; e.g.:
.PP
.Vb 2
\&    $SH\->seek(0,0);    ### GOOD: will work on any 5.005
\&    seek($SH,0,0);     ### WARNING: will only work on 5.005_57 and beyond
.Ve
.SH "VERSION"
.IX Header "VERSION"
$Id: Scalar.pm,v 1.6 2005/02/10 21:21:53 dfs Exp $
.SH "AUTHORS"
.IX Header "AUTHORS"
.Sh "Primary Maintainer"
.IX Subsection "Primary Maintainer"
David F. Skoll (\fIdfs@roaringpenguin.com\fR).
.Sh "Principal author"
.IX Subsection "Principal author"
Eryq (\fIeryq@zeegee.com\fR).
President, ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR).
.Sh "Other contributors"
.IX Subsection "Other contributors"
The full set of contributors always includes the folks mentioned
in \*(L"\s-1CHANGE\s0 \s-1LOG\s0\*(R" in IO::Stringy.  But just the same, special
thanks to the following individuals for their invaluable contributions
(if I've forgotten or misspelled your name, please email me!):
.PP
\&\fIAndy Glew,\fR
for contributing \f(CW\*(C`getc()\*(C'\fR.
.PP
\&\fIBrandon Browning,\fR
for suggesting \f(CW\*(C`opened()\*(C'\fR.
.PP
\&\fIDavid Richter,\fR
for finding and fixing the bug in \f(CW\*(C`PRINTF()\*(C'\fR.
.PP
\&\fIEric L. Brine,\fR
for his offset-using \fIread()\fR and \fIwrite()\fR implementations.
.PP
\&\fIRichard Jones,\fR
for his patches to massively improve the performance of \f(CW\*(C`getline()\*(C'\fR
and add \f(CW\*(C`sysread\*(C'\fR and \f(CW\*(C`syswrite\*(C'\fR.
.PP
\&\fIB. K. Oxley (binkley),\fR
for stringification and inheritance improvements,
and sundry good ideas.
.PP
\&\fIDoug Wilson,\fR
for the IO::Handle inheritance and automatic tie\-ing.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
IO::String, which is quite similar but which was designed
more-recently and with an IO::Handle\-like interface in mind,
so you could mix \s-1OO\-\s0 and native-filehandle usage without using \fItied()\fR.
.PP
\&\fINote:\fR as of version 2.x, these classes all work like
their IO::Handle counterparts, so we have comparable
functionality to IO::String.