Test::Builder::IO::Scalar(3p) Perl Programmers Reference Guide #
Test::Builder::IO::Scalar(3p) Perl Programmers Reference Guide
NNAAMMEE #
Test::Builder::IO::Scalar - A copy of IO::Scalar for Test::Builder
DDEESSCCRRIIPPTTIIOONN #
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 "open()"'s built in support.
Test::Builder can not have dependencies on other modules without careful
consideration, so its simply been copied into the distribution.
CCOOPPYYRRIIGGHHTT aanndd LLIICCEENNSSEE This file came from the “IO-stringy” Perl5 toolkit.
Copyright (c) 1996 by Eryq. All rights reserved. Copyright (c)
1999,2001 by ZeeGee Software Inc. All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
CCoonnssttrruuccttiioonn new [ARGS…] _C_l_a_s_s _m_e_t_h_o_d_. Return a new, unattached scalar handle. If any arguments are given, they’re sent to ooppeenn(()).
open [SCALARREF]
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. 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.
Returns the self object on success, undefined on error.
opened
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Is the scalar handle opened on something?
close
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Disassociate the scalar handle from its underlying
scalar. Done automatically on destroy.
IInnppuutt aanndd oouuttppuutt flush _I_n_s_t_a_n_c_e _m_e_t_h_o_d_. No-op, provided for OO compatibility.
getc
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Return the next character, or undef if none remain.
getline
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Return the next line, or undef on end of string.
Can safely be called in an array context. Currently, lines are
delimited by "\n".
getlines
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Get all remaining lines. It will ccrrooaakk(()) if
accidentally called in a scalar context.
print ARGS...
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Print ARGS to the underlying scalar.
WWaarrnniinngg:: this continues to always cause a seek to the end of the
string, but if you perform sseeeekk(())s and tteellll(())s, it is still safer to
explicitly seek-to-end before subsequent pprriinntt(())s.
read BUF, NBYTES, [OFFSET]
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Read some bytes from the scalar. Returns the number
of bytes actually read, 0 on end-of-file, undef on error.
write BUF, NBYTES, [OFFSET]
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Write some bytes to the scalar.
sysread BUF, LEN, [OFFSET]
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Read some bytes from the scalar. Returns the number
of bytes actually read, 0 on end-of-file, undef on error.
syswrite BUF, NBYTES, [OFFSET]
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Write some bytes to the scalar.
SSeeeekkiinngg//tteelllliinngg aanndd ootthheerr aattttrriibbuutteess autoflush _I_n_s_t_a_n_c_e _m_e_t_h_o_d_. No-op, provided for OO compatibility.
binmode
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. No-op, provided for OO compatibility.
clearerr
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Clear the error and EOF flags. A no-op.
eof _I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Are we at end of file?
seek OFFSET, WHENCE
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Seek to a given position in the stream.
sysseek OFFSET, WHENCE
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Identical to "seek OFFSET, WHENCE", _q_._v_.
tell
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Return the current position in the stream, as a
numeric offset.
use_RS [YESNO]
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. DDeepprreeccaatteedd aanndd iiggnnoorreedd.. Obey the current setting of
$/, like IO::Handle does? Default is false in 1.x, but cold-welded
true in 2.x and later.
setpos POS
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Set the current position, using the opaque value
returned by "getpos()".
getpos
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Return the current position in the string, as an
opaque object.
sref
_I_n_s_t_a_n_c_e _m_e_t_h_o_d_. Return a reference to the underlying scalar.
WWAARRNNIINNGGSS #
Perl's TIEHANDLE spec was incomplete prior to 5.005_57; it was missing
support for "seek()", "tell()", and "eof()". 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 $^W or
"perl -w"), and you see something like this...
attempt to seek on unopened filehandle
...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.:
$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
VVEERRSSIIOONN #
$Id: Scalar.pm,v 1.6 2005/02/10 21:21:53 dfs Exp $
AAUUTTHHOORRSS #
PPrriimmaarryy MMaaiinnttaaiinneerr David F. Skoll (_d_f_s_@_r_o_a_r_i_n_g_p_e_n_g_u_i_n_._c_o_m).
PPrriinncciippaall aauutthhoorr Eryq (_e_r_y_q_@_z_e_e_g_e_e_._c_o_m). President, ZeeGee Software Inc (_h_t_t_p_:_/_/_w_w_w_._z_e_e_g_e_e_._c_o_m).
OOtthheerr ccoonnttrriibbuuttoorrss 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!):
_A_n_d_y _G_l_e_w_, for contributing "getc()".
_B_r_a_n_d_o_n _B_r_o_w_n_i_n_g_, for suggesting "opened()".
_D_a_v_i_d _R_i_c_h_t_e_r_, for finding and fixing the bug in "PRINTF()".
_E_r_i_c _L_. _B_r_i_n_e_, for his offset-using rreeaadd(()) and wwrriittee(()) implementations.
_R_i_c_h_a_r_d _J_o_n_e_s_, for his patches to massively improve the performance of
"getline()" and add "sysread" and "syswrite".
_B_. _K_. _O_x_l_e_y _(_b_i_n_k_l_e_y_)_, for stringification and inheritance improvements,
and sundry good ideas.
_D_o_u_g _W_i_l_s_o_n_, for the IO::Handle inheritance and automatic tie-ing.
SSEEEE AALLSSOO #
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 ttiieedd(()).
_N_o_t_e_: as of version 2.x, these classes all work like their IO::Handle
counterparts, so we have comparable functionality to IO::String.
perl v5.36.3 2019-02-13 Test::Builder::IO::Scalar(3p)