Module:...alar::IO(3)

🌸 Module::Generic::Scalar::IO — User Contributed Perl Documentation 🌸

✨ NAME ✨

Module::Generic::Scalar::IO — Generic Module Scalar IO Class

🌈 SYNOPSIS 🌈

okay bestie, here’s the whole vibe in code — literally the copy-paste moment 💅

my $s = Module::Generic::Scalar->new;
my $io = $s->open || die( $s->error );
# or
my $io = Module::Generic::Scalar::IO->new( $scalar_object );
# using PerlIO
my $io = Module::Generic::Scalar::IO->new( $scalar_object, '+>:ut8' );
my $io = Module::Generic::Scalar::IO->new( $scalar_object, '+>:binmode(ut-8)' );
my $io = Module::Generic::Scalar::IO->new( $scalar_object, '+>:bytes' );

$io->opened; # Return true if opened or false otherwise
$io->fileno; # returns -1
$io->flush;
$io->print( <<EOT );
Mignonne, allons voir si la rose
Qui ce matin avoit desclose
Sa robe de pourpre au Soleil,
A point perdu cette vesprée
Les plis de sa robe pourprée,
Et son teint au vostre pareil.
EOT
$io->printf( "Author: %s\n", 'Pierre de Ronsard' );
$io->getc; # return nothing, because we are at the end of file
$io->eof; # return true if we are at the end of string
$io->tell; # tells us our position in string
$io->seek(0,0);
my $l = $io->getline; # fetch the first line
$io->seek( $io->length - 1, 0 );
my $n = $io->write( ', Les Odes', 10 );
$io->seek(0,0);
@lines = $io->getlines;
print $lines[-1], "\n";
# Returns: Author: Pierre de Ronsard, Les Odes\n
$io->close;

🎀 VERSION 🎀

v0.2.1

🦋 DESCRIPTION 🦋

So this class, Module::Generic::Scalar::IO, implements object-oriented IO methods on a scalar reference. It inherits from Module::Generic::File::IO, and you can use all the methods from IO::Handle.

Unlike the default Perl open() behavior with a :scalar layer, this class adds:

• Automatic support for opening modes like r, w, w+, r+, a, etc.
• Access to low-level flags via fcntl, which are usually unavailable with plain scalar handles
• Convenient methods to inspect open mode (e.g. is_readonly, is_append, is_writeonly)
• Safe serialisation support for use with Storable or Sereal
• Automatic support for autoflush, binmode, and other standard I/O operations

Thus, this makes it possible to use a Module::Generic::Scalar object as a file handle to print and get data to and from it, and you can use it directly as well 💖

This normally can be achieved with PerlIO, like this:

my $ref = \"Hello";
open( my $fh, '+<:scalar', $ref ) || die( $! );

However, this interface provides some additions such as automatically setting filehandle flags derived from the opening mode, allowing advanced features like fcntl to work as expected.

my $flags = $fh->fcntl( F_GETFL, 0 );
$fh->fcntl( F_SETFL, O_RDWR );

This, in turn, allows the methods can_read and can_write and is_append, is_create, is_readonly, is_readwrite, is_writeonly to work.

One shortcoming due to perl’s own design, is if you call sysread( $fh, $buffer ) instead of $fh->sysread( $buffer ) or syswrite( $fh, $string ) instead of $fh->syswrite( $string ). While the latter works of course, the former does not, so always make sure to call those methods in an object-oriented way 😭✨

👑 CONSTRUCTOR 👑

🌟 new 🌟

my $io = Module::Generic::Scalar::IO->new( \$scalar_ref, 'w' );
my $io = Module::Generic::Scalar::IO->new({ scalar => \$scalar_ref, mode => 'r+' });

It takes a reference to a scalar — such as a Module::Generic::Scalar object or any other scalar reference — that will be treated as a memory buffer, plus some optional mode, and calls open. It returns a blessed file handle 🫶

If no mode is provided, it defaults to +< to allow for read and write, but without clobbering.

Supported modes are:

