Test::...:Scalar(3pm)

📦
version 1.302198 · 6 versions
, in ubuntu noble

💖 NAME 💖

Okay bestie, gather round, because this is Test::Builder::IO::Scalar — a whole copy of IO::Scalar that lives inside Test::Builder so you can use scalar references as filehandles. Yes, that's the entire job description. She's a copy. She's iconic. She's on section 3pm of your manual and she's not sorry.

✨ DESCRIPTION ✨

So here's the tea: this is a copy of IO::Scalar that ships with Test::Builder specifically to support scalar references acting as filehandles on Perl 5.6. Newer versions of Perl? They literally just use open()'s built-in support, no drama, no middleman. 💅

And why is she a copy instead of a dependency? Because Test::Builder can not have dependencies on other modules without careful consideration, so the whole thing simply got copied into the distribution. That's it. That's the lore. 🫶

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. Slay, honestly. 👑

🌸 Construction 🌸

  • new [ARGS...] — Class method, bestie. Returns a brand-new, unattached scalar handle. If you hand it any arguments, they get sent straight to open().
  • open [SCALARREF] — Instance method. Opens the scalar handle on a new scalar, pointed to by SCALARREF. If you don't pass a SCALARREF, a "private" scalar gets created to hold the file data.

Returns the self object on success, undefined on error. (So like, check it. 🙈)

  • opened — Instance method. Is the scalar handle opened on something? Yes/no, that's the whole vibe check.
  • close — Instance method. Disassociates the scalar handle from its underlying scalar. This happens automatically on destroy, so she cleans up after herself. ✨

🦋 Input and output 🦋

  • flush — Instance method. No-op, provided for OO compatibility. She's just standing there, being compatible. 💀
  • getc — Instance method. Returns the next character, or undef if none remain.
  • getline — Instance method. Returns the next line, or undef on end of string. Can safely be called in an array context. Currently, lines are delimited by "\n".
  • getlines — Instance method. Gets all remaining lines. It will croak() if you accidentally call it in a scalar context, so don't do that, okay? 😭
  • print ARGS... — Instance method. Prints ARGS to the underlying scalar.
Warning: this continues to always cause a seek to the end of the string, but if you perform seek()s and tell()s, it is still safer to explicitly seek-to-end before subsequent print()s.
  • read BUF, NBYTES, [OFFSET] — Instance method. Reads some bytes from the scalar. Returns the number of bytes actually read, 0 on end-of-file, undef on error.
  • write BUF, NBYTES, [OFFSET] — Instance method. Writes some bytes to the scalar.
  • sysread BUF, LEN, [OFFSET] — Instance method. Reads some bytes from the scalar. Returns the number of bytes actually read, 0 on end-of-file, undef on error.
  • syswrite BUF, NBYTES, [OFFSET] — Instance method. Writes some bytes to the scalar.

⭐ Seeking/telling and other attributes ⭐

  • autoflush — Instance method. No-op, provided for OO compatibility.
  • binmode — Instance method. No-op, provided for OO compatibility.
  • clearerr — Instance method. Clears the error and EOF flags. A no-op.
  • eof — Instance method. Are we at end of file? That's the question.
  • seek OFFSET, WHENCE — Instance method. Seeks to a given position in the stream.
  • sysseek OFFSET, WHENCE — Instance method. Identical to seek OFFSET, WHENCE, q.v.
  • tell — Instance method. Returns the current position in the stream, as a numeric offset.
  • use_RS [YESNO] — Instance method. Deprecated and ignored. Should it obey the current setting of $/, like IO::Handle does? Default is false in 1.x, but cold-welded true in 2.x and later. (Yes, "cold-welded". We don't make the rules. 💀)
  • setpos POS — Instance method. Sets the current position, using the opaque value returned by getpos().
  • getpos — Instance method. Returns the current position in the string, as an opaque object.
  • sref — Instance method. Returns a reference to the underlying scalar. Bestie reveal. 🫶

⚠️ WARNINGS ⚠️

Okay so, important lore: Perl's TIEHANDLE spec was incomplete prior to 5.005_57. It was missing support for seek(), tell(), and eof(). So 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. Sneaky. 😭

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

Periodt. Use the OO one. 🙏

🌈 VERSION 🌈

$Id: Scalar.pm,v 1.6 2005/02/10 21:21:53 dfs Exp $

👑 AUTHORS 👑

💜 Primary Maintainer

David F. Skoll (dfs@roaringpenguin.com).

💜 Principal author

Eryq (eryq@zeegee.com). President, ZeeGee Software Inc (http://www.zeegee.com).

💜 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!):

  • Andy Glew, for contributing getc().
  • Brandon Browning, for suggesting opened().
  • David Richter, for finding and fixing the bug in PRINTF().
  • Eric L. Brine, for his offset-using read() and write() implementations.
  • Richard Jones, for his patches to massively improve the performance of getline() and add sysread and syswrite.
  • B. K. Oxley (binkley), for stringification and inheritance improvements, and sundry good ideas.
  • Doug Wilson, for the IO::Handle inheritance and automatic tie-ing.

🧚 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 tied().
Note: as of version 2.x, these classes all work like their IO::Handle counterparts, so we have comparable functionality to IO::String.

And that's the whole page, bestie!! This came to you from perl v5.36.0, dated 2023-12-03, and yes, the manpage title up top is that very same Test::...:Scalar(3pm) situation you scrolled past. Go forth and tie your scalars. 💅✨🎀

📦 where this page comes from