Test::Builder::IO::Scalar(3p) Perl Programmers Reference Guide

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)