path: root/upstream/debian-unstable/man3/Test::Builder::IO::Scalar.3perl

.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
.\" ========================================================================
.\"
.IX Title "Test::Builder::IO::Scalar 3perl"
.TH Test::Builder::IO::Scalar 3perl 2024-05-30 "perl v5.38.2" "Perl Programmers Reference Guide"
.\" 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
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(CWopen()\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 "IO-stringy" 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.
.SS Construction
.IX Subsection "Construction"
.IP "new [ARGS...]" 4
.IX Item "new [ARGS...]"
\&\fIClass method.\fR
Return a new, unattached scalar handle.
If any arguments are given, they're sent to \fBopen()\fR.
.IP "open [SCALARREF]" 4
.IX Item "open [SCALARREF]"
\&\fIInstance method.\fR
Open the scalar handle on a new scalar, pointed to by SCALARREF.
If no SCALARREF is given, a "private" 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.
.SS "Input and output"
.IX Subsection "Input and output"
.IP flush 4
.IX Item "flush"
\&\fIInstance method.\fR
No-op, provided for OO 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 "\en".
.IP getlines 4
.IX Item "getlines"
\&\fIInstance method.\fR
Get all remaining lines.
It will \fBcroak()\fR if accidentally called in a scalar context.
.IP "print ARGS..." 4
.IX Item "print ARGS..."
\&\fIInstance method.\fR
Print ARGS to the underlying scalar.
.Sp
\&\fBWarning:\fR this continues to always cause a seek to the end
of the string, but if you perform \fBseek()\fRs and \fBtell()\fRs, it is
still safer to explicitly seek-to-end before subsequent \fBprint()\fRs.
.IP "read BUF, NBYTES, [OFFSET]" 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 BUF, NBYTES, [OFFSET]" 4
.IX Item "write BUF, NBYTES, [OFFSET]"
\&\fIInstance method.\fR
Write some bytes to the scalar.
.IP "sysread BUF, LEN, [OFFSET]" 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 BUF, NBYTES, [OFFSET]" 4
.IX Item "syswrite BUF, NBYTES, [OFFSET]"
\&\fIInstance method.\fR
Write some bytes to the scalar.
.SS "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 OO compatibility.
.IP binmode 4
.IX Item "binmode"
\&\fIInstance method.\fR
No-op, provided for OO compatibility.
.IP clearerr 4
.IX Item "clearerr"
\&\fIInstance method.\fR  Clear the error and EOF flags.  A no-op.
.IP eof 4
.IX Item "eof"
\&\fIInstance method.\fR  Are we at end of file?
.IP "seek OFFSET, WHENCE" 4
.IX Item "seek OFFSET, WHENCE"
\&\fIInstance method.\fR  Seek to a given position in the stream.
.IP "sysseek OFFSET, WHENCE" 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 [YESNO]" 4
.IX Item "use_RS [YESNO]"
\&\fIInstance method.\fR
\&\fBDeprecated and ignored.\fR
Obey the current setting of $/, like IO::Handle does?
Default is false in 1.x, but cold-welded true in 2.x and later.
.IP "setpos POS" 4
.IX Item "setpos POS"
\&\fIInstance method.\fR
Set the current position, using the opaque value returned by \f(CWgetpos()\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 TIEHANDLE spec was incomplete prior to 5.005_57;
it was missing support for \f(CWseek()\fR, \f(CWtell()\fR, and \f(CWeof()\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 OO 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"
\&\f(CW$Id:\fR Scalar.pm,v 1.6 2005/02/10 21:21:53 dfs Exp $
.SH AUTHORS
.IX Header "AUTHORS"
.SS "Primary Maintainer"
.IX Subsection "Primary Maintainer"
David F. Skoll (\fIdfs@roaringpenguin.com\fR).
.SS "Principal author"
.IX Subsection "Principal author"
Eryq (\fIeryq@zeegee.com\fR).
President, ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR).
.SS "Other contributors"
.IX Subsection "Other contributors"
The full set of contributors always includes the folks mentioned
in "CHANGE LOG" 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(CWgetc()\fR.
.PP
\&\fIBrandon Browning,\fR
for suggesting \f(CWopened()\fR.
.PP
\&\fIDavid Richter,\fR
for finding and fixing the bug in \f(CWPRINTF()\fR.
.PP
\&\fIEric L. Brine,\fR
for his offset-using \fBread()\fR and \fBwrite()\fR implementations.
.PP
\&\fIRichard Jones,\fR
for his patches to massively improve the performance of \f(CWgetline()\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 OO\- and native-filehandle usage without using \fBtied()\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.