• "<" or "r" — Read-only
• "<+" or "r+" — Read and write. This is the default.
• ">" or "w" — Clobbering. This will empty the content of the scalar reference, before writing to it.
• "+>" or "w+" — Cloberring, and read and write.
• ">>" or "a" — Append mode. This will allow for appending data to the underlying scalar reference, but not read from it.
• "+>>" "a+" — Append and read mode. This allows to append data and read from it.
• "r" — Read-only
• "w" — Write-only (truncate)
• "a" — Append mode
• "r+", "w+", "a+" — Read/write variants

The mode will automatically be normalized to include :scalar if not already present.

On failure to open, this method returns undef and sets an error accessible via $obj->error.

💅 METHODS 💅

🎀 autoflush 🎀

This is a no-op — it genuinely does not do anything. Zero. Nada. The vibes are immaculate, but the action is absent.

🎀 binmode 🎀

Another no-op. It does not do anything. It's just here, existing, serving absolutely no purpose, and honestly? Iconic.

🎀 bit 🎀

Returns the bitwise value of the mode used to open the scalar-reference io interface.

You can then use Fcntl constants O_RDONLY, O_RDWR, O_CREAT, O_WRONLY, O_APPEND to query in bitwise mode, such as:

use Fcntl;
if( $io->bit & O_RDWR )
{
    say "Can write";
}

🎀 can_read 🎀

Returns true if one can read from the scalar reference.

🎀 can_write 🎀

Returns true if one can write to the scalar reference.

🎀 clearerr 🎀

No-op alert 🚨 — this does not do anything.

🎀 close 🎀

This merely unties the scalar. In IO::Scalar, the scalar reference passed are tied so they can be used in non-object oriented way also.

This method overrides the one from IO::Scalar that would otherwise destroy our underlying Module::Generic::Scalar object. So yeah, it's protecting the goods 💅

🎀 eof 🎀

Returns true if we are positioned at the end of the string, false otherwise.

🎀 fcntl 🎀

This is used to query or set the bitwise mode. For example:

use Fcntl;
my $bits = $io->fcntl( F_GETFL, $whatever );
# Set bits. Here same as +>
$io->fcntl( F_SETFL, ( O_CREAT | O_RDWR ) );

🎀 fileno 🎀

As perl documentation for open in perlfunc says, this returns -1.

🎀 flush 🎀

This causes perl to flush any buffered data at the PerlIO API level. Any unread data in the buffer will be discarded, and any unwritten data will be written to the underlying file descriptor.

It returns "0 but true" on success, and upon error sets an Module::Generic/error in error and returns undef.

🎀 getc 🎀

Return the next character from our last position, or undef if none remains.

🎀 getline 🎀

Return the next line, or undef on end of string.

🎀 getlines 🎀

Get all the lines from the position we are in the string.

So using our example in the SYNOPSIS above:

$io->seek(0,0); # position ourself at the start of the string
my $c = $io->getc; # get the first character, which is 'M'
my @lines = $io->getlines;

This will fetch all 6 lines, except the first one will only contain:

ignonne, allons voir si la rose

i.e. without the leading M, since getc positioned us after.

So, be careful about your position in the string.

This can only be called in list context, or this will return an error.

🎀 is_append 🎀

Returns true if the bitwise mode has the O_APPEND bit enabled, false otherwise.

🎀 is_create 🎀

Returns true if the bitwise mode has the O_CREAT bit enabled, false otherwise.

🎀 is_readonly 🎀

Returns true if the bitwise mode has the O_RDONLY bit enabled, false otherwise.

🎀 is_readwrite 🎀

Returns true if the bitwise mode has the O_RDWR bit enabled, false otherwise.

🎀 is_writeonly 🎀

Returns true if the bitwise mode has the O_WRONLY bit enabled, false otherwise.

🎀 length 🎀

Returns the size of the underlying scalar reference in bytes.

🎀 line 🎀

Provided with a callback as a subroutine reference or anonymous subroutine, and this will call the callback passing it each line of the scalar.

If the callback returns undef, this will terminate the browsing of each line, unless the option auto_next is set. See below.

It takes some optional arguments as follow:

