Debian Codegraph @

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

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Test::Builder::IO::Scalar 3perl"
58 .TH Test::Builder::IO::Scalar 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Test::Builder::IO::Scalar \- A copy of IO::Scalar for Test::Builder
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 This is a copy of IO::Scalar which ships with Test::Builder to
68 support scalar references as filehandles on Perl 5.6. Newer
69 versions of Perl simply use \f(CWopen()\fR's built in support.
70 .PP
71 Test::Builder can not have dependencies on other modules without
72 careful consideration, so its simply been copied into the distribution.
73 .SH "COPYRIGHT and LICENSE"
74 .IX Header "COPYRIGHT and LICENSE"
75 This file came from the "IO-stringy" Perl5 toolkit.
76 .PP
77 Copyright (c) 1996 by Eryq. All rights reserved.
78 Copyright (c) 1999,2001 by ZeeGee Software Inc. All rights reserved.
79 .PP
80 This program is free software; you can redistribute it and/or
81 modify it under the same terms as Perl itself.
82 .SS Construction
83 .IX Subsection "Construction"
84 .IP "new [ARGS...]" 4
85 .IX Item "new [ARGS...]"
86 \&\fIClass method.\fR
87 Return a new, unattached scalar handle.
88 If any arguments are given, they're sent to \fBopen()\fR.
89 .IP "open [SCALARREF]" 4
90 .IX Item "open [SCALARREF]"
91 \&\fIInstance method.\fR
92 Open the scalar handle on a new scalar, pointed to by SCALARREF.
93 If no SCALARREF is given, a "private" scalar is created to hold
94 the file data.
95 .Sp
96 Returns the self object on success, undefined on error.
97 .IP opened 4
98 .IX Item "opened"
99 \&\fIInstance method.\fR
100 Is the scalar handle opened on something?
101 .IP close 4
102 .IX Item "close"
103 \&\fIInstance method.\fR
104 Disassociate the scalar handle from its underlying scalar.
105 Done automatically on destroy.
106 .SS "Input and output"
107 .IX Subsection "Input and output"
108 .IP flush 4
109 .IX Item "flush"
110 \&\fIInstance method.\fR
111 No-op, provided for OO compatibility.
112 .IP getc 4
113 .IX Item "getc"
114 \&\fIInstance method.\fR
115 Return the next character, or undef if none remain.
116 .IP getline 4
117 .IX Item "getline"
118 \&\fIInstance method.\fR
119 Return the next line, or undef on end of string.
120 Can safely be called in an array context.
121 Currently, lines are delimited by "\en".
122 .IP getlines 4
123 .IX Item "getlines"
124 \&\fIInstance method.\fR
125 Get all remaining lines.
126 It will \fBcroak()\fR if accidentally called in a scalar context.
127 .IP "print ARGS..." 4
128 .IX Item "print ARGS..."
129 \&\fIInstance method.\fR
130 Print ARGS to the underlying scalar.
131 .Sp
132 \&\fBWarning:\fR this continues to always cause a seek to the end
133 of the string, but if you perform \fBseek()\fRs and \fBtell()\fRs, it is
134 still safer to explicitly seek-to-end before subsequent \fBprint()\fRs.
135 .IP "read BUF, NBYTES, [OFFSET]" 4
136 .IX Item "read BUF, NBYTES, [OFFSET]"
137 \&\fIInstance method.\fR
138 Read some bytes from the scalar.
139 Returns the number of bytes actually read, 0 on end-of-file, undef on error.
140 .IP "write BUF, NBYTES, [OFFSET]" 4
141 .IX Item "write BUF, NBYTES, [OFFSET]"
142 \&\fIInstance method.\fR
143 Write some bytes to the scalar.
144 .IP "sysread BUF, LEN, [OFFSET]" 4
145 .IX Item "sysread BUF, LEN, [OFFSET]"
146 \&\fIInstance method.\fR
147 Read some bytes from the scalar.
148 Returns the number of bytes actually read, 0 on end-of-file, undef on error.
149 .IP "syswrite BUF, NBYTES, [OFFSET]" 4
150 .IX Item "syswrite BUF, NBYTES, [OFFSET]"
151 \&\fIInstance method.\fR
152 Write some bytes to the scalar.
153 .SS "Seeking/telling and other attributes"
154 .IX Subsection "Seeking/telling and other attributes"
155 .IP autoflush 4
156 .IX Item "autoflush"
157 \&\fIInstance method.\fR
158 No-op, provided for OO compatibility.
159 .IP binmode 4
160 .IX Item "binmode"
161 \&\fIInstance method.\fR
162 No-op, provided for OO compatibility.
163 .IP clearerr 4
164 .IX Item "clearerr"
165 \&\fIInstance method.\fR Clear the error and EOF flags. A no-op.
166 .IP eof 4
167 .IX Item "eof"
168 \&\fIInstance method.\fR Are we at end of file?
169 .IP "seek OFFSET, WHENCE" 4
170 .IX Item "seek OFFSET, WHENCE"
171 \&\fIInstance method.\fR Seek to a given position in the stream.
172 .IP "sysseek OFFSET, WHENCE" 4
173 .IX Item "sysseek OFFSET, WHENCE"
174 \&\fIInstance method.\fR Identical to \f(CW\*(C`seek OFFSET, WHENCE\*(C'\fR, \fIq.v.\fR
175 .IP tell 4
176 .IX Item "tell"
177 \&\fIInstance method.\fR
178 Return the current position in the stream, as a numeric offset.
179 .IP "use_RS [YESNO]" 4
180 .IX Item "use_RS [YESNO]"
181 \&\fIInstance method.\fR
182 \&\fBDeprecated and ignored.\fR
183 Obey the current setting of $/, like IO::Handle does?
184 Default is false in 1.x, but cold-welded true in 2.x and later.
185 .IP "setpos POS" 4
186 .IX Item "setpos POS"
187 \&\fIInstance method.\fR
188 Set the current position, using the opaque value returned by \f(CWgetpos()\fR.
189 .IP getpos 4
190 .IX Item "getpos"
191 \&\fIInstance method.\fR
192 Return the current position in the string, as an opaque object.
193 .IP sref 4
194 .IX Item "sref"
195 \&\fIInstance method.\fR
196 Return a reference to the underlying scalar.
197 .SH WARNINGS
198 .IX Header "WARNINGS"
199 Perl's TIEHANDLE spec was incomplete prior to 5.005_57;
200 it was missing support for \f(CWseek()\fR, \f(CWtell()\fR, and \f(CWeof()\fR.
201 Attempting to use these functions with an IO::Scalar will not work
202 prior to 5.005_57. IO::Scalar will not have the relevant methods
203 invoked; and even worse, this kind of bug can lie dormant for a while.
204 If you turn warnings on (via \f(CW$^W\fR or \f(CW\*(C`perl \-w\*(C'\fR),
205 and you see something like this...
206 .PP
207 .Vb 1
208 \& attempt to seek on unopened filehandle
209 .Ve
210 .PP
211 \&...then you are probably trying to use one of these functions
212 on an IO::Scalar with an old Perl. The remedy is to simply
213 use the OO version; e.g.:
214 .PP
215 .Vb 2
216 \& $SH\->seek(0,0); ### GOOD: will work on any 5.005
217 \& seek($SH,0,0); ### WARNING: will only work on 5.005_57 and beyond
218 .Ve
219 .SH VERSION
220 .IX Header "VERSION"
221 \&\f(CW$Id:\fR Scalar.pm,v 1.6 2005/02/10 21:21:53 dfs Exp $
222 .SH AUTHORS
223 .IX Header "AUTHORS"
224 .SS "Primary Maintainer"
225 .IX Subsection "Primary Maintainer"
226 David F. Skoll (\[email protected]\fR).
227 .SS "Principal author"
228 .IX Subsection "Principal author"
229 Eryq (\[email protected]\fR).
230 President, ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR).
231 .SS "Other contributors"
232 .IX Subsection "Other contributors"
233 The full set of contributors always includes the folks mentioned
234 in "CHANGE LOG" in IO::Stringy. But just the same, special
235 thanks to the following individuals for their invaluable contributions
236 (if I've forgotten or misspelled your name, please email me!):
237 .PP
238 \&\fIAndy Glew,\fR
239 for contributing \f(CWgetc()\fR.
240 .PP
241 \&\fIBrandon Browning,\fR
242 for suggesting \f(CWopened()\fR.
243 .PP
244 \&\fIDavid Richter,\fR
245 for finding and fixing the bug in \f(CWPRINTF()\fR.
246 .PP
247 \&\fIEric L. Brine,\fR
248 for his offset-using \fBread()\fR and \fBwrite()\fR implementations.
249 .PP
250 \&\fIRichard Jones,\fR
251 for his patches to massively improve the performance of \f(CWgetline()\fR
252 and add \f(CW\*(C`sysread\*(C'\fR and \f(CW\*(C`syswrite\*(C'\fR.
253 .PP
254 \&\fIB. K. Oxley (binkley),\fR
255 for stringification and inheritance improvements,
256 and sundry good ideas.
257 .PP
258 \&\fIDoug Wilson,\fR
259 for the IO::Handle inheritance and automatic tie-ing.
260 .SH "SEE ALSO"
261 .IX Header "SEE ALSO"
262 IO::String, which is quite similar but which was designed
263 more-recently and with an IO::Handle\-like interface in mind,
264 so you could mix OO\- and native-filehandle usage without using \fBtied()\fR.
265 .PP
266 \&\fINote:\fR as of version 2.x, these classes all work like
267 their IO::Handle counterparts, so we have comparable
268 functionality to IO::String.