• chomp (boolean) — If true, each line will be chomp in perlfunc'ed before being passed to the callback.
• auto_next (boolean) — If true, this will ignore the return value from the callback and will move on to the next line.

🎀 object 🎀

Returns the underlying Module::Generic::Scalar object or any other scalar reference that was provided during object instantiation.

🎀 open 🎀

This takes a Module::Generic::Scalar object or any other scalar reference and a mode. See new for the list of supported modes.

This will return an error if the scalar reference provided is not appropriate or if the mode provided is unsupported.

It returns the current object this was called with. It will return an error if it is called as a class function and not using an object.

🎀 opened 🎀

Returns true if the filehandle is opened or false otherwise.

🎀 print 🎀

This prints at the last position in the string the list of data provided, just like print in perlfunc.

If you want to make sure you are at the end, do:

$io->seek(0,2);
# or better yet:
$io->seek(0,SEEK_END);

🎀 printf 🎀

Same as printf in perlfunc.

🎀 read 🎀

my $buff;
$io->read( $buff, 1024 );
# or
$io->read( $buff, 1024, $offset );

Same as read in perlfunc.

Takes a string as a buffer, a length and an optional offset in the buffer and will attempt to read from our scalar the requested length and place the result in the buffer.

It returns the number of data read at the last position, or undef if there was an error.

🎀 say 🎀

Same as say in perlfunc.

🎀 seek 🎀

$io->seek( POSITION, WHENCE );

This takes 2 arguments: an integer representing a position in the string and another integer representing the action to take.

Quoting from seek in perlfunc:

The values for WHENCE are 0 to set the new position in bytes to POSITION; 1 to set it to the current position plus POSITION; and 2 to set it to EOF plus POSITION, typically negative.

You can also use Fcntl, such as:

$io->seek( $some_pos, SEEK_SET );

🎀 size 🎀

Alias for length.

🎀 stat 🎀

This is a no-op and always returns undef or an empty list in list context.

🎀 sysread 🎀

Same as sysread in perlfunc.

🎀 sysseek 🎀

Same as sysseek in perlfunc.

🎀 syswrite 🎀

Same as syswrite in perlfunc.

🎀 tell 🎀

Same as tell in perlfunc.

Returns the current position in the string.

🎀 truncate 🎀

$io->truncate( $length );
$io->truncate( $io->tell );

Same as truncate in perlfunc.

This truncates the string to the specified length $length. It returns true if successful, and false otherwise, such as when at the end of the string.

The position in the string is left unchanged. You may want to call seek before writing to the string.

This is an improvement from truncate in IO::Handle, which would otherwise fail on a scalar reference and return "Bad file descriptor".

🎀 write 🎀

$io->write( $data );
$io->write( $data, 1024 );
$io->write( $data, 1024, $offset );

Same as write in IO::Handle.

This takes some data $data, and optionally some length of those data to take and optionally at a given $offset in $data, and will print those data at the last position in string.

This is an improvement from write in IO::Handle, which does a simple print and thus returns only true or false.

It returns the number of bytes printed, or undef if there was an error, in which cases the error message can be retrieved with error.

---

🦋 SERIALISATION 🦋

Serialisation by CBOR, Sereal and Storable::Improved (or the legacy Storable) is supported by this package. To that effect, the following subroutines are implemented: FREEZE, THAW, STORABLE_freeze and STORABLE_thaw.

---

🧚 THREAD SAFETY 🧚

This module is thread-safe as long as each thread uses its own distinct scalar reference.

If you share the same scalar reference across threads (e.g., using threads::shared), then you must coordinate access using external locking mechanisms (e.g., lock()).

No internal locking is performed by this module, by design.

---

🌈 SEE ALSO 🌈

• Module::Generic::Scalar
• PerlIO::scalar
• Module::Generic::File::IO

---

👑 AUTHOR 👑

Jacques Deguest <jack@deguest.jp>

---

💖 COPYRIGHT & LICENSE 💖

Copyright (c) 2021-2024 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.

---

💖 That's the whole vibe check, bestie — this page is from perl v5.42.2, dated 2026-02-15, for Module:...alar::IO(3). Go forth and slay your scalar I/O. 💅✨